You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2015/06/16 07:41:49 UTC
[01/45] isis git commit: ISIS-1133: breaking out reference guide and
devenv guide;
moving appendices' release notes and migration notes to other docs;
improving the documentation page.
Repository: isis
Updated Branches:
refs/heads/master 461e51b75 -> 9c5dafab0
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/reference-layout/layout-6-6-0-12.html
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-layout/layout-6-6-0-12.html b/adocs/documentation/src/main/asciidoc/user-guide/images/reference-layout/layout-6-6-0-12.html
deleted file mode 100644
index 02a8e0d..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-layout/layout-6-6-0-12.html
+++ /dev/null
@@ -1,203 +0,0 @@
-f<!DOCTYPE html>
-<html lang="en">
-<head>
- <meta charset="utf-8">
- <meta http-equiv="X-UA-Compatible" content="IE=edge">
- <meta name="viewport" content="width=device-width, initial-scale=1">
- <title>colspans={6,6,0,12}</title>
-
- <!-- Bootstrap -->
- <!--
- <link rel="stylesheet" href="//netdna.bootstrapcdn.com/bootstrap/3.1.1/css/bootstrap.min.css">
- <link rel="stylesheet" href="//netdna.bootstrapcdn.com/bootstrap/3.1.1/css/bootstrap-theme.min.css">
- <script src="//netdna.bootstrapcdn.com/bootstrap/3.1.1/js/bootstrap.min.js"></script>
- -->
-
- <!-- Bootstrap -->
- <link href="css/bootstrap.min.css" rel="stylesheet">
-
- <!-- HTML5 Shim and Respond.js IE8 support of HTML5 elements and media queries -->
- <!-- WARNING: Respond.js doesn't work if you view the page via file:// -->
- <!--[if lt IE 9]>
- <script src="https://oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
- <script src="https://oss.maxcdn.com/libs/respond.js/1.4.2/respond.min.js"></script>
- <![endif]-->
- <link href="isis-layout.css" rel="stylesheet">
- <!--<link href="isis-layout-show-facets.css" rel="stylesheet">-->
-</head>
- <body>
- <div class="container">
- <h1>colspans={6,6,0,12}</h1>
- <div class="row">
- <div class="col-md-12">
- <div class="isis-header">
- <span class="isis-title">Buy bread</span>
- <div class="isis-actions">
- <div class="isis-action x-caution">
- <span>delete</span>
- </div>
- <div class="isis-action">
- <span data-isis-id="duplicate">clone</span>
- <ul class="isis-facets">
- <li>describedAs.value="Create a new todo item from this one"</li>
- </ul>
- </div>
- <div class="isis-action">
- <span>recentChanges</span>
- </div>
- <div class="isis-action">
- <span>recentChanges</span>
- </div>
- </div>
- </div>
- </div>
- </div>
- <div class="row">
- <div class="col-md-6 isis-memberGroups">
- <fieldset class="isis-memberGroup min-height-100">
- <legend>General</legend>
- <div class="isis-property">
- <span data-isis-typicallength="50">description</span>
- <ul class="isis-facets">
- <li>typicalLength.value=50</li>
- </ul>
- </div>
- <div class="isis-property">
- <span>category</span>
- <ul class="isis-facets">
- <li>disabled.reason="Use action to update both category and subcategory"</li>
- </ul>
- </div>
- <div class="isis-property">
- <span>subcategory</span>
- <ul class="isis-facets">
- <li>disabled.reason="Use action to update both category and subcategory"</li>
- </ul>
- <div class="isis-actions">
- <div class="isis-action">
- <span data-isis-id="updateCategory">update</span>
- </div>
- <div class="isis-action">
- <span>analyseCategory</span>
- </div>
- </div>
- </div>
- <div class="isis-property">
- <span class="isis-hidden">ownedBy</span>
- </div>
- <div class="isis-property x-highlight">
- <span data-isis-id="complete">done</span>
- <div class="isis-actions">
- <div class="isis-action">
- <span data-isis-id="completed">done</span>
- <ul class="isis-facets">
- <li>describedAs.value="Mark this todo item as having been completed"</li>
- </ul>
- </div>
- <div class="isis-action">
- <span>scheduleExplicitly</span>
- </div>
- <div class="isis-action">
- <span>scheduleImplicitly</span>
- </div>
- <div class="isis-action">
- <span data-isis-id="notYetCompleted">not done</span>
- </div>
- </div>
- </div>
- </fieldset>
- <fieldset class="isis-memberGroup min-height-100">
- <legend>Misc</legend>
- <div class="isis-property">
- <span data-isis-id="versionSequence">version</span>
- <ul class="isis-facets">
- <li>disabled</li>
- <li>hidden.where=STANDALONE_TABLES</li>
- </ul>
- </div>
- </fieldset>
- </div>
- <div class="col-md-6 isis-memberGroups">
- <fieldset class="isis-memberGroup">
- <legend>Priority</legend>
- <div class="isis-property">
- <span>relativePriority</span>
- <div class="isis-actions">
- <div class="isis-action">
- <span>previous</span>
- </div>
- <div class="isis-action">
- <span>next</span>
- </div>
- </div>
- </div>
- <div class="isis-property x-key">
- <span>dueBy</span>
- </div>
- </fieldset>
- <fieldset class="isis-memberGroup">
- <legend>Other</legend>
- <div class="isis-property">
- <span>cost</span>
- <div class="isis-actions">
- <div class="isis-action">
- <span data-isis-id="updateCost">update</span>
- </div>
- </div>
- </div>
- <div class="isis-property">
- <span>notes</span>
- <ul class="isis-facets">
- <li>multiLine.numberOfLines=5</li>
- <li>hidden.where=ALL_TABLES</li>
- </ul>
- </div>
- <div class="isis-property">
- <span>attachment</span>
- <ul class="isis-facets">
- <li>hidden.where=ALL_TABLES</li>
- </ul>
- </div>
- </fieldset>
- </div>
- </div>
- <div class="row">
- <div class="col-md-12">
- <fieldset class="isis-collection min-height-100">
- <legend>dependencies</legend>
- <div class="isis-actions">
- <div class="isis-action">
- <span>add</span>
- </div>
- <div class="isis-action x-caution">
- <span>remove</span>
- </div>
- </div>
- <ul class="isis-facets">
- <li>disabled</li>
- <li>paged.value=5</li>
- <li>render.value=EAGERLY</li>
- </ul>
- </fieldset>
- <fieldset class="isis-collection min-height-200">
- <legend>similarTo</legend>
- <ul class="isis-facets">
- <li>disabled</li>
- <li>paged.value=3</li>
- <li>render.value=LAZILY</li>
- </ul>
- </fieldset>
- </div>
- </div>
- </div>
-
- <!-- jQuery (necessary for Bootstrap's JavaScript plugins) -->
- <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.0/jquery.min.js"></script>
- <!-- Include all compiled plugins (below), or include individual files as needed -->
- <script src="js/bootstrap.min.js"></script>
- <script>
- $(document).ready(function () {
- });
- </script>
- </body>
-</html>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/reference-methods/prefixes/choices/dependent.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-methods/prefixes/choices/dependent.png b/adocs/documentation/src/main/asciidoc/user-guide/images/reference-methods/prefixes/choices/dependent.png
deleted file mode 100644
index e0ad239..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-methods/prefixes/choices/dependent.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/reference-methods/reserved/cssClass/strikethrough.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-methods/reserved/cssClass/strikethrough.png b/adocs/documentation/src/main/asciidoc/user-guide/images/reference-methods/reserved/cssClass/strikethrough.png
deleted file mode 100644
index 6945267..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-methods/reserved/cssClass/strikethrough.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/reference-methods/reserved/iconName/differing.pdn
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-methods/reserved/iconName/differing.pdn b/adocs/documentation/src/main/asciidoc/user-guide/images/reference-methods/reserved/iconName/differing.pdn
deleted file mode 100644
index 70b317b..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-methods/reserved/iconName/differing.pdn and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/reference-methods/reserved/iconName/differing.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-methods/reserved/iconName/differing.png b/adocs/documentation/src/main/asciidoc/user-guide/images/reference-methods/reserved/iconName/differing.png
deleted file mode 100644
index 57b0013..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-methods/reserved/iconName/differing.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/reference-methods/reserved/iconName/png-files.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-methods/reserved/iconName/png-files.png b/adocs/documentation/src/main/asciidoc/user-guide/images/reference-methods/reserved/iconName/png-files.png
deleted file mode 100644
index 7f826c5..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-methods/reserved/iconName/png-files.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/reference-services-spi/ContentNegotiationService/accept-json.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-services-spi/ContentNegotiationService/accept-json.png b/adocs/documentation/src/main/asciidoc/user-guide/images/reference-services-spi/ContentNegotiationService/accept-json.png
deleted file mode 100644
index 84778e9..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-services-spi/ContentNegotiationService/accept-json.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/reference-services-spi/ContentNegotiationService/accept-xml.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-services-spi/ContentNegotiationService/accept-xml.png b/adocs/documentation/src/main/asciidoc/user-guide/images/reference-services-spi/ContentNegotiationService/accept-xml.png
deleted file mode 100644
index cfd2ef1..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-services-spi/ContentNegotiationService/accept-xml.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/reference-services-spi/ContentNegotiationService/facade-choices.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-services-spi/ContentNegotiationService/facade-choices.png b/adocs/documentation/src/main/asciidoc/user-guide/images/reference-services-spi/ContentNegotiationService/facade-choices.png
deleted file mode 100644
index c6d5814..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-services-spi/ContentNegotiationService/facade-choices.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/reference-services-spi/ContentNegotiationService/facade-choices.pptx
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-services-spi/ContentNegotiationService/facade-choices.pptx b/adocs/documentation/src/main/asciidoc/user-guide/images/reference-services-spi/ContentNegotiationService/facade-choices.pptx
deleted file mode 100644
index ddeec7d..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-services-spi/ContentNegotiationService/facade-choices.pptx and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/reference-services-spi/EventSerializer/action-invocation-published-to-stderr.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-services-spi/EventSerializer/action-invocation-published-to-stderr.png b/adocs/documentation/src/main/asciidoc/user-guide/images/reference-services-spi/EventSerializer/action-invocation-published-to-stderr.png
deleted file mode 100644
index b0b3ca8..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-services-spi/EventSerializer/action-invocation-published-to-stderr.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/reference-services-spi/EventSerializer/changed-object-published-to-stderr.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-services-spi/EventSerializer/changed-object-published-to-stderr.png b/adocs/documentation/src/main/asciidoc/user-guide/images/reference-services-spi/EventSerializer/changed-object-published-to-stderr.png
deleted file mode 100644
index f894d8d..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-services-spi/EventSerializer/changed-object-published-to-stderr.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/reference-services-spi/PublishingService/yuml.me-23db58a4.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-services-spi/PublishingService/yuml.me-23db58a4.png b/adocs/documentation/src/main/asciidoc/user-guide/images/reference-services-spi/PublishingService/yuml.me-23db58a4.png
deleted file mode 100644
index 60ee3cb..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-services-spi/PublishingService/yuml.me-23db58a4.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/reference-services-spi/RepresentationService/service-collaborations.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-services-spi/RepresentationService/service-collaborations.png b/adocs/documentation/src/main/asciidoc/user-guide/images/reference-services-spi/RepresentationService/service-collaborations.png
deleted file mode 100644
index 995b089..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-services-spi/RepresentationService/service-collaborations.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/reference-services-spi/RepresentationService/service-collaborations.pptx
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-services-spi/RepresentationService/service-collaborations.pptx b/adocs/documentation/src/main/asciidoc/user-guide/images/reference-services-spi/RepresentationService/service-collaborations.pptx
deleted file mode 100644
index bbdb734..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-services-spi/RepresentationService/service-collaborations.pptx and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/reference-services-spi/UserProfileService/todoapp.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-services-spi/UserProfileService/todoapp.png b/adocs/documentation/src/main/asciidoc/user-guide/images/reference-services-spi/UserProfileService/todoapp.png
deleted file mode 100644
index 7867d37..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-services-spi/UserProfileService/todoapp.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/runtime/configuring-datanucleus/disabling-persistence-by-reachability/party-agreementrole-agreement.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/runtime/configuring-datanucleus/disabling-persistence-by-reachability/party-agreementrole-agreement.png b/adocs/documentation/src/main/asciidoc/user-guide/images/runtime/configuring-datanucleus/disabling-persistence-by-reachability/party-agreementrole-agreement.png
deleted file mode 100644
index 67744c9..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/runtime/configuring-datanucleus/disabling-persistence-by-reachability/party-agreementrole-agreement.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/security/security-apis-impl/configure-isis-to-use-bypass.PNG
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/security/security-apis-impl/configure-isis-to-use-bypass.PNG b/adocs/documentation/src/main/asciidoc/user-guide/images/security/security-apis-impl/configure-isis-to-use-bypass.PNG
deleted file mode 100644
index 387594b..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/security/security-apis-impl/configure-isis-to-use-bypass.PNG and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/security/security-apis-impl/configure-isis-to-use-shiro.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/security/security-apis-impl/configure-isis-to-use-shiro.png b/adocs/documentation/src/main/asciidoc/user-guide/images/security/security-apis-impl/configure-isis-to-use-shiro.png
deleted file mode 100644
index 891d373..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/security/security-apis-impl/configure-isis-to-use-shiro.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/security/security-apis-impl/configure-shiro-to-use-custom-jdbc-realm.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/security/security-apis-impl/configure-shiro-to-use-custom-jdbc-realm.png b/adocs/documentation/src/main/asciidoc/user-guide/images/security/security-apis-impl/configure-shiro-to-use-custom-jdbc-realm.png
deleted file mode 100644
index d64751a..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/security/security-apis-impl/configure-shiro-to-use-custom-jdbc-realm.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/security/security-apis-impl/configure-shiro-to-use-ini-realm.PNG
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/security/security-apis-impl/configure-shiro-to-use-ini-realm.PNG b/adocs/documentation/src/main/asciidoc/user-guide/images/security/security-apis-impl/configure-shiro-to-use-ini-realm.PNG
deleted file mode 100644
index 5576701..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/security/security-apis-impl/configure-shiro-to-use-ini-realm.PNG and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/security/security-apis-impl/configure-shiro-to-use-isis-ldap-realm.PNG
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/security/security-apis-impl/configure-shiro-to-use-isis-ldap-realm.PNG b/adocs/documentation/src/main/asciidoc/user-guide/images/security/security-apis-impl/configure-shiro-to-use-isis-ldap-realm.PNG
deleted file mode 100644
index 2a52910..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/security/security-apis-impl/configure-shiro-to-use-isis-ldap-realm.PNG and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/security/security-apis-impl/configure-shiro-to-use-isisaddons-security-module-realm-with-delegate-realm.PNG
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/security/security-apis-impl/configure-shiro-to-use-isisaddons-security-module-realm-with-delegate-realm.PNG b/adocs/documentation/src/main/asciidoc/user-guide/images/security/security-apis-impl/configure-shiro-to-use-isisaddons-security-module-realm-with-delegate-realm.PNG
deleted file mode 100644
index 14af8c0..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/security/security-apis-impl/configure-shiro-to-use-isisaddons-security-module-realm-with-delegate-realm.PNG and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/security/security-apis-impl/configure-shiro-to-use-isisaddons-security-module-realm.PNG
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/security/security-apis-impl/configure-shiro-to-use-isisaddons-security-module-realm.PNG b/adocs/documentation/src/main/asciidoc/user-guide/images/security/security-apis-impl/configure-shiro-to-use-isisaddons-security-module-realm.PNG
deleted file mode 100644
index 59780f4..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/security/security-apis-impl/configure-shiro-to-use-isisaddons-security-module-realm.PNG and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/security/security-apis-impl/security-apis-impl.pptx
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/security/security-apis-impl/security-apis-impl.pptx b/adocs/documentation/src/main/asciidoc/user-guide/images/security/security-apis-impl/security-apis-impl.pptx
deleted file mode 100644
index a86b62e..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/security/security-apis-impl/security-apis-impl.pptx and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/testing/fixture-scripts/composite.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/testing/fixture-scripts/composite.png b/adocs/documentation/src/main/asciidoc/user-guide/images/testing/fixture-scripts/composite.png
deleted file mode 100644
index fd2b397..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/testing/fixture-scripts/composite.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/testing/fixture-scripts/flat-1.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/testing/fixture-scripts/flat-1.png b/adocs/documentation/src/main/asciidoc/user-guide/images/testing/fixture-scripts/flat-1.png
deleted file mode 100644
index c712aa0..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/testing/fixture-scripts/flat-1.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/testing/fixture-scripts/flat-2.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/testing/fixture-scripts/flat-2.png b/adocs/documentation/src/main/asciidoc/user-guide/images/testing/fixture-scripts/flat-2.png
deleted file mode 100644
index f3d3a0b..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/testing/fixture-scripts/flat-2.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/testing/fixture-scripts/organizing-fixture-scripts.pptx
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/testing/fixture-scripts/organizing-fixture-scripts.pptx b/adocs/documentation/src/main/asciidoc/user-guide/images/testing/fixture-scripts/organizing-fixture-scripts.pptx
deleted file mode 100644
index 268a738..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/testing/fixture-scripts/organizing-fixture-scripts.pptx and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/testing/fixture-scripts/prompt-specifying-number.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/testing/fixture-scripts/prompt-specifying-number.png b/adocs/documentation/src/main/asciidoc/user-guide/images/testing/fixture-scripts/prompt-specifying-number.png
deleted file mode 100644
index e9b4ba2..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/testing/fixture-scripts/prompt-specifying-number.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/testing/fixture-scripts/prompt.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/testing/fixture-scripts/prompt.png b/adocs/documentation/src/main/asciidoc/user-guide/images/testing/fixture-scripts/prompt.png
deleted file mode 100644
index 6c22c49..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/testing/fixture-scripts/prompt.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/testing/fixture-scripts/prototyping-menu.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/testing/fixture-scripts/prototyping-menu.png b/adocs/documentation/src/main/asciidoc/user-guide/images/testing/fixture-scripts/prototyping-menu.png
deleted file mode 100644
index ed85463..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/testing/fixture-scripts/prototyping-menu.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/testing/fixture-scripts/result-list-specifying-number.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/testing/fixture-scripts/result-list-specifying-number.png b/adocs/documentation/src/main/asciidoc/user-guide/images/testing/fixture-scripts/result-list-specifying-number.png
deleted file mode 100644
index 2ac7e88..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/testing/fixture-scripts/result-list-specifying-number.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/testing/fixture-scripts/result-list.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/testing/fixture-scripts/result-list.png b/adocs/documentation/src/main/asciidoc/user-guide/images/testing/fixture-scripts/result-list.png
deleted file mode 100644
index abe4a0e..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/testing/fixture-scripts/result-list.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/testing/integ-tests.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/testing/integ-tests.png b/adocs/documentation/src/main/asciidoc/user-guide/images/testing/integ-tests.png
deleted file mode 100644
index 7c47d7e..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/testing/integ-tests.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/testing/integ-tests.pptx
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/testing/integ-tests.pptx b/adocs/documentation/src/main/asciidoc/user-guide/images/testing/integ-tests.pptx
deleted file mode 100644
index df192b8..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/testing/integ-tests.pptx and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/testing/wrapper-factory.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/testing/wrapper-factory.png b/adocs/documentation/src/main/asciidoc/user-guide/images/testing/wrapper-factory.png
deleted file mode 100644
index ee68cd5..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/testing/wrapper-factory.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/010-01-login-page.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/010-01-login-page.png b/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/010-01-login-page.png
deleted file mode 100644
index 068c3a8..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/010-01-login-page.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/010-02-home-page.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/010-02-home-page.png b/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/010-02-home-page.png
deleted file mode 100644
index 59c2726..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/010-02-home-page.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/010-03-prototyping-menu.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/010-03-prototyping-menu.png b/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/010-03-prototyping-menu.png
deleted file mode 100644
index ed85463..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/010-03-prototyping-menu.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/010-04-simpleobjects.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/010-04-simpleobjects.png b/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/010-04-simpleobjects.png
deleted file mode 100644
index 324083d..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/010-04-simpleobjects.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/010-05-simpleobject-list.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/010-05-simpleobject-list.png b/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/010-05-simpleobject-list.png
deleted file mode 100644
index 79bfffa..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/010-05-simpleobject-list.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/020-01-idea-configuration.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/020-01-idea-configuration.png b/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/020-01-idea-configuration.png
deleted file mode 100644
index 1ee8280..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/020-01-idea-configuration.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/020-02-idea-configuration.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/020-02-idea-configuration.png b/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/020-02-idea-configuration.png
deleted file mode 100644
index 99be18b..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/020-02-idea-configuration.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/030-01-idea-configuration-updated.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/030-01-idea-configuration-updated.png b/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/030-01-idea-configuration-updated.png
deleted file mode 100644
index c836f14..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/030-01-idea-configuration-updated.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/030-02-updated-app.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/030-02-updated-app.png b/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/030-02-updated-app.png
deleted file mode 100644
index c438315..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/030-02-updated-app.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/040-01-idea-configuration-updated.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/040-01-idea-configuration-updated.png b/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/040-01-idea-configuration-updated.png
deleted file mode 100644
index acddc93..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/040-01-idea-configuration-updated.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/050-01-list-all.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/050-01-list-all.png b/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/050-01-list-all.png
deleted file mode 100644
index 1c87cca..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/050-01-list-all.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/050-02-view-pet.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/050-02-view-pet.png b/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/050-02-view-pet.png
deleted file mode 100644
index 77824ce..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/050-02-view-pet.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/060-01-owners-menu.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/060-01-owners-menu.png b/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/060-01-owners-menu.png
deleted file mode 100644
index 642f9dc..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/060-01-owners-menu.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/060-02-owners-list.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/060-02-owners-list.png b/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/060-02-owners-list.png
deleted file mode 100644
index db0ec25..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/060-02-owners-list.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/060-03-pets-list.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/060-03-pets-list.png b/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/060-03-pets-list.png
deleted file mode 100644
index f2b9230..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/060-03-pets-list.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/060-04-pet-owner-autoComplete.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/060-04-pet-owner-autoComplete.png b/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/060-04-pet-owner-autoComplete.png
deleted file mode 100644
index d301b59..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/060-04-pet-owner-autoComplete.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/domain-model.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/domain-model.png b/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/domain-model.png
deleted file mode 100644
index 268e998..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/tutorials/pet-clinic/domain-model.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/about-page/about-page.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/about-page/about-page.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/about-page/about-page.png
deleted file mode 100644
index ae5dfc8..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/about-page/about-page.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/application-menu/dividers.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/application-menu/dividers.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/application-menu/dividers.png
deleted file mode 100644
index dcb415d..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/application-menu/dividers.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/application-menu/layout-menus.pdn
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/application-menu/layout-menus.pdn b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/application-menu/layout-menus.pdn
deleted file mode 100644
index 01453f7..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/application-menu/layout-menus.pdn and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/application-menu/layout-menus.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/application-menu/layout-menus.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/application-menu/layout-menus.png
deleted file mode 100644
index 0bc73d1..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/application-menu/layout-menus.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/application-menu/tertiary.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/application-menu/tertiary.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/application-menu/tertiary.png
deleted file mode 100644
index f2d2281..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/application-menu/tertiary.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/bookmarked-pages/panel-940.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/bookmarked-pages/panel-940.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/bookmarked-pages/panel-940.png
deleted file mode 100644
index c572707..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/bookmarked-pages/panel-940.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/bookmarked-pages/panel-estatio-940.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/bookmarked-pages/panel-estatio-940.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/bookmarked-pages/panel-estatio-940.png
deleted file mode 100644
index 2fad852..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/bookmarked-pages/panel-estatio-940.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/bookmarked-pages/panel-estatio.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/bookmarked-pages/panel-estatio.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/bookmarked-pages/panel-estatio.png
deleted file mode 100644
index 0fa0cfa..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/bookmarked-pages/panel-estatio.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/bookmarked-pages/panel.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/bookmarked-pages/panel.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/bookmarked-pages/panel.png
deleted file mode 100644
index b0d85f7..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/bookmarked-pages/panel.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/brand-logo/brand-logo-signin.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/brand-logo/brand-logo-signin.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/brand-logo/brand-logo-signin.png
deleted file mode 100644
index 92a022d..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/brand-logo/brand-logo-signin.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/brand-logo/brand-logo.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/brand-logo/brand-logo.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/brand-logo/brand-logo.png
deleted file mode 100644
index 7ab8ab3..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/brand-logo/brand-logo.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/copy-link/010-copy-link-button-940.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/copy-link/010-copy-link-button-940.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/copy-link/010-copy-link-button-940.png
deleted file mode 100644
index bf70a84..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/copy-link/010-copy-link-button-940.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/copy-link/010-copy-link-button.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/copy-link/010-copy-link-button.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/copy-link/010-copy-link-button.png
deleted file mode 100644
index ef64d29..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/copy-link/010-copy-link-button.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/copy-link/020-copy-link-dialog-940.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/copy-link/020-copy-link-dialog-940.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/copy-link/020-copy-link-dialog-940.png
deleted file mode 100644
index 84d050a..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/copy-link/020-copy-link-dialog-940.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/copy-link/020-copy-link-dialog.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/copy-link/020-copy-link-dialog.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/copy-link/020-copy-link-dialog.png
deleted file mode 100644
index 6be3190..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/copy-link/020-copy-link-dialog.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/copy-link/030-hints-940.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/copy-link/030-hints-940.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/copy-link/030-hints-940.png
deleted file mode 100644
index 3a4f690..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/copy-link/030-hints-940.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/copy-link/030-hints.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/copy-link/030-hints.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/copy-link/030-hints.png
deleted file mode 100644
index 5010132..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/copy-link/030-hints.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/copy-link/040-copy-link-with-hints-940.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/copy-link/040-copy-link-with-hints-940.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/copy-link/040-copy-link-with-hints-940.png
deleted file mode 100644
index 29ccf3b..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/copy-link/040-copy-link-with-hints-940.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/copy-link/040-copy-link-with-hints.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/copy-link/040-copy-link-with-hints.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/copy-link/040-copy-link-with-hints.png
deleted file mode 100644
index da9674f..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/copy-link/040-copy-link-with-hints.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/copy-link/050-title-url-940.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/copy-link/050-title-url-940.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/copy-link/050-title-url-940.png
deleted file mode 100644
index 955e6b2..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/copy-link/050-title-url-940.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/copy-link/050-title-url.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/copy-link/050-title-url.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/copy-link/050-title-url.png
deleted file mode 100644
index 7fbf6d5..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/copy-link/050-title-url.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/embedded-view/no-footer.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/embedded-view/no-footer.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/embedded-view/no-footer.png
deleted file mode 100644
index 48d3a39..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/embedded-view/no-footer.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/embedded-view/no-header-no-footer.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/embedded-view/no-header-no-footer.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/embedded-view/no-header-no-footer.png
deleted file mode 100644
index 4e238f6..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/embedded-view/no-header-no-footer.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/embedded-view/no-header.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/embedded-view/no-header.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/embedded-view/no-header.png
deleted file mode 100644
index 22e245b..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/embedded-view/no-header.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/embedded-view/regular.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/embedded-view/regular.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/embedded-view/regular.png
deleted file mode 100644
index 926fb7d..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/embedded-view/regular.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/010-attachment-field-940.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/010-attachment-field-940.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/010-attachment-field-940.png
deleted file mode 100644
index 96cbb31..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/010-attachment-field-940.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/010-attachment-field.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/010-attachment-field.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/010-attachment-field.png
deleted file mode 100644
index 013f6e2..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/010-attachment-field.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/020-edit-choose-file-940.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/020-edit-choose-file-940.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/020-edit-choose-file-940.png
deleted file mode 100644
index 7f90bea..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/020-edit-choose-file-940.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/020-edit-choose-file.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/020-edit-choose-file.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/020-edit-choose-file.png
deleted file mode 100644
index a7e3dc4..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/020-edit-choose-file.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/030-choose-file-using-browser-520.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/030-choose-file-using-browser-520.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/030-choose-file-using-browser-520.png
deleted file mode 100644
index 6a32d1b..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/030-choose-file-using-browser-520.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/030-choose-file-using-browser.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/030-choose-file-using-browser.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/030-choose-file-using-browser.png
deleted file mode 100644
index 700c325..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/030-choose-file-using-browser.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/040-edit-chosen-file-indicated-940.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/040-edit-chosen-file-indicated-940.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/040-edit-chosen-file-indicated-940.png
deleted file mode 100644
index d6bc924..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/040-edit-chosen-file-indicated-940.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/040-edit-chosen-file-indicated.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/040-edit-chosen-file-indicated.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/040-edit-chosen-file-indicated.png
deleted file mode 100644
index 60ea5b3..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/040-edit-chosen-file-indicated.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/050-ok-if-image-then-rendered-940.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/050-ok-if-image-then-rendered-940.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/050-ok-if-image-then-rendered-940.png
deleted file mode 100644
index 302bbbc..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/050-ok-if-image-then-rendered-940.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/050-ok-if-image-then-rendered.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/050-ok-if-image-then-rendered.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/050-ok-if-image-then-rendered.png
deleted file mode 100644
index 50799b2..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/050-ok-if-image-then-rendered.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/060-download-940.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/060-download-940.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/060-download-940.png
deleted file mode 100644
index 41b4b27..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/060-download-940.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/060-download.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/060-download.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/060-download.png
deleted file mode 100644
index f726d0d..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/060-download.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/070-edit-clear-940.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/070-edit-clear-940.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/070-edit-clear-940.png
deleted file mode 100644
index 0eae54e..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/070-edit-clear-940.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/070-edit-clear.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/070-edit-clear.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/070-edit-clear.png
deleted file mode 100644
index 57c2a24..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/file-upload-download/070-edit-clear.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/layouts/estatio-Invoice.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/layouts/estatio-Invoice.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/layouts/estatio-Invoice.png
deleted file mode 100644
index be7e917..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/layouts/estatio-Invoice.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/layouts/estatio-Lease.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/layouts/estatio-Lease.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/layouts/estatio-Lease.png
deleted file mode 100644
index e80ecb2..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/layouts/estatio-Lease.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/layouts/estatio-LeaseItem.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/layouts/estatio-LeaseItem.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/layouts/estatio-LeaseItem.png
deleted file mode 100644
index 993d498..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/layouts/estatio-LeaseItem.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/layouts/todoapp-ToDoItem.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/layouts/todoapp-ToDoItem.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/layouts/todoapp-ToDoItem.png
deleted file mode 100644
index 3218651..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/layouts/todoapp-ToDoItem.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/recent-pages/recent-pages-940.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/recent-pages/recent-pages-940.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/recent-pages/recent-pages-940.png
deleted file mode 100644
index 2e55860..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/recent-pages/recent-pages-940.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/recent-pages/recent-pages.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/recent-pages/recent-pages.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/recent-pages/recent-pages.png
deleted file mode 100644
index 8be97de..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/recent-pages/recent-pages.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/suppress-password-reset/login-page-default.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/suppress-password-reset/login-page-default.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/suppress-password-reset/login-page-default.png
deleted file mode 100644
index fdf2dee..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/suppress-password-reset/login-page-default.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/suppress-password-reset/login-page-suppress-password-reset.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/suppress-password-reset/login-page-suppress-password-reset.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/suppress-password-reset/login-page-suppress-password-reset.png
deleted file mode 100644
index b557269..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/suppress-password-reset/login-page-suppress-password-reset.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/suppress-remember-me/login-page-default.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/suppress-remember-me/login-page-default.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/suppress-remember-me/login-page-default.png
deleted file mode 100644
index fdf2dee..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/suppress-remember-me/login-page-default.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/suppress-remember-me/login-page-suppress-remember-me.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/suppress-remember-me/login-page-suppress-remember-me.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/suppress-remember-me/login-page-suppress-remember-me.png
deleted file mode 100644
index fe69496..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/suppress-remember-me/login-page-suppress-remember-me.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/suppress-sign-up/login-page-default.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/suppress-sign-up/login-page-default.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/suppress-sign-up/login-page-default.png
deleted file mode 100644
index fdf2dee..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/suppress-sign-up/login-page-default.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/suppress-sign-up/login-page-suppress-sign-up.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/suppress-sign-up/login-page-suppress-sign-up.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/suppress-sign-up/login-page-suppress-sign-up.png
deleted file mode 100644
index 8ff8bc3..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/suppress-sign-up/login-page-suppress-sign-up.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/theme-chooser/example-1.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/theme-chooser/example-1.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/theme-chooser/example-1.png
deleted file mode 100644
index 4db4b18..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/theme-chooser/example-1.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/theme-chooser/example-2.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/theme-chooser/example-2.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/theme-chooser/example-2.png
deleted file mode 100644
index 435194d..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/theme-chooser/example-2.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/user-registration/login-page-default.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/user-registration/login-page-default.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/user-registration/login-page-default.png
deleted file mode 100644
index fdf2dee..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/user-registration/login-page-default.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/user-registration/sign-up-after-registration.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/user-registration/sign-up-after-registration.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/user-registration/sign-up-after-registration.png
deleted file mode 100644
index 59902f9..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/user-registration/sign-up-after-registration.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/user-registration/sign-up-email-with-verification-link.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/user-registration/sign-up-email-with-verification-link.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/user-registration/sign-up-email-with-verification-link.png
deleted file mode 100644
index 021b642..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/user-registration/sign-up-email-with-verification-link.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/user-registration/sign-up-login-page-after-sign-up.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/user-registration/sign-up-login-page-after-sign-up.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/user-registration/sign-up-login-page-after-sign-up.png
deleted file mode 100644
index 3402bf6..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/user-registration/sign-up-login-page-after-sign-up.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/user-registration/sign-up-page.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/user-registration/sign-up-page.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/user-registration/sign-up-page.png
deleted file mode 100644
index 8e3bdaa..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/user-registration/sign-up-page.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/user-registration/sign-up-registration-page.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/user-registration/sign-up-registration-page.png b/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/user-registration/sign-up-registration-page.png
deleted file mode 100644
index 189965a..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/wicket-viewer/user-registration/sign-up-registration-page.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/resources/core-concepts/Pawson-Naked-Objects-thesis.pdf
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/resources/core-concepts/Pawson-Naked-Objects-thesis.pdf b/adocs/documentation/src/main/asciidoc/user-guide/resources/core-concepts/Pawson-Naked-Objects-thesis.pdf
deleted file mode 100644
index aca07e4..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/resources/core-concepts/Pawson-Naked-Objects-thesis.pdf and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/ug.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/ug.adoc b/adocs/documentation/src/main/asciidoc/user-guide/ug.adoc
deleted file mode 100644
index 618b3ce..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/ug.adoc
+++ /dev/null
@@ -1,35 +0,0 @@
-[[ug]]
-= User Guide
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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:
-
-
-include::_ug_core-concepts.adoc[leveloffset=+1]
-//include::_ug_getting-started.adoc[leveloffset=+1]
-//include::_ug_tutorials.adoc[leveloffset=+1]
-
-//include::_ug_how-tos.adoc[leveloffset=+1]
-//include::_ug_more-advanced.adoc[leveloffset=+1]
-
-//include::_ug_reference-annotations.adoc[leveloffset=+1]
-//include::_ug_reference-methods.adoc[leveloffset=+1]
-//include::_ug_reference-services-api.adoc[leveloffset=+1]
-//include::_ug_reference-services-spi.adoc[leveloffset=+1]
-//include::_ug_reference-classes.adoc[leveloffset=+1]
-//include::_ug_reference-object-layout.adoc[leveloffset=+1]
-
-//include::_ug_wicket-viewer.adoc[leveloffset=+1]
-//include::_ug_restfulobjects-viewer.adoc[leveloffset=+1]
-//include::_ug_security.adoc[leveloffset=+1]
-//include::_ug_runtime.adoc[leveloffset=+1]
-
-//include::_ug_isis-maven-plugin.adoc[leveloffset=+1]
-//include::_ug_deployment.adoc[leveloffset=+1]
-//include::_ug_testing.adoc[leveloffset=+1]
-//include::_ug_headless-access.adoc[leveloffset=+1]
-//include::_ug_extending.adoc[leveloffset=+1]
-//include::_ug_troubleshooting.adoc[leveloffset=+1]
-
-include::_ug_appendices.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/pom.xml
----------------------------------------------------------------------
diff --git a/adocs/pom.xml b/adocs/pom.xml
index c2b242d..59e6d01 100644
--- a/adocs/pom.xml
+++ b/adocs/pom.xml
@@ -119,9 +119,11 @@
<!-- The gem-maven-plugin appends the scope (e.g., provided) to the gemPath defined in the plugin configuration -->
<gemPath>${project.build.directory}/gems-provided</gemPath>
+ <!--
<requires>
<require>asciidoctor-diagram</require>
</requires>
+ -->
<sourceHighlighter>coderay</sourceHighlighter>
<backend>html5</backend>
[20/45] isis git commit: ISIS-1133: breaking out reference guide and
devenv guide;
moving appendices' release notes and migration notes to other docs;
improving the documentation page.
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_restfulobjects-viewer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_restfulobjects-viewer.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_restfulobjects-viewer.adoc
deleted file mode 100644
index 5cbb79b..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_restfulobjects-viewer.adoc
+++ /dev/null
@@ -1,51 +0,0 @@
-[[_ug_extending_restfulobjects-viewer]]
-= Restful Objects 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:_ug_restfulobjects-viewer[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 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, 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:_ug_restfulobjects-viewer[RestfulObjects viewer] to provide a simplified output, as described xref:_ug_restfulobjects-viewer_configuration-properties_simplified-object-representation[here]. +
-+
-If you simply want to suppress certain elements, as described xref:_ug_restfulobjects-viewer_configuration-properties_suppressing-elements[here].
-
-* `RepresentationService` +
-+
-The xref:_ug_reference-services-spi_manpage-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:_ug_reference-services-spi_manpage-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:_ug_reference-services-spi_manpage-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:_ug_restfulobjects-viewer[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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_wicket-viewer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_wicket-viewer.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_wicket-viewer.adoc
deleted file mode 100644
index 10e431e..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_wicket-viewer.adoc
+++ /dev/null
@@ -1,26 +0,0 @@
-[[_ug_extending_wicket-viewer]]
-= 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/
-
-
-The Wicket viewer allows you to customize the GUI in several (progressively more sophisticated) ways:
-
-* by xref:_ug_wicket-viewer_customisation_tweaking-css-classes[tweaking the UI using CSS]
-* by xref:_ug_wicket-viewer_customisation_custom-javascript[tweaking the UI using Javascript]
-* by writing a xref:_ug_extending_wicket-viewer_custom-bootstrap-theme[custom bootstrap theme]
-* by xref:_ug_extending_wicket-viewer_replacing-page-elements[replacing elements of the page] using the `ComponentFactory` interface
-* by implementing xref:_ug_extending_wicket-viewer_custom-pages[replacement page implementations] for the standard page types
-
-The first two of these options are discussed in the <<Wicket Viewer>> chapter. This chapter describes the remaining "heavier-weight/more powerful" options.
-
-
-include::_ug_extending_wicket-viewer_custom-bootstrap-theme.adoc[leveloffset=+1]
-
-include::_ug_extending_wicket-viewer_replacing-page-elements.adoc[leveloffset=+1]
-
-include::_ug_extending_wicket-viewer_custom-pages.adoc[leveloffset=+1]
-
-include::_ug_extending_wicket-viewer_isis-addons-extensions.adoc[leveloffset=+1]
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_wicket-viewer_custom-bootstrap-theme.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_wicket-viewer_custom-bootstrap-theme.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_wicket-viewer_custom-bootstrap-theme.adoc
deleted file mode 100644
index 10def91..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_wicket-viewer_custom-bootstrap-theme.adoc
+++ /dev/null
@@ -1,34 +0,0 @@
-[[_ug_extending_wicket-viewer_custom-bootstrap-theme]]
-= Custom Bootstrap theme
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 Isis Wicket viewer uses http://getbootstrap.com/[Bootstrap] styles and components (courtesy of the https://github.com/l0rdn1kk0n/wicket-bootstrap[Wicket Bootstrap] integration).
-
-By default the viewer uses the default bootstrap theme. It is possible to configure the Wicket viewer to allow the user to xref:_ug_wicket-viewer_configuration-properties_showing-theme-chooser[select other themes] provided by http://bootswatch.com[bootswatch.com], and if required one of these can be xref:_ug_wicket-viewer_customisation_default-theme[set as the default].
-
-However, you may instead want to write your own custom theme, for example to fit your company's look-n-feel/interface guidelines. This is done by implementing https://github.com/l0rdn1kk0n/wicket-bootstrap[Wicket Bootstrap]’s `de.agilecoders.wicket.core.settings.ITheme` class. This defines:
-
-* the name of the theme
-* the resources it needs (the CSS and optional JS and/or fonts), and
-* optional urls to load them from a Content Delivery Network (CDN).
-
-To make use of the custom `ITheme` the application should register it by adding the following snippet in
-(your application's subclass of) `IsisWicketApplication`:
-
-[source,java]
-----
-public void init() {
- ...
- IBootstrapSettings settings = new BootstrapSettings();
- ThemeProvider themeProvider = new SingleThemeProvider(new MyTheme());
- settings.setThemeProvider(themeProvider);
- Bootstrap.install(getClass(), settings);
-}
-----
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_wicket-viewer_custom-pages.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_wicket-viewer_custom-pages.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_wicket-viewer_custom-pages.adoc
deleted file mode 100644
index c26296c..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_wicket-viewer_custom-pages.adoc
+++ /dev/null
@@ -1,92 +0,0 @@
-[[_ug_extending_wicket-viewer_custom-pages]]
-= Custom pages
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 the vast majority of cases customization should be sufficient by xref:_ug_extending_wicket-viewer_replacing-page-elements[replacing elements of a page]. However, it is also possible to define an entirely new page for a given page type.
-
-Isis defines eight page types (see the `org.apache.isis.viewer.wicket.model.models.PageType` enum):
-
-.PageType enum
-[cols="1,4", options="header"]
-|===
-| Page type
-| Renders
-
-| SIGN_IN
-| The initial sign-in (aka login) page
-
-| SIGN_UP
-| The sign-up page (if xref:_ug_reference-services-spi_manpage-UserRegistrationService[user registration] is enabled).
-
-| SIGN_UP_VERIFY
-| The sign-up verification page (if xref:_ug_reference-services-spi_manpage-UserRegistrationService[user registration] is enabled; as accessed by link from verification email)
-
-| PASSWORD_RESET
-| The password reset page (if enabled).
-
-| HOME
-| The home page, displaying either the welcome message or dashboard
-
-| ABOUT
-| The about page, accessible from link top-right
-
-| ENTITY
-| Renders a single entity or view model
-
-| STANDALONE_COLLECTION
-| Page rendered after invoking an action that returns a collection of entites
-
-| VALUE
-| After invoking an action that returns a value type (though not URLs or Blob/Clobs, as these are handled appropriately automatically).
-
-| VOID_RETURN
-| After invoking an action that is `void`
-
-| ACTION_PROMPT
-| (No longer used).
-
-|===
-
-
-The `PageClassList` interface declares which class (subclass of `org.apache.wicket.Page` is used to render for each of these types. For example, Isis' `WicketSignInPage` renders the signin page.
-
-To specify a different page class, create a custom subclass of `PageClassList`:
-
-[source,java]
-----
-@Singleton
-public class MyPageClassList extends PageClassListDefault {
- protected Class<? extends Page> getSignInPageClass() {
- return MySignInPage.class;
- }
-}
-----
-
-
-You then need to register your custom `PageClassList`. This is done by adjusting the Guice bindings (part of Isis' bootstrapping) in your custom subclass of `IsisWicketApplication`:
-
-[source,java]
-----
-public class MyAppApplication extends IsisWicketApplication {
- @Override
- protected Module newIsisWicketModule() {
- final Module isisDefaults = super.newIsisWicketModule();
- final Module myAppOverrides = new AbstractModule() {
- @Override
- protected void configure() {
- ...
- bind(PageClassList.class).to(MyPageClassList.class);
- ...
- }
- };
- return Modules.override(isisDefaults).with(myAppOverrides);
- }
-}
-----
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_wicket-viewer_isis-addons-extensions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_wicket-viewer_isis-addons-extensions.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_wicket-viewer_isis-addons-extensions.adoc
deleted file mode 100644
index 46ab3cc..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_wicket-viewer_isis-addons-extensions.adoc
+++ /dev/null
@@ -1,17 +0,0 @@
-[[_ug_extending_wicket-viewer_isis-addons-extensions]]
-= Isis Addons Extensions
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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
-
-[WARNING]
-====
-Note that Isis addons, while maintained by Isis committers, are not part of the ASF.
-====
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_wicket-viewer_replacing-page-elements.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_wicket-viewer_replacing-page-elements.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_wicket-viewer_replacing-page-elements.adoc
deleted file mode 100644
index 80f410f..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_wicket-viewer_replacing-page-elements.adoc
+++ /dev/null
@@ -1,167 +0,0 @@
-[[_ug_extending_wicket-viewer_replacing-page-elements]]
-= Replacing page elements
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-Replacing elements of the page is the most powerful general-purpose way to customize the look-n-feel of the viewer. Examples at the (non-ASF) http://www.isisaddons.org[Isis Add-ons] include the http://github.com/isisaddons/isis-wicket-gmap3[gmap3] extension, the http://github.com/isisaddons/isis-wicket-fullcalendar2[calendar] extension, the http://github.com/isisaddons/isis-wicket-excel[excel download] and the http://github.com/isisaddons/isis-wicket-wickedcharts[wickedcharts] charting integration.
-
-The pages generated by Isis' Wicket viewer are built up of numerous elements, from fine-grained widgets for property/parameter fields, to much larger components that take responsibility for rendering an entire entity entity, or a collection of entities. Under the covers these are all implementations of the the Apache Wicket `Component` API. The larger components delegate to the smaller, of course.
-
-
-
-
-== How the viewer selects components
-
-Components are created using Isis' `ComponentFactory` interface, which are registered in turn through the `ComponentFactoryRegistrar` interface. Every component is categorizes by type (the `ComponentType` enum), and Isis uses this to determine which `ComponentFactory` to use. For example, the `ComponentType.BOOKMARKED_PAGES` is used to locate the `ComponentFactory` that will build the bookmarked pages panel.
-
-Each factory is also handed a model (an implementation of `org.apache.wicket.IModel`) appropriate to its `ComponentType`; this holds the data to be rendered. For example, `ComponentType.BOOKMARKED_PAGES` is given a `BookmarkedPagesModel`, while `ComponentType.SCALAR_NAME_AND_VALUE` factories are provided a model of type of type `ScalarModel` .
-
-In some cases there are several factories for a given `ComponentType`; this is most notably the case for `ComponentType.SCALAR_NAME_AND_VALUE`. After doing a first pass selection of candidate factories by `ComponentType`, each factory is then asked if it `appliesTo(Model)`. This is an opportunity for the factory to check the model itself to see if the data within it is of the appropriate type.
-
-Thus, the `BooleanPanelFactory` checks that the `ScalarModel` holds a boolean, while the `JodaLocalDatePanelFactory` checks to see if it holds `org.joda.time.LocalDate`.
-
-There will typically be only one `ComponentFactory` capable of rendering a particular `ComponentType`/`ScalarModel` combination; at any rate, the framework stops as soon as one is found.
-
-[NOTE]
-====
-There is one refinement to the above algorithm where multiple component factories might be used to render an object; this is discussed in <<Additional Views of Collections>>, below.
-====
-
-
-
-
-
-== How to replace a component
-
-This design (the http://en.wikipedia.org/wiki/Chain-of-responsibility_pattern[chain of responsibility] design pattern) makes it quite straightforward to change the rendering of any element of the page. For example, you might switch out Isis' sliding bookmark panel and replace it with one that presents the bookmarks in some different fashion.
-
-First, you need to write a `ComponentFactory` and corresponding `Component`. The recommended approach is to start with the source of the `Component` you want to switch out. For example:
-
-[source,java]
-----
-public class MyBookmarkedPagesPanelFactory extends ComponentFactoryAbstract {
- public MyBookmarkedPagesPanelFactory() {
- super(ComponentType.BOOKMARKED_PAGES);
- }
- @Override
- public ApplicationAdvice appliesTo(final IModel<?> model) {
- return appliesIf(model instanceof BookmarkedPagesModel);
- }
- @Override
- public Component createComponent(final String id, final IModel<?> model) {
- final BookmarkedPagesModel bookmarkedPagesModel = (BookmarkedPagesModel) model;
- return new MyBookmarkedPagesPanel(id, bookmarkedPagesModel);
- }
-}
-----
-
-and
-
-[source,java]
-----
-public class MyBookmarkedPagesPanel
- extends PanelAbstract<BookmarkedPagesModel> {
- ...
-}
-----
-
-Here `PanelAbstract` ultimately inherits from `org.apache.wicket.Component`.
-Your new `Component` uses the information in the provided model (eg `BookmarkedPagesModel`) to know what to render.
-
-Next, you will require a custom implementation of the `ComponentFactoryRegistrar` that registers your custom `ComponentFactory` as a replacement:
-
-[source,java]
-----
-@Singleton
-public class MyComponentFactoryRegistrar extends ComponentFactoryRegistrarDefault {
- @Override
- public void addComponentFactories(ComponentFactoryList componentFactories) {
- super.addComponentFactories(componentFactories);
- componentFactories.add(new MyBookmarkedPagesPanelFactory());
- }
-}
-----
-
-This will result in the new component being used instead of (that is, discovered prior to) Isis' default implementation.
-
-[WARNING]
-====
-Previously we suggested using "replace" rather than "add"; however this has unclear semantics for some component types; see https://issues.apache.org/jira/browse/ISIS-996[ISIS-996].
-====
-
-
-Finally (as for other customizations), you need to adjust the Guice bindings in your custom subclass of `IsisWicketApplication`:
-
-[source,java]
-----
-public class MyAppApplication extends IsisWicketApplication {
- @Override
- protected Module newIsisWicketModule() {
- final Module isisDefaults = super.newIsisWicketModule();
- final Module myAppOverrides = new AbstractModule() {
- @Override
- protected void configure() {
- ...
- bind(ComponentFactoryRegistrar.class)
- .to(MyComponentFactoryRegistrar.class);
- ...
- }
- };
-
- return Modules.override(isisDefaults).with(myAppOverrides);
- }
-}
-----
-
-
-
-
-== Additional Views of Collections
-
-As explained above, in most cases Isis' Wicket viewer will search for the first `ComponentFactory` that can render an element, and use it. In the case of (either standalone or parented) collections, though, Isis will show all available views.
-
-For example, out-of-the-box Isis provides a table view, a summary view (totals/sums/averages of any data), and a collapsed view (for `@Render(LAZILY)` collections). These are selected by clicking on the toolbar by each collection.
-
-Additional views though could render the objects in the collection as a variety of ways. Indeed, some third-party implementations already exist:
-
-* https://github.com/isisaddons/isis-wicket-excel[excel integration] (collection as a downloadable excel spreadsheet)
-* https://github.com/isisaddons/isis-wicket-gmap3[google maps v3 integration] (render any objects with a location on a map)
-* https://github.com/isisaddons/isis-wicket-wickedcharts[wicked charts integration] (barchart of any data)
-* https://github.com/isisaddons/isis-wicket-fullcalendar2[full calendar integration] (render any objects with date properties on a calendar)
-
-Registering these custom views is just a matter of adding the appropriate Maven module to the classpath. Isis uses the JDK `ServiceLoader` API to automatically discover and register the `ComponentFactory` of each such component.
-
-If you want to write your own alternative component and auto-register, then include a file `META-INF/services/org.apache.isis.viewer.wicket.ui.ComponentFactory` whose contents is the fully-qualified class name of the custom `ComponentFactory` that you have written.
-
-Wicket itself has lots of components available at its http://wicketstuff.org[wicketstuff.org] companion website; you might find some of these useful for your own customizations.
-
-
-
-
-
-
-== Custom object view (eg dashboard)
-
-One further use case in particular is worth highlighting; the rendering of an entire entity. Normally entities this is done using `EntityCombinedPanelFactory`, this being the first `ComponentFactory` for the `ComponentType.ENTITY` that is registered in Isis default `ComponentFactoryRegistrarDefault`.
-
-You could, though, register your own `ComponentFactory` for entities that is targeted at a particular class of entity - some sort of object representing a dashboard, for example. It can use the `EntityModel` provided to it to determine the class of the entity, checking if it is of the appropriate type. Your custom factory should also be registered before the `EntityCombinedPanelFactory` so that it is checked prior to the default `EntityCombinedPanelFactory`:
-
-[source,java]
-----
-@Singleton
-public class MyComponentFactoryRegistrar extends ComponentFactoryRegistrarDefault {
- @Override
- public void addComponentFactories(ComponentFactoryList componentFactories) {
- componentFactories.add(new DashboardEntityFactory());
- ...
- super.addComponentFactories(componentFactories);
- ...
- }
-}
-----
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_getting-started.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_getting-started.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_getting-started.adoc
deleted file mode 100644
index de30022..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_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_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_getting-started_datanucleus-enhancer[DataNucleus enhancer]. link:http://www.datanucleus.org/[DataNucleus] is the reference implementation of the JDO (Java data objects) spec, and 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 Isis' JDO/DataNucleus objectstore.
-
-[NOTE]
-====
-The xref:_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 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 Isis committers use either IntelliJ or Eclipse; in the xref:_ug_appendices[appendices] 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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_getting-started_datanucleus-enhancer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_getting-started_datanucleus-enhancer.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_getting-started_datanucleus-enhancer.adoc
deleted file mode 100644
index fc7d02a..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_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 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-SNAPSHOT, we put all the configuration into an (always active) profile:
-
-[TIP]
-====
-The configuration described below is automatically set up by the xref:_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.0-release</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_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_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:_ug_appendices_dev-env_eclipse[here].
-====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_getting-started_simpleapp-archetype.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_getting-started_simpleapp-archetype.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_getting-started_simpleapp-archetype.adoc
deleted file mode 100644
index cc419ca..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_getting-started_simpleapp-archetype.adoc
+++ /dev/null
@@ -1,300 +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 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.8.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 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.9.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 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:_ug_wicket-viewer[Wicket viewer] and the xref:_ug_restfulobjects-viewer[Restful Objects viewer]. The archetype also configures the [JDO Objectstore](../../components/objectstores/jdo/about.html) 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 appendices for details on xref:_ug_appendices_dev-env_eclipse[setting up Eclipse] or xref:_ug_appendices_dev-env_intellij[setting up IntelliJ IDEA]. Basically, though, it amounts to running `org.apache.isis.WebServer`, and ensuring that the xref:_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:_ug_testing_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:_ug_wicket-viewer[Wicket viewer] or the xref:_ug_restfulobjects-viewer[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:_ug_security[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 [documentation](../../documentation.html) page first).
-
-If you use Eclipse or IntelliJ IDEA, do also install the [Eclipse templates](../resources/editor-templates.html); these will help you follow the 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 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.
-
-<table class="table table-striped table-bordered table-condensed">
-<tr><th>Module</th><th>Description</th></tr>
-<tr><td>myapp</td><td>The parent (aggregator) module</td></tr>
-<tr><td>myapp-dom</td><td>The domain object model, consisting of <tt>SimpleObject</tt> and <tt>SimpleObjects</tt> (repository) domain service.</td></tr>
-<tr><td>myapp-fixture</td><td>Domain object fixtures used for initializing the system when being demo'ed or for unit testing.</td></tr>
-<tr><td>myapp-integtests</td><td>End-to-end <a href="../../core/integtestsupport.html">integration tests</a>, that exercise from the UI through to the database</td></tr>
-<tr><td>myapp-webapp</td><td>Run as a webapp (from <tt>web.xml</tt>) using either the Wicket viewer or the Restful Objects viewer</td></tr>
-</table>
-
-If you run into issues, please don't hesitate to ask for help on the [users mailing list](../../support.html).
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_headless-access.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_headless-access.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_headless-access.adoc
deleted file mode 100644
index bd72c8c..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_headless-access.adoc
+++ /dev/null
@@ -1,27 +0,0 @@
-[[_ug_headless-access]]
-= Headless access
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 tackles the topic of enabling access to an Isis application directly, or at least, not through either the xref:_ug_wicket-viewer[Wicket] or xref:_ug_restfulobjects-viewer[Restful] viewers.
-
-There are several main use-cases:
-
-* enabling background execution, eg of a thread managed by Quartz scheduler and running within the webapp
-
-* integration from other systems, eg for a subscriber on a pub/sub mechanism such as Camel, pushing changes through an Isis domain model.
-
-* leveraging an Isis application within a batch process
-
-Note that the calling thread runs in the same process space as the Isis domain object model (must be physically linked to the JAR files containing the domain classes). For use cases where the calling thread runs in some other process space (eg migrating data from a legacy system), then the xref:_ug_restfulobjects-viewer[Restful Objects viewer] is usually the way to go.
-
-The API described in this chapter is reasonably low-level, allowing code to interact very directly with the Isis metamodel and runtime. Such callers should be considered trusted: they do not (by default) honour any business rules eg implicit in the Isis annotations or hide/disable/validate methods. However the <<WrapperFactory>> service could be used to enforce such business rules if required.
-
-
-
-include::_ug_headless-access_AbstractIsisSessionTemplate.adoc[leveloffset=+1]
-include::_ug_headless-access_BackgroundCommandExecution.adoc[leveloffset=+1]
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_headless-access_AbstractIsisSessionTemplate.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_headless-access_AbstractIsisSessionTemplate.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_headless-access_AbstractIsisSessionTemplate.adoc
deleted file mode 100644
index 7402a2e..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_headless-access_AbstractIsisSessionTemplate.adoc
+++ /dev/null
@@ -1,40 +0,0 @@
-[[_ug_headless-access_AbstractIsisSessionTemplate]]
-= AbstractIsisSessionTemplate
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `AbstractIsisSessionTemplate` class (whose name is inspired by the Spring framework's naming convention for similar classes that query http://docs.spring.io/spring/docs/2.5.x/reference/jdbc.html#jdbc-JdbcTemplate[JDBC], http://docs.spring.io/spring/docs/2.5.x/reference/jms.html#jms-jmstemplate[JMS], http://docs.spring.io/spring/docs/2.5.x/reference/orm.html#orm-jpa-template[JPA] etc.) provides the mechanism to open up a 'session' within the Isis framework, in order to resolve and interact with entities.
-
-The class itself is intended to be subclassed:
-
-[source,java]
-----
-public abstract class AbstractIsisSessionTemplate {
-
- public void execute(final AuthenticationSession authSession, final Object context) { ... } //<1>
- protected abstract void doExecute(Object context); // <2>
-
- protected ObjectAdapter adapterFor(final Object targetObject) { ... }
- protected ObjectAdapter adapterFor(final RootOid rootOid) { ... }
-
- protected PersistenceSession getPersistenceSession() { ... }
- protected IsisTransactionManager getTransactionManager() { ... }
- protected AdapterManager getAdapterManager() { ... }
-}
-----
-<1> `execute(...)` sets up the `IsisSession` and delegates to ...
-<2> `doExecute(...)`, the mandatory hook method for subclasses to implement.
-The passed object represents passes a context from the caller (eg the scheduler, cron job, JMS etc) that instantiated and executed the class.
-
-The `protected` methods expose key internal APIs within Isis, for the subclass to use as necessary.
-
-
-[TIP]
-====
-One notable feature of `AbstractIsisSessionTemplate` is that it will automatically inject any domain services into itself. Thus, it is relatively easy for the subclass to "reach into" the domain, through injected repository services.
-====
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_headless-access_BackgroundCommandExecution.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_headless-access_BackgroundCommandExecution.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_headless-access_BackgroundCommandExecution.adoc
deleted file mode 100644
index 333afc6..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_headless-access_BackgroundCommandExecution.adoc
+++ /dev/null
@@ -1,45 +0,0 @@
-[[_ug_headless-access_BackgroundCommandExecution]]
-= BackgroundCommandExecution
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `BackgroundCommandExecution` class (a subclass of <<AbstractIsisSessionTemplate>>) is intended to simplify the execution of background ``Command``s persisted by way of the <<CommandService>> and the <<BackgroundCommandService>>.
-
-Its signature is:
-
-[source,java]
-----
-public abstract class BackgroundCommandExecution extends AbstractIsisSessionTemplate {
- protected void doExecute(Object context) { ... }
- protected abstract List<? extends Command> findBackgroundCommandsToExecute(); // <1>
-}
-----
-<1> `findBackgroundCommandsToExecute()` is a mandatory hook method for subclasses to implement.
-
-This allows for different implementations of the `CommandService` and `BackgroundCommandService` to persist to wherever.
-
-The diagram below (http://yuml.me/edit/363b335f[yuml.me/363b335f]) shows the dependencies between these various classes:
-
-.Inheritance Hierarchy for `BackgroundCommandExecution`
-image::{_imagesdir}headless-access/BackgroundCommandExecution.png[width="400px"]
-
-
-
-
-
-
-
-== Background Execution
-
-The `BackgroundCommandExecutionFromBackgroundCommandServiceJdo` is a concrete subclass of `BackgroundCommandExecution` (see the xref:_ug_reference-services-api_manpage-BackgroundService[`BackgroundCommandService`]), the intended use being for the class to be instantiated regularly (eg every 10 seconds) by a scheduler such as http://quartz-scheduler.org[Quartz]) to poll for ``Command``s to be executed, and then execute them.
-
-This implementation queries for ``Command``s persisted by the link:http://www.isisaddons.org/isis-module-command[Isis addons Command Module]'s implementations of xref:_ug_reference-services-spi_manpage-CommandService[`CommandService`] and xref:_ug_reference-services-spi_manpage-BackgroundCommandService[`BackgroundCommandService`] using the `BackgroundCommandServiceJdoRepository`.
-
-The diagram below (link:http://yuml.me/edit/25343da1[yuml.me/25343da1]) shows the inheritance hierarchy for this class:
-
-.Inheritance Hierarchy for `BackgroundCommandExecutionFromBackgroundCommandServiceJdo`
-image::{_imagesdir}headless-access/BackgroundCommandExecutionFromBackgroundCommandServiceJdo.png[width="500px"]
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos.adoc
deleted file mode 100644
index d03210e..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos.adoc
+++ /dev/null
@@ -1,20 +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 instructions on how to go about actually developing 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]
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_business-rules.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_business-rules.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_business-rules.adoc
deleted file mode 100644
index f7f7614..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_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/
-
-IMPORTANT: TODO
-
-
-
-== Visibility ("see it")
-
-IMPORTANT: TODO - xref:_ug_reference-methods_prefixes_manpage-hide[`hide...()`]
-
-### Hide a Property
-
-### Hide a Collection
-
-### Hide an Action
-
-### Hide a Contributed Property, Collection or Action
-
-### All Members Hidden
-
-
-
-
-== Usability ("use it")
-
-IMPORTANT: TODO - xref:_ug_reference-methods_prefixes_manpage-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")
-
-IMPORTANT: TODO - xref:_ug_reference-methods_prefixes_manpage-validate[`validate...()`], xref:_ug_reference-methods_prefixes_manpage-validateAddTo[`validateAddTo...()`], xref:_ug_reference-methods_prefixes_manpage-validateRemoveFrom[`validateRemoveFrom...()`] and xref:_ug_reference-methods_reserved_manpage-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
-
-IMPORTANT: TODO - using xref:_ug_reference-annotations_manpage-Action_mustSatisfy[`@Action#mustSatisfy()`], xref:_ug_reference-annotations_manpage-Property_mustSatisfy[`@Property#mustSatisfy()`]
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_class-structure.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_class-structure.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_class-structure.adoc
deleted file mode 100644
index 52d013b..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_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, view models 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 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 Isis programming model.
-
-[TIP]
-====
-In fact, Isis programming model is extensible; you can teach 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 Isis programming model xref:_ug_extending_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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_class-structure_action-parameters.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_class-structure_action-parameters.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_class-structure_action-parameters.adoc
deleted file mode 100644
index d19d7fe..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_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/
-
-
-IMPORTANT: TODO
-
-
-
-== ``String``s (Length)
-
-IMPORTANT: TODO
-
-
-== ``BigDecimal``s (Precision)
-
-IMPORTANT: TODO
-
-
-== Optional
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_class-structure_actions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_class-structure_actions.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_class-structure_actions.adoc
deleted file mode 100644
index 4b2364e..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_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/
-
-
-
-IMPORTANT: TODO
-
-
-[NOTE]
-====
-While Isis support actions whose parameters' types are scalar (values such as `String`, `int`, or references such as `Customer`), the framework (currently) does not support parameter types that are collections or maps.
-
-The workaround is to mark the collection as `@Programmatic`, as described in xref:_ug_how-tos_class-structure_ignoring-methods[Ignoring Methods]. This ensures that the collection is ignored by Isis.
-====
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_class-structure_class-definition.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_class-structure_class-definition.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_class-structure_class-definition.adoc
deleted file mode 100644
index ba6b28c..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_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/
-
-
-
-IMPORTANT: WIP
-
-
-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:_ug_more-advanced_decoupling[decoupling].
-====
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_class-structure_collections.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_class-structure_collections.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_class-structure_collections.adoc
deleted file mode 100644
index f562760..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_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/
-
-
-IMPORTANT: WIP
-
-
-[NOTE]
-====
-While Isis support collections of references, the framework (currently) does not support collections of values. That is, it isn't possible to define a collection of type `Set<String>`.
-
-Or, actually, you can, because that is a valid mapping supported by JDO/DataNucleus . However, Isis has no default visualization.
-
-One workaround is to mark the collection as xref:_ug_reference-annotations_manpage-Progammatic[`@Progammatic`]. This ensures that the collection is ignored by Isis.
-
-Another workaround is to wrap each value in a view model, as explained in this xref:_ug_more-advanced_tips-n-tricks_simulating-collections-of-values[tip].
-====
-
-
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_class-structure_ignoring-methods.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_class-structure_ignoring-methods.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_class-structure_ignoring-methods.adoc
deleted file mode 100644
index 2efe78e..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_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/
-
-
-
-IMPORTANT: WIP
-
-
-Sometimes you want to define a `public` method on a domain object that is not intended to be rendered in Isis' UI.
-
-To exclude such methods, use the xref:_ug_reference-annotations_manpage-Programmatic[`@Programmatic`] annotation.
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_class-structure_inject-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_class-structure_inject-services.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_class-structure_inject-services.adoc
deleted file mode 100644
index 175499d..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_class-structure_inject-services.adoc
+++ /dev/null
@@ -1,83 +0,0 @@
-[[how-to-inject-services-into-a-domain-entity-or-other-service]]
-= 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 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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_class-structure_properties-vs-parameters.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_class-structure_properties-vs-parameters.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_class-structure_properties-vs-parameters.adoc
deleted file mode 100644
index 91cec84..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_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/
-
-
-
-IMPORTANT: WIP
-
-
-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 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 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`
-|===
-
-
[08/45] isis git commit: ISIS-1133: breaking out reference guide and
devenv guide;
moving appendices' release notes and migration notes to other docs;
improving the documentation page.
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi.adoc
deleted file mode 100644
index 79284df..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi.adoc
+++ /dev/null
@@ -1,270 +0,0 @@
-[[_ug_reference-services-spi]]
-= Reference: Domain Services SPI
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 includes an extensive number of domain services for your domain objects to use; these are listed in xref:_ug_reference-services-api[Reference: Domain Services (API)] chapter.
-
-There are other domain services that constitute not an API but an SPI; if present they are used by Isis itself rather than by your domain objects. A good example of this is the xref:_ug_reference-services-spi_manpage-AuditingService[`AuditingService`] service; if an implementation is present then Isis will call that service in order to record audit log entries. If no implementation is available then Isis will carry on regardless.
-
-Some domain services can be considered both API and SPI; a good example is the xref:_ug_reference-services-api_manpage-EmailService[`EmailService`] that is of direct use for domain objects wishing to send out emails, but is also used by the framework to support the xref:_ug_wicket-viewer_features_user-registration[user registration] functionality supported by the xref:_ug_wicket-viewer[Wicket viewer]. The same is true of the xref:_ug_reference-services-api_manpage-EventBusService[`EventBusService`]; this can be used by domain objects to broadcast arbitrary events, but is also used by the framework to automatically emit events for xref:_ug_reference-annotations_manpage-Action_domainEvent[`@Action#domainEvent()`] etc.
-
-For these hybrid services we have categorized the service as an "API" service. This chapter therefore contains only the strictly SPI services.
-
-
-The table below lists the SPIs that are defined in the Isis applib (`o.a.i.core:isis-core-applib` module).
-
-
-.Applib SPI Services
-[cols="2,4a,1,1", options="header"]
-|===
-
-
-|SPI
-|Description
-|Implementation
-|Notes
-
-
-|xref:_ug_reference-services-spi_manpage-AuditingService[`o.a.i.applib.` +
-`services.audit` +
-`AuditingService3`]
-|Create an audit record for every changed property of every changed object within a transaction.
-|`AuditingService` +
-``o.ia.m.audit`` +
-``isis-module-audit``
-|related services:
-`AuditingService-` +
-`Contributions`,
-`AuditingService-` +
-`Repository`
-
-|xref:_ug_reference-services-spi_manpage-BackgroundCommandService[`o.a.i.applib.` +
-`services.background` +
-`BackgroundCommandService`]
-|Persisted a memento of an action invocation such that it can be executed asynchronously ("in the background") eg by a scheduler.
-|`BackgroundCommandServiceJdo` +
-``o.ia.m.command`` +
-``isis-module-command``
-|related services:
-`BackgroundCommandService-` +
-`JdoContributions`,
-`BackgroundCommandService-` +
-`JdoRepository`
-
-
-|xref:_ug_reference-services-spi_manpage-ClassDiscoveryService[`o.a.i.applib.` +
-`services.classdiscovery` +
-`ClassDiscoveryService`]
-|Mechanism to locate (from the classpath) classes with a specific annotation (eg xref:_ug_reference-annotations_manpage-DomainService[`@DomainService`])
-
-Subtypes of a given type (eg xref:_ug_reference-classes_super_manpage-FixtureScript[`FixtureScript`]).
-|`ClassDiscoveryService-` +
-`UsingReflections` +
-``o.a.i.core`` +
-``isis-core-applib``
-|requires `org.reflections:reflections` as Maven dependency
-
-
-|xref:_ug_reference-services-spi_manpage-CommandService[`o.a.i.applib.` +
-`services.command.spi` +
-`CommandService`]
-|Service to act as a factory and repository (create and save) of command instances, ie representations of an action invocation. Used for command/auditing and background services.
-|`CommandServiceJdo` +
-``o.ia.m.command`` +
-``isis-module-command``
-|related services: +
-`CommandService-` ++
-`JdoContributions`,
-`CommandService-` ++
-`JdoRepository`
-
-
-|xref:_ug_reference-services-spi_manpage-EmailNotificationService[`o.a.i.applib.` +
-`services.userreg` +
-`EmailNotificationService`]
-|Notify a user during xref:_ug_reference-services-spi_manpage-UserRegistrationService[self-registration] of users.
-|`EmailNotificationService-` +
-`Default` +
-``o.a.i.core`` +
-``isis-core-runtime``
-|depends on: +
-a configured `EmailService`
-
-|xref:_ug_reference-services-spi_manpage-EventSerializer[`o.a.i.applib.` +
-`services.publish` +
-`EventSerializer`]
-|Creates a representation of either an action invocation or a changed object being published through the xref:_ug_reference-services-spi_manpage-PublishingService[`PublishingService`].
-|`RestfulObjects-` +
-`SpecEventSerializer` +
-``o.ia.m.publishing`` +
-``isis-module-publishing``
-|
-
-
-|xref:_ug_reference-services-spi_manpage-ExceptionRecognizer[`o.a.i.applib.` +
-`services.exceprecog` +
-`ExceptionRecognizer2`]
-|Convert certain exceptions (eg foreign or unique key violation in the database) into a format that can be rendered to the end-user.
-|`ExceptionRecognizer-` +
-`CompositeFor-` +
-`JdoObjectStore` +
-``o.a.i.core`` +
-``isis-core-applib``
-|Extensible using composite pattern if required
-
-
-|xref:_ug_reference-services-spi_manpage-LocaleProvider[`o.a.i.applib.` +
-`services.i18n` +
-`LocaleProvider`]
-|Request-scoped service to return the locale of the current user, in support of i18n (ie so that the app's UI, messages and exceptions can be translated to the required locale by the xref:_ug_reference-services-spi_manpage-TranslationService[`TranslationService`].
-|`LocaleProviderWicket` +
-``o.a.i.viewer`` +
-``isis-viewer-wicket-impl``
-|
-
-|xref:_ug_reference-services-spi_manpage-PublishingService[`o.a.i.applib.` +
-`services.publish` +
-`PublishingService`]
-|Publish any action invocations and changed objects, typically for interchange with an external system in a different bounded context.
-|`PublishingService` +
-``o.ia.m.publishing`` +
-``isis-module-publishing``
-|related services:
-`PublishingService-` ++
-`Contributions`,
-`PublishingService-` ++
-`Repository`. +
-depends on: +
-`EventSerializer`
-
-
-|xref:_ug_reference-services-spi_manpage-TranslationService[`o.a.i.applib.` +
-`services.i18n` +
-`TranslationService`]
-|Translate an app's UI, messages and exceptions for the current user (as per the locale provided by xref:_ug_reference-services-spi_manpage-LocaleProvider[`LocalProvider`].
-|`TranslationServicePo` +
-``o.a.i.core`` +
-``isis-core-runtime``
-|related services: `TranslationServicePoMenu` +
-depends on: +
-`TranslationsResolver`, `LocaleProvider`
-
-
-|xref:_ug_reference-services-spi_manpage-TranslationsResolver[`o.a.i.applib.` +
-`services.i18n` +
-`TranslationsResolver`]
-|Obtain translations for a particuar phrase and locale, in support of i18n (ie so that the app's UI, messages and exceptions can be translated to the required locale by the xref:_ug_reference-services-spi_manpage-TranslationService[`TranslationService`]
-|`TranslationsResolverWicket` +
-``o.a.i.viewer`` +
-``isis-viewer-wicket-impl``
-|
-
-
-|xref:_ug_reference-services-spi_manpage-UserProfileService[`o.a.i.applib.` +
-`services.userprof` +
-`UserProfileService`]
-|Obtain an alternative (usually enriched/customized) name for the current user, to render in the UI.
-|
-|
-
-|xref:_ug_reference-services-spi_manpage-UserRegistrationService[`o.a.i.applib.` +
-`services.userreg` +
-`UserRegistrationService`]
-|Create a new user account with the configured security mechanism.
-|`SecurityModule-` +
-`AppUserRegistrationService` +
-``o.ia.m.security`` +
-``isis-module-security``
-|depends (implicitly) on: +
-a configured `EmailService`
-
-
-|===
-
-
-Key:
-
-* `o.a.i` is an abbreviation for `org.apache.isis`
-* `o.ia.m` is an abbreviation for `org.isisaddons.module`
-
-
-Where an implementation is available (on the classpath) then it is always registered automatically (that is, they are all (with one exception) annotated with xref:_ug_reference-annotations_manpage-DomainService[`@DomainService`]. The one exception is xref:_ug_reference-services-spi_manpage-ExceptionRecognizer[`ExceptionRecognizer`], which must be registered explicitly in `isis.properties`; this makes the service extensible (for new exceptions to be recognized).
-
-
-
-
-There are also some "internal" SPI services whose definitions depend on the internals of the framework (rather than the applib).
-
-[WARNING]
-====
-We do not guarantee that link:http://semver.org[semantic versioning] will be honoured for these APIs.
-====
-
-
-
-."Internal" SPI Services
-[cols="3,3,2,2a", options="header"]
-|===
-
-|SPI
-|Maven Module +
-Impl'n (g: a:)
-|Implementation
-|Notes
-
-
-|xref:_ug_reference-services-spi_manpage-ContentMappingService[`o.a.i.v.ro.` +
-`rendering.service.conneg.` +
-`ContentMappingService`]
-|(Attempt to) map the returned data into the representation required by the client's HTTP `Accept` header.
-|
-|No default implementation.
-
-|xref:_ug_reference-services-spi_manpage-ContentNegotiationService[`o.a.i.v.ro.` +
-`rendering.service.conneg.` +
-`ContentNegotiationService`]
-|Encodes the algorithm that delegates to any registered xref:_ug_reference-services-spi_manpage-ContentMappingService[`ContentMappingService`]s.
-|`ContentNegotiationService-` +
-`XRoDomainType` +
-``o.a.i.core`` +
-`isis-core-viewer-restfulobjects-rendering`
-|
-
-
-|xref:_ug_reference-services-spi_manpage-RepresentationService[`o.a.i.v.ro.` +
-`rendering.service.` +
-`RepresentationService`]
-|Generates the representations, delegating to any registered xref:_ug_reference-services-spi_manpage-ContentNegotiationService[`ContentNegotiationService`]s.
-|`RepresentationService-` +
-`ForRestfulObjects` +
-``o.a.i.core`` +
-`isis-core-viewer-restfulobjects-rendering`
-|
-
-
-|===
-
-Key:
-
-* `o.a.i.v.ro` is an abbreviation for `org.apache.isis.viewer.restfulobjects`
-
-
-include::_ug_reference-services-spi_manpage-AuditingService.adoc[leveloffset=+1]
-include::_ug_reference-services-spi_manpage-BackgroundCommandService.adoc[leveloffset=+1]
-include::_ug_reference-services-spi_manpage-ClassDiscoveryService.adoc[leveloffset=+1]
-include::_ug_reference-services-spi_manpage-CommandService.adoc[leveloffset=+1]
-include::_ug_reference-services-spi_manpage-ContentMappingService.adoc[leveloffset=+1]
-include::_ug_reference-services-spi_manpage-ContentNegotiationService.adoc[leveloffset=+1]
-include::_ug_reference-services-spi_manpage-EmailNotificationService.adoc[leveloffset=+1]
-include::_ug_reference-services-spi_manpage-EventSerializer.adoc[leveloffset=+1]
-include::_ug_reference-services-spi_manpage-ExceptionRecognizer.adoc[leveloffset=+1]
-include::_ug_reference-services-spi_manpage-LocaleProvider.adoc[leveloffset=+1]
-include::_ug_reference-services-spi_manpage-PublishingService.adoc[leveloffset=+1]
-include::_ug_reference-services-spi_manpage-RepresentationService.adoc[leveloffset=+1]
-include::_ug_reference-services-spi_manpage-TranslationService.adoc[leveloffset=+1]
-include::_ug_reference-services-spi_manpage-TranslationsResolver.adoc[leveloffset=+1]
-include::_ug_reference-services-spi_manpage-UserProfileService.adoc[leveloffset=+1]
-include::_ug_reference-services-spi_manpage-UserRegistrationService.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-AuditingService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-AuditingService.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-AuditingService.adoc
deleted file mode 100644
index d281e30..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-AuditingService.adoc
+++ /dev/null
@@ -1,84 +0,0 @@
-[[_ug_reference-services-spi_manpage-AuditingService]]
-= `AuditingService3`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `AuditingService3` auditing service provides a simple mechanism to capture changes to data. It is called for each property that has changed on any domain object, as a set of pre- and post-values.
-
-[NOTE]
-====
-In case you are wondering what happened to `AuditingService` and `AuditingService2`, these were earlier versions of the SPI that have since been deprecated and removed.
-====
-
-
-== SPI
-
-The SPI for the service is:
-
-[source,java]
-----
-public interface AuditingService3 {
-
- @Programmatic
- public void audit(
- final UUID transactionId, String targetClassName, final Bookmark target,
- String memberIdentifier, final String propertyName,
- final String preValue, final String postValue,
- final String user, final java.sql.Timestamp timestamp);
- }
-----
-
-The framework will call this for each and every domain object property that is modified within a transaction.
-
-
-
-== Implementation
-
-The most full-featured available implementation is the (non-ASF) http://github.com/isisaddons/isis-module-audit[Isis addons' Audit module]. This creates an audit records for each changed property (ie every time that `AuditingService3#audit(...)` is called. The implementation is `org.isisaddons.module.audit.dom.AuditingService`.
-
-The module also provides:
-
-* `AuditingServiceMenu` service which provides actions to search for ``AuditEntry``s, underneath an 'Activity' menu on the secondary menu bar.
-
-* `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:_ug_reference-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.
-
-
-
-If you just want to debug (writing to stderr), you can instead configure `o.a.i.applib.services.audit.AuditingService3$Stderr`
-
-
-
-== Usage
-
-The typical way to indicate that an object should be audited is to annotate it with the xref:_ug_reference-annotations_manpage-DomainObject_auditing[`@DomainObject#auditing()`] annotation.
-
-
-
-
-== Registering the Services
-
-Assuming that the `configuration-and-annotation` services installer is configured:
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then adding the (non-ASF) http://github.com/isisaddons/isis-module-audit[Isis addons' audit] module to the classpath will automatically register the `AuditingService`, `AuditingServiceMenu`, `AuditingServiceRepository` and `AuditingServiceContributions` services. If menu items or contributions are not required in the UI, these can be suppressed either using security or by implementing a xref:_ug_more-advanced_decoupling_vetoing-visibility[vetoing subscriber].
-
-
-
-== Related Services
-
-The auditing service works very well with the xref:_ug_reference-services-spi_manpage-CommandService[`CommandService`]. The `CommandService` captures the _cause_ of an interaction (an action was invoked, a property was edited), while the `AuditingService3` captures the _effect_ of that interaction in terms of changed state.
-
-You may also want to configure the xref:_ug_reference-services-spi_manpage-PublishingService[`PublishingService`].
-
-All three of these services collaborate implicitly by way of the xref:_ug_reference-classes_mixins_manpage-HasTransactionId[`HasTransactionId`] interface.
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-BackgroundCommandService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-BackgroundCommandService.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-BackgroundCommandService.adoc
deleted file mode 100644
index 76bb0ef..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-BackgroundCommandService.adoc
+++ /dev/null
@@ -1,129 +0,0 @@
-[[_ug_reference-services-spi_manpage-BackgroundCommandService]]
-= `BackgroundCommandService`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `BackgroundCommandService` (SPI) service supports the xref:_ug_reference-services-api_manpage-BackgroundService[`BackgroundService`] (API) service, persisting action invocations as commands such that they can subsequently be invoked in the background.
-
-The `BackgroundService` is responsible for capturing a memento representing the action invocation, and then hands off to the xref:_ug_reference-services-spi_manpage-BackgroundCommandService[`BackgroundCommandService`] `BackgroundCommandService` to actually persist it.
-
-The persisting of commands is only half the story; there needs to be a separate process to read the commands and execute them. The abstract xref:_ug_reference-services-api_manpage-BackgroundService_BackgroundCommandExecution[`BackgroundCommandExecution`] provides a mechanism to execute such commands. This can be considered an API, albeit "internal" because the implementation relies on internals of the framework.
-
-
-
-== SPI
-
-The SPI of the `BackgroundCommandService` is:
-
-[source,java]
-----
-public interface BackgroundCommandService {
- void schedule(
- ActionInvocationMemento aim, // <1>
- Command parentCommand, // <2>
- String targetClassName,
- String targetActionName,
- String targetArgs);
-
-}
-----
-<1> is a wrapper around a xref:_ug_reference-services-api_manpage-MementoService[`MementoService`]'s `Memento`, capturing the details of the action invocation to be retained (eg persisted to a database) so that it can be executed at a later time
-<2> reference to the parent `Command` requesting the action be performed as a background command. This allows information such as the initiating user to be obtained.
-
-The API of `ActionInvocationMemento` in turn is:
-
-[source,java]
-----
-public class ActionInvocationMemento {
- public String getActionId() { ... }
- public String getTargetClassName() { ... }
- public String getTargetActionName() { ... }
- public Bookmark getTarget() { ... }
- public int getNumArgs() { ... }
- public Class<?> getArgType(int num) throws ClassNotFoundException { ... }
- public <T> T getArg(int num, Class<T> type) { ... }
-
- public String asMementoString() { ... } // <1>
-}
-----
-<1> lets the `BackgroundCommandService` implementation convert the action invocation into a simple string.
-
-
-
-== "Internal" SPI
-
-The `BackgroundCommandExecution` (in isis-core) is an abstract template class for xref:_ug_headless-access_AbstractIsisSessionTemplate[headless access], that defines an abstract hook method to obtain background `Command`s to be executed:
-
-[source,java]
-----
-public abstract class BackgroundCommandExecution
- extends AbstractIsisSessionTemplate {
- ...
- protected abstract List<? extends Command> findBackgroundCommandsToExecute();
- ...
-}
-----
-
-The developer is required to implement this hook method in a subclass.
-
-
-
-
-== Implementation
-
-The (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module provides an implementation (`org.isisaddons.module.command.dom.BackgroundCommandServiceJdo`) that persists ``Command``s using the JDO/DataNucleus object store. It further provides a number of supporting services:
-
-* `org.isisaddons.module.command.dom.BackgroundCommandServiceJdoRepository` is a repository to search for persisted background ``Command``s
-
-* `org.isisaddons.module.command.dom.BackgroundCommandServiceJdoContributions` contributes actions for searching for persisted child and sibling ``Command``s.
-
-The module also provides a concrete subclass of `BackgroundCommandExecution` that knows how to query for persisted (background) `Command`s such that they can be executed by a scheduler.
-
-[TIP]
-====
-Details of setting up the Quartz scheduler to actually execute these persisted commands can be found on the xref:_ug_reference-services-api_manpage-BackgroundService[`BackgroundService`] page.
-====
-
-
-
-
-== Usage
-
-Background commands can be created either declaratively or imperatively.
-
-The declarative approach involves annotating an action using xref:_ug_reference-annotations_manpage-Action_command[`@Action#command()`] with `@Action#commandExecuteIn=CommandExecuteIn.BACKGROUND`.
-
-The imperative approach involves explicitly calling the xref:_ug_reference-services-api_manpage-BackgroundService[`BackgroundService`] from within domain object's action.
-
-
-
-
-== Registering the Services
-
-Assuming that the `configuration-and-annotation` services installer is configured:
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then adding the (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module to the classpath will automatically register the `BackgroundCommandServiceJdo`, `BackgroundCommandJdoRepository` and `BackgroundCommandServiceJdoContributions` services. If contributions are not required in the UI, these can be suppressed either using security or by implementing a xref:_ug_more-advanced_decoupling_vetoing-visibility[vetoing subscriber].
-
-Note that this module also provides service implementations of the xref:_ug_reference-services-spi_manpage-CommandService[`CommandService`].
-
-
-
-
-== Related Services
-
-As discussed above, this service supports the xref:_ug_reference-services-api_manpage-BackgroundService[`BackgroundService`] , persisting `Command`s such that they can be executed in the background.
-
-There is also a tie-up with the xref:_ug_reference-services-api_manpage-CommandContext[`CommandContext`] and its supporting xref:_ug_reference-services-spi_manpage-CommandService[`CommandService`] domain service. The `CommandContext` service is responsible for providing a parent `Command` with which the background `Command`s can then be associated as children, while the `CommandService` is responsible for persisting those parent `Command`s (analogous to the way in which the `BackgroundCommandService` persists the child background `Command`s). The `BackgroundCommandService` ensures that these background `Command`s are associated with the parent "foreground" `Command`.
-
-What that means is that the implementations of `CommandService` and `BackgroundCommandService` go together, hence both implemented in the (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module.).
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-ClassDiscoveryService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-ClassDiscoveryService.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-ClassDiscoveryService.adoc
deleted file mode 100644
index e8c43fa..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-ClassDiscoveryService.adoc
+++ /dev/null
@@ -1,81 +0,0 @@
-[[_ug_reference-services-spi_manpage-ClassDiscoveryService]]
-= `ClassDiscoveryService`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `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:_ug_reference-classes_super_manpage-FixtureScripts[`FixtureScripts`] service to automatically locate any xref:_ug_reference-classes_super_manpage-FixtureScript[`FixtureScript`] implementations.
-
-
-
-== SPI
-
-The SPI defined by the service is:
-
-[source,java]
-----
-public interface ClassDiscoveryService2 {
- @Programmatic
- <T> Set<Class<? extends T>> findSubTypesOfClasses(Class<T> type, String packagePrefix);
- @Deprecated
- @Programmatic
- <T> Set<Class<? extends T>> findSubTypesOfClasses(Class<T> type); // <1>
-}
-----
-<1> no longer used
-
-
-
-== Implementation
-
-Isis provides an implementation of this service, namely `o.a.i.applib.services.classdiscovery.ClassDiscoveryServiceUsingReflections`.
-
-[NOTE]
-====
-This implementation is also used to discover domain services annotated with xref:_ug_reference-annotations_manpage-DomainService[`@DomainService`]. Currently this logic uses the implementation directly, so is not pluggable. However, the entire `ServicesInstaller`
-====
-
-
-
-== Usage
-
-The usage will vary depending upon the conventions of the design. In the case of fixture scripts, the convention is to implement scripts by subclassing xref:_ug_reference-classes_super_manpage-FixtureScript[`FixtureScript`], and to specify the package prefix in the constructor for xref:_ug_reference-classes_super_manpage-FixtureScripts[`FixtureScripts`].
-
-For example, the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] has its fixture scripts in the `todoapp.fixture` package. the `ToDoAppFixturesService` (its subclass of xref:_ug_reference-classes_super_manpage-FixtureScripts[`FixtureScripts`] is in the same package, so its constructor is:
-
-[source,java]
-----
-package todoapp.fixture;
-...
-@DomainService(nature = NatureOfService.VIEW_MENU_ONLY)
-public class ToDoAppFixturesService extends FixtureScripts {
- public ToDoAppFixturesService() {
- super(
- ToDoAppFixturesService.class.getPackage().getName(), // <1>
- MultipleExecutionStrategy.EXECUTE);
- }
- ...
-}
-----
-<1> specify the package prefix to search under for fixture scripts
-
-Other designs using this service are likely to work in a similar way, requiring some sort of scope to be specified.
-
-
-== Registering the Services
-
-Assuming that the `configuration-and-annotation` services installer is configured:
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then 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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-CommandService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-CommandService.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-CommandService.adoc
deleted file mode 100644
index 6ece1eb..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-CommandService.adoc
+++ /dev/null
@@ -1,99 +0,0 @@
-[[_ug_reference-services-spi_manpage-CommandService]]
-= `CommandService`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `CommandService` service supports the xref:_ug_reference-services-api_manpage-CommandContext[`CommandContext`] service such that `Command` objects (that reify the invocation of an action on a domain object into an object) can be persisted.
-
-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:_ug_reference-services-api_manpage-BackgroundService[`BackgroundService`]
-* if xref:_ug_reference-services-spi_manpage-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:_ug_reference-classes_mixins_manpage-HasTransactionId[`transactionId`]
-* if xref:_ug_reference-services-spi_manpage-PublishingService[publishing] is configured, they provide better traceability as the `Command` is also correlated with any published events, again through the unique xref:_ug_reference-classes_mixins_manpage-HasTransactionId[`transactionId`]
-* the associated xref:_ug_reference-annotations_manpage-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.
-
-
-
-The screencast below provides a run-through of the command (profiling) service, auditing service, publishing service. It also shows how commands can be run in the background either explicitly by scheduling through the background service or implicitly by way of a framework annotation.
-
-
-
-video::tqXUZkPB3EI[youtube,width="560px",height="315px"]
-
-[NOTE]
-====
-Note that this screencast shows an earlier version of the xref:_ug_wicket-viewer[Wicket viewer] UI (specifically, pre 1.8.0).
-====
-
-
-== SPI
-
-The `CommandService` service defines the following very simple API:
-
-[source,java]
-----
-public interface CommandService {
- @Programmatic
- Command create();
- @Programmatic
- void startTransaction(Command command, final UUID transactionId);
- @Programmatic
- void complete(Command command);
- @Programmatic
- boolean persistIfPossible(Command command);
-}
-----
-
-where `Command` is defined as defined by the xref:_ug_reference-services-api_manpage-CommandContext[`CommandContext`] service.
-
-
-== Implementation
-
-The (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module provides an implementation (`org.isisaddons.module.command.dom.CommandServiceJdo`) that persists ``Command``s using the JDO/DataNucleus object store. It further provides a number of supporting services:
-
-* `org.isisaddons.module.command.dom.CommandServiceJdoRepository` is a repository to search for persisted ``Command``s
-
-* `org.isisaddons.module.command.dom.CommandServiceJdoContributions` contributes actions for searching for persisted child and sibling ``Command``s.
-
-
-
-== Usage
-
-The typical way to indicate that an action should be reified into a `Command` is by annotating the action using xref:_ug_reference-annotations_manpage-Action_command[`@Action#command()`].
-
-
-
-
-== Registering the Services
-
-Assuming that the `configuration-and-annotation` services installer is configured:
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-
-then adding the (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module to the classpath will automatically register the `CommandServiceJdo`, `CommandJdoRepository` and `CommandServiceJdoContributions` services. If contributions are not required in the UI, these can be suppressed either using security or by implementing a xref:_ug_more-advanced_decoupling_vetoing-visibility[vetoing subscriber].
-
-Note that this module also provides service implementations of the xref:_ug_reference-services-spi_manpage-BackgroundCommandService[`BackgroundCommandService`].
-
-
-
-== Related Services
-
-As discussed above, this service supports the xref:_ug_reference-services-api_manpage-CommandContext[`CommandContext`], providing the ability for `Command` objects to be
-persisted. This is closely related to the xref:_ug_reference-services-spi_manpage-BackgroundCommandService[`BackgroundCommandService`]that allows the xref:_ug_reference-services-api_manpage-BackgroundService[`BackgroundService`] to schedule commands for background/asynchronous execution.
-
-The implementations of `CommandService` and `BackgroundCommandService` are intended to go together, so that persistent parent `Command`s can be associated with their child background `Command`s.
-
-The services provided by this module combines very well with the xref:_ug_reference-services-spi_manpage-AuditingService[`AuditingService`]. The `CommandService` captures the _cause_ of an interaction (an action was invoked, a property was edited), while the `AuditingService3` captures the _effect_ of that interaction in terms of changed state.
-
-You may also want to configure the xref:_ug_reference-services-spi_manpage-PublishingService[`PublishingService`].
-
-All three of these services collaborate implicitly by way of the xref:_ug_reference-classes_mixins_manpage-HasTransactionId[`HasTransactionId`] interface.
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-ContentMappingService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-ContentMappingService.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-ContentMappingService.adoc
deleted file mode 100644
index 1aa87f8..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-ContentMappingService.adoc
+++ /dev/null
@@ -1,106 +0,0 @@
-[[_ug_reference-services-spi_manpage-ContentMappingService]]
-= `ContentMappingService`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `ContentMappingService` supports the (default implementation of the) xref:_ug_reference-services-spi_manpage-ContentNegotiationService[`ContentNegotiationService`] allowing the xref:_ug_restfulobjects-viewer[RestfulObjects viewer] to allow domain objects to be transformed into some other format as specified by the HTTP `Accept` header.
-
-See xref:_ug_reference-services-spi_manpage-ContentNegotiationService[`ContentNegotiationService`] for further discussion.
-
-
-
-
-== SPI
-
-The SPI defined by this service is:
-
-[source,java]
-----
-public interface ContentMappingService {
- @Programmatic
- Object map(Object object, // <1>
- List<MediaType> acceptableMediaTypes, // <2>
- RepresentationType representationType); // <3>
-
-}
-
-----
-<1> typically the input is a domain object (whose structure might change over time), and the output is a DTO (whose structure is guaranteed to be preserved over time)
-<2> as per the caller's HTTP `Accept` header
-<3> the representation type required (as per the link:http://restfulobjects.org[Restful Objects spec]).
-
-
-[WARNING]
-====
-This is an "internal" SPI, meaning that it uses types that are not part of the Isis applib. We do not guarantee that link:http://semver.org[semantic versioning] will be honoured for these APIs.
-====
-
-
-== Implementations
-
-No default implementations are provided by Isis framework itself. However, the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] includes a sample implementation to convert its `ToDoItem` entity into a `ToDoItemDto` (JAXB annotated and derived from an XSD). This uses the link:http://orika-mapper.github.io/orika-docs/intro.html[Orika] mapping library.
-
-The source code is:
-
-[source,java]
-----
-@DomainService(nature = NatureOfService.DOMAIN)
-public class CustomContentMappingService implements ContentMappingService {
- private MapperFactory mapperFactory; // <1>
- @Programmatic
- @PostConstruct
- public void init() {
- mapperFactory = new DefaultMapperFactory.Builder().build();
- mapperFactory.registerClassMap(
- mapperFactory.classMap(ToDoItem.class, ToDoItemDto.class) // <2>
- .byDefault() // <3>
- .toClassMap());
- mapperFactory.registerClassMap(
- mapperFactory.classMap(Bookmark.class, OidDto.class) // <4>
- .field("identifier", "objectIdentifier") // <5>
- .byDefault() // all other fields are compatible // <6>
- .toClassMap());
- }
- @Programmatic
- @Override // <7>
- public Object map(
- final Object object,
- final List<MediaType> acceptableMediaTypes,
- final RepresentationType representationType) {
- if(object instanceof ToDoItem) {
- final Bookmark bookmark = bookmarkService.bookmarkFor(object);
- final ToDoItemDto dto =
- mapperFactory.getMapperFacade().map(object, ToDoItemDto.class); // <8>
- final OidDto oidDto =
- mapperFactory.getMapperFacade().map(bookmark, OidDto.class); // <9>
- dto.setOid(oidDto); // <10>
- return dto;
- }
- return null;
- }
-
- @javax.inject.Inject
- private BookmarkService bookmarkService;
-}
-----
-<1> registry of known mappings
-<2> how to map `ToDoItem` to `ToDoItemDto` ...
-<3> ... all properties have same name in both source and destination types
-<4> how to map `Bookmark` to `OidDto` ...
-<5> ... this property has a different name
-<6> ... all other properties have same name
-<7> the main API to implement. This implementation ignores the `acceptableMediaTypes` and `representationType`
-<8> map the domain object to the DTO
-<9> and map its oid (by way of the xref:_ug_reference-services-api_manpage-BookmarkService[`BookmarkService`]
-<10> and perform some additional manual wiring (because domain objects don't _know_ their Oids).
-
-You'll notice that the implementation doesn't actually use the `acceptableMediaTypes` and `representationType` parameters. That's because the calling `ContentNegotiationServiceXRoDomainType` will double check that the returned object is of the correct type (as defined by the `x-ro-domain-type` parameter of the HTTP `Accept` header). Since this (example) todoapp only offers a single mapping, there's therefore no need to for the mapping service to check further.
-
-
-
-== Related Services
-
-This service is a companion to the default implementation of the xref:_ug_reference-services-spi_manpage-ContentNegotiationService[`ContentNegotiationService`].
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-ContentNegotiationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-ContentNegotiationService.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-ContentNegotiationService.adoc
deleted file mode 100644
index 8ef6a2b..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-ContentNegotiationService.adoc
+++ /dev/null
@@ -1,189 +0,0 @@
-[[_ug_reference-services-spi_manpage-ContentNegotiationService]]
-= `ContentNegotiationService`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `ContentNegotiationService` is a plug-in point for the xref:_ug_restfulobjects-viewer[RestfulObjects viewer] so that it can generate representations according to HTTP `Accept` header of the request. This idea is discussed in section 34.1 of the link:http://restfulobjects.org[Restful Objects spec] v1.0.
-
-The principal motivation is to allow more flexible representations to be generated for REST clients that (perhaps through their use of a certain Javascript library, say) expect, or at least works best with, a certain style of representation.
-
-Another use case is to support "third party" REST clients over which you have no control. In this scenario you _must not_ naively expose entities through the RO viewer, because over time those entities will inevitably evolve and change their structure. If the entities were exposed directly then those REST clients will break.
-
-Instead you need to create some sort of stable facade over your domain entities, one which you will preserve even if the domain entities change. There are three ways in which you can do this:
-
-* first is to solve the problem at the domain layer by defining a regular Isis xref:_ug_more-advanced_view-models[view model]. This is then surfaced over the RO viewer. +
-+
-If the underlying entities change, then care must be taken to ensure that structure of the view model nevertheless is unchanged.
-
-* a second option is to solve the problem at the persistence layer, but defining a (SQL) view in the database and then xref:_ug_more-advanced_mapping-rdbms-views[mapping this] to a (read-only) entity. Again this is surfaced by the RO viewer. +
-+
-If the underlying tables change (as the result of a change in their corresponding domain entities) then once more the view must be refactored so that it still presents the same structure.
-
-* our third option is to solve the problem at the presentation layer, using the `ContentNegotiationService` described in this section. +
-+
-The `ContentNegotiationService` is responsible for inspecting the HTTP `Accept` header, and use this to select the correct representation to render. +
-+
-The Isis framework provides a default implementation of `ContentNegotiationService` which inspects the "x-ro-domaintype" component of the HTTP `Accept` header. If present, this implementation will delegate to the companion xref:_ug_reference-services-spi_manpage-ContentMappingService[`ContentMappingService`] service, if configured. +
-+
-A typical implementation of `ContentMappingService` will convert the domain object into some sort of DTO (data transfer object) as specified by the "x-ro-domaintype". If this DTO is annotated with JAXB or Jackson mappings, then the RO viewer (courtesy of the underlying link:http://resteasy.jboss.org/[RestEasy] framework) can serialize these directly +
-+
-What all that means is that, if the underlying entities change, we are required to update the mappings in the `ContentMappingService` to map to the same DTOs.
-
-This diagram illustrates the three options available:
-
-image::{_imagesdir}reference-services-spi/ContentNegotiationService/facade-choices.png[width="700px",link="{_imagesdir}reference-services-spi/ContentNegotiationService/facade-choices.png"]
-
-
-
-
-== SPI
-
-The SPI defined by this service is:
-
-[source,java]
-----
-public interface ContentNegotiationService {
- @Programmatic
- Response.ResponseBuilder buildResponse( // <1>
- RepresentationService.Context2 renderContext2,
- ObjectAdapter objectAdapter);
- @Programmatic
- Response.ResponseBuilder buildResponse( // <2>
- RepresentationService.Context2 renderContext2,
- ObjectAndProperty objectAndProperty);
- @Programmatic
- Response.ResponseBuilder buildResponse( // <3>
- RepresentationService.Context2 renderContext2,
- ObjectAndCollection objectAndCollection);
- @Programmatic
- Response.ResponseBuilder buildResponse( // <4>
- RepresentationService.Context2 renderContext2,
- ObjectAndAction objectAndAction);
- @Programmatic
- Response.ResponseBuilder buildResponse( // <5>
- RepresentationService.Context2 renderContext2,
- ObjectAndActionInvocation objectAndActionInvocation);
-}
-----
-<1> representation of a single object, as per section 14.4 of the RO spec, v1.0
-<2> representation of a single property of an object, as per section 16.4 of the RO spec v1.0
-<3> representation of a single collection of an object, as per section 17.5 of the RO spec v1.0
-<4> representation of a single action (prompt) of an object, as per section 18.2 of the RO spec v1.0
-<5> representation of the results of a single action invocation, as per section 19.5 of the RO spec v1.0
-
-These methods provide:
-
-* a `RepresentationService.Context2` which provides access to request-specific context (eg HTTP headers), session-specific context (eg authentication) and global context (eg configuration settings)
-
-* an object representing the information to be rendered +
-+
-eg `ObjectAdapter`, `ObjectAndProperty`, `ObjectAndCollection` etc
-
-In all cases, returning `null` will result in the regular RO spec representation being returned.
-
-
-[WARNING]
-====
-This is an "internal" SPI, meaning that it uses types that are not part of the Isis applib. We do not guarantee that link:http://semver.org[semantic versioning] will be honoured for these APIs.
-====
-
-
-
-== Implementation
-
-`ContentNegotiationServiceAbstract` (in `o.a.i.v.ro.rendering.service.conneg`) provides a no-op implementation of the SPI, along with supporting methods:
-
-[source,java]
-----
-public abstract class ContentNegotiationServiceAbstract implements ContentNegotiationService {
- ...
- protected Object objectOf(final ObjectAdapter objectAdapter) { ... }
- protected Object returnedObjectOf(ObjectAndActionInvocation objectAndActionInvocation) { ... }
-
- protected Class<?> loadClass(String cls) { ... }
-
- protected void ensureJaxbAnnotated(Class<?> domainType) { ... }
- protected void ensureDomainObjectAssignable(
- String xRoDomainType, Class<?> domainType, Object domainObject) { ... }
-}
-----
-
-As discussed in the introduction, the framework also provides a default implementation, `o.a.i.v.ro.rendering.service.conneg.ContentNegotiationServiceXRoDomainType`. This handles content negotiation for two of the possible representations, object representations and for action result representations:
-
-* For object representations it will handle requests with HTTP `Accept` headers of the form:
-** `application/json;profile=urn:org.restfulobjects:repr-types/object;x-ro-domain-type=...`
-** `application/xml;profile=urn:org.restfulobjects:repr-types/object;x-ro-domain-type=...`
-
-* for action result representations it will similarly handle requests with HTTP `Accept` headers of the form:
-** `application/json;profile=urn:org.restfulobjects:repr-types/action-result;x-ro-domain-type=...` +
-** `application/xml;profile=urn:org.restfulobjects:repr-types/action-result;x-ro-domain-type=...`
-
-
-The value of the `x-ro-domain-type` parameter corresponds to the DTO to be mapped into by the xref:_ug_reference-services-spi_manpage-ContentMappingService[`ContentMappingService`].
-
-If the DTO is annotated with JAXB, then also note that the runtime type must be annotated with the JAXB `javax.xml.bind.annotation.XmlRootElement` so that RestEasy is able to unambiguously serialize it.
-
-
-
-
-== Usage
-
-You can find an example of all these services in the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp]. This defines a `ToDoItemDto` class that is JAXB annotated (it is in fact generated from an XSD).
-
-The example app also includes an implementation of `ContentMappingService` that maps `todoapp.dom.module.todoitem.ToDoItem` entities to `todoapp.dto.module.todoitem.ToDoItemDto` classes.
-
-A REST client can therefore request a DTO representation of an entity by invoking
-
-[source]
-----
-http://localhost:8080/restful/objects/TODO/0
-----
-
-with an `Accept` header of:
-
-[source]
-----
-application/xml;profile=urn:org.restfulobjects:repr-types/object;x-ro-domain-type=todoapp.dto.module.todoitem.ToDoItemDto
-----
-
-will result in an XML serialization of that class:
-
-image::{_imagesdir}reference-services-spi/ContentNegotiationService/accept-xml.png[width="700px",link="{_imagesdir}reference-services-spi/ContentNegotiationService/accept-xml.png"]
-
-
-while similarly hitting the same URL with an `Accept` header of:
-
-[source]
-----
-application/json;profile=urn:org.restfulobjects:repr-types/object;x-ro-domain-type=todoapp.dto.module.todoitem.ToDoItemDto
-----
-
-will result in the JSON serialization of that class:
-
-image::{_imagesdir}reference-services-spi/ContentNegotiationService/accept-json.png[width="700px",link="{_imagesdir}reference-services-spi/ContentNegotiationService/accept-json.png"]
-
-
-
-
-== Registering the Services
-
-Assuming that the `configuration-and-annotation` services installer is configured:
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then Isis' default implementation of `ContentNegotiationService` service is automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
-
-
-
-
-== Related Services
-
-The default implementation of `ContentNegotiationService` delegates to xref:_ug_reference-services-spi_manpage-ContentMappingService[`ContentMappingService`] (if present) to convert domain entities into a stable form (eg DTO).
-
-The `ContentNegotiationService` is itself called by the (default implementation of) xref:_ug_reference-services-spi_manpage-RepresentationService[`RepresentationService`].
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-EmailNotificationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-EmailNotificationService.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-EmailNotificationService.adoc
deleted file mode 100644
index ec2be22..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-EmailNotificationService.adoc
+++ /dev/null
@@ -1,80 +0,0 @@
-[[_ug_reference-services-spi_manpage-EmailNotificationService]]
-= `EmailNotificationService`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `EmailNotificationService` supports the xref:_ug_wicket-viewer_features_user-registration[user registration] (self sign-up) features of the xref:_ug_wicket-viewer[Wicket viewer] whereby a user can sign-up to access an application by providing a valid email address.
-
-The Wicket viewer will check whether an implementation of this service (and also the xref:_ug_reference-services-spi_manpage-UserRegistrationService[`UserRegistrationService`]) is available, and if so will (unless configured not to) expose a sign-up page where the user enters their email address. A verification email is sent using this service; the email includes a link back to the running application. The user then completes the registration process (choosing a user name, password and so on) and the Wicket viewer creates an account for them (using the aforementioned `UserRegistrationService`).
-
-The role of this service in all of this is to format and send out emails for the initial registration, or for password resets.
-
-The default implementation of this service uses the xref:_ug_reference-services-api_manpage-EmailService[`EmailService`], which must be configured in order for user registration to be enabled.
-
-
-== SPI
-
-The SPI defined by this service is:
-
-[source,java]
-----
-public interface EmailNotificationService extends Serializable {
- @Programmatic
- boolean send(EmailRegistrationEvent ev); // <1>
- @Programmatic
- boolean send(PasswordResetEvent ev); // <2>
- @Programmatic
- boolean isConfigured(); // <3>
-}
-----
-<1> sends an email to verify an email address as part of the initial user registration
-<2> sends an email to reset a password for an already-registered user
-<3> determines whether the implementation was configured and initialized correctly
-
-If `isConfigured()` returns false then it is _not_ valid to call `send(...)` (and doing so will result in an `IllegalStateException` being thrown.
-
-
-== Implementation
-
-The framework provides a default implementation, `o.a.i.core.runtime.services.userreg.EmailNotificationServiceDefault` that constructs the emails to send.
-
-
-
-=== Alternative Implementations
-
-The text of these email templates is hard-coded as resources, in other words baked into the core jar files. If you need to use different text then you can of course always write and register your own implementation to be used instead of Isis' default.
-
-If you have configured an alternative email service implementation, it should process the message body as HTML.
-
-If you wish to write an alternative implementation of this service, note that (unlike most Isis domain services) the implementation is also instantiated and injected by Google Guice. This is because `EmailNotificationService` is used as part of the xref:_ug_wicket-viewer_features_user-registration[user registration] functionality and is used by Wicket pages that are accessed outside of the usual Isis runtime.
-
-This implies a couple of additional constraints:
-
-* first, implementation class should also be annotated with `@com.google.inject.Singleton`
-* second, there may not be any Isis session running. (If necessary, one can be created on the fly using `IsisContext.doInSession(...)`)
-
-To ensure that your alternative implementation takes the place of the default implementation, register it explicitly in `isis.properties`.
-
-
-
-== Registering the Service
-
-Assuming that the `configuration-and-annotation` services installer is configured:
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then Isis' default implementation of `EmailNotificationService` service is automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
-
-
-== Related Services
-
-As noted elsewhere, the default implementation of this service uses xref:_ug_reference-services-api_manpage-EmailService[`EmailService`]. This service has no specific configuration properties but does require that the `EmailService` has been configured.
-
-Conversely, this service is used by (Isis' default implementation of) xref:_ug_reference-services-spi_manpage-UserRegistrationService[`UserRegistrationService`].
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-EventSerializer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-EventSerializer.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-EventSerializer.adoc
deleted file mode 100644
index 4e7facc..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-EventSerializer.adoc
+++ /dev/null
@@ -1,72 +0,0 @@
-[[_ug_reference-services-spi_manpage-EventSerializer]]
-= `EventSerializer`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `EmailSerializer` service is a supporting service intended for use by (any implementation of) xref:_ug_reference-services-spi_manpage-PublishingService[`PublishingService`]. Its responsibility is to combine the `EventMetadata` and the `EventPayload` into some serialized form (such as JSON, XML or a string) that can then be published.
-
-See xref:_ug_reference-services-spi_manpage-PublishingService[`PublishingService`] for further discussion.
-
-
-
-
-== SPI
-
-The SPI defined by this service is:
-
-[source,java]
-----
-public interface EventSerializer {
- Object serialize( // <1>
- EventMetadata metadata, // <2>
- EventPayload payload); // <3>
-}
-----
-<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:_ug_reference-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.
-
-
-
-
-
-== Implementation
-
-The (non-ASF) http://github.com/isisaddons/isis-module-publishing[Isis addons' publishing] module provides an implementation (`org.isisaddons.module.publishing.dom.eventserializer.RestfulObjectsSpecEventSerializer`) that represents the event payload using the representation defined by the link:http://restfulobjects.org[Restful Objects spec] of (transient) objects, grafting on the metadata as additional JSON nodes.
-
-For example, this is the JSON generated on an action invocation:
-
-.JSON representation of a published action invocation
-image::{_imagesdir}reference-services-spi/EventSerializer/action-invocation-published-to-stderr.png[width="750px",link="{_imagesdir}reference-services-spi/EventSerializer/action-invocation-published-to-stderr.png"]
-
-while this is the object change JSON:
-
-.JSON representation of a published changed object
-image::{_imagesdir}reference-services-spi/EventSerializer/changed-object-published-to-stderr.png[width="750px",link="{_imagesdir}reference-services-spi/EventSerializer/changed-object-published-to-stderr.png"]
-
-You could if you wish change the representation by registering your own implementation of this API in `isis.properties`:
-
-
-
-
-
-== Registering the Services
-
-Assuming that the `configuration-and-annotation` services installer is configured:
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then adding the (non-ASF) http://github.com/isisaddons/isis-module-publishing[Isis addons' publishing] module to the classpath will automatically register the `RestfulObjectsSpecEventSerializer` implementation (and also the module's `PublishingService` implementation).
-
-
-
-== Related Services
-
-This service is intended (though not mandated) to be used by implementations of xref:_ug_reference-services-spi_manpage-PublishingService[`PublishingService`].
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-ExceptionRecognizer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-ExceptionRecognizer.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-ExceptionRecognizer.adoc
deleted file mode 100644
index 8a30b60..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-ExceptionRecognizer.adoc
+++ /dev/null
@@ -1,123 +0,0 @@
-[[_ug_reference-services-spi_manpage-ExceptionRecognizer]]
-= `ExceptionRecognizer`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `ExceptionRecognizer` service provides the mechanism for both the domain programmer and also for components to be able to recognize and handle certain exceptions that may be thrown by the system. Rather than display an obscure error to the end-user, the application can instead display a user-friendly message.
-
-For example, the JDO/DataNucleus Objectstore provides a set of recognizers to recognize and handle SQL constraint exceptions such as uniqueness violations. These can then be rendered back to the user as expected errors, rather than fatal stacktraces.
-
-It is also possible to provide additional implementations, registered in `isis.properties`. Unlike other services, where any service registered in `isis.properties` replaces any default implementations, in the case of this service all implementations registered are "consulted" to see if they recognize an exception (the chain-of-responsibility pattern).
-
-
-
-
-== SPI
-
-The SPI defined by this service is:
-
-[source,java]
-----
-public interface ExceptionRecognizer2 ... {
- public enum Category { // <1>
- ...
- }
- public static class Recognition { // <2>
- private Category category;
- private String reason;
- ...
- }
- @Programmatic
- public Recognition recognize2(Throwable ex); // <3>
-
- @Deprecated
- @Programmatic
- public String recognize(Throwable ex); // <4>
-
-}
-----
-<1> an enumeration of varies categories of exceptions that are recognised
-<2> represents the fact that an exception has been recognized as has been converted into a user-friendy message, and has been categorized
-<3> the main API, to attempt to recognize an exception
-<4> deprecated API which converted exceptions into strings (reasons), ie without any categorization. This is no longer called.
-
-
-The categories are:
-
-[source,java]
-----
-public interface ExceptionRecognizer2 ... {
- public enum Category {
- CONSTRAINT_VIOLATION, // <1>
- NOT_FOUND, // <2>
- CONCURRENCY, // <3>
- CLIENT_ERROR, // <4>
- SERVER_ERROR, // <5>
- OTHER // <6>
- }
- ...
-}
-
-----
-<1> a violation of some declarative constraint (eg uniqueness or referential integrity) was detected.
-<2> the object to be acted upon cannot be found (404)
-<3> a concurrency exception, in other words some other user has changed this object.
-<4> recognized, but for some other reason... 40x error
-<5> 50x error
-<6> recognized, but uncategorized (typically: a recognizer of the original `ExceptionRecognizer` API).
-
-
-In essence, if an exception is recognized then it is also categorized. This lets the viewer act accordingly. For example, if an exception is raised from the loading of an individual object, then this is passed by the registered ``ExceptionRecognizer``s. If any of these recognize the exception as representing a not-found exception, then an Isis `ObjectNotFoundException` is raised. Both the viewers interprets this correctly (the xref:_ug_wicket-viewer[Wicket viewer] as a suitable error page, the xref:_ug_restfulobjects-viewer[Restful Objects viewer] as a 404 status return code).
-
-
-If the implementation recognizes the exception then it returns a user-friendly message to be rendered (by the viewer) back to the user; otherwise it returns `null`. There is no need for the implementation to check for exception causes; the casual chain is unwrapped by Isis core and each exception in the chain will also be passed through to the recognizer (from most specific to least). The recognizer implementation can therefore be as fine-grained or as coarse-grained as it wishes.
-
-
-
-
-== Implementation
-
-The framework provides two default implementations:
-
-* `o.a.i.core.metamodel.services.container.DomainObjectContainerDefault` provided by Isis core is itself an `ExceptionRecognizer`, and will handle ``ConcurrencyException``s. It will also handle any application exceptions raised by the system (subclasses of `o.a.i.applib.RecoverableException`).
-
-* `o.a.i.objectstore.jdo.applib.service.exceprecog.ExceptionRecognizerCompositeForJdoObjectStore` bundles up a number of more fine-grained implementations:
-** `ExceptionRecognizerForSQLIntegrityConstraintViolationUniqueOrIndexException`
-** `ExceptionRecognizerForJDOObjectNotFoundException`
-** `ExceptionRecognizerForJDODataStoreException`
-
-
-If you want to recognize and handle additional exceptions (for example to capture error messages specific to the JDBC driver you might be using), then create a fine-grained implementation of `ExceptionRecognizer2` for the particular error message (there are some convenience implementations of the interface that you can subclass from if required) and register in `isis.properties`.
-
-
-
-
-== Registering the Services
-
-
-Assuming that the `configuration-and-annotation` services installer is configured:
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then the default implementations provided by the framework (`DomainObjectContainerDefault` and `ExceptionRecognizerCompositeForJdoObjectStore`) will be registered.
-
-In addition, you can register any further exception recognizers in `isis.properties`:
-
-[source,ini]
-----
-isis.services=...,\
- com.mycompany.myapp.MyExceptionRecognizer,\
- ...
-----
-
-[NOTE]
-====
-Prior to 1.9.0, the `ExceptionRecognizerCompositeForJdoObjectStore` also required manual registration:
-
-====
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-LocaleProvider.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-LocaleProvider.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-LocaleProvider.adoc
deleted file mode 100644
index 9ce21a5..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-LocaleProvider.adoc
+++ /dev/null
@@ -1,71 +0,0 @@
-[[_ug_reference-services-spi_manpage-LocaleProvider]]
-= `LocaleProvider`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `LocaleProvider` service is one of the services that work together to implement Isis' support for i18n, being used by Isis' default implementation of xref:_ug_reference-services-spi_manpage-TranslationService[`TranslationService`].
-
-The role of the service itself is simply to return the `Locale` of the current user.
-
-
-[NOTE]
-====
-For the "big picture" and further details on Isis' i18n support, see xref:_ug_more-advanced_i18n[here].
-====
-
-
-
-== SPI
-
-The SPI defined by this service is:
-
-[source,java]
-----
-public interface LocaleProvider {
- @Programmatic
- Locale getLocale();
-}
-----
-
-This is notionally request-scoped, returning the `Locale` of the current user; _not_ that of the server. (Note that the implementation is not required to actually be xref:_ug_reference-annotations_manpage-RequestScoped[`@RequestScoped`], however).
-
-
-
-
-== Implementation
-
-Isis' xref:_ug_wicket-viewer[Wicket viewer] provides an implementation of this service (`LocaleProviderWicket`) which leverages Apache Wicket APIs.
-
-[NOTE]
-====
-Currently there is no equivalent implementation for the xref:_ug_restfulobjects-viewer[RestfulObjects viewer].
-====
-
-
-
-
-== Registering the Services
-
-Assuming that the `configuration-and-annotation` services installer is configured:
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-and that the xref:_ug_wicket-viewer[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.
-
-
-
-
-
-== Related Services
-
-This service works in conjunction with xref:_ug_reference-services-spi_manpage-TranslationService[`TranslationService`] and xref:_ug_reference-services-spi_manpage-TranslationsResolver[`TranslationsResolver`] in order to provide i18n support.
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-PublishingService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-PublishingService.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-PublishingService.adoc
deleted file mode 100644
index 9cb2229..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-PublishingService.adoc
+++ /dev/null
@@ -1,163 +0,0 @@
-[[_ug_reference-services-spi_manpage-PublishingService]]
-= `PublishingService`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `PublishingService` is intended for coarse-grained publish/subscribe for system-to-system interactions, from Isis to some other system. Here the only events published are those that action invocations and of changed objects. A typical use case is to publish onto a pub/sub bus such as link:http://activemq.apache.org/[ActiveMQ] with link:http://camel.apache.org[Camel] to keep other systems up to date.
-
-
-
-== SPI
-
-The SPI defined by the service is:
-
-[source,java]
-----
-public interface PublishingService {
- public void publish(
- EventMetadata metadata, // <1>
- EventPayload payload); // <2>
- @Deprecated
- @Programmatic
- void setEventSerializer(EventSerializer eventSerializer); // <3>
-}
-----
-<1> standard metadata about the event, such as the user, the xref:_ug_reference-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:_ug_reference-services-spi_manpage-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.
-
-
-Typically implementations will use the injected `EventSerializer` to convert the metadata and payload into a form to be published:
-
-[source,java]
-----
-public interface EventSerializer {
- public Object serialize(EventMetadata metadata, EventPayload payload);
-}
-----
-
-The serialized form returned by `EventSerializer` must be in a form that the `PublishingService` implementation is able to handle. Strings are a good lowest common denominator, but (if custom implementations of both `EventSerializer` and `PublishingService` were in use) then it might also be some other type, for example an `org.w3c.dom.Document` or an `org.json.JSONObject` might be returned instead.
-
-
-
-== Implementation
-
-The (non-ASF) http://github.com/isisaddons/isis-module-publishing[Isis addons' publishing] module provides an implementation (`org.isisaddons.module.publishing.dom.org.apache.isis.applib.services.publish`) that persists each event as a `PublishedEvent` entity. This holds the serialized form of the event metadata and payload as translated into a string by the injected `EventSerializer`. The module also provides its own implementation of `EventSerializer`, namely `RestfulObjectsSpecEventSerializer`, which represents the event payload using the representation defined by the link:http://restfulobjects.org[Restful Objects spec] of (transient) objects, grafting on the metadata as additional JSON nodes.
-
-The `PublishedEvent` entity also has a `state` field taking the values either "QUEUED" or "PROCESSED". The intention here is that an event bus can poll this table to grab pending events and dispatch them to downstream systems. When ``PublishedEvent``s are persisted initially they always take the value "QUEUED".
-
-
-
-
-== Usage
-
-To indicate that an action invocation should be published, annotate it with the xref:_ug_reference-annotations_manpage-Action_publishing[`@Action#publishing()`] annotation.
-
-To indicate that a changed object should be published is to annotate it with the xref:_ug_reference-annotations_manpage-DomainObject_publishing[`@DomainObject#publishing()`] annotation.
-
-
-It is also possible to "fine-tune" the `EventPayload` using the `#publishingFactory()` attribute (for both annotations). By default the `EventPayload` that is serialized identifies the object(s) being interacted with or changed, and in the case of the action invocation provides details of the action arguments and result (if any) of that action. However, the payload does not (by default) include any information about the new state of these objects. It is therefore the responsibility of the subscriber to call back to Isis to determine any information that has not been published.
-
-Although the representations (if using the Restful Object serializer and Restful Objects viewer) does include hrefs for the objects, this nevertheless requires an additional network call to obtain this information).
-
-In some circumstances, then, it may make more sense to eagerly "push" information about the change to the subscriber by including that state within the payload.
-
-To accomplish this, an implementation of a "`PayloadFactory`" must be specified in the annotation.
-
-For actions, we implement the `PublishingPayloadFactoryForAction` (in `o.a.i.applib.annotation`):
-
-[source,java]
-----
-public interface PublishingPayloadFactoryForAction {
- @Programmatic
- public EventPayload payloadFor(
- Identifier actionIdentifier,
- Object target,
- List<Object> arguments,
- Object result);
-}
-}
-----
-The `EventPayloadForActionInvocation` abstract class (in the Isis applib) should be used as the base class for the object instance returned from `payLoadFor(...)`.
-
-For objects, the interface to implement is `PublishingPayloadFactoryForObject`:
-
-[source,java]
-----
-public interface PublishingPayloadFactoryForObject {
-
- @Programmatic
- public EventPayload payloadFor(
- Object changedObject,
- PublishingChangeKind publishingChangeKind); // <1>
-}
-----
-<1> an enum taking the values `CREATE`, `UPDATE`, `DELETE`
-
-Similarly, the `EventPayloadForObjectChanged` abstract class should be used as the base class for the object returned from `payLoadFor(...)`.
-
-For example, the following will eagerly include a `ToDoItem`'s `description` property whenever it is changed:
-
-[source,java]
-----
-@DomainObject(publishingPayloadFactory=ToDoItemPayloadFactory.class)
-public class ToDoItem {
- ...
-}
-----
-
-where `ToDoItemPayloadFactory` is defined as:
-
-[source,java]
-----
-public class ToDoItemChangedPayloadFactory implements PublishingPayloadFactoryForObject {
- public static class ToDoItemPayload
- extends EventPayloadForObjectChanged<ToDoItem> {
- public ToDoItemPayload(ToDoItem changed) { super(changed); }
- public String getDescription() { return getChanged().getDescription(); }
- }
- @Override
- public EventPayload payloadFor(Object changedObject, PublishingChangeKind kind) {
- return new ToDoItemPayload((ToDoItem) changedObject);
- }
-}
-----
-
-
-
-
-== Registering the Services
-
-Assuming that the `configuration-and-annotation` services installer is configured:
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then adding the (non-ASF) http://github.com/isisaddons/isis-module-publishing[Isis addons' publishing] module to the classpath will automatically register the `PublishingService` implementation (and also the module's `RestfulObjectsSpecEventSerializer` implementation).
-
-
-
-
-== Related Services
-
-The `PublishingService` is intended for coarse-grained publish/subscribe for system-to-system interactions, from Isis to some other system. Here the only events published are those that action invocations (for actions annotated with xref:_ug_reference-annotations_manpage-Action_publishing[`@Action#publishing()`]) and of changed objects (for objects annotated with xref:_ug_reference-annotations_manpage-DomainObject_publishing[`@DomainObject#publishing()`].
-
-The xref:_ug_reference-services-api_manpage-EventBusService[`EventBusService`] meanwhile is intended for fine-grained publish/subscribe for object-to-object interactions within an 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:_ug_reference-classes_mixins_manpage-HasTransactionId[`HasTransactionId`] interface.
-
-
-
-
-== Design Notes
-
-The following class diagram shows how the above components fit together:
-
-image::{_imagesdir}reference-services-spi/PublishingService/yuml.me-23db58a4.png[width="800px",link="{_imagesdir}reference-services-spi/PublishingService/yuml.me-23db58a4.png"]
-
-This yuml.me diagram was generated at http://yuml.me/edit/23db58a4[yuml.me].
\ No newline at end of file
[05/45] isis git commit: ISIS-1133: breaking out reference guide and
devenv guide;
moving appendices' release notes and migration notes to other docs;
improving the documentation page.
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_maven-configuration.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_maven-configuration.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_maven-configuration.adoc
deleted file mode 100644
index 55fd56a..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_maven-configuration.adoc
+++ /dev/null
@@ -1,73 +0,0 @@
-[[_ug_testing_bdd-spec-support_maven-configuration]]
-= Maven Configuration
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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' BDD spec support is automatically configured if you use the xref:_ug_getting-started_simpleapp-archetype[SimpleApp archetype]. To set it up manually, update the `pom.xml` of your domain object model module:
-
-[source,xml]
-----
-<dependency>
- <groupId>org.apache.isis.core</groupId>
- <artifactId>isis-core-specsupport</artifactId>
- <scope>test</scope> // <1>
-</dependency>
-----
-<1> Normally `test`; usual Maven scoping rules apply.
-
-
-We also recommend that you configure the `maven-surefire-plugin` to pick up the following class patterns:
-
-
-[source,xml]
-----
-<plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-surefire-plugin</artifactId>
- <version>2.10</version>
- <configuration>
- <includes>
- <include>**/*Test.java</include>
- <include>**/*Test_*.java</include>
- <include>**/*Spec*.java</include>
- </includes>
- <excludes>
- <exclude>**/Test*.java</exclude>
- <exclude>**/*ForTesting.java</exclude>
- <exclude>**/*Abstract*.java</exclude>
- </excludes>
- <useFile>true</useFile>
- <printSummary>true</printSummary>
- <outputDirectory>${project.build.directory}/surefire-reports</outputDirectory>
- </configuration>
-</plugin>
-----
-
-
-You may also find it more convenient to place the `.feature` files in `src/test/java`, rather than `src/test/resources`. If you wish to do this, then your integtest module's `pom.xml` must contain:
-
-[source,xml]
-----
-<build>
- <testResources>
- <testResource>
- <filtering>false</filtering>
- <directory>src/test/resources</directory>
- </testResource>
- <testResource>
- <filtering>false</filtering>
- <directory>src/test/java</directory>
- <includes>
- <include>**</include>
- </includes>
- <excludes>
- <exclude>**/*.java</exclude>
- </excludes>
- </testResource>
- </testResources>
-</build>
-----
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_writing-a-bdd-spec.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_writing-a-bdd-spec.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_writing-a-bdd-spec.adoc
deleted file mode 100644
index 7b2348d..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_writing-a-bdd-spec.adoc
+++ /dev/null
@@ -1,141 +0,0 @@
-[[_ug_testing_bdd-spec-support_writing-a-bdd-spec]]
-= Writing a BDD spec
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-
-BDD specifications contain:
-
-* a `XxxSpec.feature` file, describing the feature and the scenarios (given/when/then)s that constitute its acceptance criteria
-
-* a `RunSpecs.java` class file to run the specification (all boilerplate). This will run all `.feature` files in the same package or subpackages.
-
-* one or several `XxxGlue` constituting the step definitions to be matched against. +
-+
-The "glue" (step definitions) are intended to be reused across features. We therefore recommend that they reside in a separate package, and are organized by the entity type upon which they act. +
-+
-For example, given a feature that involves `Customer` and `Order`, have the step definitions pertaining to `Customer` reside in `CustomerGlue`, and the step definitions pertaining to `Order` reside in `OrderGlue`. +
-+
-The `glue` attribute of the Cucumber-JVM JUnit runner eallows you to indicate which package(s) should be recursively searched to find any glue.
-
-* a system initializer class. You can reuse the system initializer from any integration tests (as described in xref:_ug_testing_integ-test-support[Integration Test Support], bootstrapping section).
-
-
-Here's an example of a feature from the xref:_ug_getting-started_simpleapp-archetype[SimpleApp archetype]:
-
-[source,java]
-----
-@SimpleObjectsFixture
-Feature: List and Create New Simple Objects
-
- @integration
- Scenario: Existing simple objects can be listed and new ones created
- Given there are initially 3 simple objects
- When I create a new simple object
- Then there are 4 simple objects
-----
-
-The `@SimpleObjectsFixture` is a custom tag we've specified to indicate the prerequisite fixtures to be loaded; more on this in a moment. The `@integration` tag, meanwhile, says that this feature should be run with integration-level scope.
-
-
-[NOTE]
-====
-Although BDD specs are most commonly used for end-to-end tests (ie at the same scope as an integration test), the two concerns (expressability of a test to a business person vs granularity of the test) should not be conflated. There are a couple of http://silkandspinach.net/2013/01/18/a-testing-strategy/[good] blog http://claysnow.co.uk/the-testing-iceberg/[posts] discussing http://claysnow.co.uk/living-documentation-can-be-readable-and-fast/[this]. The basic idea is to avoid the overhead of a heavy-duty integration test if possible.
-
-Apache Isis does also support running BDD specs in unit test mode; by annotating the scenario with the `@unit` (rather than `@integration` tag). When running under unit-level scope, the Isis system is _not_ instantiated. Instead, the `ScenarioExecution` class returns JMock mocks (except for the `WrapperFactory`, if configured).
-
-To support unit testing scope 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_getting-started_simpleapp-archetype[SimpleApp archetype]. For those who do require faster-executing test suite, it's worthwhile knowing that Isis can support this.
-
-====
-
-
-The `RunSpecs` class to run this feature (and any other features in this package or subpackages) is just boilerplate
-
-[source,java]
-----
-@RunWith(Cucumber.class)
-@CucumberOptions(
- format = {
- "html:target/cucumber-html-report"
- ,"json:target/cucumber.json"
- },
- glue={"classpath:domainapp.integtests.specglue"},
- strict = true,
- tags = { "~@backlog", "~@ignore" })
-public class RunSpecs {
- // intentionally empty
-}
-----
-
-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_getting-started_simpleapp-archetype[SimpleApp archetype].
-
-The bootstrapping of Isis can be moved into a `BootstrappingGlue` step definition:
-
-[source,java]
-----
-public class BootstrappingGlue extends CukeGlueAbstract {
- @Before(value={"@integration"}, order=100)
- public void beforeScenarioIntegrationScope() {
- org.apache.log4j.PropertyConfigurator.configure("logging.properties");
- SimpleAppSystemInitializer.initIsft();
-
- before(ScenarioExecutionScope.INTEGRATION);
- }
- @After
- public void afterScenario(cucumber.api.Scenario sc) {
- assertMocksSatisfied();
- after(sc);
- }
-}
-----
-
-The fixture to run also lives in its own step definition, https://github.com/apache/isis/blob/07fe61ef3fb029ae36427f60da2afeeb931e4f88/example/application/simpleapp/integtests/src/test/java/domainapp/integtests/specglue/CatalogOfFixturesGlue.java#L24[`CatalogOfFixturesGlue`]:
-
-[source,java]
-----
-public class CatalogOfFixturesGlue extends CukeGlueAbstract {
- @Before(value={"@integration", "@SimpleObjectsFixture"}, order=20000)
- public void integrationFixtures() throws Throwable {
- scenarioExecution().install(new RecreateSimpleObjects());
- }
-}
-----
-
-Note that this is annotated with a tag (`@SimpleObjectsFixture`) so that the correct fixture runs. (We might have a whole variety of these).
-
-The step definitions pertaining to `SimpleObject` domain entity then reside in the https://github.com/apache/isis/blob/07fe61ef3fb029ae36427f60da2afeeb931e4f88/example/application/simpleapp/integtests/src/test/java/domainapp/integtests/specglue/modules/simple/SimpleObjectGlue.java#L31[`SimpleObjectGlue`] class. This is where the heavy lifting gets done:
-
-[source,java]
-----
-public class SimpleObjectGlue extends CukeGlueAbstract {
- @Given("^there are.* (\\d+) simple objects$")
- public void there_are_N_simple_objects(int n) throws Throwable {
- try {
- final List<SimpleObject> findAll = service(SimpleObjects.class).listAll();
- assertThat(findAll.size(), is(n));
- putVar("list", "all", findAll);
-
- } finally {
- assertMocksSatisfied();
- }
- }
- @When("^I create a new simple object$")
- public void I_create_a_new_simple_object() throws Throwable {
- service(SimpleObjects.class).create(UUID.randomUUID().toString());
- }
-}
-----
-
-[TIP]
-====
-If using Java 8, note that Cucumber JVM supports a link:https://cucumber.io/docs/reference/jvm#java-8-lambdas[simplified syntax using lambdas].
-====
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_fixture-scripts.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_fixture-scripts.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_fixture-scripts.adoc
deleted file mode 100644
index 2f311b7..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_fixture-scripts.adoc
+++ /dev/null
@@ -1,44 +0,0 @@
-[[_ug_testing_fixture-scripts]]
-= Fixture Scripts
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 writing integration tests (and implementing the glue for BDD specs) 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.
-
-On a very simple system you could probably get away with using SQL to insert directly into the database, or you could use a toolkit such as link:http://dbunit.sourceforge.net/howto.html[dbunit] to upload data from flat files. Such approaches aren't particularly maintainable though. If in the future the domain entities (and therefore corresponding database tables) change their structure, then all of those data sets will need updating.
-
-Even more significantly, there's no way to guarantee that the data that's being loaded is logically consistent with the business behaviour of the domain objects themselves. That is, there's nothing to stop your test from putting data into the database that would be invalid if one attempted to add it through the app.
-
-The solution that Isis provides is a small library called *_fixture scripts_*. A fixture script is basically a wrapper for executing arbitrary work, but that work almost always invoking a business action.
-
-[TIP]
-====
-If you want to learn more on this topic (with live coding!), check out this https://skillsmatter.com/skillscasts/5638-to-those-whom-much-is-given-much-is-expected[presentation] given at BDD Exchange 2014.
-====
-
-There is another benefit to Isis' fixture script approach; the fixtures can be (in prototyping mode) run from your application. This means that fixture scripts can actually help all the way through the development lifecycle:
-
-* when specifying a new feature, you can write a fixture script to get the system into the "given" state, and then start exploring the required functionality with the domain expert actually _within_ the application +
-+
-And if you can't write a fixture script for the story, it probably means that there's some prerequisite feature that needs implementing that you hadn't previously recognized
-
-* when the developer implements the story, s/he has a precanned script to run when they manually verify the functionality works
-
-* when the developer automates the story's acceptance test as an integration test, they already have the "given" part of the test implemented
-
-* when you want to pass the feature over to the QA/tester for additional manual exploratory testing, they have a fixture script to get them to a jumping off point for their explorations
-
-* when you want to demonstrate the implemented feature to your domain expert, your demo can use the fixture script so you don't bore your audience in performing lots of boring setup before getting to the actual feature
-
-* when you want to roll out training to your users, you can write fixture scripts as part of their training exercises
-
-
-The following sections explain the API and how to go about using the API.
-
-
-include::_ug_testing_fixture-scripts_api-and-usage.adoc[leveloffset=+1]
-include::_ug_testing_fixture-scripts_sudo-service.adoc[leveloffset=+1]
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_fixture-scripts_api-and-usage.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_fixture-scripts_api-and-usage.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_fixture-scripts_api-and-usage.adoc
deleted file mode 100644
index 6bde700..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_fixture-scripts_api-and-usage.adoc
+++ /dev/null
@@ -1,286 +0,0 @@
-[[_ug_testing_fixture-scripts_api-and-usage]]
-= API and Usage
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 parts to using fixture scripts: the `FixtureScripts` domain service class, and the `FixtureScript` view model class, both being `abstract`.
-
-* The job of the `FixtureScripts` domain service is to locate all fixture scripts from the classpath and to let them be invoked, either from an integration test/BDD spec or from the UI of your Isis app.
-
-* With `FixtureScript` meanwhile you subclass for each of the scenarios that you want to define. You can also subclass from `FixtureScript` to create helpers; more on this below.
-
-Let's look at `FixtureScripts` domain service in more detail first.
-
-== `FixtureScripts`
-
-In your code you subclass `FixtureScripts` domain service primarily just to specify which package to search for. For example, here's the service that's generated by the xref:_ug_getting-started_simpleapp-archetype[SimpleApp archetype]:
-
-[source,java]
-----
-@DomainService
-@DomainServiceLayout(
- menuBar = DomainServiceLayout.MenuBar.SECONDARY, // <1>
- named="Prototyping", // <2>
- menuOrder = "500"
-)
-public class DomainAppFixturesService extends FixtureScripts { // <3>
-
- public DomainAppFixturesService() {
- super(
- "domainapp", // <4>
- MultipleExecutionStrategy.EXECUTE); // <5>
- }
- @Override
- public FixtureScript default0RunFixtureScript() {
- return findFixtureScriptFor(RecreateSimpleObjects.class); // <6>
- }
- @Override
- public List<FixtureScript> choices0RunFixtureScript() { // <7>
- return super.choices0RunFixtureScript();
- }
-}
-----
-<1> in the UI, render the on the right hand side (secondary) menu bar...
-<2> ... under the "Prototyping" menu
-<3> inherit from `org.apache.isis.applib.fixturescripts.FixtureScripts`
-<4> search for all fixture scripts under the "domainapp" package; in your code this would probably be "com.mycompany.myapp" or similar
-<5> if the same fixture script (class) is encountered more than once, then run anyway; more on this in <<Organizing Fixture scripts>>.
-<6> (optional) specify a default fixture script to run, in this case `RecreateSimpleObjects` fixture script (see below)
-<7> make all fixture scripts found available as a drop-down (by increasing the visibility of this method to `public`)
-
-
-Here's how the domain service looks like in the UI:
-
-image::{_imagesdir}testing/fixture-scripts/prototyping-menu.png[width="700px",link="{_imagesdir}testing/fixture-scripts/prototyping-menu.png"]
-
-
-and here's what the `runFixtureScript` action prompt looks like:
-
-image::{_imagesdir}testing/fixture-scripts/prompt.png[width="700px",link="{_imagesdir}testing/fixture-scripts/prompt.png"]
-
-
-when this is executed, the resultant objects (actually, instances of FixtureResult`) are shown in the UI:
-
-image::{_imagesdir}testing/fixture-scripts/result-list.png[width="700px",link="{_imagesdir}testing/fixture-scripts/result-list.png"]
-
-
-
-If you had defined many fixture scripts then a drop-down might become unwieldy, in which case your code would probably override the `autoComplete...())` instead:
-
-[source,java]
-----
- @Override
- public List<FixtureScript> autoComplete0RunFixtureScript(final @MinLength(1) String searchArg) {
- return super.autoComplete0RunFixtureScript(searchArg);
- }
-
-----
-
-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_getting-started_simpleapp-archetype[SimpleApp archetype] adds this additional action:
-
-[source,java]
-----
- @Action(
- restrictTo = RestrictTo.PROTOTYPING
- )
- @ActionLayout(
- cssClassFa="fa fa-refresh"
- )
- @MemberOrder(sequence="20")
- public Object recreateObjectsAndReturnFirst() {
- final List<FixtureResult> run = findFixtureScriptFor(RecreateSimpleObjects.class).run(null);
- return run.get(0).getObject();
- }
-----
-
-Let's now look at the `FixtureScript` class, where there's a bit more going on.
-
-== `FixtureScript`
-
-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_getting-started_simpleapp-archetype[SimpleApp archetype]:
-
-[source,java]
-----
-public class RecreateSimpleObjects extends FixtureScript { // <1>
-
- public final List<String> NAMES = Collections.unmodifiableList(Arrays.asList(
- "Foo", "Bar", "Baz", "Frodo", "Froyo",
- "Fizz", "Bip", "Bop", "Bang", "Boo")); // <2>
- public RecreateSimpleObjects() {
- withDiscoverability(Discoverability.DISCOVERABLE); // <3>
- }
- private Integer number; // <4>
- public Integer getNumber() { return number; }
- public RecreateSimpleObjects setNumber(final Integer number) {
- this.number = number;
- return this;
- }
- private final List<SimpleObject> simpleObjects = Lists.newArrayList(); // <5>
- public List<SimpleObject> getSimpleObjects() {
- return simpleObjects;
- }
- @Override
- protected void execute(final ExecutionContext ec) { // <6>
- // defaults
- final int number = defaultParam("number", ec, 3); // <7>
- // validate
- if(number < 0 || number > NAMES.size()) {
- throw new IllegalArgumentException(
- String.format("number must be in range [0,%d)", NAMES.size()));
- }
- // execute
- ec.executeChild(this, new SimpleObjectsTearDown()); // <8>
- for (int i = 0; i < number; i++) {
- final SimpleObjectCreate fs =
- new SimpleObjectCreate().setName(NAMES.get(i));
- ec.executeChild(this, fs.getName(), fs); // <9>
- simpleObjects.add(fs.getSimpleObject()); // <10>
- }
- }
-}
-----
-<1> inherit from `org.apache.isis.applib.fixturescripts.FixtureScript`
-<2> a hard-coded list of values for the names. Note that the http://github.com/isisaddons/isis-module-fakedata[Isis addons' fakedata] module (non-ASF) could also have been used
-<3> whether the script is "discoverable"; in other words whether it should be rendered in the drop-down by the `FixtureScripts` service
-<4> input property: the number of objects to create, up to 10; for the calling test to specify, but note this is optional and has a default (see below). It's important that a wrapper class is used (ie `java.lang.Integer`, not `int`)
-<5> output property: the generated list of objects, for the calling test to grab
-<6> the mandatory execute(...) API
-<7> the `defaultParam(...)` (inherited from `FixtureScript`) will default the `number` property (using Java's Reflection API) if none was specified
-<8> call another fixture script (`SimpleObjectsTearDown`) using the provided `ExecutionContext`. Note that although the fixture script is a view model, it's fine to simply instantiate it (rather than using `DomainObjectContainer#newTransientInstance(...)`).
-<9> calling another fixture script (`SimpleObjectCreate`) using the provided `ExecutionContext`
-<10> adding the created object to the list, for the calling object to use.
-
-
-Because this script has exposed a "number" property, it's possible to set this from within the UI. For example:
-
-image::{_imagesdir}testing/fixture-scripts/prompt.png[width="700px"]
-
-
-When this is executed, the framework will parse the text and attempt to reflectively set the corresponding properties on the fixture result. So, in this case, when the fixture script is executed we actually get 6 objects created:
-
-image::{_imagesdir}testing/fixture-scripts/result-list.png[width="700px"]
-
-
-
-It's commonplace for one fixture script to call another. In the above example this script called `SimpleObjectsTearDown` and `SimpleObjectCreate`. Let's take a quick look at `SimpleObjectCreate`:
-
-[source,java]
-----
-public class SimpleObjectCreate extends FixtureScript { // <1>
-
- private String name; // <2>
- public String getName() { return name; }
- public SimpleObjectCreate setName(final String name) {
- this.name = name;
- return this;
- }
- private SimpleObject simpleObject; // <3>
- public SimpleObject getSimpleObject() {
- return simpleObject;
- }
- @Override
- protected void execute(final ExecutionContext ec) { // <4>
- String name = checkParam("name", ec, String.class); // <5>
- this.simpleObject = wrap(simpleObjects) // <6>
- .create(name); // <7>
- ec.addResult(this, simpleObject); // <8>
- }
- @javax.inject.Inject
- private SimpleObjects simpleObjects; // <9>
-}
-----
-<1> inherit from `org.apache.isis.applib.fixturescripts.FixtureScript`, as above
-<2> input property: name of the object; this time it is required
-<3> output property: the created simple object
-<4> the mandatory execute(...) API
-<5> the `checkParam(...)` (inherited from `FixtureScript`) will check that the "name" property has been populated (using Java's Reflection API) and throw an exception if not
-<6> wrap the injected `SimpleObjects` domain service (using the xref:_ug_reference-services-api_manpage-WrapperFactory[`WrapperFactory`]) to simulate interaction through the UI...
-<7> .. and actually create the object using the "create" business action of that service
-<8> add the resulting object to the execution context; this makes the object available to access if run from the UI
-<9> inject the domain service into the fixture script
-
-
-
-
-
-
-
-== Using within Tests
-
-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_getting-started_simpleapp-archetype[SimpleApp archetype]:
-
-[source,java]
-----
-public class SimpleObjectIntegTest extends SimpleAppIntegTest {
- @Inject
- FixtureScripts fixtureScripts; // <1>
- SimpleObject simpleObjectWrapped;
- @Before
- public void setUp() throws Exception {
- // given
- RecreateSimpleObjects fs =
- new RecreateSimpleObjects().setNumber(1); // <2>
- fixtureScripts.runFixtureScript(fs, null); // <3>
-
- SimpleObject simpleObjectPojo =
- fs.getSimpleObjects().get(0); // <4>
- assertThat(simpleObjectPojo).isNotNull();
-
- simpleObjectWrapped = wrap(simpleObjectPojo); // <5>
- }
- @Test
- public void accessible() throws Exception {
- // when
- final String name = simpleObjectWrapped.getName();
- // then
- assertThat(name).isEqualTo(fs.NAMES.get(0));
- }
- ...
-}
-----
-<1> inject the `FixtureScripts` domain service (just like any other domain service)
-<2> instantiate the fixture script for this test, and configure
-<3> execute the fixture script
-<4> obtain the object under test from the fixture
-<5> wrap the object (to simulate being interacted with through the UI)
-
-
-
-== Organizing Fixture scripts
-
-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_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].
-
-These two styles are probably best illustrated with, well, some illustrations. Here's a fixture script in the "flat" style for setting up a customer with some orders, a number of which has been placed:
-
-image::{_imagesdir}testing/fixture-scripts/flat-1.png[width="700px",link="{_imagesdir}testing/fixture-scripts/flat-1.png"]
-
-Notice how we have a single script that's in control of the overall process, and takes responsibility for passing data from one fixture script to the next.
-
-Here's a similar, simpler script, from the same fictional app, to set up two customers:
-
-image::{_imagesdir}testing/fixture-scripts/flat-2.png[width="500px",link="{_imagesdir}testing/fixture-scripts/flat-2.png"]
-
-We can reuse the same fixture "customer" script, either calling it twice or (perhaps better) passing it an array of customer details to set up.
-
-With the composite style, we rely on each fixture script to set up its own prerequisites. Thus:
-
-image::{_imagesdir}testing/fixture-scripts/composite.png[width="550px",link="{_imagesdir}testing/fixture-scripts/composite.png"]
-
-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_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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_fixture-scripts_sudo-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_fixture-scripts_sudo-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_fixture-scripts_sudo-service.adoc
deleted file mode 100644
index 2c1172e..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_fixture-scripts_sudo-service.adoc
+++ /dev/null
@@ -1,59 +0,0 @@
-[[_ug_testing_fixture-scripts_sudo-service]]
-= `SudoService`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 in our fixture scripts we want to perform a business action running as a particular user. This might be for the usual reason - so that our fixtures accurately reflect the reality of the system with all business constraints enforced using the `WrapperFactory` - or more straightforwardly it might be simply that the action depends on the identity of the user invoking the action.
-
-An example of the latter case is in the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp]'s `ToDoItem` class:
-
-[source,java]
-.Production code that depends on current user
-----
-public ToDoItem newToDo(
- @Parameter(regexPattern = "\\w[@&:\\-\\,\\.\\+ \\w]*") @ParameterLayout(named="Description")
- final String description,
- @ParameterLayout(named="Category")
- final Category category,
- @Parameter(optionality = Optionality.OPTIONAL) @ParameterLayout(named="Subcategory")
- final Subcategory subcategory,
- @Parameter(optionality = Optionality.OPTIONAL) @ParameterLayout(named="Due by")
- final LocalDate dueBy,
- @Parameter(optionality = Optionality.OPTIONAL) @ParameterLayout(named="Cost")
- final BigDecimal cost) {
- return newToDo(description, category, subcategory, currentUserName(), dueBy, cost);
-}
-private String currentUserName() {
- return container.getUser().getName(); // <1>
-}
-----
-<1> is the current user.
-
-The fixture for this can use the `SudoService` to run a block of code as a specified user:
-
-[source,java]
-.Fixture Script
-----
-final String description = ...
-final Category category = ...
-final Subcategory subcategory = ...
-final LocalDate dueBy = ...
-final BigDecimal cost = ...
-final Location location = ...
-
-toDoItem = sudoService.sudo(username,
- new Callable<ToDoItem>() {
- @Override
- public ToDoItem call() {
- final ToDoItem toDoItem = wrap(toDoItems).newToDo(
- description, category, subcategory, dueBy, cost);
- wrap(toDoItem).setLocation(location);
- return toDoItem;
- }
- });
-----
-
-Behind the scenes the `SudoService` simply talks to the `DomainObjectContainer` to override the user returned by the `getUser()` API. It is possible to override both users and roles.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support.adoc
deleted file mode 100644
index f103703..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support.adoc
+++ /dev/null
@@ -1,24 +0,0 @@
-[[_ug_testing_integ-test-support]]
-= Integration Test 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/
-
-
-As discussed in the introductory overview of this chapter, Apache Isis allows you to integration test your domain objects from within JUnit. There are several parts to this:
-
-* configuring the Isis runtime so it can be bootstrapped (mostly boilerplate)
-* defining a base class to perform said bootstrapping
-* using fixture scripts to set up the app
-* using `WrapperFactory` so that the UI can be simulated.
-
-We'll get to all that shortly, but let's start by taking a look at what a typical integration test looks like.
-
-
-include::_ug_testing_integ-test-support_typical-usage.adoc[leveloffset=+1]
-include::_ug_testing_integ-test-support_bootstrapping.adoc[leveloffset=+1]
-include::_ug_testing_integ-test-support_wrapper-factory.adoc[leveloffset=+1]
-include::_ug_testing_integ-test-support_maven-configuration.adoc[leveloffset=+1]
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_bootstrapping.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_bootstrapping.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_bootstrapping.adoc
deleted file mode 100644
index 8bacf80..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_bootstrapping.adoc
+++ /dev/null
@@ -1,231 +0,0 @@
-[[_ug_testing_integ-test-support_bootstrapping]]
-= 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/
-
-
-Integration tests instantiate an Isis "runtime" (as a singleton) within a JUnit test. Because (depending on the size of your app) it takes a little time to bootstrap Isis, the framework caches the runtime on a thread-local from one test to the next.
-
-Nevertheless, we do need to bootstrap the runtime for the very first test.
-
-Since the integration tests don't depend on the `webapp` module, it's necessary to repeat all the (relevant) all the configuration in `isis.properties` and related files. That said, in practice the relevant information isn't all that much.
-
-[NOTE]
-====
-We hope to simplify the way this works in future versions of Isis.
-====
-
-The example code in this section is taken from the app generated by the xref:_ug_getting-started_simpleapp-archetype[SimpleApp archetype].
-
-
-
-
-== Builder
-
-The bootstrapping itself is mostly performed by a subclass of the `IsisSystemForTest.Builder` class:
-
-[source,java]
-----
-private static class SimpleAppSystemBuilder extends IsisSystemForTest.Builder { // <1>
-
- public SimpleAppSystemBuilder() {
- withLoggingAt(org.apache.log4j.Level.INFO);
- with(testConfiguration());
- with(new DataNucleusPersistenceMechanismInstaller()); // <2>
-
- withServicesIn( "domainapp" ); // <3>
- }
-
- private static IsisConfiguration testConfiguration() {
- final IsisConfigurationForJdoIntegTests testConfiguration =
- new IsisConfigurationForJdoIntegTests(); // <4>
-
- testConfiguration.addRegisterEntitiesPackagePrefix("domainapp.dom.modules"); // <5>
- return testConfiguration;
- }
-}
-----
-<1> subclass the framework-provided `IsisSystemForTest.Builder`.
-<2> equivalent to `isis.persistor=datanucleus` in `isis.properties`
-<3> specify the `isis.services` key in `isis.properties` (where "domainapp" is the base package for all classes within the app)
-<4> `IsisConfigurationForJdoIntegTests` has pre-canned configuration for using an in-memory HSQLDB and other standard settings; more on this below.
-<5> equivalent to `isis.persistor.datanucleus.RegisterEntities.packagePrefix` key (typically in `persistor_datanucleus.properties`
-
-
-
-
-=== IsisConfigurationForJdoIntegTests
-
-Integration tests are configured programmatically, with a default set of properties to bootstrap the JDO/DataNucleus objectstore using an HSQLDB in-memory database.
-
-To remove a little bit of boilerplate, the `IsisConfigurationForJdoIntegTests` class (in the `org.apache.isis.objectstore.jdo.datanucleus` package) can be used to bootstrap the application. If necessary, this class can be subclassed to override these defaults.
-
-
-.Default Configuration Properties for Integration Tests
-[cols="2a,1,3a", options="header"]
-|===
-|Property
-|Value
-|Description
-
-|`isis.persistor.datanucleus.impl.` +
-`javax.jdo.option.ConnectionURL`
-|jdbc:hsqldb:mem:test
-|JDBC URL
-
-|`isis.persistor.datanucleus.impl.` +
-`javax.jdo.option.ConnectionDriverName`
-|org.hsqldb.jdbcDriver
-|JDBC Driver
-
-|`isis.persistor.datanucleus.impl.` +
-`javax.jdo.option.ConnectionUserName`
-|sa
-|Username
-
-|`isis.persistor.datanucleus.impl.` +
-`javax.jdo.option.ConnectionPassword`
-|<empty string>
-|Password
-
-|`isis.persistor.datanucleus.impl.` +
-`datanucleus.schema.autoCreateAll`
-|true
-|Recreate DB for each test run (an in-memory database)
-
-|`isis.persistor.datanucleus.impl.` +
-`datanucleus.schema.validateAll`
-|false
-|Disable validations (minimize bootstrap time)
-
-|`isis.persistor.datanucleus.impl.` +
-`datanucleus.persistenceByReachabilityAtCommit`
-|false
-|As per WEB-INF/persistor_datanucleus.properties
-
-|`isis.persistor.datanucleus.impl.` +
-`datanucleus.identifier.case`
-|MixedCase
-|As per WEB-INF/persistor_datanucleus.properties
-
-|`isis.persistor.datanucleus.impl.` +
-`datanucleus.cache.level2.type`
-|none
-|As per WEB-INF/persistor_datanucleus.properties
-
-|`isis.persistor.datanucleus.impl.` +
-`datanucleus.cache.level2.mode`
-|ENABLE_SELECTIVE
-|As per WEB-INF/persistor_datanucleus.properties
-
-|`isis.persistor.datanucleus.` +
-`install-fixtures`
-|true
-|Automatically install any fixtures that might have been registered
-
-|`isis.persistor.` +
-`enforceSafeSemantics`
-|false
-|
-
-|`isis.deploymentType`
-|server_prototype
-|
-|===
-
-
-
-
-
-== System Initializer
-
-The builder is defined and used within a class we call the system initializer that is responsible for instantiating the Isis runtime, and binding it to a thread-local. This is performed within a static `initIsft()` method.
-
-Here's the code:
-
-[source,java]
-----
-public class SimpleAppSystemInitializer {
- public static void initIsft() {
- IsisSystemForTest isft = IsisSystemForTest.getElseNull();
- if(isft == null) {
- isft = new SimpleAppSystemBuilder() // <1>
- .build()
- .setUpSystem();
- IsisSystemForTest.set(isft); // <2>
- }
- }
- private static class SimpleAppSystemBuilder
- extends IsisSystemForTest.Builder { ... }
-
-}
-----
-<1> instantiates and initializes the Isis runtime (the `IsisSystemForTest` class)
-<2> binds the runtime to a thread-local.
-
-
-
-
-== Abstract Class
-
-We recommend defining a base class for all your other classes to integration classes to inherit from. The main responsibility of this class is tocall the system initializer, described earlier. We only need the initialization to be performed once, so this call is performed in a `@BeforeClass` hook.
-
-The code below shows the general form:
-
-[source,java]
-----
-public abstract class SimpleAppIntegTest {
- @BeforeClass
- public static void initClass() {
- org.apache.log4j.PropertyConfigurator.configure("logging.properties"); // <1>
- SimpleAppSystemInitializer.initIsft(); // <2>
- new ScenarioExecutionForIntegration(); // <3>
- }
-}
-----
-<1> ensure that logging messages don't get swallowed
-<2> initialize the Isis runtime
-<3> primarily exists to support the writing of xref:_ug_testing_bdd-spec-support[BDD specifications], but also enables finer-grained management of sessions/transactions (discussed below).
-
-
-
-=== `IntegrationTestAbstract`
-
-In fact, we recommend that your base class inherit from Isis' `IntegrationTestAbstract` class:
-
-[source,java]
-----
-public abstract class SimpleAppIntegTest extends IntegrationTestAbstract {
- ...
-}
-----
-
-Although not mandatory, this provides a number of helper/convenience methods and JUnit rules:
-
-[source,java]
-----
- @Rule
- public IsisTransactionRule isisTransactionRule = // <1>
- new IsisTransactionRule();
- @Rule
- public JUnitRuleMockery2 context = // <2>
- JUnitRuleMockery2.createFor(Mode.INTERFACES_AND_CLASSES);
- @Rule
- public ExpectedException expectedExceptions = // <3>
- ExpectedException.none();
- @Rule
- public ExceptionRecognizerTranslate exceptionRecognizerTranslations = // <4>
- ExceptionRecognizerTranslate.create();
-----
-<1> ensures an Isis session/transaction running for each test
-<2> sets up a JMock context (using Isis' extension to JMock as described in <<JMock Extensions>>
-<3> standard JUnit rule for writing tests that throw exceptions
-<4> to capture messages that require translation, as described in xref:_ug_more-advanced_i18n[i18 support].
-
-All of these rules could be inlined in your own base class; as we say, they are a convenience.
-
-In addition, `IntegrationTestAbstract` provides a number of helper/convenience methods. Most important amongst these are `nextSession()` and `nextTransaction()` that to allow tests to simulate multiple separate user interactions (each of which would normally occur in a separate transaction).
-
-It also provides `wrap(...)` and `unwrap(...)` which delegate to the `WrapperFactory`. We talk about these methods in the next section
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_maven-configuration.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_maven-configuration.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_maven-configuration.adoc
deleted file mode 100644
index dd3684e..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_maven-configuration.adoc
+++ /dev/null
@@ -1,46 +0,0 @@
-[[_ug_testing_integ-test-support_maven-configuration]]
-= Maven Configuration
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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' integration test support is automatically configured if you use the xref:_ug_getting-started_simpleapp-archetype[SimpleApp archetype]. To set it up manually, update the `pom.xml` of your domain object model module:
-
-[source,xml]
-----
-<dependency>
- <groupId>org.apache.isis.core</groupId>
- <artifactId>isis-core-integtestsupport</artifactId>
-</dependency>
-<dependency>
- <groupId>org.apache.isis.core</groupId>
- <artifactId>isis-core-wrapper</artifactId>
-</dependency>
-----
-
-We also recommend that you configure the `maven-surefire-plugin` to pick up the following class patterns:
-
-[source,xml]
-----
-<plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-surefire-plugin</artifactId>
- <version>2.10</version>
- <configuration>
- <includes>
- <include>**/*Test.java</include>
- <include>**/*Test_*.java</include>
- <include>**/*Spec*.java</include>
- </includes>
- <excludes>
- <exclude>**/Test*.java</exclude>
- <exclude>**/*ForTesting.java</exclude>
- <exclude>**/*Abstract*.java</exclude>
- </excludes>
- <useFile>true</useFile>
- <printSummary>true</printSummary>
- <outputDirectory>${project.build.directory}/surefire-reports</outputDirectory>
- </configuration>
-</plugin>
-----
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_typical-usage.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_typical-usage.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_typical-usage.adoc
deleted file mode 100644
index 3d76e8b..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_typical-usage.adoc
+++ /dev/null
@@ -1,124 +0,0 @@
-[[_ug_testing_integ-test-support_typical-usage]]
-= Typical Usage
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 example adapted from the link:http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] (non-ASF). The code we want to test (simplified) is:
-
-[source,java]
-----
-public class ToDoItem ... {
-
- private boolean complete;
- @Property( editing = Editing.DISABLED )
- public boolean isComplete() {
- return complete;
- }
- public void setComplete(final boolean complete) {
- this.complete = complete;
- }
-
- @Action()
- public ToDoItem completed() {
- setComplete(true);
- ...
- return this;
- }
- public String disableCompleted() {
- return isComplete() ? "Already completed" : null;
- }
- ...
-}
-----
-
-We typically put the bootstrapping of Isis into a superclass (`AbstractToDoIntegTest` below), then subclass as required.
-
-For this test (of the "completed()" action) we need an instance of a `ToDoItem` that is not yet complete. Here's the setup:
-
-[source,java]
-----
-public class ToDoItemIntegTest extends AbstractToDoIntegTest {
-
- @Inject
- FixtureScripts fixtureScripts; // <1>
- @Inject
- ToDoItems toDoItems; // <2>
- ToDoItem toDoItem; // <3>
-
- @Before
- public void setUp() throws Exception {
- RecreateToDoItemsForCurrentUser fixtureScript = // <4>
- new RecreateToDoItemsForCurrentUser();
- fixtureScripts.runFixtureScript(fixtureScript, null);
- final List<ToDoItem> all = toDoItems.notYetComplete(); // <5>
- toDoItem = wrap(all.get(0)); // <6>
- }
- ...
-}
-----
-<1> the xref:_ug_reference-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
-<5> we lookup one of the just-created todo items...
-<6> and then wrap it so that our interactions with it are as if through the UI
-
-
-
-The following code tests the happy case, that a not-yet-completed `ToDoItem` can be completed by invoking the `completed()` action:
-
-[source,java]
-----
-public class ToDoItemIntegTest ... {
- ...
- public static class Completed extends ToDoItemIntegTest { // <1>
- @Test
- public void happyCase() throws Exception {
- // given
- assertThat(toDoItem.isComplete()).isFalse(); // <2>
- // when
- toDoItem.completed();
- // then
- assertThat(toDoItem.isComplete()).isTrue();
- }
- ...
- }
-}
-----
-<1> the idiom we follow is to use nested static classes to identify the class responsibility being tested
-<2> the http://github.com/isisaddons/isis-app-todoapp[todoapp] uses link:http://joel-costigliola.github.io/assertj[AssertJ].
-
-What about when a todo item is already completed? The `disableCompleted()` method in the class says that it shouldn't be allowed (the action would be greyed out in the UI with an appropriate tooltip). The following test verifies this:
-
-[source,java]
-----
- @Test
- public void cannotCompleteIfAlreadyCompleted() throws Exception {
- // given
- unwrap(toDoItem).setComplete(true); // <1>
- // expect
- expectedExceptions.expectMessage("Already completed"); // <2>
- // when
- toDoItem.completed();
- }
-----
-<1> we unwrap the domain object in order to set its state directly
-<2> the expectedExceptions link:http://junit.org/apidocs/org/junit/rules/ExpectedException.html[JUnit rule] (defined by a superclass) verifies that the appropiate exception is indeed thrown (in the "when")
-
-
-And what about the fact that the underlying "complete" property is disabled (the `@Disabled` annotation?). If the `ToDoItem` is put into edit mode in the UI, the complete checkbox should remain read-only. Here's a verify similar test that verifies this also:
-
-[source,java]
-----
- @Test
- public void cannotSetPropertyDirectly() throws Exception {
- // expect
- expectedExceptions.expectMessage("Always disabled"); // <1>
- // when
- toDoItem.setComplete(true);
- }
-----
-<1> again we use the exceptedExceptions rule.
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_wrapper-factory.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_wrapper-factory.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_wrapper-factory.adoc
deleted file mode 100644
index 52cd4a4..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_wrapper-factory.adoc
+++ /dev/null
@@ -1,162 +0,0 @@
-[[_ug_testing_integ-test-support_wrapper-factory]]
-= Wrapper Factory
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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:_ug_reference-services-api_manpage-WrapperFactory[`WrapperFactory`] service is responsible for wrapping a domain object in a dynamic proxy, of the same type as the object being proxied. And the role of this wrapper is to simulate the UI.
-
-[NOTE]
-====
-`WrapperFactory` uses link:http://www.javassist.org[javassist] to perform its magic; this is the same technology that ORMs such as link:http://hibernate.org/[Hibernate] use to manage lazy loading/dirty tracking (DataNucleus uses a different mechanism).
-====
-
-
-
-It does this by allowing through method invocations that would be allowed if the user were interacting with the domain object through one of the viewers, but throwing an exception if the user attempts to interact with the domain object in a way that would not be possible if using the UI.
-
-The mechanics are as follows:
-
-. the integration test calls the `WrapperFactory` to obtain a wrapper for the domain object under test. This is usually done in the test's `setUp()` method.
-
-. the test calls the methods on the wrapper rather than the domain object itself
-
-. the wrapper performs a reverse lookup from the method invoked (a regular `java.lang.reflect.Method` instance) into the Isis metamodel
-
-. (like a viewer), the wrapper then performs the "see it/use it/do it" checks, checking that the member is visible, that it is enabled and (if there are arguments) that the arguments are valid
-
-. if the business rule checks pass, then the underlying member is invoked. Otherwise an exception is thrown.
-
-The type of exception depends upon what sort of check failed. It's straightforward enough: if the member is invisible then a `HiddenException` is thrown; if it's not usable then you'll get a `DisabledException`, if the args are not valid then catch an `InvalidException`.
-
-image::{_imagesdir}testing/wrapper-factory.png[width="600px"]
-
-Let's look in a bit more detail at what the test can do with the wrapper.
-
-
-
-
-
-== Wrapping and Unwrapping
-
-Wrapping a domain object is very straightforward; simply call `WrapperFactory#wrap(...)`.
-
-For example:
-
-[source,java]
-----
-Customer customer = ...;
-Customer wrappedCustomer = wrapperFactory.wrap(wrappedCustomer);
-----
-
-
-Going the other way -- getting hold of the underlying (wrapped) domain object -- is just as easy; just call `WrapperFactory#unwrap(...)`.
-
-For example:
-
-[source,java]
-----
-Customer wrappedCustomer = ...;
-Customer customer = wrapperFactory.unwrap(wrappedCustomer);
-----
-
-If you prefer, you also can get the underlying object from the wrapper itself, by downcasting to `WrappingObject` and calling `__isis_wrapped()` method:
-
-[source,java]
-----
-Customer wrappedCustomer = ...;
-Customer customer = (Customer)((WrappingObject)wrappedCustomer).__isis_wrapped());
-----
-
-We're not sure that's any easier (in fact we're certain it looks rather obscure). Stick with calling `unwrap(...)`!
-
-
-
-
-== Using the wrapper
-
-As the wrapper is intended to simulate the UI, only those methods that correspond to the "primary" methods of the domain object's members are allowed to be called. That means:
-
-* for *_object properties_* the test can call the getter or setter method
-
-* for *_object collections_* the test can call the getter. +
-+
-If there is a supporting `addTo...()` or `removeFrom...()` method, then these can be called. It can also call `add(...)` or `remove(...)` on the collection (returned by the gettter) itself. +
-+
-[NOTE]
-====
-In this respect the wrapper is more functional than the xref:_ug_wicket-viewer[Wicket viewer] (which does not expose the ability to mutate collections directly).
-====
-
-* for *_object actions_* the test can call the action method itself.
-
-As a convenience, we also allow the test to call any `default...()`,`choices...()` or `autoComplete...()` method. These are often useful for obtaining a valid value to use.
-
-What the test can't call is any of the remaining supporting methods, such as `hide...()`, `disable...()` or `validate...()`. That's because their value is implied by the exception being thrown.
-
-The wrapper _does_ also allow the object's `title()` method or its `toString()` , however this is little use for objects whose title is built up using the `@Title` annotation. Instead, we recommend that your test verifies an object's title by calling `DomainObjectContainer#titleOf(...)` method.
-
-
-
-
-
-== Firing Domain Events
-
-As well as enforcing business rules, the wrapper has another important feature, namely that it will cause domain events to be fired.
-
-For example, if we have an action annotated with `@Action(domainEvent=...`):
-
-[source,java]
-----
-public class ToDoItem ... {
- @Action(
- domainEvent =CompletedEvent.class
- )
- public ToDoItem completed() { ... }
- ...
-}
-----
-
-then invoking the action through the proxy will cause the event (`CompletedEvent` above) to be fired to any subscribers. A test might therefore look like:
-
-[source,java]
-----
-@Inject
-private EventBusService eventBusService; // <1>
-
-@Test
-public void subscriberReceivesEvents() throws Exception {
-
- // given
- final ToDoItem.CompletedEvent[] evHolder = new ToDoItem.CompletedEvent[1]; // <2>
- eventBusService.register(new Object() {
- @Subscribe
- public void on(final ToDoItem.CompletedEvent ev) { // <3>
- evHolder[0] = ev;
- }
- });
-
- // when
- toDoItem.completed(); // <4>
-
- // then
- then(evHolder[0].getSource()).isEqualTo(unwrap(toDoItem)); // <5>
- then(evHolder[0].getIdentifier().getMemberName()).isEqualTo("completed");
-}
-----
-<1> inject xref:_ug_reference-services-api_manpage-EventBusService[`EventBusService`] into this test
-<2> holder for subscriber to capture event to
-<3> subscriber's callback, using the guava subscriber syntax
-<4> invoking the domain object using the wrapper
-<5> assert that the event was populated
-
-
-The wrapper will also fire domain events for properties (if annotated with `@Property(domainEvent=...)`) or collections (if annotated with `@Collection(domainEvent=...)`).
-
-
-[NOTE]
-====
-It isn't possible to use the `WrapperFactory` in a unit test, because there needs to be a running instance of Isis that holds the metamodel.
-====
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_unit-test-support.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_unit-test-support.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_unit-test-support.adoc
deleted file mode 100644
index 2cb5ff8..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_unit-test-support.adoc
+++ /dev/null
@@ -1,13 +0,0 @@
-[[_ug_testing_unit-test-support]]
-= Unit Test 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/
-
-Isis Core provides a number of unit test helpers for you to use (if you wish) to unit test your domain objects.
-
-
-include::_ug_testing_unit-test-support_contract-tests.adoc[leveloffset=+1]
-include::_ug_testing_unit-test-support_jmock-extensions.adoc[leveloffset=+1]
-include::_ug_testing_unit-test-support_maven-configuration.adoc[leveloffset=+1]
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_unit-test-support_contract-tests.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_unit-test-support_contract-tests.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_unit-test-support_contract-tests.adoc
deleted file mode 100644
index d30528a..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_unit-test-support_contract-tests.adoc
+++ /dev/null
@@ -1,171 +0,0 @@
-[[_ug_testing_unit-test-support_contract-tests]]
-= Contract Tests
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-
-Contract tests ensure that all instances of a particular idiom/pattern that occur within your codebase are implemented correctly. You could think of them as being a way to enforce a certain type of coding standard. Implementation-wise they use link:https://code.google.com/p/reflections/[Reflections] library to scan for classes.
-
-
-
-== ``SortedSet``s Contract Test
-
-This contract test automatically checks that all fields of type `java.util.Collection` are declared as `java.util.SortedSet`. In other words, it precludes either `java.util.List` or `java.util.Set` from being used as a collection.
-
-For example, the following passes the contract test:
-
-[source,java]
-----
-public class Department {
- private SortedSet<Employee> employees = new TreeSet<Employee>();
- ...
-}
-----
-
-whereas this would not:
-
-[source,java]
-----
-public class SomeDomainObject {
- private List<Employee> employees = new ArrayList<Employee>();
- ...
-}
-----
-
-If using DataNucleus against an RDBMS (as you probably are) then we strongly recommend that you implement this test, for several reasons:
-
-* first, ``Set``s align more closely to the relational model than do `List`s. A `List` must have an additional index to specify order.
-
-* second, `SortedSet` is preferable to `Set` because then the order is well-defined and predictable (to an end user, to the programmer). +
-+
-The <<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.
-
-To use the contract test, subclass `SortedSetsContractTestAbstract`, specifying the root package to search for domain classes.
-
-For example:
-
-[source,java]
-----
-public class SortedSetsContractTestAll extends SortedSetsContractTestAbstract {
-
- public SortedSetsContractTestAll() {
- super("org.estatio.dom");
- withLoggingTo(System.out);
- }
-}
-----
-
-
-
-== Bidirectional Contract Test
-
-This contract test automatically checks that bidirectional 1:m or 1:1 associations are being maintained correctly (assuming that they follow the xref:_ug_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_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships[here]. Also check out the xref:_ug_appendices_dev-env[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`).
-
-The following will exercise these relationships:
-
-[source,java]
-----
-public class BidirectionalRelationshipContractTestAll
- extends BidirectionalRelationshipContractTestAbstract {
-
- public BidirectionalRelationshipContractTestAll() {
- super("org.apache.isis.core.unittestsupport.bidir",
- ImmutableMap.<Class<?>,Instantiator>of(
- ChildDomainObject.class, new InstantiatorForChildDomainObject(),
- PeerDomainObject.class, new InstantiatorSimple(PeerDomainObjectForTesting.class)
- ));
- withLoggingTo(System.out);
- }
-}
-----
-
-The first argument to the constructor scopes the search for domain objects; usually this would be something like `"com.mycompany.dom"`.
-
-The second argument provides a map of `Instantiator` for certain of the domain object types. This has two main purposes. First, for abstract classes, it nominates an alternative concrete class to be instantiated. Second, for classes (such as `ChildDomainObject`) that are `Comparable` and are held in a `SortedSet`), it provides the ability to ensure that different instances are unique when compared against each other. If no `Instantiator` is provided, then the contract test simply attempts to instantiates the class.
-
-If any of the supporting methods (`addToXxx()`, `removeFromXxx()`, `modifyXxx()` or `clearXxx()`) are missing, the relationship is skipped.
-
-To see what's going on (and to identify any skipped relationships), use the `withLoggingTo()` method call. If any assertion fails then the error should be descriptive enough to figure out the problem (without enabling logging).
-
-The example tests can be found https://github.com/apache/isis/tree/master/core/unittestsupport/src/test/java/org/apache/isis/core/unittestsupport/bidir[here].
-
-
-
-== Injected Services Method Contract Test
-
-It is quite common for some basic services to be injected in a project-specific domain object superclass; for example a `ClockService` might generally be injected everywhere:
-
-[source,java]
-----
-public abstract class EstatioDomainObject {
- @javax.inject.Inject
- protected ClockService clockService;
-}
-----
-
-If a subclass inadvertantly overrides this method and provides its own `ClockService` field, then the field in the superclass will never initialized. As you might imagine, ``NullPointerException``s could then arise.
-
-This contract test automatically checks that the `injectXxx(...)` method, to allow for injected services, is not overridable, ie `final`.
-
-[NOTE]
-====
-This contract test is semi-obsolete; most of the time you will want to use `@javax.inject.Inject` on fields rather than the `injectXxx()` method. The feature dates from a time before Isis supported the `@Inject` annotation.
-====
-
-
-To use the contract test, , subclass `SortedSetsContractTestAbstract`, specifying the root package to search for domain classes.
-
-For example:
-
-[source,java]
-----
-public class InjectServiceMethodMustBeFinalContractTestAll extends InjectServiceMethodMustBeFinalContractTestAbstract {
-
- public InjectServiceMethodMustBeFinalContractTestAll() {
- super("org.estatio.dom");
- withLoggingTo(System.out);
- }
-}
-----
-
-
-
-
-== Value Objects Contract Test
-
-The `ValueTypeContractTestAbstract` automatically tests that a custom value type implements `equals()` and `hashCode()` correctly.
-
-For example, testing JDK's own `java.math.BigInteger` can be done as follows:
-
-[source,java]
-----
-public class ValueTypeContractTestAbstract_BigIntegerTest extends ValueTypeContractTestAbstract<BigInteger> {
-
- @Override
- protected List<BigInteger> getObjectsWithSameValue() {
- return Arrays.asList(new BigInteger("1"), new BigInteger("1"));
- }
-
- @Override
- protected List<BigInteger> getObjectsWithDifferentValue() {
- return Arrays.asList(new BigInteger("2"));
- }
-}
-----
-
-The example unit tests can be found https://github.com/apache/isis/tree/master/core/unittestsupport/src/test/java/org/apache/isis/core/unittestsupport/value[here].
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_unit-test-support_jmock-extensions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_unit-test-support_jmock-extensions.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_unit-test-support_jmock-extensions.adoc
deleted file mode 100644
index 4bf309f..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_unit-test-support_jmock-extensions.adoc
+++ /dev/null
@@ -1,59 +0,0 @@
-[[_ug_testing_unit-test-support_jmock-extensions]]
-= JMock Extensions
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 noted earlier, for unit tests we tend to use link:http://www.jmock.org[JMock] as our mocking library. The usual given/when/then format gets an extra step:
-
-* *given* the system is in this state
-* *expecting* these interactions (set up the mock expectations here)
-* *when* I poke it with a stick
-* *then* these state changes and interactions with Mocks should have occurred.
-
-If using JMock then the interactions (in the "then") are checked automatically by a JUnit rule. However, you probably will still have some state changes to assert upon.
-
-[TIP]
-.Distinguish between queries vs mutators
-====
-For mock interactions that simply retrieve some data, your test should not need to verify that it occurred. If the system were to be refactored and starts caching some data, you don't really want your tests to start breaking because they are no longer performing a query that once they did. If using JMock API this means using the `allowing(..)` method to set up the expectation.
-
-On the other hand mocks that mutate the state of the system you probably should assert have occurred. If using JMock this typically means using the `oneOf(...)` method.
-
-For more tips on using JMock and mocking in general, check out the link:http://www.growing-object-oriented-software.com/[GOOS] book, written by JMock's authors, Steve Freeman and Nat Pryce and also link:http://natpryce.com/articles.html[Nat's blog].
-====
-
-Apache Isis' unit test support provides `JUnitRuleMockery2` which is an extension to the link:http://www.jmock.org/[JMock]'s `JunitRuleMockery`. It provides a simpler API and also providing support for autowiring.
-
-
-For example, here we see that the class under test, an instance of `CollaboratingUsingSetterInjection`, is automatically wired up with its `Collaborator`:
-
-[source,java]
-----
-public class JUnitRuleMockery2Test_autoWiring_setterInjection_happyCase {
-
- @Rule
- public JUnitRuleMockery2 context = JUnitRuleMockery2.createFor(Mode.INTERFACES_AND_CLASSES);
-
- @Mock
- private Collaborator collaborator;
-
- @ClassUnderTest
- private CollaboratingUsingSetterInjection collaborating;
-
- @Test
- public void wiring() {
- assertThat(collaborating.collaborator, is(not(nullValue())));
- }
-}
-----
-
-[NOTE]
-====
-Isis also includes (and automatically uses) a link:http://www.javassist.org[Javassist]-based implementation of JMock's link:http://www.jmock.org/mocking-classes.html[`ClassImposteriser`] interface, so that you can mock out concrete classes as well as interfaces. We've provided this rather than JMock's own cglib-based implementation (which is problematic for us given its own dependencies on link:http://asm.ow2.org/[asm]).
-====
-
-
-The example tests can be found https://github.com/apache/isis/tree/master/core/unittestsupport/src/test/java/org/apache/isis/core/unittestsupport/jmocking[here]
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_unit-test-support_maven-configuration.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_unit-test-support_maven-configuration.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_unit-test-support_maven-configuration.adoc
deleted file mode 100644
index 928a9b1..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_unit-test-support_maven-configuration.adoc
+++ /dev/null
@@ -1,46 +0,0 @@
-[[_ug_testing_unit-test-support_maven-configuration]]
-= Maven Configuration
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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' unit test support is automatically configured if you use the xref:_ug_getting-started_simpleapp-archetype[SimpleApp archetype]. To set it up manually, update the `pom.xml` of your domain object model module:
-
-[source,xml]
-----
-<dependency>
- <groupId>org.apache.isis.core</groupId>
- <artifactId>isis-core-unittestsupport</artifactId>
- <scope>test</scope> // <1>
-</dependency>
-----
-<1> Normally `test`; usual Maven scoping rules apply.
-
-
-
-We also recommend that you configure the `maven-surefire-plugin` to pick up the following class patterns:
-
-[source,xml]
-----
-<plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-surefire-plugin</artifactId>
- <version>2.10</version>
- <configuration>
- <includes>
- <include>**/*Test.java</include>
- <include>**/*Test_*.java</include>
- <include>**/*Spec*.java</include>
- </includes>
- <excludes>
- <exclude>**/Test*.java</exclude>
- <exclude>**/*ForTesting.java</exclude>
- <exclude>**/*Abstract*.java</exclude>
- </excludes>
- <useFile>true</useFile>
- <printSummary>true</printSummary>
- <outputDirectory>${project.build.directory}/surefire-reports</outputDirectory>
- </configuration>
-</plugin>
-----
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_troubleshooting.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_troubleshooting.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_troubleshooting.adoc
deleted file mode 100644
index 39384d2..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_troubleshooting.adoc
+++ /dev/null
@@ -1,14 +0,0 @@
-[[_ug_troubleshooting]]
-= Troubleshooting
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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
-
-## Logging
-
-include::_ug_troubleshooting_enabling-logging.adoc[leveloffset=+1]
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_troubleshooting_enabling-logging.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_troubleshooting_enabling-logging.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_troubleshooting_enabling-logging.adoc
deleted file mode 100644
index 414dc7d..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_troubleshooting_enabling-logging.adoc
+++ /dev/null
@@ -1,39 +0,0 @@
-[[_ug_troubleshooting_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_getting-started_simpleapp-archetype[SimpleApp archetype].
-
-== In the Database
-
-=== HSQLDB Logging
-
-Add `;sqllog=3` to the end of the JDBC URL.
-
-=== PostgreSQL Logging
-
-In `postgresql\9.2\data\postgresql.conf`:
-
-Will then log to `postgresql\9.2\data\pg_log` directory.
-
-Note that you must restart the service for this to be picked up.
-
-=== MS SQL Server Logging
-
-Use the excellent SQL Profiler tool.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_tutorials.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_tutorials.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_tutorials.adoc
deleted file mode 100644
index a4045ce..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_tutorials.adoc
+++ /dev/null
@@ -1,18 +0,0 @@
-[[_ug_tutorials]]
-= Tutorials
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 contains a couple of tutorials for you to follow.
-
-* the "petclinic" tutorial takes you step-by-step through building a simple application of just three classes. There are example solutions in the github repo in case you get lost.
-
-* the "stop scaffolding, start coding" tutorial is taken from a conference workshop. It has less hand-holding, but lists out the steps for you to follow. It's a good cookbook to follow when you're readng to take things further.
-
-Have fun!
-
-include::_ug_tutorials_pet-clinic.adoc[leveloffset=+1]
-include::_ug_tutorials_stop-scaffolding-start-coding.adoc[leveloffset=+1]
[22/45] isis git commit: ISIS-1133: breaking out reference guide and
devenv guide;
moving appendices' release notes and migration notes to other docs;
improving the documentation page.
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_dev-env_eclipse.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_dev-env_eclipse.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_dev-env_eclipse.adoc
deleted file mode 100644
index 7c26664..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_dev-env_eclipse.adoc
+++ /dev/null
@@ -1,136 +0,0 @@
-[[_ug_appendices_dev-env_eclipse]]
-= Setting up Eclipse
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../../../
-:_imagesdir: images/
-:toc: right
-
-
-We highly recommend that you develop your Isis application using an IDE. Isis is built with Maven, and all modern IDEs can import Maven projects.
-
-If you are an http://www.eclipse.org[Eclipse] user, then we recommend you download the "Eclipse JEE package" configuration.
-
-When running an Isis application, it's necessary to setup the development environment so that the Java bytecode can be enhanced by the link:http://www.datanucleus.org[DataNucleus] enhancer. If working in Eclipse, then JDO enhancement is most easily done by installing the http://www.datanucleus.org/products/datanucleus/jdo/guides/eclipse.html[DataNucleus' Eclipse plugin]. This hooks the bytecode enhancement of your domain objects into Eclipse's normal incremental compilation.
-
-This plugin needs to be configured for each of your domain modules (usually just one in any given app). The steps are therefore:
-
-* import the project into Eclipse
-* configure the DataNucleus enhancer
-* run the app from the `.launch` file
-
-
-
-
-== Screencast
-
-The following screencast shows how to import an Apache Isis maven-based application into Eclipse and configure to use with the JDO Objectstore
-
-video::RgcYfjQ8yJA[youtube,width="640px",height="480px"]
-
-
-
-
-== Importing the Project
-
-Use File > Import, then Maven > Existing Maven Projects.
-
-
-
-
-== Add DataNucleus support
-
-[TIP]
-====
-Make sure you are in the 'Java' Perspective, not the 'Java EE' Perspective.
-====
-
-
-In Eclipse, for the _domain object model_ project, first add DataNucleus support:
-
-image::{_imagesdir}appendices/dev-env/eclipse/eclipse-100-project-support.png[width="600px",link="{_imagesdir}appendices/dev-env/eclipse/eclipse-100-project-support.png"]
-
-
-Then turn on Auto-Enhancement:
-
-image::{_imagesdir}appendices/dev-env/eclipse/eclipse-110-project-support.png[width="600px",link="{_imagesdir}appendices/dev-env/eclipse/eclipse-110-project-support.png"]
-
-
-=== Update the classpath
-
-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_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_getting-started_simpleapp-archetype[SimpleApp archetype].
-
-
-Then, tell DataNucleus to use the project classpath:
-
-
-image::{_imagesdir}/appendices/dev-env/eclipse/eclipse-010-windows-preferences.png[width="750px",link="{_imagesdir}/appendices/dev-env/eclipse/eclipse-010-windows-preferences.png"]
-
-When the enhancer runs, it will print out to the console:
-
-image::{_imagesdir}/appendices/dev-env/eclipse/eclipse-120-console.png[width="500px",link="{_imagesdir}/appendices/dev-env/eclipse/eclipse-120-console.png"]
-
-
-
-=== Workaround for path limits (the DN plugin to use the persistence.xml)
-
-If running on Windows then the DataNucleus plugin is very likely to hit the Windows path limit.
-
-To fix this, we configure the enhancer to read from the `persistence.xml` file.
-
-As a prerequisite, first make sure that your domain object model has a `persistence.xml` file. Then specify the `persistence-unit` in the project properties:
-
-image::{_imagesdir}/appendices/dev-env/eclipse/eclipse-025-project-properties.png[width="750px",link="{_imagesdir}/appendices/dev-env/eclipse/eclipse-025-project-properties.png"]
-
-
-=== Workaround: If the enhancer fails
-
-On occasion it appears that Eclipse can attempt to run two instances of the DataNucleus enhancer. This is probably due to multiple Eclipse builders being defined; we've noticed multiple entries in the Eclipse's `Debug` view:
-
-
-image::{_imagesdir}/appendices/dev-env/eclipse/eclipse-210-enhancer-fails-duplicates.png[width="600px",link="{_imagesdir}/appendices/dev-env/eclipse/eclipse-210-enhancer-fails-duplicates.png"]
-
-
-At any rate, you'll know you've encountered this error if you see the following in the console:
-
-
-image::{_imagesdir}/appendices/dev-env/eclipse/eclipse-200-enhancer-fails-duplicates.png[width="600px",link="{_imagesdir}/appendices/dev-env/eclipse/eclipse-200-enhancer-fails-duplicates.png"]
-
-
-
-The best solution is to remove DataNucleus support and then to re-add it:
-
-
-image::{_imagesdir}/appendices/dev-env/eclipse/eclipse-220-enhancer-fails-duplicates.png[width="600px",link="{_imagesdir}/appendices/dev-env/eclipse/eclipse-220-enhancer-fails-duplicates.png"]
-
-
-If you consistently hit problems, then the final recourse is to disable the automatic enhancement and to remember to manually enhance your domain object model before each run.
-
-Not ideal, we know. Please feel free to contribute a better solution :-)
-
-
-
-
-== Running the App
-
-The simpleapp archetype automatically provides a `.launch` configurations in the `webapp` module. You can therefore very simply run the application by right-clicking on one of these files, and choosing "Run As…" or "Debug As…".
-
-
-[NOTE]
-====
-The screencast above shows this in action.
-====
-
-
-
-
-
-== Other domain projects.
-
-There is nothing to prevent you having multiple domain projects. You might want to do such that each domain project corresponds to a http://www.methodsandtools.com/archive/archive.php?id=97p2[DDD module], thus guaranteeing that there are no cyclic dependencies between your modules.
-
-If you do this, make sure that each project has its own `persistence.xml` file.
-
-And, remember also to configure Eclipse's DataNucleus plugin for these other domain projects.
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_dev-env_intellij.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_dev-env_intellij.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_dev-env_intellij.adoc
deleted file mode 100644
index 42e3030..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_dev-env_intellij.adoc
+++ /dev/null
@@ -1,374 +0,0 @@
-[[_ug_appendices_dev-env_intellij]]
-= Setting up IntelliJ IDEA
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../../../
-:_imagesdir: images/
-:toc: right
-
-
-This appendix describes how to install and setup IntelliJ, then how to import an application into IntelliJ and run it.
-
-
-[NOTE]
-====
-This document relates to IntelliJ Community Edition 14.1.1, with screenshots taken for Windows.
-====
-
-== Installing and Setting up
-
-This section covers installation and setup.
-
-=== Download and Install
-
-https://www.jetbrains.com/idea/download/[Download] latest version of IntelliJ Community Edition, and install:
-
-Start the wizard, click through the welcome page:
-
-.IntelliJ Installation Wizard - Welcome page
-image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/010-welcome-page.png[width="400px"]
-
-Choose the location to install the IDE:
-
-.IntelliJ Installation Wizard - Choose Location
-image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/020-choose-location.png[width="400px"]
-
-Adjust any installation options as you prefer:
-
-.IntelliJ Installation Wizard - Installation Options
-image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/030-installation-options.png[width="400px"]
-
-and the start menu:
-
-.IntelliJ Installation Wizard - Start Menu Folder
-image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/040-start-menu-folder.png[width="400px"]
-
-and finish up the wizard:
-
-.IntelliJ Installation Wizard - Completing the Wizard
-image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/050-completing.png[width="400px"]
-
-Later on we'll specify the Apache Isis/ASF code style settings, so for now select `I do not want to import settings`:
-
-.IntelliJ Installation Wizard - Import Settings
-image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/060-import-settings-or-not.png[width="400px"]
-
-Finally, if you are young and trendy, set the UI theme to Darcula:
-
-.IntelliJ Installation Wizard Set UI Theme
-image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/070-set-ui-theme.png[width="600px"]
-
-
-
-
-=== New Project
-
-In IntelliJ a project can contain multiple modules; these need not be physically located together. (If you are previously an Eclipse user, you can think of it as similar to an Eclipse workspace).
-
-Start off by creating a new project:
-
-.IntelliJ Create New Project
-image::{_imagesdir}appendices/dev-env/intellij-idea/020-create-new-project/010-new-project-create.png[width="400px"]
-
-We want to create a new *Java* project:
-
-.IntelliJ Create New Project - Create a Java project
-image::{_imagesdir}appendices/dev-env/intellij-idea/020-create-new-project/020-java-project-setup-jdk.png[width="600px"]
-
-We therefore need to specify the JDK.
-
-NOTE: at the time of writing Isis supports only Java 7; Java 8 is scheduled for support in Isis v1.9.0
-
-
-.IntelliJ Create New Java Project - Select the JDK
-image::{_imagesdir}appendices/dev-env/intellij-idea/020-create-new-project/030-java-project-select-jdk.png[width="300px"]
-
-Specify the directory containing the JDK:
-
-.IntelliJ Create New Project - Select the JDK location
-image::{_imagesdir}appendices/dev-env/intellij-idea/020-create-new-project/050-name-and-location.png[width="400px"]
-
-Finally allow IntelliJ to create the directory for the new project:
-
-.IntelliJ Create New Project
-image::{_imagesdir}appendices/dev-env/intellij-idea/020-create-new-project/060-create-dir.png[width="200px"]
-
-
-
-=== Import Settings
-
-Next we need to configure IntelliJ with ASF/Apache Isis' standard templates and coding conventions. These are bundled as the `settings.jar` JAR file link:resources/appendices/dev-env/intellij/isis-settings.jar[download from the Isis website]).
-
-Import using: `File > Import Settings`, and specify the directory that you have downloaded the file to:
-
-.IntelliJ Import Settings - Specify JAR file
-image::{_imagesdir}appendices/dev-env/intellij-idea/030-import-settings/010-settings-import-jar.png[width="400px"]
-
-Select all the (two) categories of settings available in the JAR file:
-
-.IntelliJ Import Settings - Select all categories
-image::{_imagesdir}appendices/dev-env/intellij-idea/030-import-settings/020-select-all.png[width="300px"]
-
-And then restart:
-
-.IntelliJ Import Settings - Restart
-image::{_imagesdir}appendices/dev-env/intellij-idea/030-import-settings/030-restart.png[width="200px"]
-
-
-
-=== Other Settings
-
-There are also some other miscellaneous settings that we recommend that you adjust (though these are not critical).
-
-First, specify an up-to-date Maven installation, using `File > Settings` (or `IntelliJ > Preferences` if on MacOS):
-
-.IntelliJ Other Settings - Maven Installation
-image::{_imagesdir}appendices/dev-env/intellij-idea/040-other-settings/010-maven-installation.png[width="600px"]
-
-Still on the Maven settings page, configure as follows:
-
-.IntelliJ Other Settings - Maven Configuration
-image::{_imagesdir}appendices/dev-env/intellij-idea/040-other-settings/020-maven-configuration.png[width="600px"]
-
-On the compiler settings page, ensure that `build automatically` is enabled (and optionally `compile independent modules in parallel`):
-
-.IntelliJ Other Settings - Compiler Settings
-image::{_imagesdir}appendices/dev-env/intellij-idea/040-other-settings/030-build-automatically.png[width="600px"]
-
-On the auto import page, check the `optimize imports on the fly` and `add unambiguous imports on the fly`
-
-.IntelliJ Other Settings - Auto Import
-image::{_imagesdir}appendices/dev-env/intellij-idea/040-other-settings/040-auto-import.png[width="600px"]
-
-
-
-=== Plugins
-
-You might also want to set up some additional plugins, using `File > Settings > Plugins` (or equivalently `File > Other Settings > Configure Plugins`).
-
-Recommended are:
-* link:https://plugins.jetbrains.com/plugin/7179?pr=idea[Maven Helper] plugin
-+
-Provides better visualization of dependency trees (similar to Eclipse)
-* link:https://github.com/asciidoctor/asciidoctor-intellij-plugin[AsciiDoctor] plugin
-+
-Useful if you are doing any authoring of documents.
-
-Some others you might like to explore are:
-
-.IntelliJ Plugins
-image::{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/020-some-plugins-confirmation.png[width="400px"]
-
-
-
-
-== Importing and Managing Maven Modules
-
-Let's load in some actual code! We do this by importing the Maven modules.
-
-First up, open up the Maven tool window (`View > Tool Windows > Maven Projects`). You can then use the 'plus' button to add Maven modules. In the screenshot you can see we've loaded in Isis core; the modules are listed in the _Maven Projects_ window and corresponding (IntelliJ) modules are shown in the _Projects_ window:
-
-.IntelliJ Maven Module Management - Importing Maven modules
-image::{_imagesdir}appendices/dev-env/intellij-idea/100-maven-module-mgmt/010-maven-modules-view.png[width="730px"]
-
-We can then import another module (from some other directory). For example, here we are importing the Isis Addons' todoapp example:
-
-.IntelliJ Maven Module Management - Importing another Module
-image::{_imagesdir}appendices/dev-env/intellij-idea/100-maven-module-mgmt/020-adding-another-module.png[width="400px"]
-
-You should then see the new Maven module loaded in the _Projects_ window and also the _Maven Projects_ window:
-
-.IntelliJ Maven Module Management -
-image::{_imagesdir}appendices/dev-env/intellij-idea/100-maven-module-mgmt/030-other-module-added.png[width="730px"]
-
-If any dependencies are already loaded in the project, then IntelliJ will automatically update the CLASSPATH to resolve to locally held modules (rather from `.m2/repository` folder). So, for example (assuming that the `<version>` is correct, of course), the Isis todoapp will have local dependencies on the Isis core.
-
-You can press F4 (or use `File > Project Structure`) to see the resolved classpath for any of the modules loaded into the project.
-
-If you want to focus on one set of code (eg the Isis todoapp but not Isis core) then you _could_ remove the module; but better is to ignore those modules. This will remove from the the _Projects_ window but keep them available in the _Maven Projects_ window for when you next want to work on them:
-
-.IntelliJ Maven Module Management - Ignoring Modules
-image::{_imagesdir}appendices/dev-env/intellij-idea/100-maven-module-mgmt/040-ignoring-modules.png[width="730px"]
-
-Confirm that it's ok to ignore these modules:
-
-.IntelliJ Maven Module Management - Ignoring Modules (ctd)
-image::{_imagesdir}appendices/dev-env/intellij-idea/100-maven-module-mgmt/050-ignoring-modules-2.png[width="300px"]
-
-All being well you should see that the _Projects_ window now only contains the code you are working on. Its classpath dependencies will be adjusted (eg to resolve to Isis core from `.m2/repository`):
-
-.IntelliJ Maven Module Management - Updated Projects Window
-image::{_imagesdir}appendices/dev-env/intellij-idea/100-maven-module-mgmt/060-ignored-modules.png[width="730px"]
-
-
-
-== Running
-
-Let's see how to run both the app and the tests.
-
-=== Running the App
-
-Once you've imported your Isis application, we should run it. We do this by creating a Run configuration, using `Run > Edit Configurations`.
-
-Set up the details as follows:
-
-.IntelliJ Running the App - Run Configuration
-image::{_imagesdir}appendices/dev-env/intellij-idea/110-running-the-app/010-run-configuration.png[width="600px"]
-
-We specify the `Main class` to be `org.apache.isis.WebServer`; this is a wrapper around Jetty. It's possible to pass program arguments to this (eg to automatically install fixtures), but for now leave this blank.
-
-Also note that `Use classpath of module` is the webapp module for your app, and that the `working directory` is `$MODULE_DIR$`.
-
-Next, and most importantly, configure the DataNucleus enhancer to run for your `dom` goal. This can be done by defining a Maven goal to run before the app:
-
-.IntelliJ Running the App - Datanucleus Enhancer Goal
-image::{_imagesdir}appendices/dev-env/intellij-idea/110-running-the-app/020-datanucleus-enhancer-goal.png[width="400px"]
-
-The `-o` flag in the goal means run off-line; this will run faster.
-
-WARNING: if you forget to set up the enhancer goal, or don't run it on the correct (dom) module, then you will get all sorts of errors when you startup. These usually manifest themselves as class cast exception in DataNucleus.
-
-You should now be able to run the app using `Run > Run Configuration`. The same configuration can also be used to debug the app if you so need.
-
-
-=== Running the Unit Tests
-
-The easiest way to run the unit tests is just to right click on the `dom` module in the _Project Window_, and choose run unit tests. Hopefully your tests will pass (!).
-
-.IntelliJ Running the App - Unit Tests Run Configuration
-image::{_imagesdir}appendices/dev-env/intellij-idea/110-running-the-app/030-running-unit-tests.png[width="600px"]
-
-As a side-effect, this will create a run configuration, very similar to the one we manually created for the main app:
-
-.IntelliJ Running the App - Unit Tests Run Configuration
-image::{_imagesdir}appendices/dev-env/intellij-idea/110-running-the-app/040-running-unit-tests-run-configuration.png[width="600px"]
-
-Thereafter, you should run units by selecting this configuration (if you use the right click approach you'll end up with lots of run configurations, all similar).
-
-=== Running the Integration Tests
-
-Integration tests can be run in the same way as unit tests, however the `dom` module must also have been enhanced.
-
-One approach is to initially run the tests use the right click on the `integtests` module; the tests will fail because the code won't have been enhanced, but we can then go and update the run configuration to run the datanucleus enhancer goal (same as when running the application):
-
-.IntelliJ Running the App - Integration Tests Run Configuration
-image::{_imagesdir}appendices/dev-env/intellij-idea/110-running-the-app/050-running-integration-tests-run-configuration.png[width="600px"]
-
-
-
-
-== Hints and Tips
-
-=== Keyboard Shortcuts Cheat Sheets
-
-You can download 1-page PDFs cheat sheets for IntelliJ's keyboard shortcuts:
-* for link:https://www.jetbrains.com/idea/docs/IntelliJIDEA_ReferenceCard.pdf[Windows]
-* for MacOS:https://www.jetbrains.com/idea/docs/IntelliJIDEA_ReferenceCard_Mac.pdf[MacOS]
-
-Probably the most important shortcut on them is for `Find Action`:
-- `ctrl-shift-A` on Windows
-- `cmd-shift-A` on MacOS.
-
-This will let you search for any action just by typing its name.
-
-### Switching between Tool Windows and Editors
-
-The Tool Windows are the views around the editor (to left, bottom and right). It's possible to move these around to your preferred locations.
-
-* Use `alt-1` through `alt-9` (or `cmd-1` through `alt-9`) to select the tool windows
-** Press it twice and the tool window will hide itself; so can use to toggle
-* If in the _Project Window_ (say) and hit enter on a file, then it will be shown in the editor, but (conveniently) the focus remains in the tool window. To switch to the editor, just press `Esc`.
-** If in the _Terminal Window_, you'll need to press `Shift-Esc`.
-* If on the editor and want to locate the file in (say) the _Project Window_, use `alt-F1`.
-* To change the size of any tool window, use `ctrl-shift-arrow`
-
-Using these shortcuts you can easily toggle between the tool windows and the editor, without using the mouse. Peachy!
-
-=== Navigating Around
-
-For all of the following, you don't need to type every letter, typing "ab" will actually search for ".*a.*b.*".
-
-* to open classes or files or methods that you know the name of:
-** `ctrl-N` to open class
-** `ctrl-shift-N` to open a file
-** (bit fiddly this) `ctrl-shift-alt-N` to search for any symbol.
-* open up dialog of recent files: `ctrl-E`
-* search for any file: `shift-shift`
-
-Navigating around:
-* find callers of a method (the call hierarchy): `ctrl-alt-H`
-* find subclasses or overrides: `ctrl-alt-B`
-* find superclasses/interface/declaration: `ctrl-B`
-
-Viewing the structure (ie outline) of a class
-* `ctrl-F12` will pop-up a dialog showing all members
-** hit `ctrl-F12` again to also see inherited members
-
-
-=== Editing
-
-* Extend selection using `ctrl-W`
-** and contract it down again using `ctrl-shift-W`
-* to duplicate a line, it's `ctrl-D`
-** if you have some text selected (or even some lines), it'll actually duplicate the entire selection
-* to delete a line, it's `ctrl-X`
-* to move a line up or down: `shift-alt-up` and `shift-alt-down`
-** if you have selected several lines, it'll move them all togethe
-* `ctrl-shift-J` can be handy for joining lines together
-** just hit enter to split them apart (even in string quotes; IntelliJ will "do the right thing")
-
-### Intentions and Code Completion
-
-Massively useful is the "Intentions" popup; IntelliJ tries to guess what you might want to do. You can activate this using`alt-enter`, whenever you see a lightbulb/tooltip in the margin of the current line.
-
-Code completion usually happens whenever you type '.'. You can also use `ctrl-space` to bring these up.
-
-In certain circumstances (eg in methods0) you can also type `ctrl-shift-space` to get a smart list of methods etc that you might want to call. Can be useful.
-
-Last, when invoking a method, use `ctrl-P` to see the parameter types.
-
-
-=== Refactoring
-
-Loads of good stuff on the `Refactor` menu; most used are:
-
-* Rename (`shift-F6`)
-* Extract
-** method: `ctrl-alt-M`
-** variable: `ctrl-alt-V`
-* Inline method/variable: `ctrl-alt-N`
-* Change signature
-
-If you can't remember all those shortcuts, just use `ctrl-shift-alt-T` (might want to rebind that to something else!) and get a context-sensitive list of refactorings available for the currently selected object
-
-
-=== Troubleshooting
-
-When a Maven module is imported, IntelliJ generates its own project files (suffix `.ipr`), and the application is actually built from that.
-
-Occasionally these don't keep in sync (even if auto-import of Maven modules has been enabled).
-
-To fix the issue, try:
-* reimport module
-* rebuild selected modules/entire project
-* remove and then re-add the project
-* restart, invalidating caches
-* hit StackOverflow (!)
-
-One thing worth knowing; IntelliJ actively scans the filesystem all the time. It's therefore (almost always) fine to build the app from the Maven command line; IntelliJ will detect the changes and keep in sync. If you want to force that, use `File > Synchronize`, `ctrl-alt-Y`.
-
-
-
-
-== Advanced
-
-In this section are a couple of options that will reduce the length of the change code/build/deploy/review feedback loop.
-
-
-=== Setting up Dynamic Reloading
-
-IMPORTANT: TODO - see link:http://blog.jetbrains.com/idea/2013/07/get-true-hot-swap-in-java-with-dcevm-and-intellij-idea/[IntelliJ blog].
-
-
-=== Setting up JRebel
-
-IMPORTANT: TODO
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_migration-notes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_migration-notes.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_migration-notes.adoc
deleted file mode 100644
index d8a5d0d..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_migration-notes.adoc
+++ /dev/null
@@ -1,563 +0,0 @@
-[[_ug_appendices_migration-notes]]
-= Migration Notes
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-== Upgrading to DataNucleus 4 (in 1.9.0-SNAPSHOT)
-
-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 <<SimpleApp archetype>>; its Maven configuration has been updated.
-
-If you have an existing Isis app that you want to upgrade, then you'll need to make some changes.
-
-
-
-=== In the parent `pom.xml`
-
-under the `<project>/<properties>`, remove:
-
-[source,xml]
-----
-<!-- must be consistent with the versions defined by the JDO Objectstore -->
-<datanucleus-accessplatform-jdo-rdbms.version>3.3.6</datanucleus-accessplatform-jdo-rdbms.version>
-<datanucleus-maven-plugin.version>3.3.2</datanucleus-maven-plugin.version>
-----
-
-
-=== In `dom/pom.xml`,
-
-under `<build>/<plugins>`, remove:
-
-[source,xml]
-----
-<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>compile</phase>
- <goals>
- <goal>enhance</goal>
- </goals>
- </execution>
- </executions>
-</plugin>
-----
-
-and (if you have it) under `<build>/<pluginManagement>/<plugins>`, remove:
-
-[source,xml]
-----
-<!--This plugin's configuration is used to store Eclipse m2e settings only. It has no influence on the Maven build itself.-->
-<plugin>
- <groupId>org.eclipse.m2e</groupId>
- <artifactId>lifecycle-mapping</artifactId>
- <version>1.0.0</version>
- <configuration>
- <lifecycleMappingMetadata>
- <pluginExecutions>
- <pluginExecution>
- <pluginExecutionFilter>
- <groupId>
- org.datanucleus
- </groupId>
- <artifactId>
- datanucleus-maven-plugin
- </artifactId>
- <versionRange>
- [3.2.0-release,)
- </versionRange>
- <goals>
- <goal>enhance</goal>
- </goals>
- </pluginExecutionFilter>
- <action>
- <ignore></ignore>
- </action>
- </pluginExecution>
- </pluginExecutions>
- </lifecycleMappingMetadata>
- </configuration>
-</plugin>
-----
-
-
-and instead in `<profiles>` add:
-
-
-[source,xml]
-----
-<profile>
- <id>enhance</id>
- <activation>
- <activeByDefault>true</activeByDefault>
- </activation>
- <properties>
- <datanucleus-maven-plugin.version>4.0.0-release</datanucleus-maven-plugin.version>
- </properties>
- <build>
- <pluginManagement>
- <plugins>
- <plugin>
- <!--This plugin's configuration is used to store Eclipse m2e settings only. It has no influence on the Maven build itself.-->
- <groupId>org.eclipse.m2e</groupId>
- <artifactId>lifecycle-mapping</artifactId>
- <version>1.0.0</version>
- <configuration>
- <lifecycleMappingMetadata>
- <pluginExecutions>
- <pluginExecution>
- <pluginExecutionFilter>
- <groupId>org.datanucleus</groupId>
- <artifactId>datanucleus-maven-plugin</artifactId>
- <versionRange>[${datanucleus-maven-plugin.version},)</versionRange>
- <goals>
- <goal>enhance</goal>
- </goals>
- </pluginExecutionFilter>
- <action>
- <ignore></ignore>
- </action>
- </pluginExecution>
- </pluginExecutions>
- </lifecycleMappingMetadata>
- </configuration>
- </plugin>
- </plugins>
- </pluginManagement>
- <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>
-----
-
-If you don't use Eclipse then you can omit the `org.eclipse.m2e` plugin in `<pluginManagement>`.
-
-
-
-
-=== In the webapp's `persistor_datanucleus.properties`
-
-in `src/main/webapp/WEB-INF/`,
-
-change:
-
-[source,ini]
-----
-isis.persistor.datanucleus.impl.datanucleus.autoCreateSchema=true
-isis.persistor.datanucleus.impl.datanucleus.validateTables=true
-isis.persistor.datanucleus.impl.datanucleus.validateConstraints=true
-----
-
-to:
-
-[source,ini]
-----
-isis.persistor.datanucleus.impl.datanucleus.schema.autoCreateAll=true
-isis.persistor.datanucleus.impl.datanucleus.schema.validateTables=true
-isis.persistor.datanucleus.impl.datanucleus.schema.validateConstraints=true
-----
-
-and change:
-
-[source,ini]
-----
-isis.persistor.datanucleus.impl.datanucleus.identifier.case=PreserveCase
-----
-
-to:
-
-[source,ini]
-----
-isis.persistor.datanucleus.impl.datanucleus.identifier.case=MixedCase
-----
-
-
-[WARNING]
-====
-Be careful to ensure that your classes are only enhanced by the DataNucleus 4 enhancer, and _not_ by the DataNucleus 3 enhancer. Or even, be careful that they are not doubly enhanced. One of our committers had this situation and it led to all sorts of bizarre issues. The solution, it turned out, was actually just to do a full `mvn clean`.
-
-If you are struggling and suspect you may have misconfigured the enhancer plugin, then you can decompile the bytecode (eg in IntelliJ) and take a look:
-
-* A class enhanced with DataNucleus 3 would implement `javax.jdo.spi.PersistenceCapable` interface
-* A class enhanced with DataNucleus 4 will implement `org.datanucleus.enhancer.Persistable`.
-====
-
-
-
-
-== Upgrading to Java 8 (1.9.0-SNAPSHOT and later)
-
-Apache Isis 1.9.0-SNAPSHOT is the first version to support Java 8. You can continue to use Java 7, but if you want to move to Java 8 then there are several small changes to be made.
-
-=== In the parent `pom.xml`
-
-under `<build>/<pluginManagement>/<plugins>`, add (or update) maven-enforcer-plugin:
-
-[source,xml]
-----
-<plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-compiler-plugin</artifactId>
- <version>3.1</version>
- <configuration>
- <source>1.8</source>
- <target>1.8</target>
- <compilerArgument>-parameters</compilerArgument>
- </configuration>
- <executions>
- <execution>
- <id>source</id>
- <phase>compile</phase>
- </execution>
- <execution>
- <id>test</id>
- <phase>test-compile</phase>
- </execution>
- </executions>
-</plugin>
-----
-
-[TIP]
-====
-The `-parameters` argument causes the Java compiler to capture the names of method parameters in the `.class` files. Isis can be configured to use this, thereby avoiding the requirement to annotate every parameter with `@ParameterLayout(named=...)` or `@Named()`. The necessary configuration is provided in an http://github.com/isisaddons/isis-metamodel-paraname8[Isis addons' paraname8] metamodel extension (non-ASF).
-====
-
-We also recommend that you add the `maven-enforcer-plugin` (if not used already). Again, this resides under `<build>/<pluginManagement>/<plugins>`:
-
-[source,xml]
-----
-<plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-enforcer-plugin</artifactId>
- <version>1.3.1</version>
- <configuration>
- <rules>
- <requireMavenVersion>
- <version>[3.2.1,)</version>
- </requireMavenVersion>
- <requireJavaVersion>
- <version>[1.8.0,)</version>
- </requireJavaVersion>
- <requirePluginVersions>
- <message>All plugin versions must be defined!</message>
- <banLatest>true</banLatest>
- <banRelease>true</banRelease>
- </requirePluginVersions>
- <DependencyConvergence />
- </rules>
- </configuration>
- <executions>
- <execution>
- <id>validate-enforce</id>
- <phase>validate</phase>
- <goals>
- <goal>enforce</goal>
- </goals>
- </execution>
- </executions>
-</plugin>
-----
-
-
-== Migrating from v1.7.0 to 1.8.0
-
-Existing projects written against v1.7.0 should run against v1.8.0 without any changes. In particular (unlike 1.6.0 and
- 1.7.0) there should be no need to update `pom.xml` files of existing projects. If you *do* encounter any difficulties
-then let us know via the [users mailing list](../../support.html), so we can support you and document issues here.
-
-That said, many of the existing annotations have been deprecated in 1.8.0, replaced with a simplified and rationalized
- set of annotations; see [here](../../reference/recognized-annotations/about.html). To help you migrate your application
- over to the new annotations, there is a new configuration property that can be set in `isis.properties`:
-
- isis.reflector.validator.allowDeprecated=false
-
-If this flag is present and set to false, then metamodel validation errors will be thrown on startup if any deprecated
-annotations are encountered. These can be viewed either in the console or by browsing to the app (an error page will
-be displayed).
-
-
-
-
-
-== Migrating from v1.6.0 to 1.7.0
-
-In v1.7.0 we've continued the work started in v1.6.0 in modularizing the framework. The most important change to note is that all Isis core modules (with the Maven `groupId` of `org.apache.isis.module` have now MOVED to [http://www.isisaddons.org](Isis Addons).
-
-In addition, we've retired some obsolete (and unused) functionality, specifically the `ProfileStore` component.
-
-To move up amounts to changing POM files and, where required, updating package names for any referenced modules.
-
-=== Reorganized 'modules'
-
-The following modules are no longer released as part of Isis core and have moved to Isis Addons (or in one case, back into Isis core).
-
-Minor changes are required to `pom.xml` files and (in some cases) to `isis.properties` config file.
-
-In one or two exceptional cases it may be necessary to fix up import statements if there are reference to changed package/class names in code (most likely any dependency on the `devutils` module or `settings` module).
-
-==== Audit module
-
-In `pom.xml`, replace:
-
-[source,xml]
-----
-<dependency>
- <groupId>org.apache.isis.module</groupId>
- <artifactId>isis-module-audit-jdo</artifactId>
-</dependency>
-----
-
-with:
-
-[source,xml]
-----
-<dependency>
- <groupId>org.isisaddons.module.audit</groupId>
- <artifactId>isis-module-audit-dom</artifactId>
-</dependency>
-----
-
-If necessary, also update any services registered in `isis.properties` (package/class names may have changed slightly).
-
-==== Command module
-
-In `pom.xml`, replace:
-
-[source,xml]
-----
-<dependency>
- <groupId>org.apache.isis.module</groupId>
- <artifactId>isis-module-command-jdo</artifactId>
-</dependency>
-----
-
-with:
-
-[source,xml]
-----
-<dependency>
- <groupId>org.isisaddons.module.command</groupId>
- <artifactId>isis-module-command-dom</artifactId>
-</dependency>
-----
-
-If necessary, also update any services registered in `isis.properties` (package/class names may have changed slightly).
-
-==== DevUtils module
-
-In `pom.xml`, replace:
-
-[source,xml]
-----
-<dependency>
- <groupId>org.apache.isis.module</groupId>
- <artifactId>isis-module-devutils-applib</artifactId>
-</dependency>
-----
-
-with:
-
-[source,xml]
-----
-<dependency>
- <groupId>org.isisaddons.module.devutils</groupId>
- <artifactId>isis-module-devutils-dom</artifactId>
-</dependency>
-----
-
-Remove any references to:
-
-[source,xml]
-----
-<dependency>
- <groupId>org.apache.isis.module</groupId>
- <artifactId>isis-module-devutils</artifactId>
-</dependency>
-----
-
-or to:
-
-[source,xml]
-----
-<dependency>
- <groupId>org.apache.isis.module</groupId>
- <artifactId>isis-module-devutils-impl</artifactId>
-</dependency>
-----
-
-These modules are no longer required (the `org.apache.isis.module:isis-module-devutils-applib`
-and `org.apache.isis.module:isis-module-devutils-impl` submodules have been combined
-into the new `org.isisaddons.module.devutils:isis-module-devutils-dom` module).
-
-If necessary, also update any services registered in `isis.properties` (package/class names may have changed slightly).
-
-==== Publishing module
-
-In `pom.xml`, replace:
-
-[source,xml]
-----
-<dependency>
- <groupId>org.apache.isis.module</groupId>
- <artifactId>isis-module-publishing-jdo</artifactId>
-</dependency>
-----
-
-with:
-
-[source,xml]
-----
-<dependency>
- <groupId>org.isisaddons.module.publishing</groupId>
- <artifactId>isis-module-publishing-dom</artifactId>
-</dependency>
-----
-
-If necessary, also update any services registered in `isis.properties` (package/class names may have changed slightly).
-
-==== Publishing Event Serializer RO module
-
-Remove any references to:
-
-[source,xml]
-----
-<dependency>
- <groupId>org.apache.isis.module</groupId>
- <artifactId>isis-module-publishingeventserializer-ro</artifactId>
-</dependency>
-----
-
-This module has been merged with `org.isisaddons.module.publishing:isis-module-publishing-dom`, above.
-
-==== Settings module
-
-In `pom.xml`, replace:
-
-[source,xml]
-----
-<dependency>
- <groupId>org.apache.isis.module</groupId>
- <artifactId>isis-module-settings-applib</artifactId>
-</dependency>
-----
-
-with:
-
-[source,xml]
-----
-<dependency>
- <groupId>org.isisaddons.module.settings</groupId>
- <artifactId>isis-module-settings-dom</artifactId>
-</dependency>
-----
-
-Remove any references to:
-
-[source,xml]
-----
-<dependency>
- <groupId>org.apache.isis.module</groupId>
- <artifactId>isis-module-settings</artifactId>
-</dependency>
-----
-
-or to:
-
-[source,xml]
-----
-<dependency>
- <groupId>org.apache.isis.module</groupId>
- <artifactId>isis-module-settings-impl</artifactId>
-</dependency>
-----
-
-These modules are no longer required (the `org.apache.isis.module:isis-module-settings-applib`
-and `org.apache.isis.module:isis-module-settings-impl` submodules have been combined
-into the new `org.isisaddons.module.settings:isis-module-settings-dom` module).
-
-If necessary, also update any services registered in `isis.properties` (package/class names may have changed slightly).
-
-==== Background module
-
-In `pom.xml`, remove:
-
-[source,xml]
-----
-<dependency>
- <groupId>org.apache.isis.module</groupId>
- <artifactId>isis-module-background</artifactId>
-</dependency>
-----
-
-The service classes have been moved into existing `org.apache.isis.core:isis-core-runtime` Maven module (that is, already be referenced in the `pom.xml`).
-
-If necessary, also update any services registered in `isis.properties` (package/class names may have changed slightly).
-
-=== Retired `ProfileStore` component
-
-As per <a href='https://issues.apache.org/jira/browse/ISIS-802'>ISIS-802</a>, the ProfileStore component has been removed. This functionality was not surfaced or available in the Wicket or Restful Objects viewers, so there is no meaningful loss of functionality. However, Maven `pom.xml` files will require updating:
-
-Specifically, remove any dependencies on `org.apache.isis:isis-core-profilestore`:
-
-[source,xml]
-----
-<dependency>
- <groupId>org.apache.isis.core</groupId>
- <artifactId>isis-core-profilestore</artifactId>
-</dependency>
-----
-
-A number of corresponding classes/interfaces have also been removed from the Isis applib:
-
-* `org.apache.isis.applib.fixtures.userprofile.UserProfileService`
-* `org.apache.isis.applib.fixtures.userprofile.UserProfileServiceAware`
-* `org.apache.isis.applib.fixtures.UserProfileFixture`
-* `org.apache.isis.applib.profiles.Profile`
-* `org.apache.isis.applib.profiles.Perspective`
-
-It is highly unlikely that any existing production code references these classes.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_release-notes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_release-notes.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_release-notes.adoc
deleted file mode 100644
index 6aa6c9f..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_release-notes.adoc
+++ /dev/null
@@ -1,127 +0,0 @@
-[[_ug_appendices_release-notes]]
-= Release Notes
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-[cols="1,1,2a,3a"]
-|===
-| Version | Date | Components | Notes
-
-| 1.8.0
-| 24-feb-2015
-| * link:https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311171&version=12328845[core-1.8.0]
-* link:https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311171&version=12328847[archetype-1.8.0]
-| Wicket viewer moved into core; todoapp archetype moved to link:http://www.isisaddons.org[Isis Addons] (non-ASF).
-
-| 1.7.0
-| 18-oct-2014
-| * link:https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311171&version=12326453[core-1.7.0]
-* link:https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311171&version=12326460[viewer-wicket-1.7.0]
-* link:https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311171&version=12327441[archetype-simpleapp-1.7.0]
-* link:https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311171&version=12327440[archetype-todoapp-1.7.0]
-| Module functionality previously in 1.6.0 now retired; use http://isisaddons.org[Isis Addons] (non-ASF) instead.
-
-| 1.6.0
-| 28-jul-2014
-| * link:https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311171&version=12325314[core-1.6.0]
-* link:https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311171&version=12325318[viewer-wicket-1.6.0]
-* link:https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311171&version=12326462[archetype-simpleapp-1.6.0]
-* link:https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311171&version=12326461[archetype-todoapp-1.6.0]
-| Restful Objects viewer, JDO/Datanucleus Objectstore and Shiro Security all moved into core. Quickstart-wrj archetype renamed to todoapp; simple-wrj archetype renamed to simpleapp. Some functionality copied/refactored as link:http://www.isisaddons.org[Isis Addons] (non-ASF).
-
-| 1.5.0
-| 08-jun-2014
-| * link:https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311171&version=12326524[core-1.5.0]
-* link:https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311171&version=12326525[objectstore-jdo-1.5.0]
-* link:https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311171&version=12326529[security-shiro-1.5.0]
-* link:https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311171&version=12326947[viewer-restfulobjects-2.3.0]
-* link:https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311171&version=12326526[viewer-wicket-1.5.0]
-* link:https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311171&version=12326528[archetype-simple-wrj-1.5.0]
-* link:https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311171&version=12326527[archetype-quickstart-wrj-1.5.0]
-| No longer releasing security-file
-
-| 1.4.1
-| 14-mar-2014
-| * objectstore-jdo-1.4.1
-* viewer-wicket-1.4.1
-* archetype-simple-wrj-1.4.1
-* archetype-quickstart-wrj-1.4.1
-| Patch release
-
-| 1.4.0
-| 11-mar-2014
-| * core-1.4.0
-* objectstore-jdo-1.4.0
-* security-file-1.4.0
-* security-shiro-1.4.0
-* viewer-restfulobjects-2.2.0
-* viewer-wicket-1.4.0
-* archetype-simple-wrj-1.4.0
-* archetype-quickstart-wrj-1.4.0
-|
-
-| 1.3.1
-| 7-nov-2013
-| * viewer-wicket-1.3.1
-* archetype-simple-wrj-1.3.1
-* archetype-quickstart-wrj-1.3.1
-| Patch release
-
-| 1.3.0
-| 25-oct-2013
-| * core-1.3.0
-* objectstore-jdo-1.3.0
-* security-file-1.0.2
-* security-shiro-1.3.0
-* viewer-restfulobjects-2.1.0
-* viewer-wicket-1.3.0
-* archetype-simple-wrj-1.3.0
-* archetype-quickstart-wrj-1.3.0
-| WRJ archetype renamed to Quickstart WRJ. Simple WRJ archetype added.
-
-| 1.2.0
-| 30-may-2013
-| * core-1.2.0
-* objectstore-jdo-1.2.0
-* security-file-1.0.1
-* security-shiro-1.1.1
-* viewer-restfulobjects-2.0.0
-* viewer-wicket-1.2.0
-* archetype-wrj-1.0.3
-|
-
-| 1.1.0
-| 31-jan-2013
-|* core-1.1.0
-* security-shiro-1.1.0
-* viewer-wicket-1.1.0
-* archetype-wrj-1.0.2
-|
-
-| 1.0.1
-| 10-jan-2013
-| * security-shiro-1.0.0
-* archetype-wrj-1.0.1
-| Combining RestfulObjects and Wicket viewers into a single webapp, along with Shiro security
-
-| 1.0.0
-| 24-dec-2012
-|* core-1.0.0
-* security-file-1.0.0
-* viewer-wicket-1.0.0
-* viewer-restfulobjects-1.0.0
-* archetype-wrj-1.0.0
-| First release having graduated
-
-| 0.2.0-incubating
-| 20-feb-2012
-| * 0.2.0-incubating
-|
-
-| 0.1.2-incubating
-| 13-jul-2011
-| * 0.1.2-incubating
-| First release in the ASF incubator
-|===
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts.adoc
deleted file mode 100644
index f7b255c..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_add-ons.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_add-ons.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_add-ons.adoc
deleted file mode 100644
index 83777e3..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_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 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 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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_building-blocks.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_building-blocks.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_building-blocks.adoc
deleted file mode 100644
index 80e045d..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_building-blocks.adoc
+++ /dev/null
@@ -1,93 +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/
-
-IMPORTANT: TODO
-
-## A MetaModel with Explicit and Inferred Semantics
-
-IMPORTANT: TODO
-
-* use of annotations
-** reuse JEE annotations where possible
-* layout hints are overridable, to avoid restarting the app/speed up feedback
-
-
-## Domain Objects and Domain Services
-
-IMPORTANT: TODO
-
-* domain model
-** domain objects
-*** domain entity
-*** view model
-** domain service
-** value type
-
-Anything else can be (should be) ignored by annotating with `@Programmatic`.
-
-
-
-## Properties, Collections and Actions
-
-IMPORTANT: TODO
-
-
-## Domain Entities vs View Models
-
-IMPORTANT: TODO
-
-`@DomainObject(nature=...)`
-
-
-
-## Domain Services
-
-Domain services consist of a set of logically grouped actions, and as such follow the same conventions as for entities. However, a service cannot have (persisted) properties, nor can it have (persisted) collections.
-
-Domain services are instantiated once and once only by the framework, and are used to centralize any domain logic that does not logically belong in a domain entity or value. Isis will automatically inject services into every domain entity that requests them, and into each other.
-
-For convenience you can inherit from AbstractService or one of its subclasses, but this is not mandatory.
-
-
-### Domain Services vs View Services
-
-IMPORTANT: 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.
-****
-
-
-
-
-## Value Objects (Primitives)
-
-IMPORTANT: TODO
-
-
-
-## Contributions
-
-IMPORTANT: TODO
-
-
-
-
-## Event Bus
-
-IMPORTANT: TODO
-
-
-
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_framework-provided-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_framework-provided-services.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_framework-provided-services.adoc
deleted file mode 100644
index 9961500..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_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:_ug_reference-services-api_manpage-DomainObjectContainer[`DomainObjectContainer`]
-* xref:_ug_reference-services-api_manpage-ClockService[`ClockService`]
-* xref:_ug_reference-services-api_manpage-IsisSupportJdo[`IsisSupportJdo`]
-* xref:_ug_reference-services-api_manpage-WrapperFactory[`WrapperFactory`]
-* xref:_ug_reference-services-api_manpage-EventBusService[`EventBusService`]
-* xref:_ug_reference-services-api_manpage-EmailService[`EmailService`]
-
-Commands/Background/Auditing:
-
-* xref:_ug_reference-services-api_manpage-CommandContext[`CommandContext`] (SPI)
-* xref:_ug_reference-services-spi_manpage-CommandService[`CommandService`] (SPI)
-* xref:_ug_reference-services-spi_manpage-AuditingService[`AuditingService`] (SPI)
-* xref:_ug_reference-services-api_manpage-BackgroundService[`BackgroundService`]
-* xref:_ug_reference-services-spi_manpage-BackgroundCommandService[`BackgroundCommandService`] (SPI)
-* xref:_ug_reference-services-spi_manpage-PublishingService[`PublishingService`] (SPI)
-
-Information Sharing:
-
-* xref:_ug_reference-services-api_manpage-ScratchPad[`ScratchPad`]
-* xref:_ug_reference-services-api_manpage-ActionInvocationContext[`ActionInvocationContext`]
-* xref:_ug_reference-services-api_manpage-QueryResultsCache[`QueryResultsCache`]
-
-
-UserManagement:
-
-* xref:_ug_reference-services-spi_manpage-UserProfileService[`UserProfileService`] (SPI)
-* xref:_ug_reference-services-spi_manpage-UserRegistrationService[`UserRegistrationService`] (SPI)
-* xref:_ug_reference-services-spi_manpage-EmailNotificationService[`EmailNotificationService`] (SPI)
-
-
-Bookmarks and Mementos:
-
-* xref:_ug_reference-services-api_manpage-BookmarkService[`BookmarkService`]
-* xref:_ug_reference-services-api_manpage-MementoService[`MementoService`]
-* xref:_ug_reference-services-api_manpage-DeepLinkService[`DeepLinkService`]
-* xref:_ug_reference-services-api_manpage-XmlSnapshotService[`XmlSnapshotService`]
-
-
-A full list of services can be found in the xref:_ug_domain-services-api[Domain Services (API)] and xref:_ug_domain-services-spi[Domain Services (SPI)] reference chapters.
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_other-deployment-options.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_other-deployment-options.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_other-deployment-options.adoc
deleted file mode 100644
index ce6bece..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_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 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 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_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 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 Isis, there can be a lot of value in using 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 teamEnum (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 Isis deliberately minimizes the dependencies on the rest of the framework. In fact, the only hard dependency that the domain model classes have on Isis is through the `org.apache.isis.applib` classes, mostly to pick up annotations such as `@Disabled`.
-So, if you have used 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; 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 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 Isis provides "out-of-the-box" (eg xref:_ug_reference-services-api_manpage-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. Isis' <<_restfulobjects_viewer, Restful Objects viewer] is an implementation of that spec, making any 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 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 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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_philosophy.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_philosophy.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_philosophy.adoc
deleted file mode 100644
index b31b507..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_philosophy_aop.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_philosophy_aop.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_philosophy_aop.adoc
deleted file mode 100644
index 4c29dd2..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_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; and many tend to think of xref:_ug_core-concepts_philosophy_domain-driven-design,DDD>> as an updated treatise on good object modelling[in the same vein as Rebecca Wirf Brock's link:http://en.wikipedia.org/wiki/Responsibility-driven_design[Responsibility Driven Design], say. Meanwhile the <<_naked_objects_pattern, naked objects pattern] very much comes from an OO background (it even has 'object' in its name); and 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 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:_ug_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_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. 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 Isis' AOP support for mixins (xref:_ug_more-advanced_decoupling_contributions[contributions]) and interceptors (the xref:_ug_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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_philosophy_dci.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_philosophy_dci.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_philosophy_dci.adoc
deleted file mode 100644
index 1e4c916..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_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/
-
-
-IMPORTANT: TODO ... Trygve Reenskaug
-
[16/45] isis git commit: ISIS-1133: breaking out reference guide and
devenv guide;
moving appendices' release notes and migration notes to other docs;
improving the documentation page.
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-CollectionLayout_cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-CollectionLayout_cssClass.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-CollectionLayout_cssClass.adoc
deleted file mode 100644
index 24a1f03..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-CollectionLayout_cssClass.adoc
+++ /dev/null
@@ -1,36 +0,0 @@
-[[_ug_reference-annotations_manpage-CollectionLayout_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()` attribute can be used to render additional CSS classes in the HTML (a wrapping `<div>`) that represents the collection. xref:_ug_runtime_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:_ug_reference-annotations_manpage-DomainObjectLayout_cssClass[domain objects], xref:_ug_reference-annotations_manpage-ViewModelLayout_cssClass[view models], xref:_ug_reference-annotations_manpage-ActionLayout_cssClass[actions], xref:_ug_reference-annotations_manpage-PropertyLayout_cssClass[properties] and xref:_ug_reference-annotations_manpage-ParameterLayout_cssClass[parameters].
-
-
-For example:
-
-[source,java]
-----
-public class ToDoItem {
- @CollectionLayout(
- cssClass="x-important"
- )
- public SortedSet<ToDoItem> getDependencies() { ... }
- ...
-}
-----
-
-
-As an alternative to using the annotation, the dynamic xref:_ug_reference-object-layout_dynamic[`.layout.json`]
-can be used instead, eg:
-
-[source,javascript]
-----
-"dependencies": {
- "collectionLayout": { "cssClass": "x-important" }
-}
-----
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-CollectionLayout_describedAs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-CollectionLayout_describedAs.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-CollectionLayout_describedAs.adoc
deleted file mode 100644
index 50ad84f..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-CollectionLayout_describedAs.adoc
+++ /dev/null
@@ -1,37 +0,0 @@
-[[_ug_reference-annotations_manpage-CollectionLayout_describedAs]]
-= `describedAs()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `describedAs()` attribute is used to provide a short description of the collection to the user. In the xref:_ug_wicket-viewer[Wicket viewer] it is displayed as a 'tool tip'.
-
-The `describedAs()` attribute can also be specified for xref:_ug_reference-annotations_manpage-PropertyLayout_describedAs[properties], xref:_ug_reference-annotations_manpage-ActionLayout_describedAs[actions], xref:_ug_reference-annotations_manpage-ParameterLayout_describedAs[parameters], xref:_ug_reference-annotations_manpage-DomainObjectLayout_describedAs[domain objects] and xref:_ug_reference-annotations_manpage-ViewModelLayout_describedAs[view models].
-
-
-For example:
-
-[source,java]
-----
-public class ToDoItem {
- @CollectionLayout(
- describedAs="Other todo items that must be completed before this one")
- public SortedSet<ToDoItem getDependencies() { ... }
- ...
-}
-----
-
-
-As an alternative to using the annotation, the dynamic xref:_ug_reference-object-layout_dynamic[`.layout.json`]
-can be used instead, eg:
-
-[source,javascript]
-----
-"dependencies": {
- "collectionLayout": {
- "describedAs": "Other todo items that must be completed before this one"
- }
-}
-----
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-CollectionLayout_hidden.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-CollectionLayout_hidden.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-CollectionLayout_hidden.adoc
deleted file mode 100644
index f47bbcc..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-CollectionLayout_hidden.adoc
+++ /dev/null
@@ -1,58 +0,0 @@
-[[_ug_reference-annotations_manpage-CollectionLayout_hidden]]
-= `hidden()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `hidden()` attribute indicates where (in the UI) the collection should be hidden from the user. This attribute can also be applied to xref:_ug_reference-annotations_manpage-ActionLayout_hidden[actions] and xref:_ug_reference-annotations_manpage-PropertyLayout_hidden[properties].
-
-
-[TIP]
-====
-It is also possible to use xref:_ug_reference-annotations_manpage-Collection_hidden[`@Collection#hidden()`] to hide an action at the domain 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:
-
-[source,java]
-----
-public class ToDoItem {
- @CollectionLayout(
- hidden=Where.EVERYWHERE
- public SortedSet<ToDoItem> getDependencies() { ... }
- ...
-}
-----
-
-
-The acceptable values for the `where` parameter are:
-
-* `Where.EVERYWHERE` or `Where.ANYWHERE` +
-+
-The collection should be hidden everywhere.
-
-* `Where.ANYWHERE` +
-+
-Synonym for everywhere.
-
-* `Where.OBJECT_FORMS` +
-+
-The collection should be hidden when displayed within an object form.
-
-* `Where.NOWHERE` +
-+
-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_reference-object-layout_dynamic[`.layout.json`]
-can be used instead, eg:
-
-[source,javascript]
-----
-"dependencies": {
- "collectionLayout": { "hidden": "EVERYWHERE" }
-}
-----
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-CollectionLayout_named.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-CollectionLayout_named.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-CollectionLayout_named.adoc
deleted file mode 100644
index 7c30d7c..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-CollectionLayout_named.adoc
+++ /dev/null
@@ -1,53 +0,0 @@
-[[_ug_reference-annotations_manpage-CollectionLayout_named]]
-= `named()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `named()` attribute explicitly specifies the collection's name, overriding the name that would normally be inferred from the Java source code. This attribute can also be specified for xref:_ug_reference-annotations_manpage-ActionLayout_named[actions], xref:_ug_reference-annotations_manpage-PropertyLayout_named[properties], xref:_ug_reference-annotations_manpage-ParameterLayout_named[parameters], xref:_ug_reference-annotations_manpage-DomainObjectLayout_named[domain objects], xref:_ug_reference-annotations_manpage-ViewModelLayout_named[view models] and xref:_ug_reference-annotations_manpage-DomainServiceLayout_named[domain services].
-
-[TIP]
-====
-Following the link:http://en.wikipedia.org/wiki/Don%27t_repeat_yourself[don't repeat yourself] principle, we recommend that you only use this attribute when the desired name cannot be used in Java source code. Examples of that include a name that would be a reserved Java keyword (eg "package"), or a name that has punctuation, eg apostrophes.
-====
-
-
-By default the name is HTML escaped. To allow HTML markup, set the related `namedEscaped()` attribute to `false`.
-
-
-For example:
-
-[source,java]
-----
-public class ToDoItem {
- @CollectionLayout(
- named="Todo items that are <i>dependencies</i> of this item",
- namedEscaped=false
- )
- public SortedSet<ToDoItem getDependencies() { ... }
- ...
-}
-----
-
-
-
-As an alternative to using the annotation, the dynamic xref:_ug_reference-object-layout_dynamic[`.layout.json`]
-can be used instead, eg:
-
-[source,javascript]
-----
-"dependencies": {
- "collectionLayout": {
- "named": "Todo items that are <i>dependencies</i> of this item",
- "namedEscaped": false,
- }
-}
-----
-
-
-[TIP]
-====
-The framework also provides a separate, powerful mechanism for xref:_ug_more-advanced_i18n[internationalization].
-====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-CollectionLayout_paged.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-CollectionLayout_paged.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-CollectionLayout_paged.adoc
deleted file mode 100644
index d6a9ace..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-CollectionLayout_paged.adoc
+++ /dev/null
@@ -1,45 +0,0 @@
-[[_ug_reference-annotations_manpage-CollectionLayout_paged]]
-= `paged()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `paged()` attribute specifies the number of rows to display in a (parented) collection. This attribute can also be applied to xref:_ug_reference-annotations_manpage-DomainObjectLayout_paged[domain objects] and xref:_ug_reference-annotations_manpage-ViewModelLayout_paged[view models].
-
-
-[WARNING]
-====
-The xref:_ug_restfulobjects-viewer[RestfulObjects viewer] currently does not support paging. The xref:_ug_wicket-viewer[Wicket viewer] _does_ support paging, but note that the paging is performed client-side rather than server-side.
-
-We therefore recommend that large collections should instead be modelled as actions (to allow filtering to be applied to limit the number of rows).
-====
-
-
-For example:
-
-[source,java]
-----
-public class Order {
- @CollectionLayout(paged=15)
- public SortedSet<OrderLine> getDetails() {...}
-}
-----
-
-
-It is also possible to specify a global default for the page size of standalone collections, using the xref:_ug_runtime_configuring-core[configuration property] `isis.viewer.paged.parented`.
-
-
-
-As an alternative to using the annotation, the dynamic xref:_ug_reference-object-layout_dynamic[`.layout.json`]
-can be used instead, eg:
-
-[source,javascript]
-----
-"details": {
- "collectionLayout": {
- "paged": 15
- }
-}
-----
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-CollectionLayout_render.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-CollectionLayout_render.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-CollectionLayout_render.adoc
deleted file mode 100644
index 84b6529..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-CollectionLayout_render.adoc
+++ /dev/null
@@ -1,40 +0,0 @@
-[[_ug_reference-annotations_manpage-CollectionLayout_render]]
-= `render()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `render()` attribute specifies that the collection be rendered either "eagerly" (shown open, displaying its contents) or "lazily" (shown closed, hiding its contents). The terminology here is based on the similar concept of lazy loading of collections in the domain/persistence layer boundary (except that the rendering relates to the presentation/domain layer boundary).
-
-
-For example:
-
-[source,java]
-----
-public class Order {
- @CollectionLayout(render=RenderType.EAGERLY)
- public SortedSet<LineItem> getDetails() { ... }
- ...
-}
-----
-
-
-As an alternative to using the annotation, the dynamic xref:_ug_reference-object-layout_dynamic[`.layout.json`]
-can be used instead, eg:
-
-[source,javascript]
-----
-"details": {
- "collectionLayout": {
- "render": "EAGERLY"
- }
-}
-----
-
-
-[NOTE]
-====
-Note that xref:_ug_how-tos_contributed-members[contributed collections] (which, under the covers are just action invocations against a domain service) are always rendered eagerly.
-====
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-CollectionLayout_sortedBy.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-CollectionLayout_sortedBy.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-CollectionLayout_sortedBy.adoc
deleted file mode 100644
index b05f89a..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-CollectionLayout_sortedBy.adoc
+++ /dev/null
@@ -1,59 +0,0 @@
-[[_ug_reference-annotations_manpage-CollectionLayout_sortedBy]]
-= `sortedBy()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `sortedBy()` attribute specifies that the collection be ordered using the specified comparator, rather than the natural ordering of the entity (as would usually be the case).
-
-For example:
-
-[source,java]
-----
-public class ToDoItem implements Comparable<ToDoItem> { // <1>
- public static class DependenciesComparator // <2>
- implements Comparator<ToDoItem> {
- @Override
- public int compare(ToDoItem p, ToDoItem q) {
- return ORDERING_BY_DESCRIPTION // <3>
- .compound(Ordering.<ToDoItem>natural())
- .compare(p, q);
- }
- }
- @CollectionLayout(sortedBy=DependenciesComparator.class) // <4>
- public SortedSet<ToDoItem> getDependencies() { ... }
- ...
-}
-----
-<1> the class has a natural ordering (implementation not shown)
-<2> declaration of the comparator class
-<3> ordering defined as being by the object's `description` property (not shown), and then by the natural ordering of the class
-<4> specify the comparator to use
-
-When the `dependencies` collection is rendered, the elements are sorted by the `description` property first:
-
-image::{_imagesdir}reference-annotations/CollectionLayout/sortedby-dependencies.png[width="720px",link="{_imagesdir}reference-annotations/CollectionLayout/sortedby-dependencies.png"]
-
-[NOTE]
-====
-Note that this screenshot shows an earlier version of the xref:_ug_wicket-viewer[Wicket viewer] UI (specifically, pre 1.8.0).
-====
-
-
-Without this annotation, the order would have been inverted (because the natural ordering places items not completed before those items that have been completed.
-
-
-
-
-As an alternative to using the annotation, the dynamic xref:_ug_reference-object-layout_dynamic[`.layout.json`]
-can be used instead, eg:
-
-[source,javascript]
-----
-"dependencies": {
- "collectionLayout": {
- "sortedBy": "com.mycompany.myapp.dom.ToDoItem.DependenciesComparator"
- }
-}
-----
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Collection_domainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Collection_domainEvent.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Collection_domainEvent.adoc
deleted file mode 100644
index 0f548eb..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Collection_domainEvent.adoc
+++ /dev/null
@@ -1,158 +0,0 @@
-[[_ug_reference-annotations_manpage-Collection_domainEvent]]
-= `domainEvent()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-Whenever a domain object (or list of domain objects) is to be rendered, the framework fires off multiple domain events for every property, collection and action of the domain object. In the cases of the domain object's collections, the events that are fired are:
-
-* hide phase: to check that the collection is visible (has not been hidden)
-* disable phase: to check that the collection is usable (has not been disabled)
-* validate phase: to check that the collection's arguments are valid (to add or remove an element)
-* pre-execute phase: before the modification of the collection
-* post-execute: after the modification of the collection
-
-Subscribers subscribe through the xref:_ug_reference-services-api_manpage-EventBusService[`EventBusService`] using either link:https://github.com/google/guava[Guava] or link:http://www.axonframework.org/[Axon Framework] annotations and can influence each of these phases.
-
-
-[WARNING]
-====
-The xref:_ug_wicket-viewer[Wicket viewer] does _not_ currently support the modification of collections; they are rendered read-only. However, domain events are still relevant to determine if such collections should be hidden.
-
-The workaround is to create add/remove actions and use xref:_ug_reference-annotations_manpage-MemberOrder[UI hints] to render them close to the collection.
-====
-
-By default the event raised is `CollectionDomainEvent.Default`. For example:
-
-[source,java]
-----
-public class ToDoItem {
- @Collection()
- public SortedSet<ToDoItem> getDependencies() { ... }
- ...
-}
-----
-
-The purpose of the `domainEvent()` attribute is to allows a custom subclass to be emitted instead. This attribute is also supported for xref:_ug_reference-annotations_manpage-Action_domainEvent[actions] and xref:_ug_reference-annotations_manpage-Property_domainEvent[properties].
-
-
-For example:
-
-[source,java]
-----
-public class ToDoItem {
- public static class DependenciesChangedEvent
- extends CollectionDomainEvent<ToDoItem, ToDoItem> { // <1>
- private static final long serialVersionUID = 1L;
- public DependenciesChangedEvent( // <2>
- ToDoItem source, // <3>
- Identifier identifier, // <4>
- Of of, // <5>
- ToDoItem value) { // <6>
- super(source, identifier, of, value);
- }
- }
- @Collection(
- domainEvent=DependenciesChangedEvent.class
- )
- public SortedSet<ToDoItem> getDependencies() { ... }
- ...
-}
-----
-<1> inherit from `CollectionDomainEvent<T,E>` where `T` is the type of the domain object being interacted with, and `E` is the type of the element in the collection (both `ToDoItem` in this example)
-<2> constructor called reflectively by the framework
-<3> populated with the object being interacted with (the source of the event)
-<4> identifier of the collection
-<5> indicates if the collection is being accessed, added to or removed from.
-<6> the element being added or removed from the collection
-
-
-The benefit is that subscribers can be more targetted as to the events that they subscribe to.
-
-
-
-== Subscribers
-
-Subscribers (which must be domain services) subscribe using either the link:https://github.com/google/guava[Guava] API or (if the xref:_ug_reference-services-api_manpage-EventBusService[`EventBusService`] has been appropriately configured) using the link:http://www.axonframework.org/[Axon Framework] API. The examples below use the Guava API.
-
-Subscribers can be either coarse-grained (if they subscribe to the top-level event type):
-
-[source,java]
-----
-@DomainService
-public class SomeSubscriber {
- @Programmatic
- @com.google.common.eventbus.Subscribe
- public void on(CollectionInteractionEvent ev) {
- ...
- }
-}
-----
-
-or can be fine-grained (by subscribing to specific event subtypes):
-
-[source,java]
-----
-@DomainService
-public class SomeSubscriber {
- @Programmatic
- @com.google.common.eventbus.Subscribe
- public void on(ToDoItem.DependenciesChangedEvent ev) {
- ...
- }
-}
-----
-
-[TIP]
-====
-If the AxonFramework is being used, replace `@com.google.common.eventbus.Subscribe` with `@org.axonframework.eventhandling.annotation.EventHandler`.
-====
-
-The subscriber's method is called (up to) 5 times:
-
-* whether to veto visibility (hide)
-* whether to veto usability (disable)
-* whether to veto execution (validate) the element being added to/removed from the collection
-* steps to perform prior to the collection being added to/removed from
-* steps to perform after the collection has been added to/removed from.
-
-The subscriber can distinguish these by calling `ev.getPhase()`. Thus the general form is:
-
-[source,java]
-----
-@Programmatic
-@com.google.common.eventbus.Subscribe
-public void on(CollectionDomainEvent ev) {
- switch(ev.getPhase()) {
- case HIDE:
- // call ev.hide() or ev.veto("") to hide the collection
- break;
- case DISABLE:
- // call ev.disable("...") or ev.veto("...") to disable the collection
- break;
- case VALIDATE:
- // call ev.invalidate("...") or ev.veto("...")
- // if object being added/removed to collection is invalid
- break;
- case EXECUTING:
- break;
- case EXECUTED:
- break;
- }
-}
-----
-
-It is also possible to abort the transaction during the executing or executed phases by throwing an exception. If the exception is a subtype of `RecoverableException` then the exception will be rendered as a user-friendly warning (eg Growl/toast) rather than an error.
-
-
-
-
-== Raising events programmatically
-
-Normally events are only raised for interactions through the UI. However, events can be raised programmatically either by calling the xref:_ug_reference-services-api_manpage-EventBusService[`EventBusService`] API directly, or by emulating the UI by
-wrapping the target object using the xref:_ug_reference-services-api_manpage-WrapperFactory[`WrapperFactory`] domain service.
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Collection_editing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Collection_editing.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Collection_editing.adoc
deleted file mode 100644
index 9fc8a5a..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Collection_editing.adoc
+++ /dev/null
@@ -1,48 +0,0 @@
-[[_ug_reference-annotations_manpage-Collection_editing]]
-= `editing()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `editing()` annotation indicates whether a collection can be added to or removed from within the UI. This attribute can also be specified for xref:_ug_reference-annotations_manpage-Property_editing[properties], and can also be specified for the xref:_ug_reference-annotations_manpage-DomainObject_editing[domain object]
-
-The related `editingDisabledReason()` attribute specifies the a hard-coded reason why the collection cannot be modified directly.
-
-[WARNING]
-====
-The xref:_ug_wicket-viewer[Wicket viewer] does _not_ currently support the modification of collections; they are rendered read-only.
-
-The workaround is to create add/remove actions and use xref:_ug_reference-annotations_manpage-MemberOrder[UI hints] to render them close to the collection.
-====
-
-Whether a collection is enabled or disabled depends upon these factors:
-
-* whether the domain object has been configured as immutable through the xref:_ug_reference-annotations_manpage-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:_ug_runtime_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.
-
-* else, the result of invoking any supporting xref:_ug_reference-methods_prefixes_manpage-disable[`disable...()`] supporting methods
-
-
-Thus, to make a collection read-only even if the object would otherwise be editable, use:
-
-
-[source,java]
-----
-public class ToDoItem {
- @Collection(
- editing=Editing.DISABLED,
- editingDisabledReason="Use the add and remove actions to modify"
- )
- public SortedSet<ToDoItem> getDependencies() { ... }
-}
-----
-
-[NOTE]
-====
-To reiterate, it is _not_ possible to enable editing for a collection if editing has been disabled at the object-level.
-====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Collection_hidden.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Collection_hidden.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Collection_hidden.adoc
deleted file mode 100644
index e0e627d..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Collection_hidden.adoc
+++ /dev/null
@@ -1,54 +0,0 @@
-[[_ug_reference-annotations_manpage-Collection_hidden]]
-= `hidden()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-Collections can be hidden at the domain-level, indicating that they are not visible to the end-user. This attribute can also be applied to xref:_ug_reference-annotations_manpage-Action_hidden[actions] and xref:_ug_reference-annotations_manpage-Property_hidden[properties].
-
-[TIP]
-====
-It is also possible to use xref:_ug_reference-annotations_manpage-CollectionLayout_hidden[`@CollectionLayout#hidden()`] or xref:_ug_reference-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:
-
-[source,java]
-----
-public class Customer {
- @Collection(where=Where.EVERYWHERE)
- public SortedSet<Address> getAddresses() { ... }
-}
-----
-
-
-The acceptable values for the `where` parameter are:
-
-* `Where.EVERYWHERE` or `Where.ANYWHERE` +
-+
-The collection should be hidden everywhere.
-
-* `Where.ANYWHERE` +
-+
-Synonym for everywhere.
-
-* `Where.OBJECT_FORMS` +
-+
-The collection should be hidden when displayed within an object form.
-
-* `Where.NOWHERE` +
-+
-The collection should not be hidden.
-
-The other values of the `Where` enum have no meaning for a collection.
-
-
-
-
-[NOTE]
-====
-The xref:_ug_wicket-viewer[Wicket viewer] suppresses collections when displaying lists of objects.
-
-The xref:_ug_restfulobjects-viewer[RestfulObjects viewer] by default suppress collections when rendering a domain object.
-====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Collection_notPersisted.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Collection_notPersisted.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Collection_notPersisted.adoc
deleted file mode 100644
index 53c84e4..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Collection_notPersisted.adoc
+++ /dev/null
@@ -1,57 +0,0 @@
-[[_ug_reference-annotations_manpage-Collection_notPersisted]]
-= `notPersisted()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 (somewhat misnamed) `notPersisted()` attribute indicates that the collection should be excluded from any snapshots generated by the xref:_ug_reference-services-api_manpage-XmlSnapshotService[`XmlSnapshotService`]. This attribute is also supported for xref:_ug_reference-annotations_manpage-Property_notPersisted[properties].
-
-
-[WARNING]
-====
-This annotation does _not_ specify that a collection is not persisted in the JDO/DataNucleus objectstore. See below for details as to how to additionally annotate the collection for this.
-====
-
-
-For example:
-
-[source,java]
-----
-public class Customer {
- @Collection(notPersisted=true)
- public SortedSet<Order> getPreviousOrders() {...}
- public void setPreviousOrder(SortedSet<Order> previousOrders) {...}
- ...
-}
-----
-
-Historically this annotation also hinted as to whether the collection's contents should be persisted in the object store. However, the JDO/DataNucleus objectstore does not recognize this annotation. Thus, to ensure that a collection is actually not persisted, it should *also* be annotated with `@javax.jdo.annotations.NotPersistent`.
-
-For example:
-
-[source,java]
-----
-public class Customer {
- @Collection(notPersisted=true) // <1>
- @javax.jdo.annotations.NotPersistent // <2>
- public SortedSet<Order> getPreviousOrders() {...}
- public void setPreviousOrder(SortedSet<Order> previousOrders) {...}
- ...
-}
-----
-<1> ignored by Isis
-<2> ignored by JDO/DataNucleus
-
-
-
-Alternatively, if the collection is derived, then providing only a "getter" will also work:
-
-[source,java]
-----
-public class Customer {
- public SortedSet<Order> getPreviousOrders() {...}
- ...
-}
-----
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Collection_typeOf.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Collection_typeOf.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Collection_typeOf.adoc
deleted file mode 100644
index 39e657f..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Collection_typeOf.adoc
+++ /dev/null
@@ -1,26 +0,0 @@
-[[_ug_reference-annotations_manpage-Collection_typeOf]]
-= `typeOf()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `typeOf()` attribute specifies the expected type of an element contained within a collection when for whatever reason the type cannot be inferred from the generic type, or to provide a hint about the actual run-time (as opposed to compile-time) type. This attribute can also be specified for xref:_ug_reference-annotations_manpage-Action_typeOf[actions].
-
-For example:
-
-[source,java]
-----
-public void Customer {
- @TypeOf(Order.class)
- public SortedSet getOutstandingOrders() { ... }
- ...
-}
-----
-
-[TIP]
-====
-In general we recommend that you use generics instead, eg `SortedSet<Order>`.
-====
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Column.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Column.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Column.adoc
deleted file mode 100644
index 3d75e18..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Column.adoc
+++ /dev/null
@@ -1,154 +0,0 @@
-[[_ug_reference-annotations_manpage-Column]]
-= `@Column` (`javax.jdo`)
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 JDO `@javax.jdo.annotation.Column` provides metadata describing how JDO/DataNucleus should persist the property to a database RDBMS table column (or equivalent concept for other persistence stores).
-
-Apache Isis also parses and interprets this annotation in order to build up aspects of its metamodel.
-
-[NOTE]
-====
-Isis parses the `@Column` annotation from the Java source code; it does not query the JDO metamodel. This means that it the `@Column` annotation must be used rather than the equivalent `<column>` link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/orm/schema_mapping.html[XML metadata].
-
-Moreover, while JDO/DataNucleus will recognize annotations on either the field or the getter method, Isis (currently) only inspects the getter method. Therefore ensure that the annotation is placed there.
-====
-
-This section identifies which attributes of `@Column` are recognized and used by Isis.
-
-
-
-== Nullability
-
-The `allowsNull()` attribute is used to specify if a property is mandatory or is optional.
-
-For example:
-
-[source,java]
-----
-public class Customer {
- @javax.jdo.annotations.Column(allowNulls="true")
- public String getMiddleInitial() { ... }
- public void setMiddleInitial(String middleInitial) { ... }
-----
-
-Isis also provides xref:_ug_reference-annotations_manpage-Property_optionality[`@Property#optionality()`] attribute. If both are specified, Isis will check when it initializes for any contradictions, and will fail-fast with an appropriate error message in the log if there are.
-
-You should also be aware that in the lack of either the `@Column#allowsNull()` or the `@Property#optionality()` attributes, that the JDO and Isis defaults differ. Isis rule is straight-forward: properties are assumed to be required. JDO on the other hand specifies that only primitive types are mandatory; everything else is assumed to be optional. Therefore a lack of either annotation can also trigger the fail-fast validation check.
-
-In the vast majority of cases you should be fine just to add the `@Column#allowsNull()` attribute to the getter. But see the documentation for xref:_ug_reference-annotations_manpage-Property_optionality[`@Property#optionality()`] attribute for discussion on one or two minor edge cases.
-
-
-
-== Length for ``String``s
-
-The `length()` attribute is used to specify the length of `java.lang.String` property types as they map to `varchar(n)` columns.
-
-For example:
-
-[source,java]
-----
-public class Customer {
- @javax.jdo.annotations.Column(length=20)
- public String getFirstName() { ... }
- public void setFirstName(String firstName) { ... }
- @javax.jdo.annotations.Column(allowNulls="true", length=1)
- public String getMiddleInitial() { ... }
- public void setMiddleInitial(String middleInitial) { ... }
- @javax.jdo.annotations.Column(length=30)
- public String getLastName() { ... }
- public void setLastName(String lastName) { ... }
-----
-
-Isis also provides xref:_ug_reference-annotations_manpage-Property_maxLength[`@Property#maxLength()`] attribute. If both are specified, Isis will check when it initializes for any contradictions, and will fail-fast with an appropriate error message in the log if there are.
-
-
-
-== Length/scale for ``BigDecimal``s
-
-
-The `length()` and `scale()` attributes are used to infer the precision/scale of `java.math.BigDecimal` property types as they map to `decimal(n,p)` columns.
-
-For example:
-
-[source,java]
-----
-public class Customer {
- @javax.jdo.annotations.Column(length=10, scale=2)
- public BigDecimal getTotalOrdersToDate() { ... }
- public void setTotalOrdersToDate(BigDecimal totalOrdersToDate) { ... }
-----
-
-For ``BigDecimal``s it is also possible to specify the xref:_ug_reference-annotations_manpage-Digits[`@Digits`] annotation, whose form is `@Digits(integer, fraction)`. There is a subtle difference here: while `@Column#scale()` corresponds to `@Digits#fraction()`, the value of `@Column#length()` (ie the precision) is actually the _sum_ of the `@Digits`' `integer()` and `fraction()` parts.
-
-If both are specified, Isis will check when it initializes for any contradictions, and will fail-fast with an appropriate error message in the log if there are.
-
-
-
-
-== Hints and Tips
-
-This seems to be a good place to describe some additional common mappings that use `@Column`. Unlike the sections above, the attributes specified in these hints and tips aren't actually part of Isis metamodel.
-
-
-=== Mapping foreign keys
-
-The `name()` attribute can be used to override the name of the column. References to other objects are generally mapped as foreign key columns. If there are multiple references to a given type, then you will want to override the name that JDO/DataNucleus would otherwise default.
-
-For example (taken from link:http://github.com/estatio/estatio[estatio] app):
-
-[source,java]
-----
-public class PartyRelationship {
- @Column(name = "fromPartyId", allowsNull = "false")
- public Party getFrom() { ... }
- public void setFrom(Party from) { ... }
- @Column(name = "toPartyId", allowsNull = "false")
- public Party getTo() { ... }
- public void setTo(Party to) { ... }
- ...
-}
-----
-
-
-
-== Mapping ``Blob``s and ``Clob``s
-
-Isis provides custom value types for xref:_ug_reference-classes_value-types_manpage-Blob[`Blob`]s and xref:_ug_reference-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]):
-
-[source,java]
-----
-private Blob attachment;
-@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 = "BLOB")
-})
-@Property(
- domainEvent = AttachmentDomainEvent.class,
- optionality = Optionality.OPTIONAL
-)
-public Blob getAttachment() { ... }
-public void setAttachment(Blob attachment) { ... }
-----
-
-And here's how to map a `Clob` (also taken from the todoapp):
-
-[source,java]
-----
-private Clob doc;
-@javax.jdo.annotations.Persistent(defaultFetchGroup="false", columns = {
- @javax.jdo.annotations.Column(name = "doc_name"),
- @javax.jdo.annotations.Column(name = "doc_mimetype"),
- @javax.jdo.annotations.Column(name = "doc_chars", jdbcType = "CLOB", sqlType = "CLOB")
-})
-@Property(
- optionality = Optionality.OPTIONAL
-)
-public Clob getDoc() { ... }
-public void setDoc(final Clob doc) { ... }
-----
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Digits.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Digits.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Digits.adoc
deleted file mode 100644
index 99507c4..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Digits.adoc
+++ /dev/null
@@ -1,35 +0,0 @@
-[[_ug_reference-annotations_manpage-Digits]]
-= `@Digits` (`javax`)
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@javax.validation.constraints.Digits` annotation is recognized by Apache Isis as a means to specify the precision for properties and action parameters of type `java.math.BigDecimal`.
-
-For example (taken from the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp]):
-
-[source,java]
-----
-@javax.jdo.annotations.Column(
- scale=2 // <1>
-)
-@javax.validation.constraints.Digits(
- integer=10,
- fraction=2 // <2>
-)
-public BigDecimal getCost() {
- return cost;
-}
-public void setCost(final BigDecimal cost) {
- this.cost = cost!=null
- ? cost.setScale(2, BigDecimal.ROUND_HALF_EVEN) // <3>
- :null;
-}
-----
-<1> the xref:_ug_reference-annotations_manpage-Column[`@Column#scale()`] attribute must be ...
-<2> ... consistent with `@Digits#fraction()`
-<3> the correct idiom when setting a new value is to normalized to the correct scale
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Discriminator.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Discriminator.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Discriminator.adoc
deleted file mode 100644
index 5c43f42..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Discriminator.adoc
+++ /dev/null
@@ -1,59 +0,0 @@
-[[_ug_reference-annotations_manpage-Discriminator]]
-= `@Discriminator` (`javax.jdo`)
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@javax.jdo.annotation.Discriminator` is used by JDO/DataNucleus to specify how to discriminate between subclasses of an inheritance hierarchy.
-
-It is valid to add a `@Discriminator` for any class, even those not part of an explicitly mapped inheritance hierarchy. Apache Isis also checks for this annotation, and if present will use the `@Discriminator#value()` as the object type, a unique alias for the object's class name.
-
-[NOTE]
-====
-Isis parses the `@Discriminator` annotation from the Java source code; it does not query the JDO metamodel. This means that it the `@Discriminator` annotation must be used rather than the equivalent `<discriminator>` link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/orm/inheritance.html[XML metadata].
-
-Moreover, while JDO/DataNucleus will recognize annotations on either the field or the getter method, Isis (currently) only inspects the getter method. Therefore ensure that the annotation is placed there.
-====
-
-The object type is used internally by Isis to generate a string representation of an objects identity (the `Oid`). This can appear in several contexts, including:
-
-* as the value of `o.a.i.applib.services.bookmark.Bookmark#getObjectType()`
-* in the `toString()` value of `Bookmark`
-* in the URLs of the xref:_ug_restfulobjects-viewer[RestfulObjects viewer]
-* in the URLs of the xref:_ug_wicket-viewer[Wicket viewer] (in general and in particular if xref:_ug_wicket-viewer_features_hints-and-copy-url[copying URLs])
-* in XML snapshots generated by the xref:_ug_reference-services-api_manpage-XmlSnapshotService[`XmlSnapshotService`]
-
-
-For example:
-
-[source,java]
-----
-@javax.jdo.annotations.Discriminator(value="custmgmt.Customer")
-public class Customer {
- ...
-}
-----
-
-has an object type of `custmgmt.Customer`.
-
-If the object type has not been specified, then Isis will use the fully qualified class name of the entity.
-
-
-
-[TIP]
-====
-This might be obvious, but to make explicit: we recommend that you use namespaces of some form or other.
-
-If the object type has not been specified (by either this annotation, or by xref:_ug_reference-annotations_manpage-PersistenceCapable[`@PersistenceCapable`], or by Isis' own xref:_ug_reference-annotations_manpage-DomainObject_objectType[`@DomainObject#objectType()`] annotation/attribute), then (as noted above) Isis will use the fully qualified class name of the entity.
-
-However, chances are that the fully qualified class name is liable to change over time, for example if the code is refactored or (more fundamentally) if your company/organization reorganizes/renames itself/is acquired.
-
-We therefore strongly recommend that you specify an object type for all entities, one way or another. Specifying `@Discriminator` will override `@PersistenceCapable`, which overrides `@DomainObject#objectType()`. Using `@PersistenceCapable#schema()` is probably the best choice in most cases.
-====
-
-[NOTE]
-====
-If the object type is not unique across all domain classes then the framework will fail-fast and fail to boot. An error message will be printed in the log to help you determine which classes have duplicate object tyoes.
-====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject.adoc
deleted file mode 100644
index ea6bc3e..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject.adoc
+++ /dev/null
@@ -1,105 +0,0 @@
-[[_ug_reference-annotations_manpage-DomainObject]]
-= `@DomainObject`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@DomainObject` annotation applies to domain objects, collecting together all domain semantics within a single annotation.
-
-The table below summarizes the annotation's attributes.
-
-.`@DomainObject` attributes
-[cols="2,2,4a", options="header"]
-|===
-
-| Attribute
-| Values (default)
-| Description
-
-
-|xref:_ug_reference-annotations_manpage-DomainObject_auditing[`auditing()`]
-|`AS_CONFIGURED`, `ENABLED`, `DISABLED` +
-(`AS_CONFIGURED`)
-|indicates whether each of the changed properties of an object should be submitted to the registered xref:_ug_reference-services-spi_manpage-AuditingService[`AuditingService`].
-
-
-|xref:_ug_reference-annotations_manpage-DomainObject_autoCompleteRepository[`autoCompleteRepository()`]
-|Domain service class
-|nominate a method on a domain service to be used for looking up instances of the domain object
-
-
-|`autoCompleteAction()`
-|Method name +
-(`autoComplete()`)
-|override the method name to use on the auto-complete repository
-
-
-|xref:_ug_reference-annotations_manpage-DomainObject_bounded[`bounded()`]
-|`true`, `false` +
-(`false`)
-|Whether the number of instances of this domain class is relatively small (a "bounded" set), such that instances could be selected from a drop-down list box or similar.
-
-
-|xref:_ug_reference-annotations_manpage-DomainObject_editing[`editing()`]
-|`AS_CONFIGURED`, `ENABLED`, `DISABLED` +
-(`AS_CONFIGURED`)
-|whether the object's properties and collections can be edited or not (ie whether the instance should be considered to be immutable)
-
-
-|xref:_ug_reference-annotations_manpage-DomainObject_nature[`nature()`]
-|`NOT_SPECIFIED`, `JDO_ENTITY`, `EXTERNAL_ENTITY`, `INMEMORY_ENTITY`, `VIEW_MODEL` (`NOT_SPECIFIED`)
-|whether the domain object logically is an entity (part of the domain layer) or is a view model (part of the application layer); and if an entity, how is its persistence managed
-
-
-|xref:_ug_reference-annotations_manpage-DomainObject_objectType[`objectType()`]
-|(none, which implies fully qualified class name)
-|specify an alias for the domain class used to uniquely identify the object both within the Isis runtime and externally
-
-
-|xref:_ug_reference-annotations_manpage-DomainObject_publishing[`publishing()`]
-|`AS_CONFIGURED`, `ENABLED`, `DISABLED` +
-(`AS_CONFIGURED`)
-|whether changes to the object should be published to the registered xref:_ug_reference-services-spi_manpage-PublishingService[`PublishingService`].
-
-
-|`publishing-` +
-`PayloadFactory()`
-|subtype of `PublishingPayloadFactory-` `ForObject` (none)
-|specifies that a custom implementation of `PublishingPayloadFactoryForObject` be used to create the (payload of the) published event representing the change to the object
-
-|===
-
-
-
-For example:
-
-[source,java]
-----
-@DomainObject(
- auditing=Auditing.ENABLED,
- autoCompleteRepository=CustomerRepository.class
- editing=Editing.ENABLED, // <1>
- publishing=Publishing.ENABLED
-)
-public class Customer {
- ...
-}
-----
-<1> default value, so could be omitted
-
-
-
-include::_ug_reference-annotations_manpage-DomainObject_auditing.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-DomainObject_autoCompleteRepository.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-DomainObject_bounded.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-DomainObject_editing.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-DomainObject_nature.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-DomainObject_objectType.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-DomainObject_publishing.adoc[leveloffset=+1]
-
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout.adoc
deleted file mode 100644
index a26e56e..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout.adoc
+++ /dev/null
@@ -1,115 +0,0 @@
-[[_ug_reference-annotations_manpage-DomainObjectLayout]]
-= `@DomainObjectLayout`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@DomainObjectLayout` annotation applies to domain classes, collecting together all UI hints within a single annotation.
-
-
-[NOTE]
-====
-For view models that have been annotated with `@ViewModel` the equivalent xref:_ug_reference-annotations_manpage-ViewModelLayout[`@ViewModelLayout`] can be used.
-====
-
-
-The table below summarizes the annotation's attributes.
-
-.`@DomainObjectLayout` attributes
-[cols="2,2,4a", options="header"]
-|===
-
-| Attribute
-| Values (default)
-| Description
-
-
-|xref:_ug_reference-annotations_manpage-DomainObjectLayout_bookmarking[`bookmarking()`]
-|`AS_ROOT`, `AS_CHILD`, `NEVER` +
-(`NEVER`)
-|whether (and how) this domain object should be automatically bookmarked
-
-
-|xref:_ug_reference-annotations_manpage-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:_ug_runtime_application-specific_application-css[`application.css`]
-
-
-|xref:_ug_reference-annotations_manpage-DomainObjectLayout_cssClassFa[`cssClassFa()`]
-|Any valid link:http://fortawesome.github.io/Font-Awesome/[Font awesome] icon name
-|specify a font awesome icon for the action's menu link or icon. +
-
-
-|`cssClassFaPosition()`
-|`LEFT`, `RIGHT` +
-(`LEFT`)
-|Currently unused.
-
-
-|xref:_ug_reference-annotations_manpage-DomainObjectLayout_describedAs[`describedAs()`]
-|String.
-|description of this class, eg to be rendered in a tooltip.
-
-
-
-|xref:_ug_reference-annotations_manpage-DomainObjectLayout_named[`named()`]
-|String.
-|to override the name inferred from the action's name in code. +
-
-A typical use case is if the desired name is a reserved Java keyword, such as `default` or `package`.
-
-
-|xref:_ug_reference-annotations_manpage-DomainObjectLayout_paged[`paged()`]
-|Positive integer
-|the page size for instances of this class when rendered within a table (as returned from an action invocation)
-
-
-|xref:_ug_reference-annotations_manpage-DomainObjectLayout_plural[`plural()`]
-|String.
-|the plural name of the class
-
-|===
-
-
-
-For example:
-
-[source,java]
-----
-@DomainObjectLayout(
- cssClass="x-key",
- cssClassFa="fa-checklist",
- describedAs="Capture a task that you need to do",
- named="ToDo",
- paged=30,
- plural="ToDo List")
-)
-public class ToDoItem {
- ...
-}
-----
-
-
-
-[NOTE]
-====
-Note that there is (currently) no support for specifying UI hints for domain objects through the dynamic xref:_ug_reference-object-layout_dynamic[`.layout.json`] file (only for properties, collections and actions are supported).
-====
-
-
-
-
-
-
-
-include::_ug_reference-annotations_manpage-DomainObjectLayout_bookmarking.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-DomainObjectLayout_cssClass.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-DomainObjectLayout_cssClassFa.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-DomainObjectLayout_describedAs.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-DomainObjectLayout_named.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-DomainObjectLayout_paged.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-DomainObjectLayout_plural.adoc[leveloffset=+1]
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_bookmarking.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_bookmarking.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_bookmarking.adoc
deleted file mode 100644
index 1a1188d..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_bookmarking.adoc
+++ /dev/null
@@ -1,66 +0,0 @@
-[[_ug_reference-annotations_manpage-DomainObjectLayout_bookmarking]]
-= `bookmarking()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `bookmarking()` attribute indicates that an entity is automatically bookmarked. This attribute is also supported for xref:_ug_reference-annotations_manpage-Action_bookmarking[domain objects].
-
-(In the Wicket viewer), a link to a bookmarked object is shown in the bookmarks panel:
-
-image::{_imagesdir}reference-annotations/DomainObjectLayout/bookmarking.png[width="720px",link="{_imagesdir}reference-annotations/DomainObjectLayout/bookmarking.png"]
-
-[NOTE]
-====
-Note that this screenshot shows an earlier version of the xref:_ug_wicket-viewer[Wicket viewer] UI (specifically, pre 1.8.0).
-====
-
-For example:
-
-[source,java]
-----
-@DomainObject(bookmarking=BookmarkPolicy.AS_ROOT)
-public class ToDoItem ... {
- ...
-}
-----
-
-indicates that the `ToDoItem` class is bookmarkable:
-
-
-It is also possible to nest bookmarkable entities. For example, this screenshot is taken from http://github.com/estatio/estatio[Estatio]:
-
-image::{_imagesdir}reference-annotations/DomainObjectLayout/bookmarking-nested.png[width="720px",link="{_imagesdir}reference-annotations/DomainObjectLayout/bookmarking-nested.png"]
-
-
-[NOTE]
-====
-Note that this screenshot shows an earlier version of the xref:_ug_wicket-viewer[Wicket viewer] UI (specifically, pre 1.8.0).
-====
-
-
-For example, the `Property` entity "[OXF] Oxford Super Mall" is a root bookmark, but the `Unit` child entity "[OXF-001] Unit 1" only appears as a bookmark _but only if_ its parent `Property` has already been bookmarked.
-
-This is accomplished with the following annotations:
-
-[source,java]
-----
-@DomainObject(bookmarking=BookmarkPolicy.AS_ROOT)
-public class Property { ... }
-----
-
-and
-
-[source,java]
-----
-@DomainObject(bookmarking=BookmarkPolicy.AS_CHILD)
-public abstract class Unit { ... }
-----
-
-The nesting can be done to any level; the Estatio screenshot also shows a bookmark nesting `Lease` > `LeaseItem` > `LeaseTerm` (3 levels deep).
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_cssClass.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_cssClass.adoc
deleted file mode 100644
index f34dfed..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_cssClass.adoc
+++ /dev/null
@@ -1,34 +0,0 @@
-[[_ug_reference-annotations_manpage-DomainObjectLayout_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()` attribute can be used to render additional CSS classes in the HTML (a wrapping `<div>`) that represents the domain object. xref:_ug_runtime_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:_ug_reference-annotations_manpage-DomainObjectLayout_cssClass[domain objects], xref:_ug_reference-annotations_manpage-ViewModelLayout_cssClass[view models], xref:_ug_reference-annotations_manpage-ActionLayout_cssClass[actions] xref:_ug_reference-annotations_manpage-PropertyLayout_cssClass[properties], xref:_ug_reference-annotations_manpage-CollectionLayout_cssClass[collections] and xref:_ug_reference-annotations_manpage-ParameterLayout_cssClass[parameters].
-
-
-For example:
-
-[source,java]
-----
-@DomainObject(
- cssClass="x-core-entity"
-)
-public class ToDoItem { ... }
-----
-
-
-
-
-[NOTE]
-====
-The similar xref:_ug_reference-annotations_manpage-DomainObjectLayout_cssClassFa[`@DomainObjectLayout#cssClassFa()`] annotation attribute is also used as a hint to apply CSS, but in particular to allow http://fortawesome.github.io/Font-Awesome/icons/[Font Awesome icons]
-to be rendered as the icon for classes.
-====
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_cssClassFa.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_cssClassFa.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_cssClassFa.adoc
deleted file mode 100644
index b689d4d..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_cssClassFa.adoc
+++ /dev/null
@@ -1,40 +0,0 @@
-[[_ug_reference-annotations_manpage-DomainObjectLayout_cssClassFa]]
-= `cssClassFa()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `cssClassFa()` attribute is used to specify the name of a link:http://fortawesome.github.io/Font-Awesome/icons/[Font Awesome icon] name, to be rendered as the domain object's icon.
-
-These attributes can also be applied to xref:_ug_reference-annotations_manpage-ViewModelLayout_cssClassFa[view models] to specify the object's icon, and to xref:_ug_reference-annotations_manpage-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:_ug_reference-methods_reserved_manpage-iconName[`iconName()`] method.
-
-
-
-For example:
-
-[source,java]
-----
-@DomainObjectLayout(
- cssClassFa="fa-check-circle"
-)
-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.
-
-
-The related `cssClassFaPosition()` attribute is currently unused for domain objects; the icon is always rendered to the left.
-
-
-[TIP]
-====
-The similar xref:_ug_reference-annotations_manpage-DomainObjectLayout_cssClass[`@DomainObjectLayout#cssClass()`] annotation attribute is also used as a hint
-to apply CSS, but for wrapping the representation of an object or object
-member so that it can be styled in an application-specific way.
-====
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_describedAs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_describedAs.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_describedAs.adoc
deleted file mode 100644
index 2e295a0..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_describedAs.adoc
+++ /dev/null
@@ -1,22 +0,0 @@
-[[_ug_reference-annotations_manpage-DomainObjectLayout_describedAs]]
-= `describedAs()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `describedAs()` attribute is used to provide a short description of the domain object to the user. In the xref:_ug_wicket-viewer[Wicket viewer] it is displayed as a 'tool tip'. The attribute can also be specified for xref:_ug_reference-annotations_manpage-CollectionLayout_describedAs[collections], xref:_ug_reference-annotations_manpage-PropertyLayout_describedAs[properties], xref:_ug_reference-annotations_manpage-ActionLayout_describedAs[actions], xref:_ug_reference-annotations_manpage-ParameterLayout_describedAs[parameters] and xref:_ug_reference-annotations_manpage-ViewModelLayout_describedAs[view models].
-
-For example:
-
-[source,java]
-----
-@DescribedAs("A customer who may have originally become known to us via " +
- "the marketing system or who may have contacted us directly.")
-public class ProspectiveSale {
- ...
-}
-----
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_named.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_named.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_named.adoc
deleted file mode 100644
index 2e35cad..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_named.adoc
+++ /dev/null
@@ -1,37 +0,0 @@
-[[_ug_reference-annotations_manpage-DomainObjectLayout_named]]
-= `named()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `named()` attribute explicitly specifies the domain object's name, overriding the name that would normally be inferred from the Java source code. The attribute can also be specified for xref:_ug_reference-annotations_manpage-ActionLayout_named[actions], xref:_ug_reference-annotations_manpage-CollectionLayout_named[collections], xref:_ug_reference-annotations_manpage-PropertyLayout_named[properties], xref:_ug_reference-annotations_manpage-ParameterLayout_named[parameters], xref:_ug_reference-annotations_manpage-ViewModelLayout_named[view models] and xref:_ug_reference-annotations_manpage-DomainServiceLayout_named[domain services].
-
-
-[TIP]
-====
-Following the link:http://en.wikipedia.org/wiki/Don%27t_repeat_yourself[don't repeat yourself] principle, we recommend that you only use this attribute when the desired name cannot be used in Java source code. Examples of that include a name that would be a reserved Java keyword (eg "package"), or a name that has punctuation, eg apostrophes.
-====
-
-
-For example:
-
-[source,java]
-----
-@DomainObjectLayout(
- named="Customer"
-)
-public class CustomerImpl implements Customer{
- ...
-}
-----
-
-It's also possible to specify a xref:_ug_reference-annotations_manpage-DomainObjectLayout_plural[plural form] of the name, used by the framework when rendering a standalone collection of the domain object.
-
-
-[TIP]
-====
-The framework also provides a separate, powerful mechanism for xref:_ug_more-advanced_i18n[internationalization].
-====
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_paged.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_paged.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_paged.adoc
deleted file mode 100644
index cbe0432..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_paged.adoc
+++ /dev/null
@@ -1,33 +0,0 @@
-[[_ug_reference-annotations_manpage-DomainObjectLayout_paged]]
-= `paged()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `paged()` attribute specifies the number of rows to display in a standalone collection, as returned from an action invocation. This attribute can also be applied to xref:_ug_reference-annotations_manpage-CollectionLayout_paged[collections] and xref:_ug_reference-annotations_manpage-ViewModelLayout_paged[view models].
-
-
-[WARNING]
-====
-The xref:_ug_restfulobjects-viewer[RestfulObjects viewer] currently does not support paging. The xref:_ug_wicket-viewer[Wicket viewer] _does_ support paging, but note that the paging is performed client-side rather than server-side.
-
-We therefore recommend that large collections should instead be modelled as actions (to allow filtering to be applied to limit the number of rows).
-====
-
-
-For example:
-
-[source,java]
-----
-@DomainObjectLayout(paged=15)
-public class Order {
- ...
-}
-----
-
-
-It is also possible to specify a global default for the page size of standalone collections, using the xref:_ug_runtime_configuring-core[configuration property] `isis.viewer.paged.standalone`.
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_plural.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_plural.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_plural.adoc
deleted file mode 100644
index 7b132ae..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObjectLayout_plural.adoc
+++ /dev/null
@@ -1,28 +0,0 @@
-[[_ug_reference-annotations_manpage-DomainObjectLayout_plural]]
-= `plural()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 Apache Isis displays a standalone collection of several objects, it will label the collection using the plural form of the object type.
-
-By default the plural name will be derived from the end of the singular name, with support for some basic English language defaults (eg using "ies" for names ending with a "y").
-
-The `plural()` attribute allows the plural form of the class name to be specified explicitly. This attribute is also supported for xref:_ug_reference-annotations_manpage-ViewModelLayout_plural[view models].
-
-For example:
-
-[source,java]
-----
-@DomainObjectLayout(plural="Children")
-public class Child {
- ...
-}
-----
-
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_auditing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_auditing.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_auditing.adoc
deleted file mode 100644
index 1bfef57..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_auditing.adoc
+++ /dev/null
@@ -1,38 +0,0 @@
-[[_ug_reference-annotations_manpage-DomainObject_auditing]]
-= `auditing()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `auditing()` attribute indicates that if the object is modified, then each of its changed properties should be submitted to the xref:_ug_reference-services-spi_manpage-AuditingService[`AuditingService`], if one has been configured.
-
-The default value for the attribute is `AS_CONFIGURED`, meaning that the xref:_ug_runtime_configuring-core[configuration property] `isis.services.audit.objects` is used to determine the whether the action is published:
-
-* `all` +
-+
-all changed objects are published
-
-* `none` +
-+
-no changed objects are published
-
-If there is no configuration property in `isis.properties` then auditing is automatically enabled for domain objects.
-
-This default can be overridden on an object-by-object basis; if `auditing()` is set to `ENABLED` then changed properties of instances of the domain class are audited irrespective of the configured value; if set to `DISABLED` then the changed properties of instances are _not_ audited, again irrespective of the configured value.
-
-For example:
-
-[source,java]
-----
-@DomainObject(
- auditing=Auditing.ENABLED // <1>
-)
-public class Customer {
- ...
-}
-----
-<1> because set to enabled, will be audited irrespective of the configured value.
-
-
-
[03/45] isis git commit: ISIS-1133: breaking out reference guide and
devenv guide;
moving appendices' release notes and migration notes to other docs;
improving the documentation page.
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_customisation_brand-logo.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_customisation_brand-logo.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_customisation_brand-logo.adoc
deleted file mode 100644
index 9572f74..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_customisation_brand-logo.adoc
+++ /dev/null
@@ -1,71 +0,0 @@
-[[_ug_wicket-viewer_customisation_brand-logo]]
-= Brand logo
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 Wicket viewer will display the application name top-left in the header menu. This can be changed to
-display a png logo instead.
-
-== Screenshots
-
-The screenshot below shows the Isis addons example https://github.com/isisaddons/isis-app-todoapp/[todoapp] (not ASF) with a 'brand logo' image in its header:
-
-image::{_imagesdir}wicket-viewer/brand-logo/brand-logo.png[width="750px",link="{_imagesdir}wicket-viewer/brand-logo/brand-logo.png"]
-
-A custom brand logo (typically larger) can also be specified for the signin page:
-
-image::{_imagesdir}wicket-viewer/brand-logo/brand-logo-signin.png[width="750px",link="{_imagesdir}wicket-viewer/brand-logo/brand-logo-signin.png"]
-
-
-
-
-== Configuration
-
-In the application-specific subclass of `IsisWicketApplication`, bind:
-
-* a string with name "brandLogoHeader" to the URL of a header image. A size of 160x40 works well.
-* a string with name "brandLogoSignin" to the URL of a image for the sign-in page. A size of 400x100 works well.
-
-For example:
-
-[source,java]
-----
-@Override
-protected Module newIsisWicketModule() {
- final Module isisDefaults = super.newIsisWicketModule();
-
- final Module overrides = new AbstractModule() {
- @Override
- protected void configure() {
- ...
- bind(String.class).annotatedWith(Names.named("brandLogoHeader"))
- .toInstance("/images/todoapp-logo-header.png");
- bind(String.class).annotatedWith(Names.named("brandLogoSignin"))
- .toInstance("/images/todoapp-logo-signin.png");
- ...
- }
- };
-
- return Modules.override(isisDefaults).with(overrides);
-}
-----
-
-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:_ug_runtime_application-specific_application-css[`application.css`]. For example, a logo with height 40px works well with the following:
-
-[source,css]
-----
-.navbar-brand img {
- margin-top: -5px;
- margin-left: 5px;
-}
-----
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_customisation_cheap-n-cheerful-theme.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_customisation_cheap-n-cheerful-theme.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_customisation_cheap-n-cheerful-theme.adoc
deleted file mode 100644
index 7ad6257..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_customisation_cheap-n-cheerful-theme.adoc
+++ /dev/null
@@ -1,29 +0,0 @@
-[[_ug_wicket-viewer_customisation_cheap-n-cheerful-theme]]
-= Cheap-n-cheerful "theme"
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 application name (as defined in the `IsisWicketApplication` subclass) is also used (in sanitized form) as the CSS class in a `<div>` that wraps all the rendered content of every page.
-
-For example, if the application name is "ToDo App", then the `<div>` generated is:
-
-[source,html]
-----
-<div class="todo-app">
- ...
-</div>
-----
-
-You can therefore use this CSS class as a way of building your own "theme" for the various elements of the wicket viewer pages.
-
-[TIP]
-====
-Alternatively you could "do it properly" and create your xref:_ug_extending_wicket-viewer_custom-bootstrap-theme[own Bootstrap theme], as described in the <<Extending>> chapter.
-====
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_customisation_custom-javascript.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_customisation_custom-javascript.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_customisation_custom-javascript.adoc
deleted file mode 100644
index 919bbf3..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_customisation_custom-javascript.adoc
+++ /dev/null
@@ -1,42 +0,0 @@
-[[_ug_wicket-viewer_customisation_custom-javascript]]
-= Custom Javascript
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 Wicket viewer ships with embedded JQuery, so this can be leveraged to perform arbitrary transformations of the rendered page (eg to run some arbitrary JQuery on page load).
-
-[WARNING]
-====
-Just because something is possible, it doesn't necessarily mean we encourage it. Please be aware that there is no formal API for any custom javascript that you might implement to target; future versions of Isis might break your code.
-
-If possible, consider using the `ComponentFactory` API described in the xref:_ug_extending_wicket-viewer[Extending] chapter.
-====
-
-To register your Javascript code, adjusting the Guice bindings (part of Isis' bootstrapping) in your custom subclass of `IsisWicketApplication`:
-
- public class MyAppApplication extends IsisWicketApplication {
- @Override
- protected Module newIsisWicketModule() {
- final Module isisDefaults = super.newIsisWicketModule();
- final Module myAppOverrides = new AbstractModule() {
- @Override
- protected void configure() {
- ...
- bind(String.class)
- .annotatedWith(Names.named("applicationJs"))
- .toInstance("scripts/application.js");
- ...
- }
- };
- return Modules.override(isisDefaults).with(myAppOverrides);
- }
- }
-
-Currently only one such `.js` file can be registered.
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_customisation_default-theme.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_customisation_default-theme.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_customisation_default-theme.adoc
deleted file mode 100644
index 69518bb..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_customisation_default-theme.adoc
+++ /dev/null
@@ -1,29 +0,0 @@
-[[_ug_wicket-viewer_customisation_default-theme]]
-= Specifying a default theme
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 Isis Wicket viewer uses http://getbootstrap.com/[Bootstrap] styles and components (courtesy of the https://github.com/l0rdn1kk0n/wicket-bootstrap[Wicket Bootstrap] integration).
-
-Unless specified otherwise, the viewer uses the default bootstrap theme. However, this can be changed by overriding `init()` in the application's subclass of `IsisWicketApplication`. For example, to set the http://bootswatch.com/flatly/[bootswatch.com flatly] theme
- as the default, use:
-
-[source,java]
-----
-@Override
-protected void init() {
- super.init();
- IBootstrapSettings settings = Bootstrap.getSettings();
- settings.setThemeProvider(new BootswatchThemeProvider(BootswatchTheme.Flatly));
-}
-----
-
-If you have developed a custom Bootstrap theme (as described xref:_ug_extending_wicket-viewer_custom-bootstrap-theme[here]) then this can also be specified using the https://github.com/l0rdn1kk0n/wicket-bootstrap/wiki/Themes[Wicket Bootstrap API].
-
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_customisation_tweaking-css-classes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_customisation_tweaking-css-classes.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_customisation_tweaking-css-classes.adoc
deleted file mode 100644
index b619cc4..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_customisation_tweaking-css-classes.adoc
+++ /dev/null
@@ -1,109 +0,0 @@
-[[_ug_wicket-viewer_customisation_tweaking-css-classes]]
-= Tweaking CSS 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 HTML generated by the Wicket viewer include plenty of CSS classes so that you can easily target the required elements as required. For example, you could use CSS to suppress the entity's icon alongside its title. This would be done using:
-
-[source,css]
-----
-.entityIconAndTitlePanel a img {
- display: none;
-}
-----
-
-These customizations should generally be added to xref:_ug_runtime_application-specific_application-css[`application.css]`; this file is included by default in every webpage served up by the Wicket viewer.
-
-
-
-== Targeting individual members
-
-For example, the `ToDoItem` object of the Isis addons example https://github.com/isisaddons/isis-app-todoapp/[todoapp] (not ASF) has a `notes` property. The HTML for this will be something like:
-
-[source,html]
-----
-<div>
- <div class="property ToDoItem-notes">
- <div class="multiLineStringPanel scalarNameAndValueComponentType">
- <label for="id83" title="">
- <span class="scalarName">Notes</span>
- <span class="scalarValue">
- <textarea
- name="middleColumn:memberGroup:1:properties:4:property:scalarIfRegular:scalarValue"
- disabled="disabled"
- id="id83" rows="5" maxlength="400" size="125"
- title="">
- </textarea>
- <span>
- </span>
- </span>
- </label>
- </div>
- </div>
-</div>
-----
-
-The xref:_ug_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:
-
-[source,css]
-----
-div.ToDoItem-notes span.scalarValue {
- display: none;
-}
-----
-
-You can use a similar approach for collections and actions.
-
-
-
-
-== Targeting members through a custom CSS style
-
-The above technique works well if you know the class member to target, but you might instead want to apply a custom style to a set of members. For this, you can use the `@CssClass`.
-
-For example, in the `ToDoItem` class the following annotation (indicating that this is a key, important, property) :
-
-[source,java]
-----
-@PropertyLayout(cssClass="x-myapp-highlight")
-public LocalDate getDueBy() {
- return dueBy;
-}
-----
-
-would generate the HTML:
-
-[source,html]
-----
-<div>
- <div class="property ToDoItem-dueBy x-myapp-highlight">
- ...
- </div>
-</div>
-----
-
-This can then be targeted, for example using:
-
-[source,css]
-----
-div.x-myapp-highlight span.scalarName {
- color: red;
-}
-----
-
-Note also that instead of using `@PropertyLayout(cssClass=...)` annotation, you can also specify the CSS style using a xref:_ug_reference-object-layout_dynamic[dynamic layout] JSON file:
-
-[source,javascript]
-----
-"dueBy": {
- "propertyLayout": {
- "cssClass": "x-myapp-important"
- }
-},
-----
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_customisation_using-different-css-file.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_customisation_using-different-css-file.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_customisation_using-different-css-file.adoc
deleted file mode 100644
index 118d831..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_customisation_using-different-css-file.adoc
+++ /dev/null
@@ -1,36 +0,0 @@
-[[_ug_wicket-viewer_customisation_using-different-css-file]]
-= Using a different CSS file
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 for some reason you wanted to name the CSS file differently (eg `stylesheets/myapp.css`), then adjust the Guice bindings (part of Isis' bootstrapping) in your custom subclass of `IsisWicketApplication`:
-
-[source,java]
-----
-public class MyAppApplication extends IsisWicketApplication {
- @Override
- protected Module newIsisWicketModule() {
- final Module isisDefaults = super.newIsisWicketModule();
- final Module myAppOverrides = new AbstractModule() {
- @Override
- protected void configure() {
- ...
- bind(String.class)
- .annotatedWith(Names.named("applicationCss"))
- .toInstance("stylesheets/myapp.css");
- ...
- }
- };
-
- return Modules.override(isisDefaults).with(myAppOverrides);
- }
-}
-----
-
-As indicated above, this file is resolved relative to `src/main/webapp`.
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_customisation_welcome-page.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_customisation_welcome-page.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_customisation_welcome-page.adoc
deleted file mode 100644
index bb3d26c..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_customisation_welcome-page.adoc
+++ /dev/null
@@ -1,42 +0,0 @@
-[[_ug_wicket-viewer_customisation_welcome-page]]
-= Welcome page
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-It's possible to customize the application name, welcome message and about message can also be customized. This is done by adjusting the Guice bindings (part of Isis' bootstrapping) in your custom subclass of `IsisWicketApplication`:
-
-[source,java]
-----
-public class MyAppApplication extends IsisWicketApplication {
- @Override
- protected Module newIsisWicketModule() {
- final Module isisDefaults = super.newIsisWicketModule();
- final Module myAppOverrides = new AbstractModule() {
- @Override
- protected void configure() {
- ...
- bind(String.class)
- .annotatedWith(Names.named("applicationName"))
- .toInstance("My Wonderful App");
- bind(String.class)
- .annotatedWith(Names.named("welcomeMessage"))
- .toInstance(readLines("welcome.html")); // <1>
- bind(String.class)
- .annotatedWith(Names.named("aboutMessage"))
- .toInstance("My Wonderful App v1.0");
- ...
- }
- };
-
- return Modules.override(isisDefaults).with(myAppOverrides);
- }
-}
-----
-<1> the `welcome.html` file is resolved relative to `src/main/webapp`.
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features.adoc
deleted file mode 100644
index 0345b5b..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features.adoc
+++ /dev/null
@@ -1,26 +0,0 @@
-[[_ug_wicket-viewer_features]]
-= Features/end-user usage
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 features of the wicket viewer from the perspective of an end-user actually using your Isis application.
-
-
-include::_ug_wicket-viewer_features_recent-pages.adoc[leveloffset=+1]
-include::_ug_wicket-viewer_features_bookmarked-pages.adoc[leveloffset=+1]
-include::_ug_wicket-viewer_features_hints-and-copy-url.adoc[leveloffset=+1]
-include::_ug_wicket-viewer_features_titles-in-tables.adoc[leveloffset=+1]
-include::_ug_wicket-viewer_features_file-upload-download.adoc[leveloffset=+1]
-include::_ug_wicket-viewer_features_user-registration.adoc[leveloffset=+1]
-
-
-
-
-
-
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features_bookmarked-pages.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features_bookmarked-pages.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features_bookmarked-pages.adoc
deleted file mode 100644
index 2a99ea5..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features_bookmarked-pages.adoc
+++ /dev/null
@@ -1,107 +0,0 @@
-[[_ug_wicket-viewer_features_bookmarked-pages]]
-= Bookmarked pages
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 Wicket viewer supports the bookmarking of both domain objects and query-only (xref:_ug_reference-annotations_manpage-Action_semantics[@Action(semantics=...)]) actions.
-
-Domain objects, if bookmarkable, can be nested.
-
-Bookmarking is automatic; whenever a bookmarkable object/action is visited, then a bookmark is created. To avoid the number of bookmarks from indefinitely growing, bookmarks that have not been followed after a whle are automatically removed (an MRU/LRU algorithm). The number of bookmarks to preserve can be configured.
-
-
-
-
-== Screenshots
-
-The following screenshot, taken from https://github.com/isisaddons/isis-app-todoapp[Isisaddons example todoapp] (not ASF) shows how the bookmarks are listed in a sliding panel.
-
-image::{_imagesdir}wicket-viewer/bookmarked-pages/panel.png[width="800px",link="{_imagesdir}wicket-viewer/bookmarked-pages/panel.png"]
-
-[NOTE]
-====
-Note that these screenshots show an earlier version of the xref:_ug_wicket-viewer[Wicket viewer] UI (specifically, pre 1.8.0).
-====
-
-Note how the list contains both domain objects and an action ("not yet complete").
-
-Bookmarks can also form a hierarchy. The following screenshot, also taken from the https://github.com/estatio/estatio[Estatio] application, shows a variety of different bookmarked objects with a nested structure:
-
-image::{_imagesdir}wicket-viewer/bookmarked-pages/panel-estatio.png[width="800px",link="{_imagesdir}wicket-viewer/bookmarked-pages/panel-estatio.png"]
-
-Some - like `Property`, `Lease` and `Party` - are root nodes. However, `LeaseItem` is bookmarkable as a child of `Lease`, and `LeaseTerm` is bookmarkable only as a child of `LeaseItem`. This parent/child relationship is reflected in the layout.
-
-
-
-
-== Domain Code
-
-To indicate a class is bookmarkable, use the xref:_ug_reference-annotations_manpage-DomainObjectLayout[@DomainObjectLayout] annotation:
-
-[source,java]
-----
-@DomainObjectLayout(
- bookmarking=BookmarkPolicy.AS_ROOT
-)
-public class Lease { ... }
-----
-
-To indicate a class is bookmarkable but only as a child of some parent bookmark, specify the bookmark policy:
-
-[source,java]
-----
-@DomainObjectLayout(
- bookmarking=BookmarkPolicy.AS_CHILD
-)
-public class LeaseItem { ... }
-----
-
-To indicate that a safe (query only) action is bookmarkable, use the xref:_ug_reference-annotations_manpage-ActionLayout[@ActionLayout] annotation:
-
-[source,java]
-----
-public class ToDoItem ... {
- ...
- @ActionLayout(
- bookmarking=BookmarkPolicy.AS_ROOT
- )
- @ActionSemantics(Of.SAFE)
- public List<ToDoItem> notYetComplete() { ... }
- ...
-}
-----
-
-[NOTE]
-====
-The BookmarkPolicy.AS_CHILD does not have a meaning for actions; if the `bookmarking` attribute is set to any other value, it will be ignored.
-====
-
-
-
-
-== User Experience
-
-The sliding panel appears whenever the mouse pointer hovers over the thin blue tab (to the left of the top header region).
-
-Alternatively, `alt+[` will toggle open/close the panel; it can also be closed using `Esc` key.
-
-
-=== Related functionality
-
-The xref:_ug_wicket-viewer_features_recent-pages[Recent Pages] also lists recently visited pages, selected from a drop-down.
-
-
-
-
-
-== Configuration
-
-By default, the bookmarked pages panel will show a maximum of 15 'root' pages. This can be overridden using a property (in `isis.properties`), for example:
-
-[source,ini]
-----
-isis.viewer.wicket.bookmarkedPages.maxSize=20
-----
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features_file-upload-download.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features_file-upload-download.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features_file-upload-download.adoc
deleted file mode 100644
index c7d3032..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features_file-upload-download.adoc
+++ /dev/null
@@ -1,121 +0,0 @@
-[[_ug_wicket-viewer_features_file-upload-download]]
-= File upload/download
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 Isis application library provides the xref:_ug_reference-classes_value-types_manpage-Blob[Blob] value type (binary large objects) and also the xref:_ug_reference-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:
-
-
-
-
-== Screenshots
-
-The following screenshots are taken from the Isis addons example https://github.com/isisaddons/isis-app-todoapp[todoapp] (not ASF):
-
-
-
-=== View mode, empty
-
-`Blob` field rendered as attachment (with no data):
-
-image::{_imagesdir}wicket-viewer/file-upload-download/010-attachment-field-940.png[width="800px",link="{_imagesdir}wicket-viewer/file-upload-download/010-attachment-field.png"]
-
-[NOTE]
-====
-Note that these screenshots show an earlier version of the xref:_ug_wicket-viewer[Wicket viewer] UI (specifically, pre 1.8.0).
-====
-
-
-=== Edit mode
-
-Hit edit; 'choose file' button appears:
-
-image::{_imagesdir}wicket-viewer/file-upload-download/020-edit-choose-file-940.png[width="800px",link="{_imagesdir}wicket-viewer/file-upload-download/020-edit-choose-file.png"]
-
-
-
-=== Choose file
-
-Choose file using the regular browser window:
-
-image::{_imagesdir}wicket-viewer/file-upload-download/030-choose-file-using-browser-520.png[width="520px",link="{_imagesdir}wicket-viewer/file-upload-download/030-choose-file-using-browser.png"]
-
-
-Chosen file is indicated:
-
-image::{_imagesdir}wicket-viewer/file-upload-download/040-edit-chosen-file-indicated-940.png[width="800px",link="{_imagesdir}wicket-viewer/file-upload-download/040-edit-chosen-file-indicated.png"]
-
-
-
-=== Image rendered
-
-Back in view mode (ie once hit OK) if the `Blob` is an image, then it is shown:
-
-image::{_imagesdir}wicket-viewer/file-upload-download/050-ok-if-image-then-rendered-940.png[width="800px",link="{_imagesdir}wicket-viewer/file-upload-download/050-ok-if-image-then-rendered.png"]
-
-
-
-=== Download
-
-`Blob` can be downloaded:
-
-image::{_imagesdir}wicket-viewer/file-upload-download/060-download-940.png[width="800px",link="{_imagesdir}wicket-viewer/file-upload-download/060-download.png"]
-
-
-
-=== Clear
-
-Back in edit mode, can choose a different file or clear (assuming property is not mandatory):
-
-image::{_imagesdir}wicket-viewer/file-upload-download/070-edit-clear-940.png[width="800px",link="{_imagesdir}wicket-viewer/file-upload-download/070-edit-clear.png"]
-
-
-
-
-
-== Domain Code
-
-To define a `Blob`, use:
-
-[source,java]
-----
-private Blob attachment;
-@javax.jdo.annotations.Persistent(defaultFetchGroup="false")
- @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 = "BLOB")
- })
-@Property(
- domainEvent = AttachmentDomainEvent.class,
- optionality = Optionality.OPTIONAL
-)
-public Blob getAttachment() { return attachment; }
-public void setAttachment(final Blob attachment) { this.attachment = attachment; }
-----
-
-To define a `Clob`, use:
-
-[source,java]
-----
-private Clob doc;
-@javax.jdo.annotations.Persistent(defaultFetchGroup="false", columns = {
- @javax.jdo.annotations.Column(name = "doc_name"),
- @javax.jdo.annotations.Column(name = "doc_mimetype"),
- @javax.jdo.annotations.Column(name = "doc_chars", jdbcType = "CLOB", sqlType = "CLOB")
-})
-@Property(
- optionality = Optionality.OPTIONAL
-)
-public Clob getDoc() { return doc; }
-public void setDoc(final Clob doc) { this.doc = doc; }
-----
-
-The `Blob` and `Clob` types can also be used as parameters to actions.
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features_hints-and-copy-url.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features_hints-and-copy-url.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features_hints-and-copy-url.adoc
deleted file mode 100644
index 71ae3a8..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features_hints-and-copy-url.adoc
+++ /dev/null
@@ -1,79 +0,0 @@
-[[_ug_wicket-viewer_features_hints-and-copy-url]]
-= Hints and copy URL
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-While the user can often copy the URL of a domain object directly from the browser's address bar, the Wicket viewer also allows the URL of domain objects to be easily copied from a dialog.
-
-More interestingly, this URL can also contain hints capturing any sorting or page numbering, or hiding/viewing of collections. End-users can therefore share these URLs as a form of deep linking into a particular view on a domain object.
-
-The copy URL and hinting is automatic.
-
-
-
-
-== Screenshots
-
-The following screenshots are taken from the [Estatio](https://github.com/estatio/estatio) application.
-
-=== Copy URL
-
-This screenshot shows the copy URL button (top right):
-
-image::{_imagesdir}wicket-viewer/copy-link/010-copy-link-button.png[width="800px",link="{_imagesdir}wicket-viewer/copy-link/010-copy-link-button.png"]
-
-[NOTE]
-====
-Note that these screenshots show an earlier version of the xref:_ug_wicket-viewer[Wicket viewer] UI (specifically, pre 1.8.0).
-====
-
-Clicking on this button brings up a dialog with the URL preselected:
-
-image::{_imagesdir}wicket-viewer/copy-link/020-copy-link-dialog.png[width="800px",link="{_imagesdir}wicket-viewer/copy-link/020-copy-link-dialog.png"]
-
-
-The URL in this case is something like:
-
- http://localhost:8080/wicket/entity/org.estatio.dom.lease.Lease:0
-
-The user can copy the link (eg `ctrl+C`) into the clipboard, then hit `OK` or `Esc` to dismiss the dialog.
-
-
-=== Hints
-
-Using the viewer the user can hide/show collection tables, can sort the tables by header columns:
-
-image::{_imagesdir}wicket-viewer/copy-link/030-hints.png[width="800px",link="{_imagesdir}wicket-viewer/copy-link/030-hints.png"]
-
-
-Also, if the collection spans multiple pages, then the individual page can be selected.
-
-Once the view has been customised, the URL shown in the copy URL dialog is in an extended form:
-
-image::{_imagesdir}wicket-viewer/copy-link/040-copy-link-with-hints.png[width="800px",link="{_imagesdir}wicket-viewer/copy-link/040-copy-link-with-hints.png"]
-
-The URL in this case is something like:
-
- http://localhost:8080/wicket/entity/org.estatio.dom.lease.Lease:0?hint-1:collectionContents-view=3&hint-1:collectionContents:collectionContents-3:table-DESCENDING=value&hint-1:collectionContents:collectionContents-3:table-pageNumber=0&hint-2:collectionContents-view=0&hint-2:collectionContents:collectionContents-2:table-pageNumber=0&hint-3:collectionContents-view=2&hint-3:collectionContents:collectionContents-2:table-pageNumber=0&hint-4:collectionContents-view=3&hint-4:collectionContents:collectionContents-3:table-ASCENDING=exerciseDate&hint-4:collectionContents:collectionContents-3:table-pageNumber=0&hint-5:collectionContents-view=0&hint-5:collectionContents:collectionContents-3:table-pageNumber=0
-
-
-
-=== Copy URL from title
-
-When the user invokes an action on the object, the URL (necessarily) changes to indicate that the action was invoked. This URL is specific to the user's session and cannot be shared with others.
-
-A quick way for the user to grab a shareable URL is simply by clicking on the object's title:
-
-image::{_imagesdir}wicket-viewer/copy-link/050-title-url.png[width="800px",link="{_imagesdir}wicket-viewer/copy-link/050-title-url.png"]
-
-
-
-
-== User Experience
-
-The copy URL dialog is typically obtained by clicking on the icon.
-
-Alternatively, `alt+]` will also open the dialog. It can be closed with either `OK` or the `Esc` key.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features_recent-pages.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features_recent-pages.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features_recent-pages.adoc
deleted file mode 100644
index aedc999..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features_recent-pages.adoc
+++ /dev/null
@@ -1,53 +0,0 @@
-[[_ug_wicket-viewer_features_recent-pages]]
-= Recent pages (drop down)
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 Wicket viewer provides a recent pages drop-down that acts as a breadcrumb trail. Using it, the user can quickly open a recently accessed domain object.
-
-
-
-== Screenshots
-
-The following screenshot, taken from the https://github.com/estatio/estatio[Estatio] application, shows the recent pages drop-down after a number of pages have been accessed.
-
-image::{_imagesdir}wicket-viewer/recent-pages/recent-pages.png[width="800px",link="{_imagesdir}wicket-viewer/recent-pages/recent-pages.png"]
-
-
-[NOTE]
-====
-Note that this screenshot show an earlier version of the xref:_ug_wicket-viewer[Wicket viewer] UI (specifically, pre 1.8.0).
-====
-
-
-
-
-
-== Domain Code
-
-The recent pages drop-down is automatically populated; no changes need to be made to the domain classes.
-
-
-
-
-== User Experience
-
-Selecting the domain object from the list causes the viewer to automatically navigate to the page for the selected object.
-
-
-
-
-== Related functionality
-
-The xref:_ug_wicket-viewer_features_bookmarked-pages[bookmarked pages] (sliding panel) also provides links to recently visited objects, but only those explicitly marked as `@DomainObject(bookmarking=...)`. The bookmarks panel also nests related objects together hierarchically (the recent pages drop-down does not).
-
-
-
-
-== Configuration
-
-The number of objects is hard-coded as 10; it cannot currently be configured.
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features_titles-in-tables.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features_titles-in-tables.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features_titles-in-tables.adoc
deleted file mode 100644
index 2e8f92f..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features_titles-in-tables.adoc
+++ /dev/null
@@ -1,76 +0,0 @@
-[[_ug_wicket-viewer_features_titles-in-tables]]
-= Titles 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/
-
-
-Object titles can often be quite long if the intention is to uniquely identify the object. While this is appropriate for the object view, it can be cumbersome within tables.
-
-If an object's title is specified with from `@Title` annotation then the Wicket viewer will (for parented collections) automatically "contextualize" a title by excluding the part of the title corresponding to a reference to the owning (parent) object.
-
-In other words, suppose we have:
-
-image::{_imagesdir}how-tos/ui-hints/object-titles-and-icons/cust-order-product.png[width="579px",link="{_imagesdir}how-tos/ui-hints/object-titles-and-icons/cust-order-product.png"]
-
-so that `Customer` has a collection of `Order`s:
-
-[source,java]
-----
-public class Customer {
- public Set<Order> getOrders() { ... }
- ...
-}
-----
-
-and `Product` also has a collection of `Order`s (please forgive the suspect domain modelling in this example (!)):
-
-[source,java]
-----
-public class Product {
- public Set<Order> getOrders() { ... }
- ...
-}
-----
-
-and where the `Order` class references both `Customer` and `Product`.
-
-The `Order`'s might involve each of these:
-
-[source,java]
-----
-public class Order {
- @Title(sequence="1")
- public Customer getCustomer() { ... }
- @Title(sequence="2")
- public Product getProduct() { ... }
- @Title(sequence="3")
- public String getOtherInfo() { ... }
- ...
-}
-----
-
-In this case, if we view a `Customer` with its collection of `Order`s, then in that parented collection's table the customer's property will be automatically excluded from the title of the `Order` (but it would show the product). Conversely, if a `Product` is viewed then its collection of `Order`s would suppress product (but would show the customer).
-
-[TIP]
-====
-This feature is a close cousin of the `@PropertyLayout(hidden=Where.REFERENCES_PARENT)` annotation, which will cause the property itself to be hidden as a column in the table. An Isis idiom is therefore:
-
-[source,java]
-----
-public class Order {
- @Title(sequence="1")
- @PropertyLayout(hidden=Where.REFERENCES_PARENT)
- public Customer getCustomer() { ... }
- ...
-}
-----
-
-====
-
-The above annotations mean that titles usually "just work", altering according to the context in which they are viewed.
-
-[TIP]
-====
-It is also possible to configure the Wicket viewer to xref:_ug_wicket-viewer_configuration-properties_abbreviating-titles[abbreviate titles or suppress them] completely.
-====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features_user-registration.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features_user-registration.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features_user-registration.adoc
deleted file mode 100644
index 9e64496..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features_user-registration.adoc
+++ /dev/null
@@ -1,81 +0,0 @@
-[[_ug_wicket-viewer_features_user-registration]]
-= User Registration
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 Wicket viewer provides the ability for users to sign-up by providing a valid email address:
-
-* from the login page the user can instead follow a link to take them to a sign-up page, where they enter their email address.
-* a verification email is sent using this service; the email includes a link back to the running application.
-* the user then completes the registration process by choosing a user name and password.
-* the Wicket viewer then creates an account for them and logs them in.
-
-In a similar way, if the user has forgotten their password then they can request a reset link to be sent to their email, again by providing their email address.
-
-To support this the framework requires three services to be registered and configured:
-
-* the xref:_ug_reference-services-spi_manpage-UserRegistrationService[user registration service], which provides an API to create the user account
-* the xref:_ug_reference-services-spi_manpage-EmailNotificationService[email notification service], which provides an API for to send the verification emails
-* the xref:_ug_reference-services-api_manpage-EmailService[email service], that is used by the email notification service to actually send the email.
-
-The Isis core framework provides a default implementation of both the email notification service and the email service. If your application uses the https://github.com/isisaddons/isis-module-security[Isis addons security module] (not ASF) then an implementation is provided by that module; just add to the classpath. Otherwise you will need to provide your own implementation.
-
-[NOTE]
-====
-There is _no_ default implementation of the user registration service in the core framework.
-====
-
-
-
-== Screenshots
-
-The user is presented with a login page:
-
-image::{_imagesdir}wicket-viewer/user-registration/login-page-default.png[width="300px",link="{_imagesdir}wicket-viewer/user-registration/login-page-default.png"]
-
-
-Navigate to the sign up page. Complete the page, and verify:
-
-image::{_imagesdir}wicket-viewer/user-registration/sign-up-page.png[width="300px",link="{_imagesdir}wicket-viewer/user-registration/sign-up-page.png"]
-
-
-Back to the login page:
-
-image::{_imagesdir}wicket-viewer/user-registration/sign-up-login-page-after-sign-up.png[width="300px",link="{_imagesdir}wicket-viewer/user-registration/sign-up-login-page-after-sign-up.png"]
-
-
-Email arrives, with link:
-
-image::{_imagesdir}wicket-viewer/user-registration/sign-up-email-with-verification-link.png[width="500px",link="{_imagesdir}wicket-viewer/user-registration/sign-up-email-with-verification-link.png"]
-
-
-Follow the link, complete the page:
-
-image::{_imagesdir}wicket-viewer/user-registration/sign-up-registration-page.png[width="300px",link="{_imagesdir}wicket-viewer/user-registration/sign-up-registration-page.png"]
-
-
-Automatically logged in:
-
-image::{_imagesdir}wicket-viewer/user-registration/sign-up-after-registration.png[width="800px",link="{_imagesdir}wicket-viewer/user-registration/sign-up-after-registration.png"]
-
-
-
-
-== Configuration
-
-There are two prerequisites:
-
-* register an implementation of the xref:_user_registration_service[user registration service] (eg by using the https://github.com/isisaddons/isis-module-security[Isis addons security module])
-
-* configure the xref:_ug_reference-services-api_manpage-EmailService[email service]
-
-The latter is required if you are using the default email notification service and email service. If you are using your own alternative implementation of the email notification service then it may be omitted (and configure your own alternative implementation as required).
-
-It is also possible to configure the Wicket viewer to suppress xref:_ug_wicket-viewer_configuration-properties_suppressing-sign-up[the sign-up page link] and/or the xref:_ug_wicket-viewer_configuration-properties_suppressing-password-reset[password reset page].
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_isis-addons.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_isis-addons.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_isis-addons.adoc
deleted file mode 100644
index 2e499d7..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_isis-addons.adoc
+++ /dev/null
@@ -1,33 +0,0 @@
-[[_ug_wicket-viewer_isis-addons]]
-= Isis Add-ons (not ASF)
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 (non-ASF) link:http://www.isisaddons.org[Isis Addons] website provides a number of extensions to the Wicket viewer (leveraging the APIs described in <<Extending the Wicket viewer>> section, later. While you are free to fork and adapt any of them to your needs, they are also intended for use "out-of-the-box".
-
-[WARNING]
-====
-Note that Isis addons, while maintained by Isis committers, are not part of the ASF.
-====
-
-This short section gives an overview of their capabilities. For full information, check out the README on their respective github repo. Each wicket extension also includes a demo app so you can (a) see what the extension does and (b) see how to use it within your own code.
-
-
-== Excel download
-
-IMPORTANT: TODO
-
-== Fullcalendar2
-
-IMPORTANT: TODO
-
-== Gmap3
-
-IMPORTANT: TODO
-
-== Wicked charts
-
-IMPORTANT: TODO
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_layout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_layout.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_layout.adoc
deleted file mode 100644
index f373eff..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_layout.adoc
+++ /dev/null
@@ -1,97 +0,0 @@
-[[_ug_wicket-viewer_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/
-
-
-
-The wicket viewer has full support for the various methods of specifying the xref:_ug_reference-object-layout[layout of objects], either statically or dynamically.
-
-Dynamic reloading is automatically supported when running in xref:_ug_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.
-
-
-[TIP]
-====
-To pick up a change, edit the `.layout.json` file in the IDE and rebuild. Then click on the title of the object _*twice*_.
-
-The first click will cause Isis to pick up the new metadata, but too late in the process to adjust the rendering. The second click will re-render the object with the new metadata.
-====
-
-
-The screenshots below show some of the effects that can be accomplished, for the open source link:https://github.com/estatio/estatio[Estatio] app.
-
-
-
-First, an `Invoice`. This places the properties in three equal-sized columns, with collections underneath:
-
-image::{_imagesdir}wicket-viewer/layouts/estatio-Invoice.png[width="800px",link="{_imagesdir}wicket-viewer/layouts/estatio-Invoice.png"]
-
-
-
-Next, `Lease`. This places its properties in two columns (one wide, one narrow), with its collections shown in the right-most column:
-
-image::{_imagesdir}wicket-viewer/layouts/estatio-Lease.png[width="800px",link="{_imagesdir}wicket-viewer/layouts/estatio-Lease.png"]
-
-
-
-Next, `LeaseItem`. This is similar to `Lease`, with two columns for properties and the third column for collections:
-
-image::{_imagesdir}wicket-viewer/layouts/estatio-LeaseItem.png[width="800px",link="{_imagesdir}wicket-viewer/layouts/estatio-LeaseItem.png"]
-
-
-
-And finally, from the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp], its `ToDoItem`. This puts its properties in two columns; the collections (not visible in the screenshot below) are underneath (like Estatio's `Invoice`):
-
-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_reference-object-layout[object layout] chapter.
-
-
-
-== Screencast
-
-How to layout properties and collections dynamically, in the Wicket viewer.
-
-video::zmrg49WeEPc[youtube,width="530px",height="354px"]
-
-
-
-[NOTE]
-====
-Note that this screencast shows an earlier version of the xref:_ug_wicket-viewer[Wicket viewer] UI (specifically, pre 1.8.0).
-====
-
-
-
-
-== Required updates to the dom project's pom.xml
-
-If using the `.layout.json` files, these must be compiled and available in the classpath. When using an IDE such as Eclipse+M2E, any `.layout.json` files in `src/main/java` or `src/main/resources` will be part of the classpath automatically. However, unless the `pom.xml` is changed, these will not be part of the compiled WAR.
-
-Therefore, make sure the following is added to the dom project's `pom.xml`:
-
-[source.xml]
-----
-<resources>
- <resource>
- <filtering>false</filtering>
- <directory>src/main/resources</directory>
- </resource>
- <resource>
- <filtering>false</filtering>
- <directory>src/main/java</directory>
- <includes>
- <include>**</include>
- </includes>
- <excludes>
- <exclude>**/*.java</exclude>
- </excludes>
- </resource>
-</resources>
-----
-
-If using an Isis xref:_ug_getting-started_simpleapp-archetype[SimpleApp archetype], then the POM is already correctly configured.
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_request-parameters.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_request-parameters.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_request-parameters.adoc
deleted file mode 100644
index 53e4cd6..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_request-parameters.adoc
+++ /dev/null
@@ -1,53 +0,0 @@
-[[_ug_wicket-viewer_request-parameters]]
-= Request 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/
-
-
-This section describes features that are dependent on HTTP request parameters (*not* by setting configuration properties in `isis.properties`).
-
-== Suppressing Header and Footer (Embedded View)
-
-The Wicket viewer provides some support such that an Isis application can be embedded within a host webapp, for example within an iframe.
-
-Currently this support consists simply of being able to suppress the header and/or footer.
-
-=== Screenshots
-
-For example, the regular view is:
-
-image::{_imagesdir}wicket-viewer/embedded-view/regular.png[width="720px",link="{_imagesdir}wicket-viewer/embedded-view/regular.png"]
-
-
-With the header and footer both suppressed only the main content is shown:
-
-image::{_imagesdir}wicket-viewer/embedded-view/no-header-no-footer.png[width="720px",link="{_imagesdir}wicket-viewer/embedded-view/no-header-no-footer.png"]
-
-
-It is also possible to suppress just the header, or just the footer.
-
-
-=== Request parameters
-
-To suppress the header, add the following as a request parameter:
-
-[source,ini]
-----
-isis.no.header
-----
-
-and to suppress the header, add the following as a request parameter:
-
-[source,ini]
-----
-isis.no.footer
-----
-
-For example,
-
-[source,ini]
-----
-http://localhost:8080/wicket/entity/TODO:0?isis.no.header&isis.no.footer
-----
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_xxx.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_xxx.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_xxx.adoc
deleted file mode 100644
index cfbb258..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_xxx.adoc
+++ /dev/null
@@ -1 +0,0 @@
-[[_ug_xxx]]
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/eclipse/eclipse-010-windows-preferences.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/eclipse/eclipse-010-windows-preferences.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/eclipse/eclipse-010-windows-preferences.png
deleted file mode 100644
index 149a23b..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/eclipse/eclipse-010-windows-preferences.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/eclipse/eclipse-025-project-properties.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/eclipse/eclipse-025-project-properties.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/eclipse/eclipse-025-project-properties.png
deleted file mode 100644
index 120856c..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/eclipse/eclipse-025-project-properties.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/eclipse/eclipse-100-project-support.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/eclipse/eclipse-100-project-support.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/eclipse/eclipse-100-project-support.png
deleted file mode 100644
index 7068fb4..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/eclipse/eclipse-100-project-support.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/eclipse/eclipse-110-project-support.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/eclipse/eclipse-110-project-support.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/eclipse/eclipse-110-project-support.png
deleted file mode 100644
index 49d04a8..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/eclipse/eclipse-110-project-support.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/eclipse/eclipse-120-console.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/eclipse/eclipse-120-console.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/eclipse/eclipse-120-console.png
deleted file mode 100644
index 1e77587..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/eclipse/eclipse-120-console.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/eclipse/eclipse-200-enhancer-fails-duplicates.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/eclipse/eclipse-200-enhancer-fails-duplicates.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/eclipse/eclipse-200-enhancer-fails-duplicates.png
deleted file mode 100644
index 8d7e10a..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/eclipse/eclipse-200-enhancer-fails-duplicates.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/eclipse/eclipse-210-enhancer-fails-duplicates.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/eclipse/eclipse-210-enhancer-fails-duplicates.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/eclipse/eclipse-210-enhancer-fails-duplicates.png
deleted file mode 100644
index 5350251..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/eclipse/eclipse-210-enhancer-fails-duplicates.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/eclipse/eclipse-220-enhancer-fails-duplicates.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/eclipse/eclipse-220-enhancer-fails-duplicates.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/eclipse/eclipse-220-enhancer-fails-duplicates.png
deleted file mode 100644
index dbe247e..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/eclipse/eclipse-220-enhancer-fails-duplicates.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/010-installing/010-welcome-page.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/010-installing/010-welcome-page.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/010-installing/010-welcome-page.png
deleted file mode 100644
index 24fbed3..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/010-installing/010-welcome-page.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/010-installing/020-choose-location.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/010-installing/020-choose-location.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/010-installing/020-choose-location.png
deleted file mode 100644
index 1d0cb46..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/010-installing/020-choose-location.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/010-installing/030-installation-options.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/010-installing/030-installation-options.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/010-installing/030-installation-options.png
deleted file mode 100644
index 01fbe56..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/010-installing/030-installation-options.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/010-installing/040-start-menu-folder.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/010-installing/040-start-menu-folder.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/010-installing/040-start-menu-folder.png
deleted file mode 100644
index dc850cc..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/010-installing/040-start-menu-folder.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/010-installing/050-completing.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/010-installing/050-completing.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/010-installing/050-completing.png
deleted file mode 100644
index 7b80e17..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/010-installing/050-completing.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/010-installing/060-import-settings-or-not.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/010-installing/060-import-settings-or-not.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/010-installing/060-import-settings-or-not.png
deleted file mode 100644
index 0054c4c..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/010-installing/060-import-settings-or-not.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/010-installing/070-set-ui-theme.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/010-installing/070-set-ui-theme.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/010-installing/070-set-ui-theme.png
deleted file mode 100644
index 247fc64..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/010-installing/070-set-ui-theme.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/020-create-new-project/010-new-project-create.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/020-create-new-project/010-new-project-create.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/020-create-new-project/010-new-project-create.png
deleted file mode 100644
index a950887..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/020-create-new-project/010-new-project-create.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/020-create-new-project/020-java-project-setup-jdk.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/020-create-new-project/020-java-project-setup-jdk.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/020-create-new-project/020-java-project-setup-jdk.png
deleted file mode 100644
index 16fe8d1..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/020-create-new-project/020-java-project-setup-jdk.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/020-create-new-project/030-java-project-select-jdk.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/020-create-new-project/030-java-project-select-jdk.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/020-create-new-project/030-java-project-select-jdk.png
deleted file mode 100644
index d0214c6..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/020-create-new-project/030-java-project-select-jdk.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/020-create-new-project/040-sdk-selected.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/020-create-new-project/040-sdk-selected.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/020-create-new-project/040-sdk-selected.png
deleted file mode 100644
index b9399d6..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/020-create-new-project/040-sdk-selected.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/020-create-new-project/050-name-and-location.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/020-create-new-project/050-name-and-location.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/020-create-new-project/050-name-and-location.png
deleted file mode 100644
index 7f3b8d6..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/020-create-new-project/050-name-and-location.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/020-create-new-project/060-create-dir.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/020-create-new-project/060-create-dir.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/020-create-new-project/060-create-dir.png
deleted file mode 100644
index 287478a..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/020-create-new-project/060-create-dir.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/030-import-settings/010-settings-import-jar.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/030-import-settings/010-settings-import-jar.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/030-import-settings/010-settings-import-jar.png
deleted file mode 100644
index c607856..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/030-import-settings/010-settings-import-jar.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/030-import-settings/020-select-all.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/030-import-settings/020-select-all.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/030-import-settings/020-select-all.png
deleted file mode 100644
index 8e63a35..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/030-import-settings/020-select-all.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/030-import-settings/030-restart.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/030-import-settings/030-restart.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/030-import-settings/030-restart.png
deleted file mode 100644
index c20e0ac..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/030-import-settings/030-restart.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/040-other-settings/010-maven-installation.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/040-other-settings/010-maven-installation.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/040-other-settings/010-maven-installation.png
deleted file mode 100644
index 9fef693..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/040-other-settings/010-maven-installation.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/040-other-settings/020-maven-configuration.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/040-other-settings/020-maven-configuration.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/040-other-settings/020-maven-configuration.png
deleted file mode 100644
index 945968d..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/040-other-settings/020-maven-configuration.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/040-other-settings/030-build-automatically.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/040-other-settings/030-build-automatically.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/040-other-settings/030-build-automatically.png
deleted file mode 100644
index b383b3c..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/040-other-settings/030-build-automatically.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/040-other-settings/040-auto-import.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/040-other-settings/040-auto-import.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/040-other-settings/040-auto-import.png
deleted file mode 100644
index 293d2c3..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/040-other-settings/040-auto-import.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/050-some-plugins/010-some-plugins.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/050-some-plugins/010-some-plugins.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/050-some-plugins/010-some-plugins.png
deleted file mode 100644
index 9e2230b..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/050-some-plugins/010-some-plugins.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/050-some-plugins/020-some-plugins-confirmation.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/050-some-plugins/020-some-plugins-confirmation.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/050-some-plugins/020-some-plugins-confirmation.png
deleted file mode 100644
index 037c967..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/050-some-plugins/020-some-plugins-confirmation.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/010-maven-modules-view.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/010-maven-modules-view.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/010-maven-modules-view.png
deleted file mode 100644
index a5b8944..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/010-maven-modules-view.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/020-adding-another-module.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/020-adding-another-module.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/020-adding-another-module.png
deleted file mode 100644
index b8e9ba9..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/020-adding-another-module.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/030-other-module-added.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/030-other-module-added.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/030-other-module-added.png
deleted file mode 100644
index 58b42f0..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/030-other-module-added.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/040-ignoring-modules.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/040-ignoring-modules.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/040-ignoring-modules.png
deleted file mode 100644
index 0421f99..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/040-ignoring-modules.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/050-ignoring-modules-2.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/050-ignoring-modules-2.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/050-ignoring-modules-2.png
deleted file mode 100644
index 6bf26ac..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/050-ignoring-modules-2.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/060-ignored-modules.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/060-ignored-modules.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/060-ignored-modules.png
deleted file mode 100644
index b16086b..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/060-ignored-modules.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/110-running-the-app/010-run-configuration.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/110-running-the-app/010-run-configuration.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/110-running-the-app/010-run-configuration.png
deleted file mode 100644
index 0c6a929..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/110-running-the-app/010-run-configuration.png and /dev/null differ
[19/45] isis git commit: ISIS-1133: breaking out reference guide and
devenv guide;
moving appendices' release notes and migration notes to other docs;
improving the documentation page.
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_class-structure_properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_class-structure_properties.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_class-structure_properties.adoc
deleted file mode 100644
index b96d8ae..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_class-structure_properties.adoc
+++ /dev/null
@@ -1,283 +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/
-
-
-IMPORTANT: TODO
-
-
-
-
-
-== Value vs Reference Types
-
-IMPORTANT: WIP
-
-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_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 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 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 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 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 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)
-
-IMPORTANT: 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_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 = "BLOB")
-})
-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 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 = "BLOB",
- allowsNull="false")
-})
-private Blob attachment;
-@Property(
- optionality = Optionality.MANDATORY
-)
-public Blob getAttachment() {
-return attachment;
-}
-public void setAttachment(final Blob attachment) {
-this.attachment = attachment;
-}
-----
-
-=== Mapping Clobs
-
-Mapping `Clob`s works in a very similar way, but the `@Column#sqlType` attribute will be `CLOB`:
-
-[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", sqlType = "CLOB")
-})
-private Clob doc;
-@Property(
- optionality = Optionality.OPTIONAL
-)
-public Clob getDoc() {
- return doc;
-}
-public void setDoc(final Clob doc) {
- this.doc = doc;
-}
-----
-
-
-=== Mapping to VARBINARY or VARCHAR
-
-Instead of mapping to a `Blob` or `Clob` datatype, you might also specify map to a `VARBINARY` or `VARCHAR`. In this case you will need to specify a length. For example:
-
-
-[source,java]
-----
-@javax.jdo.annotations.Column(name = "attachment_bytes", sqlType = "VARBINARY", length=2048)
-----
-
-or
-
-[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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_contributed-members.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_contributed-members.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_contributed-members.adoc
deleted file mode 100644
index b45b6fd..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_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/
-
-
-
-IMPORTANT: WIP - 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
-
-IMPORTANT: TODO
-
-## Contributed Property
-
-IMPORTANT: TODO
-
-## Contributed Collection
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_crud.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_crud.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_crud.adoc
deleted file mode 100644
index f8d1b9a..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_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/
-
-IMPORTANT: TODO
-
-
-## Instantiating and Persisting Objects
-
-IMPORTANT: TODO - using ``DomainObjectContainer``'s support for xref:_ug_reference-services-api_manpage-DomainObjectContainer_object-creation-api[creation] and xref:_ug_reference-services-api_manpage-DomainObjectContainer_object-persistence-api[persistence]
-
-## Finding Objects
-
-IMPORTANT: TODO - using xref:_ug_reference-services-api_manpage-DomainObjectContainer_generic-repository-api[`DomainObjectContainer`]
-
-### Using DataNucleus type-safe queries
-
-IMPORTANT: TODO - as described xref:_ug_reference-services-api_manpage-IsisJdoSupport_type-safe-jdoql-queries[here]
-
-
-
-## Deleting Objects
-
-IMPORTANT: TODO using ``DomainObjectContainer``'s support for xref:_ug_reference-services-api_manpage-DomainObjectContainer_object-persistence-api[persistence]
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_derived-members.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_derived-members.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_derived-members.adoc
deleted file mode 100644
index 5283f3e..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_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/
-
-IMPORTANT: TODO
-
-
-
-
-== Derived Property
-
-IMPORTANT: TODO
-
-
-
-
-== Derived Collection
-
-IMPORTANT: WIP
-
-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
-
-IMPORTANT: TODO - xref:_ug_reference-methods_prefixes_manpage-modify[`modify...()`], xref:_ug_reference-methods_prefixes_manpage-clear[`clear...()`]
-
-
-
-== Trigger on collection change
-
-IMPORTANT: TODO - xref:_ug_reference-methods_prefixes_manpage-addTo[`addTo...()`], xref:_ug_reference-methods_prefixes_manpage-removeFrom[`removeFrom...()`]
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_domain-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_domain-services.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_domain-services.adoc
deleted file mode 100644
index c4d0004..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_domain-services.adoc
+++ /dev/null
@@ -1,164 +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/
-
-
-
-
-It's worth extending the <<_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"]
-
-Here, we can see that the addons provide services both to the Isis framework (for example security, command and auditing) and also - by way of dependency injection - to the domain objects (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:_ug_reference-services-api[here] and xref:_ug_reference-services-spi[here].
-
-
-
-
-
-== 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:_ug_reference-annotations_manpage-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:_ug_reference-services-api[here] and xref:_ug_reference-services-spi[here] for further details.
-
-
-
-
-== Registering domain services
-
-
-IMPORTANT: TODO - discuss @DomainService if `isis.services-installer=annotation-and-configuration`; how to override these defaults by explicit registration
-
-Domain services (which includes repositories and factories) can be registered 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:_ug_reference-services-api[here] and _ug_reference-services-spi[here] for further details.
-
-
-
-
-
-== Contributions
-
-IMPORTANT: WIP - just xref xref:_ug_how-tos_contributed-members[contributed members] section.
-
-
-
-
-
-
-== Menu items
-
-IMPORTANT: WIP - update to new annotations, including @DomainService(nature=...)
-
-
-By default every action of a service (by which we also mean repositories and factories) will be rendered in the viewer, eg as a menu item for that service menu. This behaviour can be suppressed by annotating the action using `@org.apache.isis.applib.annotations.NotInServiceMenu`.
-
-For example:
-
-[source,java]
-----
-public interface Library {
- @NotInServiceMenu
- public Loan borrow(Loanable l, Borrower b);
-}
-----
-
-Note that an action annotated as being `@NotInServiceMenu` will still be contributed. If an action should neither be contributed nor appear in service menu items, then simply annotate it as `@Hidden`.
-
-Alternatively, this can be performed using a supporting method:
-
-[source,java]
-----
-public class LibraryImpl implements Library {
- public Loan borrow(Loanable l, Borrower b) { ... }
- public boolean notInServiceMenuBorrow() { ... }
-}
-----
-
-
-
-
-== Menus
-
-IMPORTANT: WIP - update to new annotations, including @DomainService(nature=...)
-
-If none of the service menu items should appear, then the service itself should be annotated as `@Hidden`.
-
-For example:
-
-[source,java]
-----
-@Hidden
-public interface EmailService {
- public void sendEmail(String to, String from, String subject, String body);
- public void forwardEmail(String to, String from, String subject, String body);
-}
-----
-
-
-
-
-== 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 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:_ug_reference-annotations_manpage-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:_ug_reference-annotations_manpage-PreDestroy[`@PreDestroy`].
-
-
-
-
-== The getId() method
-
-Optionally, a service may provide a xref:_ug_reference-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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_drop-downs-and-defaults.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_drop-downs-and-defaults.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_drop-downs-and-defaults.adoc
deleted file mode 100644
index 28fe16c..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_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/
-
-IMPORTANT: TODO
-
-
-== For Properties
-
-IMPORTANT: WIP
-
-### Choices for Property
-
-IMPORTANT: TODO - xref:_ug_reference-methods_prefixes_manpage-choices[`choices...()`]
-
-### Auto-complete for property
-
-IMPORTANT: TODO - xref:_ug_reference-methods_prefixes_manpage-autoComplete[`autoComplete...()`]
-
-### Default for property
-
-IMPORTANT: TODO - xref:_ug_reference-methods_prefixes_manpage-default[`default...()`]
-
-
-
-
-== For Action Parameters
-
-IMPORTANT: WIP
-
-### Choices for action parameter
-
-IMPORTANT: TODO - xref:_ug_reference-methods_prefixes_manpage-choices[`choices...()`]
-
-### Dependent choices for action params
-
-IMPORTANT: TODO - xref:_ug_reference-methods_prefixes_manpage-choices[`choices...()`]
-
-### Auto-complete for action param
-
-IMPORTANT: TODO - xref:_ug_reference-methods_prefixes_manpage-autoComplete[`autoComplete...()`]
-
-### Default for action param
-
-IMPORTANT: TODO - xref:_ug_reference-methods_prefixes_manpage-default[`default...()`]
-
-
-
-
-
-== For both Properties and Action Parameters
-
-IMPORTANT: WIP
-
-
-### Drop-down for limited number of instances
-
-IMPORTANT: TODO - xref:_ug_reference-annotations_manpage-DomainObject_bounded[`@DomainObject#bounded()`]
-
-
-### Auto-complete (repository-based)
-
-xref:_ug_reference-annotations_manpage-DomainObject_autoComplete[`@DomainObject#autoComplete()`]
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_entity-relationships.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_entity-relationships.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_entity-relationships.adoc
deleted file mode 100644
index 611946b..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_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/
-
-
-IMPORTANT: TODO
-
-== Mandatory and Optional
-
-IMPORTANT: 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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships.adoc
deleted file mode 100644
index a622470..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships.adoc
+++ /dev/null
@@ -1,58 +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:_ug_reference-methods_prefixes_manpage-modify[`modify...()`] and xref:_ug_reference-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.
-
-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 (as of Isis 1.4.1) hit an NullPointerException. This may be a bug in DataNucleus, we are not completely sure, but the above idiom seems to fix the issue.
-
-For more information, see http://isis.markmail.org/thread/ipu2lzqqikqdglox[this thread] on the 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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_ui-hints.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_ui-hints.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_ui-hints.adoc
deleted file mode 100644
index 62a57b6..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_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 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]
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_ui-hints_action-icons-and-css.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_ui-hints_action-icons-and-css.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_ui-hints_action-icons-and-css.adoc
deleted file mode 100644
index a55e11c..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_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
-
-IMPORTANT: WIP - xref:_ug_reference-annotations_manpage-ActionLayout_cssClass[`@ActionLayout#cssClass()`] and xref:_ug_reference-annotations_manpage-ActionLayout_cssClassFa[`@ActionLayout#cssClassFa()`]
-
-
-Alternatively, you can specify these hints dynamically in the xref:_ug_reference-object-layout[`Xxx.layout.json`] for the entity.
-
-
-== Per pattern matching
-
-Rather than annotating every action with xref:_ug_reference-annotations_manpage-ActionLayout_cssClassFa[`@ActionLayout#cssClassFa()`] and xref:_ug_reference-annotations_manpage-ActionLayout_cssClass[`@ActionLayout#cssClass()`] you can instead specify the UI hint globally using regular expressions.
-
-The xref:_ug_runtime_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:_ug_runtime_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:_ug_reference-annotations_manpage-ActionLayout_cssClassFa[`@ActionLayout#cssClassFa()`] or xref:_ug_reference-annotations_manpage-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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_ui-hints_eager-rendering.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_ui-hints_eager-rendering.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_ui-hints_eager-rendering.adoc
deleted file mode 100644
index bf35d00..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_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:
-
-IMPORTANT: TODO - screenshot here
-
-For the more commonly used collections we want to show the table expanded:
-
-IMPORTANT: 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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_ui-hints_layout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_ui-hints_layout.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_ui-hints_layout.adoc
deleted file mode 100644
index e4c8665..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_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_reference-object-layout[object layout] chapter.
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_ui-hints_names-and-descriptions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_ui-hints_names-and-descriptions.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_ui-hints_names-and-descriptions.adoc
deleted file mode 100644
index 2e72955..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_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/
-
-IMPORTANT: TODO
-
-
-
-NOTE: see also xref:_ug_more-advanced_i18n[Internationalization]
-
-== Class (object)
-
-IMPORTANT: TODO - xref:_ug_reference-annotations_manpage-DomainObjectLayout_named[`@DomainObjectLayout#named()`], xref:_ug_reference-annotations_manpage-DomainObjectLayout_describedAs[`@DomainObjectLayout#describedAs()`]
-
-
-== Property
-
-IMPORTANT: TODO - xref:_ug_reference-annotations_manpage-PropertyLayout_named[`@PropertyLayout#named()`], xref:_ug_reference-annotations_manpage-PropertyLayout_describedAs[`@PropertyLayout#describedAs()`]
-
-
-
-== Collections
-
-IMPORTANT: TODO - xref:_ug_reference-annotations_manpage-CollectionLayout_named[`@CollectionLayout#named()`], xref:_ug_reference-annotations_manpage-CollectionLayout_describedAs[`@CollectionLayout#describedAs()`]
-
-
-
-== Actions
-
-IMPORTANT: TODO - xref:_ug_reference-annotations_manpage-ActionLayout_named[`@ActionLayout#named()`], xref:_ug_reference-annotations_manpage-ActionLayout_describedAs[`@ActionLayout#describedAs()`]
-
-
-== Action Parameters
-
-IMPORTANT: TODO - xref:_ug_reference-annotations_manpage-ParameterLayout_named[`@ParameterLayout#named()`], xref:_ug_reference-annotations_manpage-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:_upgrading_to_java_8_1_9_0_snapshot_and_later[upgrading to Java 8].
-====
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_ui-hints_object-titles-and-icons.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_ui-hints_object-titles-and-icons.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_ui-hints_object-titles-and-icons.adoc
deleted file mode 100644
index 0bce72d..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_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:_ug_wicket-viewer_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:_ug_reference-annotations_manpage-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
-
-IMPORTANT: TODO - see xref:_ug_reference-methods_reserved_manpage-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).
-
-IMPORTANT: TODO - xref:_ug_reference-methods_reserved_manpage-iconName[`iconName()`], xref:_ug_reference-annotations_manpage-DomainObjectLayout_cssClassFa[`@DomainObjectLayout#cssClassFa()`]
-
-
-
-
-== Object CSS Styling
-
-
-It is also possible for an object to return a xref:_ug_reference-methods_reserved_manpage-cssClass[CSS class]. In conjunction with xref:_ug_wicket-viewer_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.
-
-IMPORTANT: TODO - xref:_ug_reference-methods_reserved_manpage-cssClass[`cssClass()`], xref:_ug_reference-annotations_manpage-DomainObjectLayout_cssClass[`@DomainObjectLayout#cssClass()`] xref:_ug_reference-annotations_manpage-ActionLayout_cssClass[`@ActionLayout#cssClass()`], xref:_ug_reference-annotations_manpage-PropertyLayout_cssClass[`@PropertyLayout#cssClass()`], xref:_ug_reference-annotations_manpage-CollectionLayout_cssClass[`@CollectionLayout#cssClass()`]
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_isis-maven-plugin.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_isis-maven-plugin.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_isis-maven-plugin.adoc
deleted file mode 100644
index a9a72b6..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_isis-maven-plugin.adoc
+++ /dev/null
@@ -1,9 +0,0 @@
-[[_ug_isis-maven-plugin]]
-= Isis Maven Plugin
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../../../
-:_imagesdir: images/
-:toc: right
-
-IMPORTANT: TODO
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced.adoc
deleted file mode 100644
index 4b61cb2..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced.adoc
+++ /dev/null
@@ -1,26 +0,0 @@
-[[_ug_more-advanced]]
-= More Advanced Techniques
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 pulls together a number of more advanced techniques that we've discovered and developed while building our own Isis applications.
-
-
-include::_ug_more-advanced_decoupling.adoc[leveloffset=+1]
-include::_ug_more-advanced_overriding-jdo-annotations.adoc[leveloffset=+1]
-include::_ug_more-advanced_bulk-actions.adoc[leveloffset=+1]
-include::_ug_more-advanced_view-models.adoc[leveloffset=+1]
-include::_ug_more-advanced_mapping-rdbms-views.adoc[leveloffset=+1]
-include::_ug_more-advanced_transactions-and-errors.adoc[leveloffset=+1]
-include::_ug_more-advanced_i18n.adoc[leveloffset=+1]
-include::_ug_more-advanced_multi-tenancy.adoc[leveloffset=+1]
-include::_ug_more-advanced_persistence-lifecycle.adoc[leveloffset=+1]
-include::_ug_more-advanced_tips-n-tricks.adoc[leveloffset=+1]
-
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_bulk-actions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_bulk-actions.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_bulk-actions.adoc
deleted file mode 100644
index 30bfc10..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_bulk-actions.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-[[_ug_more-advanced_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/
-
-IMPORTANT: TODO - xref:_ug_reference-annotations_manpage-Action_invokeOn[`@Action#invokeOn()`]
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_decoupling.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_decoupling.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_decoupling.adoc
deleted file mode 100644
index cd8e635..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_decoupling.adoc
+++ /dev/null
@@ -1,26 +0,0 @@
-[[_ug_more-advanced_decoupling]]
-= Decoupling
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-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, or module.
-
-This section describes how to use Isis' features to ensure that your domain application remains decoupled. The techniques described here are also the ones that have been adopted by the various http://github.com/isisaddons[Isis Addons] modules (not ASF) for security, commands, auditing etc.
-
-The following sections describe how to re-assemble an application, in particular where some modules are in-house but others are potentially third-party (eg the Isis Addons modules).
-
-[NOTE]
-====
-There is some overlap with OSGi and Java 9's Jigsaw concepts of "module"; in the future we expect to refactor Isis to leverage these module systems.
-====
-
-include::_ug_more-advanced_decoupling_db-schemas.adoc[leveloffset=+1]
-include::_ug_more-advanced_decoupling_contributions.adoc[leveloffset=+1]
-include::_ug_more-advanced_decoupling_vetoing-visibility.adoc[leveloffset=+1]
-include::_ug_more-advanced_decoupling_event-bus.adoc[leveloffset=+1]
-include::_ug_more-advanced_decoupling_pushing-changes.adoc[leveloffset=+1]
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_decoupling_contributions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_decoupling_contributions.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_decoupling_contributions.adoc
deleted file mode 100644
index ead0886..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_decoupling_contributions.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-[[_ug_more-advanced_decoupling_contributions]]
-= Contributions
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-IMPORTANT: TODO
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_decoupling_db-schemas.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_decoupling_db-schemas.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_decoupling_db-schemas.adoc
deleted file mode 100644
index 9a842c6..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_decoupling_db-schemas.adoc
+++ /dev/null
@@ -1,151 +0,0 @@
-[[_ug_more-advanced_decoupling_db-schemas]]
-= Database Schemas
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 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. As of 1.9.0-SNAPSHOT, all the link:http://www.isisaddons.org[Isis Addons] (non-ASF) modules do this, for example:
-
-
-
-[source,java]
-----
-@javax.jdo.annotations.PersistenceCapable( ...
- schema = "isissecurity",
- table = "ApplicationUser")
-public class ApplicationUser ... { ... }
-----
-
-results in a `CREATE TABLE` statement of:
-
-[source,sql]
-----
-CREATE TABLE isissecurity."ApplicationUser" (
- ...
-)
-----
-
-
-while:
-
-[source,java]
-----
-@javax.jdo.annotations.PersistenceCapable( ...
- schema = "isisaudit",
- table="AuditEntry")
-public class AuditEntry ... { ... }
-----
-
-similarly results in:
-
-[source,sql]
-----
-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:_ug_runtime_configuring-datanucleus[configuring DataNucleus Overriding Annotations] for more details.
-====
-
-
-
-
-== Listener to create schema
-
-JDO/DataNucleus does not automatically create these schema objects, but it _does_ provide a listener callback API
-on the initialization of each class into the JDO metamodel.
-
-[TIP]
-====
-Actually, the above statement isn't quite true. In DN 3.2.x (as used by Isis up to v1.8.0) there was no support for schemas. As of Isis 1.9.0-SNAPSHOT and DN 4.0 there is now support. But we implemented this feature initially against DN 3.2.x, and it still works, so for now we've decided to leave it in.
-====
-
-Therefore Apache Isis attaches a listener, `CreateSchemaObjectFromClassMetadata`, that checks for the schema's existence, and creates the schema if required.
-
-The guts of its implementation is:
-
-[source,java]
-----
-public class CreateSchemaObjectFromClassMetadata
- implements MetaDataListener,
- PersistenceManagerFactoryAware,
- DataNucleusPropertiesAware {
- @Override
- public void loaded(final AbstractClassMetaData cmd) { ... }
-
- protected String buildSqlToCheck(final AbstractClassMetaData cmd) {
- final String schemaName = schemaNameFor(cmd);
- return String.format(
- "SELECT count(*) FROM INFORMATION_SCHEMA.SCHEMATA where SCHEMA_NAME = '%s'", schemaName);
- }
- protected String buildSqlToExec(final AbstractClassMetaData cmd) {
- final String schemaName = schemaNameFor(cmd);
- return String.format("CREATE SCHEMA \"%s\"", schemaName);
- }
-}
-----
-
-where `MetaDataListener` is the DataNucleus listener API:
-
-[source,java]
-----
-public interface MetaDataListener {
- void loaded(AbstractClassMetaData cmd);
-}
-----
-
-Although not formal API, the default `CreateSchemaObjectFromClassMetadata` has been designed to be easily overrideable if you
-need to tweak it to support other RDBMS'. Any implementation must implement `org.datanucleus.metadata.MetaDataListener`:
-
-The implementation provided has has been tested for HSQLDB, PostgreSQL and MS SQL Server, and is used automatically unless an alternative implementation is specified (as described in the section below).
-
-
-
-
-
-== Alternative implementation
-
-An alternative implementation can be registered and used through the following configuration property:
-
-[source,ini]
-----
-isis.persistor.datanucleus.classMetadataLoadedListener=\
- org.apache.isis.objectstore.jdo.datanucleus.CreateSchemaObjectFromClassMetadata
-----
-
-
-Because this pertains to the JDO Objectstore we suggest you put this configuration property in `WEB-INF/persistor_datanucleus.properties`; but putting it in `isis.properties` will also work.
-
-Any implementation must implement `org.datanucleus.metadata.MetaDataListener`. In many cases simply subclassing from `CreateSchemaObjectFromClassMetadata` and overriding `buildSqlToCheck(...)` and `buildSqlToExec(...)` should suffice.
-
-If you _do_ need more control, your implementation can also optionally implement `org.apache.isis.objectstore.jdo.datanucleus.PersistenceManagerFactoryAware`:
-
-[source,java]
-----
-public interface PersistenceManagerFactoryAware {
- public void setPersistenceManagerFactory(final PersistenceManagerFactory persistenceManagerFactory);
-}
-----
-
-and also `org.apache.isis.objectstore.jdo.datanucleus.DataNucleusPropertiesAware`:
-
-[source,java]
-----
-public interface DataNucleusPropertiesAware {
- public void setDataNucleusProperties(final Map<String, String> properties);
-}
-----
-
-This latter interface provides access to the properties passed through to JDO/DataNucleus.
-
-
-[IMPORTANT]
-====
-If you do extend Isis' `CreateSchemaObjectFromClassMetadata` class for some other database, please https://issues.apache.org/jira/browse/ISIS[contribute back] your improvements.
-====
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_decoupling_event-bus.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_decoupling_event-bus.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_decoupling_event-bus.adoc
deleted file mode 100644
index ce1852d..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_decoupling_event-bus.adoc
+++ /dev/null
@@ -1,11 +0,0 @@
-[[_ug_more-advanced_decoupling_event-bus]]
-= Event Bus
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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:_ug_reference-services-api_manpage-EventBusService[`EventBusService`], xref:_ug_reference-annotations_manpage-Action_domainEvent[`@Action#domainEvent()`], xref:_ug_reference-annotations_manpage-Property_domainEvent[`@Property#domainEvent()`], xref:_ug_reference-annotations_manpage-Collection_domainEvent[`@Collection#domainEvent()`], xref:_ug_reference-services-api_manpage-WrapperFactory[`WrapperFactory`].
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_decoupling_pushing-changes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_decoupling_pushing-changes.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_decoupling_pushing-changes.adoc
deleted file mode 100644
index 076744d..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_decoupling_pushing-changes.adoc
+++ /dev/null
@@ -1,140 +0,0 @@
-[[_ug_more-advanced_decoupling_pushing-changes]]
-= Pushing Changes
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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]
-====
-This technique is much less powerful than using xref:_ug_more-advanced_decoupling_event-bus[the event bus] . We present it mostly for completeness.
-====
-
-
-
-
-== When a property is changed
-
-If you want to invoke functionality whenever a property is changed by the user, then you should create a supporting `modifyXxx()` method and include the functionality within that. The syntax is:
-
-[source,java]
---
-public void modifyPropertyName(PropertyType param) { ... }
---
-
-Why not just put this functionality in the setter? Well, the setter is used by the object store to recreate the state of an already persisted object. Putting additional behaviour in the setter would cause it to be triggered incorrectly.
-
-For example:
-
-[source,java]
---
-public class Order() {
- public Integer getAmount() { ... }
- public void setAmount(Integer amount) { ... }
- public void modifyAmount(Integer amount) { // <1>
- setAmount(amount); // <3>
- addToTotal(amount); // <2>
- }
- ...
-}
---
-<1> The `modifyAmount()` method calls ...
-<2> ... the `addToTotal()` (not shown) to maintain some running total.
-
-We don't want this `addToCall()` method to be called when pulling the object back from the object store, so we put it into the modify, not the setter.
-
-You may optionally also specify a `clearXxx()` which works the same way as modify `modify Xxx()` but is called when the property is cleared by the user (i.e. the current value replaced by nothing). The syntax is:
-
-[source,java]
---
-public void clearPropertyName() { ... }
---
-
-To extend the above example:
-
-[source,java]
---
-public class Order() {
- public Integer getAmount() { ... }
- public void setAmount(Integer amount) { ... }
- public void modifyAmount(Integer amount) { ... }
- public void clearAmount() {
- removeFromTotal(this.amount);
- setAmount(null);
- }
- ...
-}
---
-
-
-
-
-== When a collection is modified
-
-A collection may have a corresponding `addToXxx()` and/or
-`removeFromXxx()` method. If present, and direct manipulation of the
-contents of the connection has not been disabled (see ?), then they will
-be called (instead of adding/removing an object directly to the
-collection returned by the accessor).
-
-The reason for this behaviour is to allow other behaviour to be
-triggered when the contents of the collection is altered. That is, it is
-directly equivalent to the supporting `modifyXxx()` and `clearXxx()`
-methods for properties (see ?).
-
-The syntax is:
-
-[source,java]
---
-public void addTo<CollectionName>(EntityType param) { ... }
---
-
-and
-
-[source,java]
---
-public void removeFromCollectionName(EntityType param) { ... }
---
-
-where `EntityType` is the same type as the generic collection type.
-
-For example:
-
-[source,java]
---
-public class Employee { ... }
-
-public class Department {
-
- private int numMaleEmployees; // <1>
- private int numFemaleEmployees; // <2>
-
- private Set<Employee> employees = new TreeSet<Employee>();
- public Set<Employee> getEmployees() {
- return employees;
- }
- private void setEmployees(Set<Employee> employees) {
- this.employees = employees;
- }
- public void addToEmployees(Employee employee) { // <3>
- numMaleEmployees += countOneMale(employee);
- numFemaleEmployees += countOneFemale(employee);
- employees.add(employee);
- }
- public void removeFromEmployees(Employee employee) { // <4>
- numMaleEmployees -= countOneMale(employee);
- numFemaleEmployees -= countOneFemale(employee);
- employees.remove(employee);
- }
- private int countOneMale(Employee employee) { return employee.isMale()?1:0; }
- private int countOneFemale(Employee employee) { return employee.isFemale()?1:0; }
-
- ...
-}
---
-<1> maintain a count of the number of male ...
-<2> ... and female employees (getters and setters omitted)
-<3> the xref:_ug_reference-methods_prefixes_manpage-addTo[`addTo...()`] method increments the derived properties
-<4> the xref:_ug_reference-methods_prefixes_manpage-removeTo[`removeTo...()`] method similarly decrements the derived properties
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_decoupling_vetoing-visibility.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_decoupling_vetoing-visibility.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_decoupling_vetoing-visibility.adoc
deleted file mode 100644
index 77a4556..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_decoupling_vetoing-visibility.adoc
+++ /dev/null
@@ -1,15 +0,0 @@
-[[_ug_more-advanced_decoupling_vetoing-visibility]]
-= Vetoing Visibility
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-IMPORTANT: TODO - a write-up of the "vetoing subscriber" design pattern, eg as described in the xref:_ug_reference-services-api_manpage-BookmarkService[`BookmarkService`]
-
-
-eg if included an addon such as auditing or security.
-
-solution is to write a domain event subscriber that vetoes the visibility
-
-All the addons actions inherit from common base classes so this can be as broad-brush or fine-grained as required
\ No newline at end of file
[24/45] isis git commit: ISIS-1133: breaking out reference guide and
devenv guide;
moving appendices' release notes and migration notes to other docs;
improving the documentation page.
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/configuration/configuring-shiro/ldap/activeds-ldap-mojo-partition.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/configuration/configuring-shiro/ldap/activeds-ldap-mojo-partition.png b/adocs/documentation/src/main/asciidoc/guides/images/configuration/configuring-shiro/ldap/activeds-ldap-mojo-partition.png
new file mode 100644
index 0000000..42d7480
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/configuration/configuring-shiro/ldap/activeds-ldap-mojo-partition.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/configuration/configuring-shiro/ldap/activeds-ldap-mojo-root-dse.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/configuration/configuring-shiro/ldap/activeds-ldap-mojo-root-dse.png b/adocs/documentation/src/main/asciidoc/guides/images/configuration/configuring-shiro/ldap/activeds-ldap-mojo-root-dse.png
new file mode 100644
index 0000000..9c4c480
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/configuration/configuring-shiro/ldap/activeds-ldap-mojo-root-dse.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/configuration/configuring-shiro/ldap/activeds-ldap-sasl-authentication.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/configuration/configuring-shiro/ldap/activeds-ldap-sasl-authentication.png b/adocs/documentation/src/main/asciidoc/guides/images/configuration/configuring-shiro/ldap/activeds-ldap-sasl-authentication.png
new file mode 100644
index 0000000..91d1a61
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/configuration/configuring-shiro/ldap/activeds-ldap-sasl-authentication.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/configuration/configuring-shiro/ldap/activeds-ldap-users.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/configuration/configuring-shiro/ldap/activeds-ldap-users.png b/adocs/documentation/src/main/asciidoc/guides/images/configuration/configuring-shiro/ldap/activeds-ldap-users.png
new file mode 100644
index 0000000..7ff133c
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/configuration/configuring-shiro/ldap/activeds-ldap-users.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/core-concepts/philosophy/hexagonal-architecture.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/core-concepts/philosophy/hexagonal-architecture.png b/adocs/documentation/src/main/asciidoc/guides/images/core-concepts/philosophy/hexagonal-architecture.png
new file mode 100644
index 0000000..d8b28bd
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/core-concepts/philosophy/hexagonal-architecture.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/core-concepts/philosophy/hexagonal-architecture.pptx
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/core-concepts/philosophy/hexagonal-architecture.pptx b/adocs/documentation/src/main/asciidoc/guides/images/core-concepts/philosophy/hexagonal-architecture.pptx
new file mode 100644
index 0000000..3eb0aad
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/core-concepts/philosophy/hexagonal-architecture.pptx differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/getting-started/simpleapp-webapp-with-fixtures.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/getting-started/simpleapp-webapp-with-fixtures.png b/adocs/documentation/src/main/asciidoc/guides/images/getting-started/simpleapp-webapp-with-fixtures.png
new file mode 100644
index 0000000..1dd885a
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/getting-started/simpleapp-webapp-with-fixtures.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/getting-started/simpleapp-webapp.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/getting-started/simpleapp-webapp.png b/adocs/documentation/src/main/asciidoc/guides/images/getting-started/simpleapp-webapp.png
new file mode 100644
index 0000000..771451b
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/getting-started/simpleapp-webapp.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/010-root-page.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/010-root-page.png b/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/010-root-page.png
new file mode 100644
index 0000000..74e5ff9
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/010-root-page.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/020-login-to-wicket-viewer.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/020-login-to-wicket-viewer.png b/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/020-login-to-wicket-viewer.png
new file mode 100644
index 0000000..fc0d919
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/020-login-to-wicket-viewer.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/030-home-page-run-fixture-scripts.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/030-home-page-run-fixture-scripts.png b/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/030-home-page-run-fixture-scripts.png
new file mode 100644
index 0000000..3a1bb54
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/030-home-page-run-fixture-scripts.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/040-first-object.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/040-first-object.png b/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/040-first-object.png
new file mode 100644
index 0000000..bc999ee
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/040-first-object.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/050-update-name-prompt.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/050-update-name-prompt.png b/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/050-update-name-prompt.png
new file mode 100644
index 0000000..166e533
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/050-update-name-prompt.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/060-object-updated.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/060-object-updated.png b/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/060-object-updated.png
new file mode 100644
index 0000000..d34888a
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/060-object-updated.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/070-list-all-prompt.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/070-list-all-prompt.png b/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/070-list-all-prompt.png
new file mode 100644
index 0000000..59cc275
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/070-list-all-prompt.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/080-list-all.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/080-list-all.png b/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/080-list-all.png
new file mode 100644
index 0000000..e3e67cf
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/080-list-all.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/090-create.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/090-create.png b/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/090-create.png
new file mode 100644
index 0000000..f5708ec
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/090-create.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/100-create-prompt.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/100-create-prompt.png b/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/100-create-prompt.png
new file mode 100644
index 0000000..9829512
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/100-create-prompt.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/110-object-created.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/110-object-created.png b/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/110-object-created.png
new file mode 100644
index 0000000..31696f3
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/110-object-created.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/120-list-all.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/120-list-all.png b/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/120-list-all.png
new file mode 100644
index 0000000..75a4e04
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/120-list-all.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/220-login-to-restful-viewer.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/220-login-to-restful-viewer.png b/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/220-login-to-restful-viewer.png
new file mode 100644
index 0000000..1b364b5
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/220-login-to-restful-viewer.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/230-home-page.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/230-home-page.png b/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/230-home-page.png
new file mode 100644
index 0000000..d032e68
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/230-home-page.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/240-list-all-invoke.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/240-list-all-invoke.png b/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/240-list-all-invoke.png
new file mode 100644
index 0000000..57971ef
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/240-list-all-invoke.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/250-list-all-results.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/250-list-all-results.png b/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/250-list-all-results.png
new file mode 100644
index 0000000..b8c8b8b
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/getting-started/using-simple-app/250-list-all-results.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/headless-access/BackgroundCommandExecution.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/headless-access/BackgroundCommandExecution.png b/adocs/documentation/src/main/asciidoc/guides/images/headless-access/BackgroundCommandExecution.png
new file mode 100644
index 0000000..5cefae3
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/headless-access/BackgroundCommandExecution.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/headless-access/BackgroundCommandExecutionFromBackgroundCommandServiceJdo.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/headless-access/BackgroundCommandExecutionFromBackgroundCommandServiceJdo.png b/adocs/documentation/src/main/asciidoc/guides/images/headless-access/BackgroundCommandExecutionFromBackgroundCommandServiceJdo.png
new file mode 100644
index 0000000..0c026fb
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/headless-access/BackgroundCommandExecutionFromBackgroundCommandServiceJdo.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/how-tos/domain-services/hexagonal-architecture-addons.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/how-tos/domain-services/hexagonal-architecture-addons.png b/adocs/documentation/src/main/asciidoc/guides/images/how-tos/domain-services/hexagonal-architecture-addons.png
new file mode 100644
index 0000000..af32db1
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/how-tos/domain-services/hexagonal-architecture-addons.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/how-tos/tips-n-tricks/are-you-sure-happy-case.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/how-tos/tips-n-tricks/are-you-sure-happy-case.png b/adocs/documentation/src/main/asciidoc/guides/images/how-tos/tips-n-tricks/are-you-sure-happy-case.png
new file mode 100644
index 0000000..1981c09
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/how-tos/tips-n-tricks/are-you-sure-happy-case.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/how-tos/tips-n-tricks/are-you-sure-sad-case.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/how-tos/tips-n-tricks/are-you-sure-sad-case.png b/adocs/documentation/src/main/asciidoc/guides/images/how-tos/tips-n-tricks/are-you-sure-sad-case.png
new file mode 100644
index 0000000..6182447
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/how-tos/tips-n-tricks/are-you-sure-sad-case.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/how-tos/tips-n-tricks/are-you-sure.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/how-tos/tips-n-tricks/are-you-sure.png b/adocs/documentation/src/main/asciidoc/guides/images/how-tos/tips-n-tricks/are-you-sure.png
new file mode 100644
index 0000000..e1a76fe
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/how-tos/tips-n-tricks/are-you-sure.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/how-tos/ui-hints/object-titles-and-icons/cust-order-product.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/how-tos/ui-hints/object-titles-and-icons/cust-order-product.png b/adocs/documentation/src/main/asciidoc/guides/images/how-tos/ui-hints/object-titles-and-icons/cust-order-product.png
new file mode 100644
index 0000000..3cec4bd
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/how-tos/ui-hints/object-titles-and-icons/cust-order-product.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/ActionLayout/bookmarking.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/ActionLayout/bookmarking.png b/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/ActionLayout/bookmarking.png
new file mode 100644
index 0000000..0100b63
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/ActionLayout/bookmarking.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/ActionLayout/position-BELOW.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/ActionLayout/position-BELOW.png b/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/ActionLayout/position-BELOW.png
new file mode 100644
index 0000000..944bb52
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/ActionLayout/position-BELOW.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/ActionLayout/position-PANEL.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/ActionLayout/position-PANEL.png b/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/ActionLayout/position-PANEL.png
new file mode 100644
index 0000000..ef01a63
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/ActionLayout/position-PANEL.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/ActionLayout/position-PANEL_DROPDOWN.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/ActionLayout/position-PANEL_DROPDOWN.png b/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/ActionLayout/position-PANEL_DROPDOWN.png
new file mode 100644
index 0000000..2194ee8
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/ActionLayout/position-PANEL_DROPDOWN.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/ActionLayout/position-RIGHT.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/ActionLayout/position-RIGHT.png b/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/ActionLayout/position-RIGHT.png
new file mode 100644
index 0000000..0da5647
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/ActionLayout/position-RIGHT.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/CollectionLayout/sortedby-dependencies.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/CollectionLayout/sortedby-dependencies.png b/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/CollectionLayout/sortedby-dependencies.png
new file mode 100644
index 0000000..e5936b5
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/CollectionLayout/sortedby-dependencies.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/DomainObjectLayout/bookmarking-nested.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/DomainObjectLayout/bookmarking-nested.png b/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/DomainObjectLayout/bookmarking-nested.png
new file mode 100644
index 0000000..c48eb9c
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/DomainObjectLayout/bookmarking-nested.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/DomainObjectLayout/bookmarking.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/DomainObjectLayout/bookmarking.png b/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/DomainObjectLayout/bookmarking.png
new file mode 100644
index 0000000..0100b63
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/DomainObjectLayout/bookmarking.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/DomainServiceLayout/menuBar-primary.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/DomainServiceLayout/menuBar-primary.png b/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/DomainServiceLayout/menuBar-primary.png
new file mode 100644
index 0000000..6fe3947
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/DomainServiceLayout/menuBar-primary.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/DomainServiceLayout/menuBar-secondary.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/DomainServiceLayout/menuBar-secondary.png b/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/DomainServiceLayout/menuBar-secondary.png
new file mode 100644
index 0000000..46f8e62
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/DomainServiceLayout/menuBar-secondary.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/DomainServiceLayout/menuBar-tertiary.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/DomainServiceLayout/menuBar-tertiary.png b/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/DomainServiceLayout/menuBar-tertiary.png
new file mode 100644
index 0000000..c87c8ad
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/DomainServiceLayout/menuBar-tertiary.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/DomainServiceLayout/menuOrder.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/DomainServiceLayout/menuOrder.png b/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/DomainServiceLayout/menuOrder.png
new file mode 100644
index 0000000..b5029dd
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/DomainServiceLayout/menuOrder.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/HomePage/HomePage.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/HomePage/HomePage.png b/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/HomePage/HomePage.png
new file mode 100644
index 0000000..59880f4
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/HomePage/HomePage.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/PropertyLayout/labelPosition-LEFT.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/PropertyLayout/labelPosition-LEFT.png b/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/PropertyLayout/labelPosition-LEFT.png
new file mode 100644
index 0000000..3298ead
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/PropertyLayout/labelPosition-LEFT.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/PropertyLayout/labelPosition-NONE.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/PropertyLayout/labelPosition-NONE.png b/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/PropertyLayout/labelPosition-NONE.png
new file mode 100644
index 0000000..e903f0c
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/PropertyLayout/labelPosition-NONE.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/PropertyLayout/labelPosition-TOP.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/PropertyLayout/labelPosition-TOP.png b/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/PropertyLayout/labelPosition-TOP.png
new file mode 100644
index 0000000..8cd2f37
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/PropertyLayout/labelPosition-TOP.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/PropertyLayout/labelPosition-boolean-LEFT.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/PropertyLayout/labelPosition-boolean-LEFT.png b/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/PropertyLayout/labelPosition-boolean-LEFT.png
new file mode 100644
index 0000000..9b4742b
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/PropertyLayout/labelPosition-boolean-LEFT.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/PropertyLayout/labelPosition-boolean-RIGHT.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/PropertyLayout/labelPosition-boolean-RIGHT.png b/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/PropertyLayout/labelPosition-boolean-RIGHT.png
new file mode 100644
index 0000000..6595267
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/reference-annotations/PropertyLayout/labelPosition-boolean-RIGHT.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/reference-layout/4-0-8-0.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/reference-layout/4-0-8-0.png b/adocs/documentation/src/main/asciidoc/guides/images/reference-layout/4-0-8-0.png
new file mode 100644
index 0000000..1ebb062
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/reference-layout/4-0-8-0.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/reference-layout/4-4-4-12.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/reference-layout/4-4-4-12.png b/adocs/documentation/src/main/asciidoc/guides/images/reference-layout/4-4-4-12.png
new file mode 100644
index 0000000..fd946bf
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/reference-layout/4-4-4-12.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/reference-layout/6-6-0-12.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/reference-layout/6-6-0-12.png b/adocs/documentation/src/main/asciidoc/guides/images/reference-layout/6-6-0-12.png
new file mode 100644
index 0000000..369efb7
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/reference-layout/6-6-0-12.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/reference-layout/isis-layout-show-facets.css
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/reference-layout/isis-layout-show-facets.css b/adocs/documentation/src/main/asciidoc/guides/images/reference-layout/isis-layout-show-facets.css
new file mode 100644
index 0000000..c6b6334
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/images/reference-layout/isis-layout-show-facets.css
@@ -0,0 +1,3 @@
+ul.isis-facets {
+ display: initial;
+}
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/reference-layout/isis-layout.css
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/reference-layout/isis-layout.css b/adocs/documentation/src/main/asciidoc/guides/images/reference-layout/isis-layout.css
new file mode 100644
index 0000000..acd445d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/images/reference-layout/isis-layout.css
@@ -0,0 +1,253 @@
+.primary-1 {
+ background-color: #669900;
+}
+
+.primary-2 {
+ background-color: #669900;
+}
+
+.primary-3 {
+ background-color: #669900;
+}
+
+.primary-4 {
+ background-color: #99FF66;
+}
+
+.primary-5 {
+ background-color: #CCFF99;
+}
+
+.secondary-a-1 {
+ background-color: #006666;
+}
+
+.secondary-a-2 {
+ background-color: #006666;
+}
+
+.secondary-a-3 {
+ background-color: #006666;
+}
+
+.secondary-a-4 {
+ background-color: #66CCCC;
+}
+
+.secondary-a-5 {
+ background-color: #99CCCC;
+}
+
+.secondary-b-1 {
+ background-color: #999900;
+}
+
+.secondary-b-2 {
+ background-color: #999900;
+}
+
+.secondary-b-3 {
+ background-color: #999900;
+}
+
+.secondary-b-4 {
+ background-color: #FFFF66;
+}
+
+.secondary-b-5 {
+ background-color: #FFFFCC;
+}
+
+.complement-1 {
+ background-color: #990033;
+}
+
+.complement-2 {
+ background-color: #990033;
+}
+
+.complement-3 {
+ background-color: #990033;
+}
+
+.complement-4 {
+ background-color: #FF6699;
+}
+
+.complement-5 {
+ background-color: #FF99CC;
+}
+
+
+
+legend {
+ background-color: white;
+}
+
+fieldset {
+ padding-bottom: 10px;
+}
+
+span,li {
+ color: white;
+}
+span {
+ font-weight: bold;
+}
+
+li {
+ padding-bottom: 10px;
+ margin-bottom: 10px;
+}
+
+
+
+.isis-header {
+ padding: 20px 80px 20px 40px;
+ margin-right: 100px;
+ background-color: #99CCCC;
+ display: block;
+ width: 100%;
+}
+
+.isis-header span.isis-title {
+ font-size: xx-large;
+ padding: 5px 80px 5px 40px;
+ margin-right: 50px;
+ color: black;
+ background-color: #99FF66;
+ display: inline-table;
+ vertical-align: bottom;
+}
+
+.isis-header div.isis-actions span {
+ font-size: large;
+ padding: 5px 5px 5px 5px;
+ display: inline-table;
+}
+
+.isis-memberGroup, .isis-collection {
+ margin-top: 10px;
+ margin-bottom: 10px;
+ min-height: 100px;
+}
+
+.isis-memberGroup {
+ background-color: #669900;
+}
+
+.isis-collection {
+ background-color: #999900;
+}
+
+
+div.isis-property > span {
+ margin-left: 5%;
+ padding-left: 10px;
+ width: 90%;
+ display: block;
+}
+
+fieldset div.isis-property > span {
+ padding: 5px;
+ margin: 10px;
+ background-color: #006666;
+}
+
+.isis-header div.isis-actions,
+fieldset div.isis-actions {
+ margin-left: 60px;
+}
+
+fieldset.isis-collection div.isis-actions {
+ margin-left: 60px;
+}
+
+.isis-header .isis-actions {
+ display: inline-block;
+}
+
+.isis-header div.isis-action,
+fieldset div.isis-action {
+ display: inline-table;
+ padding: 5px;
+ margin-top: 5px;
+ margin-bottom: 5px;
+ background-color: #990033;
+}
+
+
+fieldset div.isis-action span {
+ background-color: #990033;
+}
+
+.isis-memberGroups {}
+
+.isis-memberGroup.min-height-50,
+.isis-collection.min-height-50 {
+ min-height: 50px;
+}
+
+.isis-memberGroup.min-height-100,
+.isis-collection.min-height-100 {
+ min-height: 100px;
+}
+
+.isis-memberGroup.min-height-150,
+.isis-collection.min-height-150 {
+ min-height: 150px;
+}
+
+.isis-memberGroup.min-height-200,
+.isis-collection.min-height-200 {
+ min-height: 200px;
+}
+
+.isis-memberGroup.min-height-250,
+.isis-collection.min-height-250 {
+ min-height: 250px;
+}
+
+.isis-memberGroup.min-height-300,
+.isis-collection.min-height-300 {
+ min-height: 300px;
+}
+
+.isis-memberGroup.min-height-350,
+.isis-collection.min-height-350 {
+ min-height: 350px;
+}
+
+.isis-memberGroup.min-height-400,
+.isis-collection.min-height-400 {
+ min-height: 400px;
+}
+
+.isis-memberGroup .isis-hidden {
+ display: none;
+}
+
+.isis-action ul.isis-facets li {
+ margin-top: 30px;
+}
+ul.isis-facets li {
+ margin-left: 40px;
+ font-size: small;
+}
+.isis-action ul.isis-facets li {
+ margin-top: 10px;
+ margin-left: 20px;
+}
+.isis-action ul.isis-facets li {
+ font-size: small;
+}
+ul.isis-facets {
+ line-height: 0px;
+}
+ul.isis-facets {
+ margin:0px;
+}
+
+.isis-facets {
+ display: none;
+}
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/reference-layout/layout-4-0-8-0.html
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/reference-layout/layout-4-0-8-0.html b/adocs/documentation/src/main/asciidoc/guides/images/reference-layout/layout-4-0-8-0.html
new file mode 100644
index 0000000..eeeb185
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/images/reference-layout/layout-4-0-8-0.html
@@ -0,0 +1,198 @@
+f<!DOCTYPE html>
+<html lang="en">
+<head>
+ <meta charset="utf-8">
+ <meta http-equiv="X-UA-Compatible" content="IE=edge">
+ <meta name="viewport" content="width=device-width, initial-scale=1">
+ <title>colspans={4,0,8,0}</title>
+
+ <!-- Bootstrap -->
+ <!--
+ <link rel="stylesheet" href="//netdna.bootstrapcdn.com/bootstrap/3.1.1/css/bootstrap.min.css">
+ <link rel="stylesheet" href="//netdna.bootstrapcdn.com/bootstrap/3.1.1/css/bootstrap-theme.min.css">
+ <script src="//netdna.bootstrapcdn.com/bootstrap/3.1.1/js/bootstrap.min.js"></script>
+ -->
+
+ <!-- Bootstrap -->
+ <link href="css/bootstrap.min.css" rel="stylesheet">
+
+ <!-- HTML5 Shim and Respond.js IE8 support of HTML5 elements and media queries -->
+ <!-- WARNING: Respond.js doesn't work if you view the page via file:// -->
+ <!--[if lt IE 9]>
+ <script src="https://oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
+ <script src="https://oss.maxcdn.com/libs/respond.js/1.4.2/respond.min.js"></script>
+ <![endif]-->
+ <link href="isis-layout.css" rel="stylesheet">
+ <!--<link href="isis-layout-show-facets.css" rel="stylesheet">-->
+</head>
+ <body>
+ <div class="container">
+ <h1>colspans={4,0,8,0}</h1>
+ <div class="row">
+ <div class="col-md-12">
+ <div class="isis-header">
+ <span class="isis-title">Buy bread</span>
+ <div class="isis-actions">
+ <div class="isis-action x-caution">
+ <span>delete</span>
+ </div>
+ <div class="isis-action">
+ <span data-isis-id="duplicate">clone</span>
+ <ul class="isis-facets">
+ <li>describedAs.value="Create a new todo item from this one"</li>
+ </ul>
+ </div>
+ <div class="isis-action">
+ <span>recentChanges</span>
+ </div>
+ <div class="isis-action">
+ <span>recentChanges</span>
+ </div>
+ </div>
+ </div>
+ </div>
+ </div>
+ <div class="row">
+ <div class="col-md-4 isis-memberGroups">
+ <fieldset class="isis-memberGroup min-height-100">
+ <legend>General</legend>
+ <div class="isis-property">
+ <span data-isis-typicallength="50">description</span>
+ <ul class="isis-facets">
+ <li>typicalLength.value=50</li>
+ </ul>
+ </div>
+ <div class="isis-property">
+ <span>category</span>
+ <ul class="isis-facets">
+ <li>disabled.reason="Use action to update both category and subcategory"</li>
+ </ul>
+ </div>
+ <div class="isis-property">
+ <span>subcategory</span>
+ <ul class="isis-facets">
+ <li>disabled.reason="Use action to update both category and subcategory"</li>
+ </ul>
+ <div class="isis-actions">
+ <div class="isis-action">
+ <span data-isis-id="updateCategory">update</span>
+ </div>
+ <div class="isis-action">
+ <span>analyseCategory</span>
+ </div>
+ </div>
+ </div>
+ <div class="isis-property">
+ <span class="isis-hidden">ownedBy</span>
+ </div>
+ <div class="isis-property x-highlight">
+ <span data-isis-id="complete">done</span>
+ <div class="isis-actions">
+ <div class="isis-action">
+ <span data-isis-id="completed">done</span>
+ <ul class="isis-facets">
+ <li>describedAs.value="Mark this todo item as having been completed"</li>
+ </ul>
+ </div>
+ <div class="isis-action">
+ <span>scheduleExplicitly</span>
+ </div>
+ <div class="isis-action">
+ <span>scheduleImplicitly</span>
+ </div>
+ <div class="isis-action">
+ <span data-isis-id="notYetCompleted">not done</span>
+ </div>
+ </div>
+ </div>
+ </fieldset>
+ <fieldset class="isis-memberGroup">
+ <legend>Priority</legend>
+ <div class="isis-property">
+ <span>relativePriority</span>
+ <div class="isis-actions">
+ <div class="isis-action">
+ <span>previous</span>
+ </div>
+ <div class="isis-action">
+ <span>next</span>
+ </div>
+ </div>
+ </div>
+ <div class="isis-property x-key">
+ <span>dueBy</span>
+ </div>
+ <legend>Other</legend>
+ <div class="isis-property">
+ <span>cost</span>
+ <div class="isis-actions">
+ <div class="isis-action">
+ <span data-isis-id="updateCost">update</span>
+ </div>
+ </div>
+ </div>
+ <div class="isis-property">
+ <span>notes</span>
+ <ul class="isis-facets">
+ <li>multiLine.numberOfLines=5</li>
+ <li>hidden.where=ALL_TABLES</li>
+ </ul>
+ </div>
+ <div class="isis-property">
+ <span>attachment</span>
+ <ul class="isis-facets">
+ <li>hidden.where=ALL_TABLES</li>
+ </ul>
+ </div>
+ <div class="isis-property">
+ <span data-isis-id="versionSequence">version</span>
+ <ul class="isis-facets">
+ <li>disabled</li>
+ <li>hidden.where=STANDALONE_TABLES</li>
+ </ul>
+ </div>
+ </fieldset>
+ </div>
+ <div class="col-md-8">
+ <fieldset class="isis-collection min-height-100">
+ <legend>dependencies</legend>
+ <div class="isis-actions">
+ <div class="isis-action">
+ <span>add</span>
+ </div>
+ <div class="isis-action x-caution">
+ <span>remove</span>
+ </div>
+ </div>
+ <ul class="isis-facets">
+ <li>disabled</li>
+ <li>paged.value=5</li>
+ <li>render.value=EAGERLY</li>
+ </ul>
+ </fieldset>
+ <fieldset class="isis-collection min-height-200">
+ <legend>similarTo</legend>
+ <ul class="isis-facets">
+ <li>disabled</li>
+ <li>paged.value=3</li>
+ <li>render.value=LAZILY</li>
+ </ul>
+ </fieldset>
+ </div>
+ </div>
+ <div class="row">
+ <div class="col-md-12">
+ </div>
+ </div>
+ </div>
+
+ <!-- jQuery (necessary for Bootstrap's JavaScript plugins) -->
+ <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.0/jquery.min.js"></script>
+ <!-- Include all compiled plugins (below), or include individual files as needed -->
+ <script src="js/bootstrap.min.js"></script>
+ <script>
+ $(document).ready(function () {
+ });
+ </script>
+ </body>
+</html>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/reference-layout/layout-4-4-4-12.html
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/reference-layout/layout-4-4-4-12.html b/adocs/documentation/src/main/asciidoc/guides/images/reference-layout/layout-4-4-4-12.html
new file mode 100644
index 0000000..cd508dc
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/images/reference-layout/layout-4-4-4-12.html
@@ -0,0 +1,205 @@
+f<!DOCTYPE html>
+<html lang="en">
+<head>
+ <meta charset="utf-8">
+ <meta http-equiv="X-UA-Compatible" content="IE=edge">
+ <meta name="viewport" content="width=device-width, initial-scale=1">
+ <title>colspans={4,4,4,12}</title>
+
+ <!-- Bootstrap -->
+ <!--
+ <link rel="stylesheet" href="//netdna.bootstrapcdn.com/bootstrap/3.1.1/css/bootstrap.min.css">
+ <link rel="stylesheet" href="//netdna.bootstrapcdn.com/bootstrap/3.1.1/css/bootstrap-theme.min.css">
+ <script src="//netdna.bootstrapcdn.com/bootstrap/3.1.1/js/bootstrap.min.js"></script>
+ -->
+
+ <!-- Bootstrap -->
+ <link href="css/bootstrap.min.css" rel="stylesheet">
+
+ <!-- HTML5 Shim and Respond.js IE8 support of HTML5 elements and media queries -->
+ <!-- WARNING: Respond.js doesn't work if you view the page via file:// -->
+ <!--[if lt IE 9]>
+ <script src="https://oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
+ <script src="https://oss.maxcdn.com/libs/respond.js/1.4.2/respond.min.js"></script>
+ <![endif]-->
+ <link href="isis-layout.css" rel="stylesheet">
+ <!--<link href="isis-layout-show-facets.css" rel="stylesheet">-->
+</head>
+ <body>
+ <div class="container">
+ <h1>colspans={4,4,4,12}</h1>
+ <div class="row">
+ <div class="col-md-12">
+ <div class="isis-header">
+ <span class="isis-title">Buy bread</span>
+ <div class="isis-actions">
+ <div class="isis-action x-caution">
+ <span>delete</span>
+ </div>
+ <div class="isis-action">
+ <span data-isis-id="duplicate">clone</span>
+ <ul class="isis-facets">
+ <li>describedAs.value="Create a new todo item from this one"</li>
+ </ul>
+ </div>
+ <div class="isis-action">
+ <span>recentChanges</span>
+ </div>
+ <div class="isis-action">
+ <span>recentChanges</span>
+ </div>
+ </div>
+ </div>
+ </div>
+ </div>
+ <div class="row">
+ <div class="col-md-4 isis-memberGroups">
+ <fieldset class="isis-memberGroup min-height-100">
+ <legend>General</legend>
+ <div class="isis-property">
+ <span data-isis-typicallength="50">description</span>
+ <ul class="isis-facets">
+ <li>typicalLength.value=50</li>
+ </ul>
+ </div>
+ <div class="isis-property">
+ <span>category</span>
+ <ul class="isis-facets">
+ <li>disabled.reason="Use action to update both category and subcategory"</li>
+ </ul>
+ </div>
+ <div class="isis-property">
+ <span>subcategory</span>
+ <ul class="isis-facets">
+ <li>disabled.reason="Use action to update both category and subcategory"</li>
+ </ul>
+ <div class="isis-actions">
+ <div class="isis-action">
+ <span data-isis-id="updateCategory">update</span>
+ </div>
+ <div class="isis-action">
+ <span>analyseCategory</span>
+ </div>
+ </div>
+ </div>
+ <div class="isis-property">
+ <span class="isis-hidden">ownedBy</span>
+ </div>
+ <div class="isis-property x-highlight">
+ <span data-isis-id="complete">done</span>
+ <div class="isis-actions">
+ <div class="isis-action">
+ <span data-isis-id="completed">done</span>
+ <ul class="isis-facets">
+ <li>describedAs.value="Mark this todo item as having been completed"</li>
+ </ul>
+ </div>
+ <div class="isis-action">
+ <span>scheduleExplicitly</span>
+ </div>
+ <div class="isis-action">
+ <span>scheduleImplicitly</span>
+ </div>
+ <div class="isis-action">
+ <span data-isis-id="notYetCompleted">not done</span>
+ </div>
+ </div>
+ </div>
+ </fieldset>
+ </div>
+ <div class="col-md-4 isis-memberGroups">
+ <fieldset class="isis-memberGroup">
+ <legend>Priority</legend>
+ <div class="isis-property">
+ <span>relativePriority</span>
+ <div class="isis-actions">
+ <div class="isis-action">
+ <span>previous</span>
+ </div>
+ <div class="isis-action">
+ <span>next</span>
+ </div>
+ </div>
+ </div>
+ <div class="isis-property x-key">
+ <span>dueBy</span>
+ </div>
+ </fieldset>
+ </div>
+ <div class="col-md-4 isis-memberGroups">
+ <fieldset class="isis-memberGroup">
+ <legend>Other</legend>
+ <div class="isis-property">
+ <span>cost</span>
+ <div class="isis-actions">
+ <div class="isis-action">
+ <span data-isis-id="updateCost">update</span>
+ </div>
+ </div>
+ </div>
+ <div class="isis-property">
+ <span>notes</span>
+ <ul class="isis-facets">
+ <li>multiLine.numberOfLines=5</li>
+ <li>hidden.where=ALL_TABLES</li>
+ </ul>
+ </div>
+ <div class="isis-property">
+ <span>attachment</span>
+ <ul class="isis-facets">
+ <li>hidden.where=ALL_TABLES</li>
+ </ul>
+ </div>
+ </fieldset>
+ <fieldset class="isis-memberGroup min-height-100">
+ <legend>Misc</legend>
+ <div class="isis-property">
+ <span data-isis-id="versionSequence">version</span>
+ <ul class="isis-facets">
+ <li>disabled</li>
+ <li>hidden.where=STANDALONE_TABLES</li>
+ </ul>
+ </div>
+ </fieldset>
+ </div>
+ </div>
+ <div class="row">
+ <div class="col-md-12">
+ <fieldset class="isis-collection min-height-100">
+ <legend>dependencies</legend>
+ <div class="isis-actions">
+ <div class="isis-action">
+ <span>add</span>
+ </div>
+ <div class="isis-action x-caution">
+ <span>remove</span>
+ </div>
+ </div>
+ <ul class="isis-facets">
+ <li>disabled</li>
+ <li>paged.value=5</li>
+ <li>render.value=EAGERLY</li>
+ </ul>
+ </fieldset>
+ <fieldset class="isis-collection min-height-200">
+ <legend>similarTo</legend>
+ <ul class="isis-facets">
+ <li>disabled</li>
+ <li>paged.value=3</li>
+ <li>render.value=LAZILY</li>
+ </ul>
+ </fieldset>
+ </div>
+ </div>
+ </div>
+
+ <!-- jQuery (necessary for Bootstrap's JavaScript plugins) -->
+ <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.0/jquery.min.js"></script>
+ <!-- Include all compiled plugins (below), or include individual files as needed -->
+ <script src="js/bootstrap.min.js"></script>
+ <script>
+ $(document).ready(function () {
+ });
+ </script>
+ </body>
+</html>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/reference-layout/layout-6-6-0-12.html
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/reference-layout/layout-6-6-0-12.html b/adocs/documentation/src/main/asciidoc/guides/images/reference-layout/layout-6-6-0-12.html
new file mode 100644
index 0000000..02a8e0d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/images/reference-layout/layout-6-6-0-12.html
@@ -0,0 +1,203 @@
+f<!DOCTYPE html>
+<html lang="en">
+<head>
+ <meta charset="utf-8">
+ <meta http-equiv="X-UA-Compatible" content="IE=edge">
+ <meta name="viewport" content="width=device-width, initial-scale=1">
+ <title>colspans={6,6,0,12}</title>
+
+ <!-- Bootstrap -->
+ <!--
+ <link rel="stylesheet" href="//netdna.bootstrapcdn.com/bootstrap/3.1.1/css/bootstrap.min.css">
+ <link rel="stylesheet" href="//netdna.bootstrapcdn.com/bootstrap/3.1.1/css/bootstrap-theme.min.css">
+ <script src="//netdna.bootstrapcdn.com/bootstrap/3.1.1/js/bootstrap.min.js"></script>
+ -->
+
+ <!-- Bootstrap -->
+ <link href="css/bootstrap.min.css" rel="stylesheet">
+
+ <!-- HTML5 Shim and Respond.js IE8 support of HTML5 elements and media queries -->
+ <!-- WARNING: Respond.js doesn't work if you view the page via file:// -->
+ <!--[if lt IE 9]>
+ <script src="https://oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
+ <script src="https://oss.maxcdn.com/libs/respond.js/1.4.2/respond.min.js"></script>
+ <![endif]-->
+ <link href="isis-layout.css" rel="stylesheet">
+ <!--<link href="isis-layout-show-facets.css" rel="stylesheet">-->
+</head>
+ <body>
+ <div class="container">
+ <h1>colspans={6,6,0,12}</h1>
+ <div class="row">
+ <div class="col-md-12">
+ <div class="isis-header">
+ <span class="isis-title">Buy bread</span>
+ <div class="isis-actions">
+ <div class="isis-action x-caution">
+ <span>delete</span>
+ </div>
+ <div class="isis-action">
+ <span data-isis-id="duplicate">clone</span>
+ <ul class="isis-facets">
+ <li>describedAs.value="Create a new todo item from this one"</li>
+ </ul>
+ </div>
+ <div class="isis-action">
+ <span>recentChanges</span>
+ </div>
+ <div class="isis-action">
+ <span>recentChanges</span>
+ </div>
+ </div>
+ </div>
+ </div>
+ </div>
+ <div class="row">
+ <div class="col-md-6 isis-memberGroups">
+ <fieldset class="isis-memberGroup min-height-100">
+ <legend>General</legend>
+ <div class="isis-property">
+ <span data-isis-typicallength="50">description</span>
+ <ul class="isis-facets">
+ <li>typicalLength.value=50</li>
+ </ul>
+ </div>
+ <div class="isis-property">
+ <span>category</span>
+ <ul class="isis-facets">
+ <li>disabled.reason="Use action to update both category and subcategory"</li>
+ </ul>
+ </div>
+ <div class="isis-property">
+ <span>subcategory</span>
+ <ul class="isis-facets">
+ <li>disabled.reason="Use action to update both category and subcategory"</li>
+ </ul>
+ <div class="isis-actions">
+ <div class="isis-action">
+ <span data-isis-id="updateCategory">update</span>
+ </div>
+ <div class="isis-action">
+ <span>analyseCategory</span>
+ </div>
+ </div>
+ </div>
+ <div class="isis-property">
+ <span class="isis-hidden">ownedBy</span>
+ </div>
+ <div class="isis-property x-highlight">
+ <span data-isis-id="complete">done</span>
+ <div class="isis-actions">
+ <div class="isis-action">
+ <span data-isis-id="completed">done</span>
+ <ul class="isis-facets">
+ <li>describedAs.value="Mark this todo item as having been completed"</li>
+ </ul>
+ </div>
+ <div class="isis-action">
+ <span>scheduleExplicitly</span>
+ </div>
+ <div class="isis-action">
+ <span>scheduleImplicitly</span>
+ </div>
+ <div class="isis-action">
+ <span data-isis-id="notYetCompleted">not done</span>
+ </div>
+ </div>
+ </div>
+ </fieldset>
+ <fieldset class="isis-memberGroup min-height-100">
+ <legend>Misc</legend>
+ <div class="isis-property">
+ <span data-isis-id="versionSequence">version</span>
+ <ul class="isis-facets">
+ <li>disabled</li>
+ <li>hidden.where=STANDALONE_TABLES</li>
+ </ul>
+ </div>
+ </fieldset>
+ </div>
+ <div class="col-md-6 isis-memberGroups">
+ <fieldset class="isis-memberGroup">
+ <legend>Priority</legend>
+ <div class="isis-property">
+ <span>relativePriority</span>
+ <div class="isis-actions">
+ <div class="isis-action">
+ <span>previous</span>
+ </div>
+ <div class="isis-action">
+ <span>next</span>
+ </div>
+ </div>
+ </div>
+ <div class="isis-property x-key">
+ <span>dueBy</span>
+ </div>
+ </fieldset>
+ <fieldset class="isis-memberGroup">
+ <legend>Other</legend>
+ <div class="isis-property">
+ <span>cost</span>
+ <div class="isis-actions">
+ <div class="isis-action">
+ <span data-isis-id="updateCost">update</span>
+ </div>
+ </div>
+ </div>
+ <div class="isis-property">
+ <span>notes</span>
+ <ul class="isis-facets">
+ <li>multiLine.numberOfLines=5</li>
+ <li>hidden.where=ALL_TABLES</li>
+ </ul>
+ </div>
+ <div class="isis-property">
+ <span>attachment</span>
+ <ul class="isis-facets">
+ <li>hidden.where=ALL_TABLES</li>
+ </ul>
+ </div>
+ </fieldset>
+ </div>
+ </div>
+ <div class="row">
+ <div class="col-md-12">
+ <fieldset class="isis-collection min-height-100">
+ <legend>dependencies</legend>
+ <div class="isis-actions">
+ <div class="isis-action">
+ <span>add</span>
+ </div>
+ <div class="isis-action x-caution">
+ <span>remove</span>
+ </div>
+ </div>
+ <ul class="isis-facets">
+ <li>disabled</li>
+ <li>paged.value=5</li>
+ <li>render.value=EAGERLY</li>
+ </ul>
+ </fieldset>
+ <fieldset class="isis-collection min-height-200">
+ <legend>similarTo</legend>
+ <ul class="isis-facets">
+ <li>disabled</li>
+ <li>paged.value=3</li>
+ <li>render.value=LAZILY</li>
+ </ul>
+ </fieldset>
+ </div>
+ </div>
+ </div>
+
+ <!-- jQuery (necessary for Bootstrap's JavaScript plugins) -->
+ <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.0/jquery.min.js"></script>
+ <!-- Include all compiled plugins (below), or include individual files as needed -->
+ <script src="js/bootstrap.min.js"></script>
+ <script>
+ $(document).ready(function () {
+ });
+ </script>
+ </body>
+</html>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/reference-methods/prefixes/choices/dependent.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/reference-methods/prefixes/choices/dependent.png b/adocs/documentation/src/main/asciidoc/guides/images/reference-methods/prefixes/choices/dependent.png
new file mode 100644
index 0000000..e0ad239
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/reference-methods/prefixes/choices/dependent.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/reference-methods/reserved/cssClass/strikethrough.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/reference-methods/reserved/cssClass/strikethrough.png b/adocs/documentation/src/main/asciidoc/guides/images/reference-methods/reserved/cssClass/strikethrough.png
new file mode 100644
index 0000000..6945267
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/reference-methods/reserved/cssClass/strikethrough.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/reference-methods/reserved/iconName/differing.pdn
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/reference-methods/reserved/iconName/differing.pdn b/adocs/documentation/src/main/asciidoc/guides/images/reference-methods/reserved/iconName/differing.pdn
new file mode 100644
index 0000000..70b317b
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/reference-methods/reserved/iconName/differing.pdn differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/reference-methods/reserved/iconName/differing.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/reference-methods/reserved/iconName/differing.png b/adocs/documentation/src/main/asciidoc/guides/images/reference-methods/reserved/iconName/differing.png
new file mode 100644
index 0000000..57b0013
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/reference-methods/reserved/iconName/differing.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/reference-methods/reserved/iconName/png-files.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/reference-methods/reserved/iconName/png-files.png b/adocs/documentation/src/main/asciidoc/guides/images/reference-methods/reserved/iconName/png-files.png
new file mode 100644
index 0000000..7f826c5
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/reference-methods/reserved/iconName/png-files.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/reference-services-spi/ContentNegotiationService/accept-json.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/reference-services-spi/ContentNegotiationService/accept-json.png b/adocs/documentation/src/main/asciidoc/guides/images/reference-services-spi/ContentNegotiationService/accept-json.png
new file mode 100644
index 0000000..84778e9
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/reference-services-spi/ContentNegotiationService/accept-json.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/reference-services-spi/ContentNegotiationService/accept-xml.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/reference-services-spi/ContentNegotiationService/accept-xml.png b/adocs/documentation/src/main/asciidoc/guides/images/reference-services-spi/ContentNegotiationService/accept-xml.png
new file mode 100644
index 0000000..cfd2ef1
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/reference-services-spi/ContentNegotiationService/accept-xml.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/reference-services-spi/ContentNegotiationService/facade-choices.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/reference-services-spi/ContentNegotiationService/facade-choices.png b/adocs/documentation/src/main/asciidoc/guides/images/reference-services-spi/ContentNegotiationService/facade-choices.png
new file mode 100644
index 0000000..c6d5814
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/reference-services-spi/ContentNegotiationService/facade-choices.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/reference-services-spi/ContentNegotiationService/facade-choices.pptx
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/reference-services-spi/ContentNegotiationService/facade-choices.pptx b/adocs/documentation/src/main/asciidoc/guides/images/reference-services-spi/ContentNegotiationService/facade-choices.pptx
new file mode 100644
index 0000000..ddeec7d
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/reference-services-spi/ContentNegotiationService/facade-choices.pptx differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/reference-services-spi/EventSerializer/action-invocation-published-to-stderr.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/reference-services-spi/EventSerializer/action-invocation-published-to-stderr.png b/adocs/documentation/src/main/asciidoc/guides/images/reference-services-spi/EventSerializer/action-invocation-published-to-stderr.png
new file mode 100644
index 0000000..b0b3ca8
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/reference-services-spi/EventSerializer/action-invocation-published-to-stderr.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/reference-services-spi/EventSerializer/changed-object-published-to-stderr.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/reference-services-spi/EventSerializer/changed-object-published-to-stderr.png b/adocs/documentation/src/main/asciidoc/guides/images/reference-services-spi/EventSerializer/changed-object-published-to-stderr.png
new file mode 100644
index 0000000..f894d8d
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/reference-services-spi/EventSerializer/changed-object-published-to-stderr.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/reference-services-spi/PublishingService/yuml.me-23db58a4.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/reference-services-spi/PublishingService/yuml.me-23db58a4.png b/adocs/documentation/src/main/asciidoc/guides/images/reference-services-spi/PublishingService/yuml.me-23db58a4.png
new file mode 100644
index 0000000..60ee3cb
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/reference-services-spi/PublishingService/yuml.me-23db58a4.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..995b089
Binary files /dev/null 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/9c5dafab/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
new file mode 100644
index 0000000..bbdb734
Binary files /dev/null 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/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/reference-services-spi/UserProfileService/todoapp.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/reference-services-spi/UserProfileService/todoapp.png b/adocs/documentation/src/main/asciidoc/guides/images/reference-services-spi/UserProfileService/todoapp.png
new file mode 100644
index 0000000..7867d37
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/reference-services-spi/UserProfileService/todoapp.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/runtime/configuring-datanucleus/disabling-persistence-by-reachability/party-agreementrole-agreement.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/runtime/configuring-datanucleus/disabling-persistence-by-reachability/party-agreementrole-agreement.png b/adocs/documentation/src/main/asciidoc/guides/images/runtime/configuring-datanucleus/disabling-persistence-by-reachability/party-agreementrole-agreement.png
new file mode 100644
index 0000000..67744c9
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/runtime/configuring-datanucleus/disabling-persistence-by-reachability/party-agreementrole-agreement.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/security/security-apis-impl/configure-isis-to-use-bypass.PNG
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/security/security-apis-impl/configure-isis-to-use-bypass.PNG b/adocs/documentation/src/main/asciidoc/guides/images/security/security-apis-impl/configure-isis-to-use-bypass.PNG
new file mode 100644
index 0000000..387594b
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/security/security-apis-impl/configure-isis-to-use-bypass.PNG differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/security/security-apis-impl/configure-isis-to-use-shiro.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/security/security-apis-impl/configure-isis-to-use-shiro.png b/adocs/documentation/src/main/asciidoc/guides/images/security/security-apis-impl/configure-isis-to-use-shiro.png
new file mode 100644
index 0000000..891d373
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/security/security-apis-impl/configure-isis-to-use-shiro.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/security/security-apis-impl/configure-shiro-to-use-custom-jdbc-realm.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/security/security-apis-impl/configure-shiro-to-use-custom-jdbc-realm.png b/adocs/documentation/src/main/asciidoc/guides/images/security/security-apis-impl/configure-shiro-to-use-custom-jdbc-realm.png
new file mode 100644
index 0000000..d64751a
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/security/security-apis-impl/configure-shiro-to-use-custom-jdbc-realm.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/security/security-apis-impl/configure-shiro-to-use-ini-realm.PNG
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/security/security-apis-impl/configure-shiro-to-use-ini-realm.PNG b/adocs/documentation/src/main/asciidoc/guides/images/security/security-apis-impl/configure-shiro-to-use-ini-realm.PNG
new file mode 100644
index 0000000..5576701
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/security/security-apis-impl/configure-shiro-to-use-ini-realm.PNG differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/security/security-apis-impl/configure-shiro-to-use-isis-ldap-realm.PNG
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/security/security-apis-impl/configure-shiro-to-use-isis-ldap-realm.PNG b/adocs/documentation/src/main/asciidoc/guides/images/security/security-apis-impl/configure-shiro-to-use-isis-ldap-realm.PNG
new file mode 100644
index 0000000..2a52910
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/security/security-apis-impl/configure-shiro-to-use-isis-ldap-realm.PNG differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/security/security-apis-impl/configure-shiro-to-use-isisaddons-security-module-realm-with-delegate-realm.PNG
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/security/security-apis-impl/configure-shiro-to-use-isisaddons-security-module-realm-with-delegate-realm.PNG b/adocs/documentation/src/main/asciidoc/guides/images/security/security-apis-impl/configure-shiro-to-use-isisaddons-security-module-realm-with-delegate-realm.PNG
new file mode 100644
index 0000000..14af8c0
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/security/security-apis-impl/configure-shiro-to-use-isisaddons-security-module-realm-with-delegate-realm.PNG differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/security/security-apis-impl/configure-shiro-to-use-isisaddons-security-module-realm.PNG
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/security/security-apis-impl/configure-shiro-to-use-isisaddons-security-module-realm.PNG b/adocs/documentation/src/main/asciidoc/guides/images/security/security-apis-impl/configure-shiro-to-use-isisaddons-security-module-realm.PNG
new file mode 100644
index 0000000..59780f4
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/security/security-apis-impl/configure-shiro-to-use-isisaddons-security-module-realm.PNG differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/security/security-apis-impl/security-apis-impl.pptx
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/security/security-apis-impl/security-apis-impl.pptx b/adocs/documentation/src/main/asciidoc/guides/images/security/security-apis-impl/security-apis-impl.pptx
new file mode 100644
index 0000000..a86b62e
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/security/security-apis-impl/security-apis-impl.pptx differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/testing/fixture-scripts/composite.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/testing/fixture-scripts/composite.png b/adocs/documentation/src/main/asciidoc/guides/images/testing/fixture-scripts/composite.png
new file mode 100644
index 0000000..fd2b397
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/testing/fixture-scripts/composite.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/testing/fixture-scripts/flat-1.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/testing/fixture-scripts/flat-1.png b/adocs/documentation/src/main/asciidoc/guides/images/testing/fixture-scripts/flat-1.png
new file mode 100644
index 0000000..c712aa0
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/testing/fixture-scripts/flat-1.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/testing/fixture-scripts/flat-2.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/testing/fixture-scripts/flat-2.png b/adocs/documentation/src/main/asciidoc/guides/images/testing/fixture-scripts/flat-2.png
new file mode 100644
index 0000000..f3d3a0b
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/testing/fixture-scripts/flat-2.png differ
[43/45] isis git commit: ISIS-1133: breaking out reference guide and
devenv guide;
moving appendices' release notes and migration notes to other docs;
improving the documentation page.
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa_other.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa_other.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa_other.adoc
new file mode 100644
index 0000000..7f7dd93
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa_other.adoc
@@ -0,0 +1,57 @@
+[[_rg_annotations_aaa_other]]
+= Other Isis Annotations
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+These annotations are also commonly used, but relate _not_ to objects or object members but instead to other aspects of the Isis metamodel.
+
+.Other Isis Annotations
+[cols="2,4a,1,1", options="header"]
+|===
+|Annotation
+|Purpose
+|Layer
+|xref:rg.adoc#_rg_object-layout_dynamic[Dynamic layout]?
+
+|xref:rg.adoc#_rg_annotations_manpage-Facets[`@Facets`]
+|Install arbitrary facets within the Isis metamodel.
+|(any)
+|
+
+|xref:rg.adoc#_rg_annotations_manpage-HomePage[`@HomePage`]
+|Query-only action (on domain service) to be invoked, result of which is rendered as the user's home page.
+|UI
+|
+
+|xref:rg.adoc#_rg_annotations_manpage-MemberGroupLayout[`@MemberGroupLayout`]
+|Grouping of properties into groups, and organizing of properties, collections into columns.
+|UI
+|Yes
+
+
+|xref:rg.adoc#_rg_annotations_manpage-MemberOrder[`@MemberOrder`]
+|Ordering of properties, collections and actions, and also associating actions with either a property or a collection.
+|UI
+|Yes
+
+
+|xref:rg.adoc#_rg_annotations_manpage-MinLength[`@MinLength`]
+|Minimum number of characters required for an auto-complete search argument.
+|UI
+|
+
+
+|xref:rg.adoc#_rg_annotations_manpage-Programmatic[`@Programmatic`]
+|Ignore a public method, excluded from the Isis metamodel.
+|Domain
+|
+
+|xref:rg.adoc#_rg_annotations_manpage-Title[`@Title`]
+|Indicates which of the object's properties should be used to build up a title for the object.
+|UI
+
+|===
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa_partial.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa_partial.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa_partial.adoc
new file mode 100644
index 0000000..8007bcf
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa_partial.adoc
@@ -0,0 +1,92 @@
+[[_rg_annotations_aaa_partial]]
+= Incomplete/partial 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/
+
+
+These annotations have only incomplete/partial support, primarily relating to the management of value types. We recommend that you do not use them for now. Future versions of Isis may either formally deprecate/retire them, or we may go the other way and properly support them. This will depend in part on the interactions between the Isis runtime, its two viewer implementations, and DataNucleus persistence.
+
+
+.Annotations with incomplete/partial support
+[cols="2,4a,1", options="header"]
+|===
+|Annotation
+|Purpose
+|Layer
+
+|`@Aggregated`
+|Indicates that the object is aggregated, or wholly owned, by a root object. +
+
+This information could in theory provide useful semantics for some object store implementations, eg to store the aggregated objects "inline". +
+
+Currently neither the JDO ObjectStore nor any of the viewers exploit this metadata.
+|Domain, Persistence
+
+|`@Defaulted`
+|Indicates that a (value) class has a default value. +
+
+The concept of "defaulted" means being able to provide a default value for the type by way of the `o.a.i.applib.adapters.DefaultsProvider` interface. Generally this only applies to value types, where the `@Value` annotation implies encodability through the `ValueSemanticsProvider` interface. +
+
+For these reasons the `@Defaulted` annotation is generally never applied directly, but can be thought of as a placeholder for future enhancements whereby non-value types might also have a default value provided for them.|Domain
+
+|`@Encodable`
+|Indicates that a (value) class can be serialized/encoded. +
+
+Encodability means the ability to convert an object to-and-from a string, by way of the `o.a.i.applib.adapters.EncoderDecoder` interface. Generally this only applies to value types, where the `@Value` annotation implies encodability through the `ValueSemanticsProvider` interface.
+
+For these reasons the `@Encodable` annotation is generally never applied directly, but can be thought of as a placeholder for future enhancements whereby non-value types might also be directly encoded.
+
+Currently neither the Wicket viewer nor the RO viewer use this API. The Wicket viewer uses Wicket APIs, while RO viewer has its own mechanisms (parsing data from input JSON representations, etc.)
+|Persistence
+
+|`@NotPersistable`
+|Indicates that a domain object may not be programmatically persisted. +
++
+This annotation indicates that transient instances of this class may be created but may not be persisted. The framework will not provide the user with an option to 'save' the object, and attempting to persist such an object programmatically would be an error.
+
+For example:
+
+[source,java]
+----
+@NotPersistable(By.USER)
+public class InputForm {
+ ...
+}
+----
+
+By default the annotated object is effectively transient (ie default to `By.USER_OR_PROGRAM`).
+
+This annotation is not supported by: Wicket viewer (which does not support transient objects). See also link:https://issues.apache.org/jira/browse/ISIS-743[ISIS-743] contemplating the removal of this annotation.
+|Domain, Persistence
+
+|`@Parseable`
+|Indicates that a (value) class can be reconstructed from a string. +
+
+Parseability means being able to parse a string representation into an object by way of the `o.a.i.applib.adapters.Parser` interface. Generally this only applies to value types, where the `@Value` annotation implies encodability through the `ValueSemanticsProvider` interface. +
+
+For these reasons the `@Parser` annotation is generally never applied directly, but can be thought of as a placeholder for future enhancements whereby non-value types might also have be able to be parsed. +
+
+Note that the Wicket viewer uses Apache Wicket's Converter API instead.
+|UI, Domain
+
+|`@Value`
+|Specify that a class has value-semantics. +
+
+The `@Value` annotation indicates that a class should be treated as a value type rather than as a reference (or entity) type. It does this providing an implementation of a `o.a.i.applib.adapters.ValueSemanticsProvider`. +
+
+For example: +
+
+[source,java]
+----
+@Value(semanticsProviderClass=
+ ComplexNumberValueSemanticsProvider.class)
+public class ComplexNumber {
+ ...
+}
+----
+
+The `ValueSemanticsProvider` allows the framework to interact with the value, parsing strings and displaying as text, and encoding/decoding (for serialization).
+|Domain
+
+|===
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action.adoc
new file mode 100644
index 0000000..2f2628b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action.adoc
@@ -0,0 +1,134 @@
+[[_rg_annotations_manpage-Action]]
+= `@Action`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@Action` annotation groups together all domain-specific metadata for an invokable action on a domain object or domain service.
+
+The table below summarizes the annotation's attributes.
+
+.`@Action` attributes
+[cols="2,2,4a", options="header"]
+|===
+
+| Attribute
+| Values (default)
+| Description
+
+
+|xref:rg.adoc#_rg_annotations_manpage-Action_command[`command()`]
+|`AS_CONFIGURED`, `ENABLED`, `DISABLED` +
+(`AS_CONFIGURED`)
+|whether the action invocation should be reified into a `o.a.i.applib.` +
+`services.command.Command` object through the xref:rg.adoc#_rg_services-api_manpage-CommandContext[`CommandContext`] service.
+
+
+|`commandExecuteIn()`
+|`FOREGROUND`,`BACKGROUND` +
+(`FOREGROUND`)
+|whether to execute the command immediately, or to persist it (assuming that an appropriate implementation of xref:rg.adoc#_rg_services-spi_manpage-CommandService[`CommandService`] has been configured) such that a background scheduler can execute the command asynchronously
+
+
+|`commandPersistence()`
+|`PERSISTED`, `NOT_PERSISTED`, `IF_HINTED` +
+(`PERSISTED`)
+|whether the reified `Command` (as provided by the `CommandContext` domain service) should actually be persisted (assuming an appropriate implementation of xref:rg.adoc#_rg_services-spi_manpage-CommandService[`CommandService`] has been configured).
+
+
+|xref:rg.adoc#_rg_annotations_manpage-Action_domainEvent[`domainEvent()`]
+|subtype of `ActionDomainEvent` +
+(`ActionDomainEvent.Default`)
+|the event type to be posted to the xref:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`] to broadcast the action's business rule checking (hide, disable, validate) and its invocation (pre-execute and post-execution).
+
+
+|xref:rg.adoc#_rg_annotations_manpage-Action_hidden[`hidden()`]
+|`EVERYWHERE`, `NOWHERE` +
+(`NOWHERE`)
+|indicates where (in the UI) the action should be hidden from the user.
+
+
+|xref:rg.adoc#_rg_annotations_manpage-Action_invokeOn[`invokeOn()`]
+|`OBJECT_ONLY`, `COLLECTION_ONLY`, `OBJECT_AND_COLLECTION` +
+(`OBJECT_ONLY`)
+|whether an action can be invoked on a single object and/or on many objects in a collection.
+
+Currently this is only supported for no-arg actions.
+
+
+|xref:rg.adoc#_rg_annotations_manpage-Action_publishing[`publishing()`]
+|`AS_CONFIGURED`, `ENABLED`, `DISABLED` +
+(`AS_CONFIGURED`)
+|whether the action invocation should be published to the registered xref:rg.adoc#_rg_services-spi_manpage-PublishingService[`PublishingService`].
+
+|`publishing-` +
+`PayloadFactory()`
+|subtype of `PublishingPayloadFactory-` `ForAction` (none)
+|specifies that a custom implementation of `PublishingPayloadFactoryForAction` be used to create the (payload of the) published event representing the action invocation
+
+|xref:rg.adoc#_rg_annotations_manpage-Action_restrictTo[`restrictTo()`]
+|`NO_RESTRICTIONS`,`PROTOTYPING` +
+(`NO_RESTRICTIONS`)
+|whether the action is only available in prototyping mode, or whether it is available also in production mode.
+
+|xref:rg.adoc#_rg_annotations_manpage-Action_semantics[`semantics()`]
+|`QUERY`, `IDEMPOTENT`, `NON_IDEMPOTENT` +
+(`NON_IDEMPOTENT`)
+|the action's semantics (ie whether objects are modified as the result of invoking this action, and if so whether reinvoking the action would result in no further change)
+
+|xref:rg.adoc#_rg_annotations_manpage-Action_typeOf[`typeOf()`]
+|(none)
+|if the action returns a collection, hints as to the run-time type of the objects within that collection (as a fallback)
+
+|===
+
+
+For example:
+
+[source,java]
+----
+public class ToDoItem {
+ public static class CompletedEvent extends ActionDomainEvent<ToDoItem> {
+ private static final long serialVersionUID = 1L;
+ public CompletedEvent(
+ final ToDoItem source,
+ final Identifier identifier,
+ final Object... arguments) {
+ super("completed", source, identifier, arguments);
+ }
+ }
+ @Action(
+ command=CommandReification.ENABLED,
+ commandExecuteIn=CommandExecuteIn.FOREGROUND, // <1>
+ commandPersistence=CommandPersistence.NOT_PERSISTED, // <2>
+ domainEvent=CompletedEvent.class,
+ hidden = Where.NOWHERE, // <3>
+ invokeOn = InvokeOn.OBJECT_ONLY, // <4>
+ publishing = Publishing.ENABLED,
+ semantics = SemanticsOf.IDEMPOTENT
+ )
+ public ToDoItem completed() { ... }
+}
+----
+<1> default value, so could be omitted
+<2> default value, so could be omitted
+<3> default value, so could be omitted
+<4> default value, so could be omitted
+
+
+
+
+
+include::_rg_annotations_manpage-Action_command.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-Action_domainEvent.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-Action_hidden.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-Action_invokeOn.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-Action_publishing.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-Action_restrictTo.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-Action_semantics.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-Action_typeOf.adoc[leveloffset=+1]
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout.adoc
new file mode 100644
index 0000000..bac249d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout.adoc
@@ -0,0 +1,133 @@
+[[_rg_annotations_manpage-ActionLayout]]
+= `@ActionLayout`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@ActionLayout` annotation applies to actions, collecting together all UI hints within a single annotation.
+
+The table below summarizes the annotation's attributes.
+
+.`@ActionLayout` attributes
+[cols="2,2,4a", options="header"]
+|===
+
+| Attribute
+| Values (default)
+| Description
+
+
+|xref:rg.adoc#_rg_annotations_manpage-ActionLayout_bookmarking[`bookmarking()`]
+|`AS_ROOT`, `NEVER` +
+(`NEVER`)
+|indicates if an action (with safe xref:rg.adoc#_rg_annotations_manpage-Action_semantics[action semantics]) is automatically bookmarked.
+
+
+|xref:rg.adoc#_rg_annotations_manpage-ActionLayout_contributedAs[`contributedAs()`]
+|`AS_BOTH`, `AS_ACTION`, `AS_ASSOCIATION`, `AS_NEITHER` +
+(`AS_BOTH`)
+|for a domain service action that can be contributed, whether to contribute as an action or as an association (ie a property or collection). +
+
+For a domain service action to be contributed, the domain services must have a xref:rg.adoc#_rg_annotations_manpage-DomainService_nature[nature] nature of either `VIEW` or `VIEW_CONTRIBUTIONS_ONLY`, and the action must have xref:rg.adoc#_rg_annotations_manpage-Action_semantics[safe action semantics], and takes a single argument, namely the contributee domain object.
+
+
+|xref:rg.adoc#_rg_annotations_manpage-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:ug.adoc#_ug_runtime_application-specific_application-css[`application.css`]. +
+
+Supported by the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] but currently ignored by the xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer].
+
+
+|xref:rg.adoc#_rg_annotations_manpage-ActionLayout_cssClassFa[`cssClassFa()`]
+|Any valid link:http://fortawesome.github.io/Font-Awesome/[Font awesome] icon name
+|specify a font awesome icon for the action's menu link or icon. +
+
+
+|`cssClassFaPosition()`
+|`LEFT`, `RIGHT` +
+(`LEFT`)
+|Positioning of the icon on the button/menu item.
+
+
+|xref:rg.adoc#_rg_annotations_manpage-ActionLayout_describedAs[`describedAs()`]
+|String.
+|provides a short description of the action, eg for rendering as a 'tool tip'.
+
+
+|xref:rg.adoc#_rg_annotations_manpage-ActionLayout_hidden[`hidden()`]
+|`EVERYWHERE`, `NOWHERE` +
+(`NOWHERE`)
+|indicates where (in the UI) the action should be hidden from the user.
+
+
+|xref:rg.adoc#_rg_annotations_manpage-ActionLayout_named[`named()`]
+|String.
+|to override the name inferred from the action's name in code. +
+
+A typical use case is if the desired name is a reserved Java keyword, such as `default` or `package`.
+
+|xref:rg.adoc#_rg_annotations_manpage-ActionLayout_position[`position()`]
+|`BELOW`, `RIGHT`, `PANEL`, `PANEL_DROPDOWN` (`BELOW`)
+|for actions associated (using xref:rg.adoc#_rg_annotations_manpage-MemberOrder[`@MemberOrder#named()`]) with properties, the positioning of the action's button with respect to the property
+
+
+|===
+
+
+For example:
+
+[source,java]
+----
+public class ToDoItems {
+ @Action(semantics=SemanticsOf.SAFE) // <1>
+ @ActionLayout(
+ bookmarking=BookmarkPolicy.AS_ROOT,
+ cssClass="x-key",
+ cssClassFa="fa-checkbox",
+ describedAs="Mark the todo item as not complete after all",
+ hidden=Where.NOWHERE // <2>
+ )
+ @MemberOrder(sequence = "1")
+ public List<ToDoItem> notYetComplete() {
+ ...
+ }
+}
+----
+<1> required for bookmarkable actions
+<2> default value, so could be omitted
+
+
+
+
+As an alternative to using the `@ActionLayout` annotation, a dynamic layout using xref:rg.adoc#_rg_object-layout_dynamic[`.layout.json`] file can be specified; for example:
+
+[source,javascript]
+----
+"notYetComplete": {
+ "actionLayout": {
+ "bookmarking": "AS_ROOT",
+ "cssClass": "x-key",
+ "cssClassFa": "fa-checkbox",
+ "describedAs": "Mark the todo item as not complete after all",
+ "hidden": "NOWHERE"
+ }
+}
+----
+
+
+
+include::_rg_annotations_manpage-ActionLayout_bookmarking.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-ActionLayout_contributedAs.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-ActionLayout_cssClass.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-ActionLayout_cssClassFa.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-ActionLayout_describedAs.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-ActionLayout_hidden.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-ActionLayout_named.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-ActionLayout_position.adoc[leveloffset=+1]
+
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_bookmarking.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_bookmarking.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_bookmarking.adoc
new file mode 100644
index 0000000..cd73033
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_bookmarking.adoc
@@ -0,0 +1,64 @@
+[[_rg_annotations_manpage-ActionLayout_bookmarking]]
+= `bookmarking()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `bookmarking()` attribute indicates if an action (with safe xref:rg.adoc#_rg_annotations_manpage-Action_semantics[action semantics]) is automatically bookmarked. This attribute is also supported for xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_bookmarking[domain objects].
+
+
+
+In the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer], a link to a bookmarked object is shown in the bookmarks panel:
+
+image::{_imagesdir}reference-annotations/ActionLayout/bookmarking.png[width="720px",link="{_imagesdir}reference-annotations/ActionLayout/bookmarking.png"]
+
+[NOTE]
+====
+Note that this screenshot shows an earlier version of the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] UI (specifically, pre 1.8.0).
+====
+
+[TIP]
+====
+The xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] supports `alt-[` as a shortcut for opening the bookmark panel. `Esc` will close.
+====
+
+
+For example:
+
+[source,java]
+----
+public class ToDoItems {
+ @Action(semantics=SemanticsOf.SAFE)
+ @ActionLayout(bookmarking=BookmarkPolicy.AS_ROOT)
+ @MemberOrder(sequence = "1")
+ public List<ToDoItem> notYetComplete() {
+ ...
+ }
+}
+----
+
+indicates that the `notYetComplete()` action is bookmarkable.
+
+
+
+[NOTE]
+====
+The enum value `AS_CHILD` has no meaning for actions; it relates only to bookmarked xref:rg.adoc#_rg_annotations_manpage-DomainObject_bookmarking[domain object]s.
+====
+
+
+
+As an alternative to using the annotation, the dynamic xref:rg.adoc#_rg_object-layout_dynamic[`.layout.json`]
+can be used instead, eg:
+
+[source,javascript]
+----
+"notYetComplete": {
+ "actionLayout": { "bookmarking": "AS_ROOT" }
+}
+----
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_contributedAs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_contributedAs.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_contributedAs.adoc
new file mode 100644
index 0000000..888fdde
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_contributedAs.adoc
@@ -0,0 +1,54 @@
+[[_rg_annotations_manpage-ActionLayout_contributedAs]]
+= `contributedAs()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+For a domain service action that _can_ be contributed, the `contributedAs()` attribute determines how it is contributed: as an action or as an association (ie a property or collection).
+
+The distinction between property or collection is automatic: if the action returns a `java.util.Collection` (or subtype) then the action is contributed as a collection; otherwise it is contributed as a property.
+
+For a domain service action to be contributed, the domain services must have a xref:rg.adoc#_rg_annotations_manpage-DomainService_nature[nature] nature of either `VIEW` or `VIEW_CONTRIBUTIONS_ONLY`, and the action must have xref:rg.adoc#_rg_annotations_manpage-Action_semantics[safe action semantics], and takes a single argument, namely the contributee domain object.
+
+For example:
+
+[source,java]
+----
+@DomainService(nature=NatureOfService.VIEW_CONTRIBUTIONS_ONLY)
+public class CustomerContributions {
+ @Action(semantics=SemanticsOf.SAFE)
+ @ActionLayout(contributedAs=Contributed.AS_ASSOCIATION)
+ public List<Order> mostRecentOrders(Customer customer) { ... }
+ ...
+}
+----
+
+[TIP]
+====
+The `@ActionLayout` is not required if the action does not have safe semantics, or if the action takes more than one argument; in these cases the action can only be contributed _as_ an action.
+====
+
+
+It's also possible to use the attribute to suppress the action completely:
+
+[source,java]
+----
+@DomainService(nature=NatureOfService.VIEW)
+public class OrderContributions {
+ @ActionLayout(contributedAs=Contributed.AS_NEITHER)
+ public void cancel(Order order);
+ ...
+}
+----
+
+In such cases, though, it would probably make more sense to annotate the action as either xref:rg.adoc#_rg_annotations_manpage-Action_hidden[hidden] or indeed xref:rg.adoc#_rg_annotations_manpage-Programmatic[`@Programmatic`].
+
+
+
+[NOTE]
+====
+Unlike other `@ActionLayout` attributes, this attribute _cannot_ be specified dynamically in the `.layout.json` xref:rg.adoc#_rg_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/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_cssClass.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_cssClass.adoc
new file mode 100644
index 0000000..58f7fc5
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_cssClass.adoc
@@ -0,0 +1,41 @@
+[[_rg_annotations_manpage-ActionLayout_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()` attribute can be used to render additional CSS classes in the HTML (a wrapping `<div>`) that represents the action. xref:ug.adoc#_ug_runtime_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:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_cssClass[domain objects], xref:rg.adoc#_rg_annotations_manpage-ViewModelLayout_cssClass[view models], xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_cssClass[properties], xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_cssClass[collections] and xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_cssClass[parameters].
+
+
+For example:
+
+[source,java]
+----
+public class ToDoItem {
+ @ActionLayout(cssClass="x-key")
+ public ToDoItem postpone(LocalDate until) { ... }
+ ...
+}
+----
+
+[NOTE]
+====
+The similar xref:rg.adoc#_rg_annotations_manpage-ActionLayout_cssClassFa[`@ActionLayout#cssClassFa()`] annotation attribute is also used as a hint
+to apply CSS, specifically to add http://fortawesome.github.io/Font-Awesome/icons/[Font Awesome icons] on action menu items or buttons.
+====
+
+
+
+As an alternative to using the annotation, the dynamic xref:rg.adoc#_rg_object-layout_dynamic[`.layout.json`]
+can be used instead, eg:
+
+[source,javascript]
+----
+"postpone": {
+ "actionLayout": { "cssClass": "x-key" }
+}
+----
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_cssClassFa.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_cssClassFa.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_cssClassFa.adoc
new file mode 100644
index 0000000..d8f18db
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_cssClassFa.adoc
@@ -0,0 +1,59 @@
+[[_rg_annotations_manpage-ActionLayout_cssClassFa]]
+= `cssClassFa()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `cssClassFa()` attribute is used to specify the name of a link:http://fortawesome.github.io/Font-Awesome/icons/[Font Awesome icon] name, to be rendered on the action's representation as a button or menu item. The related `cssClassFaPosition()` attribute specifies the positioning of the icon, to the left or the right of the text.
+
+These attributes can also be applied to xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_cssClassFa[domain objects] and to xref:rg.adoc#_rg_annotations_manpage-ViewModelLayout_cssClassFa[view models] to specify the object's icon.
+
+
+For example:
+
+[source,java]
+----
+public class ToDoItem {
+ @ActionLayout(
+ cssClassFa="fa-step-backward"
+ )
+ public ToDoItem previous() { ... }
+
+ @ActionLayout(
+ cssClassFa="fa-step-forward",
+ cssClassFaPosition=ActionLayout.CssClassFaPosition.RIGHT
+ )
+ public ToDoItem next() { ... }
+}
+----
+
+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:rg.adoc#_rg_object-layout_dynamic[`.layout.json`]
+can be used instead, eg:
+
+[source,javascript]
+----
+"previous": {
+ "actionLayout": {
+ "cssClassFa": "fa-step-backward",
+ "cssClassFaPosition": "LEFT"
+ }
+},
+"next": {
+ "actionLayout": {
+ "cssClassFa": "fa-step-forward",
+ "cssClassFaPosition": "RIGHT"
+ }
+}
+----
+
+
+
+[NOTE]
+====
+The similar xref:rg.adoc#_rg_annotations_manpage-ActionLayout_cssClass[`@ActionLayout#cssClass()`] annotation attribute is also used as a hint to apply CSS, but for wrapping the representation of an object or object member so that it can be styled in an application-specific way.
+====
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_describedAs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_describedAs.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_describedAs.adoc
new file mode 100644
index 0000000..eeee65b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_describedAs.adoc
@@ -0,0 +1,37 @@
+[[_rg_annotations_manpage-ActionLayout_describedAs]]
+= `describedAs()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `describedAs()` attribute is used to provide a short description of the action to the user. In the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] it is displayed as a 'tool tip'.
+
+This attribute can also be specified for xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_describedAs[collections], xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_describedAs[properties], xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_describedAs[parameters], xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_describedAs[domain objects] and xref:rg.adoc#_rg_annotations_manpage-ViewModelLayout_describedAs[view models].
+
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ @ActionLayout(describedAs="Place a repeat order of the last (most recently placed) order")
+ public Order placeRepeatOrder(...) { ... }
+}
+----
+
+
+
+
+As an alternative to using the annotation, the dynamic xref:rg.adoc#_rg_object-layout_dynamic[`.layout.json`]
+can be used instead, eg:
+
+[source,javascript]
+----
+"postpone": {
+ "actionLayout": { "describedAs": "Place a repeat order of the last (most recently placed) order" }
+}
+----
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_hidden.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_hidden.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_hidden.adoc
new file mode 100644
index 0000000..413f321
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_hidden.adoc
@@ -0,0 +1,57 @@
+[[_rg_annotations_manpage-ActionLayout_hidden]]
+= `hidden()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `hidden()` attribute indicates where (in the UI) the action should be hidden from the user. This attribute can also be applied to xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_hidden[properties] and xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_hidden[collections].
+
+[TIP]
+====
+It is also possible to use xref:rg.adoc#_rg_annotations_manpage-Action_hidden[`@Action#hidden()`] to hide an action at the domain 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:
+
+[source,java]
+----
+public class Customer {
+ @ActionLayout(hidden=Where.EVERYWHERE)
+ public void updateStatus() { ... }
+ ...
+}
+----
+
+The acceptable values for the `where` parameter are:
+
+* `Where.EVERYWHERE` or `Where.ANYWHERE` +
++
+The action should be hidden at all times.
+
+* `Where.NOWHERE` +
++
+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:rg.adoc#_rg_object-layout_dynamic[`.layout.json`]
+can be used instead, eg:
+
+[source,javascript]
+----
+"updateStatus": {
+ "actionLayout": { "hidden": "EVERYWHERE" }
+}
+----
+
+
+[NOTE]
+====
+For actions of domain services the visibility is dependent upon its xref:rg.adoc#_rg_annotations_manpage-DomainService_nature[`@DomainService#nature()`] and also on whether it is contributed (as per xref:rg.adoc#_rg_annotations_manpage-ActionLayout_contributedAs[`@ActionLayout#contributedAs()`]).
+====
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_named.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_named.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_named.adoc
new file mode 100644
index 0000000..be7320e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_named.adoc
@@ -0,0 +1,45 @@
+[[_rg_annotations_manpage-ActionLayout_named]]
+= `named()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `named()` attribute explicitly specifies the action's name, overriding the name that would normally be inferred from the Java source code. This attribute can also be specified for xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_named[collections], xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_named[properties], xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_named[parameters], xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_named[domain objects], xref:rg.adoc#_rg_annotations_manpage-ViewModelLayout_named[view models] and xref:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_named[domain services].
+
+[TIP]
+====
+Following the link:http://en.wikipedia.org/wiki/Don%27t_repeat_yourself[don't repeat yourself] principle, we recommend that you only use this attribute when the desired name cannot be used in Java source code. Examples of that include a name that would be a reserved Java keyword (eg "package"), or a name that has punctuation, eg apostrophes.
+====
+
+
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ @ActionLayout(named="Get credit rating")
+ public CreditRating obtainCreditRating() { ... }
+}
+----
+
+
+As an alternative to using the annotation, the dynamic xref:rg.adoc#_rg_object-layout_dynamic[`.layout.json`]
+can be used instead, eg:
+
+[source,javascript]
+----
+"obtainCreditRating": {
+ "actionLayout": { "named": "Get credit rating" }
+}
+----
+
+
+[TIP]
+====
+The framework also provides a separate, powerful mechanism for xref:ug.adoc#_ug_more-advanced_i18n[internationalization].
+====
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_position.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_position.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_position.adoc
new file mode 100644
index 0000000..951a1cb
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ActionLayout_position.adoc
@@ -0,0 +1,80 @@
+[[_rg_annotations_manpage-ActionLayout_position]]
+= `position()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `position()` attribute pertains only to actions that have been associated with properties using xref:rg.adoc#_rg_annotations_manpage-MemberOrder[`@MemberOrder#named()`]. For these actions, it specifies the positioning of the action's button with respect to the field representing the object property.
+
+The attribute can take one of four values: `BELOW`, `RIGHT`, `PANEL` or `PANEL_DROPDOWN`.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+
+ @Property(
+ editing=Editing.DISABLED // <1>
+ )
+ public CustomerStatus getStatus() { ... }
+ public void setStatus(CustomerStatus customerStatus) { ... }
+
+ @MemberOrder(
+ named="status", // <2>
+ sequence="1"
+ )
+ @ActionLayout(
+ named="Update", // <3>
+ position=Position.BELOW
+ )
+ public CreditRating updateStatus(Customer ) { ... }
+}
+----
+<1> indicate the property as read-only, such that it can only be updated using an action
+<2> associate the "updateStatus" action with the "status" property
+<3> give the action an abbreviated name, because the fact that the "status" property is to be updated is implied by its positioning
+
+
+The default is `BELOW`, which is rendered (by the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer]) as shown below:
+
+image::{_imagesdir}reference-annotations/ActionLayout/position-BELOW.png[width="720px",link="{_imagesdir}reference-annotations/ActionLayout/position-BELOW.png.png"]
+
+
+If the action is positioned as `RIGHT`, then the action's button is rendered to the right of the property's field, in a compact drop-down. This is ideal if there are many actions associated with a property:
+
+image::{_imagesdir}reference-annotations/ActionLayout/position-RIGHT.png[width="720px",link="{_imagesdir}reference-annotations/ActionLayout/position-RIGHT.png.png"]
+
+
+
+If the action is positioned as `PANEL`, then the action's button is rendered on the header of the panel that contains the property:
+
+image::{_imagesdir}reference-annotations/ActionLayout/position-PANEL.png[width="720px",link="{_imagesdir}reference-annotations/ActionLayout/position-PANEL.png.png"]
+
+
+
+And finally, if the action is positioned as `PANEL_DROPDOWN`, then the action's button is again rendered on the panel header, but as a drop-down:
+
+
+image::{_imagesdir}reference-annotations/ActionLayout/position-PANEL_DROPDOWN.png[width="720px",link="{_imagesdir}reference-annotations/ActionLayout/position-PANEL_DROPDOWN.png.png"]
+
+
+
+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:rg.adoc#_rg_object-layout_dynamic[`.layout.json`]
+can be used instead, eg:
+
+[source,javascript]
+----
+"obtainCreditRating": {
+ "actionLayout": { "named": "Get credit rating" }
+}
+----
+
+The fact that the layout is dynamic (does not require a rebuild/restart) is particularly useful in that the look-n-feel can be easily experimented with and adjusted.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_command.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_command.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_command.adoc
new file mode 100644
index 0000000..b17e9f1
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_command.adoc
@@ -0,0 +1,134 @@
+[[_rg_annotations_manpage-Action_command]]
+= `command()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@Action(command=...)` attribute (and the related `@Action(commandPersistence=...)` and `@Action(commandExecuteIn=...)` attributes) allows an action invocation to be made into a concrete object such that it can be inspected and persisted. The primary use case for this is enhanced profiling/auditing, and it also supports the deferring the execution of the action such that it can be invoked in the background.
+
+The annotation works with (and is influenced by the behaviour of) a number of domain services:
+
+* xref:rg.adoc#_rg_services-api_manpage-CommandContext[`CommandContext`]
+* xref:rg.adoc#_rg_services-spi_manpage-CommandService[`CommandService`]
+* xref:rg.adoc#_rg_services-spi_manpage-BackgroundService[`BackgroundService`] and
+* xref:rg.adoc#_rg_services-spi_manpage-BackgroundCommandService[`BackgroundCommandService`]
+
+
+Each action invocation is reified by the xref:rg.adoc#_rg_services-api_manpage-CommandContext[`CommandContext`] service into a `Command` object, capturing details of the target object, the action, the parameter arguments, the user, a timestamp and so on.
+
+If an appropriate `CommandService` is configured (for example using (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module), then the `Command` itself is persisted.
+
+By default, actions are invoked in directly in the thread of the invocation. If there is an implementation of `BackgroundCommandService` (as the http://github.com/isisaddons/isis-module-command[Isis addons' command] module does provide), then this means in turn that the `BackgroundService` can be used by the domain object code to programmatically create background ``Command``s.
+
+[NOTE]
+====
+If background ``Command``s are used, then an external scheduler, using xref:ug.adoc#_ug_headless-access_BackgroundCommandExecution[headless access], must also be configured.
+====
+
+
+
+The `command()` attribute determines whether the action invocation should be reified into a `Command` object (by the xref:rg.adoc#_rg_services-api_manpage-CommandContext[`CommandContext`] service).
+
+The default is `AS_CONFIGURED`, meaning that the xref:ug.adoc#_ug_runtime_configuring-core[configuration property] `isis.services.command.actions` is used to determine the whether the action is reified:
+
+* `all` +
++
+all actions are reified
+
+* `ignoreSafe` (or `ignoreQueryOnly`) +
++
+actions with safe (read-only) semantics are ignored, but actions which may modify data are not ignored
+
+* `none` +
++
+no actions are reified.
+
+If there is no configuration property in `isis.properties` then all actions are reified into ``Command``s.
+
+[NOTE]
+====
+Note: `Command` reification does not necessarily imply that `Command` objects will be persisted; that depends on whether there is a xref:rg.adoc#_rg_services-spi_manpage-CommandService[`CommandService`] configured that will persist said ``Command``s.
+====
+
+This default can be overridden on an action-by-action basis; if `command()` is set to `ENABLED` then the action is reified irrespective of the configured value; if set to `DISABLED` then the action is NOT reified irrespective of the configured value.
+
+For example:
+
+[source,java]
+----
+public class Order {
+ @Action(command=CommandReification.ENABLED)
+ public Invoice generateInvoice(...) { ... }
+}
+----
+
+corresponds to the behaviour described above; the `Command` object is persisted (assuming an appropriate `CommandService` is defined, and executed immediately in the foreground).
+
+
+
+
+== `commandPersistence()`
+
+If the action has been reified, then the `commandPersistence()` attribute determines whether that `Command` object
+should then also be persisted (the default), or not persisted, or only if hinted.
+
+To explain this last alternative:
+
+[source,java]
+----
+public class Order {
+ @Action(
+ command=CommandReification.ENABLED,
+ commandPersistence=CommandPersistence.IF_HINTED
+ )
+ public Invoice generateInvoice(...) { ... }
+}
+----
+
+will suppress the persistence of the `Command` object _unless_ a child background `Command` has been created in the body of the action by way of the xref:rg.adoc#_rg_services-api_manpage-BackgroundService[`BackgroundService`].
+
+On the other hand:
+
+[source,java]
+----
+public class Order {
+ @Action(
+ command=CommandReification.ENABLED,
+ commandExecuteIn=CommandExecuteIn.FOREGROUND,
+ commandPersistence=CommandPersistence.NOT_PERSISTED
+ )
+ public Invoice generateInvoice(...) { ... }
+}
+----
+
+will prevent the parent `Command` object from being persisted, _even if_ a child background `Command` is created.
+
+
+
+
+
+== `commandExecuteIn()`
+
+For persisted commands, the `commandExecuteIn()` attribute determines whether the `Command` should be executed in the foreground (the default) or executed in the background.
+
+Background execution means that the command is not executed immediately, but is available for a configured xref:rg.adoc#_rg_services-spi_manpage-BackgroundCommandService[`BackgroundCommandService`] to execute, eg by way of an in-memory scheduler such as Quartz. See xref:ug.adoc#_ug_headless-access_BackgroundCommandExecution[here] for further information on this topic.
+
+For example:
+
+[source,java]
+----
+public class Order {
+ @Action(
+ command=CommandReification.ENABLED,
+ commandExecuteIn=CommandExecuteIn.BACKGROUND)
+ public Invoice generateInvoice(...) { ... }
+}
+----
+
+will result in the `Command` being persisted but its execution deferred to a background execution mechanism. The
+returned object from this action is the persisted `Command` itself.
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_domainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_domainEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_domainEvent.adoc
new file mode 100644
index 0000000..b2a679c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_domainEvent.adoc
@@ -0,0 +1,146 @@
+[[_rg_annotations_manpage-Action_domainEvent]]
+= domainEvent()
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+Whenever a domain object (or list of domain objects) is to be rendered, the framework fires off multiple domain events for every property, collection and action of the domain object. In the cases of the domain object's actions, the events that are fired are:
+
+* hide phase: to check that the action is visible (has not been hidden)
+* disable phase: to check that the action is usable (has not been disabled)
+* validate phase: to check that the action's arguments are valid
+* pre-execute phase: before the invocation of the action
+* post-execute: after the invocation of the action
+
+Subscribers subscribe through the xref:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`] using either link:https://github.com/google/guava[Guava] or link:http://www.axonframework.org/[Axon Framework] annotations and can influence each of these phases.
+
+By default the event raised is `ActionDomainEvent.Default`. For example:
+
+[source,java]
+----
+public class ToDoItem {
+ @Action()
+ public ToDoItem completed() { ... }
+ ...
+}
+----
+
+The purpose of the `domainEvent()` attribute is to allows a custom subclass to be emitted instead. This attribute is also supported for xref:rg.adoc#_rg_annotations_manpage-Collection_domainEvent[collections] and xref:rg.adoc#_rg_annotations_manpage-Property_domainEvent[properties].
+
+For example:
+
+[source,java]
+----
+public class ToDoItem {
+ public static class CompletedEvent extends ActionDomainEvent<ToDoItem> { // <1>
+ private static final long serialVersionUID = 1L;
+ public CompletedEvent( // <2>
+ final ToDoItem source, // <3>
+ final Identifier identifier, // <4>
+ final Object... arguments) { // <5>
+ super("completed", source, identifier, arguments);
+ }
+ }
+ @Action(domainEvent=CompletedEvent.class)
+ public ToDoItem completed() { ... }
+}
+----
+<1> inherit from `ActionDomainEvent<T>` where `T` is the type of the domain object being interacted with
+<2> constructor called reflectively by the framework
+<3> populated with the object being interacted with (the source of the event)
+<4> identifier of the collection
+<5> action argument(s)
+
+
+The benefit is that subscribers can be more targetted as to the events that they subscribe to.
+
+
+
+
+== Subscribers
+
+Subscribers (which must be domain services) subscribe using either the link:https://github.com/google/guava[Guava] API or (if the xref:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`] has been appropriately configured) using the link:http://www.axonframework.org/[Axon Framework] API. The examples below use the Guava API.
+
+Subscribers can be either coarse-grained (if they subscribe to the top-level event type):
+
+[source,java]
+----
+@DomainService
+public class SomeSubscriber {
+ @Programmatic
+ @com.google.common.eventbus.Subscribe
+ public void on(ActionInteractionEvent ev) {
+ ...
+ }
+}
+----
+
+or can be fine-grained (by subscribing to specific event subtypes):
+
+[source,java]
+----
+@DomainService
+public class SomeSubscriber {
+ @Programmatic
+ @com.google.common.eventbus.Subscribe
+ public void on(ToDoItem.CompletedEvent ev) {
+ ...
+ }
+}
+----
+
+[TIP]
+====
+If the AxonFramework is being used, replace `@com.google.common.eventbus.Subscribe` with `@org.axonframework.eventhandling.annotation.EventHandler`.
+====
+
+
+The subscriber's method is called (up to) 5 times:
+
+* whether to veto visibility (hide)
+* whether to veto usability (disable)
+* whether to veto execution (validate)
+* steps to perform prior to the action being invoked.
+* steps to perform after the action has been invoked.
+
+The subscriber can distinguish these by calling `ev.getEventPhase()`. Thus the general form is:
+
+[source,java]
+----
+@Programmatic
+@com.google.common.eventbus.Subscribe
+public void on(ActionDomainEvent ev) {
+ switch(ev.getPhase()) {
+ case HIDE:
+ // call ev.hide() or ev.veto("") to hide the action
+ break;
+ case DISABLE:
+ // call ev.disable("...") or ev.veto("...") to disable the action
+ break;
+ case VALIDATE:
+ // call ev.invalidate("...") or ev.veto("...")
+ // if action arguments are invalid
+ break;
+ case EXECUTING:
+ break;
+ case EXECUTED:
+ break;
+ }
+}
+----
+
+It is also possible to abort the transaction during the executing or executed phases by throwing an exception. If the exception is a subtype of `RecoverableException` then the exception will be rendered as a user-friendly warning (eg Growl/toast) rather than an error.
+
+
+
+
+== Raising events programmatically
+
+Normally events are only raised for interactions through the UI. However, events can be raised programmatically either by calling the xref:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`] API directly, or by emulating the UI by
+wrapping the target object using the xref:rg.adoc#_rg_services-api_manpage-WrapperFactory[`WrapperFactory`] domain service.
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_hidden.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_hidden.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_hidden.adoc
new file mode 100644
index 0000000..0c4ffc8
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_hidden.adoc
@@ -0,0 +1,49 @@
+[[_rg_annotations_manpage-Action_hidden]]
+= `hidden()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+
+Actions can be hidden at the domain-level, indicating that they are not visible to the end-user. This attribute can also be applied to xref:rg.adoc#_rg_annotations_manpage-Property_hidden[properties] and xref:rg.adoc#_rg_annotations_manpage-Collection_hidden[collections].
+
+[TIP]
+====
+It is also possible to use xref:rg.adoc#_rg_annotations_manpage-ActionLayout_hidden[`@ActionLayout#hidden()`] or xref:rg.adoc#_rg_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:
+
+[source,java]
+----
+public class Customer {
+ @Action(hidden=Where.EVERYWHERE)
+ public void updateStatus() { ... }
+ ...
+}
+----
+
+The acceptable values for the `where` parameter are:
+
+* `Where.EVERYWHERE` or `Where.ANYWHERE` +
++
+The action should be hidden at all times.
+
+* `Where.NOWHERE` +
++
+The action should not be hidden.
+
+
+The other values of the `Where` enum have no meaning for a collection.
+
+
+
+[NOTE]
+====
+For actions of domain services the visibility is dependent upon its xref:rg.adoc#_rg_annotations_manpage-DomainService_nature[`@DomainService#nature()`] and also on whether it is contributed (as per xref:rg.adoc#_rg_annotations_manpage-ActionLayout_contributedAs[`@ActionLayout#contributedAs()`]).
+====
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_invokeOn.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_invokeOn.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_invokeOn.adoc
new file mode 100644
index 0000000..59c91ec
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_invokeOn.adoc
@@ -0,0 +1,64 @@
+[[_rg_annotations_manpage-Action_invokeOn]]
+= `invokeOn()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `invokeOn()` attribute indicates whether the an action can be invoked on a single object (the default) and/or on many objects in a collection.
+
+For example:
+
+[source,java]
+----
+public class ToDoItem {
+ @Action(invokeOn=InvokeOn.OBJECT_AND_COLLECTION)
+ public void markAsCompleted() {
+ setCompleted(true);
+ }
+ ...
+}
+----
+
+
+Actions to be invoked on collection (currently) have a number of constraints. It:
+
+* must take no arguments
+* cannot be hidden (any annotations or supporting methods to that effect will be ignored)
+* cannot be disabled (any annotations or supporting methods to that effect will be ignored).
+
+The example given above is probably ok, because `setCompleted()` is most likely idempotent. However, if the action also called some other method, then we should add a guard.
+
+For example, for this non-idempotent action:
+
+[source,java]
+----
+@Action(invokeOn=InvokeOn.OBJECT_AND_COLLECTION)
+public void markAsCompleted() {
+ setCompleted(true);
+ todoTotalizer.incrementNumberCompleted();
+}
+----
+
+we should instead write it as:
+
+[source,java]
+----
+@Action(invokeOn=InvokeOn.OBJECT_AND_COLLECTION)
+public void markAsCompleted() {
+ if(isCompleted()) {
+ return;
+ }
+ setCompleted(true);
+ todoTotalizer.incrementNumberCompleted();
+}
+----
+
+[NOTE]
+====
+This attribute has no meaning if annotated on an action of a domain service.
+====
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_publishing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_publishing.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_publishing.adoc
new file mode 100644
index 0000000..62119db
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_publishing.adoc
@@ -0,0 +1,53 @@
+[[_rg_annotations_manpage-Action_publishing]]
+= `publishing()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `publishing()` attribute determines whether and how an action invocation is published via the registered implementation of a xref:rg.adoc#_rg_services-spi_manpage-PublishingService[`PublishingService`]). This attribute is also supported for xref:rg.adoc#_rg_annotations_manpage-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:ug.adoc#_ug_runtime_configuring-core[configuration property] `isis.services.publish.actions` is used to determine the whether the action is published:
+
+* `all` +
++
+all actions are published
+
+* `ignoreSafe` (or `ignoreQueryOnly`) +
++
+actions with safe (read-only) semantics are ignored, but actions which may modify data are not ignored
+
+* `none` +
++
+no actions are published
+
+If there is no configuration property in `isis.properties` then publishing is automatically enabled.
+
+This default can be overridden on an action-by-action basis; if `publishing()` is set to `ENABLED` then the action invocation is published irrespective of the configured value; if set to `DISABLED` then the action invocation is _not_ published, again irrespective of the configured value.
+
+For example:
+
+[source,java]
+----
+public class Order {
+ @Action(publishing=Publishing.ENABLED) // <1>
+ public Invoice generateInvoice(...) { ... }
+}
+----
+<1> because set to enabled, will be published irrespective of the configured value.
+
+
+
+
+== `publishingPayloadFactory()`
+
+The (optional) related `publishingPayloadFactory()` specifies the class to use to create the (payload of the) event to be published by the publishing factory.
+
+Rather than simply broadcast that the action was invoked, the payload factory allows a "fatter" payload to be instantiated that can eagerly push commonly-required information to all subscribers. For at least some subscribers this should avoid the necessity to query back for additional information.
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_restrictTo.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_restrictTo.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_restrictTo.adoc
new file mode 100644
index 0000000..d526762
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_restrictTo.adoc
@@ -0,0 +1,30 @@
+[[_rg_annotations_manpage-Action_restrictTo]]
+= `restrictTo()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 actions are available irrespective of the xref:ug.adoc#_ug_runtime_deployment-types[deployment mode]. The `restrictTo()` attribute specifies whether the action should instead be restricted to only available in prototyping mode.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ public Order placeNewOrder() { ... }
+ public List<Order> listRecentOrders() { ... }
+
+ @Action(restrictTo=RestrictTo.PROTOTYPING)
+ public List<Order> listAllOrders() { ... }
+ ...
+}
+----
+
+In this case the listing of all orders (in the `listAllOrders()` action) probably doesn't make sense for production; there could be thousands or millions. However, it would be useful to disaply how for a test or demo system where there are only a handful of orders.
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_semantics.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_semantics.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_semantics.adoc
new file mode 100644
index 0000000..3fccf4c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_semantics.adoc
@@ -0,0 +1,36 @@
+[[_rg_annotations_manpage-Action_semantics]]
+= `semantics()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `semantics()` attribute describes whether the invocation is safe (as no side-effects), is idempotent (may have side-effects but always has the same post-conditions), or is neither safe nor idempotent. If the annotation is missing then the framework assumes non-idempotent.
+
+[TIP]
+====
+The attribute was originally introduced for the xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer] in order that action invocations could be made available using either HTTP GET, PUT or POST (respectively).
+
+Since then its use has been extended into the core runtime. For example, it is now aso used for the in-built concurrency checking; the invocation of a safe action does not perform a concurrency check, whereas non-safe actions do perform a concurrency check.
+====
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ @Action(semantics=SemanticsOf.SAFE)
+ public CreditRating checkCredit() { ... }
+
+ @Action(semantics=SemanticsOf.IDEMPOTENT)
+ public void changeOfAddress(Address address) { ... }
+
+ @Action(semantics=SemanticsOf.NON_IDEMPOTENT)
+ public Order placeNewOrder() { ... }
+ ...
+}
+----
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_typeOf.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_typeOf.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_typeOf.adoc
new file mode 100644
index 0000000..8647912
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_typeOf.adoc
@@ -0,0 +1,31 @@
+[[_rg_annotations_manpage-Action_typeOf]]
+= `typeOf()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `typeOf()` attribute specifies the expected type of an element returned by the action (returning a collection), when for whatever reason the type cannot be inferred from the generic type, or to provide a hint about the actual run-time (as opposed to compile-time) type. This attribute can also be specified for xref:rg.adoc#_rg_annotations_manpage-Collection_typeOf[collections].
+
+
+For example:
+
+[source,java]
+----
+public void AccountService {
+ @Action(typeOf=Customer.class)
+ public List errantAccounts() {
+ return customers.allNewCustomers();
+ }
+ ...
+
+ @Inject
+ CustomerRepository customers;
+}
+----
+
+[TIP]
+====
+In general we recommend that you use generics instead, eg `List<Customer>`.
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Collection.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Collection.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Collection.adoc
new file mode 100644
index 0000000..2186eab
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Collection.adoc
@@ -0,0 +1,106 @@
+[[_rg_annotations_manpage-Collection]]
+= `@Collection`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@Collection` annotation applies to collections collecting together all domain semantics within a single annotation.
+
+The table below summarizes the annotation's attributes.
+
+.`@Collection` attributes
+[cols="2,2,4a", options="header"]
+|===
+
+| Attribute
+| Values (default)
+| Description
+
+
+|xref:rg.adoc#_rg_annotations_manpage-Collection_domainEvent[`domainEvent()`]
+|subtype of `CollectionDomainEvent` +
+(`CollectionDomainEvent.Default`)
+|the event type to be posted to the xref:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`] to broadcast the collection's business rule checking (hide, disable, validate) and its modification (before and after).
+
+
+|xref:rg.adoc#_rg_annotations_manpage-Collection_editing[`editing()`]
+|`ENABLED`, `DISABLED`, `AS_CONFIGURED` +
+(`AS_CONFIGURED`)
+|whether a collection can be added to or removed from within the UI
+
+
+|`editingDisabledReason()`
+|String value
+|if `editing()` is `DISABLED`, provides a reason as to why.
+
+
+|xref:rg.adoc#_rg_annotations_manpage-Collection_hidden[`hidden()`]
+|`EVERYWHERE`, `OBJECT_FORMS`, `NOWHERE` +
+(`NOWHERE`)
+|indicates where (in the UI) the collection should be hidden from the user.
+
+
+|xref:rg.adoc#_rg_annotations_manpage-Collection_notPersisted[`notPersisted()`]
+|`true`, `false` +
+(`false`)
+|whether to exclude from snapshots. +
+
+[WARNING]
+====
+Collection must also be annotated with `@javax.jdo.annotations.NotPersistent` in order to not be persisted.
+====
+
+
+
+|xref:rg.adoc#_rg_annotations_manpage-Collection_typeOf[`typeOf()`]
+|
+|hints as to the run-time type of the objects within that collection (as a fallback)
+
+|===
+
+
+For example:
+
+[source,java]
+----
+public class ToDoItem {
+ public static class DependenciesChangedEvent
+ extends CollectionDomainEvent<ToDoItem, ToDoItem> {
+ private static final long serialVersionUID = 1L;
+ public DependenciesChangedEvent(
+ ToDoItem source,
+ Identifier identifier,
+ Of of,
+ ToDoItem value) {
+ super(source, identifier, of, value);
+ }
+ }
+ @Collection(
+ domainEvent=DependenciesChangedEvent.class,
+ editing = Editing.ENABLED,
+ hidden = Where.NOWHERE, // <1>
+ notPersisted = false, // <2>
+ typeOf = ToDoItem.class // <3>
+ )
+ public SortedSet<ToDoItem> getDependencies() { ... }
+ ...
+}
+----
+<1> default value, so could be omitted
+<2> default value, so could be omitted
+<3> default value, so could be omitted
+
+
+
+
+
+include::_rg_annotations_manpage-Collection_domainEvent.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-Collection_editing.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-Collection_hidden.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-Collection_notPersisted.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-Collection_typeOf.adoc[leveloffset=+1]
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout.adoc
new file mode 100644
index 0000000..1e4988c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout.adoc
@@ -0,0 +1,121 @@
+[[_rg_annotations_manpage-CollectionLayout]]
+= `@CollectionLayout`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@CollectionLayout` annotation applies to collections, collecting together all UI hints within a single
+annotation. It is also possible to apply the annotation to actions of domain services that are acting as contributed collections.
+
+The table below summarizes the annotation's attributes.
+
+.`@CollectionLayout` attributes
+[cols="2,2,4a", options="header"]
+|===
+
+| Attribute
+| Values (default)
+| Description
+
+
+|xref:rg.adoc#_rg_annotations_manpage-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:ug.adoc#_ug_runtime_application-specific_application-css[`application.css`]
+
+
+|xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_describedAs[`describedAs()`]
+|String.
+|description of this collection, eg to be rendered in a tooltip.
+
+
+|xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_hidden[`hidden()`]
+|`EVERYWHERE`, `OBJECT_FORMS`, `NOWHERE` +
+(`NOWHERE`)
+|indicates where (in the UI) the collection should be hidden from the user.
+
+
+|xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_named[named()]
+|String.
+|to override the name inferred from the collection's name in code. +
+
+A typical use case is if the desired name is a reserved Java keyword, such as `default` or `package`.
+
+
+|namedEscaped()
+|`true`,`false` (`true`)
+|whether to HTML escape the name of this property.
+
+
+|xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_paged[`paged()`]
+|Positive integer
+|the page size for instances of this class when rendered within a table.
+
+
+|xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_render[`render()`]
+|`EAGERLY`, `LAZILY` +
+(`LAZILY`)
+|whether the collection should be (eagerly) rendered open or (lazily) rendered closed
+
+
+|xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_sortedBy[`sortedBy()`]
+|Subclass of `java.util.Comparator` for element type
+|indicates that the elements in the `java.util.SortedSet` collection should be sorted according to a specified `Comparator` rather than their natural sort order.
+
+|===
+
+
+
+
+For example:
+
+[source,java]
+----
+public class ToDoItem {
+ @CollectionLayout(
+ cssClass="x-key",
+ named="Todo items that are <i>dependencies</i> of this item.",
+ namedEscaped=false,
+ describedAs="Other todo items that must be completed before this one",
+ labelPosition=LabelPosition.LEFT,
+ render=EAGERLY)
+ public SortedSet<ToDoItem> getDependencies() { ... }
+ ...
+}
+----
+
+
+
+As an alternative to using the `@CollectionLayout` annotation, a dynamic layout using xref:rg.adoc#_rg_object-layout_dynamic[`.layout.json`] file can be specified; for example:
+
+[source,javascript]
+----
+"dependencies": {
+ "collectionLayout": {
+ "cssClass": "x-key",
+ "named": "Todo items that are <i>dependencies</i> of this item.",
+ "namedEscaped": false,
+ "describedAs": "Other todo items that must be completed before this one",
+ "labelPosition": "LEFT",
+ "render": "EAGERLY"
+ }
+}
+----
+
+
+
+
+
+include::_rg_annotations_manpage-CollectionLayout_cssClass.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-CollectionLayout_describedAs.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-CollectionLayout_hidden.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-CollectionLayout_named.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-CollectionLayout_paged.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-CollectionLayout_render.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-CollectionLayout_sortedBy.adoc[leveloffset=+1]
+
+
+
+
+
+
[36/45] isis git commit: ISIS-1133: breaking out reference guide and
devenv guide;
moving appendices' release notes and migration notes to other docs;
improving the documentation page.
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-BookmarkService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-BookmarkService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-BookmarkService.adoc
new file mode 100644
index 0000000..d56a2b4
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-BookmarkService.adoc
@@ -0,0 +1,117 @@
+[[_rg_services-api_manpage-BookmarkService]]
+= `BookmarkService`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `BookmarkService` provides the ability to obtain a serializable `o.a.i.applib.bookmarks.Bookmark` for any (persisted) domain object, and to lookup domain objects given a `Bookmark`. This can then in turn be converted to and from a string.
+
+For example, a `Customer` object with:
+
+* an object type of "custmgmt.Customer" (as per xref:rg.adoc#_rg_annotations_manpage-DomainObject_objectType[`DomainObject#objectType()`] or equivalent) , and
+* an id=123
+
+could correspond to a `Bookmark` with a string representation of `custmgmt.Customer|123`.
+
+[NOTE]
+====
+A `Bookmark` is little more than an API equivalent of Isis' internal `Oid` (object identifier). Nevertheless, the ability to uniquely address _any_ domain object within an Isis system -- to in effect provide a URN -- is immensely useful.
+
+For example, a `Bookmark` could be converted into a barcode, and then this used for automated scanning of correspondence from a customer.
+====
+
+``Bookmark``s are used by several other domain services as a means of storing areference to an arbitrary object (a polymorphic relationship). For example, the (non-ASF) http://github.com/isisaddons/isis-module-auditing[Isis addons' auditing] module's implementation of xref:rg.adoc#_rg_services-spi_manpage-AuditingService[`AuditingService`] uses bookmarks to capture the object that is being audited.
+
+[TIP]
+====
+One downside of using ``Bookmark``s is that there is no way for the JDO/DataNucleus objectstore to enforce any kind of referental integrity. However, the (non-ASF) http://github.com/isisaddons/isis-module-poly[Isis addons' poly] module describes and supports a design pattern to address this requirement.
+====
+
+
+
+
+== API & Implementation
+
+The API defined by `BookmarkService` is:
+
+[source,java]
+----
+public interface BookmarkService {
+ @Programmatic
+ Object lookup(BookmarkHolder bookmarkHolder);
+ @Programmatic
+ Object lookup(Bookmark bookmark);
+ @Programmatic
+ <T> T lookup(Bookmark bookmark, Class<T> cls); // <1>
+ @Programmatic
+ Bookmark bookmarkFor(Object domainObject);
+ @Programmatic
+ Bookmark bookmarkFor(Class<?> cls, String identifier);
+}
+----
+<1> same as `lookup(Bookmark bookmark)`, but downcasts to the specified type.
+
+
+The core framework provides a default implementation of this API, namely `o.a.i.core.metamodel.services.bookmarks.BookmarkServiceDefault`
+
+
+== `BookmarkHolder`
+
+The `BookmarkHolder` interface is intended to be implemented by domain objects that use a `Bookmark` to reference a (single) domain object; an example might be a class such as the audit entry, mentioned above. The interface is simply:
+
+
+[source,java]
+----
+public interface BookmarkHolder {
+ @Programmatic
+ Bookmark bookmark();
+}
+
+----
+
+There are two services that will contribute to this interface:
+
+* `BookmarkHolderActionContributions` will provide a `lookup(...)` action
+* `BookmarkHolderAssociationContributions` provides an `object` property.
+
+Either of these can be suppressed, if required, using a vetoing subscriber. For example, to suppress the `object` property (so that only the `lookup(...)` action is ever shown for implementations of `BookmarkHolder`, define:
+
+[source,java]
+----
+@DomainObject
+public class AlwaysHideBookmarkHolderAssociationsObjectProperty {
+ @Subscribe
+ public void on(BookmarkHolderAssociationContributions.ObjectDomainEvent ev) {
+ ev.hide();
+ }
+}
+----
+
+A more sophisticated implementation could look inside the passed `ev` argument and selectively hide or not based on the contributee.
+
+
+
+
+== Usage by other services
+
+Bookmarks are used by the (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module's implementation of xref:rg.adoc#_rg_services-api_manpage-BackgroundCommandService[`BackgroundCommandService`], which uses a bookmark to capture the target object on which an action will be invoked subsequently.
+
+Bookmarks are also used by the (non-ASF) http://github.com/isisaddons/isis-module-publishing[Isis addons' publishing] module's implementation of xref:rg.adoc#_rg_services-spi_manpage-PublishingService[`PublishingService`], and by the (non-ASF) http://github.com/isisaddons/isis-module-auditing[Isis addons' auditing] module's implementation of xref:rg.adoc#_rg_services-spi_manpage-AuditingService[`AuditingService`].
+
+
+
+
+== Registering the Service
+
+Assuming that the `configuration-and-annotation` services installer is configured:
+
+[source,ini]
+----
+isis.services-installer=configuration-and-annotation
+----
+
+then 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/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-BulkInteractionContext.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-BulkInteractionContext.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-BulkInteractionContext.adoc
new file mode 100644
index 0000000..7c96f94
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-BulkInteractionContext.adoc
@@ -0,0 +1,9 @@
+[[_rg_services-api_manpage-BulkInteractionContext]]
+= `BulkInteractionContext`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 service is deprecated, replaced by xref:rg.adoc#_rg_services-api_manpage-ActionInvocationContext[`ActionInvocationContext`].
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-ClockService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-ClockService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-ClockService.adoc
new file mode 100644
index 0000000..48391a8
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-ClockService.adoc
@@ -0,0 +1,104 @@
+[[_rg_services-api_manpage-ClockService]]
+= `ClockService`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 deal with dates and times in one way or another. For example, if an `Order` is placed, then the `Customer` may have 30 days to pay the `Invoice`, otherwise a penalty may be levied.
+
+However, such date/time related functionality can quickly complicate automated testing: "today+30" will be a different value every time the test is run.
+
+Even disregarding testing, there may be a requirement to ensure that date/times are obtained from an NNTP server (rather than the system PC). While instantiating a `java.util.Date` to current the current time is painless enough, we would not want complex technical logic for querying an NNTP server spread around domain logic code.
+
+Therefore it's common to provide a domain service whose responsibility is to provide the current time. This service can be injected into any domain object (and can be mocked out for unit testing). Isis provides such a facade through the `ClockService`.
+
+
+
+== API & Implementation
+
+The API defined by `ClockService` is:
+
+[source,java]
+----
+@DomainService(nature = NatureOfService.DOMAIN)
+public class ClockService {
+ @Programmatic
+ public LocalDate now() { ... }
+ @Programmatic
+ public LocalDateTime nowAsLocalDateTime() { ... }
+ @Programmatic
+ public DateTime nowAsDateTime() { ... }
+ @Programmatic
+ public Timestamp nowAsJavaSqlTimestamp() { ... }
+ @Programmatic
+ public long nowAsMillis() { ... }
+}
+----
+
+This class (`o.a.i.applib.services.clock.ClockService`) is also the default implementation. The time provided by this default implementation is based on the system clock.
+
+
+
+
+== Testing Support
+
+The default `ClockService` implementation in fact simply delegates to another class defined in the API, namely the `o.a.i.applib.clock.Clock`, an abstract singleton class. It is not recommended that your code use the `Clock` directly, but you should understand how this all works:
+
+* 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:ug.adoc#_ug_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:ug.adoc#_ug_runtime_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.
+
+
+
+=== Alternative Implementations
+
+Suppose you want (as discussed in the introduction to this service) to use a clock that delegates to NNTP. For most domain services this would amount to implementing the appropriate service and registering in `isis.properties` so that it is used in preference to any implementations provided by default by the framework.
+
+In the case of the `ClockService`, though, this approach (unfortunately) will not work, because parts of Isis (still) delegate to the `Clock` singleton rather than using the `ClockService` domain service.
+
+The workaround, therefore, is to implement your functionality as a subclass of `Clock`. You can write a domain service that will ensure that your implementation is used ahead of any implementations provided by the framework.
+
+For example:
+
+[source,java]
+----
+@DomainService(nature=NatureOfService.DOMAIN)
+public class NntpClockServiceInitializer {
+ @Programmatic
+ @PostConstruct
+ public void postConstruct(Map<String,String> properties) {
+ new NntpClock(properties); // <1>
+ }
+ private static class NntpClock extends Clock {
+ NntpClock(Map<String,String> properties) { ... } // <2>
+ protected long time() { ... } // <3>
+ ... NNTP stuff here ...
+ }
+ }
+}
+----
+<1> enough to simply instantiate the `Clock`; it will register itself as singleton
+<2> connect to NNTP service using configuration properties from `isis.properties`
+<3> call to NNTP service here
+
+
+
+
+== Registering the Service
+
+Assuming that the `configuration-and-annotation` services installer is configured:
+
+[source,ini]
+----
+isis.services-installer=configuration-and-annotation
+----
+
+then Isis' core implementation of `ClockService` is automatically registered (it is annotated with `@DomainService`) so no further configuration is required.
+
+If you want to use a different implementation of `Clock`, eg delegating to NNTP, then do _not_ register directly, but instead subclass from `o.a.i.applib.clock.Clock` singleton (as described in the section above).
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-CommandContext.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-CommandContext.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-CommandContext.adoc
new file mode 100644
index 0000000..bbde20f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-CommandContext.adoc
@@ -0,0 +1,217 @@
+[[_rg_services-api_manpage-CommandContext]]
+= `CommandContext`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `CommandContext` service is a xref:rg.adoc#_rg_annotations_manpage-RequestScoped[request-scoped] service that reifies the invocation of an action on a domain object into an object itself. This reified information is encapsulated within the `Command` object.
+
+By default, the `Command` is held in-memory only; once the action invocation has completed, the `Command` object is gone. The optional
+ supporting xref:rg.adoc#_rg_services-spi_manpage-CommandService[`CommandService`] enables the implementation of `Command` to be pluggable. With an appropriate implementation (eg as provided by the (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module's xref:rg.adoc#_rg_services-spi_manpage-CommandService[`CommandService`]) the `Command` may then be persisted.
+
+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:rg.adoc#_rg_services-api_manpage-BackgroundService[`BackgroundService`]
+* if xref:rg.adoc#_rg_services-spi_manpage-AuditingService[`AuditingService`] 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) through the unique `transactionId` GUID
+* if xref:rg.adoc#_rg_services-spi_manpage-PublishingService[`PublishingService`] is configured, they provide better traceability as the `Command` is also correlated with any published events, again through the unique `transactionId` GUID
+
+Assuming that the `CommandService` supports persistent `Command`s, the associated xref:rg.adoc#_rg_annotations_manpage-Action_command[`@Action#command()`] annotation 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.
+
+
+
+[[_rg_services-api_manpage-CommandContext_screencast]]
+== Screencast
+
+
+The screencast provides a run-through of the command (profiling) service, auditing service, publishing service. It also shows how commands can be run in the background either explicitly by scheduling through the background service or implicitly by way of a framework annotation.
+
+video::tqXUZkPB3EI[youtube,width="640px",height="360px"]
+
+[NOTE]
+====
+Note that this screencast shows an earlier version of the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] UI (specifically, pre 1.8.0).
+====
+
+
+
+
+== API & Implementation
+
+The `CommandContext` request-scoped service defines the following very simple API:
+
+[source,java]
+----
+@RequestScoped
+public class CommandContext {
+ @Programmatic
+ public Command getCommand() { ... }
+}
+----
+
+This class (`o.a.i.applib.services.CommandContext`) is also the default implementation. Under normal circumstances there shouldn't be any need to replace this implementation with another.
+
+The `Command` type referenced above is in fact an interface, defined as:
+
+[source,java]
+----
+public interface Command extends HasTransactionId {
+
+ public abstract String getUser(); // <1>
+ public abstract Timestamp getTimestamp(); // <2>
+
+ public abstract Bookmark getTarget(); // <3>
+ public abstract String getMemberIdentifier(); // <4>
+ public abstract String getTargetClass(); // <5>
+ public abstract String getTargetAction(); // <6>
+ public String getArguments(); // <7>
+ public String getMemento(); // <8>
+
+ public ExecuteIn getExecuteIn(); // <9>
+ public Executor getExecutor(); // <10>
+ public Persistence getPersistence(); // <11>
+ public boolean isPersistHint(); // <12>
+
+ public abstract Timestamp getStartedAt(); // <13>
+ public abstract Timestamp getCompletedAt(); // <14>
+ public Command getParent(); // <15>
+
+ public Bookmark getResult(); // <16>
+ public String getException(); // <17>
+}
+----
+<1> `getUser()` - is the user that initiated the action.
+<2> `getTimestamp()` - the date/time at which this action was created.
+<3> `getTarget()` - bookmark of the target object (entity or service) on which this action was performed
+<4> `getMemberIdentifier()` - holds a string representation of the invoked action
+<5> `getTargetClass()` - a human-friendly description of the class of the target object
+<6> `getTargetAction()` - a human-friendly name of the action invoked on the target object
+<7> `getArguments()` - a human-friendly description of the arguments with which the action was invoked
+<8> `getMemento()` - a formal (XML or similar) specification of the action to invoke/being invoked
+<9> `getExecuteIn()` - whether this command is executed in the foreground or background
+<10> `getExecutor()` - the (current) executor of this command, either user, or background service, or other (eg redirect after post).
+<11> `getPersistence()`- the policy controlling whether this command should ultimately be persisted (either "persisted", "if hinted", or "not persisted")
+<12> `isPersistHint()` - whether that the command should be persisted, if persistence policy is "if hinted".
+<13> `getStartedAt()` - the date/time at which this action started (same as `timestamp` property for foreground commands)
+<14> `getCompletedAt()` - the date/time at which this action completed.
+<15> `getParent()` - for actions created through the `BackgroundService`, captures the parent action
+<16> `getResult()` - bookmark to object returned by action, if any
+<17> `getException()` - exception stack trace if action threw exception
+
+
+
+
+== Usage
+
+The typical way to indicate that an action should be treated as a command is to annotate it with the xref:rg.adoc#_rg_annotations_manpage-Action_command[`@Action#command()`] annotation.
+
+For example:
+
+[source,java]
+----
+public class ToDoItem ... {
+ @Action(command=CommandReification.ENABLED)
+ public ToDoItem completed() { ... }
+}
+----
+
+
+[TIP]
+====
+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:rg.adoc#_rg_annotations_manpage-Action_command[`@Action#command()`] and xref:ug.adoc#_ug_runtime_configuring-core[runtime configuration] for further details.
+====
+
+
+The xref:rg.adoc#_rg_annotations_manpage-Action_command[`@Action#command()`] annotation can also be used to specify whether the command should be performed in the background, for example:
+
+[source,java]
+----
+public class ToDoItem ... {
+ @Command(executeIn=ExecuteIn.BACKGROUND)
+ public ToDoItem scheduleImplicitly() {
+ completeSlowly(3000);
+ return this;
+ }
+}
+----
+
+When a background command is invoked, the user is returned the command object itself (to provide a handle to the command being invoked).
+
+This requires that an implementation of xref:rg.adoc#_rg_services-spi_manpage-CommandService[`CommandService`] that persists the commands (such as the (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module's `CommandService`) is configured. It also requires that a scheduler is configured to execute the background commands, see xref:rg.adoc#_rg_services-spi_manpage-BackgroundCommandService[`BackgroundCommandService`]).
+
+
+
+== Interacting with the services
+
+Typically the domain objects have little need to interact with the `CommandContext` and `Command` directly; what is more useful is that these are persisted in support of the various use cases identified above.
+
+One case however where a domain object might want to obtain the `Command` is to determine whether it has been invoked in the foreground, or in the background. It can do this using the `getExecutedIn()` method:
+
+Although not often needed, this then allows the domain object to access the `Command` object through the `CommandContext` service. To expand th above example:
+
+
+[source,java]
+----
+public class ToDoItem ... {
+ @Action(
+ command=CommandReification.ENABLED,
+ commandExecuteIn=CommandExecuteIn.BACKGROUND
+ )
+ public ToDoItem completed() {
+ ...
+ Command currentCommand = commandContext.getCommand();
+ ...
+ }
+ @Inject
+ CommandContext commandContext;
+}
+----
+
+
+If run in the background, it might then notify the user (eg by email) if all work is done.
+
+This leads us onto a related point, distinguishing the current effective user vs the originating "real" user. When running in the foreground, the current user can be obtained from the `DomainObjectContainer`, using:
+
+[source,java]
+----
+String user = container.getUser().getName();
+----
+
+If running in the background, however, then the current user will be the credentials of the background process, for example as run by a Quartz scheduler job.
+
+The domain object can still obtain the original ("effective") user that caused the job to be created, using:
+
+[source,java]
+----
+String user = commandContext.getCommand().getUser();
+----
+
+
+
+
+
+== Registering the Services
+
+Assuming that the `configuration-and-annotation` services installer is configured:
+
+[source,ini]
+----
+isis.services-installer=configuration-and-annotation
+----
+
+then Isis' core implementation of `CommandContext` service is automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
+
+
+
+
+
+
+== Related Services
+
+As discussed above, the supporting xref:rg.adoc#_rg_services-spi_manpage-CommandService[`CommandService`] enables `Command` objects to be persisted. Other related services are the xref:rg.adoc#_rg_services-api_manpage-BackgroundService[`BackgroundService`] and xref:rg.adoc#_rg_services-spi_manpage-BackgroundCommandService[`BackgroundCommandService`]). For `BackgroundService` captures commands for execution in the background, while the [BackgroundCommandService] persists such commands for execution.
+
+The implementations of `CommandService` and `BackgroundCommandService` are intended to go together, so that persistent parent `Command`s can be associated with their child background `Command`s.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DeepLinkService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DeepLinkService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DeepLinkService.adoc
new file mode 100644
index 0000000..8d7fba3
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DeepLinkService.adoc
@@ -0,0 +1,57 @@
+[[_rg_services-api_manpage-DeepLinkService]]
+= `DeepLinkService`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `DeepLinkService` provides the ability to obtain a `java.net.URI` that links to a representation of any (persisted) domain entity or
+view model.
+
+A typical use case is to generate a clickable link for rendering in an email, PDF, tweet or other communication.
+
+
+
+== API & Implementation
+
+The API defined by `DeepLinkService` is:
+
+[source,java]
+----
+public interface DeepLinkService {
+ URI deepLinkFor(Object domainObject); // <1>
+}
+----
+<1> Creates a URI that can be used to obtain a representation of the provided domain object in one of the Isis viewers.
+
+The xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] this provides an implementation for accessing the representation through this viewer. (For the xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer], a URL can be constructed according to the link:http://www.restfulobjects.org[Restful Objects spec] in conjunction with a `Bookmark` obtained via the xref:rg.adoc#_rg_services-api_manpage-BookmarkService[`BookmarkService`]).
+
+
+
+== Usage within the framework
+
+The xref:rg.adoc#_rg_services-spi_manpage-EmailNotificationService[`EmailNotificationService`] uses this service in order to generate emails as part of xref:ug.adoc#_ug_wicket-viewer_features_user-registration[user registration].
+
+
+
+== Implementations
+
+The Wicket viewer core framework provides a default implementation of this API:
+
+* `org.apache.isis.viewer.wicket.viewer.services.DeepLinkServiceWicket`
+
+
+
+
+== Registering the Services
+
+Assuming that the `configuration-and-annotation` services installer is configured:
+
+[source,ini]
+----
+isis.services-installer=configuration-and-annotation
+----
+
+and that the xref:ug.adoc#_ug_wicket-viewer[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/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer.adoc
new file mode 100644
index 0000000..b359f8a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer.adoc
@@ -0,0 +1,43 @@
+[[_rg_services-api_manpage-DomainObjectContainer]]
+= `DomainObjectContainer`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `DomainObjectContainer` service provides a set of general purpose functionality for domain objects to call. Principal amongst these are a generic APIs for querying objects and creating and persisting objects. In addition, the service provides access to security context (the "current user"), allows information and warning messages to be raised, and various other miscellaneous functions.
+
+[NOTE]
+====
+Compared to other services provided by Isis, the `DomainObjectContainer` provides by far the most number of methods, addressing several quite distinct responsibilities. This is a historical accident: in early versions of Isis the `DomainObjectContainer` was the one and only domain service provided by the framework.
+
+In the future we may deprecate this service and break out its responsibilities into a number of small services. However, given how important this service was in days past, we are unlikely to delete it as a service even once it has been deprecated.
+====
+
+The sections below discuss the functions provided by the service, broken out into categories.
+
+
+include::_rg_services-api_manpage-DomainObjectContainer_object-creation-api.adoc[leveloffset=+1]
+include::_rg_services-api_manpage-DomainObjectContainer_generic-repository-api.adoc[leveloffset=+1]
+include::_rg_services-api_manpage-DomainObjectContainer_object-persistence-api.adoc[leveloffset=+1]
+include::_rg_services-api_manpage-DomainObjectContainer_messages-api.adoc[leveloffset=+1]
+include::_rg_services-api_manpage-DomainObjectContainer_security-api.adoc[leveloffset=+1]
+include::_rg_services-api_manpage-DomainObjectContainer_presentation-api.adoc[leveloffset=+1]
+include::_rg_services-api_manpage-DomainObjectContainer_validation-api.adoc[leveloffset=+1]
+include::_rg_services-api_manpage-DomainObjectContainer_properties-api.adoc[leveloffset=+1]
+include::_rg_services-api_manpage-DomainObjectContainer_services-api.adoc[leveloffset=+1]
+
+
+
+
+
+== Registering the Service
+
+Assuming that the `configuration-and-annotation` services installer is configured:
+
+[source,ini]
+----
+isis.services-installer=configuration-and-annotation
+----
+
+then 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/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer_generic-repository-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer_generic-repository-api.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer_generic-repository-api.adoc
new file mode 100644
index 0000000..b0828cb
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer_generic-repository-api.adoc
@@ -0,0 +1,89 @@
+[[_rg_services-api_manpage-DomainObjectContainer_generic-repository-api]]
+= Generic Repository 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/
+
+
+
+The repository API acts as an abstraction over the JDO/DataNucleus objectstore. You can use it during prototyping to write naive queries (find all rows, then filter using the Guava `Predicate` API, or you can use it to call JDO link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/query.html#named[named queries] using JDOQL.
+
+As an alternative, you could also use link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/jdoql_typesafe.html[JDO typesafe queries] through the xref:rg.adoc#_rg_services-api_manpage-IsisJdoSupport[`IsisJdoSupport`] service.
+
+
+[source,java]
+----
+public interface DomainObjectContainer {
+ @Programmatic
+ public <T> List<T> allInstances(Class<T> ofType, long... range); // <1>
+ @Programmatic
+ <T> List<T> allMatches(Query<T> query); // <2>
+ @Programmatic
+ <T> List<T> allMatches(Class<T> ofType, Predicate<? super T> predicate, long... range); // <3>
+ @Programmatic
+ <T> List<T> allMatches(Class<T> ofType, String title, long... range); // <4>
+ @Programmatic
+ <T> List<T> allMatches(Class<T> ofType, T pattern, long... range); // <5>
+ ...
+}
+----
+<1> all persisted instances of specified type. Mostly for prototyping, though can be useful to obtain all instances of domain entities if the number is known to be small. The optional varargs parameters are for paging control; more on this below.
+<2> all persistence instances matching the specified `Query`. Query itself is an Isis abstraction on top of JDO/DataNucleus' Query API. *This is the primary API used for querying*
+<3> all persistenced instances of specified type matching `Predicate`. Only really intended for prototyping because in effect constitutes a client-side WHERE clause
+<4> all persisted instances with the specified string as their title. Only very occasionally used
+<5> all persisted instances matching object (query-by-example). Only very occasionally used
+
+There are various implementations of the `Query` API, but these either duplicate functionality of the other overloads of `allMatches(...)` or they are not supported by the JDO/DataNucleus object store. The only significant implementation of `Query` to be aware of is `QueryDefault`, which identifies a named query and a set of parameter/argument tuples.
+
+For example, in the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] the `ToDoItem` is annotated:
+
+[source,java]
+----
+@javax.jdo.annotations.Queries( {
+ @javax.jdo.annotations.Query(
+ name = "findByAtPathAndComplete", language = "JDOQL", // <1>
+ value = "SELECT "
+ + "FROM todoapp.dom.module.todoitem.ToDoItem "
+ + "WHERE atPath.indexOf(:atPath) == 0 " // <2>
+ + " && complete == :complete"), // <3>
+ ...
+})
+public class ToDoItem ... {
+ ...
+}
+----
+<1> name of the query
+<2> defines the `atPath` parameter
+<3> defines the `complete` parameter
+
+This JDO query definitions are used in the `ToDoItemRepositoryImplUsingJdoql` service:
+
+[source,java]
+----
+@DomainService(nature = NatureOfService.DOMAIN)
+public class ToDoItemRepositoryImplUsingJdoql implements ToDoItemRepositoryImpl {
+ @Programmatic
+ public List<ToDoItem> findByAtPathAndCategory(final String atPath, final Category category) {
+ return container.allMatches(
+ new QueryDefault<>(ToDoItem.class,
+ "findByAtPathAndCategory", // <1>
+ "atPath", atPath, // <2>
+ "category", category)); // <3>
+ }
+ ...
+ @javax.inject.Inject
+ DomainObjectContainer container;
+}
+----
+<1> corresponds to the "findByAtPathAndCategory" JDO named query
+<2> provide argument for the `atPath` parameter. The pattern is parameter, argument, parameter, argument, ... and so on.
+<3> provide argument for the `category` parameter. The pattern is parameter, argument, parameter, argument, ... and so on.
+
+Other JDOQL named queries (not shown) follow the exact same pattern.
+
+With respect to the other query APIs, the varargs parameters are optional, but allow for (client-side and managed) paging. The first parameter is the `start` (0-based, the second is the `count`.
+
+[TIP]
+====
+It is also possible to query using DataNucleus' type-safe query API. For more details, see xref:rg.adoc#_rg_services-api_manpage-IsisJdoSupport[`IsisJdoSupport`].
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer_messages-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer_messages-api.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer_messages-api.adoc
new file mode 100644
index 0000000..d292365
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer_messages-api.adoc
@@ -0,0 +1,50 @@
+[[_rg_services-api_manpage-DomainObjectContainer_messages-api]]
+= Messages 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/
+
+
+
+The `DomainObjectContainer` allows domain objects to raise information, warning or error messages. These messages can either be simple strings, or can be translated.
+
+[source,java]
+----
+public interface DomainObjectContainer {
+ @Programmatic
+ void informUser(String message); // <1>
+ @Programmatic
+ String informUser(TranslatableString message, Class<?> contextClass, String contextMethod); // <2>
+
+ @Programmatic
+ void warnUser(String message); // <3>
+ @Programmatic
+ String warnUser(TranslatableString message, Class<?> contextClass, String contextMethod); // <4>
+
+ @Programmatic
+ void raiseError(String message); // <5>
+ @Programmatic
+ String raiseError(TranslatableString message, Class<?> contextClass, String contextMethod); // <6>
+ ...
+}
+----
+<1> display as a transient message to the user (not requiring acknowledgement). In the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] this is implemented as a toast that automatically disappears after a period of time.
+<2> ditto, but with translatable string, for xref:ug.adoc#_ug_more-advanced_i18n[i18n support].
+<3> warn the user about a situation with the specified message. In the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] this is implemented as a toast that must be closed by the end-user.
+<4> ditto, but with translatable string, for i18n support.
+<5> show the user an unexpected application error. In the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] this is implemented as a toast (with a different colour) that must be closed by the end-user.
+<6> ditto, but with translatable string, for i18n support.
+
+
+For example:
+
+[source,java]
+----
+public Order addItem(Product product, @ParameterLayout(named="Quantity) int quantity) {
+ if(productRepository.stockLevel(product) == 0) {
+ container.warnUser(
+ product.getDescription() + " out of stock; order fulfillment may be delayed");
+ }
+ ...
+}
+----
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer_object-creation-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer_object-creation-api.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer_object-creation-api.adoc
new file mode 100644
index 0000000..8269b1d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer_object-creation-api.adoc
@@ -0,0 +1,40 @@
+[[_rg_services-api_manpage-DomainObjectContainer_object-creation-api]]
+= Object Creation 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/
+
+
+
+The object creation APIs are used to instantiate new domain objects or view models.
+
+[source,java]
+----
+public interface DomainObjectContainer {
+ @Programmatic
+ <T> T newTransientInstance(final Class<T> ofType); // <1>
+ @Programmatic
+ <T> T newViewModelInstance(final Class<T> ofType, final String memento); // <2>
+ ...
+}
+----
+<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:rg.adoc#_rg_annotations_manpage-ViewModel[`@ViewModel`] and let Isis manage the memento automatically.
+
+For example:
+
+[source,java]
+----
+Customer cust = container.newTransientInstance(Customer.class);
+cust.setFirstName("Freddie");
+cust.setLastName("Mercury");
+container.persist(cust);
+----
+
+As an alternative to using `newTransientInstance(...)`, you could also simply `new()` up the object. Doing this will not inject any domain services, but they can be injected manually using xref:rg.adoc#_rg_services-api_manpage-DomainObjectContainer_services-api[#injectServicesInto(...)`].
+
+[NOTE]
+====
+Calling `new(...)` also this circumvents Isis' xref:rg.adoc#_rg_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 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/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer_object-persistence-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer_object-persistence-api.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer_object-persistence-api.adoc
new file mode 100644
index 0000000..4b3a28d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer_object-persistence-api.adoc
@@ -0,0 +1,62 @@
+[[_rg_services-api_manpage-DomainObjectContainer_object-persistence-api]]
+= Object Persistence 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/
+
+
+
+
+
+The persistence API is used to persist newly created objects (as per xref:rg.adoc#_rg_services-api_manpage-DomainObjectContainer_object-creation-api[`#newTransientInstance(...)`], above and to delete (remove) objects that are persistent.
+
+Note that there is no API for updating existing objects; the framework (or rather, JDO/DataNucleus) performs object dirty tracking and so any objects that are modified in the course of a request will be automatically updated).
+
+
+[source,java]
+----
+public interface DomainObjectContainer {
+ @Programmatic
+ boolean isPersistent(Object domainObject); // <1>
+ @Programmatic
+ boolean isViewModel(Object domainObject); // <2>
+
+ @Programmatic
+ void persist(Object domainObject); // <3>
+ @Programmatic
+ void persistIfNotAlready(Object domainObject); // <4>
+
+ @Programmatic
+ void remove(Object persistentDomainObject); // <5>
+ @Programmatic
+ void removeIfNotAlready(Object domainObject); // <6>
+
+ @Programmatic
+ boolean flush(); // <7>
+ ...
+}
+----
+<1> test whether a particular domain object is persistent or not
+<2> test whether a particular domain object is a view model or not. Note that this includes any domain objects annotated with xref:rg.adoc#_rg_annotations_manpage-DomainObject_nature[`@DomainObject#nature=Nature.EXTERNAL_ENTITY)`] or xref:rg.adoc#_rg_annotations_manpage-DomainObject_nature[`@DomainObject#nature=Nature.INMEMORY_ENTITY`]
+<3> persist a transient object. Note though that this will throw an exception if the object is already persistent; this can happen if JDO/DataNucleus's link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/orm/cascading.html[persistence-by-reachability] is in effect. For this reason it is generally better to use:
+<4> persist an object but only if know to not have been persistent. But if the object is persistent, is a no-op
+<5> remove (ie DELETE) a persistent object. For similar reasons to the persistence, it is generally better to use:
+<6> remove (ie DELETE) an object only if known to be persistent. But if the object has already been deleted, then is a no-op.
+<7> flushes all pending changes to the objectstore. Explained further below.
+
+For example:
+
+[source,java]
+----
+Customer cust = container.newTransientInstance(Customer.class);
+cust.setFirstName("Freddie");
+cust.setLastName("Mercury");
+container.persistIfNotAlready(cust);
+----
+
+You should be aware that by default 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:rg.adoc#_rg_services-api_manpage-DomainObjectContainer_generic-repository-api[above]. However, this behaviour can be disabled using the xref:ug.adoc#_ug_runtime_configuring-core[configuration property] `isis.services.container.disableAutoFlush`.
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer_presentation-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer_presentation-api.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer_presentation-api.adoc
new file mode 100644
index 0000000..d153934
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer_presentation-api.adoc
@@ -0,0 +1,46 @@
+[[_rg_services-api_manpage-DomainObjectContainer_presentation-api]]
+= Presentation 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/
+
+
+
+
+A responsibility of every domain object is to return a title. This can be done declaratively using the xref:rg.adoc#_rg_annotations_manpage-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.
+
+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 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.
+
+Similarly, it often makes sense if xref:rg.adoc#_rg_services-api_manpage-DomainObjectContainer_messages-api[raising messages] to use the title of an object in a message rather (than a some other property of the object), because this is how end-users will be used to identifying the object.
+
+The API defined by `DomainObjectContainer` is simply:
+
+[source,java]
+----
+public interface DomainObjectContainer {
+ @Programmatic
+ String titleOf(Object domainObject); // <1>
+ ...
+}
+----
+<1> return the title of the object, as rendered in the UI by the Isis viewers.
+
+
+By way of example, here's some code from the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] showing the use of the API in an message:
+
+[source,java]
+----
+ public List<ToDoItem> delete() {
+ final String title = container.titleOf(this); // <1>
+ ...
+ container.removeIfNotAlready(this);
+ container.informUser(
+ TranslatableString.tr(
+ "Deleted {title}", "title", title), // <2>
+ this.getClass(), "delete");
+ ...
+ }
+
+----
+<1> the title is obtained first, because we're not allowed to reference object after it's been deleted
+<2> use the title in an i18n `TranslatableString`
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer_properties-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer_properties-api.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer_properties-api.adoc
new file mode 100644
index 0000000..43b95d9
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer_properties-api.adoc
@@ -0,0 +1,54 @@
+[[_rg_services-api_manpage-DomainObjectContainer_properties-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/
+
+
+
+
+
+= Properties API
+
+The properties API allows domain objects to read the configuration properties aggregated from the various xref:ug.adoc#_ug_runtime_configuration-files[configuration files].
+
+[source,java]
+----
+public interface DomainObjectContainer {
+ @Programmatic
+ String getProperty(String name); // <1>
+ @Programmatic
+ String getProperty(String name, String defaultValue); // <2>
+ @Programmatic
+ List<String> getPropertyNames(); // <3>
+}
+----
+<1> Return the configuration property with the specified name; else return null.
+<2> Return the configuration property with the specified name; if it doesn't exist then return the specified default value.
+<3> Return the names of all the available properties.
+
+For example, here's a fictitious service that might wrap link:http://twitter4j.org/en/configuration.html[Twitter4J]. say:
+
+[source,java]
+----
+@DomainService(nature=NatureOfService.DOMAIN)
+public class TweetService {
+ @Programmatic
+ @PostConstruct
+ public void init() {
+ this.oauthConsumerKey = container.getProperty("tweetservice.oauth.consumerKey");
+ this.oauthConsumerSecret = container.getProperty("tweetservice.oauth.consumerSecret");
+ this.oauthAccessToken = container.getProperty("tweetservice.oauth.accessToken");
+ this.oauthAccessTokenSecret = container.getProperty("tweetservice.oauth.accessTokenSecret");
+ }
+ ...
+ @Inject
+ DomainObjectContainer container;
+}
+----
+
+[TIP]
+====
+If you _do_ have a domain service that needs to access properties, then note that an alternative is to define a xref:rg.adoc#_rg_annotations_manpage-PostConstruct[`@PostConstruct`] method and pass in a `Map<String,String>` of properties. The two techniques are almost identical; it's mostly a matter of taste.
+====
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer_security-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer_security-api.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer_security-api.adoc
new file mode 100644
index 0000000..2bfbbc7
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer_security-api.adoc
@@ -0,0 +1,48 @@
+[[_rg_services-api_manpage-DomainObjectContainer_security-api]]
+= Security 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/
+
+
+
+The security API allows the domain object to obtain the identity of the user interacting with said object.
+
+[source,java]
+----
+public interface DomainObjectContainer {
+ @Programmatic
+ UserMemento getUser();
+ ...
+}
+----
+
+where in turn (the essence of) `UserMemento` is:
+
+[source,java]
+----
+public final class UserMemento {
+ public String getName() { ... }
+ public boolean isCurrentUser(final String userName) { ... }
+
+ public List<RoleMemento> getRoles() { ... }
+ public boolean hasRole(final RoleMemento role) { ... }
+ public boolean hasRole(final String roleName) { ... }
+ ...
+}
+----
+
+and `RoleMemento` is simpler still:
+
+[source,java]
+----
+public final class RoleMemento {
+ public String getName() { ... }
+ public String getDescription() { ... }
+ ...
+}
+----
+
+The roles associated with the `UserMemento` will be based on the configured xref:ug.adoc#_ug_security[security] (typically Shiro).
+
+In addition, when using the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] there will be an additional "org.apache.isis.viewer.wicket.roles.USER" role; this is used internally to restrict access to web pages without authenticating.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer_services-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer_services-api.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer_services-api.adoc
new file mode 100644
index 0000000..111d939
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer_services-api.adoc
@@ -0,0 +1,37 @@
+[[_rg_services-api_manpage-DomainObjectContainer_services-api]]
+= Services 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/
+
+
+The services API allows your domain objects to programmatically inject services into arbitrary objects, as well as to look up services by type:
+
+[source,java]
+----
+public interface DomainObjectContainer {
+ @Programmatic
+ <T> T injectServicesInto(final T domainObject); // <1>
+ @Programmatic
+ <T> T lookupService(Class<T> service); // <2>
+ @Programmatic
+ <T> Iterable<T> lookupServices(Class<T> service); // <3>
+ ...
+}
+----
+<1> injects services into domain object; used extensively internally by the framework (eg to inject to other services, or to entities, or integration test instances, or fixture scripts). Service injection is done automatically if objects are created using `#newTransientInstance()`, described xref:rg.adoc#_rg_services-api_manpage-DomainObjectContainer_object-creation-api[above]
+<2> returns the first registered service that implements the specified class
+<3> returns an `Iterable` in order to iterate over all registered services that implement the specified class
+
+The primary use case is to instantiate domain objects using a regular constructor ("new is the new new") rather than using the xref:rg.adoc#_rg_services-api_manpage-DomainObjectContainer_object-creation-api[`#newTransientInstance()`] API, and then using the `#injectServicesInto(...)` API to set up any dependencies.
+
+For example:
+
+[source,java]
+----
+Customer cust = container.injectServicesInto( new Customer());
+cust.setFirstName("Freddie");
+cust.setLastName("Mercury");
+container.persist(cust);
+----
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer_validation-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer_validation-api.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer_validation-api.adoc
new file mode 100644
index 0000000..5cfec93
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer_validation-api.adoc
@@ -0,0 +1,26 @@
+[[_rg_services-api_manpage-DomainObjectContainer_validation-api]]
+= Validation 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/
+
+
+
+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 API provided is:
+
+[source,java]
+----
+public interface DomainObjectContainer {
+ @Programmatic
+ boolean isValid(Object domainObject);
+ @Programmatic
+ String validate(Object domainObject);
+ ...
+}
+----
+
+If an object is changed by editing its properties, then (using the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] at least) 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
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-EmailService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-EmailService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-EmailService.adoc
new file mode 100644
index 0000000..367958d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-EmailService.adoc
@@ -0,0 +1,98 @@
+[[_rg_services-api_manpage-EmailService]]
+= `EmailService`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `EmailService` provides the ability to send HTML emails, with attachments, to one or more recipients.
+
+Apache Isis provides a default implementation to send emails using an external SMTP provider. Note that this must be configured (using a number of configuration properties) before it can be used. The that sends email as an HTML message, using an external SMTP provider.
+
+
+
+== API & Implementation
+
+The API for the service is:
+
+[source,java]
+----
+public interface EmailService {
+ @Programmatic
+ boolean send( // <1>
+ List<String> to, List<String> cc, List<String> bcc, // <2>
+ String subject,
+ String body, // <3>
+ DataSource... attachments);
+ @Programmatic
+ boolean isConfigured(); // <4>
+ }
+----
+<1> is the main API to send the email (and optional attachments). Will return `false` if failed to send
+<2> pass either `null` or `Collections.emptyList()` if not required
+<3> should be HTML text
+<4> indicates whether the implementation was configured and initialized correctly. If this returns `false` then any attempt to call `send(...)` will fail.
+
+As noted in the introduction, the core framework provides a default implementation (`EmailServiceDefault`) that sends email as an HTML message, using an external SMTP provider.
+
+
+
+== Configuration
+
+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:ug.adoc#_ug_runtime_configuring-core[here]):
+
+* `isis.service.email.sender.hostname`
+* `isis.service.email.port`
+* `isis.service.email.tls.enabled`
+
+These configuration properties can be specified either in `isis.properties` or in an xref:ug.adoc#_ug_deployment_externalized-configuration[external configuration file].
+
+If prototyping (that is, running the app using `org.apache.isis.WebServer`), the configuration properties can also be specified as system properties. For example, if you create a test email account on gmail, you can configure the service using:
+
+[source,ini]
+----
+-Disis.service.email.sender.address=xxx@gmail.com -Disis.service.email.sender.password=yyy
+----
+
+where "xxx" is the gmail user account and "yyy" is its password
+
+
+
+
+== Alternative Implementations
+
+If you wish to write an alternative implementation, be aware that it should process the message body as HTML (as opposed to plain text or any other format).
+
+Also, note that (unlike most Isis domain services) the implementation is also instantiated and injected by Google Guice. This is because `EmailService` is used as part of the xref:ug.adoc#_ug_wicket-viewer_features_user-registration[user registration] functionality and is used by Wicket pages that are accessed outside of the usual Isis runtime. This implies a couple of additional constraints:
+
+* first, implementation class should also be annotated with `@com.google.inject.Singleton`
+* second, there may not be any Isis session running. (If necessary, one can be created on the fly using `IsisContext.doInSession(...)`)
+
+To ensure that your alternative implementation takes the place of the default implementation, register it explicitly in `isis.properties`.
+
+
+
+== Registering the Services
+
+Assuming that the `configuration-and-annotation` services installer is configured:
+
+[source,ini]
+----
+isis.services-installer=configuration-and-annotation
+----
+
+then Isis' core implementation of `EmailService` service is automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
+
+If you have written an alternative implementation, then register your implementation in `isis.properties` under the "isis.services" key and it will be used instead.
+
+
+
+== Related Services
+
+The email service is used by the xref:rg.adoc#_rg_services-spi_manpage-EmailNotificationService[`EmailNotificationService`] which is, in turn, used by xref:rg.adoc#_rg_services-spi_manpage-UserRegistrationService[`UserRegistrationService`].
\ No newline at end of file
[13/45] isis git commit: ISIS-1133: breaking out reference guide and
devenv guide;
moving appendices' release notes and migration notes to other docs;
improving the documentation page.
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_hidden.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_hidden.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_hidden.adoc
deleted file mode 100644
index bac70df..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_hidden.adoc
+++ /dev/null
@@ -1,66 +0,0 @@
-[[_ug_reference-annotations_manpage-Property_hidden]]
-= `hidden()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-Properties can be hidden at the domain-level, indicating that they are not visible to the end-user. This attribute can also be applied to xref:_ug_reference-annotations_manpage-ActionLayout_hidden[actions] and xref:_ug_reference-annotations_manpage-CollectionLayout_hidden[collections].
-
-[TIP]
-====
-It is also possible to use xref:_ug_reference-annotations_manpage-Property_hidden[`@Property#hidden()`] to hide an action at the domain 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:
-
-[source,java]
-----
-public class Customer {
- @Property(hidden=Where.EVERYWHERE)
- public int getInternalId() { ... }
- @Property(hidden=Where.ALL_TABLES)
- public void updateStatus() { ... }
- ...
-}
-----
-
-The acceptable values for the `where` parameter are:
-
-* `Where.EVERYWHERE` or `Where.ANYWHERE` +
-+
-The property should be hidden everywhere.
-
-* `Where.ANYWHERE` +
-+
-Synonym for everywhere.
-
-* `Where.OBJECT_FORMS` +
-+
-The property should be hidden when displayed within an object form.
-
-* `Where.PARENTED_TABLES` +
-+
-The property should be hidden when displayed as a column of a table within a parent object's collection.
-
-* `Where.STANDALONE_TABLES` +
-+
-The property should be hidden when displayed as a column of a table showing a standalone list of objects, for example as returned by a repository query.
-
-* `Where.ALL_TABLES` +
-+
-The property should be hidden when displayed as a column of a table, either an object's * collection or a standalone list. This combines `PARENTED_TABLES` and `STANDALONE_TABLES`.
-
-* `Where.NOWHERE` +
-+
-The property should not be hidden, overriding any other metadata/conventions that would normally cause the property to be hidden. +
-
-For example, if a property is annotated with xref:_ug_reference-annotations_manpage-Title[`@Title`], then normally this should be hidden from all
-tables. Annotating with `@Property(where=Where.NOWHERE)` overrides this.
-
-
-[NOTE]
-====
-The xref:_ug_restfulobjects-viewer[RestfulObjects viewer] has only partial support for these `Where` enums.
-====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_maxLength.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_maxLength.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_maxLength.adoc
deleted file mode 100644
index c0fcc3e..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_maxLength.adoc
+++ /dev/null
@@ -1,49 +0,0 @@
-[[_ug_reference-annotations_manpage-Property_maxLength]]
-= `maxLength()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `maxLength()` attribute applies only to `String` properties, indicating the maximum number of characters that the user may enter (for example in a text field in the UI). The attribute It is ignored if applied to properties of any other type. This attribute can also be applied to xref:_ug_reference-annotations_manpage-Parameter_maxLength[parameters].
-
-
-That said, properties are most commonly defined on persistent domain objects (entities), in which case the JDO xref:_ug_reference-annotations_manpage-Column[`@Column`] will in any case need to be specified. Isis can infer the `maxLength` semantic directly from the equivalent `@Column#length()` annotation/attribute.
-
-For example:
-
-[source,java]
-----
-public class Customer {
- @javax.jdo.annotations.Column(length=30)
- public String getFirstName() { ... }
- public void setFirstName(String firstName) { ... }
- ...
-}
-----
-
-In this case there is therefore no need for the `@Property#maxLength()` attribute.
-
-
-
-== Non-persistent properties
-
-Of course, not every property is persistent (it could instead be derived), and neither is every domain object an entity (it could be a view model). For these non persistable properties the `maxLength()` attribute is still required.
-
-For example:
-
-[source,java]
-----
-public class Customer {
- @javax.jdo.annotation.NotPersistent // <1>
- @Property(maxLength=100)
- public String getFullName() { ... } // <2>
- public void setFullName(String fullName) { ... } // <3>
- ...
-}
-----
-<1> a non persisted (derived) property
-<2> implementation would most likely derive full name from constituent parts (eg first name, middle initial, last name)
-<3> implementation would most likely parse the input and update the constituent parts
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_mustSatisfy.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_mustSatisfy.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_mustSatisfy.adoc
deleted file mode 100644
index ca82b3a..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_mustSatisfy.adoc
+++ /dev/null
@@ -1,46 +0,0 @@
-[[_ug_reference-annotations_manpage-Property_mustSatisfy]]
-= `mustSatisfy()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `mustSatisfy()` attribute allows arbitrary validation to be applied to properties using an (implementation of a) `org.apache.isis.applib.spec.Specification` object.
- The attribute is also supported on xref:_ug_reference-annotations_manpage-Parameter_mustSatisfy[parameters].
-
-[TIP]
-====
-The specification implementations can (of course) be reused between properties and xref:_ug_reference-annotations_manpage-Parameter_mustSatisfy[parameters].
-====
-
-The `Specification` is consulted during validation, being passed the proposed value. If the proposed value fails, then the value returned is the used as the invalidity reason.
-
-For example:
-
-[source,java]
-----
-public class StartWithCapitalLetterSpecification
- extends AbstractSpecification<String> { // <1>
- 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 {
- @MustSatisfy(StartWithCapitalLetterSpecification.class)
- public String getFirstName() { ... }
- ...
-}
-----
-<1> the `AbstractSpecification` class conveniently handles type-safety and dealing with null values. The applib also provides `SpecificationAnd` and `SpecificationOr` to allow specifications to be combined "algebraically".
-
-
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_notPersisted.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_notPersisted.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_notPersisted.adoc
deleted file mode 100644
index af7dcc0..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_notPersisted.adoc
+++ /dev/null
@@ -1,61 +0,0 @@
-[[_ug_reference-annotations_manpage-Property_notPersisted]]
-= `notPersisted()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 (somewhat misnamed) `notPersisted()` attribute indicates that the collection should be excluded from any snapshots generated by the xref:_ug_reference-services-api_manpage-XmlSnapshotService[`XmlSnapshotService`]. This attribute is also supported for xref:_ug_reference-annotations_manpage-Collection_notPersisted[collections].
-
-
-[WARNING]
-====
-This annotation does _not_ specify that a property is not persisted in the JDO/DataNucleus objectstore. See below for details as to how to additionally annotate the property for this.
-====
-
-
-For example:
-
-[source,java]
-----
-public class Order {
- @Property(notPersisted=true)
- public Order getPreviousOrder() {...}
- public void setPreviousOrder(Order previousOrder) {...}
- ...
-}
-----
-
-Historically this annotation also hinted as to whether the property's value contents should be persisted in the object store. However, the JDO/DataNucleus objectstore does not recognize this annotation. Thus, to ensure that a property is actually not persisted, it should *also* be annotated with `@javax.jdo.annotations.NotPersistent`.
-
-For example:
-
-[source,java]
-----
-public class Order {
- @Property(notPersisted=true) // <1>
- @javax.jdo.annotations.NotPersistent // <2>
- public Order getPreviousOrder() {...}
- public void setPreviousOrder(Order previousOrder) {...}
- ...
-}
-----
-<1> ignored by Isis
-<2> ignored by JDO/DataNucleus
-
-
-
-
-
-Alternatively, if the property is derived, then providing only a "getter" will also work:
-
-[source,java]
-----
-public class Order {
- public Order getPreviousOrder() {...}
- ...
-}
-----
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_optionality.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_optionality.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_optionality.adoc
deleted file mode 100644
index fec4556..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_optionality.adoc
+++ /dev/null
@@ -1,129 +0,0 @@
-[[_ug_reference-annotations_manpage-Property_optionality]]
-= `optionality()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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, Apache Isis assumes that all properties of an domain object or view model are required (mandatory). The `optionality()` attribute allows this to be relaxed. The attribute is also supported for xref:_ug_reference-annotations_manpage-Parameter_optionality[parameters].
-
-That said, properties are most commonly defined on persistent domain objects (entities), in which case the JDO xref:_ug_reference-annotations_manpage-Column[`@Column`] should be specified. Isis can infer the maxLength directly from the equivalent @Column#length() annotation.
-
-That said, properties are most commonly defined on persistent domain objects (entities), in which case the JDO xref:_ug_reference-annotations_manpage-Column[`@Column`] will in any case need to be specified. Isis can infer the `optionality` semantic directly from the equivalent `@Column#allowNulls()` annotation/attribute.
-
-For example:
-
-[source,java]
-----
-public class Customer {
- @javax.jdo.annotations.Column(allowNulls="true")
- public String getMiddleInitial() { ... }
- public void setMiddleInitial(String middleInitial) { ... }
- ...
-}
-----
-
-In this case there is no need for the `@Property#optionality()` attribute.
-
-
-== Mismatched defaults
-
-If the `@Column#allowNulls()` attribute is omitted and the `@Property#optionality() attribute is also omitted, then note that Isis' defaults and JDO's defaults differ. Specifically, Isis always assumes properties are mandatory, whereas JDO specifies that primitives are mandatory, but all reference types are optional.
-
-When Isis initializes it checks for these mismatches during its metamodel validation phase, and will fail to boot ("fail-fast") if there is a mismatch. The fix is usually to add the `@Column#allowsNulls()` annotation/attribute.
-
-
-== Superclass inheritance type
-
-There is one case (at least) it may be necessary to annotate the property with both `@Column#allowsNull` and also `@Property#optionality()`. If the property is logically mandatory and is in a subclass, but the mapping of the class hierarchy is to store both the superclass and subclass(es) into a single table (ie a "roll-up" mapping using `javax.jdo.annotations.InheritanceStrategy#SUPERCLASS_TABLE`), then JDO requires that the property is annotated as `@Column#allowsNull="true"`: its value will be not defined for other subclasses.
-
-In this case we therefore require both annotations.
-
-[source,java]
-----
-@javax.jdo.annotations.PersistenceCapable
-@javax.jdo.annotations.Inheritance(strategy = InheritanceStrategy.NEW_TABLE)
-public abstract class PaymentMethod {
- ...
-}
-@javax.jdo.annotations.PersistenceCapable
-@javax.jdo.annotations.Inheritance(strategy = InheritanceStrategy.SUPERCLASS_TABLE)
-public class CreditCardPaymentMethod extends PaymentMethod {
- private String cardNumber;
- @javax.jdo.annotations.Column(allowNulls="true")
- @Property(optionality=Optionality.MANDATORY)
- public String getCardNumber() { return this.cardNumber; }
- public void setCardNumber(String cardNumber) { this.cardNumber = cardNumber; }
- ...
-}
-----
-
-Alternatively, you could rely on the fact that Isis never looks at fields (whereas JDO does) and move the JDO annotation to the field:
-
-[source,java]
-----
-@javax.jdo.annotations.PersistenceCapable
-@javax.jdo.annotations.Inheritance(strategy = InheritanceStrategy.SUPERCLASS_TABLE)
-public class CreditCardPaymentMethod extends PaymentMethod {
- @javax.jdo.annotations.Column(allowNulls="true")
- private String cardNumber;
- public String getCardNumber() { return this.cardNumber; }
- public void setCardNumber(String cardNumber) { this.cardNumber = cardNumber; }
- ...
-}
-----
-
-However this at first glance this might be read as eing that the property is optional whereas Isis' default (required) applies. Also, in the future Isis may be extended to support reading annotations from fields.
-
-
-
-== Non-persistent properties
-
-Of course, not every property is persistent (it could instead be derived), and neither is every domain object an entity (it could be a view model). For these non persistable properties the `optionality()` attribute is still required.
-
-For example:
-
-[source,java]
-----
-public class Customer {
- @javax.jdo.annotation.NotPersistent // <1>
- @Property(optionality=Optionality.OPTIONAL)
- public String getFullName() { ... } // <2>
- public void setFullName(String fullName) { ... } // <3>
- ...
-}
-----
-<1> a non persisted (derived) property
-<2> implementation would most likely derive full name from constituent parts (eg first name, middle initial, last name)
-<3> implementation would most likely parse the input and update the constituent parts
-
-
-[TIP]
-====
-The attribute has no meaning for a primitive type such as `int`: primitives will always have a default value (e.g. zero). If optionality is required, then use the corresponding wrapper class (e.g. `java.lang.Integer`) and annotate with `Parameter#optionality()` as required.
-====
-
-The values for the attribute are simply `OPTIONAL` or `MANDATORY`.
-
-For example:
-
-[source,java]
-----
-public class Customer {
- public Order placeOrder(
- final Product product,
- @ParameterLayout(named = "Quantity")
- final int quantity,
- @Parameter(optionality = Optionality.OPTIONAL)
- @ParameterLayout(named = "Special Instructions")
- final String instr) {
- ...
- }
- ...
-}
-----
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_regexPattern.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_regexPattern.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_regexPattern.adoc
deleted file mode 100644
index 73e4135..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_regexPattern.adoc
+++ /dev/null
@@ -1,28 +0,0 @@
-[[_ug_reference-annotations_manpage-Property_regexPattern]]
-= `regexPattern()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `regexPattern()` attribute validates the contents of any string property with respect to a regular expression pattern. It is ignored if applied to properties of any other type. This attribute can also be specified for xref:_ug_reference-annotations_manpage-Parameter_regexPattern[parameters].
-
-For example:
-
-[source,java]
-----
-public class Customer {
- @Property(
- regexPattern = "(\\w+\\.)*\\w+@(\\w+\\.)+[A-Za-z]+",
- regexPatternFlags=Pattern.CASE_INSENSITIVE
- )
- public String getEmail() { ... }
-}
-----
-
-
-
-The related `regexPatternFlags()` attribute specifies flags that modify the handling of the pattern. The values are those that would normally be passed to `java.util.regex.Pattern#compile(String,int)`.
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-RequestScoped.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-RequestScoped.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-RequestScoped.adoc
deleted file mode 100644
index b6b8312..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-RequestScoped.adoc
+++ /dev/null
@@ -1,50 +0,0 @@
-[[_ug_reference-annotations_manpage-RequestScoped]]
-= `@RequestScoped` (`javax`)
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@javax.enterprise.context.RequestScoped` link:https://jcp.org/en/jsr/detail?id=299[JSR-299] CDI annotation is used to specify that a xref:_ug_reference-annotations_manpage-DomainService[domain service] should be request-scoped rather than a singleton.
-
-Although Isis does not (currently) leverage CDI, the semantics are the same as request-scoped service; a new instance is created for each HTTP request, reserved for the exclusive use of all objects interacted with during that request.
-
-One of the built-in domain services that uses this annotation is xref:_ug_reference-services-api_manpage-Scratchpad[`Scratchpad`], intended to allow the arbitrary sharing of data between objects. Here is the full source code of this service is:
-
-
-[source,java]
-----
-@DomainService(
- nature = NatureOfService.DOMAIN
-)
-@RequestScoped
-public class Scratchpad {
- private final Map<Object, Object> userData = Maps.newHashMap(); // <1>
- @Programmatic
- public Object get(Object key) {
- return userData.get(key); // <2>
- }
- @Programmatic
- public void put(Object key, Object value) {
- userData.put(key, value); // <3>
- }
- @Programmatic
- public void clear() {
- userData.clear(); // <4>
- }
-}
-----
-<1> Provides a mechanism for each object being acted upon to pass data to the next object.
-<2> Obtain user-data, as set by a previous object being acted upon.
-<3> Set user-data, for the use of a subsequent object being acted upon.
-<4> Clear any user data.
-
-
-The vast majority of domain services in Isis tend to be singletons (which requires no special annotation); but as you can see setting up request-scoped services is very straightforward.
-
-[NOTE]
-====
-Behind the covers Isis creates a (singleton) wrapper for the domain service; the individual request-scoped instances are held in a thread-local of this wrapper. One consequence of this implementation is that request-scoped methods should not be marked as `final`.
-====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Title.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Title.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Title.adoc
deleted file mode 100644
index d0d4f3d..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Title.adoc
+++ /dev/null
@@ -1,38 +0,0 @@
-[[_ug_reference-annotations_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/
-
-
-The `@Title` annotation is used to indicate which property or properties make up the object title. If more than one property is used, the order can be specified (using the same Dewey-decimal notation as used by `@MemberOrder`) and the string to use between the components can also be specified.
-
-For example:
-
-[source,java]
-----
-public void Customer {
- @Title(sequence="1.0")
- public String lastName() { ... }
- ...
- @Title(sequence="1.5", prepend=", ")
- public String firstName() { ... }
- ...
- @Title(sequence="1.7", append=".")
- public String midInitial() { ... }
- ...
-}
-----
-
-could be used to create names of the style "Bloggs, Joe K."
-
-It is also possible to annotate reference properties; in this case the
-title will return the title of the referenced object (rather than, say,
-its string representation).
-
-An additional convention for `@Title` properties is that they are hidden
-in tables (in other words, it implies `@Hidden(where=Where.ALL_TABLES)`.
-For viewers that support this annotation (for example, the Wicket
-viewer), this convention excludes any properties whose value is already
-present in the title column. This convention can be overridden using
-`@Hidden(where=Where.NOWHERE)`.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ViewModel.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ViewModel.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ViewModel.adoc
deleted file mode 100644
index 9784f55..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ViewModel.adoc
+++ /dev/null
@@ -1,44 +0,0 @@
-[[_ug_reference-annotations_manpage-ViewModel]]
-= `@ViewModel`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@ViewModel` annotation, applied to a class, is the simplest way to indicate that the class is a view model.
-
-View models are not persisted to the database, instead their state is encoded within their identity (ultimately
-represented in the URL). As such, view models are immutable.
-
-For example:
-
-[source,java]
-----
-@ViewModel
-public class MyViewModel {
- public MyViewModel() {} // <1>
- ...
-}
-----
-<1> must have a no-arg constructor for subsequent "recreation" by the framework.
-
-
-To instantiate a view model, you can either instantiate directly using its constructor, or indirectly using `DomainObjectContainer#newTransientInstance()`. If you use the former, also programmatically call `DomainObjectContainer#injectServicesInto(...)` to ensure that any dependencies are injected into the service.
-
-
-[TIP]
-====
-Note that there is a `DomainObjectContainer#newViewModelInstance(.)`; this is for view models that implement `ViewModel` interface and can be safely ignored.
-====
-
-
-The view model's memento will be derived from the value of the view model object's properties. Any xref:_ug_reference-annotations_manpage-Property_notPersisted[`@Property#notPersisted()`] properties will be excluded from the memento, as will any http://isis.apache.org/reference/recognized-annotations/Programmatic.html[@Programmatic] properties. Properties that are merely http://isis.apache.org/reference/recognized-annotations/Hidden-deprecated.html[@Hidden] are included in the memento.
-
-Only properties supported by the configured xref:_ug_reference-services-api_manpage-MementoService[`MementoService`] can be used. The default implementation supports all the value types and persisted entities.
-
-(As of 1.8.0) there are some limitations:
-* view models cannot hold collections other view models (simple properties _are_ supported, though)
-* collections (of either view models or entities) are ignored.
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ViewModelLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ViewModelLayout.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ViewModelLayout.adoc
deleted file mode 100644
index da35e81..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ViewModelLayout.adoc
+++ /dev/null
@@ -1,102 +0,0 @@
-[[_ug_reference-annotations_manpage-ViewModelLayout]]
-= `@ViewModelLayout`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@ViewModelLayout` annotation is identical to the xref:_ug_reference-annotations_manpage-DomainObjectLayout[`@DomainObjectLayout`], but is provided
-for symmetry with domain objects that have been annotated using xref:_ug_reference-annotations_manpage-ViewModel[`@ViewModel`] (rather than xref:_ug_reference-annotations_manpage-DomainObject_nature[`@DomainObject(nature=VIEW_MODEL)`]).
-
-
-The table below summarizes the annotation's attributes.
-
-.`@ViewModel` attributes
-[cols="2,2,4a", options="header"]
-|===
-
-| Attribute
-| Values (default)
-| Description
-
-
-|xref:_ug_reference-annotations_manpage-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:_ug_runtime_application-specific_application-css[`application.css`]
-
-
-|xref:_ug_reference-annotations_manpage-ViewModelLayout_cssClassFa[`cssClassFa()`]
-|Any valid link:http://fortawesome.github.io/Font-Awesome/[Font awesome] icon name
-|specify a font awesome icon for the action's menu link or icon. +
-
-
-|`cssClassFaPosition()`
-|`LEFT`, `RIGHT` +
-(`LEFT`)
-|Currently unused.
-
-
-|xref:_ug_reference-annotations_manpage-ViewModelLayout_describedAs[`describedAs()`]
-|String.
-|description of this class, eg to be rendered in a tooltip.
-
-
-
-|xref:_ug_reference-annotations_manpage-ViewModelLayout_named[`named()`]
-|String.
-|to override the name inferred from the action's name in code. +
-
-A typical use case is if the desired name is a reserved Java keyword, such as `default` or `package`.
-
-
-|xref:_ug_reference-annotations_manpage-ViewModelLayout_paged[`paged()`]
-|Positive integer
-|the page size for instances of this class when rendered within a table (as returned from an action invocation)
-
-
-|xref:_ug_reference-annotations_manpage-ViewModelLayout_plural[`plural()`]
-|String.
-|the plural name of the class
-
-
-|===
-
-
-
-
-
-For example:
-
-[source,java]
-----
-@ViewModel // <1>
-@ViewModelLayout(
- cssClass="x-analysis",
- cssClassFa="fa-piechart",
- describedAs="Analysis of todo items by category"
-)
-public class CategoryPieChart { ... }
-----
-<1> this annotation is intended for use with `@ViewModel`. If a view model has been specified using the equivalent xref:_ug_reference-annotations_manpage-DomainObject_nature[`@DomainObject(nature=Nature.VIEW_MODEL)`], then we recommend you use xref:_ug_reference-annotations_manpage-DomainObjectLayout[`@DomainObjectLayout`] instead.
-
-
-[NOTE]
-====
-Note that there is (currently) no support for specifying UI hints for view models through the dynamic xref:_ug_reference-object-layout_dynamic[`.layout.json`] file (only for properties, collections and actions are supported).
-====
-
-
-
-include::_ug_reference-annotations_manpage-ViewModelLayout_cssClass.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-ViewModelLayout_cssClassFa.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-ViewModelLayout_describedAs.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-ViewModelLayout_named.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-ViewModelLayout_paged.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-ViewModelLayout_plural.adoc[leveloffset=+1]
-
-
-
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ViewModelLayout_cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ViewModelLayout_cssClass.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ViewModelLayout_cssClass.adoc
deleted file mode 100644
index 7d06e1b..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ViewModelLayout_cssClass.adoc
+++ /dev/null
@@ -1,30 +0,0 @@
-[[_ug_reference-annotations_manpage-ViewModelLayout_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()` attribute can be used to render additional CSS classes in the HTML (a wrapping `<div>`) that represents the view model. xref:_ug_runtime_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:_ug_reference-annotations_manpage-DomainObjectLayout_cssClass[domain objects], xref:_ug_reference-annotations_manpage-ActionLayout_cssClass[actions] xref:_ug_reference-annotations_manpage-PropertyLayout_cssClass[properties], xref:_ug_reference-annotations_manpage-CollectionLayout_cssClass[collections] and xref:_ug_reference-annotations_manpage-ParameterLayout_cssClass[parameters].
-
-
-For example:
-
-[source,java]
-----
-@ViewModel
-@ViewModelLayout(cssClass="x-analysis")
-public class CategoryPieChart { ... }
-----
-
-
-
-
-[NOTE]
-====
-The similar xref:_ug_reference-annotations_manpage-ViewModelLayout_cssClassFa[`@ViewModelLayout#cssClassFa()`] annotation attribute is also used as a hint to apply CSS, but in particular to allow http://fortawesome.github.io/Font-Awesome/icons/[Font Awesome icons] to be rendered as the icon for classes.
-====
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ViewModelLayout_cssClassFa.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ViewModelLayout_cssClassFa.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ViewModelLayout_cssClassFa.adoc
deleted file mode 100644
index e35f79d..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ViewModelLayout_cssClassFa.adoc
+++ /dev/null
@@ -1,41 +0,0 @@
-[[_ug_reference-annotations_manpage-ViewModelLayout_cssClassFa]]
-= `cssClassFa()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `cssClassFa()` attribute is used to specify the name of a link:http://fortawesome.github.io/Font-Awesome/icons/[Font Awesome icon] name, to be rendered as the domain object's icon.
-
-These attribute can also be applied to xref:_ug_reference-annotations_manpage-DomainObjectLayout_cssClassFa[domain objects] to specify the object's icon, and to xref:_ug_reference-annotations_manpage-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:_ug_reference-methods_reserved_manpage-iconName[`iconName()`] method.
-
-
-
-
-For example:
-
-[source,java]
-----
-@ViewModel
-@ViewModelLayout(
- cssClassFa="fa-piechart"
-)
-public class CategoryPieChart { ... }
-----
-
-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.
-
-
-The related `cssClassFaPosition()` attribute is currently unused for domain objects; the icon is always rendered to the left.
-
-
-[NOTE]
-====
-The similar xref:_ug_reference-annotations_manpage-ViewModelLayout_cssClass[`@ViewModelLayout#cssClass()`] annotation attribute is also used as a hint to apply CSS, but for wrapping the representation of an object or object member so that it can be styled in an application-specific way.
-====
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ViewModelLayout_describedAs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ViewModelLayout_describedAs.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ViewModelLayout_describedAs.adoc
deleted file mode 100644
index 5842fb1..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ViewModelLayout_describedAs.adoc
+++ /dev/null
@@ -1,23 +0,0 @@
-[[_ug_reference-annotations_manpage-ViewModelLayout_describedAs]]
-= `describedAs()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `describedAs()` attribute is used to provide a short description of the view model to the user. In the xref:_ug_wicket-viewer[Wicket viewer] it is displayed as a 'tool tip'. The `describedAs()` attribute can also be specified for xref:_ug_reference-annotations_manpage-CollectionLayout_describedAs[collections], xref:_ug_reference-annotations_manpage-PropertyLayout_describedAs[properties], xref:_ug_reference-annotations_manpage-ActionLayout_describedAs[actions], xref:_ug_reference-annotations_manpage-ParameterLayout_describedAs[parameters] and xref:_ug_reference-annotations_manpage-DomainObjectLayout_describedAs[domain objects].
-
-For example:
-
-[source,java]
-----
-@ViewModel
-@ViewModelLayout(
- cssClass="x-analysis",
- cssClassFa="fa-piechart",
- describedAs="Analysis of todo items by category"
-)
-public class CategoryPieChart { ... }
-----
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ViewModelLayout_named.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ViewModelLayout_named.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ViewModelLayout_named.adoc
deleted file mode 100644
index e8de94f..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ViewModelLayout_named.adoc
+++ /dev/null
@@ -1,35 +0,0 @@
-[[_ug_reference-annotations_manpage-ViewModelLayout_named]]
-= `named()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `named()` attribute explicitly specifies the view model's name, overriding the name that would normally be inferred from the Java source code. This attribute can also be specified for xref:_ug_reference-annotations_manpage-ActionLayout_named[actions], xref:_ug_reference-annotations_manpage-CollectionLayout_named[collections], xref:_ug_reference-annotations_manpage-PropertyLayout_named[properties], xref:_ug_reference-annotations_manpage-ParameterLayout_named[parameters], xref:_ug_reference-annotations_manpage-DomainObjectLayout_named[domain objects] and xref:_ug_reference-annotations_manpage-DomainServiceLayout_named[domain services].
-
-[TIP]
-====
-Following the link:http://en.wikipedia.org/wiki/Don%27t_repeat_yourself[don't repeat yourself] principle, we recommend that you only use this attribute when the desired name cannot be used in Java source code. Examples of that include a name that would be a reserved Java keyword (eg "package"), or a name that has punctuation, eg apostrophes.
-====
-
-
-
-For example:
-
-[source,java]
-----
-@ViewModel
-@ViewModelLayout(
- named="PieChartAnalysis"
-)
-public class PieChartAnalysisViewModel {
- ...
-}
-----
-
-
-
-[TIP]
-====
-The framework also provides a separate, powerful mechanism for xref:_ug_more-advanced_i18n[internationalization].
-====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ViewModelLayout_paged.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ViewModelLayout_paged.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ViewModelLayout_paged.adoc
deleted file mode 100644
index 6d83fab..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ViewModelLayout_paged.adoc
+++ /dev/null
@@ -1,34 +0,0 @@
-[[_ug_reference-annotations_manpage-ViewModelLayout_paged]]
-= `paged()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `paged()` attribute specifies the number of rows to display in a standalone collection, as returned from an action invocation. This attribute can also be applied to xref:_ug_reference-annotations_manpage-CollectionLayout_paged[collections] and xref:_ug_reference-annotations_manpage-DomainObjectLayout_paged[domain objects].
-
-
-
-[WARNING]
-====
-The xref:_ug_restfulobjects-viewer[RestfulObjects viewer] currently does not support paging. The xref:_ug_wicket-viewer[Wicket viewer] _does_ support paging, but note that the paging is performed client-side rather than server-side.
-
-We therefore recommend that large collections should instead be modelled as actions (to allow filtering to be applied to limit the number of rows).
-====
-
-
-For example:
-
-[source,java]
-----
-@ViewModel
-@ViewModelLayout(paged=15)
-public class OrderAnalysis {
- ...
-}
-----
-
-
-It is also possible to specify a global default for the page size of standalone collections, using the xref:_ug_runtime_configuring-core[configuration property] `isis.viewer.paged.standalone`.
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ViewModelLayout_plural.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ViewModelLayout_plural.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ViewModelLayout_plural.adoc
deleted file mode 100644
index 4f34fe3..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ViewModelLayout_plural.adoc
+++ /dev/null
@@ -1,24 +0,0 @@
-[[_ug_reference-annotations_manpage-ViewModelLayout_plural]]
-= `plural()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 Apache Isis displays a standalone collection of several objects, it will label the collection using the plural form of the object type.
-
-By default the plural name will be derived from the end of the singular name, with support for some basic English language defaults (eg using "ies" for names ending with a "y").
-
-The `plural()` attribute allows the plural form of the class name to be specified explicitly. This attribute is also supported for xref:_ug_reference-annotations_manpage-DomainObjectLayout_plural[domain objects].
-
-For example:
-
-[source,java]
-----
-@ViewModel
-@ViewModelLayout(plural="Children")
-public class Child {
- ...
-}
-----
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes.adoc
deleted file mode 100644
index e775287..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes.adoc
+++ /dev/null
@@ -1,14 +0,0 @@
-[[_ug_reference-classes]]
-= Reference: 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/
-
-IMPORTANT: TODO
-
-
-include::_ug_reference-classes_super.adoc[leveloffset=+1]
-include::_ug_reference-classes_value-types.adoc[leveloffset=+1]
-include::_ug_reference-classes_utility.adoc[leveloffset=+1]
-include::_ug_reference-classes_mixins.adoc[leveloffset=+1]
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_mixins.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_mixins.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_mixins.adoc
deleted file mode 100644
index 3e56792..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_mixins.adoc
+++ /dev/null
@@ -1,56 +0,0 @@
-[[_ug_reference-classes_mixins]]
-= Mixins
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 like "mix-ins"; they allow domain services to contribute actions/properties/collections to any domain objects that implement these interfaces.
-
-
-
-== `HasTransactionId`
-
-The `HasTransactionId` interface is a mix-in for any domain objects that pertain
-
-[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`)
-
-
-== `HasUsername`
-
-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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_mixins_manpage-HasTransactionId.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_mixins_manpage-HasTransactionId.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_mixins_manpage-HasTransactionId.adoc
deleted file mode 100644
index 4f4a583..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_mixins_manpage-HasTransactionId.adoc
+++ /dev/null
@@ -1,9 +0,0 @@
-[[_ug_reference-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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_mixins_manpage-HasUserName.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_mixins_manpage-HasUserName.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_mixins_manpage-HasUserName.adoc
deleted file mode 100644
index ad46e11..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_mixins_manpage-HasUserName.adoc
+++ /dev/null
@@ -1,9 +0,0 @@
-[[_ug_reference-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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_super.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_super.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_super.adoc
deleted file mode 100644
index 0dcffd5..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_super.adoc
+++ /dev/null
@@ -1,136 +0,0 @@
-[[_ug_reference-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/
-
-IMPORTANT: TODO
-
-
-The table below summarizes all the convenience superclasses defined by Apache Isis.
-
-.Convenience Superclasses
-[cols="2,4a,1,1", options="header"]
-|===
-
-|API
-|Maven Module +
-Impl'n (g: a:)
-|Implementation
-|Notes
-
-
-|xref:_ug_reference-classes_super_manpage-AbstractContainedObject[`o.a.i.applib.` +
-`AbstractContainedObject`]
-|``o.a.i.core`` +
-``isis-core-applib``
-|(abstract class)
-|
-
-
-|xref:_ug_reference-classes_super_manpage-AbstractDomainEvent[`o.a.i.applib.` +
-`AbstractDomainEvent`]
-|``o.a.i.core`` +
-``services.eventbus`` +
-``isis-core-applib``
-|(abstract class)
-|
-
-
-|xref:_ug_reference-classes_super_manpage-AbstractDomainObject[`o.a.i.applib.` +
-`AbstractDomainObject`]
-|``o.a.i.core`` +
-``isis-core-applib``
-|(abstract class)
-|
-
-
-|xref:_ug_reference-classes_super_manpage-AbstractFactoryAndRepository[`o.a.i.applib.` +
-`AbstractFactoryAndRepository`]
-|``o.a.i.core`` +
-``isis-core-applib``
-|(abstract class)
-|
-
-
-|xref:_ug_reference-classes_super_manpage-AbstractService[`o.a.i.applib.` +
-`AbstractService`]
-|``o.a.i.core`` +
-``isis-core-applib``
-|(abstract class)
-|
-
-
-|xref:_ug_reference-classes_super_manpage-AbstractViewModel[`o.a.i.applib.` +
-`AbstractViewModel`]
-|``o.a.i.core`` +
-``isis-core-applib``
-|(abstract class)
-|
-
-
-|xref:_ug_reference-classes_super_manpage-ActionDomainEvent[`o.a.i.applib.` +
-`ActionDomainEvent`]
-|``o.a.i.core`` +
-``services.eventbus`` +
-``isis-core-applib``
-|(abstract class)
-|
-
-
-|xref:_ug_reference-classes_super_manpage-CollectionDomainEvent[`o.a.i.applib.` +
-`CollectionDomainEvent`]
-|``o.a.i.core`` +
-``services.eventbus`` +
-``isis-core-applib``
-|(abstract class)
-|
-
-
-|xref:_ug_reference-classes_super_manpage-FixtureScript[`o.a.i.applib.` +
-`fixturescript` +
-`FixtureScript`]
-|``o.a.i.core`` +
-``isis-core-applib``
-|(abstract class)
-|
-
-
-|xref:_ug_reference-classes_super_manpage-FixtureScripts[`o.a.i.applib.` +
-`fixturescripts` +
-`FixtureScripts`]
-|``o.a.i.core`` +
-``isis-core-applib``
-|(abstract class)
-|depends on: +
-`ClassDiscoveryService`
-
-
-|xref:_ug_reference-classes_super_manpage-PropertyDomainEvent[`o.a.i.applib.` +
-`PropertyDomainEvent`]
-|``o.a.i.core`` +
-``services.eventbus`` +
-``isis-core-applib``
-|(abstract class)
-|
-
-
-
-|===
-
-
-
-
-include::_ug_reference-classes_super_manpage-AbstractContainedObject.adoc[leveloffset=+1]
-include::_ug_reference-classes_super_manpage-AbstractDomainEvent.adoc[leveloffset=+1]
-include::_ug_reference-classes_super_manpage-AbstractDomainObject.adoc[leveloffset=+1]
-include::_ug_reference-classes_super_manpage-AbstractFactoryAndRepository.adoc[leveloffset=+1]
-include::_ug_reference-classes_super_manpage-AbstractService.adoc[leveloffset=+1]
-include::_ug_reference-classes_super_manpage-AbstractViewModel.adoc[leveloffset=+1]
-include::_ug_reference-classes_super_manpage-ActionDomainEvent.adoc[leveloffset=+1]
-include::_ug_reference-classes_super_manpage-CollectionDomainEvent.adoc[leveloffset=+1]
-include::_ug_reference-classes_super_manpage-FixtureScript.adoc[leveloffset=+1]
-include::_ug_reference-classes_super_manpage-FixtureScripts.adoc[leveloffset=+1]
-include::_ug_reference-classes_super_manpage-PropertyDomainEvent.adoc[leveloffset=+1]
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_super_manpage-AbstractContainedObject.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_super_manpage-AbstractContainedObject.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_super_manpage-AbstractContainedObject.adoc
deleted file mode 100644
index 0a60f5e..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_super_manpage-AbstractContainedObject.adoc
+++ /dev/null
@@ -1,9 +0,0 @@
-[[_ug_reference-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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_super_manpage-AbstractDomainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_super_manpage-AbstractDomainEvent.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_super_manpage-AbstractDomainEvent.adoc
deleted file mode 100644
index 90ec8fc..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_super_manpage-AbstractDomainEvent.adoc
+++ /dev/null
@@ -1,9 +0,0 @@
-[[_ug_reference-classes_super_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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_super_manpage-AbstractDomainObject.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_super_manpage-AbstractDomainObject.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_super_manpage-AbstractDomainObject.adoc
deleted file mode 100644
index feab1ea..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_super_manpage-AbstractDomainObject.adoc
+++ /dev/null
@@ -1,9 +0,0 @@
-[[_ug_reference-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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_super_manpage-AbstractDomainService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_super_manpage-AbstractDomainService.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_super_manpage-AbstractDomainService.adoc
deleted file mode 100644
index e3947a7..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_super_manpage-AbstractDomainService.adoc
+++ /dev/null
@@ -1,9 +0,0 @@
-[[_ug_reference-classes_super_manpage-AbstractDomainService]]
-= `AbstractDomainService`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_super_manpage-AbstractFactoryAndRepository.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_super_manpage-AbstractFactoryAndRepository.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_super_manpage-AbstractFactoryAndRepository.adoc
deleted file mode 100644
index a098dd9..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_super_manpage-AbstractFactoryAndRepository.adoc
+++ /dev/null
@@ -1,9 +0,0 @@
-[[_ug_reference-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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_super_manpage-AbstractService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_super_manpage-AbstractService.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_super_manpage-AbstractService.adoc
deleted file mode 100644
index aa64cba..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_super_manpage-AbstractService.adoc
+++ /dev/null
@@ -1,9 +0,0 @@
-[[_ug_reference-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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_super_manpage-AbstractViewModel.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_super_manpage-AbstractViewModel.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_super_manpage-AbstractViewModel.adoc
deleted file mode 100644
index 7c6c831..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_super_manpage-AbstractViewModel.adoc
+++ /dev/null
@@ -1,9 +0,0 @@
-[[_ug_reference-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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_super_manpage-ActionDomainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_super_manpage-ActionDomainEvent.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_super_manpage-ActionDomainEvent.adoc
deleted file mode 100644
index 8894df1..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_super_manpage-ActionDomainEvent.adoc
+++ /dev/null
@@ -1,9 +0,0 @@
-[[_ug_reference-classes_super_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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_super_manpage-CollectionDomainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_super_manpage-CollectionDomainEvent.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_super_manpage-CollectionDomainEvent.adoc
deleted file mode 100644
index 1f4e686..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_super_manpage-CollectionDomainEvent.adoc
+++ /dev/null
@@ -1,9 +0,0 @@
-[[_ug_reference-classes_super_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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_super_manpage-FixtureScript.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_super_manpage-FixtureScript.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_super_manpage-FixtureScript.adoc
deleted file mode 100644
index ca1243f..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_super_manpage-FixtureScript.adoc
+++ /dev/null
@@ -1,9 +0,0 @@
-[[_ug_reference-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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_super_manpage-FixtureScripts.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_super_manpage-FixtureScripts.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_super_manpage-FixtureScripts.adoc
deleted file mode 100644
index 769a866..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_super_manpage-FixtureScripts.adoc
+++ /dev/null
@@ -1,9 +0,0 @@
-[[_ug_reference-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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_super_manpage-PropertyDomainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_super_manpage-PropertyDomainEvent.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_super_manpage-PropertyDomainEvent.adoc
deleted file mode 100644
index 34de0b6..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_super_manpage-PropertyDomainEvent.adoc
+++ /dev/null
@@ -1,9 +0,0 @@
-[[_ug_reference-classes_super_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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_utility.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_utility.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_utility.adoc
deleted file mode 100644
index cae46ec..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_utility.adoc
+++ /dev/null
@@ -1,15 +0,0 @@
-[[_ug_reference-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::_ug_reference-classes_utility_manpage-Enums.adoc[leveloffset=+1]
-include::_ug_reference-classes_utility_manpage-ObjectContracts.adoc[leveloffset=+1]
-include::_ug_reference-classes_utility_manpage-Reasons.adoc[leveloffset=+1]
-include::_ug_reference-classes_utility_manpage-TitleBuffer.adoc[leveloffset=+1]
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_utility_manpage-Enums.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_utility_manpage-Enums.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_utility_manpage-Enums.adoc
deleted file mode 100644
index 1fb16f3..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_utility_manpage-Enums.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-[[_ug_reference-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/
-
-
-IMPORTANT: TODO
[26/45] isis git commit: ISIS-1133: breaking out reference guide and
devenv guide;
moving appendices' release notes and migration notes to other docs;
improving the documentation page.
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_tutorials_stop-scaffolding-start-coding.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_tutorials_stop-scaffolding-start-coding.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_tutorials_stop-scaffolding-start-coding.adoc
new file mode 100644
index 0000000..bbda412
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_tutorials_stop-scaffolding-start-coding.adoc
@@ -0,0 +1,684 @@
+[[_ug_tutorials_stop-scaffolding-start-coding]]
+= Stop scaffolding, start coding
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 half-day tutorial on developing domain-driven apps using Apache Isis. Actually, you could probably spend a full day working through this tutorial if you wanted to, so pick and choose the bits that look interesting.
+
+There's a bit of overlap with the xref:ug.adoc#_ug_tutorials_pet-clinic[Pet Clinic] tutorial initially, but it then sets off on its own.
+
+
+
+== Prerequisites
+
+You'll need:
+
+* Java 7 JDK
+* http://maven.apache.org/[Maven] 3.2.x
+* an IDE, such as http://www.eclipse.org/[Eclipse] or https://www.jetbrains.com/idea/[IntelliJ IDEA].
+
+
+
+== Run the archetype
+
+As per the http://isis.apache.org/intro/getting-started/simpleapp-archetype.html[Isis website], run the simpleapp archetype to build an empty Isis application:
+
+[source,bash]
+----
+mvn archetype:generate \
+ -D archetypeGroupId=org.apache.isis.archetype \
+ -D archetypeArtifactId=simpleapp-archetype \
+ -D archetypeVersion=1.8.0 \
+ -D groupId=com.mycompany \
+ -D artifactId=myapp \
+ -D version=1.0-SNAPSHOT \
+ -D archetypeRepository=http://repository-estatio.forge.cloudbees.com/snapshot/ \
+ -B
+----
+
+
+
+
+== Build and run
+
+Start off by building the app from the command line:
+
+[source,bash]
+----
+cd myapp
+mvn clean install
+----
+
+Once that's built then run using:
+
+[source,bash]
+----
+mvn antrun:run -P self-host
+----
+
+A splash screen should appear offering to start up the app. Go ahead and start; the web browser should be opened at http://localhost:8080[http://localhost:8080]
+
+Alternatively, you can run using the mvn-jetty-plugin:
+
+[source,bash]
+----
+mvn jetty:run
+----
+
+This will accomplish the same thing, though the webapp is mounted at a slightly different URL
+
+
+
+
+== Using the app
+
+Navigate to the Wicket UI (eg link:http://localhost:8080/wicket[http://localhost:8080/wicket]), and login (sven/pass).
+
+Once at the home page:
+
+* install fixtures
+* list all objects
+* create a new object
+* list all objects
+
+Go back to the splash screen, and quit the app. Note that the database runs in-memory (using HSQLDB) so any data created will be lost between runs.
+
+
+
+
+== Dev environment
+
+Set up xref:dg.adoc[an IDE] and import the project to be able to run and debug the app.
+
+Then set up a launch configuration and check that you can:
+
+* Run the app from within the IDE
+* Run the app in debug mode
+* Run with different deploymentTypes; note whether prototype actions (those annotated xref:rg.adoc#_rg_annotations_manpage-Action_restrictTo[`@Action(restrictTo=PROTOTYPING`]) are available or not:
+* `--type SERVER_PROTOTYPE`
+* `--type SERVER`
+
+
+
+
+== Explore codebase
+
+Apache Isis applications are organized into several Maven modules. Within your IDE navigate to the various classes and correlate back to the generated UI:
+
+* `myapp` : parent module
+* `myapp-dom`: domain objects module
+* entity: `dom.simple.SimpleObject`
+* repository: `dom.simple.SimpleObjects`
+* `myapp-fixture`: fixtures module
+* fixture script:`fixture.simple.SimpleObjectsFixture`
+* `myapp-integtests`: integration tests module
+* `myapp-webapp`: webapp module
+* (builds the WAR file)
+
+
+
+
+== Testing
+
+Testing is of course massively important, and Isis makes both unit testing and (end-to-end) integration testing easy. Building the app from the Maven command line ("mvn clean install") will run all tests, but you should also run the tests from within the IDE.
+
+* `myapp-dom` unit tests
+* run
+* inspect, eg
+ - `SimpleObjectTest`
+* `myapp-integtests` integration tests
+* run
+* inspect, eg:
+** `integration.tests.smoke.SimpleObjectsTest`
+** `integration.specs.simple.SimpleObjectSpec_listAllAndCreate.feature`
+* generated report, eg
+ - `myapp/integtests/target/cucumber-html-report/index.html`
+** change test in IDE, re-run (in Maven)
+
+If you have issues with the integration tests, make sure that the domain classes have been enhanced by the DataNucleus enhancer. (The exact mechanics depends on the IDE being used).
+
+
+
+
+== Prototyping
+
+Although testing is important, in this tutorial we want to concentrate on how to write features and to iterate quickly. So for now, exclude the `integtests` module. Later on in the tutorial we'll add the tests back in so you can learn how to write automated tests for the features of your app.
+
+In the parent `pom.xml`:
+
+[source,xml]
+----
+<modules>
+ <module>dom</module>
+ <module>fixture</module>
+ <module>integtests</module>
+ <module>webapp</module>
+</modules>
+----
+
+change to:
+
+[source,xml]
+----
+<modules>
+ <module>dom</module>
+ <module>fixture</module>
+ <!--
+ <module>integtests</module>
+ -->
+ <module>webapp</module>
+</modules>
+----
+
+
+
+
+== Build a domain app
+
+The remainder of the tutorial provides guidance on building a domain application. We don't mandate any particular design, but we suggest one with no more than 3 to 6 domain entities in the first instance. If you're stuck for ideas, then how about:
+
+* a todo app (``ToDoItem``s)
+* a pet clinic (`Pet`, `Owner`, `PetSpecies`, `Visit`)
+* a library (`Book`, `Title`, `LibraryMember`, `Loan`, `Reservation`)
+* a holiday cottage rental system
+* a scrum/kanban system (inspired by Trello)
+* a meeting planner (inspired by Doodle)
+* (the domain model for) a CI server (inspired by Travis/Jenkins)
+* a shipping system (inspired by the example in the DDD "blue" book)
+* a system for ordering coffee (inspired by Restbucks, the example in "Rest in Practice" book)
+
+Hopefully one of those ideas appeals or sparks an idea for something of your own.
+
+
+
+
+== Domain entity
+
+Most domain objects in Apache Isis applications are persistent entities. In the simpleapp archetype the `SimpleObject` is an example. We can start developing our app by refactoring that class:
+
+* rename the `SimpleObject` class
+** 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]
+* make the entity bookmarkable by adding the <<__code_domainobjectlayout_code,@DomainObjectLayout(bookmarking=...)` annotation
+* confirm is available from bookmark panel (top-left of Wicket UI)
+
+
+
+
+== Domain service
+
+Domain services often act as factories or repositories to entities; more generally can be used to "bridge across" to other domains/bounded contexts. Most are application-scoped, but they can also be request-scoped if required.
+
+In the simpleapp archetype the `SimpleObjects` service is a factory/repository for the original `SimpleObject` entity. For our app it therefore makes sense to refactor that class into our own first service:
+
+* 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]
+* 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]
+* note the annotations on the corresponding domain class (originally called `SimpleObject`, though renamed by now, eg to `Pet`)
+* rename if you wish
+** eg `listPets()`
+* note the xref:rg.adoc#_rg_annotations_manpage-DomainService[`@DomainService`] annotation
+* optional: add an action to a return subset of objects
+** use the JDO `@Query` annotation
+** see for example the Isisaddons example https://github.com/isisaddons/isis-app-todoapp[todoapp] (not ASF), see https://github.com/apache/isis/blob/b3e936c9aae28754fb46c2df52b1cb9b023f9ab8/example/application/todoapp/dom/src/main/java/dom/todo/ToDoItem.java#L93[here] and https://github.com/apache/isis/blob/b3e936c9aae28754fb46c2df52b1cb9b023f9ab8/example/application/todoapp/dom/src/main/java/dom/todo/ToDoItems.java#L63[here]
+
+
+
+
+== Fixture scripts
+
+Fixture scripts are used to setup the app into a known state. They are great for demo's and as a time-saver when implementing a feature, and they can also be reused in automated integration tests. We usually also have a fixture script to zap all the (non-reference) data (or some logical subset of the data)
+
+* rename the `SimpleObjectsTearDownFixture` class
+* and update to delete from the appropriate underlying database table(s)
+* use the injected xref:rg.adoc#_rg_services-api_manpage-IsisJdoSupport[`IsisJdoSupport`] domain service.
+* refactor/rename the fixture script classes that create instances your entity:
+* `RecreateSimpleObjects`, which sets up a set of objects for a given scenario
+* `SimpleObjectCreate` which creates a single object
+* note that domain services can be injected into these fixture scripts
+
+
+
+
+== Actions
+
+Most business functionality is implemented using actions� basically a `public` method accepting domain classes and primitives as its parameter types. The action can return a domain entity, or a collection of entities, or a primitive/String/value, or void. If a domain entity is returned then that object is rendered immediately; if a collection is returned then the Wicket viewer renders a table. Such collections are sometimes called "standalone" collections.
+
+* write an action to update the domain property (originally called `SimpleObject#name`, though renamed by now)
+* use the xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_named[`@ParameterLayout(named=...)`] annotation to specify the name of action parameters
+* use the xref:rg.adoc#_rg_annotations_manpage-Action_semantics[`@Action(semanticsOf=...)`] annotation to indicate the semantics of the action (safe/query-only, idempotent or non-idempotent)
+* annotate safe action as bookmarkable using xref:rg.adoc#_rg_annotations_manpage-ActionLayout_bookmarking[`@ActionLayout(bookmarking=...)`]
+* confirm is available from bookmark panel (top-left of Wicket UI)
+* optional: add an action to clone an object
+
+
+
+
+== REST API
+
+As well as exposing the Wicket viewer, Isis also exposes a REST API (an implementation of the http://restfulobjects.org[Restful Objects spec]). All of the functionality of the domain object model is available through this REST API.
+
+* add Chrome extensions
+* install https://chrome.google.com/webstore/detail/postman-rest-client/fdmmgilgnpjigdojojpjoooidkmcomcm?hl=en[Postman]
+* install https://chrome.google.com/webstore/detail/jsonview/chklaanhfefbnpoihckbnefhakgolnmc?hl=en[JSON-View]
+* browse to Wicket viewer, install fixtures
+* browse to the http://localhost:8080/restful[http://localhost:8080/restful] API
+* invoke the service to list all objects
+* services
+* actions
+* invoke (invoking 0-arg actions is easy; the Restful Objects spec defines how to invoke N-arg actions)
+
+
+
+
+== Specify Action semantics
+
+The semantics of an action (whether it is safe/query only, whether it is idempotent, whether it is neither) can be specified for each action; if not specified then Isis assumes non-idempotent. In the Wicket viewer this matters in that only query-only actions can be bookmarked or used as contributed properties/collections. In the RESTful viewer this matters in that it determines the HTTP verb (GET, PUT or POST) that is used to invoke the action.
+
+* experiment changing xref:rg.adoc#_rg_annotations_manpage-Action_semantics[`@Action(semantics=...)`] on actions
+* note the HTTP methods exposed in the REST API change
+* note whether the non-safe actions are bookmarkable (assuming that it has been annotated with `@ActionLayout(bookmarking=...)`, that is).
+
+
+
+
+== Value properties
+
+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:
+* for string properties
+** use the xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_multiLine[`@Property(multiLine=...)`] annotation to render a text area instead of a text box
+** use the xref:rg.adoc#_rg_annotations_manpage-Property_maxLength[`@Property(maxLength=...)`] annotation to specify the maximum number of characters allowable
+** use joda date/time properties, bigdecimals and blob/clob properties
+* use the xref:rg.adoc#_rg_annotations_manpage-Property_optionality[`@Column(allowsNull=...)`] annotation specify whether a property is optional or mandatory
+* use enums for properties (eg as used in the Isis addons example https://github.com/isisaddons/isis-app-todoapp[todoapp], see https://github.com/apache/isis/blob/b3e936c9aae28754fb46c2df52b1cb9b023f9ab8/example/application/todoapp/dom/src/main/java/dom/todo/ToDoItem.java#L207[here] and https://github.com/apache/isis/blob/b3e936c9aae28754fb46c2df52b1cb9b023f9ab8/example/application/todoapp/dom/src/main/java/dom/todo/ToDoItem.java#L266[here])
+* update the corresponding domain service for creating new instances
+* 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:rg.adoc#_rg_annotations_manpage-Title[`@Title`] annotation
+** rather than the xref:rg.adoc#_rg_methods_reserved_manpage-title[`title()`] `title()` method
+* order the properties using the xref:rg.adoc#_rg_annotations_manpage-MemberOrder[`@MemberOrder`], also `@MemberGroupLayout`
+** see also the docs on xref:rg.adoc#_rg_object-layout_static[static layouts]
+* use the xref:rg.adoc#_rg_annotations_manpage-PropertyLayout[`@PropertyLayout`] annotation to position property/action parameter labels either to the LEFT, TOP or NONE
+** do the same for parameters using xref:rg.adoc#_rg_annotations_manpage-ParameterLayout[`@ParameterLayout`]
+
+
+
+
+== Reference properties
+
+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]
+* update the corresponding domain service (for creation actoin)
+* use different techniques to obtain references (shown in drop-down list box)
+** use the xref:rg.adoc#_rg_annotations_manpage-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
+*** on a property
+*** on an action parameter
+** use a xref:rg.adoc#_rg_methods_prefixes_manpage-autoComplete[`autoComplete...()`] supporting method
+*** on a property
+*** on an action parameter
+
+
+
+
+== Usability: Defaults
+
+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
+
+
+
+
+== Collections
+
+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`
+*** 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
+** Use the xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_render[`@CollectionLayout(render=...)`] annotation to indicate if the collection should be visible or hidden by default
+* optional: use the xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_sortedBy[`@CollectionLayout(sortedBy=...)`] annotation to specify a different comparator than the natural ordering
+
+
+
+
+
+== Actions and Collections
+
+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
+** generally we recommend using the xref:rg.adoc#_rg_annotations_manpage-Inject[`@Inject`] annotation with either private or default visibility
+* the service itself should use xref:rg.adoc#_rg_services-api_manpage-DomainObjectContainer[`DomainObjectContainer`]
+* use the xref:rg.adoc#_rg_annotations_manpage-MemberOrder[`@MemberOrder(name=...)`] annotation to associate an action with a property or with a collection
+
+
+
+
+== CSS UI Hints
+
+CSS classes can be associated with any class member (property, collection, action). But for actions in particular:
+
+* the bootstrap "btn" CSS classes can be used using the xref:rg.adoc#_rg_annotations_manpage-ActionLayout_cssClass[`@ActionLayout(cssClass=...)`] annotation
+
+* the http://fortawesome.github.io/Font-Awesome/icons/[Font Awesome] icons can be used using the xref:rg.adoc#_rg_annotations_manpage-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].
+
+So:
+- for some of the actions of your domain services or entities, annotate using `@ActionLayout(cssClass=...)` or `@ActionLayout(cssClassFa=...)`
+
+
+
+
+== Dynamic Layout
+
+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>Reload Changed Classes):
+
+* Delete the various hint annotations and instead specify layout hints using a xref:rg.adoc#_rg_object-layout_dynamic[.layout.json] file.
+
+
+
+
+== Business rules
+
+Apache Isis excels for domains where there are complex business rules to enforce. The UI tries not to constrain the user from navigating around freely, however the domain objects nevertheless ensure that they cannot change into an invalid state. Such rules can be enforced either declaratively (using annotations) or imperatively (using code). The objects can do this in one of three ways:
+
+* visibility: preventing the user from even seeing a property/collection/action
+* usability: allowing the user to view a property/collection/action but not allowing the user to change it
+* validity: allowing the user to modify the property/invoke the action, but validating that the new value/action arguments are correct before hand.
+
+Or, more pithily: "see it, use it, do it"
+
+
+=== See it!
+
+* Use the xref:rg.adoc#_rg_annotations_manpage-Property_hidden[`Property(hidden=...)`] annotation to make properties invisible
+** likewise xref:rg.adoc#_rg_annotations_manpage-Collection_hidden[`@Collection(hidden=...)`] for collections
+** the xref:rg.adoc#_rg_annotations_manpage-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 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 it!
+
+* Use the xref:rg.adoc#_rg_annotations_manpage-Property_editing[`Property(editing=...)`] annotation to make property read-only
+** likewise xref:rg.adoc#_rg_annotations_manpage-Collection_editing[`@Collection(editing=...)`] for collections
+** alternatively, use xref:rg.adoc#_rg_annotations_manpage-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
+
+
+=== Do it!
+
+* Validate string properties or action parameters:
+* use the xref:rg.adoc#_rg_annotations_manpage-Property_regex[`@Property(regex=...)`] annotation to specify a regex pattern for properties, and use xref:rg.adoc#_rg_annotations_manpage-Parameter_regex[`@Parameter(regex=...)`] for parameters
+* use the xref:rg.adoc#_rg_annotations_manpage-Property_maxLength[`@Property(maxLength=...)`] annotation to indicate a minimum number of characters, and xref:rg.adoc#_rg_annotations_manpage-Parameter_minLength[`@Parameter(minLength=...)`] for parameters
+* Use the xref:rg.adoc#_rg_methods_prefixes_manpage-validate[`validate...()`] supporting method on properties or action parameter
+* optional: for any data type:
+** use the xref:rg.adoc#_rg_annotations_manpage-Property_mustSatisfy[`Property(mustSatisfy=...)`] and xref:rg.adoc#_rg_annotations_manpage-Parameter_mustSatisfy[`Parameter(mustSatisfy=...)`] annotations to specify arbitrary constraints on properties and parameters
+
+
+
+
+== Home page
+
+The Wicket UI will automatically invoke the "home page" action, if available. This is a no-arg action of one of the domain services, that can return either an object (eg representing the current user) or a standalone action.
+
+* Add the xref:rg.adoc#_rg_annotations_manpage-HomePage[`@HomePage`] annotation to one (no more) of the domain services' no-arg actions
+
+
+
+
+== Clock Service
+
+To ensure testability, there should be no dependencies on system time, for example usage of `LocalDate.now()`. Instead the domain objects should delegate to the provided `ClockService`.
+
+* remove any dependencies on system time (eg defaults for date/time action parameters)
+* inject xref:rg.adoc#_rg_services-api_manpage-ClockService[`ClockService`]
+* call `ClockService.now()` etc where required.
+
+
+
+
+== Using Contributions
+
+One of Isis' most powerful features is the ability for the UI to combine functionality from domain services into the representation of an entity. The effect is similar to traits or mix-ins in other languages, however the "mixing in" is done at runtime, within the Isis metamodel. In Isis' terminology, we say that the domain service action is contributed to the entity.
+
+Any action of a domain service that has a domain entity type as one of its parameter types will (by default) be contributed. If the service action takes more than one argument, or does not have safe semantics, then it will be contributed as an entity action. If the service action has precisely one parameter type (that of the entity) and has safe semantics then it will be contributed either as a collection or as a property (dependent on whether it returns a collection of a scalar).
+
+Why are contributions so useful? Because the service action will match not on the entity type, but also on any of the entity's supertypes (all the way up to `java.lang.Object`). That means that you can apply the http://en.wikipedia.org/wiki/Dependency_inversion_principle[dependency inversion principle] to ensure that the modules of your application have acyclic dependencies; but in the UI it can still appear as if there are bidirectional dependencies between those modules. The lack of bidirectional dependencies can help save your app degrading into a http://en.wikipedia.org/wiki/Big_ball_of_mud[big ball of mud].
+
+Finally, note that the layout of contributed actions/collections/properties can be specified using the `.layout.json` file (and it is highly recommended that you do so).
+
+=== Contributed Actions
+
+* Write a new domain service
+** by convention, called "XxxContributions"
+** annotate with xref:rg.adoc#_rg_annotations_manpage-DomainService_nature[`@DomainService(nature=NatureOfService.VIEW_CONTRIBUTIONS_ONLY)`]
+*** indicates that all of the service's actions should _not_ be included in the main application menu bar
+*** should be rendered "as if" an action of the entity
+* Write an action accepting >1 args:
+** one being a domain entity
+** other being a primitive or String
+
+=== Contributed Collections
+
+* Write a new domain service (or update the one previously)
+* Write a query-only action accepting exactly 1 arg (a domain entity)
+* returning a collection, list or set
+* For this action:
+** add the xref:rg.adoc#_rg_annotations_manpage-ActionLayout_contributedAs[`@ActionLayout(contributedAs=ASSOCIATION)`] annotation
+** should be rendered in the UI "as if" a collection of the entity
+* use `.layout.json` to position as required
+
+
+=== Contributed Properties
+
+* As for contributed collections, write a new domain service with a query-only action accepting exactly 1 arg (a domain entity); except:
+** returning a scalar value rather than a collection
+* For this action:
+** add the xref:rg.adoc#_rg_annotations_manpage-ActionLayout_contributedAs[`@ActionLayout(contributedAs=ASSOCIATION)`] annotation
+* should be rendered in the UI "as if" a property of the entity
+* use `.layout.json` to position as required
+
+
+
+== Using the Event Bus
+
+Another way in which Apache Isis helps you keep your application nicely modularized is through its event bus. Each action invocation, or property modification, can be used to generate a succession of events that allows subscribers to veto the interaction (the see it/use it/do it rules) or, if the action is allowed, to perform work prior to the execution of the action or after the execution of the action.
+
+Under the covers Isis uses the https://code.google.com/p/guava-libraries/wiki/EventBusExplained[Guava event bus] and subscribers (always domain services) subscribe by writing methods annotated with `@com.google.common.eventbus.Subscribe` annotation.
+
+By default the events generated are `ActionDomainEvent.Default` (for actions) and `PropertyDomainEvent.Default` (for properties). Subclasses of these can be specified using the xref:rg.adoc#_rg_annotations_manpage-Action_domainEvent[`@Action(domainEvent=...)`] or xref:rg.adoc#_rg_annotations_manpage-Property_domainEvent[`Property(domainEvent=...)`] for properties.
+
+
+Using the guidance in the docs for the xref:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`]:
+
+* write a domain service subscriber to subscribe to events
+* use the domain service to perform log events
+* use the domain service to veto actions (hide/disable or validate)
+
+
+
+== Bulk actions
+
+Bulk actions are actions that can be invoked on a collection of actions, that is on collections returned by invoking an action. Actions are specified as being bulk actions using the xref:rg.adoc#_rg_annotations_manpage-Action_invokeOn[`@action(invokeOn=OBJECT_AND_COLLECTION)`] annotation.
+
+[NOTE]
+====
+Note that currently (1.8.0) only no-arg actions can be specified as bulk actions.
+====
+
+Thus:
+* Write a no-arg action for your domain entity, annotate with `@Action(invokeOn=...)`
+* Inject the xref:rg.adoc#_rg_services-api_manpage-ActionInvocationContext[`ActionInteractionContext`] (request-scoped) service
+* Use the `ActionInteractionContext` service to determine whether the action was invoked in bulk or as a regular action.
+* return null if invoked on a collection; the Wicket viewer will go back to the original collection
+** (if return non-null, then Wicket viewer will navigate to the object of the last invocation� generally not what is required)
+
+The similar xref:rg.adoc#_rg_services-api_manpage-ScratchPad[`ScratchPad`] (request-scoped) domain service is a good way to share information between bulk action invocations:
+
+* Inject the `ScratchPad` domain service
+* for each action, store state (eg a running total)
+* in the last invoked bulk action, perform some aggregate processing (eg calculate the average) and return
+
+
+
+
+== Performance tuning
+
+The xref:rg.adoc#_rg_services-api_manpage-QueryResultsCache[`QueryResultsCache`] (request-scoped) domain service allows arbitrary objects to be cached for the duration of a request.
+
+This can be helpful for "naive" code which would normally make the same query within a loop.
+
+* optional: inject the `QueryResultsCache` service, invoke queries "through" the cache API
+* remember that the service is request-scoped, so it only really makes sense to use this service for code that invokes queries within a loop
+
+
+
+
+== Extending the Wicket UI
+
+Each element in the Wicket viewer (entity form, properties, collections, action button etc) is a component, each created by a internal API (`ComponentFactory`, described xref:ug.adoc#_ug_extending_wicket-viewer[here]). For collections there can be multiple views, and the Wicket viewer provides a view selector drop down (top right of each collection panel).
+
+Moreover, we can add additional views. In this section we'll explore some of these, already provided through http://www.isisaddons.org/[Isis addons] (not ASF).
+
+=== Excel download
+
+The https://github.com/isisaddons/isis-wicket-excel[Excel download add-on] allows the collection to be downloaded as an Excel spreadsheet (`.xlsx`).
+
+* Use the instructions on the add-on module's README to add in the excel download module (ie: update the POM).
+
+=== Fullcalendar2
+
+The https://github.com/isisaddons/isis-wicket-fullcalendar2[Fullcalendar2 download add-on] allows entities to be rendered in a full-page calendar.
+
+* Use the instructions on the add-on module's README to add in the fullcalendar2 module (ie: update the POM).
+* on one of your entities, implement either the `CalendarEventable` interface or the (more complex) `Calendarable` interface.
+* update fixture scripts to populate any new properties
+* when the app is run, a collection of the entities should be shown within a calendar view
+
+=== gmap3
+
+The https://github.com/isisaddons/isis-wicket-gmap3[Gmap3 download add-on] allows entities that implement certain APIs to be rendered in a full-page gmap3.
+
+* Use the instructions on the add-on module's README to add in the gmap3 module (ie: update the POM).
+* on one of your entities, implement the `Locatable` interface
+* update fixture scripts to populate any new properties
+* when the app is run, a collection of the entities should be shown within a map view
+
+
+
+
+== Add-on modules (optional)
+
+In addition to providing Wicket viewer extensions, http://www.isisaddons.org/[Isis addons] also has a large number of modules. These address such cross-cutting concerns as security, command (profiling), auditing and publishing.
+
+* (optional): follow the https://github.com/isisaddons/isis-module-security[security module] README or http://youtu.be/bj8735nBRR4[screencast]
+* (optional): follow the https://github.com/isisaddons/isis-module-command[command module] README or http://youtu.be/g01tK58MxJ8[screencast]
+* (optional): follow the https://github.com/isisaddons/isis-module-audit[auditing module] README or (the same) http://youtu.be/g01tK58MxJ8[screencast]
+
+
+
+
+== View models
+
+In most cases users can accomplish the business operations they need by invoking actions directly on domain entities. For some high-volume or specialized uses cases, though, there may be a requirement to bring together data or functionality that spans several entities.
+
+Also, if using 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, Isis therefore allows you to write a view model, either by annotating the class with xref:rg.adoc#_rg_annotations_manpage-ViewModel[`@ViewModel`] or (for more control) by implementing the xref:rg.adoc#_rg_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)
+
+
+
+
+== Testing
+
+Up to this point we've been introducing the features of Isis and building out our domain application, but with little regard to testing. Time to fix that.
+
+
+=== Unit testing
+
+Unit testing domain entities and domain services is easy; just use JUnit and mocking libraries to mock out interactions with domain services.
+
+https://code.google.com/p/mockito/[Mockito] seems to be the current favourite among Java developers for mocking libraries, but if you use JMock then you'll find we provide a `JUnitRuleMockery2` class and a number of other utility classes, documented xref:_unit_test_support[here].
+
+* write some unit tests (adapt from the unit tests in the `myapp-dom` Maven module).
+
+
+
+=== Integration testing
+
+Although unit tests are easy to write and fast to execute, integration tests are more valuable: they test interactions of the system from the outside-in, simulating the way in which the end-users use the application.
+
+Earlier on in the tutorial we commented out the `myapp-integtests` module. Let's commented it back in. In the parent `pom.xml`:
+
+[source,xml]
+----
+<modules>
+ <module>dom</module>
+ <module>fixture</module>
+ <!--
+ <module>integtests</module>
+ -->
+ <module>webapp</module>
+</modules>
+----
+
+change back to:
+
+[source,xml]
+----
+<modules>
+ <module>dom</module>
+ <module>fixture</module>
+ <module>integtests</module>
+ <module>webapp</module>
+</modules>
+----
+
+There will probably be some compile issues to fix up once you've done this; comment out all code that doesn't compile.
+
+Isis has great support for writing xref:ug.adoc#_ug_testing_integ-test-support[integration tests]; well-written integration tests should leverage fixture scripts and use the xref:rg.adoc#_rg_services-api_manpage-WrapperFactory[`@WrapperFactory`] domain service.
+
+* use the tests from the original archetype and the documentation on the website to develop integration tests for your app's functionality.
+
+
+
+
+== Customising the REST API
+
+The REST API generated by Isis conforms to the Restful Objects specification. Isis 1.8.0 provides experimental support to allow the representations to be customized.
+
+* as per xref:ug.adoc#_ug_restfulobjects-viewer_configuration-properties_simplified-object[the documentation], configure the Restful Objects viewer to generate a simplified object representation: +
++
+[source,ini]
+----
+isis.viewer.restfulobjects.objectPropertyValuesOnly=true
+----
+
+
+
+
+== Configuring to use an external database
+
+If you have an external database available, then update the `pom.xml` for the classpath and update the JDBC properties in `WEB-INF\persistor.properties` to point to your database.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer.adoc
new file mode 100644
index 0000000..3706371
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer.adoc
@@ -0,0 +1,30 @@
+[[_ug_wicket-viewer]]
+= 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/
+
+This chapter describes end-user features, configuration and customization of the Wicket viewer.
+
+Note that extending the Wicket viewer is described in the <<Extending>> chapter.
+
+
+include::_ug_wicket-viewer_features.adoc[leveloffset=+1]
+
+include::_ug_wicket-viewer_configuration-properties.adoc[leveloffset=+1]
+
+include::_ug_wicket-viewer_request-parameters.adoc[leveloffset=+1]
+
+include::_ug_wicket-viewer_layout.adoc[leveloffset=+1]
+
+include::_ug_wicket-viewer_customisation.adoc[leveloffset=+1]
+
+
+
+== Extending the viewer
+
+APIs to extend the Wicket viewer are discussed in the xref:ug.adoc#_ug_extending[Extending] chapter.
+
+
+include::_ug_wicket-viewer_isis-addons.adoc[leveloffset=+1]
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_configuration-properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_configuration-properties.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_configuration-properties.adoc
new file mode 100644
index 0000000..2364cb5
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_configuration-properties.adoc
@@ -0,0 +1,112 @@
+[[_ug_wicket-viewer_configuration-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/
+
+
+Wicket configuration properties alter the way in which Isis' Wicket viewer renders domain objects. They are typically stored in `WEB-INF/viewer_wicket.properties`.
+
+[NOTE]
+====
+To tell Isis that the Wicket viewer is in use (and should therefore search for the `viewer_wicket.properties` file), add the following to `WEB-INF/web.xml`:
+
+[source, xml]
+----
+<context-param>
+ <param-name>isis.viewers</param-name>
+ <param-value>wicket</param-value>
+</context-param>
+----
+
+====
+
+If you prefer you can place all configuration properties into `WEB-INF/isis.properties` (the configuration properties from all config files are merged together).
+
+
+.Wicket Viewer Configuration Properties
+[cols="2a,1,3", options="header"]
+|===
+|Property
+|Value +
+(_default value_)
+|Description
+
+|`isis.viewer.wicket.` +
+`bookmarkedPages`
+| +ve int (`_15_`)
+| number of pages to bookmark
+
+|`isis.viewer.wicket.` +
+`disableDependentChoiceAutoSelection`
+| `true`,`false` (`_false_`)
+| For dependent choices, whether to automatically select the first dependent (eg subcategory) when the parameter on which it depends (category) changes.
+
+|`isis.viewer.wicket.` +
+`disableModalDialogs`
+| `true`,`false` (`_false_`)
+| By default the Isis Wicket viewer uses a modal dialog for action parameters. Before this feature was implemented (prior to 1.4.0), Isis rendered action parameters on its own page. This property re-enables the old behaviour.
+
+Note that action pages are still used for bookmarked actions.
+
+|`isis.viewer.wicket.` +
+`maxTitleLengthInParentedTables`
+| +ve integer, (`_12_`)
+| See discussion xref:ug.adoc#_ug_wicket-viewer_configuration-properties_abbreviating-titles[below].
+
+|`isis.viewer.wicket.` +
+`maxTitleLengthInStandaloneTables`
+| +ve integer, (`_12_`)
+| See discussion xref:ug.adoc#_ug_wicket-viewer_configuration-properties_abbreviating-titles[below].
+
+|`isis.viewer.wicket.` +
+`maxTitleLengthInTables`
+| +ve integer, (`_12_`)
+| See discussion xref:ug.adoc#_ug_wicket-viewer_configuration-properties_abbreviating-titles[below].
+
+|`isis.viewer.wicket.` +
+`regularCase`
+| `true`,`false` (`_false_`)
+| Ignored for 1.8.0+; in earlier versions forced regular case rather than title case in the UI
+
+|`isis.viewer.wicket.` +
+`stripWicketTags`
+| `true`,`false` (`_true_`)
+| Whether to force Wicket tags to be stripped in prototype/development mode. See discussion xref:ug.adoc#_ug_wicket-viewer_configuration-properties_stripped-wicket-tags[below].
+
+|`isis.viewer.wicket.` +
+`suppressPasswordReset`
+| `true`,`false` (`_false_`)
+|If user registration is enabled, whether to suppress the "password reset" link on the login page. See discussion xref:ug.adoc#_ug_wicket-viewer_configuration-properties_suppressing-password-reset[below].
+
+|`isis.viewer.wicket.` +
+`suppressRememberMe`
+| `true`,`false` (`_false_`)
+|Whether to suppress "remember me" checkbox on the login page.
+
+|`isis.viewer.wicket.` +
+`suppressSignUp`
+| `true`,`false` (`_false_`)
+|If user registration is enabled, whether to suppress the "sign up" link on the login page. See discussion xref:ug.adoc#_ug_wicket-viewer_configuration-properties_suppressing-sign-up[below].
+
+|`isis.viewer.wicket.` +
+`themes.enabled`
+| comma separated list ...
+| ... of bootswatch themes. Only applies if `themes.showChooser`==`true`. See discussion xref:ug.adoc#_ug_wicket-viewer_configuration-properties_showing-theme-chooser[below].
+
+|`isis.viewer.wicket.` +
+`themes.showChooser`
+| `true`,`false` (`_false_`)
+| Whether to show chooser for Bootstrap themes. See discussion xref:ug.adoc#_ug_wicket-viewer_configuration-properties_showing-theme-chooser[below]
+
+|===
+
+
+
+include::_ug_wicket-viewer_configuration-properties_abbreviating-titles.adoc[leveloffset=+1]
+include::_ug_wicket-viewer_configuration-properties_suppressing-remember-me.adoc[leveloffset=+1]
+include::_ug_wicket-viewer_configuration-properties_suppressing-sign-up.adoc[leveloffset=+1]
+include::_ug_wicket-viewer_configuration-properties_suppressing-password-reset.adoc[leveloffset=+1]
+include::_ug_wicket-viewer_configuration-properties_stripped-wicket-tags.adoc[leveloffset=+1]
+include::_ug_wicket-viewer_configuration-properties_showing-theme-chooser.adoc[leveloffset=+1]
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_configuration-properties_abbreviating-titles.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_configuration-properties_abbreviating-titles.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_configuration-properties_abbreviating-titles.adoc
new file mode 100644
index 0000000..94ba6ad
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_configuration-properties_abbreviating-titles.adoc
@@ -0,0 +1,33 @@
+[[_ug_wicket-viewer_configuration-properties_abbreviating-titles]]
+= Abbreviating/suppressing titles 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/
+
+
+
+Objects whose title is overly long can be cumbersome in titles. The Wicket viewer has a xref:ug.adoc#_ug_wicket-viewer_features_titles-in-tables[mechanism to automatically shorten] the titles of objects specified using `@Title`. As an alternative/in addition, the viewer can also be configured to simply truncate titles longer than a certain length.
+
+The properties themselves are:
+
+[source,ini]
+----
+isis.viewer.wicket.maxTitleLengthInStandaloneTables=20
+isis.viewer.wicket.maxTitleLengthInParentedTables=8
+----
+
+If you wish to use the same value in both cases, you can also specify just:
+
+[source,ini]
+----
+isis.viewer.wicket.maxTitleLengthInTables=15
+----
+
+This is used as a fallback if the more specific properties are not provided.
+
+If no properties are provided, then the Wicket viewer defaults to abbreviating titles to a length of `12`.
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_configuration-properties_showing-theme-chooser.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_configuration-properties_showing-theme-chooser.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_configuration-properties_showing-theme-chooser.adoc
new file mode 100644
index 0000000..78ee943
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_configuration-properties_showing-theme-chooser.adoc
@@ -0,0 +1,43 @@
+[[_ug_wicket-viewer_configuration-properties_showing-theme-chooser]]
+= Showing a theme chooser
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 Wicket viewer uses http://getbootstrap.com/[Bootstrap] styles and components (courtesy of the https://github.com/l0rdn1kk0n/wicket-bootstrap[Wicket Bootstrap] integration).
+
+Unless a xref:ug.adoc#_ug_wicket-viewer_customisation_default-theme[default theme has been specified], the viewer uses the default bootstrap theme. However,
+the viewer can also be configured to allow the end-user to switch theme to another theme, in particular one of those provided by http://bootswatch.com[bootswatch.com].
+
+This is done using the following configuration property (in `WEB-INF/viewer_wicket.properties`):
+
+[source,ini]
+----
+isis.viewer.wicket.themes.showChooser=true
+----
+
+.Example 1
+image::{_imagesdir}wicket-viewer/theme-chooser/example-1.png[width="720px",link="{_imagesdir}wicket-viewer/theme-chooser/example-1.png"]
+
+
+.Example 2:
+image::{_imagesdir}wicket-viewer/theme-chooser/example-2.png[width="720px",link="{_imagesdir}wicket-viewer/theme-chooser/example-2.png"]
+
+It is also possible to restrict the themes shown to some subset of those in bootswatch. This is done using a further
+property:
+
+[source,ini]
+----
+isis.viewer.wicket.themes.enabled=bootstrap-theme,Cosmo,Flatly,Darkly,Sandstone,United
+----
+
+where the value is the list of themes (from http://bootswatch.com[bootswatch.com]) to be made available.
+
+[TIP]
+====
+You can also develop and install a custom themes (eg to fit your company's look-n-feel/interface guidelines); see the xref:ug.adoc#_ug_extending_wicket-viewer_custom-bootstrap-theme[Extending] chapter for further details.
+====
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_configuration-properties_stripped-wicket-tags.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_configuration-properties_stripped-wicket-tags.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_configuration-properties_stripped-wicket-tags.adoc
new file mode 100644
index 0000000..cb653bd
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_configuration-properties_stripped-wicket-tags.adoc
@@ -0,0 +1,26 @@
+[[_ug_wicket-viewer_configuration-properties_stripped-wicket-tags]]
+= Stripped Wicket tags
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 Isis Wicket viewer will always strip wicket tags. However, when running in prototype mode, this behaviour can be overridden using a configuration property:
+
+[source,ini]
+----
+isis.viewer.wicket.stripWicketTags=false
+----
+
+[NOTE]
+====
+In 1.7.0 and earlier, the behaviour is different; the Isis Wicket viewer will preserve wicket tags when running in Isis' prototype/development mode, but will still strip wicket tags in Isis' server/deployment mode.
+
+We changed the behaviour in 1.8.0 because we found that Internet Explorer can be sensitive to the presence of Wicket tags.
+====
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_configuration-properties_suppressing-password-reset.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_configuration-properties_suppressing-password-reset.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_configuration-properties_suppressing-password-reset.adoc
new file mode 100644
index 0000000..d9d24ad
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_configuration-properties_suppressing-password-reset.adoc
@@ -0,0 +1,47 @@
+[[_ug_wicket-viewer_configuration-properties_suppressing-password-reset]]
+= Suppressing 'password reset'
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 xref:_user_registration[user registration] has been configured, then the Wicket viewer allows the user to sign-up a new account and to reset their password from the login page.
+
+The 'password reset' link can be suppressed, if required, by setting a configuration flag.
+
+
+
+== Screenshots
+
+With 'password reset' not suppressed (the default):
+
+image::{_imagesdir}wicket-viewer/suppress-password-reset/login-page-default.png[width="300px",link="{_imagesdir}wicket-viewer/suppress-password-reset/login-page-default.png"]
+
+and with the link suppressed:
+
+image::{_imagesdir}wicket-viewer/suppress-password-reset/login-page-suppress-password-reset.png[width="300px",link="{_imagesdir}wicket-viewer/suppress-password-reset/login-page-suppress-password-reset.png"]
+
+
+
+== Configuration
+
+To suppress the 'password reset' link, add the following configuration flag:
+
+[source,ini]
+----
+isis.viewer.wicket.suppressPasswordReset=true
+----
+
+Typically this should be added to the `viewer_wicket.properties` file (in `WEB-INF`), though you can add to `isis.properties` if you wish.
+
+
+
+== See also
+
+The xref:ug.adoc#_ug_wicket-viewer_configuration-properties_suppressing-sign-up[sign up link] can be suppressed in a similar manner.
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_configuration-properties_suppressing-remember-me.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_configuration-properties_suppressing-remember-me.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_configuration-properties_suppressing-remember-me.adoc
new file mode 100644
index 0000000..887a572
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_configuration-properties_suppressing-remember-me.adoc
@@ -0,0 +1,35 @@
+[[_ug_wicket-viewer_configuration-properties_suppressing-remember-me]]
+= Suppressing 'remember me'
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 'remember me' checkbox on the login page can be suppressed, if required, by setting a configuration flag.
+
+
+
+== Screenshots
+
+With 'remember me' not suppressed (the default):
+
+image::{_imagesdir}wicket-viewer/suppress-remember-me/login-page-default.png[width="300px",link="{_imagesdir}wicket-viewer/suppress-remember-me/login-page-default.png"]
+
+and with the checkbox suppressed:
+
+image::{_imagesdir}wicket-viewer/suppress-remember-me/login-page-suppress-remember-me.png[width="300px",link="{_imagesdir}wicket-viewer/suppress-remember-me/login-page-suppress-remember-me.png"]
+
+
+
+== Configuration
+
+To suppress the 'remember me' checkbox, add the following configuration flag:
+
+[source,ini]
+----
+isis.viewer.wicket.suppressRememberMe=true
+
+----
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_configuration-properties_suppressing-sign-up.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_configuration-properties_suppressing-sign-up.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_configuration-properties_suppressing-sign-up.adoc
new file mode 100644
index 0000000..10d9901
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_configuration-properties_suppressing-sign-up.adoc
@@ -0,0 +1,49 @@
+[[_ug_wicket-viewer_configuration-properties_suppressing-sign-up]]
+= Suppressing 'sign up'
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 xref:_user_registration[user registration] has been configured, then the Wicket viewer allows the user to sign-up a new account and to reset their password from the login page.
+
+The 'sign up' link can be suppressed, if required, by setting a configuration flag.
+
+
+
+
+== Screenshots
+
+With 'sign up' not suppressed (the default):
+
+image::{_imagesdir}wicket-viewer/suppress-sign-up/login-page-default.png[width="300px",link="{_imagesdir}wicket-viewer/suppress-sign-up/login-page-default.png"]
+
+and with the link suppressed:
+
+image::{_imagesdir}wicket-viewer/suppress-sign-up/login-page-suppress-sign-up.png[width="300px",link="{_imagesdir}wicket-viewer/suppress-sign-up/login-page-suppress-sign-up.png"]
+
+
+
+
+== Configuration
+
+To suppress the 'sign up' link, add the following configuration flag:
+
+[source,ini]
+----
+isis.viewer.wicket.suppressSignUp=true
+----
+
+
+
+== See also
+
+The xref:ug.adoc#_ug_wicket-viewer_configuration-properties_suppressing-password-reset[password reset link] can be suppressed in a similar manner.
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_customisation.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_customisation.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_customisation.adoc
new file mode 100644
index 0000000..9ad143e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_customisation.adoc
@@ -0,0 +1,18 @@
+[[_ug_wicket-viewer_customisation]]
+= Customisation
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+include::_ug_wicket-viewer_customisation_brand-logo.adoc[leveloffset=+1]
+include::_ug_wicket-viewer_customisation_default-theme.adoc[leveloffset=+1]
+include::_ug_wicket-viewer_customisation_welcome-page.adoc[leveloffset=+1]
+include::_ug_wicket-viewer_customisation_about-page.adoc[leveloffset=+1]
+include::_ug_wicket-viewer_customisation_tweaking-css-classes.adoc[leveloffset=+1]
+include::_ug_wicket-viewer_customisation_tweaking-css-classes.adoc[leveloffset=+1]
+include::_ug_wicket-viewer_customisation_using-different-css-file.adoc[leveloffset=+1]
+include::_ug_wicket-viewer_customisation_custom-javascript.adoc[leveloffset=+1]
+include::_ug_wicket-viewer_customisation_auto-refresh.adoc[leveloffset=+1]
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_customisation_about-page.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_customisation_about-page.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_customisation_about-page.adoc
new file mode 100644
index 0000000..dddaed9
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_customisation_about-page.adoc
@@ -0,0 +1,121 @@
+[[_ug_wicket-viewer_customisation_about-page]]
+= About page
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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' Wicket viewer has an About page that, by default, will provide a dump of the JARs that make up the webapp. This page will also show the manifest attributes of the WAR archive itself, if there are any. One of these attributes may also be used as the application version number.
+
+
+== Screenshot
+
+Here's what the About page looks like with this configuration added:
+
+image::{_imagesdir}wicket-viewer/about-page/about-page.png[width="800px",link="{_imagesdir}wicket-viewer/about-page/about-page.png"]
+
+[NOTE]
+====
+Note that this screenshot shows an earlier version of the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] UI (specifically, pre 1.8.0).
+====
+
+Note that the `Build-Time` attribute has been used as the version number. The Wicket viewer is hard-coded to search for specific attributes and use as the application version. In order, it searches for:
+
+* `Implementation-Version`
+* `Build-Time`
+
+If none of these are found, then no version is displayed.
+
+== Configuration
+
+[TIP]
+====
+This configuration is included within the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype].
+====
+
+=== Adding attributes to the WAR's manifest
+
+Add the following to the webapp's `pom.xml` (under `<build>/<plugins>`):
+
+[source,xml]
+----
+<plugin>
+ <groupId>org.codehaus.mojo</groupId>
+ <artifactId>build-helper-maven-plugin</artifactId>
+ <version>1.5</version>
+ <executions>
+ <execution>
+ <phase>validate</phase>
+ <goals>
+ <goal>maven-version</goal>
+ </goals>
+ </execution>
+ </executions>
+</plugin>
+
+<plugin>
+ <artifactId>maven-war-plugin</artifactId>
+ <configuration>
+ <archive>
+ <manifest>
+ <addDefaultImplementationEntries>true</addDefaultImplementationEntries>
+ </manifest>
+ <manifestEntries>
+ <Build-Time>${maven.build.timestamp}</Build-Time>
+ <Build-Number>${buildNumber}</Build-Number>
+ <Build-Host>${agent.name}</Build-Host>
+ <Build-User>${user.name}</Build-User>
+ <Build-Maven>Maven ${maven.version}</Build-Maven>
+ <Build-Java>${java.version}</Build-Java>
+ <Build-OS>${os.name}</Build-OS>
+ <Build-Label>${project.version}</Build-Label>
+ </manifestEntries>
+ </archive>
+ </configuration>
+ <executions>
+ <execution>
+ <phase>package</phase>
+ <goals>
+ <goal>war</goal>
+ </goals>
+ <configuration>
+ <classifier>${env}</classifier>
+ </configuration>
+ </execution>
+ </executions>
+</plugin>
+----
+
+If you then build the webapp from the Maven command line (`mvn clean package`), then the WAR should contain a `META-INF/MANIFEST.MF` with those various attribute entries.
+
+=== Exporting the attributes into the app
+
+The manifest attributes are provided to the rest of the application by way of the Wicket viewer's integration with Google Guice.
+
+In your subclass of `IsisWicketApplication`, there is a method `newIsisWicketModule()`. In this method you need to bind an `InputStream` that will read the manifest attributes. This is all boilerplate so you can just copy-n-paste:
+
+[source,java]
+----
+@Override
+protected Module newIsisWicketModule() {
+ ...
+ final Module simpleappOverrides = new AbstractModule() {
+ @Override
+ protected void configure() {
+ ...
+ bind(InputStream.class)
+ .annotatedWith(Names.named("metaInfManifest"))
+ .toProvider(Providers.of(
+ getServletContext().getResourceAsStream("/META-INF/MANIFEST.MF")));
+ }
+ };
+ ...
+}
+----
+
+With that you should be good to go!
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_customisation_auto-refresh.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_customisation_auto-refresh.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_customisation_auto-refresh.adoc
new file mode 100644
index 0000000..2c8f645
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_customisation_auto-refresh.adoc
@@ -0,0 +1,35 @@
+[[_ug_wicket-viewer_customisation_auto-refresh]]
+= Auto-refresh page
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 requirement from the users mailing list:
+
+pass:[<div class="extended-quote-first"><p>]Suppose you want to build a monitoring application, eg for an electricity grid. Data is updated in the background (eg via the Restful Objects REST API). What is needed is the ability to show an entity that includes a http://github.com/isisaddons/isis-wicket-gmap3[map], and have it auto-refresh every 5 seconds or so.
+pass:[</p></div>]
+
+Here's one (somewhat crude, but workable) way to accomplish this.
+
+* First, update the domain object to return custom CSS: +
++
+[source,java]
+----
+public class MyDomainObject {
+ ...
+ public String cssClass() {return "my-special-auto-updating-entity"; }
+ ...
+}
+----
+
+* Then, use javascript in `webapp/src/main/webapp/scripts/application.js` to reload: +
++
+[source,javascript]
+----
+$(function() {
+ if ($(".my-special-auto-updating-entity").length) {
+ setTimeout(function() {document.location.reload();}, 5000); // 1000 is 5 sec
+ }
+});
+----
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_customisation_brand-logo.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_customisation_brand-logo.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_customisation_brand-logo.adoc
new file mode 100644
index 0000000..07de56c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_customisation_brand-logo.adoc
@@ -0,0 +1,71 @@
+[[_ug_wicket-viewer_customisation_brand-logo]]
+= Brand logo
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 Wicket viewer will display the application name top-left in the header menu. This can be changed to
+display a png logo instead.
+
+== Screenshots
+
+The screenshot below shows the Isis addons example https://github.com/isisaddons/isis-app-todoapp/[todoapp] (not ASF) with a 'brand logo' image in its header:
+
+image::{_imagesdir}wicket-viewer/brand-logo/brand-logo.png[width="750px",link="{_imagesdir}wicket-viewer/brand-logo/brand-logo.png"]
+
+A custom brand logo (typically larger) can also be specified for the signin page:
+
+image::{_imagesdir}wicket-viewer/brand-logo/brand-logo-signin.png[width="750px",link="{_imagesdir}wicket-viewer/brand-logo/brand-logo-signin.png"]
+
+
+
+
+== Configuration
+
+In the application-specific subclass of `IsisWicketApplication`, bind:
+
+* a string with name "brandLogoHeader" to the URL of a header image. A size of 160x40 works well.
+* a string with name "brandLogoSignin" to the URL of a image for the sign-in page. A size of 400x100 works well.
+
+For example:
+
+[source,java]
+----
+@Override
+protected Module newIsisWicketModule() {
+ final Module isisDefaults = super.newIsisWicketModule();
+
+ final Module overrides = new AbstractModule() {
+ @Override
+ protected void configure() {
+ ...
+ bind(String.class).annotatedWith(Names.named("brandLogoHeader"))
+ .toInstance("/images/todoapp-logo-header.png");
+ bind(String.class).annotatedWith(Names.named("brandLogoSignin"))
+ .toInstance("/images/todoapp-logo-signin.png");
+ ...
+ }
+ };
+
+ return Modules.override(isisDefaults).with(overrides);
+}
+----
+
+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:ug.adoc#_ug_runtime_application-specific_application-css[`application.css`]. For example, a logo with height 40px works well with the following:
+
+[source,css]
+----
+.navbar-brand img {
+ margin-top: -5px;
+ margin-left: 5px;
+}
+----
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_customisation_cheap-n-cheerful-theme.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_customisation_cheap-n-cheerful-theme.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_customisation_cheap-n-cheerful-theme.adoc
new file mode 100644
index 0000000..b96cb73
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_customisation_cheap-n-cheerful-theme.adoc
@@ -0,0 +1,29 @@
+[[_ug_wicket-viewer_customisation_cheap-n-cheerful-theme]]
+= Cheap-n-cheerful "theme"
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 application name (as defined in the `IsisWicketApplication` subclass) is also used (in sanitized form) as the CSS class in a `<div>` that wraps all the rendered content of every page.
+
+For example, if the application name is "ToDo App", then the `<div>` generated is:
+
+[source,html]
+----
+<div class="todo-app">
+ ...
+</div>
+----
+
+You can therefore use this CSS class as a way of building your own "theme" for the various elements of the wicket viewer pages.
+
+[TIP]
+====
+Alternatively you could "do it properly" and create your xref:ug.adoc#_ug_extending_wicket-viewer_custom-bootstrap-theme[own Bootstrap theme], as described in the <<Extending>> chapter.
+====
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_customisation_custom-javascript.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_customisation_custom-javascript.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_customisation_custom-javascript.adoc
new file mode 100644
index 0000000..908a1f2
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_customisation_custom-javascript.adoc
@@ -0,0 +1,42 @@
+[[_ug_wicket-viewer_customisation_custom-javascript]]
+= Custom Javascript
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 Wicket viewer ships with embedded JQuery, so this can be leveraged to perform arbitrary transformations of the rendered page (eg to run some arbitrary JQuery on page load).
+
+[WARNING]
+====
+Just because something is possible, it doesn't necessarily mean we encourage it. Please be aware that there is no formal API for any custom javascript that you might implement to target; future versions of Isis might break your code.
+
+If possible, consider using the `ComponentFactory` API described in the xref:ug.adoc#_ug_extending_wicket-viewer[Extending] chapter.
+====
+
+To register your Javascript code, adjusting the Guice bindings (part of Isis' bootstrapping) in your custom subclass of `IsisWicketApplication`:
+
+ public class MyAppApplication extends IsisWicketApplication {
+ @Override
+ protected Module newIsisWicketModule() {
+ final Module isisDefaults = super.newIsisWicketModule();
+ final Module myAppOverrides = new AbstractModule() {
+ @Override
+ protected void configure() {
+ ...
+ bind(String.class)
+ .annotatedWith(Names.named("applicationJs"))
+ .toInstance("scripts/application.js");
+ ...
+ }
+ };
+ return Modules.override(isisDefaults).with(myAppOverrides);
+ }
+ }
+
+Currently only one such `.js` file can be registered.
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_customisation_default-theme.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_customisation_default-theme.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_customisation_default-theme.adoc
new file mode 100644
index 0000000..8746e09
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_customisation_default-theme.adoc
@@ -0,0 +1,29 @@
+[[_ug_wicket-viewer_customisation_default-theme]]
+= Specifying a default theme
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 Isis Wicket viewer uses http://getbootstrap.com/[Bootstrap] styles and components (courtesy of the https://github.com/l0rdn1kk0n/wicket-bootstrap[Wicket Bootstrap] integration).
+
+Unless specified otherwise, the viewer uses the default bootstrap theme. However, this can be changed by overriding `init()` in the application's subclass of `IsisWicketApplication`. For example, to set the http://bootswatch.com/flatly/[bootswatch.com flatly] theme
+ as the default, use:
+
+[source,java]
+----
+@Override
+protected void init() {
+ super.init();
+ IBootstrapSettings settings = Bootstrap.getSettings();
+ settings.setThemeProvider(new BootswatchThemeProvider(BootswatchTheme.Flatly));
+}
+----
+
+If you have developed a custom Bootstrap theme (as described xref:ug.adoc#_ug_extending_wicket-viewer_custom-bootstrap-theme[here]) then this can also be specified using the https://github.com/l0rdn1kk0n/wicket-bootstrap/wiki/Themes[Wicket Bootstrap API].
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_customisation_tweaking-css-classes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_customisation_tweaking-css-classes.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_customisation_tweaking-css-classes.adoc
new file mode 100644
index 0000000..5ab6909
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_customisation_tweaking-css-classes.adoc
@@ -0,0 +1,109 @@
+[[_ug_wicket-viewer_customisation_tweaking-css-classes]]
+= Tweaking CSS 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 HTML generated by the Wicket viewer include plenty of CSS classes so that you can easily target the required elements as required. For example, you could use CSS to suppress the entity's icon alongside its title. This would be done using:
+
+[source,css]
+----
+.entityIconAndTitlePanel a img {
+ display: none;
+}
+----
+
+These customizations should generally be added to xref:ug.adoc#_ug_runtime_application-specific_application-css[`application.css]`; this file is included by default in every webpage served up by the Wicket viewer.
+
+
+
+== Targeting individual members
+
+For example, the `ToDoItem` object of the Isis addons example https://github.com/isisaddons/isis-app-todoapp/[todoapp] (not ASF) has a `notes` property. The HTML for this will be something like:
+
+[source,html]
+----
+<div>
+ <div class="property ToDoItem-notes">
+ <div class="multiLineStringPanel scalarNameAndValueComponentType">
+ <label for="id83" title="">
+ <span class="scalarName">Notes</span>
+ <span class="scalarValue">
+ <textarea
+ name="middleColumn:memberGroup:1:properties:4:property:scalarIfRegular:scalarValue"
+ disabled="disabled"
+ id="id83" rows="5" maxlength="400" size="125"
+ title="">
+ </textarea>
+ <span>
+ </span>
+ </span>
+ </label>
+ </div>
+ </div>
+</div>
+----
+
+The xref:ug.adoc#_ug_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:
+
+[source,css]
+----
+div.ToDoItem-notes span.scalarValue {
+ display: none;
+}
+----
+
+You can use a similar approach for collections and actions.
+
+
+
+
+== Targeting members through a custom CSS style
+
+The above technique works well if you know the class member to target, but you might instead want to apply a custom style to a set of members. For this, you can use the `@CssClass`.
+
+For example, in the `ToDoItem` class the following annotation (indicating that this is a key, important, property) :
+
+[source,java]
+----
+@PropertyLayout(cssClass="x-myapp-highlight")
+public LocalDate getDueBy() {
+ return dueBy;
+}
+----
+
+would generate the HTML:
+
+[source,html]
+----
+<div>
+ <div class="property ToDoItem-dueBy x-myapp-highlight">
+ ...
+ </div>
+</div>
+----
+
+This can then be targeted, for example using:
+
+[source,css]
+----
+div.x-myapp-highlight span.scalarName {
+ color: red;
+}
+----
+
+Note also that instead of using `@PropertyLayout(cssClass=...)` annotation, you can also specify the CSS style using a xref:rg.adoc#_rg_object-layout_dynamic[dynamic layout] JSON file:
+
+[source,javascript]
+----
+"dueBy": {
+ "propertyLayout": {
+ "cssClass": "x-myapp-important"
+ }
+},
+----
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_customisation_using-different-css-file.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_customisation_using-different-css-file.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_customisation_using-different-css-file.adoc
new file mode 100644
index 0000000..118d831
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_customisation_using-different-css-file.adoc
@@ -0,0 +1,36 @@
+[[_ug_wicket-viewer_customisation_using-different-css-file]]
+= Using a different CSS file
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 for some reason you wanted to name the CSS file differently (eg `stylesheets/myapp.css`), then adjust the Guice bindings (part of Isis' bootstrapping) in your custom subclass of `IsisWicketApplication`:
+
+[source,java]
+----
+public class MyAppApplication extends IsisWicketApplication {
+ @Override
+ protected Module newIsisWicketModule() {
+ final Module isisDefaults = super.newIsisWicketModule();
+ final Module myAppOverrides = new AbstractModule() {
+ @Override
+ protected void configure() {
+ ...
+ bind(String.class)
+ .annotatedWith(Names.named("applicationCss"))
+ .toInstance("stylesheets/myapp.css");
+ ...
+ }
+ };
+
+ return Modules.override(isisDefaults).with(myAppOverrides);
+ }
+}
+----
+
+As indicated above, this file is resolved relative to `src/main/webapp`.
+
+
+
[09/45] isis git commit: ISIS-1133: breaking out reference guide and
devenv guide;
moving appendices' release notes and migration notes to other docs;
improving the documentation page.
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-EmailService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-EmailService.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-EmailService.adoc
deleted file mode 100644
index 600b16d..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-EmailService.adoc
+++ /dev/null
@@ -1,98 +0,0 @@
-[[_ug_reference-services-api_manpage-EmailService]]
-= `EmailService`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `EmailService` provides the ability to send HTML emails, with attachments, to one or more recipients.
-
-Apache Isis provides a default implementation to send emails using an external SMTP provider. Note that this must be configured (using a number of configuration properties) before it can be used. The that sends email as an HTML message, using an external SMTP provider.
-
-
-
-== API & Implementation
-
-The API for the service is:
-
-[source,java]
-----
-public interface EmailService {
- @Programmatic
- boolean send( // <1>
- List<String> to, List<String> cc, List<String> bcc, // <2>
- String subject,
- String body, // <3>
- DataSource... attachments);
- @Programmatic
- boolean isConfigured(); // <4>
- }
-----
-<1> is the main API to send the email (and optional attachments). Will return `false` if failed to send
-<2> pass either `null` or `Collections.emptyList()` if not required
-<3> should be HTML text
-<4> indicates whether the implementation was configured and initialized correctly. If this returns `false` then any attempt to call `send(...)` will fail.
-
-As noted in the introduction, the core framework provides a default implementation (`EmailServiceDefault`) that sends email as an HTML message, using an external SMTP provider.
-
-
-
-== Configuration
-
-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:_ug_runtime_configuring-core[here]):
-
-* `isis.service.email.sender.hostname`
-* `isis.service.email.port`
-* `isis.service.email.tls.enabled`
-
-These configuration properties can be specified either in `isis.properties` or in an xref:_ug_deployment_externalized-configuration[external configuration file].
-
-If prototyping (that is, running the app using `org.apache.isis.WebServer`), the configuration properties can also be specified as system properties. For example, if you create a test email account on gmail, you can configure the service using:
-
-[source,ini]
-----
--Disis.service.email.sender.address=xxx@gmail.com -Disis.service.email.sender.password=yyy
-----
-
-where "xxx" is the gmail user account and "yyy" is its password
-
-
-
-
-== Alternative Implementations
-
-If you wish to write an alternative implementation, be aware that it should process the message body as HTML (as opposed to plain text or any other format).
-
-Also, note that (unlike most Isis domain services) the implementation is also instantiated and injected by Google Guice. This is because `EmailService` is used as part of the xref:_ug_wicket-viewer_features_user-registration[user registration] functionality and is used by Wicket pages that are accessed outside of the usual Isis runtime. This implies a couple of additional constraints:
-
-* first, implementation class should also be annotated with `@com.google.inject.Singleton`
-* second, there may not be any Isis session running. (If necessary, one can be created on the fly using `IsisContext.doInSession(...)`)
-
-To ensure that your alternative implementation takes the place of the default implementation, register it explicitly in `isis.properties`.
-
-
-
-== Registering the Services
-
-Assuming that the `configuration-and-annotation` services installer is configured:
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then Isis' core implementation of `EmailService` service is automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
-
-If you have written an alternative implementation, then register your implementation in `isis.properties` under the "isis.services" key and it will be used instead.
-
-
-
-== Related Services
-
-The email service is used by the xref:_ug_reference-services-spi_manpage-EmailNotificationService[`EmailNotificationService`] which is, in turn, used by xref:_ug_reference-services-spi_manpage-UserRegistrationService[`UserRegistrationService`].
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-EventBusService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-EventBusService.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-EventBusService.adoc
deleted file mode 100644
index e0731b2..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-EventBusService.adoc
+++ /dev/null
@@ -1,381 +0,0 @@
-[[_ug_reference-services-api_manpage-EventBusService]]
-= `EventBusService`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `EventBusService` allows domain objects to emit events to subscribing domain services using an in-memory event bus.
-
-The primary user of the service is the framework itself, which automatically emit events for xref:_ug_reference-annotations_manpage-Action_domainEvent[actions], xref:_ug_reference-annotations_manpage-Property_domainEvent[properties] and xref:_ug_reference-annotations_manpage-Collection_domainEvent[collections]. Multiple events are generated:
-
-* when an object member is to be viewed, an event is fired; subscribers can veto (meaning that the member is hidden)
-* when an object member is to be enabled, the same event instance is fired; subscribers can veto (meaning that the member is disabled, ie cannot be edited/invoked)
-* when an object member is being validated, then a new event instance is fired; subscribers can veto (meaning that the candidate values/action arguments are rejected)
-* when an object member is about to be changed, then the same event instance is fired; subscribers can perform pre-execution operations
-* when an object member has been changed, then the same event instance is fired; subscribers can perform post-execution operations
-
-If a subscriber throws an exception in the first three steps, then the interaction is vetoed. If a subscriber throws an exception in the last two steps, then the transaction is aborted. For more on this topic, see xref:_ug_reference-annotations_manpage-Action_domainEvent[`@Action#domainEvent()`], xref:_ug_reference-annotations_manpage-Property_domainEvent[`@Property#domainEvent()`] and xref:_ug_reference-annotations_manpage-Collection_domainEvent[`@Collection#domainEvent()`].
-
-It is also possible for domain objects to programmatically generate domain events. However the events are published, the primary use case is to decoupling interactions from one module/package/namespace and another.
-
-Two implementations are available, using either link:https://code.google.com/p/guava-libraries/[Guava]'s https://code.google.com/p/guava-libraries/wiki/EventBusExplained[`EventBus`], or alternatively using the link:http://www.axonframework.org/[AxonFramework]'s link:http://www.axonframework.org/docs/2.4/single.html#d5e1489[SimpleEventBus]. It is also possible to plug in a custom implementation.
-
-
-
-[[_ug_reference-services-api_manpage-EventBusService_api-and-implementation]]
-== API & Implementation
-
-The API defined by `EventBusService` is:
-
-[source,java]
-----
-public abstract class EventBusService {
- @Programmatic
- public void post(Object event) { ... } // <1>
- @Programmatic
- public void register(final Object domainService) { ... } // <2>
- @Programmatic
- public void unregister(final Object domainService) { ... } // <3>
-}
-----
-<1> posts the event onto event bus
-<2> allows domain services to register themselves. This should be done in their xref:_ug_reference-annotations_manpage-PostConstruct[`@PostConstruct`] initialization method (for both singleton and xref:_ug_reference-annotations_manpage-RequestScoped[`@RequestScoped`] domain services.
-<3> exists for symmetry, but need never be called (it is in fact deliberately a no-op).
-
-Isis provides a default implementation of the service, `o.a.i.objectstore.jdo.datanucleus.service.eventbus.EventBusServiceJdo`.
-
-
-
-
-
-== Registering Subscribers
-
-The `register()` method should be called in the xref:_ug_reference-annotations_manpage-PostConstruct[`@PostConstruct`] lifecycle method. It is valid and probably the least confusing to readers to also "unregister" in the xref:_ug_reference-annotations_manpage-PreDestroy[`@PreDestroy`] lifecycle method (though as noted xref:_ug_reference-services-api_manpage-EventBusService_api-and-implementation[above], unregistering is actually a no-op).
-
-For example:
-
-[source,java]
-----
-@DomainService(nature=NatureOfService.DOMAIN)
-public class MySubscribingDomainService {
- @PostConstruct
- public void postConstruct() {
- eventBusService.register(this);
- }
- @PreDestroy
- public void preDestroy() {
- eventBusService.unregister(this);
- }
- ...
- @javax.inject.Inject
- EventBusService eventBusService;
-}
-----
-
-This works for both singleton (application-scoped) and also xref:_ug_reference-annotations_manpage-RequestScoped[`@RequestScoped`] domain services.
-
-
-
-
-
-== Annotating Members
-
-As discussed in the introduction, the framework will automatically emit domain events for all of the object members (actions, properties or collections) of an object whenever that object is rendered or (more generally) interacted with.
-
-For example:
-
-[source,java]
-----
-public class Customer {
- @Action
- public Customer placeOrder(Product product, @ParameterLayout(named="Quantity") int qty) { ... }
- ...
-}
-----
-
-will propagate an instance of the default `o.a.i.applib.services.eventbus.ActionDomainEvent.Default` class. If using the Guava event bus this can be subscribed to using:
-
-[source,java]
-----
-@DomainService(nature=NatureOfService.DOMAIN)
-public class MySubscribingDomainService
- @Programmatic
- @com.google.common.eventbus.Subscribe
- public void on(ActionDomainEvent ev) { ... }
- ...
-}
-----
-
-or if using Axonframework, the subscriber uses a different annotation:
-
-[source,java]
-----
-@DomainService(nature=NatureOfService.DOMAIN)
-public class MySubscribingDomainService
- @Programmatic
- @org.axonframework.eventhandling.annotation.EventHandle
- public void on(ActionDomainEvent ev) { ... }
- ...
-}
-----
-
-More commonly though you will probably want to emit domain events of a specific subtype. As a slightly more interesting example, suppose in a library domain that a `LibraryMember` wants to leave the library. A letter should be sent out detailing any books that they still have out on loan:
-
-In the `LibraryMember` class, we publish the event by way of an annotation:
-
-[source,java]
-----
-public class LibraryMember {
- @Action(domainEvent=LibraryMemberLeaveEvent.class) // <1>
- public void leave() { ... }
- ...
-}
-----
-<1> `LibraryMemberLeaveEvent` is a subclass of `o.a.i.applib.eventbus.ActionDomainEvent`. The topic of subclassing is discussed in more detail xref:_ug_reference-services-api_manpage-EventBusService_event-hierarchy[below].
-
-Meanwhile, in the `BookRepository` domain service, we subscribe to the event and act upon it. For example:
-
-[source,java]
-----
-public class BookRepository {
- @Programmatic
- @com.google.common.eventbus.Subscribe
- public void onLibraryMemberLeaving(LibraryMemberLeaveEvent e) {
- LibraryMember lm = e.getLibraryMember();
- List<Book> lentBooks = findBooksOnLoanFor(lm);
- if(!lentBooks.isEmpty()) {
- sendLetter(lm, lentBooks);
- }
- }
- ...
-}
-----
-
-This design allows the `libraryMember` module to be decoupled from the `book` module.
-
-
-
-[[_ug_reference-services-api_manpage-EventBusService_event-hierarchy]]
-== Event hierarchy
-
-By creating domain event subtypes we can be more semantically precise and in turn providesmore flexibility for subscribers: they can choose whether to be broadly applicable (by subscribing to a superclass) or to be tightly focussed (by subscribing to a subclass).
-
-We recommend that you define event classes at (up to) four scopes:
-
-* at the top "global" scope is the Isis-defined `o.a.i.applib.event.ActionDomainEvent`
-* for the "module" scope, create a static class to represent the module itself, and creating nested classes within
-* for each "class" scope, create a nested static event class in the domain object's class for all of the domain object's actions
-* for each "action" scope, create a nested static event class for that action, inheriting from the "domain object" class.
-
-To put all that into code; at the module level we can define:
-
-[source,java]
-----
-package com.mycompany.modules.libmem;
-...
-public static class LibMemModule {
- private LibMemModule() {}
- public abstract static class ActionDomainEvent<S>
- extends org.apache.isis.applib.event.ActionDomainEvent<S> {
- private static final long serialVersionUID = 1L;
- public ActionDomainEvent(
- final S source,
- final Identifier identifier,
- final Object... arguments) {
- super(source, identifier, arguments);
- }
- }
- ... // <1>
-}
-----
-<1> similar events for properties and collections should also be defined
-
-For the class-level we can define:
-
-[source,java]
-----
-public static class LibraryMember {
- public abstract static class ActionDomainEvent extends LibMemModule.ActionDomainEvent<LibraryMember> {
- private static final long serialVersionUID = 1L;
- public ActionDomainEvent(
- final LibraryMember source,
- final Identifier identifier,
- final Object... arguments) {
- super(source, identifier, arguments);
- }
- }
- ... // <1>
-}
-----
-<1> similar events for properties and collections should also be defined
-
-and finally at the action level we can define:
-
-[source,java]
-----
-public class LibraryMember {
- ...
- public static class LeaveEvent extends LibraryMember.ActionDomainEvent {
- private static final long serialVersionUID = 1L;
- public PlaceOrderEvent(
- final Customer source,
- final Identifier identifier,
- final Object... arguments) {
- super(source, identifier, arguments);
- }
- }
- @Action(domainEvent=LeaveEvent.class)
- public void leave() { ... }
- ...
-}
-----
-
-The subscriber can subscribe either to the general superclass (as before), or to any of the classes in the hierarchy.
-
-
-
-
-
-== Programmatic posting
-
-To programmatically post an event, simply call `#post()`.
-
-The `LibraryMember` example described above could for example be rewritten into:
-
-[source,java]
-----
-public class LibraryMember {
- ...
- public void leave() {
- ...
- eventBusService.post(new LibraryMember.LeaveEvent(...)); // <1>
- }
- ...
-}
-----
-<1> `LibraryMember.LeaveEvent` could be _any_ class, not just a subclass of `o.a.i.applib.event.ActionDomainEvent`.
-
-In practice we suspect there will be few cases where the programmatic approach is required rather than the declarative approach afforded by xref:_ug_reference-annotations_manpage-Action_domainEvent[`@Action#domainEvent()`] et al.
-
-
-
-== Using `WrapperFactory`
-
-An alternative way to cause events to be posted is through the xref:_ug_reference-services-api_manpage-WrapperFactory[`WrapperFactory`]. This is useful when you wish to enforce a (lack-of-) trust boundary between the caller and the callee.
-
-For example, suppose that `Customer#placeOrder(...)` emits a `PlaceOrderEvent`, which is subscribed to by a `ReserveStockSubscriber`. This subscriber in turn calls `StockManagementService#reserveStock(...)`. Any business rules on `#reserveStock(...)` should be enforced.
-
-In the `ReserveStockSubscriber`, we therefore use the `WrapperFactory`:
-
-[source,java]
-----
-@DomainService(nature=NatureOfService.DOMAIN)
-public class ReserveStockSubscriber {
- @Programmatic
- @Subscribe
- public void on(Customer.PlaceOrderEvent ev) {
- wrapperFactory.wrap(stockManagementService)
- .reserveStock(ev.getProduct(), ev.getQuantity());
- }
- ...
- @Inject
- StockManagementService stockManagementService;
- @Inject
- WrapperFactory wrapperFactory;
-}
-----
-
-
-== Implementation SPI
-
-The implementation of `EventBusService` provided by 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. Which is used is specified through configuration property (described xref:_ug_reference-services-api_manpage-EventBusService_Configuration[below]).
-
-[NOTE]
-.Guava vs Axon, which to use?
-====
-Guava actually queues up events; they are not guaranteed to be dispatched immediately. This generally is not problem, but can be for cases where the subscriber may in turn want to post its own events (using xref:_ug_reference-services-api_manpage-WrapperFactory[`WrapperFactory`]).
-
-The Axon `SimpleEventBus`-based implementation on the other hand is fully synchronous; events are dispatched as soon as they are posted. This works well in all scenarios (that we have tested).
-====
-
-
-It is also possible to use some other implementation.
-
-[source,java]
-----
-public interface EventBusImplementation {
- void register(Object domainService);
- void unregister(Object domainService);
- void post(Object event);
-}
-----
-
-As is probably obvious, the `EventBusService` just delegates down to these method calls when its own similarly named methods are called.
-
-If you do provide your own implementation of this SPI, be aware that your subscribers will need to use whatever convention is required (eg different annotations) such that the events are correctly routed through to your subscribers.
-
-
-
-[[_ug_reference-services-api_manpage-EventBusService_Configuration]]
-== Configuration
-
-The implementation of `EventBusService` provided by 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:_ug_runtime_configuring-core[configuration property] `isis.services.eventbus.implementation`:
-
-[source,ini]
-----
-isis.services.eventbus.implementation=guava
-----
-
-or
-
-[source,ini]
-----
-isis.services.eventbus.implementation=axon
-----
-
-If you have written your own implementation of the `EventBusServiceImplementation` SPI, then specify instead its fully-qualified class name:
-
-[source,ini]
-----
-isis.services.eventbus.implementation=com.mycompany.isis.MyEventBusServiceImplementation
-----
-
-
-
-In addition, there is one further configuration property, whether to allow "late registration":
-
-[source,ini]
-----
-isis.services.eventbus.allowLateRegistration=false
-----
-
-Late registration refers to the idea that a domain service can register itself with the `EventBusService` after events have been posted. Since domain services are set up at boot time, this almost certainly constitutes a bug in the code and so by default late registration is _not_ allowed. Setting the above property to `true` disables this check.
-
-
-
-
-
-== Registering the Services
-
-Assuming that the `configuration-and-annotation` services installer is configured:
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then Isis' core implementation of `EventBusService` service is automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
-
-
-
-
-
-== Related Services
-
-The `EventBusService` is intended for fine-grained publish/subscribe for object-to-object interactions within an 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).
-
-The xref:_ug_reference-services-spi_manpage-PublishingService[`PublishingService`] meanwhile is intended for coarse-grained publish/subscribe for system-to-system interactions, from Isis to some other system. Here the only events published are those that action invocations (for actions annotated with xref:_ug_reference-annotations_manpage-Action_publishing[`@Action#publishing()`]) and of changed objects (for objects annotated with xref:_ug_reference-annotations_manpage-DomainObject_publishing[`@DomainObject#publishing()`]).
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-GuiceBeanProvider.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-GuiceBeanProvider.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-GuiceBeanProvider.adoc
deleted file mode 100644
index d1f665e..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-GuiceBeanProvider.adoc
+++ /dev/null
@@ -1,90 +0,0 @@
-[[_ug_reference-services-api_manpage-GuiceBeanProvider]]
-= `GuiceBeanProvider`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `GuiceBeanProvider` domain service acts as a bridge between Isis' xref:_ug_wicket-viewer[Wicket viewer] internal bootstrapping using link:https://github.com/google/guice[Google Guice].
-
-This service operates at a very low-level, and you are unlikely to have a need for it. It is used internally by the framework, in the default implementation of the xref:_ug_reference-services-api_manpage-DeepLinkService[`DeepLinkService`].
-
-[NOTE]
-====
-Currently Isis uses a combination of Guice (within the Wicket viewer only) and a home-grown dependency injection framework. In future versions we intended to refactor the framework to use CDI throughout. At that time this service is likely to become redundant because we will allow any of the internal components of Isis to be injected into your domain object code.
-====
-
-
-== API & Implementation
-
-The API defined by this service is:
-
-[source,java]
-----
-public interface GuiceBeanProvider {
- @Programmatic
- <T> T lookup(Class<T> beanType);
- @Programmatic
- <T> T lookup(Class<T> beanType, final Annotation qualifier);
-}
-----
-
-The xref:_ug_wicket-viewer[Wicket viewer] this provides an implementation of this service.
-
-
-
-== Usage
-
-Using the xref:_ug_wicket-viewer[Wicket viewer] requires subclassing of `IsisWicketApplication`. In the subclass it is commonplace to override `newIsisWicketModule()`, for example:
-
-[source,java]
-----
-@Override
-protected Module newIsisWicketModule() {
- final Module isisDefaults = super.newIsisWicketModule();
- final Module overrides = new AbstractModule() {
- @Override
- protected void configure() {
- bind(String.class).annotatedWith(Names.named("applicationName"))
- .toInstance("ToDo App");
- bind(String.class).annotatedWith(Names.named("applicationCss"))
- .toInstance("css/application.css");
- bind(String.class).annotatedWith(Names.named("applicationJs"))
- .toInstance("scripts/application.js");
- ...
- }
- };
- return Modules.override(isisDefaults).with(overrides);
-}
-----
-
-This "module" is in fact a Guice module, and so the `GuiceBeanProvider` service can be used to lookup any of the components bound into it.
-
-For example:
-
-[source,java]
-----
-public class SomeDomainObject {
- private String lookupApplicationName() {
- return guiceBeanProvider.lookup(String.class, Names.named("applicationName"));
- }
- @Inject
- GuiceBeanProvider guiceBeanProvider;
-}
-----
-
-should return "ToDo App".
-
-
-
-== Registering the Services
-
-Assuming that the `configuration-and-annotation` services installer is configured:
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-and that the xref:_ug_wicket-viewer[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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-IsisJdoSupport.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-IsisJdoSupport.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-IsisJdoSupport.adoc
deleted file mode 100644
index 4cd4d99..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-IsisJdoSupport.adoc
+++ /dev/null
@@ -1,276 +0,0 @@
-[[_ug_reference-services-api_manpage-IsisJdoSupport]]
-= `IsisJdoSupport`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `IsisJdoSupport` service provides a number of general purpose methods for working with the JDO/DataNucleus objectstore. In general these act at a lower-level of abstraction than the APIs normally used (specifically, those of xref:_ug_reference-services-api_manpage-DomainObjectContainer[`DomainObjectContainer`]), but nevertheless deal with some of the most common use cases. For service also provides access to the underlying JDO `PersistenceManager` for full control.
-
-The following sections discuss the functionality provided by the service, broken out into categories.
-
-
-
-
-[[_ug_reference-services-api_manpage-IsisJdoSupport_executing-sql]]
-== Executing SQL
-
-You can use the `IsisJdoSupportService` to perform arbitrary SQL SELECTs or UPDATEs:
-
-[source,java]
-----
-public interface IsisJdoSupport {
- @Programmatic
- List<Map<String, Object>> executeSql(String sql);
- @Programmatic
- Integer executeUpdate(String sql);
- ...
-}
-----
-
-
-The `executeSql(...)` method allows arbitrary SQL `SELECT` queries to be submitted:
-
-[source,java]
-----
-List<Map<String, Object>> results = isisJdoSupport.executeSql("select * from custMgmt.customers");
-----
-
-The result set is automatically converted into a list of maps, where the map key is the column name.
-
-
-In a similar manner, the `executeUpdate(...)` allows arbitrary SQL ``UPDATE``s to be performed.
-
-[source,java]
-----
-int count = isisJdoSupport.executeUpdate("select count(*) from custMgmt.customers);
-----
-
-The returned value is the number of rows updated.
-
-[TIP]
-====
-As an alternative, consider using DataNucleus' link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/jdoql_typesafe.html[type-safe JDO query API], discussed xref:_ug_reference-services-api_manpage-IsisJdoSupport_type-safe-query-api[below].
-====
-
-
-
-
-[[_ug_reference-services-api_manpage-IsisJdoSupport_type-safe-jdoql-queries]]
-== Type-safe JDOQL Queries
-
-DataNucleus provides an link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/jdoql_typesafe.html[extension to JDO], so that JDOQL queries can be built up and executed using a set of type-safe classes.
-
-The types in question for type safe queries are not the domain entities, but rather are companion "Q..." query classes. These classes are generated dynamically by an link:https://www.jcp.org/en/jsr/detail?id=269[annotation processor] as a side-effect of compilation, one "Q..." class for each of the xref:_ug_reference-annotations_manpage-PersistenceCapable[`@PersistenceCapable`] domain entity in your application. For example, a `ToDoItem` domain entity will give rise to a `QToDoItem` query class. These "Q..." classes mirror the structure of domain entity, but expose properties that allow predicates to be built up for querying instances, as well as other functions in support of order by. group by and other clauses.
-
-[NOTE]
-====
-Most IDEs (including IntelliJ and Eclipse) enable annotation processing by default, as does Maven. The DataNucleus' link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/jdoql_typesafe.html[documentation] offers some guidance on confirming that APT is enabled.
-====
-
-The `IsisJdoSupport` service offers two methods at different levels of abstraction:
-
-[source,java]
-----
-public interface IsisJdoSupport {
- @Programmatic
- <T> List<T> executeQuery(final Class<T> cls, final BooleanExpression be);
- @Programmatic
- <T> TypesafeQuery<T> newTypesafeQuery(Class<T> cls);
- ...
-}
-----
-
-
-The `executeQuery(...)` method supports the common case of obtaining a set of objects that meet some criteria, filtered using the provided `BooleanExpression`. To avoid memory leaks, the returned list is cloned and the underlying query closed.
-
-For example, in the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] there is an implementation of `ToDoItemRepository` using type-safe queries. The following JDOQL:
-
-[source,sql]
-----
-SELECT
-FROM todoapp.dom.module.todoitem.ToDoItem
-WHERE atPath.indexOf(:atPath) == 0
- && complete == :complete")
-----
-
-can be expressed using type-safe queries as follows:
-
-[source,java]
-----
-public List<ToDoItem> findByAtPathAndCategory(final String atPath, final Category category) {
- final QToDoItem q = QToDoItem.candidate();
- return isisJdoSupport.executeQuery(ToDoItem.class,
- q.atPath.eq(atPath).and(
- q.category.eq(category)));
-}
-----
-
-[NOTE]
-====
-You can find the full example of the JDOQL equivalent in the xref:_ug_reference-services-api_manpage-DomainObjectContainer_generic-repository-api[`DomainObjectContainer`]
-====
-
-
-The `newTypesafeQuery(...)` method is a lower-level API that allows a type safe query to be instantiated for most sophisticated querying, eg using group by or order by clauses. See the
-DataNucleus link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/jdoql_typesafe.html[documentation] for full details of using this.
-
-One thing to be aware of is that after the query has been executed, it should be closed, using `query.closeAll()`. If calling `query.executeList()` we also recommend cloning the resultant list first. The following utility method does both of these tasks:
-
-[source,java]
-----
-private static <T> List<T> executeListAndClose(final TypesafeQuery<T> query) {
- final List<T> elements = query.executeList();
- final List<T> list = Lists.newArrayList(elements);
- query.closeAll();
- return list;
-}
-----
-
-
-
-[[_ug_reference-services-api_manpage-IsisJdoSupport_fixture-support]]
-== Fixture support
-
-When writing xref:_ug_testing_integ-test-support[integration tests] you'll usually need to tear down some/all mutable transactional data before each test. One way to do that is to use the `executeUpdate(...)` method described xref:_ug_reference-services-api_manpage-IsisJdoSupport_executing-sql[above].
-
-Alternatively, the `deleteAll(...)` method will let your test delete all instances of a class without resorting to SQL:
-
-[source,java]
-----
-public interface IsisJdoSupport {
- @Programmatic
- void deleteAll(Class<?>... pcClasses);
- ...
-}
-----
-
-For example:
-
-[source,java]
-----
-public class TearDownAll extends FixtureScriptAbstract {
- @Override
- protected void execute(final ExecutionContext ec) {
- isisJdoSupport.deleteAll(Order.class);
- isisJdoSupport.deleteAll(CustomerAddress.class);
- isisJdoSupport.deleteAll(Customer.class);
- }
- @Inject
- IsisJdoSupport isisJdoSupport;
-}
-----
-
-[NOTE]
-====
-It can occasionally be the case that Isis' internal adapter for the domain object is
-still in memory. JDO/DataNucleus seems to bump up the version of the object prior to its deletion,
-which under normal circumstances would cause Isis to throw a concurrency exception. Therefore
-to prevent this from happening (ie to _force_ the deletion of all instances), concurrency checking
-is temporarily disabled while this method is performed.
-====
-
-
-
-
-[[_ug_reference-services-api_manpage-IsisJdoSupport_reloading-entities]]
-== Reloading entities
-
-An http://www.datanucleus.org/products/datanucleus/jdo/orm/relationships.html[(intentional) limitation] of JDO/DataNucleus is that persisting a child entity (in a 1:n bidirectional relationship) does not cause the parent's collection to be updated.
-
-[source,java]
-----
-public interface IsisJdoSupport {
- @Programmatic
- <T> T refresh(T domainObject);
- @Programmatic
- void ensureLoaded(Collection<?> collectionOfDomainObjects);
- ...
-}
-----
-
-
-
-The `refresh(T domainObject)` method can be used to reload the parent object (or indeed any object). Under the covers it uses the JDO `PersistenceManager#refresh(...)` API.
-
-
-For example:
-
-[source,java]
-----
-@DomainService(nature=NatureOfService.VIEW_CONTRIBUTIONS_ONLY)
-public class OrderContributions {
- public Order newOrder(final Customer customer) {
- Order order = newTransientInstance(Order.class);
- order.setCustomer(customer);
- container.persist(customer);
- container.flush(); // <1>
- isisJdoSupport.refresh(customer); // <2>
- return order;
- }
- @Inject
- DomainObjectContainer container;
- @Inject
- IsisJdoSupport isisJdoSupport;
-}
-----
-<1> flush to database, ensuring that the database row corresponding to the `Order` exists in its `order` table.
-<2> reload the parent (customer) from the database, so that its collection of ``Order``s is accurate.
-
-
-[NOTE]
-====
-The particular example that led to this method being added was a 1:m bidirectional relationship,
-analogous to `Customer 1<-->* Order`. Persisting the child `Order` object did not cause
-the parent ``Customer``'s collection of orders to be updated. In fact, JDO does not make any
-such guarantee to do so. Options are therefore either to maintain the collection in code, or to
-refresh the parent.
-====
-
-
-The `ensureLoaded(...)` method allows a collection of domain objects to be loaded from the database in a single hit. This can be valuable as a performance optimization to avoid multiple roundtrips to the database. Under the covers it uses the `PersistenceManager#retrieveAll(...)` API.
-
-
-
-
-
-[[_ug_reference-services-api_manpage-IsisJdoSupport_jdo-persistencemanager]]
-== JDO `PersistenceManager`
-
-The functionality provided by `IsisJdoSupport` focus only on the most common use cases. If you require more flexibility than this, eg for dynamically constructed queries, then you can use the service to access the underlying JDO `PersistenceManager` API:
-
-[source,java]
-----
-public interface IsisJdoSupport {
- @Programmatic
- PersistenceManager getJdoPersistenceManager();
- ...
-}
-----
-
-For example:
-
-[source,java]
-----
-public List<Order> findOrders(...) {
- javax.jdo.PersistenceManager pm = isisJdoSupport.getPersistenceManager();
-
- // knock yourself out...
-
- return someListOfOrders;
-}
-----
-
-
-
-
-== Registering the Services
-
-Assuming that the `configuration-and-annotation` services installer is configured:
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then 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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-MementoService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-MementoService.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-MementoService.adoc
deleted file mode 100644
index 395c7fa..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-MementoService.adoc
+++ /dev/null
@@ -1,131 +0,0 @@
-[[_ug_reference-services-api_manpage-MementoService]]
-= `MementoService`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `MementoService` was originally introduced to simplify the implementation of xref:_ug_more-advanced_view-models[ViewModel]s which are required by the framework to return string representation of all of their backing state, moreover which is safe for use within a URL.
-
-However, it can also be used to create a memento of arbitrary objects. Indeed, it is used internally by the core implementation of xref:_ug_reference-services-api_manpage-BackgroundService[`BackgroundService`] to capture the state of action invocations so that they can be executed by a background process.
-
-
-
-
-== API & Implementation
-
-The API defined by `MementoService` is:
-
-[source,java]
-----
-public interface MementoService {
- public static interface Memento {
- @Programmatic
- public Memento set(String name, Object value);
- @Programmatic
- public <T> T get(String name, Class<T> cls);
- @Programmatic
- public String asString();
- public Set<String> keySet();
- }
- @Programmatic
- public Memento create();
- @Programmatic
- public Memento parse(final String str);
- @Programmatic
- public boolean canSet(Object input);
-}
-----
-
-The core framework provides a default implementation of this API, namely `o.a.i.core.runtime.services.memento.MementoServiceDefault`. The string returned (from `Memento#asString()`) is a base-64 URL encoded representation of the underlying format (an XML string).
-
-[NOTE]
-====
-In fact, the `MementoServiceDefault` implementation does provide a mechanism to disable the URL encoding, but this is not part of the `MementoService` public API. Note also that the encoding method is not pluggable.
-
-However, you are of course free to write some other implementation of `MementoService`, perhaps based on `MementoServiceDefault` code if you wish.
-====
-
-The types of objects that are supported by the `MementoService` are implementation-specific, but would typically include all the usual value types as well as Isis' `Bookmark` class (to represent references to arbitrary entities). Nulls can also be set.
-
-In the case of the default implementation provided by the core framework, the types supported are:
-
-* `java.lang.String`
-* `java.lang.Boolean`, `boolean`
-* `java.lang.Byte`, `byte`
-* `java.lang.Short`, `short`
-* `java.lang.Integer`, `int`
-* `java.lang.Long`, `long`
-* `java.lang.Float`, `float`
-* `java.lang.Double`, `double`
-* `java.lang.Character`, `char`
-* `java.math.BigDecimal`
-* `java.math.BigInteger`
-* `org.joda.time.LocalDate`
-* `org.apache.isis.applib.services.bookmark.Bookmark`
-
-If using another implementation, the `canSet(...)` method can be used to check if the candidate object's type is supported.
-
-
-
-== Usage
-
-As noted in the introduction, a common use case for this service is in the implementation of the xref:_ug_reference-classes_super_manpage-AbstractViewModel[`ViewModel`] interface.
-
-[TIP]
-====
-Rather than implementing `ViewModel`, it's usually easier to annotate your view models with xref:_ug_reference-annotations_manpage-ViewModel[`@ViewModel`] (or equivalently xref:_ug_reference-annotations_manpage-DomainObject_nature[`@DomainObject#nature=EXTERNAL_ENTITY`] or xref:_ug_reference-annotations_manpage-DomainObject_nature[`@DomainObject#nature=INMEMORY_ENTITY`].
-====
-
-For example, suppose you were implementing a view model that represents an external entity in a SOAP web service. To access this service the view model needs to store (say) the hostname, port number and an id to the object.
-
-Using an injected `MementoService` the view model can roundtrip to and from this string, thus implementing the `ViewModel` API:
-
-[source,java]
-----
-public class ExternalEntity implements ViewModel {
- private String hostname;
- private int port;
- private String id;
- public String viewModelMemento() { // <1>
- return mementoService.create()
- .set("hostname", hostname)
- .set("port", port)
- .set("id", id)
- .asString();
- }
- public void viewModelInit(String mementoStr) { // <2>
- Memento memento = mementoService.parse(mementoStr);
- hostname = memento.get("hostname", String.class);
- port = memento.get("port", int.class);
- id = memento.get("id", String.class);
- ...
- @Inject
- MementoService mementoService;
-}
-----
-<1> part of the `ViewModel` API
-<2> part of the `ViewModel` API
-
-
-
-
-
-== Related Services
-
-The memento service is used by the xref:_ug_reference-services-api_manpage-CommandContext[`CommandContext`] service and also xref:_ug_reference-services-spi_manpage-BackgroundCommandService[`BackgroundCommandService`]. These both use a memento to capture a representation of an action invocation.
-
-
-
-
-== Registering the Service
-
-Assuming that the `configuration-and-annotation` services installer is configured:
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then 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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-MetamodelService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-MetamodelService.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-MetamodelService.adoc
deleted file mode 100644
index 91aa7aa..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-MetamodelService.adoc
+++ /dev/null
@@ -1,42 +0,0 @@
-[[_ug_reference-services-api_manpage-MetamodelService]]
-= `MetamodelService`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `MetaModelService` provides access (albeit currently extremely limited) to aspects of Isis' internal metamodel.
-
-Currently this is limited to looking up the object type (as specified in xref:_ug_reference-annotations_manpage-DomainObject_objectType[`@DomainObject#objectType()`] and equivalent mechanisms, and as used in xref:_ug_reference-services-api_manpage-BookmarkService[`Bookmark`]s and elsewhere) from an object's class, and vice versa. In the future we expect other aspects of the metamodel to also be formally surfaced through this API.
-
-
-== API & Implementation
-
-The API defined by the service is:
-
-[source,java]
-----
-public interface MetaModelService {
- @Programmatic
- Class<?> fromObjectType(final String objectType); // <1>
- @Programmatic
- String toObjectType(final Class<?> domainType); // <2>
-}
-----
-<1> reverse lookup of a domain class' object type
-<2> lookup of a domain class' object type
-
-
-
-
-== Registering the Service
-
-Assuming that the `configuration-and-annotation` services installer is configured:
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then 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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-QueryResultsCache.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-QueryResultsCache.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-QueryResultsCache.adoc
deleted file mode 100644
index fbdc62e..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-QueryResultsCache.adoc
+++ /dev/null
@@ -1,127 +0,0 @@
-[[_ug_reference-services-api_manpage-QueryResultsCache]]
-= `QueryResultsCache`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 purpose of the `QueryResultsCache` is to improve response times to the user, by providing a short-term (link:../../more-advanced-topics/how-to-09-020-How-to-write-a-typical-domain-service.html[request-scoped]) cache of the value of some (safe or idempotent) method call. This will typically be as the result of running a query, but could be any expensive operation.
-
-Caching such values is useful for code that loops "naively" through a bunch of stuff, performing an expensive operation each time. If the data is such that the same expensive operation is made many times, then the query cache is a perfect fit.
-
-
-[NOTE]
-====
-This service was inspired by similar functionality that exists in relational databases, for example Sybase's http://infocenter.sybase.com/help/index.jsp?topic=/com.sybase.dc20023_1251/html/optimizer/X43480.htm[subquery results cache] and Oracle's http://www.dba-oracle.com/oracle11g/oracle_11g_result_cache_sql_hint.htm[result_cache] hint.
-====
-
-
-
-== API & Implementation
-
-The API defined by `QueryResultsCache` is:
-
-[source,java]
-----
-@RequestScoped
-public class QueryResultsCache {
- public static class Key {
- public Key(Class<?> callingClass, String methodName, Object... keys) {...}
- public Class<?> getCallingClass() { ... }
- public String getMethodName() { ... }
- public Object[] getKeys() { ... }
- }
- public static class Value<T> {
- public Value(T result) { ... }
- private T result;
- public T getResult() {
- return result;
- }
- }
- @Programmatic
- public <T> T execute(
- final Callable<T> callable,
- final Class<?> callingClass, final String methodName, final Object... keys) { ... }
- @Programmatic
- public <T> T execute(final Callable<T> callable, final Key cacheKey) { ... }
- @Programmatic
- public <T> Value<T> get(
- final Class<?> callingClass, final String methodName, final Object... keys) { ... }
- @Programmatic
- public <T> Value<T> get(final Key cacheKey) { ... }
- @Programmatic
- public <T> void put(final Key cacheKey, final T result) { ... }
-}
-----
-
-This class (`o.a.i.applib.services.queryresultscache.QueryResultsCache`) is also the implementation.
-
-
-
-
-== Usage
-
-Suppose that there's a `TaxService` that calculates tax on `Taxable` items, with respect to some `TaxType`, and for a given `LocalDate`. To calculate tax it must run a database query and then perform some additional calculations.
-
-Our original implementation is:
-
-[source,java]
-----
-@DomainService
-public class TaxService {
- public BigDecimal calculateTax(
- final Taxable t, final TaxType tt, final LocalDate d) {
- // query against DB using t, tt, d
- // further expensive calculations
- }
-}
-----
-
-Suppose now that this service is called in a loop, for example iterating over a bunch of orders, where several of those orders are for the same taxable products, say. In this case the result of the calculation would always be the same for any given product.
-
-We can therefore refactor the method to use the query cache as follows:
-
-[source,java]
-----
-public class TaxService {
- public BigDecimal calculateTax(
- final Taxable t, final TaxType tt, final LocalDate d) {
- return queryResultsCache.execute(
- new Callable<BigDecimal>(){ // <1>
- public BigDecimal call() throws Exception {
- // query against DB using t, tt, d
- // further expensive calculations
- }
- },
- TaxService.class, // <2>
- "calculateTax",
- t, tt, d);
- }
-}
-----
-<1> the `Callable` is the original code
-<2> the remaining parameters in essence uniquely identify the method call.
-
-This refactoring will be worthwhile provided that enough of the orders being processed reference the same taxable products. If however every order is for a different product, then no benefit will be gained from the refactoring.
-
-
-
-
-== Registering the Service
-
-Assuming that the `configuration-and-annotation` services installer is configured:
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then Isis' core implementation of `QueryResultsCache` service is automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
-
-
-
-
-== Related Services
-
-The xref:_ug_reference-services-api_manpage-Scratchpad[`Scratchpad`] service is also intended for actions that are called many times, allowing arbitrary information to be shared between them. Those methods could be called from some outer loop in domain code, or by the framework itself if the action invoked has the xref:_ug_reference-annotations_manpage-Action_invokeOn[`@Action#invokeOn()`] annotation attribute set to `OBJECT_AND_COLLECTION` or `COLLECTION_ONLY`.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-ScratchPad.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-ScratchPad.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-ScratchPad.adoc
deleted file mode 100644
index 6eb08cd..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-ScratchPad.adoc
+++ /dev/null
@@ -1,127 +0,0 @@
-[[_ug_reference-services-api_manpage-Scratchpad]]
-= `Scratchpad`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `Scratchpad` service is a link:../../more-advanced-topics/how-to-09-020-How-to-write-a-typical-domain-service.html[request-scoped] service to allow objects to exchange information even if they do not directly call each other.
-
-
-
-
-== API & Implementation
-
-The API of `Scratchpad` service is:
-
-[source,java]
-----
-@RequestScoped
-public class Scratchpad {
- @Programmatic
- public Object get(Object key) { ... }
- @Programmatic
- public void put(Object key, Object value) { ... }
- @Programmatic
- public void clear() { ... }
-}
-----
-
-This class (`o.a.i.applib.services.scratchpad.Scratchpad`) is also the implementation. And, as you can see, the service is just a request-scoped wrapper around a `java.util.Map`.
-
-
-
-
-
-== Usage
-
-The most common use-case is for xref:_ug_reference-annotations_manpage-Action_invokeOn[bulk] actions that act upon multiple objects in a list. The (same) `Scratchpad` service is injected into each of these objects, and so they can use pass information.
-
-For example, the Isis addons example https://github.com/isisaddons/isis-app-todoapp/[todoapp] (not ASF) demonstrates how the `Scratchpad` service can be used to calculate the total cost of the selected `ToDoItem`s:
-
-
-[source,java]
-----
-@ActionSemantics(Of.SAFE)
-@Bulk(AppliesTo.BULK_ONLY)
-public BigDecimal totalCost() {
- BigDecimal total = (BigDecimal) scratchpad.get("runningTotal");
- if(getCost() != null) {
- total = total != null ? total.add(getCost()) : getCost();
- scratchpad.put("runningTotal", total);
- }
- return total.setScale(2);
-}
-@Inject
-Scratchpad scratchpad;
-----
-
-A more complex example could use a xref:_ug_more-advanced_view-models[view model] to enable bulk updates to a set of objects. The view model's job is to gather track of the items to be updated:
-
-[source,java]
-----
-public class ToDoItemUpdateBulkUpdate extends AbstractViewModel {
- private List<ToDoItem> _items = ...;
- public ToDoItemBulkUpdate add(ToDoItem item) {
- _items.add(item);
- return this;
- }
- ... // <1>
-}
-----
-<1> not shown - the implementation of `ViewModel` for converting the list of `_items` into a string.
-
-The bulk action in the objects simply adds the selected item to the view model:
-
-[source,java]
-----
-@Action(
- invokeOn=InvokeOn.COLLECTIONS_ONLY
- semantics=SemanticsOf.SAFE
-)
-public ToDoItemBulkUpdate bulkUpdate() {
- return lookupBulkUpdateViewModel().add(this);
-}
-private ToDoItemBulkUpdate lookupBulkUpdateViewModel() {
- ToDoItemBulkUpdate bulkUpdate =
- (ToDoItemBulkUpdate) scratchpad.get("bulkUpdateViewModel"); // <1>
- if(bulkUpdate == null) {
- bulkUpdate = container.injectServicesInto(new ToDoItemBulkUpdate());
- scratchpad.put("bulkUpdateViewModel", bulkUpdate); // <2>
- }
- return bulkUpdate;
-}
-@Inject
-Scratchpad scratchpad;
-----
-<1> look for the `ToDoItemBulkUpdate` in the scratchpad...
-<2> ... and add one if there isn't one (ie for the first object returned).
-
-If using the xref:_ug_wicket-viewer[Wicket viewer], the `ToDoItemBulkUpdate` view model returned from the last action invoked will be displayed. Thereafter this view model can be used to perform a bulk update of the "enlisted" items.
-
-
-
-
-
-== Registering the Service
-
-Assuming that the `configuration-and-annotation` services installer is configured:
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then Isis' core implementation of `Scratchpad` service is automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
-
-
-
-
-
-
-== Related Services
-
-The xref:_ug_reference-services-api_manpage-ActionInteractionContext[`ActionInteractionContext`] service allows xref:_ug_reference-annotations_manpage-Action_invokeOn[bulk actions] to co-ordinate with each other.
-
-The xref:_ug_reference-services-api_manpage-QueryResultsCache[`QueryResultsCache`] is useful for caching the results of expensive method calls.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-SudoService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-SudoService.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-SudoService.adoc
deleted file mode 100644
index aece2fc..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-SudoService.adoc
+++ /dev/null
@@ -1,68 +0,0 @@
-[[_ug_reference-services-api_manpage-SudoService]]
-= `SudoService`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `SudoService` allows the current user reported by the `DomainObjectContainer` to be temporarily changed to some
-other user. This is useful both for xref:_ug_testing_integ-test-support[integration testing] (eg if testing a workflow system whereby objects are moved from one user to another) and while running xref:_ug_testing_fixture-scripts[fixture scripts] (eg setting up objects that would normally require several users to have acted upon the objects).
-
-
-== API & Implementation
-
-The API provided by the service is:
-
-[source,java]
-----
-public interface SudoService {
- @Programmatic
- void sudo(String username, final Runnable runnable);
- @Programmatic
- <T> T sudo(String username, final Callable<T> callable);
- @Programmatic
- void sudo(String username, List<String> roles, final Runnable runnable);
- @Programmatic
- <T> T sudo(String username, List<String> roles, final Callable<T> callable);
-}
-----
-
-which will run the provided block of code (a `Runnable` or a `Callable`) in a way such that calls to `DomainObjectContainer#getUser()` will return the specified user (and roles, if specified)
-
-The core framework provides a default implementation of this service (`o.a.i.core.runtime.services.sudo.SudoServiceDefault`)
-
-
-
-
-== Usage
-
-A good example can be found in the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] which uses the `SudoService` in a fixture script to set up `ToDoItem` objects:
-
-[source,java]
-----
-protected void execute(final ExecutionContext ec) {
- ...
- sudoService.sudo(getUsername(),
- new Runnable() {
- @Override
- public void run() {
- wrap(toDoItem).completed();
- }
- });
- ...
-}
-----
-
-
-
-== Registering the Service
-
-Assuming that the `configuration-and-annotation` services installer is configured:
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then 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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-WrapperFactory.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-WrapperFactory.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-WrapperFactory.adoc
deleted file mode 100644
index 1bb96f1..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-WrapperFactory.adoc
+++ /dev/null
@@ -1,162 +0,0 @@
-[[_ug_reference-services-api_manpage-WrapperFactory]]
-= `WrapperFactory`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `WrapperFactory` provides the ability to enforce business rules for programmatic interactions between domain objects. If there is a (lack-of-) trust boundary between the caller and callee -- eg if they reside in different modules -- then the wrapper factory is a useful mechanism to ensure that any business constraints defined by te callee are honoured.
-
-For example, if the calling object attempts to modify an unmodifiable property on the target object, then an exception will be thrown. Said another way: interactions are performed "as if" they are through the viewer.
-
-[NOTE]
-====
-For a discussion of the use of the `WrapperFactory` within integration tests (the primary or at least original use case for this service) can be found xref:_ug_testing_integ-test-support_wrapper-factory[here]
-====
-
-This capability goes beyond enforcing the (imperative) constraints within the `hideXxx()`, `disableXxx()` and `validateXxx()` supporting methods; it also enforces (declarative) constraints such as those represented by annotations, eg `@MaxLength` or `@Regex`.
-
-This capability is frequently used within xref:_ug_testing_integ-test-support[integration tests], but can also be used in production code. (There are analogies that can be drawn here with the way that JEE beans can interact through an EJB local interface).
-
-
-
-
-== API
-
-The API provided by the service is:
-
-[source,java]
-----
-public interface WrapperFactory {
- @Programmatic
- <T> T wrap(T domainObject); // <1>
- @Programmatic
- <T> T unwrap(T possibleWrappedDomainObject); // <2>
- @Programmatic
- <T> boolean isWrapper(T possibleWrappedDomainObject); // <3>
-
- public static enum ExecutionMode { // <4>
- EXECUTE(true,true),
- SKIP_RULES(false, true), // <5>
- NO_EXECUTE(true, false); // <6>
- }
- @Programmatic
- <T> T wrap(T domainObject, ExecutionMode mode); // <7>
- @Programmatic
- <T> T wrapNoExecute(T domainObject); // <8>
- @Programmatic
- <T> T wrapSkipRules(T domainObject); // <9>
- ...
- }
-----
-<1> wraps the underlying domain object. If it is already wrapped, returns the object back unchanged.
-<2> Obtains the underlying domain object, if wrapped. If the object is not wrapped, returns back unchanged.
-<3> whether the supplied object has been wrapped.
-<4> enumerates how the wrapper interacts with the underlying domain object.
-<5> validate all business rules and then execute.
-<6> skip all business rules and then execute (including creating xref:_ug_reference-annotations_manpage-Action_command[command]s and firing pre- and post-execute xref:_ug_reference-annotations_manpage-Action_domainEvent[domain event]s).
-<7> validate all business rules (including those from xref:_ug_reference-annotations_manpage-Action_domainEvent[domain event]s) but do not execute.
-<8> convenience method to invoke `wrap(...)` with `ExecuteMode#NO_EXECUTE` (make this feature more discoverable)
-<9> convenience method to invoke `wrap(...)` with `ExecuteMode#SKIP_RULES` (make this feature more discoverable)
-
-
-
-The service works by returning a "wrapper" around a supplied domain object (a link:http://www.javassist.org[javassist] proxy), and it is this wrapper that ensures that the hide/disable/validate rules implies by the Isis programming model are enforced. The wrapper can be interacted with as follows:
-
-* a `get...()` method for properties or collections
-* a `set...()` method for properties
-* an `addTo...()` or `removeFrom...()` method for collections
-* any action
-
-Calling any of the above methods may result in a (subclass of) `InteractionException` if the object disallows it. For example, if a property is annotated with `@Hidden` then a `HiddenException` will be thrown. Similarly if an action has a `validateXxx()` method and the supplied arguments are invalid then an `InvalidException` will be thrown.
-
-In addition, the following methods may also be called:
-
-* the xref:_ug_reference-methods_reserved_manpage-title[`title()`] and `toString()` methods
-* any xref:_ug_reference-methods_prefixes_manpage-default[`default...()`], xref:_ug_reference-methods_prefixes_manpage-choices[`choices...()`] or xref:_ug_reference-methods_prefixes_manpage-autoComplete[`autoComplete...()`] methods
-
-An exception will be thrown if any other methods are thrown.
-
-
-
-
-
-== Usage
-
-The caller will typically obtain the target object (eg from some repository) and then use the injected `WrapperFactory` to wrap it before interacting with it.
-
-For example:
-
-[source,java]
-----
-public class CustomerAgent {
- @Action
- public void refundOrder(final Order order) {
- final Order wrappedOrder = wrapperFactory.wrap(order);
- try {
- wrappedOrder.refund();
- } catch(InteractionException ex) { // <1>
- container.raiseError(ex.getMessage()); // <2>
- return;
- }
- }
- ...
- @Inject
- WrapperFactory wrapperFactory;
- @Inject
- DomainObjectContainer container;
-}
-----
-<1> if any constraints on the `Order`'s `refund()` action would be violated, then ...
-<2> ... these will be trapped and raised to the user as a warning.
-
-[NOTE]
-====
-It ought to be possible to implement an xref:_ug_reference-services-spi_manpage-ExceptionRecognizer[`ExceptionRecognizer`]s that would allow the above boilerplate to be removed. This recognizer service would recognize the `InteractionException` and convert to a suitable message.
-
-At the time of writing Isis does not provide an out-of-the-box implementation of such an `ExceptionRecognizer`; but it should be simple enough to write one…
-====
-
-
-
-
-== Listener API
-
-The `WrapperFactory` also provides a listener API to allow other services to listen in on interactions.
-
-[source,java]
-----
-public interface WrapperFactory {
- ...
- @Programmatic
- List<InteractionListener> getListeners(); // <1>
- @Programmatic
- public boolean addInteractionListener(InteractionListener listener); // <2>
- @Programmatic
- public boolean removeInteractionListener(InteractionListener listener); // <3>
- @Programmatic
- public void notifyListeners(InteractionEvent ev); // <4>
-}
-----
-<1> all ``InteractionListener``s that have been registered.
-<2> registers an `InteractionListener`, to be notified of interactions on all wrappers. The listener will be notified of interactions even on wrappers created before the listener was installed. (From an implementation perspective this is because the wrappers delegate back to the container to fire the events).
-<3> remove an `InteractionListener`, to no longer be notified of interactions on wrappers.
-<4> used by the framework itself
-
-The original intent of this API was to enable test transcripts to be captured (in a BDD-like fashion) from integration tests. No such feature has yet been implemented however. Also, the capabilities have by and large been superceded by Isis' support for domain events. We may therefore deprecate this API in the future.
-
-
-
-
-== Registering the Service
-
-Assuming that the `configuration-and-annotation` services installer is configured:
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then 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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-XmlSnapshotService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-XmlSnapshotService.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-XmlSnapshotService.adoc
deleted file mode 100644
index 13a6de0..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-XmlSnapshotService.adoc
+++ /dev/null
@@ -1,214 +0,0 @@
-[[_ug_reference-services-api_manpage-XmlSnapshotService]]
-= `XmlSnapshotService`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `XmlSnapshotService` provides the capability to generate XML snapshots (and if required corresponding XSD schemas) based on graphs of domain objects.
-
-Typical use cases include creating mementos for business-focused auditing, such that a report could be generated as to which end-user performed a business action (perhaps for legal reasons). For one system that we know of, a digest of this snapshot of data is signed with the public encryption key so as to enforce non-repudiation.
-
-Another use case is to grab raw data such that it could be merged into a report template or communication.
-
-The service offers a basic API to create a snapshot of a single object, and an more flexible API that allows the size of the graph to be customized.
-
-The core framework provides an implementation of this service (`o.a.i.core.runtime.services.xmlsnapshot.XmlSnapshotServiceDefault`).
-
-
-
-== Standard API
-
-The (basic) API of `XmlSnapshotService` is:
-
-[source]
-----
-public interface XmlSnapshotService {
- public interface Snapshot {
- Document getXmlDocument();
- Document getXsdDocument();
- String getXmlDocumentAsString();
- String getXsdDocumentAsString();
- }
- @Programmatic
- public XmlSnapshotService.Snapshot snapshotFor(Object domainObject);
- ...
-}
-----
-
-
-The most straight-forward usage of this service is simply:
-
-[source,java]
-----
-XmlSnapshot snapshot = xmlsnapshotService.snapshotFor(customer);
-Element customerAsXml = snapshot.getXmlElement();
-----
-
-This will return an XML (document) element that contains the names and values of each of the customer's value properties, along with the titles of reference properties, and also the number of items in collections.
-
-
-As well as obtaining the XML snapshot, it is also possible to obtain an XSD schema that the XML snapshot conforms to.
-
-[source]
-----
-XmlSnapshot snapshot = ...;
-Element customerAsXml = snapshot.getXmlElement();
-Element customerXsd = snapshot.getXsdElement();
-----
-
-This can be useful for some tools. For example, link:http://www.altova.com/stylevision.html[Altova Stylevision] can use the XML and XSD to transform into reports. Please note that this link does not imply endorsement (nor even a recommendation that this is a good design).
-
-
-
-
-
-== Builder API
-
-The contents of the snapshot can be adjusted by including "paths" to other references or collections. To do this, the
-builder is used. The API for this is:
-
-[source,java]
-----
-public interface XmlSnapshotService {
- ...
- public interface Builder {
- void includePath(final String path);
- void includePathAndAnnotation(String path, String annotation);
- XmlSnapshotService.Snapshot build();
- }
- @Programmatic
- public XmlSnapshotService.Builder builderFor(Object domainObject);
-}
-----
-
-We start by obtaining a builder:
-
-[source,java]
-----
-XmlSnapshot.Builder builder = xmlsnapshotService.builderFor(customer);
-----
-
-Suppose now that we want the snapshot to also include details of the customer's address, where `address` in this case is a reference property to an instance of the `Address` class. We can "walk-the-graph" by including these references within the builder.
-
-[source,java]
-----
-builder.includePath("address");
-----
-
-We could then go further and include details of every order in the customer's `orders` collection, and details of every
-product of every order:
-
-[source,java]
-----
-builder.includePath("orders/product");
-----
-
-When all paths are included, then the builder can build the snapshot:
-
-[source,java]
-----
-XmlSnapshot snapshot = builder.build();
-Element customerAsXml = snapshot.getXmlElement();
-----
-
-All of this can be strung together in a fluent API:
-
-[source,java]
-----
-Element customerAsXml = xmlsnapshotService.builderFor(customer)
- .includePath("address")
- .includePath("orders/product")
- .build()
- .getXmlElement();
-----
-
-
-As you might imagine, the resultant XML document can get quite large very quickly with only a few "include"s.
-
-
-[NOTE]
-====
-If an XSD schema is beng generated (using `snapshot.getXsdElement()` then note that for the XSD to be correct, the object being snapshotted must have non-null values for the paths that are `include()`'d. If this isn't done then the XSD will not be correct reflect for another snapshotted object that does have non-null values.
-====
-
-
-
-
-== Automatic inclusions
-
-If the domain object being snapshotted implements the `SnapshottableWithInclusions` interace, then this moves the
-responsibility for determining what is included within the snapshot from the caller to the snapshottable object itself:
-
-[source]
-----
-public interface SnapshottableWithInclusions extends Snapshottable {
- List<String> snapshotInclusions();
-}
-----
-
-If necessary, both approaches can be combined.
-
-
-[TIP]
-====
-As an alternative to using `include()`, you might consider building a view model domain object which can reference only the relevant information required for the snapshot. For example, if only the 5 most recent Orders for a Customer were required, a `CustomerAndRecentOrders` view model could hold a collection of just those 5 ``Order``s. Typically such view models would implement `SnapshottableWithInclusions`.
-
-One reason for doing this is to provide a stable API between the domain model and whatever it is that might be consuming the XML. With a view model you can refactor the domain entities but still preserve a view model such that the XML is the same.
-====
-
-
-
-== Convenience API
-
-The `XmlSnapshotService` also provides some API for simply manipulating XML:
-
-[source]
-----
-public interface XmlSnapshotService {
- ...
- @Programmatic
- public Document asDocument(String xmlStr); // <1>
- @Programmatic
- public <T> T getChildElementValue( // <2>
- Element el, String tagname, Class<T> expectedCls);
- @Programmatic
- public Element getChildElement( // <3>
- Element el, String tagname);
- @Programmatic
- public String getChildTextValue(Element el); // <4>
-}
-----
-<1> is a convenience method to convert xml string back into a W3C Document
-<2> is a convenience method to extract the value of an XML element, based on its type.
-<3> is a convenience method to walk XML document.
-<4> is a convenience method to obtain value of child text node.
-
-
-
-
-
-
-
-== Registering the Service
-
-Assuming that the `configuration-and-annotation` services installer is configured:
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then Isis' core implementation of `XmlSnapshotService` service is automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
-
-
-== Related Services
-
-The xref:_ug_reference-services-api_manpage-BookmarkService[`BookmarkService`] provides a mechanism for obtaining a string representations of a single domain object.
-
-The xref:_ug_reference-services-api_manpage-MementoService[`MementoService`] also provides a mechanism for generating string representations of domain objects.
-
-
-
-
[04/45] isis git commit: ISIS-1133: breaking out reference guide and
devenv guide;
moving appendices' release notes and migration notes to other docs;
improving the documentation page.
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_tutorials_pet-clinic.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_tutorials_pet-clinic.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_tutorials_pet-clinic.adoc
deleted file mode 100644
index 3b0a7f1..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_tutorials_pet-clinic.adoc
+++ /dev/null
@@ -1,557 +0,0 @@
-[[_ug_tutorials_pet-clinic]]
-= Pet Clinic
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-This is a step-by-step tutorial to build up a simple "petclinic" application, starting from the xref:_ug_getting-started_simpleapp-archetype[SimpleApp archetype].
-
-It consists of just three domain classes (http://yuml.me/edit/3db2078c[http://yuml.me/3db2078c]):
-
-image::{_imagesdir}tutorials/pet-clinic/domain-model.png[link="{_imagesdir}tutorials/pet-clinic/domain-model.png"]
-
-
-This supports the following use cases:
-
-* register a Pet
-* register an Owner
-* maintain a Pet's details
-* check in a Pet to visit the clinic
-* enter a diagnosis
-
-check out a Pet to visit the clinic
-
-Either follow along or check out the tags from the corresponding https://github.com/danhaywood/isis-app-petclinic[github repo].
-
-== Prerequisites
-
-You'll need:
-
-* Java 7 JDK
-* http://maven.apache.org/[Maven] 3.2.x
-* an IDE, such as http://www.eclipse.org/[Eclipse] or https://www.jetbrains.com/idea/[IntelliJ IDEA].
-
-
-
-
-== Run the archetype
-
-Throughout this tutorial you can, if you wish, just checkout from the github repo wherever you see a "git checkout" note:
-
-[TIP]
-====
-[source,bash]
-----
-git checkout https://github.com/danhaywood/isis-app-petclinic/commit/249abe476797438d83faa12ff88365da2c362451
-----
-
-====
-
-[NOTE]
-====
-This tutorial was developed against Apache Isis 1.8.0-SNAPSHOT. Since then 1.8.0 has been released, so simply replace "1.8.0-SNAPSHOT" for "1.8.0" wherever it appears in the `pom.xml` files.
-====
-
-
-As per the http://isis.apache.org/intro/getting-started/simpleapp-archetype.html[Isis website], run the simpleapp archetype to build an empty Isis application:
-
-
-[source,bash]
-----
-mvn archetype:generate \
- -D archetypeGroupId=org.apache.isis.archetype \
- -D archetypeArtifactId=simpleapp-archetype \
- -D archetypeVersion=1.8.0 \
- -D groupId=com.mycompany \
- -D artifactId=petclinic \
- -D version=1.0-SNAPSHOT \
- -D archetypeRepository=http://repository-estatio.forge.cloudbees.com/snapshot/ \
- -B
-----
-
-This will generate the app in a `petclinic` directory. Move the contents back:
-
-[source,bash]
-----
-mv petclinic/* .
-rmdir petclinic
-----
-
-
-
-
-== Build and run
-
-Start off by building the app from the command line:
-
-[source,bash]
-----
-mvn clean install
-----
-
-Once that's built then run using:
-
-[source,bash]
-----
-mvn antrun:run -P self-host
-----
-
-A splash screen should appear offering to start up the app. Go ahead and start; the web browser should be opened at http://localhost:8080[http://localhost:8080]
-
-Alternatively, you can run using the mvn-jetty-plugin:
-
-[source,bash]
-----
-mvn jetty:run
-----
-
-This will accomplish the same thing, though the webapp is mounted at a slightly different URL
-
-
-
-
-== Using the app
-
-Navigate to the Wicket UI (eg http://localhost:8080/wicket[http://localhost:8080/wicket]), and login (sven/pass).
-
-image::{_imagesdir}tutorials/pet-clinic/010-01-login-page.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/010-01-login-page.png"]
-
-
-
-The home page should be shown:
-
-image::{_imagesdir}tutorials/pet-clinic/010-02-home-page.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/010-02-home-page.png"]
-
-
-
-Install the fixtures (example test data) using the `Prototyping` menu:
-
-image::{_imagesdir}tutorials/pet-clinic/010-03-prototyping-menu.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/010-03-prototyping-menu.png"]
-
-
-
-List all objects using the `Simple Objects` menu:
-
-image::{_imagesdir}tutorials/pet-clinic/010-04-simpleobjects.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/010-04-simpleobjects.png"]
-
-
-To return the objects created:
-
-image::{_imagesdir}tutorials/pet-clinic/010-05-simpleobject-list.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/010-05-simpleobject-list.png"]
-
-
-
-Experiment some more, to:
-
-* create a new object
-* list all objects
-
-Go back to the splash screen, and quit the app. Note that the database runs in-memory (using HSQLDB) so any data created will be lost between runs.
-
-
-
-
-== Dev environment
-
-Set up xref:_ug_appendices_dev-env[an IDE] and import the project to be able to run and debug the app.
-
-Then set up a launch configuration so that you can run the app from within the IDE. To save having to run the fixtures
-every time, specify the following system properties:
-
-[source,bash]
-----
--Disis.persistor.datanucleus.install-fixtures=true -Disis.fixtures=fixture.simple.scenario.SimpleObjectsFixture
-----
-
-For example, here's what a launch configuration in IntelliJ idea looks like:
-
-image::{_imagesdir}tutorials/pet-clinic/020-01-idea-configuration.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/020-01-idea-configuration.png"]
-
-
-
-where the "before launch" maven goal (to run the DataNucleus enhancer) is defined as:
-
-
-image::{_imagesdir}tutorials/pet-clinic/020-02-idea-configuration.png[width="400px",link="{_imagesdir}tutorials/pet-clinic/020-02-idea-configuration.png"]
-
-
-
-
-== Explore codebase
-
-Apache Isis applications are organized into several Maven modules. Within your IDE navigate to the various classes and correlate back to the generated UI:
-
-* `petclinic` : parent module
-* `petclinic-dom`: domain objects module
-** entity: `dom.simple.SimpleObject`
-** repository: `dom.simple.SimpleObjects`
-* `petclinic-fixture`: fixtures module
-** fixture script:`fixture.simple.SimpleObjectsFixture`
-* `petclinic-integtests`: integration tests module
-* `petclinic-webapp`: webapp module
-** (builds the WAR file)
-
-
-
-
-== Testing
-
-Testing is of course massively important, and Isis makes both unit testing and (end-to-end) integration testing easy. Building the app from the Maven command line ("mvn clean install") will run all tests, but you should also run the tests from within the IDE.
-
-* `myapp-dom` unit tests
-* run
-* inspect, eg
- - `SimpleObjectTest`
-* `myapp-integtests` integration tests
-* run
-* inspect, eg:
-** `integration.tests.smoke.SimpleObjectsTest`
-** `integration.specs.simple.SimpleObjectSpec_listAllAndCreate.feature`
-* generated report, eg
- - `myapp/integtests/target/cucumber-html-report/index.html`
-** change test in IDE, re-run (in Maven)
-
-If you have issues with the integration tests, make sure that the domain classes have been enhanced by the DataNucleus enhancer. (The exact mechanics depends on the IDE being used).
-
-
-
-
-== Update POM files
-
-[TIP]
-====
-[source,bash]
-----
-git checkout https://github.com/danhaywood/isis-app-petclinic/commit/68904752bc2de9ebb3c853b79236df2b3ad2c944
-----
-
-====
-
-The POM files generated by the simpleapp archetype describe the app as "SimpleApp". Update them to say "PetClinic" instead.
-
-
-
-
-== Delete the BDD specs
-
-[TIP]
-====
-[source,bash]
-----
-git checkout https://github.com/danhaywood/isis-app-petclinic/commit/9046226249429b269325dfa2baccf03635841c20
-----
-
-====
-
-
-During this tutorial we're going to keep the integration tests in-sync with the code, but we're going to stop short of writing BDD/Cucumber specs.
-
-Therefore delete the BDD feature spec and glue in the `integtest` module:
-
-* `integration/specs/*`
-* `integration/glue/*`
-
-
-
-
-== Rename artifacts
-
-[TIP]
-====
-[source,bash]
-----
-git checkout https://github.com/danhaywood/isis-app-petclinic/commit/bee3629c0b64058f939b6dd20f226be31810fc66
-----
-
-====
-
-
-Time to start refactoring the app. The heart of the PetClinic app is the `Pet` concept, so go through the code and refactor. While we're at it, refactor the app itself from "SimpleApp" to "PetClinicApp".
-
-See the git commit for more detail, but in outline, the renames required are:
-
-* in the `dom` module's production code
-** `SimpleObject` -> `Pet` (entity)
-** `SimpleObjects` -> `Pets` (repository domain service)
-** `SimpleObject.layout.json` -> `Pet.layout.json` (layout hints for the `Pet` entity)
-** delete the `SimpleObject.png`, and add a new `Pet.png` (icon shown against all `Pet` instances).
-* in the `dom` module's unit test code
-** `SimpleObjectTest` -> `PetTest` (unit tests for `Pet` entity)
-** `SimpleObjectsTest` -> `PetsTest` (unit tests for `Pets` domain service)
-* in the `fixture` module:
-** `SimpleObjectsFixturesService` -> `PetClinicAppFixturesService` (rendered as the prototyping menu in the UI)
-** `SimpleObjectsTearDownService` -> `PetClinicAppTearDownService` (tear down all objects between integration tests)
-** `SimpleObjectAbstract` -> `PetAbstract` (abstract class for setting up a single pet object
-*** and corresponding subclasses to set up sample data (eg `PetForFido`)
-** `SimpleObjectsFixture` -> `PetsFixture` (tear downs system and then sets up all pets)
-* in the `integtest` module:
-** `SimpleAppSystemInitializer` -> `PetClinicAppSystemInitializer` (bootstraps integration tests with domain service/repositories)
-** `SimpleAppIntegTest` -> `PetClinicAppIntegTest` (base class for integration tests)
-** `SimpleObjectTest` -> `PetTest` (integration test for `Pet` entity)
-** `SimpleObjectsTest` -> `PetsTest` (integration test for `Pets` domain service)
-* in the `webapp` module:
-** `SimpleApplication` -> `PetClinicApplication`
-** update `isis.properties`
-** update `web.xml`
-
-
-Note that `Pet` has both both Isis and JDO annotations:
-
-[source,java]
-----
-@javax.jdo.annotations.PersistenceCapable(identityType=IdentityType.DATASTORE) // <1>
-@javax.jdo.annotations.DatastoreIdentity( // <2>
- strategy=javax.jdo.annotations.IdGeneratorStrategy.IDENTITY,
- column="id")
-@javax.jdo.annotations.Version( // <3>
- strategy=VersionStrategy.VERSION_NUMBER,
- column="version")
-@javax.jdo.annotations.Unique(name="Pet_name_UNQ", members = {"name"}) // <4>
-@ObjectType("PET") // <5>
-@Bookmarkable // <6>
-public class Pet implements Comparable<Pet> {
- ...
-}
-----
-
-where:
-
-<1> `@PersistenceCapable` and
-<2> `@DatastoreIdentity` specify a surrogate `Id` column to be used as the primary key
-<3> `@Version` provides support for optimistic locking
-<4> `@Unique` enforces a uniqueness constraint so that no two `Pet`s can have the same name (unrealistic, but can refactor later)
-<5> `@ObjectType` is used by Isis for its own internal "OID" identifier; this also appears in the URL in Isis' Wicket viewer and REST API
-<6> `@Bookmarkable` indicates that the object can be automatically bookmarked in Isis' Wicket viewer
-
-[NOTE]
-====
-The `@ObjectType` and `@Bookmarkable` annotations have since been deprecated, replaced with `@DomainObject(objectType=...)` and `@DomainObjectLayout(bookmarking=...)`
-====
-
-
-The `Pets` domain service also has Isis annotations:
-
-[source,java]
-----
-@DomainService(repositoryFor = Pet.class)
-@DomainServiceLayout(menuOrder = "10")
-public class Pets {
- ...
-}
-----
-
-where:
-
-* `DomainService` indicates that the service should be instantiated automatically (as a singleton)
-* `DomainServiceLayout` provides UI hints, in this case the positioning of the menu for the actions provided by the service
-
-To run the application will require an update to the IDE configuration, for the changed name of the fixture class:
-
-
-image::{_imagesdir}tutorials/pet-clinic/030-01-idea-configuration-updated.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/030-01-idea-configuration-updated.png"]
-
-
-Running the app should now show `Pet`s:
-
-image::{_imagesdir}tutorials/pet-clinic/030-02-updated-app.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/030-02-updated-app.png"]
-
-
-
-
-
-== Update package names
-
-[TIP]
-====
-[source,bash]
-----
-git checkout https://github.com/danhaywood/isis-app-petclinic/commit/55ec36e520191f5fc8fe7f5b89956814eaf13317
-----
-
-====
-
-
-
-The classes created by the simpleapp archetype are by default in the `simple` package. Move these classes to `pets` package instead. Also adjust package names where they appear as strings:
-
-* in `PetClinicAppFixturesService`, change the package name from "fixture.simple" to "fixture.pets".
-* in `PetClinicAppSystemInitializer`, change the package name "dom.simple" to "dom.pets", and similarly "fixture.simple" to "fixture.pets"
-* in `WEB-INF/isis.properties`, similarly change the package name "dom.simple" to "dom.pets", and similarly "fixture.simple" to "fixture.pets"
-
-To run the application will require a further update to the IDE configuration, for the changed package of the fixture class:
-
-
-image::{_imagesdir}tutorials/pet-clinic/040-01-idea-configuration-updated.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/040-01-idea-configuration-updated.png"]
-
-
-
-== Add `PetSpecies` enum
-
-[TIP]
-====
-[source,bash]
-----
-git checkout https://github.com/danhaywood/isis-app-petclinic/commit/55c9cd28ff960220719b3dc7cb8abadace8d0829
-----
-
-====
-
-
-Each `Pet` is of a particular species. Model these as an enum called `PetSpecies`:
-
-[source,java]
-----
-public enum PetSpecies {
- Cat,
- Dog,
- Budgie,
- Hamster,
- Tortoise
-}
-----
-
-Introduce a new property on `Pet` of this type:
-
-[source,java]
-----
-public class Pet {
- ...
- private PetSpecies species;
- @javax.jdo.annotations.Column(allowsNull = "false")
- public PetSpecies getSpecies() { return species; }
- public void setSpecies(final PetSpecies species) { this.species = species; }
- ...
-}
-----
-
-Update fixtures, unit tests and integration tests.
-
-
-
-
-== Icon to reflect pet species
-
-[TIP]
-====
-[source,bash]
-----
-git checkout https://github.com/danhaywood/isis-app-petclinic/commit/2212765694693eb463f8fa88bab1bad154add0cb
-----
-
-====
-
-
-Rather than using a single icon for a domain class, instead a different icon can be supplied for each instance. We can therefore have different icon files for each pet, reflecting that pet's species.
-
-[source,java]
-----
-public class Pet {
- ...
- public String iconName() {
- return getSpecies().name();
- }
- ...
-}
-----
-
-Download corresponding icon files (`Dog.png`, `Cat.png` etc)
-
-Running the app shows the `Pet` and its associated icon:
-
-image::{_imagesdir}tutorials/pet-clinic/050-01-list-all.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/050-01-list-all.png"]
-
-
-
-with the corresponding view of the `Pet`:
-
-image::{_imagesdir}tutorials/pet-clinic/050-02-view-pet.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/050-02-view-pet.png"]
-
-
-== Add pet's `Owner`
-
-[TIP]
-====
-[source,bash]
-----
-git checkout https://github.com/danhaywood/isis-app-petclinic/commit/6f92a8ee8e76696d005da2a8b7a746444d017546
-----
-
-====
-
-
-Add the `Owner` entity and corresponding `Owners` domain service (repository). Add a query to find `Order`s by name:
-
-[source,java]
-----
-...
-@javax.jdo.annotations.Queries( {
- @javax.jdo.annotations.Query(
- name = "findByName", language = "JDOQL",
- value = "SELECT "
- + "FROM dom.owners.Owner "
- + "WHERE name.matches(:name)")
-})
-public class Owner ... {
- ...
-}
-----
-
-and `findByName(...)` in `Owners`:
-
-[source,java]
-----
-public class Owners {
- ...
- public List<Owner> findByName(
- @ParameterLayout(named = "Name")
- final String name) {
- final String nameArg = String.format(".*%s.*", name);
- final List<Owner> owners = container.allMatches(
- new QueryDefault<>(
- Owner.class,
- "findByName",
- "name", nameArg));
- return owners;
- }
- ...
-}
-----
-
-Add an `owner` property to `Pet`, with supporting `autoCompleteXxx()` method (so that available owners are shown in a drop-down list box):
-
-[source,java]
-----
-public class Pet ... {
- ...
- private Owner owner;
- @javax.jdo.annotations.Column(allowsNull = "false")
- public Owner getOwner() { return owner; }
- public void setOwner(final Owner owner) { this.owner = owner; }
- public Collection<Owner> autoCompleteOwner(final @MinLength(1) String name) {
- return owners.findByName(name);
- }
- ...
-}
-----
-
-Also updated fixture data to set up a number of `Owner`s, and associate each `Pet` with an `Owner`. Also add unit tests and integration tests for `Owner`/`Owners` and updated for `Pet`/`Pets`.
-
-When running the app, notice the new `Owners` menu:
-
-image::{_imagesdir}tutorials/pet-clinic/060-01-owners-menu.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/060-01-owners-menu.png"]
-
-which when invoked returns all `Owner` objects:
-
-image::{_imagesdir}tutorials/pet-clinic/060-02-owners-list.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/060-02-owners-list.png"]
-
-
-Each `Pet` also indicates its corresponding `Owner`:
-
-image::{_imagesdir}tutorials/pet-clinic/060-03-pets-list.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/060-03-pets-list.png"]
-
-
-And, on editing a `Pet`, a new `Owner` can be specified using the autoComplete:
-
-image::{_imagesdir}tutorials/pet-clinic/060-04-pet-owner-autoComplete.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/060-04-pet-owner-autoComplete.png"]
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_tutorials_stop-scaffolding-start-coding.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_tutorials_stop-scaffolding-start-coding.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_tutorials_stop-scaffolding-start-coding.adoc
deleted file mode 100644
index 8eea3f4..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_tutorials_stop-scaffolding-start-coding.adoc
+++ /dev/null
@@ -1,684 +0,0 @@
-[[_ug_tutorials_stop-scaffolding-start-coding]]
-= Stop scaffolding, start coding
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 half-day tutorial on developing domain-driven apps using Apache Isis. Actually, you could probably spend a full day working through this tutorial if you wanted to, so pick and choose the bits that look interesting.
-
-There's a bit of overlap with the xref:_ug_tutorials_pet-clinic[Pet Clinic] tutorial initially, but it then sets off on its own.
-
-
-
-== Prerequisites
-
-You'll need:
-
-* Java 7 JDK
-* http://maven.apache.org/[Maven] 3.2.x
-* an IDE, such as http://www.eclipse.org/[Eclipse] or https://www.jetbrains.com/idea/[IntelliJ IDEA].
-
-
-
-== Run the archetype
-
-As per the http://isis.apache.org/intro/getting-started/simpleapp-archetype.html[Isis website], run the simpleapp archetype to build an empty Isis application:
-
-[source,bash]
-----
-mvn archetype:generate \
- -D archetypeGroupId=org.apache.isis.archetype \
- -D archetypeArtifactId=simpleapp-archetype \
- -D archetypeVersion=1.8.0 \
- -D groupId=com.mycompany \
- -D artifactId=myapp \
- -D version=1.0-SNAPSHOT \
- -D archetypeRepository=http://repository-estatio.forge.cloudbees.com/snapshot/ \
- -B
-----
-
-
-
-
-== Build and run
-
-Start off by building the app from the command line:
-
-[source,bash]
-----
-cd myapp
-mvn clean install
-----
-
-Once that's built then run using:
-
-[source,bash]
-----
-mvn antrun:run -P self-host
-----
-
-A splash screen should appear offering to start up the app. Go ahead and start; the web browser should be opened at http://localhost:8080[http://localhost:8080]
-
-Alternatively, you can run using the mvn-jetty-plugin:
-
-[source,bash]
-----
-mvn jetty:run
-----
-
-This will accomplish the same thing, though the webapp is mounted at a slightly different URL
-
-
-
-
-== Using the app
-
-Navigate to the Wicket UI (eg link:http://localhost:8080/wicket[http://localhost:8080/wicket]), and login (sven/pass).
-
-Once at the home page:
-
-* install fixtures
-* list all objects
-* create a new object
-* list all objects
-
-Go back to the splash screen, and quit the app. Note that the database runs in-memory (using HSQLDB) so any data created will be lost between runs.
-
-
-
-
-== Dev environment
-
-Set up xref:_ug_appendices_dev-env[an IDE] and import the project to be able to run and debug the app.
-
-Then set up a launch configuration and check that you can:
-
-* Run the app from within the IDE
-* Run the app in debug mode
-* Run with different deploymentTypes; note whether prototype actions (those annotated xref:_ug_reference-annotations_manpage-Action_restrictTo[`@Action(restrictTo=PROTOTYPING`]) are available or not:
-* `--type SERVER_PROTOTYPE`
-* `--type SERVER`
-
-
-
-
-== Explore codebase
-
-Apache Isis applications are organized into several Maven modules. Within your IDE navigate to the various classes and correlate back to the generated UI:
-
-* `myapp` : parent module
-* `myapp-dom`: domain objects module
-* entity: `dom.simple.SimpleObject`
-* repository: `dom.simple.SimpleObjects`
-* `myapp-fixture`: fixtures module
-* fixture script:`fixture.simple.SimpleObjectsFixture`
-* `myapp-integtests`: integration tests module
-* `myapp-webapp`: webapp module
-* (builds the WAR file)
-
-
-
-
-== Testing
-
-Testing is of course massively important, and Isis makes both unit testing and (end-to-end) integration testing easy. Building the app from the Maven command line ("mvn clean install") will run all tests, but you should also run the tests from within the IDE.
-
-* `myapp-dom` unit tests
-* run
-* inspect, eg
- - `SimpleObjectTest`
-* `myapp-integtests` integration tests
-* run
-* inspect, eg:
-** `integration.tests.smoke.SimpleObjectsTest`
-** `integration.specs.simple.SimpleObjectSpec_listAllAndCreate.feature`
-* generated report, eg
- - `myapp/integtests/target/cucumber-html-report/index.html`
-** change test in IDE, re-run (in Maven)
-
-If you have issues with the integration tests, make sure that the domain classes have been enhanced by the DataNucleus enhancer. (The exact mechanics depends on the IDE being used).
-
-
-
-
-== Prototyping
-
-Although testing is important, in this tutorial we want to concentrate on how to write features and to iterate quickly. So for now, exclude the `integtests` module. Later on in the tutorial we'll add the tests back in so you can learn how to write automated tests for the features of your app.
-
-In the parent `pom.xml`:
-
-[source,xml]
-----
-<modules>
- <module>dom</module>
- <module>fixture</module>
- <module>integtests</module>
- <module>webapp</module>
-</modules>
-----
-
-change to:
-
-[source,xml]
-----
-<modules>
- <module>dom</module>
- <module>fixture</module>
- <!--
- <module>integtests</module>
- -->
- <module>webapp</module>
-</modules>
-----
-
-
-
-
-== Build a domain app
-
-The remainder of the tutorial provides guidance on building a domain application. We don't mandate any particular design, but we suggest one with no more than 3 to 6 domain entities in the first instance. If you're stuck for ideas, then how about:
-
-* a todo app (``ToDoItem``s)
-* a pet clinic (`Pet`, `Owner`, `PetSpecies`, `Visit`)
-* a library (`Book`, `Title`, `LibraryMember`, `Loan`, `Reservation`)
-* a holiday cottage rental system
-* a scrum/kanban system (inspired by Trello)
-* a meeting planner (inspired by Doodle)
-* (the domain model for) a CI server (inspired by Travis/Jenkins)
-* a shipping system (inspired by the example in the DDD "blue" book)
-* a system for ordering coffee (inspired by Restbucks, the example in "Rest in Practice" book)
-
-Hopefully one of those ideas appeals or sparks an idea for something of your own.
-
-
-
-
-== Domain entity
-
-Most domain objects in Apache Isis applications are persistent entities. In the simpleapp archetype the `SimpleObject` is an example. We can start developing our app by refactoring that class:
-
-* rename the `SimpleObject` class
-** eg rename to `Pet`
-* if required, rename the `SimpleObject` class' `name` property
-** for `Pet`, can leave `name` property as is
-* specify a xref:_ug_how-tos_ui-hints_object-titles-and-icons[title]
-* specify an xref:_ug_how-tos_ui-hints_object-titles-and-icons[icon]
-* make the entity bookmarkable by adding the <<__code_domainobjectlayout_code,@DomainObjectLayout(bookmarking=...)` annotation
-* confirm is available from bookmark panel (top-left of Wicket UI)
-
-
-
-
-== Domain service
-
-Domain services often act as factories or repositories to entities; more generally can be used to "bridge across" to other domains/bounded contexts. Most are application-scoped, but they can also be request-scoped if required.
-
-In the simpleapp archetype the `SimpleObjects` service is a factory/repository for the original `SimpleObject` entity. For our app it therefore makes sense to refactor that class into our own first service:
-
-* rename the `SimpleObjects` class
-** eg rename to `Pets`
-* review `create` action (acting as a factory)
-** as per the docs describing xref:_ug_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_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()`
-* note the xref:_ug_reference-annotations_manpage-DomainService[`@DomainService`] annotation
-* optional: add an action to a return subset of objects
-** use the JDO `@Query` annotation
-** see for example the Isisaddons example https://github.com/isisaddons/isis-app-todoapp[todoapp] (not ASF), see https://github.com/apache/isis/blob/b3e936c9aae28754fb46c2df52b1cb9b023f9ab8/example/application/todoapp/dom/src/main/java/dom/todo/ToDoItem.java#L93[here] and https://github.com/apache/isis/blob/b3e936c9aae28754fb46c2df52b1cb9b023f9ab8/example/application/todoapp/dom/src/main/java/dom/todo/ToDoItems.java#L63[here]
-
-
-
-
-== Fixture scripts
-
-Fixture scripts are used to setup the app into a known state. They are great for demo's and as a time-saver when implementing a feature, and they can also be reused in automated integration tests. We usually also have a fixture script to zap all the (non-reference) data (or some logical subset of the data)
-
-* rename the `SimpleObjectsTearDownFixture` class
-* and update to delete from the appropriate underlying database table(s)
-* use the injected xref:_ug_reference-services-api_manpage-IsisJdoSupport[`IsisJdoSupport`] domain service.
-* refactor/rename the fixture script classes that create instances your entity:
-* `RecreateSimpleObjects`, which sets up a set of objects for a given scenario
-* `SimpleObjectCreate` which creates a single object
-* note that domain services can be injected into these fixture scripts
-
-
-
-
-== Actions
-
-Most business functionality is implemented using actions� basically a `public` method accepting domain classes and primitives as its parameter types. The action can return a domain entity, or a collection of entities, or a primitive/String/value, or void. If a domain entity is returned then that object is rendered immediately; if a collection is returned then the Wicket viewer renders a table. Such collections are sometimes called "standalone" collections.
-
-* write an action to update the domain property (originally called `SimpleObject#name`, though renamed by now)
-* use the xref:_ug_reference-annotations_manpage-ParameterLayout_named[`@ParameterLayout(named=...)`] annotation to specify the name of action parameters
-* use the xref:_ug_reference-annotations_manpage-Action_semantics[`@Action(semanticsOf=...)`] annotation to indicate the semantics of the action (safe/query-only, idempotent or non-idempotent)
-* annotate safe action as bookmarkable using xref:_ug_reference-annotations_manpage-ActionLayout_bookmarking[`@ActionLayout(bookmarking=...)`]
-* confirm is available from bookmark panel (top-left of Wicket UI)
-* optional: add an action to clone an object
-
-
-
-
-== REST API
-
-As well as exposing the Wicket viewer, Isis also exposes a REST API (an implementation of the http://restfulobjects.org[Restful Objects spec]). All of the functionality of the domain object model is available through this REST API.
-
-* add Chrome extensions
-* install https://chrome.google.com/webstore/detail/postman-rest-client/fdmmgilgnpjigdojojpjoooidkmcomcm?hl=en[Postman]
-* install https://chrome.google.com/webstore/detail/jsonview/chklaanhfefbnpoihckbnefhakgolnmc?hl=en[JSON-View]
-* browse to Wicket viewer, install fixtures
-* browse to the http://localhost:8080/restful[http://localhost:8080/restful] API
-* invoke the service to list all objects
-* services
-* actions
-* invoke (invoking 0-arg actions is easy; the Restful Objects spec defines how to invoke N-arg actions)
-
-
-
-
-== Specify Action semantics
-
-The semantics of an action (whether it is safe/query only, whether it is idempotent, whether it is neither) can be specified for each action; if not specified then Isis assumes non-idempotent. In the Wicket viewer this matters in that only query-only actions can be bookmarked or used as contributed properties/collections. In the RESTful viewer this matters in that it determines the HTTP verb (GET, PUT or POST) that is used to invoke the action.
-
-* experiment changing xref:_ug_reference-annotations_manpage-Action_semantics[`@Action(semantics=...)`] on actions
-* note the HTTP methods exposed in the REST API change
-* note whether the non-safe actions are bookmarkable (assuming that it has been annotated with `@ActionLayout(bookmarking=...)`, that is).
-
-
-
-
-== Value properties
-
-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_how-tos_class-structure_properties[value properties]; also:
-* for string properties
-** use the xref:_ug_reference-annotations_manpage-PropertyLayout_multiLine[`@Property(multiLine=...)`] annotation to render a text area instead of a text box
-** use the xref:_ug_reference-annotations_manpage-Property_maxLength[`@Property(maxLength=...)`] annotation to specify the maximum number of characters allowable
-** use joda date/time properties, bigdecimals and blob/clob properties
-* use the xref:_ug_reference-annotations_manpage-Property_optionality[`@Column(allowsNull=...)`] annotation specify whether a property is optional or mandatory
-* use enums for properties (eg as used in the Isis addons example https://github.com/isisaddons/isis-app-todoapp[todoapp], see https://github.com/apache/isis/blob/b3e936c9aae28754fb46c2df52b1cb9b023f9ab8/example/application/todoapp/dom/src/main/java/dom/todo/ToDoItem.java#L207[here] and https://github.com/apache/isis/blob/b3e936c9aae28754fb46c2df52b1cb9b023f9ab8/example/application/todoapp/dom/src/main/java/dom/todo/ToDoItem.java#L266[here])
-* update the corresponding domain service for creating new instances
-* 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:_ug_reference-annotations_manpage-Title[`@Title`] annotation
-** rather than the xref:_ug_reference-methods_reserved_manpage-title[`title()`] `title()` method
-* order the properties using the xref:_ug_reference-annotations_manpage-MemberOrder[`@MemberOrder`], also `@MemberGroupLayout`
-** see also the docs on xref:_ug_reference-object-layout_static[static layouts]
-* use the xref:_ug_reference-annotations_manpage-PropertyLayout[`@PropertyLayout`] annotation to position property/action parameter labels either to the LEFT, TOP or NONE
-** do the same for parameters using xref:_ug_reference-annotations_manpage-ParameterLayout[`@ParameterLayout`]
-
-
-
-
-== Reference properties
-
-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_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:_ug_reference-annotations_manpage-DomainObject_bounded[`@DomainObjectLayout(bounded=...)`] annotation on the referenced type if there are only a small number (bounded) of instances
-** use a xref:_ug_reference-methods_prefixes_manpage-choices[`choices...()`] supporting method
-*** on a property
-*** on an action parameter
-** use a xref:_ug_reference-methods_prefixes_manpage-autoComplete[`autoComplete...()`] supporting method
-*** on a property
-*** on an action parameter
-
-
-
-
-== Usability: Defaults
-
-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_how-tos_drop-downs-and-defaults[defaults] for action parameters
-
-
-
-
-== Collections
-
-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:_ug_reference-classes_utility_manpage-ObjectContracts[`ObjectContracts`] utility class to help implement `Comparable`
-*** you can also `equals()`, `hashCode()`, `toString()`
-* Add a xref:_ug_how-tos_class-structure_collections[collection] to one of the entities
-** Use `SortedSet` as the class
-** Use the xref:_ug_reference-annotations_manpage-CollectionLayout_render[`@CollectionLayout(render=...)`] annotation to indicate if the collection should be visible or hidden by default
-* optional: use the xref:_ug_reference-annotations_manpage-CollectionLayout_sortedBy[`@CollectionLayout(sortedBy=...)`] annotation to specify a different comparator than the natural ordering
-
-
-
-
-
-== Actions and Collections
-
-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_how-tos_class-structure_inject-services[inject] associated domain service
-** generally we recommend using the xref:_ug_reference-annotations_manpage-Inject[`@Inject`] annotation with either private or default visibility
-* the service itself should use xref:_ug_reference-services-api_manpage-DomainObjectContainer[`DomainObjectContainer`]
-* use the xref:_ug_reference-annotations_manpage-MemberOrder[`@MemberOrder(name=...)`] annotation to associate an action with a property or with a collection
-
-
-
-
-== CSS UI Hints
-
-CSS classes can be associated with any class member (property, collection, action). But for actions in particular:
-
-* the bootstrap "btn" CSS classes can be used using the xref:_ug_reference-annotations_manpage-ActionLayout_cssClass[`@ActionLayout(cssClass=...)`] annotation
-
-* the http://fortawesome.github.io/Font-Awesome/icons/[Font Awesome] icons can be used using the xref:_ug_reference-annotations_manpage-ActionLayout_cssClassFa[`@ActionLayout(cssClassFa=...)`]
-
-It's also possible to use Font Awesome icons for the xref:_ug_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=...)`
-
-
-
-
-== Dynamic Layout
-
-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>Reload Changed Classes):
-
-* Delete the various hint annotations and instead specify layout hints using a xref:_ug_reference-object-layout_dynamic[.layout.json] file.
-
-
-
-
-== Business rules
-
-Apache Isis excels for domains where there are complex business rules to enforce. The UI tries not to constrain the user from navigating around freely, however the domain objects nevertheless ensure that they cannot change into an invalid state. Such rules can be enforced either declaratively (using annotations) or imperatively (using code). The objects can do this in one of three ways:
-
-* visibility: preventing the user from even seeing a property/collection/action
-* usability: allowing the user to view a property/collection/action but not allowing the user to change it
-* validity: allowing the user to modify the property/invoke the action, but validating that the new value/action arguments are correct before hand.
-
-Or, more pithily: "see it, use it, do it"
-
-
-=== See it!
-
-* Use the xref:_ug_reference-annotations_manpage-Property_hidden[`Property(hidden=...)`] annotation to make properties invisible
-** likewise xref:_ug_reference-annotations_manpage-Collection_hidden[`@Collection(hidden=...)`] for collections
-** the xref:_ug_reference-annotations_manpage-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 Isis metamodel.
-* Use the xref:_ug_reference-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!
-
-* Use the xref:_ug_reference-annotations_manpage-Property_editing[`Property(editing=...)`] annotation to make property read-only
-** likewise xref:_ug_reference-annotations_manpage-Collection_editing[`@Collection(editing=...)`] for collections
-** alternatively, use xref:_ug_reference-annotations_manpage-DomainObject_editing[`@DomainObject(editing=...)`] to disable editing for all properties/collections
-* Use the xref:_ug_reference-methods_prefixes_manpage-disable[`disable...()`] supporting method on properties and actions to make a property/action disabled according to some imperative rule
-
-
-=== Do it!
-
-* Validate string properties or action parameters:
-* use the xref:_ug_reference-annotations_manpage-Property_regex[`@Property(regex=...)`] annotation to specify a regex pattern for properties, and use xref:_ug_reference-annotations_manpage-Parameter_regex[`@Parameter(regex=...)`] for parameters
-* use the xref:_ug_reference-annotations_manpage-Property_maxLength[`@Property(maxLength=...)`] annotation to indicate a minimum number of characters, and xref:_ug_reference-annotations_manpage-Parameter_minLength[`@Parameter(minLength=...)`] for parameters
-* Use the xref:_ug_reference-methods_prefixes_manpage-validate[`validate...()`] supporting method on properties or action parameter
-* optional: for any data type:
-** use the xref:_ug_reference-annotations_manpage-Property_mustSatisfy[`Property(mustSatisfy=...)`] and xref:_ug_reference-annotations_manpage-Parameter_mustSatisfy[`Parameter(mustSatisfy=...)`] annotations to specify arbitrary constraints on properties and parameters
-
-
-
-
-== Home page
-
-The Wicket UI will automatically invoke the "home page" action, if available. This is a no-arg action of one of the domain services, that can return either an object (eg representing the current user) or a standalone action.
-
-* Add the xref:_ug_reference-annotations_manpage-HomePage[`@HomePage`] annotation to one (no more) of the domain services' no-arg actions
-
-
-
-
-== Clock Service
-
-To ensure testability, there should be no dependencies on system time, for example usage of `LocalDate.now()`. Instead the domain objects should delegate to the provided `ClockService`.
-
-* remove any dependencies on system time (eg defaults for date/time action parameters)
-* inject xref:_ug_reference-services-api_manpage-ClockService[`ClockService`]
-* call `ClockService.now()` etc where required.
-
-
-
-
-== Using Contributions
-
-One of Isis' most powerful features is the ability for the UI to combine functionality from domain services into the representation of an entity. The effect is similar to traits or mix-ins in other languages, however the "mixing in" is done at runtime, within the Isis metamodel. In Isis' terminology, we say that the domain service action is contributed to the entity.
-
-Any action of a domain service that has a domain entity type as one of its parameter types will (by default) be contributed. If the service action takes more than one argument, or does not have safe semantics, then it will be contributed as an entity action. If the service action has precisely one parameter type (that of the entity) and has safe semantics then it will be contributed either as a collection or as a property (dependent on whether it returns a collection of a scalar).
-
-Why are contributions so useful? Because the service action will match not on the entity type, but also on any of the entity's supertypes (all the way up to `java.lang.Object`). That means that you can apply the http://en.wikipedia.org/wiki/Dependency_inversion_principle[dependency inversion principle] to ensure that the modules of your application have acyclic dependencies; but in the UI it can still appear as if there are bidirectional dependencies between those modules. The lack of bidirectional dependencies can help save your app degrading into a http://en.wikipedia.org/wiki/Big_ball_of_mud[big ball of mud].
-
-Finally, note that the layout of contributed actions/collections/properties can be specified using the `.layout.json` file (and it is highly recommended that you do so).
-
-=== Contributed Actions
-
-* Write a new domain service
-** by convention, called "XxxContributions"
-** annotate with xref:_ug_reference-annotations_manpage-DomainService_nature[`@DomainService(nature=NatureOfService.VIEW_CONTRIBUTIONS_ONLY)`]
-*** indicates that all of the service's actions should _not_ be included in the main application menu bar
-*** should be rendered "as if" an action of the entity
-* Write an action accepting >1 args:
-** one being a domain entity
-** other being a primitive or String
-
-=== Contributed Collections
-
-* Write a new domain service (or update the one previously)
-* Write a query-only action accepting exactly 1 arg (a domain entity)
-* returning a collection, list or set
-* For this action:
-** add the xref:_ug_reference-annotations_manpage-ActionLayout_contributedAs[`@ActionLayout(contributedAs=ASSOCIATION)`] annotation
-** should be rendered in the UI "as if" a collection of the entity
-* use `.layout.json` to position as required
-
-
-=== Contributed Properties
-
-* As for contributed collections, write a new domain service with a query-only action accepting exactly 1 arg (a domain entity); except:
-** returning a scalar value rather than a collection
-* For this action:
-** add the xref:_ug_reference-annotations_manpage-ActionLayout_contributedAs[`@ActionLayout(contributedAs=ASSOCIATION)`] annotation
-* should be rendered in the UI "as if" a property of the entity
-* use `.layout.json` to position as required
-
-
-
-== Using the Event Bus
-
-Another way in which Apache Isis helps you keep your application nicely modularized is through its event bus. Each action invocation, or property modification, can be used to generate a succession of events that allows subscribers to veto the interaction (the see it/use it/do it rules) or, if the action is allowed, to perform work prior to the execution of the action or after the execution of the action.
-
-Under the covers Isis uses the https://code.google.com/p/guava-libraries/wiki/EventBusExplained[Guava event bus] and subscribers (always domain services) subscribe by writing methods annotated with `@com.google.common.eventbus.Subscribe` annotation.
-
-By default the events generated are `ActionDomainEvent.Default` (for actions) and `PropertyDomainEvent.Default` (for properties). Subclasses of these can be specified using the xref:_ug_reference-annotations_manpage-Action_domainEvent[`@Action(domainEvent=...)`] or xref:_ug_reference-annotations_manpage-Property_domainEvent[`Property(domainEvent=...)`] for properties.
-
-
-Using the guidance in the docs for the xref:_ug_reference-services-api_manpage-EventBusService[`EventBusService`]:
-
-* write a domain service subscriber to subscribe to events
-* use the domain service to perform log events
-* use the domain service to veto actions (hide/disable or validate)
-
-
-
-== Bulk actions
-
-Bulk actions are actions that can be invoked on a collection of actions, that is on collections returned by invoking an action. Actions are specified as being bulk actions using the xref:_ug_reference-annotations_manpage-Action_invokeOn[`@action(invokeOn=OBJECT_AND_COLLECTION)`] annotation.
-
-[NOTE]
-====
-Note that currently (1.8.0) only no-arg actions can be specified as bulk actions.
-====
-
-Thus:
-* Write a no-arg action for your domain entity, annotate with `@Action(invokeOn=...)`
-* Inject the xref:_ug_reference-services-api_manpage-ActionInvocationContext[`ActionInteractionContext`] (request-scoped) service
-* Use the `ActionInteractionContext` service to determine whether the action was invoked in bulk or as a regular action.
-* return null if invoked on a collection; the Wicket viewer will go back to the original collection
-** (if return non-null, then Wicket viewer will navigate to the object of the last invocation� generally not what is required)
-
-The similar xref:_ug_reference-services-api_manpage-ScratchPad[`ScratchPad`] (request-scoped) domain service is a good way to share information between bulk action invocations:
-
-* Inject the `ScratchPad` domain service
-* for each action, store state (eg a running total)
-* in the last invoked bulk action, perform some aggregate processing (eg calculate the average) and return
-
-
-
-
-== Performance tuning
-
-The xref:_ug_reference-services-api_manpage-QueryResultsCache[`QueryResultsCache`] (request-scoped) domain service allows arbitrary objects to be cached for the duration of a request.
-
-This can be helpful for "naive" code which would normally make the same query within a loop.
-
-* optional: inject the `QueryResultsCache` service, invoke queries "through" the cache API
-* remember that the service is request-scoped, so it only really makes sense to use this service for code that invokes queries within a loop
-
-
-
-
-== Extending the Wicket UI
-
-Each element in the Wicket viewer (entity form, properties, collections, action button etc) is a component, each created by a internal API (`ComponentFactory`, described xref:_ug_extending_wicket-viewer[here]). For collections there can be multiple views, and the Wicket viewer provides a view selector drop down (top right of each collection panel).
-
-Moreover, we can add additional views. In this section we'll explore some of these, already provided through http://www.isisaddons.org/[Isis addons] (not ASF).
-
-=== Excel download
-
-The https://github.com/isisaddons/isis-wicket-excel[Excel download add-on] allows the collection to be downloaded as an Excel spreadsheet (`.xlsx`).
-
-* Use the instructions on the add-on module's README to add in the excel download module (ie: update the POM).
-
-=== Fullcalendar2
-
-The https://github.com/isisaddons/isis-wicket-fullcalendar2[Fullcalendar2 download add-on] allows entities to be rendered in a full-page calendar.
-
-* Use the instructions on the add-on module's README to add in the fullcalendar2 module (ie: update the POM).
-* on one of your entities, implement either the `CalendarEventable` interface or the (more complex) `Calendarable` interface.
-* update fixture scripts to populate any new properties
-* when the app is run, a collection of the entities should be shown within a calendar view
-
-=== gmap3
-
-The https://github.com/isisaddons/isis-wicket-gmap3[Gmap3 download add-on] allows entities that implement certain APIs to be rendered in a full-page gmap3.
-
-* Use the instructions on the add-on module's README to add in the gmap3 module (ie: update the POM).
-* on one of your entities, implement the `Locatable` interface
-* update fixture scripts to populate any new properties
-* when the app is run, a collection of the entities should be shown within a map view
-
-
-
-
-== Add-on modules (optional)
-
-In addition to providing Wicket viewer extensions, http://www.isisaddons.org/[Isis addons] also has a large number of modules. These address such cross-cutting concerns as security, command (profiling), auditing and publishing.
-
-* (optional): follow the https://github.com/isisaddons/isis-module-security[security module] README or http://youtu.be/bj8735nBRR4[screencast]
-* (optional): follow the https://github.com/isisaddons/isis-module-command[command module] README or http://youtu.be/g01tK58MxJ8[screencast]
-* (optional): follow the https://github.com/isisaddons/isis-module-audit[auditing module] README or (the same) http://youtu.be/g01tK58MxJ8[screencast]
-
-
-
-
-== View models
-
-In most cases users can accomplish the business operations they need by invoking actions directly on domain entities. For some high-volume or specialized uses cases, though, there may be a requirement to bring together data or functionality that spans several entities.
-
-Also, if using 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, Isis therefore allows you to write a view model, either by annotating the class with xref:_ug_reference-annotations_manpage-ViewModel[`@ViewModel`] or (for more control) by implementing the xref:_ug_reference-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)
-
-
-
-
-== Testing
-
-Up to this point we've been introducing the features of Isis and building out our domain application, but with little regard to testing. Time to fix that.
-
-
-=== Unit testing
-
-Unit testing domain entities and domain services is easy; just use JUnit and mocking libraries to mock out interactions with domain services.
-
-https://code.google.com/p/mockito/[Mockito] seems to be the current favourite among Java developers for mocking libraries, but if you use JMock then you'll find we provide a `JUnitRuleMockery2` class and a number of other utility classes, documented xref:_unit_test_support[here].
-
-* write some unit tests (adapt from the unit tests in the `myapp-dom` Maven module).
-
-
-
-=== Integration testing
-
-Although unit tests are easy to write and fast to execute, integration tests are more valuable: they test interactions of the system from the outside-in, simulating the way in which the end-users use the application.
-
-Earlier on in the tutorial we commented out the `myapp-integtests` module. Let's commented it back in. In the parent `pom.xml`:
-
-[source,xml]
-----
-<modules>
- <module>dom</module>
- <module>fixture</module>
- <!--
- <module>integtests</module>
- -->
- <module>webapp</module>
-</modules>
-----
-
-change back to:
-
-[source,xml]
-----
-<modules>
- <module>dom</module>
- <module>fixture</module>
- <module>integtests</module>
- <module>webapp</module>
-</modules>
-----
-
-There will probably be some compile issues to fix up once you've done this; comment out all code that doesn't compile.
-
-Isis has great support for writing xref:_ug_testing_integ-test-support[integration tests]; well-written integration tests should leverage fixture scripts and use the xref:_ug_reference-services-api_manpage-WrapperFactory[`@WrapperFactory`] domain service.
-
-* use the tests from the original archetype and the documentation on the website to develop integration tests for your app's functionality.
-
-
-
-
-== Customising the REST API
-
-The REST API generated by Isis conforms to the Restful Objects specification. Isis 1.8.0 provides experimental support to allow the representations to be customized.
-
-* as per xref:_ug_restfulobjects-viewer_configuration-properties_simplified-object[the documentation], configure the Restful Objects viewer to generate a simplified object representation: +
-+
-[source,ini]
-----
-isis.viewer.restfulobjects.objectPropertyValuesOnly=true
-----
-
-
-
-
-== Configuring to use an external database
-
-If you have an external database available, then update the `pom.xml` for the classpath and update the JDBC properties in `WEB-INF\persistor.properties` to point to your database.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer.adoc
deleted file mode 100644
index ff0bfce..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer.adoc
+++ /dev/null
@@ -1,30 +0,0 @@
-[[_ug_wicket-viewer]]
-= 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/
-
-This chapter describes end-user features, configuration and customization of the Wicket viewer.
-
-Note that extending the Wicket viewer is described in the <<Extending>> chapter.
-
-
-include::_ug_wicket-viewer_features.adoc[leveloffset=+1]
-
-include::_ug_wicket-viewer_configuration-properties.adoc[leveloffset=+1]
-
-include::_ug_wicket-viewer_request-parameters.adoc[leveloffset=+1]
-
-include::_ug_wicket-viewer_layout.adoc[leveloffset=+1]
-
-include::_ug_wicket-viewer_customisation.adoc[leveloffset=+1]
-
-
-
-== Extending the viewer
-
-APIs to extend the Wicket viewer are discussed in the xref:_ug_extending[Extending] chapter.
-
-
-include::_ug_wicket-viewer_isis-addons.adoc[leveloffset=+1]
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_configuration-properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_configuration-properties.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_configuration-properties.adoc
deleted file mode 100644
index 8d6523a..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_configuration-properties.adoc
+++ /dev/null
@@ -1,112 +0,0 @@
-[[_ug_wicket-viewer_configuration-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/
-
-
-Wicket configuration properties alter the way in which Isis' Wicket viewer renders domain objects. They are typically stored in `WEB-INF/viewer_wicket.properties`.
-
-[NOTE]
-====
-To tell Isis that the Wicket viewer is in use (and should therefore search for the `viewer_wicket.properties` file), add the following to `WEB-INF/web.xml`:
-
-[source, xml]
-----
-<context-param>
- <param-name>isis.viewers</param-name>
- <param-value>wicket</param-value>
-</context-param>
-----
-
-====
-
-If you prefer you can place all configuration properties into `WEB-INF/isis.properties` (the configuration properties from all config files are merged together).
-
-
-.Wicket Viewer Configuration Properties
-[cols="2a,1,3", options="header"]
-|===
-|Property
-|Value +
-(_default value_)
-|Description
-
-|`isis.viewer.wicket.` +
-`bookmarkedPages`
-| +ve int (`_15_`)
-| number of pages to bookmark
-
-|`isis.viewer.wicket.` +
-`disableDependentChoiceAutoSelection`
-| `true`,`false` (`_false_`)
-| For dependent choices, whether to automatically select the first dependent (eg subcategory) when the parameter on which it depends (category) changes.
-
-|`isis.viewer.wicket.` +
-`disableModalDialogs`
-| `true`,`false` (`_false_`)
-| By default the Isis Wicket viewer uses a modal dialog for action parameters. Before this feature was implemented (prior to 1.4.0), Isis rendered action parameters on its own page. This property re-enables the old behaviour.
-
-Note that action pages are still used for bookmarked actions.
-
-|`isis.viewer.wicket.` +
-`maxTitleLengthInParentedTables`
-| +ve integer, (`_12_`)
-| See discussion xref:_ug_wicket-viewer_configuration-properties_abbreviating-titles[below].
-
-|`isis.viewer.wicket.` +
-`maxTitleLengthInStandaloneTables`
-| +ve integer, (`_12_`)
-| See discussion xref:_ug_wicket-viewer_configuration-properties_abbreviating-titles[below].
-
-|`isis.viewer.wicket.` +
-`maxTitleLengthInTables`
-| +ve integer, (`_12_`)
-| See discussion xref:_ug_wicket-viewer_configuration-properties_abbreviating-titles[below].
-
-|`isis.viewer.wicket.` +
-`regularCase`
-| `true`,`false` (`_false_`)
-| Ignored for 1.8.0+; in earlier versions forced regular case rather than title case in the UI
-
-|`isis.viewer.wicket.` +
-`stripWicketTags`
-| `true`,`false` (`_true_`)
-| Whether to force Wicket tags to be stripped in prototype/development mode. See discussion xref:_ug_wicket-viewer_configuration-properties_stripped-wicket-tags[below].
-
-|`isis.viewer.wicket.` +
-`suppressPasswordReset`
-| `true`,`false` (`_false_`)
-|If user registration is enabled, whether to suppress the "password reset" link on the login page. See discussion xref:_ug_wicket-viewer_configuration-properties_suppressing-password-reset[below].
-
-|`isis.viewer.wicket.` +
-`suppressRememberMe`
-| `true`,`false` (`_false_`)
-|Whether to suppress "remember me" checkbox on the login page.
-
-|`isis.viewer.wicket.` +
-`suppressSignUp`
-| `true`,`false` (`_false_`)
-|If user registration is enabled, whether to suppress the "sign up" link on the login page. See discussion xref:_ug_wicket-viewer_configuration-properties_suppressing-sign-up[below].
-
-|`isis.viewer.wicket.` +
-`themes.enabled`
-| comma separated list ...
-| ... of bootswatch themes. Only applies if `themes.showChooser`==`true`. See discussion xref:_ug_wicket-viewer_configuration-properties_showing-theme-chooser[below].
-
-|`isis.viewer.wicket.` +
-`themes.showChooser`
-| `true`,`false` (`_false_`)
-| Whether to show chooser for Bootstrap themes. See discussion xref:_ug_wicket-viewer_configuration-properties_showing-theme-chooser[below]
-
-|===
-
-
-
-include::_ug_wicket-viewer_configuration-properties_abbreviating-titles.adoc[leveloffset=+1]
-include::_ug_wicket-viewer_configuration-properties_suppressing-remember-me.adoc[leveloffset=+1]
-include::_ug_wicket-viewer_configuration-properties_suppressing-sign-up.adoc[leveloffset=+1]
-include::_ug_wicket-viewer_configuration-properties_suppressing-password-reset.adoc[leveloffset=+1]
-include::_ug_wicket-viewer_configuration-properties_stripped-wicket-tags.adoc[leveloffset=+1]
-include::_ug_wicket-viewer_configuration-properties_showing-theme-chooser.adoc[leveloffset=+1]
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_configuration-properties_abbreviating-titles.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_configuration-properties_abbreviating-titles.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_configuration-properties_abbreviating-titles.adoc
deleted file mode 100644
index fdf2878..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_configuration-properties_abbreviating-titles.adoc
+++ /dev/null
@@ -1,33 +0,0 @@
-[[_ug_wicket-viewer_configuration-properties_abbreviating-titles]]
-= Abbreviating/suppressing titles 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/
-
-
-
-Objects whose title is overly long can be cumbersome in titles. The Wicket viewer has a xref:_ug_wicket-viewer_features_titles-in-tables[mechanism to automatically shorten] the titles of objects specified using `@Title`. As an alternative/in addition, the viewer can also be configured to simply truncate titles longer than a certain length.
-
-The properties themselves are:
-
-[source,ini]
-----
-isis.viewer.wicket.maxTitleLengthInStandaloneTables=20
-isis.viewer.wicket.maxTitleLengthInParentedTables=8
-----
-
-If you wish to use the same value in both cases, you can also specify just:
-
-[source,ini]
-----
-isis.viewer.wicket.maxTitleLengthInTables=15
-----
-
-This is used as a fallback if the more specific properties are not provided.
-
-If no properties are provided, then the Wicket viewer defaults to abbreviating titles to a length of `12`.
-
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_configuration-properties_showing-theme-chooser.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_configuration-properties_showing-theme-chooser.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_configuration-properties_showing-theme-chooser.adoc
deleted file mode 100644
index 884c3fd..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_configuration-properties_showing-theme-chooser.adoc
+++ /dev/null
@@ -1,43 +0,0 @@
-[[_ug_wicket-viewer_configuration-properties_showing-theme-chooser]]
-= Showing a theme chooser
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 Wicket viewer uses http://getbootstrap.com/[Bootstrap] styles and components (courtesy of the https://github.com/l0rdn1kk0n/wicket-bootstrap[Wicket Bootstrap] integration).
-
-Unless a xref:_ug_wicket-viewer_customisation_default-theme[default theme has been specified], the viewer uses the default bootstrap theme. However,
-the viewer can also be configured to allow the end-user to switch theme to another theme, in particular one of those provided by http://bootswatch.com[bootswatch.com].
-
-This is done using the following configuration property (in `WEB-INF/viewer_wicket.properties`):
-
-[source,ini]
-----
-isis.viewer.wicket.themes.showChooser=true
-----
-
-.Example 1
-image::{_imagesdir}wicket-viewer/theme-chooser/example-1.png[width="720px",link="{_imagesdir}wicket-viewer/theme-chooser/example-1.png"]
-
-
-.Example 2:
-image::{_imagesdir}wicket-viewer/theme-chooser/example-2.png[width="720px",link="{_imagesdir}wicket-viewer/theme-chooser/example-2.png"]
-
-It is also possible to restrict the themes shown to some subset of those in bootswatch. This is done using a further
-property:
-
-[source,ini]
-----
-isis.viewer.wicket.themes.enabled=bootstrap-theme,Cosmo,Flatly,Darkly,Sandstone,United
-----
-
-where the value is the list of themes (from http://bootswatch.com[bootswatch.com]) to be made available.
-
-[TIP]
-====
-You can also develop and install a custom themes (eg to fit your company's look-n-feel/interface guidelines); see the xref:_ug_extending_wicket-viewer_custom-bootstrap-theme[Extending] chapter for further details.
-====
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_configuration-properties_stripped-wicket-tags.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_configuration-properties_stripped-wicket-tags.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_configuration-properties_stripped-wicket-tags.adoc
deleted file mode 100644
index cb653bd..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_configuration-properties_stripped-wicket-tags.adoc
+++ /dev/null
@@ -1,26 +0,0 @@
-[[_ug_wicket-viewer_configuration-properties_stripped-wicket-tags]]
-= Stripped Wicket tags
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 Isis Wicket viewer will always strip wicket tags. However, when running in prototype mode, this behaviour can be overridden using a configuration property:
-
-[source,ini]
-----
-isis.viewer.wicket.stripWicketTags=false
-----
-
-[NOTE]
-====
-In 1.7.0 and earlier, the behaviour is different; the Isis Wicket viewer will preserve wicket tags when running in Isis' prototype/development mode, but will still strip wicket tags in Isis' server/deployment mode.
-
-We changed the behaviour in 1.8.0 because we found that Internet Explorer can be sensitive to the presence of Wicket tags.
-====
-
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_configuration-properties_suppressing-password-reset.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_configuration-properties_suppressing-password-reset.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_configuration-properties_suppressing-password-reset.adoc
deleted file mode 100644
index b305948..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_configuration-properties_suppressing-password-reset.adoc
+++ /dev/null
@@ -1,47 +0,0 @@
-[[_ug_wicket-viewer_configuration-properties_suppressing-password-reset]]
-= Suppressing 'password reset'
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 xref:_user_registration[user registration] has been configured, then the Wicket viewer allows the user to sign-up a new account and to reset their password from the login page.
-
-The 'password reset' link can be suppressed, if required, by setting a configuration flag.
-
-
-
-== Screenshots
-
-With 'password reset' not suppressed (the default):
-
-image::{_imagesdir}wicket-viewer/suppress-password-reset/login-page-default.png[width="300px",link="{_imagesdir}wicket-viewer/suppress-password-reset/login-page-default.png"]
-
-and with the link suppressed:
-
-image::{_imagesdir}wicket-viewer/suppress-password-reset/login-page-suppress-password-reset.png[width="300px",link="{_imagesdir}wicket-viewer/suppress-password-reset/login-page-suppress-password-reset.png"]
-
-
-
-== Configuration
-
-To suppress the 'password reset' link, add the following configuration flag:
-
-[source,ini]
-----
-isis.viewer.wicket.suppressPasswordReset=true
-----
-
-Typically this should be added to the `viewer_wicket.properties` file (in `WEB-INF`), though you can add to `isis.properties` if you wish.
-
-
-
-== See also
-
-The xref:_ug_wicket-viewer_configuration-properties_suppressing-sign-up[sign up link] can be suppressed in a similar manner.
-
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_configuration-properties_suppressing-remember-me.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_configuration-properties_suppressing-remember-me.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_configuration-properties_suppressing-remember-me.adoc
deleted file mode 100644
index 887a572..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_configuration-properties_suppressing-remember-me.adoc
+++ /dev/null
@@ -1,35 +0,0 @@
-[[_ug_wicket-viewer_configuration-properties_suppressing-remember-me]]
-= Suppressing 'remember me'
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 'remember me' checkbox on the login page can be suppressed, if required, by setting a configuration flag.
-
-
-
-== Screenshots
-
-With 'remember me' not suppressed (the default):
-
-image::{_imagesdir}wicket-viewer/suppress-remember-me/login-page-default.png[width="300px",link="{_imagesdir}wicket-viewer/suppress-remember-me/login-page-default.png"]
-
-and with the checkbox suppressed:
-
-image::{_imagesdir}wicket-viewer/suppress-remember-me/login-page-suppress-remember-me.png[width="300px",link="{_imagesdir}wicket-viewer/suppress-remember-me/login-page-suppress-remember-me.png"]
-
-
-
-== Configuration
-
-To suppress the 'remember me' checkbox, add the following configuration flag:
-
-[source,ini]
-----
-isis.viewer.wicket.suppressRememberMe=true
-
-----
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_configuration-properties_suppressing-sign-up.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_configuration-properties_suppressing-sign-up.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_configuration-properties_suppressing-sign-up.adoc
deleted file mode 100644
index 0455cae..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_configuration-properties_suppressing-sign-up.adoc
+++ /dev/null
@@ -1,49 +0,0 @@
-[[_ug_wicket-viewer_configuration-properties_suppressing-sign-up]]
-= Suppressing 'sign up'
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 xref:_user_registration[user registration] has been configured, then the Wicket viewer allows the user to sign-up a new account and to reset their password from the login page.
-
-The 'sign up' link can be suppressed, if required, by setting a configuration flag.
-
-
-
-
-== Screenshots
-
-With 'sign up' not suppressed (the default):
-
-image::{_imagesdir}wicket-viewer/suppress-sign-up/login-page-default.png[width="300px",link="{_imagesdir}wicket-viewer/suppress-sign-up/login-page-default.png"]
-
-and with the link suppressed:
-
-image::{_imagesdir}wicket-viewer/suppress-sign-up/login-page-suppress-sign-up.png[width="300px",link="{_imagesdir}wicket-viewer/suppress-sign-up/login-page-suppress-sign-up.png"]
-
-
-
-
-== Configuration
-
-To suppress the 'sign up' link, add the following configuration flag:
-
-[source,ini]
-----
-isis.viewer.wicket.suppressSignUp=true
-----
-
-
-
-== See also
-
-The xref:_ug_wicket-viewer_configuration-properties_suppressing-password-reset[password reset link] can be suppressed in a similar manner.
-
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_customisation.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_customisation.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_customisation.adoc
deleted file mode 100644
index 9ad143e..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_customisation.adoc
+++ /dev/null
@@ -1,18 +0,0 @@
-[[_ug_wicket-viewer_customisation]]
-= Customisation
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-include::_ug_wicket-viewer_customisation_brand-logo.adoc[leveloffset=+1]
-include::_ug_wicket-viewer_customisation_default-theme.adoc[leveloffset=+1]
-include::_ug_wicket-viewer_customisation_welcome-page.adoc[leveloffset=+1]
-include::_ug_wicket-viewer_customisation_about-page.adoc[leveloffset=+1]
-include::_ug_wicket-viewer_customisation_tweaking-css-classes.adoc[leveloffset=+1]
-include::_ug_wicket-viewer_customisation_tweaking-css-classes.adoc[leveloffset=+1]
-include::_ug_wicket-viewer_customisation_using-different-css-file.adoc[leveloffset=+1]
-include::_ug_wicket-viewer_customisation_custom-javascript.adoc[leveloffset=+1]
-include::_ug_wicket-viewer_customisation_auto-refresh.adoc[leveloffset=+1]
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_customisation_about-page.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_customisation_about-page.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_customisation_about-page.adoc
deleted file mode 100644
index 8d46887..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_customisation_about-page.adoc
+++ /dev/null
@@ -1,121 +0,0 @@
-[[_ug_wicket-viewer_customisation_about-page]]
-= About page
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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' Wicket viewer has an About page that, by default, will provide a dump of the JARs that make up the webapp. This page will also show the manifest attributes of the WAR archive itself, if there are any. One of these attributes may also be used as the application version number.
-
-
-== Screenshot
-
-Here's what the About page looks like with this configuration added:
-
-image::{_imagesdir}wicket-viewer/about-page/about-page.png[width="800px",link="{_imagesdir}wicket-viewer/about-page/about-page.png"]
-
-[NOTE]
-====
-Note that this screenshot shows an earlier version of the xref:_ug_wicket-viewer[Wicket viewer] UI (specifically, pre 1.8.0).
-====
-
-Note that the `Build-Time` attribute has been used as the version number. The Wicket viewer is hard-coded to search for specific attributes and use as the application version. In order, it searches for:
-
-* `Implementation-Version`
-* `Build-Time`
-
-If none of these are found, then no version is displayed.
-
-== Configuration
-
-[TIP]
-====
-This configuration is included within the xref:_ug_getting-started_simpleapp-archetype[SimpleApp archetype].
-====
-
-=== Adding attributes to the WAR's manifest
-
-Add the following to the webapp's `pom.xml` (under `<build>/<plugins>`):
-
-[source,xml]
-----
-<plugin>
- <groupId>org.codehaus.mojo</groupId>
- <artifactId>build-helper-maven-plugin</artifactId>
- <version>1.5</version>
- <executions>
- <execution>
- <phase>validate</phase>
- <goals>
- <goal>maven-version</goal>
- </goals>
- </execution>
- </executions>
-</plugin>
-
-<plugin>
- <artifactId>maven-war-plugin</artifactId>
- <configuration>
- <archive>
- <manifest>
- <addDefaultImplementationEntries>true</addDefaultImplementationEntries>
- </manifest>
- <manifestEntries>
- <Build-Time>${maven.build.timestamp}</Build-Time>
- <Build-Number>${buildNumber}</Build-Number>
- <Build-Host>${agent.name}</Build-Host>
- <Build-User>${user.name}</Build-User>
- <Build-Maven>Maven ${maven.version}</Build-Maven>
- <Build-Java>${java.version}</Build-Java>
- <Build-OS>${os.name}</Build-OS>
- <Build-Label>${project.version}</Build-Label>
- </manifestEntries>
- </archive>
- </configuration>
- <executions>
- <execution>
- <phase>package</phase>
- <goals>
- <goal>war</goal>
- </goals>
- <configuration>
- <classifier>${env}</classifier>
- </configuration>
- </execution>
- </executions>
-</plugin>
-----
-
-If you then build the webapp from the Maven command line (`mvn clean package`), then the WAR should contain a `META-INF/MANIFEST.MF` with those various attribute entries.
-
-=== Exporting the attributes into the app
-
-The manifest attributes are provided to the rest of the application by way of the Wicket viewer's integration with Google Guice.
-
-In your subclass of `IsisWicketApplication`, there is a method `newIsisWicketModule()`. In this method you need to bind an `InputStream` that will read the manifest attributes. This is all boilerplate so you can just copy-n-paste:
-
-[source,java]
-----
-@Override
-protected Module newIsisWicketModule() {
- ...
- final Module simpleappOverrides = new AbstractModule() {
- @Override
- protected void configure() {
- ...
- bind(InputStream.class)
- .annotatedWith(Names.named("metaInfManifest"))
- .toProvider(Providers.of(
- getServletContext().getResourceAsStream("/META-INF/MANIFEST.MF")));
- }
- };
- ...
-}
-----
-
-With that you should be good to go!
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_customisation_auto-refresh.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_customisation_auto-refresh.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_customisation_auto-refresh.adoc
deleted file mode 100644
index 2c8f645..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_customisation_auto-refresh.adoc
+++ /dev/null
@@ -1,35 +0,0 @@
-[[_ug_wicket-viewer_customisation_auto-refresh]]
-= Auto-refresh page
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 requirement from the users mailing list:
-
-pass:[<div class="extended-quote-first"><p>]Suppose you want to build a monitoring application, eg for an electricity grid. Data is updated in the background (eg via the Restful Objects REST API). What is needed is the ability to show an entity that includes a http://github.com/isisaddons/isis-wicket-gmap3[map], and have it auto-refresh every 5 seconds or so.
-pass:[</p></div>]
-
-Here's one (somewhat crude, but workable) way to accomplish this.
-
-* First, update the domain object to return custom CSS: +
-+
-[source,java]
-----
-public class MyDomainObject {
- ...
- public String cssClass() {return "my-special-auto-updating-entity"; }
- ...
-}
-----
-
-* Then, use javascript in `webapp/src/main/webapp/scripts/application.js` to reload: +
-+
-[source,javascript]
-----
-$(function() {
- if ($(".my-special-auto-updating-entity").length) {
- setTimeout(function() {document.location.reload();}, 5000); // 1000 is 5 sec
- }
-});
-----
[41/45] isis git commit: ISIS-1133: breaking out reference guide and
devenv guide;
moving appendices' release notes and migration notes to other docs;
improving the documentation page.
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_autoCompleteRepository.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_autoCompleteRepository.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_autoCompleteRepository.adoc
new file mode 100644
index 0000000..c000054
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_autoCompleteRepository.adoc
@@ -0,0 +1,76 @@
+[[_rg_annotations_manpage-DomainObject_autoCompleteRepository]]
+= `autoCompleteRepository()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `autoCompleteRepository()` attribute nominates a single method on a domain service as the fallback means for lookuping up instances of the domain object using a simple string.
+
+For example, this might search for a customer by their name or number. Or it could search for a country based on its ISO-3 code or user-friendly name.
+
+
+[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.
+====
+
+
+For example:
+
+[source,java]
+----
+@AutoComplete(
+ autoCompleteRepository=Customers.class
+)
+public class Customer extends AbstractDomainObject {
+ ....
+}
+----
+
+where:
+
+[source,java]
+----
+public interface Customers {
+ @Programmatic // <1>
+ List<Customer> autoComplete(String search); // <2>
+ ...
+}
+----
+<1> do not expose in the UI
+<2> is assumed to be called "autoComplete", and accepts a single string
+
+
+
+== `autoCompleteAction()`
+
+As noted above, by default the method invoked on the repository is assumed to be called "autoComplete". The optional `autoCompleteAction()` attribute allows the method on the repository to be overridden.
+
+
+For example:
+
+[source,java]
+----
+@AutoComplete(
+ autoCompleteRepository=Customers.class,
+ autoCompleteAction="findByCustomerName"
+)
+public class Customer extends AbstractDomainObject {
+ ....
+}
+----
+
+where in this case `findByCustomerName` might be an existing method already defined:
+
+[source,java]
+----
+public interface Customers {
+ @Action(semantics=SemanticsOf.SAFE)
+ List<Customer> findByCustomerName(@ParameterLayout(named="name") String name);
+ ...
+}
+----
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_bounded.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_bounded.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_bounded.adoc
new file mode 100644
index 0000000..28b36f8
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_bounded.adoc
@@ -0,0 +1,36 @@
+[[_rg_annotations_manpage-DomainObject_bounded]]
+= `bounded()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 domain classes are immutable to the user, and moreover have only a fixed number of instances. Often these are "reference" ("standing") data, or lookup data/pick lists. Typical examples could include categories, countries, states, and tax or interest rate tables.
+
+Where the number of instances is relatively small, ie bounded, then the `bounded()` attribute can be used as a hint. For such domain objects the framework will automatically allow instances to be selected; xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] displays these as a drop-down list.
+
+
+For example:
+
+[source,java]
+----
+@DomainObject(
+ bounded=true,
+ editing=Editing.DISABLED // <1>
+)
+public class Currency {
+ ...
+}
+----
+<1> This attribute is commonly combined with `editing=DISABLED` to enforce the fact that reference data is immutable
+
+
+[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:rg.adoc#_rg_annotations_manpage-DomainObject_autoComplete[`@DomainObject#autoComplete()`] attribute instead.
+====
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_editing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_editing.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_editing.adoc
new file mode 100644
index 0000000..6e8d5cd
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_editing.adoc
@@ -0,0 +1,61 @@
+[[_rg_annotations_manpage-DomainObject_editing]]
+= `editing()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `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:ug.adoc#_ug_runtime_configuring-core[configuration property] `isis.objects.editing` is used to determine the whether the object is modifiable:
+
+* `true` +
++
+the object's properties and collections are modifiable.
+
+* `false` +
++
+the object's properties and collections are read-only, ie _not_ modifiable.
+
+If there is no configuration property in `isis.properties` then object are assumed to be modifiable.
+
+[TIP]
+====
+In other words, editing can be disabled globally for an application by setting:
+
+[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.
+====
+
+The related `editingDisabledReason()` attribute specifies the a hard-coded reason why the object's properties and collections cannot be modified directly.
+
+
+
+This default can be overridden on an object-by-object basis; if `editing()` is set to `ENABLED` then the object's properties and collections are editable irrespective of the configured value; if set to `DISABLED` then the object's properties and collections are not editable irrespective of the configured value.
+
+For example:
+
+[source,java]
+----
+@DomainObject(
+ editing=Editing.DISABLED,
+ editingDisabledReason="Reference data, so cannot be modified"
+)
+public class Country {
+ ...
+}
+----
+
+[TIP]
+====
+Another interesting example of immutable reference data is to define an entity to represent individual dates; after all, for a system with an expected lifetime of 20 years that equates to only 7,300 days, a comparatively tiny number of rows to hold in a database.
+====
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_nature.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_nature.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_nature.adoc
new file mode 100644
index 0000000..da3a7f8
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_nature.adoc
@@ -0,0 +1,59 @@
+[[_rg_annotations_manpage-DomainObject_nature]]
+= `nature()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `nature()` attribute is used to characterize the domain object as either an entity (part of the domain layer) or as a view model (part of the application layer). If the domain object should be thought of as an entity, it also captures how the persistence of that entity is managed.
+
+For example:
+
+[source,java]
+----
+@DomainObject(nature=Nature.VIEW_MODEL)
+public class PieChartAnalysis {
+ ...
+}
+----
+
+Specifically, the nature must be one of:
+
+* `NOT_SPECIFIED,` +
++
+(the default); specifies no paricular semantics for the domain class.
+
+* `JDO_ENTITY` +
++
+indicates that the domain object is an entity whose persistence is managed internally by Isis, using the JDO/DataNucleus objectstore.
+
+* `EXTERNAL_ENTITY` +
++
+indicates that the domain objecct is a wrapper/proxy/stub (choose your term) to an entity that is managed by some related external system. For example, the domain object may hold just the URI to a RESTful resource of some third party REST service, or the id of some system accessible over SOAP. +
++
+The identity of an external 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.
+
+* `INMEMORY_ENTITY` +
++
+indicates that the domain object is a wrapper/proxy/stub to a "synthetic" entity, for example one that is constructed from some sort of internal memory data structure. +
++
+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.
+
+* `VIEW_MODEL` +
++
+indicates that the domain object is conceptually part of the application layer, and exists to surfaces behaviour and/or state that is aggregate of one or more domain entities.
+
+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:rg.adoc#_rg_annotations_manpage-ViewModel[`@ViewModel`] or implement the xref:rg.adoc#_rg_classes_super_manpage-ViewModel[`ViewModel`] interface.
+
+
+[NOTE]
+====
+Under the covers Isis' support for `VIEW_MODEL`, `EXTERNAL_ENTITY` and `INMEMORY_ENTITY` domain objects is identical; the state of the object is encoded into its internal OID (represented ultimately as its URL), and is recreated directly from that URL.
+
+Because this particular implementation was originally added to Isis in support of view models, the term was also used for the logically different external entities and inmemory entities.
+
+The benefit of `nature()` is that it allows the developer to properly characterize the layer (domain vs application) that an entity lives, thus avoiding confusion as "view model" (the implementation technique) and "view model" (the application layer concept).
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_objectType.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_objectType.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_objectType.adoc
new file mode 100644
index 0000000..cabb478
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_objectType.adoc
@@ -0,0 +1,46 @@
+[[_rg_annotations_manpage-DomainObject_objectType]]
+= `objectType()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `objectType()` attribute is used to provide a unique alias for the object's class name.
+
+This value is used internally to generate a string representation of an objects identity (the `Oid`). This can appear in several contexts, including:
+
+* as the value of `o.a.i.applib.services.bookmark.Bookmark#getObjectType()`
+* in the `toString()` value of `Bookmark`
+* in the URLs of the xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer]
+* in the URLs of the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] (in general and in particular if xref:ug.adoc#_ug_wicket-viewer_features_hints-and-copy-url[copying URLs])
+* in XML snapshots generated by the xref:rg.adoc#_rg_services-api_manpage-XmlSnapshotService[`XmlSnapshotService`]
+
+
+For example:
+
+[source,java]
+----
+@DomainObject(
+ objectType="ORD"
+)
+public class Order {
+ ...
+}
+----
+
+If the object type has not been specified, then Isis will use the fully qualified class name of the entity.
+
+
+[TIP]
+====
+This might be obvious, but to make explicit: we recommend that you use namespaces of some form or other for object types.
+
+As noted above, if the object type has not been specified, then Isis will use the fully qualified class name of the entity. However, this is liable to change over time, for example if the code is refactored or (more fundamentally) if your company/organization reorganizes/renames itself/is acquired.
+
+We therefore strongly recommend that you specify an object type for all entities, either using `objectType()` or using the JDO xref:rg.adoc#_rg_annotations_manpage-PersistenceCapable[`@PersistenceCapable`] (with a `schema()` attribute) or xref:rg.adoc#_rg_annotations_manpage-Discriminator[`@Discriminator`] annotations. Specifying `@Discriminator` will override `@PersistenceCapable`, which in turn overrides `objectType()`. Using `@PersistenceCapable#schema()` is probably the best choice in most cases.
+====
+
+[NOTE]
+====
+If the object type is not unique across all domain classes then the framework will fail-fast and fail to boot. An error message will be printed in the log to help you determine which classes have duplicate object tyoes.
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_publishing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_publishing.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_publishing.adoc
new file mode 100644
index 0000000..4672235
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_publishing.adoc
@@ -0,0 +1,49 @@
+[[_rg_annotations_manpage-DomainObject_publishing]]
+= `publishing()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `publishing()` attribute determines whether and how a modified object instance is published via the registered implementation of a xref:rg.adoc#_rg_services-spi_manpage-PublishingService[`PublishingService`]). This attribute is also supported for xref:rg.adoc#_rg_annotations_manpage-Action_publishing[actions], where it controls whether action invocations 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:ug.adoc#_ug_runtime_configuring-core[configuration property] `isis.services.publish.objects` is used to determine the whether the action is published:
+
+* `all` +
++
+all changed objects are published
+
+* `none` +
++
+no changed objects are published
+
+If there is no configuration property in `isis.properties` then publishing is automatically enabled for domain objects.
+
+This default can be overridden on an object-by-object basis; if `publishing()` is set to `ENABLED` then changed instances of the domain class are published irrespective of the configured value; if set to `DISABLED` then the changed instances are _not_ published, again irrespective of the configured value.
+
+For example:
+
+[source,java]
+----
+@DomainObject(
+ publishing=Publishing.ENABLED // <1>
+)
+public class InterestRate {
+ ...
+}
+----
+<1> because set to enabled, will be published irrespective of the configured value.
+
+
+
+
+== `publishingPayloadFactory()`
+
+The (optional) related `publishingPayloadFactory()` specifies the class to use to create the (payload of the) event to be published by the publishing factory.
+
+Rather than simply broadcast that the object was changed, the payload factory allows a "fatter" payload to be instantiated that can eagerly push commonly-required information to all subscribers. For at least some subscribers this should avoid the necessity to query back for additional information.
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainService.adoc
new file mode 100644
index 0000000..0a5fd02
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainService.adoc
@@ -0,0 +1,64 @@
+[[_rg_annotations_manpage-DomainService]]
+= `@DomainService`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@DomainService` annotation indicates that the (concrete) class should be automatically instantiated as a domain service.
+
+Domain services with this annotation do NOT need to be registered explicitly in `isis.properties`; they will be
+discovered automatically on the CLASSPATH.
+
+The table below summarizes the annotation's attributes.
+
+.`@DomainService` attributes
+[cols="2,2,4a", options="header"]
+|===
+
+| Attribute
+| Values (default)
+| Description
+
+
+|xref:rg.adoc#_rg_annotations_manpage-DomainService_nature[`nature()`]
+|`VIEW`, `VIEW_MENU_ONLY`, `VIEW_CONTRIBUTIONS_ONLY`, `VIEW_REST_ONLY`, `DOMAIN` (`VIEW`)
+|the nature of this service: providing actions for menus, or as contributed actions, or for the xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects REST API], or neither
+
+
+|xref:rg.adoc#_rg_annotations_manpage-DomainService_repositoryFor[`repositoryFor()`]
+|
+|if this domain service acts as a repository for an entity type, specify that entity type. (This is currently informational only)
+
+
+|`menuOrder()`
+|
+|Deprecated in 1.8.0; use instead xref:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`]
+
+|===
+
+
+
+For example:
+
+[source,java]
+----
+@DomainService(
+ nature=NatureOfService.DOMAIN,
+ repositoryFor=Loan.class
+)
+public class LoanRepository {
+ @Programmatic
+ public List<Loan> findLoansFor(Borrower borrower) { ... }
+}
+----
+
+
+
+include::_rg_annotations_manpage-DomainService_nature.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-DomainService_repositoryFor.adoc[leveloffset=+1]
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainServiceLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainServiceLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainServiceLayout.adoc
new file mode 100644
index 0000000..671fd01
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainServiceLayout.adoc
@@ -0,0 +1,78 @@
+[[_rg_annotations_manpage-DomainServiceLayout]]
+= `@DomainServiceLayout`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@DomainServiceLayout` annotation applies to domain services, collecting together all view layout semantics within a single annotation.
+
+[TIP]
+====
+You will also find some additional material in the xref:rg.adoc#_rg_object-layout_application-menu[object layout] chapter.
+====
+
+
+The table below summarizes the annotation's attributes.
+
+.`@DomainServiceLayout` attributes
+[cols="2,2,4a", options="header"]
+|===
+
+| Attribute
+| Values (default)
+| Description
+
+
+|xref:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_menuBar[`menuBar()`]
+|`PRIMARY`, `SECONDARY`, `TERTIARY` (`PRIMARY`).
+|the menubar in which the menu that holds this service's actions should reside.
+
+
+|xref:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_menuOrder[`menuOrder()`]
+|
+|the order of the service's menu with respect to other service's.
+
+
+|xref:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_named[`named()`]
+|string, eg "Customers"
+|name of this class (overriding the name derived from its name in code)
+
+
+
+|===
+
+
+
+For example:
+
+[source,java]
+----
+@DomainService
+@DomainServiceLayout(
+ menuBar=MenuBar.PRIMARY,
+ menuOrder="100",
+ named="ToDos"
+)
+public class ToDoItems {
+ ...
+}
+----
+
+
+
+[NOTE]
+====
+Note that there is (currently) no support for specifying UI hints for domain services through the dynamic xref:rg.adoc#_rg_object-layout_dynamic[`.layout.json`] file (only for properties, collections and actions are supported).
+====
+
+
+
+include::_rg_annotations_manpage-DomainServiceLayout_menuBar.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-DomainServiceLayout_menuOrder.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-DomainServiceLayout_named.adoc[leveloffset=+1]
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainServiceLayout_menuBar.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainServiceLayout_menuBar.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainServiceLayout_menuBar.adoc
new file mode 100644
index 0000000..0a510c8
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainServiceLayout_menuBar.adoc
@@ -0,0 +1,43 @@
+[[_rg_annotations_manpage-DomainServiceLayout_menuBar]]
+= `menuBar()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `menuBar()` attribute is a hint to specify where on the application menu a domain service's actions should be rendered.
+
+For example:
+
+[source,java]
+----
+@DomainService
+@DomainServiceLayout(menuBar=MenuBar.PRIMARY)
+public class ToDoItems {
+ ...
+}
+----
+
+In the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer], domain services placed on the `PRIMARY` menu bar appears to the left:
+
+image::{_imagesdir}reference-annotations/DomainServiceLayout/menuBar-primary.png[width="720px",link="{_imagesdir}reference-annotations/DomainServiceLayout/menuBar-primary.png"]
+
+Domain services placed on the `SECONDARY` menu bar appear to the right:
+
+image::{_imagesdir}reference-annotations/DomainServiceLayout/menuBar-secondary.png[width="720px",link="{_imagesdir}reference-annotations/DomainServiceLayout/menuBar-secondary.png"]
+
+
+Domain services placed on the `TERTIARY` appear in the menu bar associated with the user's name (far top-right)
+
+image::{_imagesdir}reference-annotations/DomainServiceLayout/menuBar-tertiary.png[width="720px",link="{_imagesdir}reference-annotations/DomainServiceLayout/menuBar-tertiary.png"]
+
+
+The grouping of multiple domain services actions within a single drop-down is managed by the xref:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] attribute.
+
+
+[NOTE]
+====
+The xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer] does not support this attribute.
+====
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainServiceLayout_menuOrder.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainServiceLayout_menuOrder.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainServiceLayout_menuOrder.adoc
new file mode 100644
index 0000000..4687db8
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainServiceLayout_menuOrder.adoc
@@ -0,0 +1,74 @@
+[[_rg_annotations_manpage-DomainServiceLayout_menuOrder]]
+= `menuOrder()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `menuOrder()` attribute determines the ordering of a domain service's actions as menu items within a specified menu bar and top-level menu.
+
+
+The algorithm works as follows:
+
+* first, the xref:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_menuBar[`menuBar()`] determines which of the three menu bars the service's actions should be rendered
+* then, the domain service's top-level name (typically explicitly specified using xref:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_named[`named()`]) is used to determine the top-level menu item to be rendered on the menu bar
+* finally, if there is more than domain service that has the same name, then the `menuOrder` attribute is used to order those actions on the menu item drop-down.
+
+For example, the screenshot below shows the "prototyping" menu from the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp]:
+
+image::{_imagesdir}reference-annotations/DomainServiceLayout/menuOrder.png[width="500px",link="{_imagesdir}reference-annotations/DomainServiceLayout/menuOrder.png"]
+
+
+The xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] automatically places separators between actions from different domain services. From this we can infer that there are actually five different domain services that are all rendered on the "prototyping" top-level menu.
+
+One of these is the todoapp's `DemoDomainEventSubscriptions` service:
+
+[source,java]
+----
+@DomainService(
+ nature = NatureOfService.VIEW_MENU_ONLY
+)
+@DomainServiceLayout(
+ menuBar = MenuBar.SECONDARY,
+ named = "Prototyping", // <1>
+ menuOrder = "500.20") // <2>
+public class DemoDomainEventSubscriptions {
+ @ActionLayout(named="Set subscriber behaviour")
+ @MemberOrder(sequence = "500.20.1") // <3>
+ public void subscriberBehaviour(...) { ... }
+ ...
+}
+----
+<1> render on the "Prototyping" menu
+<2> positioning relative to other service's on the "Prototyping" menu
+<3> by convention (nothing more) the `@MemberOrder#sequence()` attribute continues the same Dewey decimal sequence format (a simple string "1" could in fact have been used instead)
+
+
+while another comes from the (non-ASF) http://github.com/isisaddons/isis-module-devutils[Isis addons' devutils] module:
+
+[source,java]
+----
+@DomainServiceLayout(
+ menuBar = MenuBar.SECONDARY,
+ named = "Prototyping", // <1>
+ menuOrder = "500.600" // <2>
+)
+public class DeveloperUtilitiesServiceMenu {
+ @MemberOrder( sequence = "500.600.1" ) // <3>
+ public Clob downloadMetaModel() { ... }
+ @MemberOrder( sequence = "500.600.2" )
+ public Blob downloadLayouts() { ... }
+ @ActionLayout(named = "Rebuild Services Meta Model")
+ @MemberOrder( sequence = "500.600.3")
+ public void refreshServices() { ... }
+ ...
+}
+----
+<1> render on the "Prototyping" menu
+<2> positioning relative to other service's on the "Prototyping" menu; this appears after the `DemoDomainEventSubscriptions` service shown above
+<3> by convention (nothing more) the `@MemberOrder#sequence()` attribute continues the same Dewey decimal sequence format (a simple string "1", "2", "3", ... could in fact have been used instead)
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainServiceLayout_named.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainServiceLayout_named.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainServiceLayout_named.adoc
new file mode 100644
index 0000000..e5d33ca
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainServiceLayout_named.adoc
@@ -0,0 +1,29 @@
+[[_rg_annotations_manpage-DomainServiceLayout_named]]
+= `named()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `named()` attribute explicitly specifies the domain service's name, overriding the name that would normally be inferred from the Java source code. This attribute can also be specified for xref:rg.adoc#_rg_annotations_manpage-ActionLayout_named[actions], xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_named[collections], xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_named[properties], xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_named[parameters], xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_named[domain objects] and xref:rg.adoc#_rg_annotations_manpage-ViewModelLayout_named[view models].
+
+
+[TIP]
+====
+The value of this attribute also has an important role to play in the positioning of the domain service's actions relative to the actions of other domain services. See xref:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_menuOrder[`menuOrder()`] for a full discussion with examples.
+====
+
+For example:
+
+[source,java]
+----
+@DomainService
+@DomainServiceLayout(
+ named="Customers"
+)
+public class CustomerRepository {
+ ...
+}
+----
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainService_nature.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainService_nature.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainService_nature.adoc
new file mode 100644
index 0000000..9cf20f2
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainService_nature.adoc
@@ -0,0 +1,89 @@
+[[_rg_annotations_manpage-DomainService_nature]]
+= `nature()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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, a domain service's actions will be rendered in the application menu bar _and_ be contributed _and_ appear in the REST API _and_ (of course) be available to invoke programmatically wherever that domain service is injected. This is great for initial prototyping, but later on you may prefer to add a little more structure. This is the purpose of the `nature()` attribute: to indicates the intent of (all of) the actions defined within the domain service.
+
+The values of the enum are:
+
+* `VIEW` +
++
+The default; the service's actions appear on menu bars, can be contributed, appear in the REST API
+
+* `VIEW_MENU_ONLY` +
++
+The service's actions appear on menus and in the REST API, but are not contributed to domain objects or view models
+
+* `VIEW_CONTRIBUTIONS_ONLY` +
++
+The service's actions are intended only to be used as contributed actions/associations to domain objects and view models. +
++
+The related xref:rg.adoc#_rg_annotations_manpage-ActionLayout_contributedAs[`@ActionLayout#contributedAs()`] determines whether any given (1-arg) action is contributed as an association rather than an action.
+
+* `VIEW_REST_ONLY` +
++
+The service's actions are intended only to be listed in the REST API exposed by the xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer].
+
+* `DOMAIN` +
++
+The service and its actions are only intended to be invoked programmatically; they are a domain layer responsibility.
+
+
+The actual class name of the domain service is only rendered for the `VIEW`, `VIEW_MENU_ONLY` and `VIEW_REST_ONLY` natures. Thus, you might also want to adopt naming conventions for your domain classes so you can infer the nature from the class. For example, the naming convention adopted (by and large) by the (non-ASF) link:http://isisaddons.org[Isis Addons] is `ProgrammaticServices` or `Repository` as a suffix for `DOMAIN` services, and `Contributions` as a suffix for `VIEW_CONTRIBUTIONS_ONLY` services.
+
+For example:
+
+[source,java]
+----
+@DomainService(
+ nature=NatureOfService.VIEW_CONTRIBUTIONS_ONLY
+)
+public class LoanContributions { // <1>
+ @Action(semantics=SemanticsOf.SAFE) // <2>
+ @ActionLayout(contributed=Contributed.AS_ASSOCIATION )
+ public List<Loan> currentLoans(Borrower borrower) { ... }
+ public Borrower newLoan(Borrower borrower, Book book) { ... }
+}
+----
+<1> `Contributions` as a suffix for a domain service that contributes a number of actions to ``Borrower``s. Note that `Borrower` could be a (marker) interface, so this functionality is "mixed in" merely by the class (eg `LibraryMember`) implementing this interface
+<2> actions contibuted as associations (a collection in this case) must have safe semantics
+
+
+Another example:
+
+[source,java]
+----
+@DomainService(
+ nature=NatureOfService.DOMAIN
+)
+public class LoanRepository { // <1>
+ @Programmatic // <2>
+ public List<Loan> findLoansFor(Borrower borrower) { ... }
+}
+----
+<1> `Repository` as a suffix for a domain-layer service
+<2> methods on `DOMAIN` services are often xref:rg.adoc#_rg_annotations_manpage-Programmatic[`@Programmatic`]; they will never be exposed in the UI, so there's little point in including them in Isis' metamodel
+
+
+
+A final example:
+
+[source,java]
+----
+@DomainService(
+ nature=NatureOfService.VIEW_MENU_ONLY
+)
+public class Loans { // <1>
+ @Action(semantics=SemanticsOf.SAFE)
+ public List<Loan> findOverdueLoans() { ... }
+ @Inject
+ LoanRepository loanRepository; // <2>
+}
+----
+<1> name is intended to be rendered in the UI
+<2> it's common for domain-layer domain services to be injected into presentation layer services (such as `VIEW_MENU_ONLY` and `VIEW_CONTRIBUTIONS_ONLY`).
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainService_repositoryFor.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainService_repositoryFor.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainService_repositoryFor.adoc
new file mode 100644
index 0000000..7c5cefd
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainService_repositoryFor.adoc
@@ -0,0 +1,26 @@
+[[_rg_annotations_manpage-DomainService_repositoryFor]]
+= `repositoryFor()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `repositoryFor()` attribute is intended for domain services (probably with a xref:rg.adoc#_rg_annotations_manpage-DomainService_nature[`nature=DOMAIN`]) that are intended to act as repositories for domain entities.
+
+For example:
+
+[source,java]
+----
+@DomainService(
+ nature=NatureOfService.DOMAIN,
+ repositoryFor=Loan.class
+)
+public class LoanRepository {
+ @Programmatic
+ public List<Loan> findLoansFor(Borrower borrower) { ... }
+}
+----
+
+
+Currently the metadata is unused; one planned use is to infer the icon for the domain service from the icon of the nominated entity.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Facets.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Facets.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Facets.adoc
new file mode 100644
index 0000000..f08744a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Facets.adoc
@@ -0,0 +1,15 @@
+[[_rg_annotations_manpage-Facets]]
+= `@Facets`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@Facets` annotation allows `FacetFactory` implementations and so can be used to run install arbitrary `Facet`s for a type. Generally this is not needed, but can be useful for overriding a custom programming model where a `FacetFactory` is not typically included.
+
+
+[NOTE]
+====
+`FacetFactory` is an important internal API that is used by Isis to
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-HomePage.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-HomePage.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-HomePage.adoc
new file mode 100644
index 0000000..aa99027
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-HomePage.adoc
@@ -0,0 +1,52 @@
+[[_rg_annotations_manpage-HomePage]]
+= `@HomePage`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@HomePage` annotation allows a _single_ (no-arg, query-only) action on a _single_ domain service to be nominated as the action to invoke for the default home page. This often returns a view model that acts as some sort of dashboard, presenting key information and makeing the most commonly used actions easy to invoke.
+
+For example, the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] uses `@HomePage` to return a dashboard of todo items to complete:
+
+image::{_imagesdir}reference-annotations/HomePage/HomePage.png[width="800px",link="{_imagesdir}reference-annotations/HomePage/HomePage.png"]
+
+
+The corresponding code is:
+
+[source,java]
+----
+@DomainService(nature = NatureOfService.DOMAIN)
+public class ToDoAppDashboardService {
+ @Action(
+ semantics = SemanticsOf.SAFE
+ )
+ @HomePage
+ public ToDoAppDashboard lookup() {
+ return container.injectServicesInto(new ToDoAppDashboard());
+ }
+ @Inject
+ private DomainObjectContainer container;
+}
+----
+
+where `ToDoAppDashboard` is:
+
+[source,java]
+----
+@DomainObject(nature = Nature.VIEW_MODEL)
+public class ToDoAppDashboard {
+ public String title() { return "Dashboard"; }
+
+ public List<ToDoItem> getNotYetComplete() { ... }
+ public List<ToDoItem> getComplete() { ... }
+
+ public Blob exportToWordDoc() { ... } // <1>
+}
+----
+<1> associated using xref:rg.adoc#_rg_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/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Inject.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Inject.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Inject.adoc
new file mode 100644
index 0000000..f047066
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Inject.adoc
@@ -0,0 +1,110 @@
+[[_rg_annotations_manpage-Inject]]
+= `@Inject` (`javax`)
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 automatically injects domain services into other domain services and also into domain objects and view models. In fact, it also injects domain services into xref:ug.adoc#_ug_testing_integ-test-support[integration tests] and xref:ug.adoc#_ug_testing_fixture-scripts[fixture scripts].
+
+[NOTE]
+====
+One omission: Isis (currently) does not inject services into `o.a.i.applib.spec.Specification` instances (as used by xref:rg.adoc#_rg_annotations_manpage-Property_mustSatisfy[`@Property#mustSatisfy()`] and xref:rg.adoc#_rg_annotations_manpage-Parameter_mustSatisfy[`@Parameter#mustSatisfy()`] annotations.
+====
+
+Isis supports several syntaxes for injecting domain services. The simplest uses the `@javax.inject.Inject` annotation on the field, as defined in link:https://jcp.org/en/jsr/detail?id=330[JSR-330].
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ public List<Order> findRecentOrders() { // <1>
+ return orders.recentOrdersFor(this);
+ }
+ @javax.inject.Inject
+ OrderRepository orders; // <2>
+}
+----
+<1> an alternative implementation would be to implement `findRecentOrders()` as a xref:ug.adoc#_ug_how-tos_contributed-members[contributed action].
+<2> we recommend default (rather than `private`) visibility so that unit tests can easily mock out the service
+
+
+
+== Alternative syntaxes
+
+Isis also supports setter-based injection:
+
+[source,java]
+----
+public class Customer {
+ ...
+ public void setOrderRepository(OrderRepository orderRepository) { ... }
+}
+----
+
+and also supports an additional syntax of using `inject...` as the prefix:
+
+[source,java]
+----
+public class Customer {
+ ...
+ public void injectOrderRepository(OrderRepository orderRepository) { ... }
+}
+----
+
+Generally we recommend using `@javax.inject.Inject`; it involves less code, and is more immediately familiar to most Java developers.
+
+
+
+== Manually injecting services
+
+Isis performs dependency injection when domain entities are recreated. It will also perform dependency injection if an object is created through the `DomainObjectContainer`.
+
+For example, to create a new (transient) domain object, the idiom is:
+
+[source,java]
+----
+Customer cust = container.newTransientInstance(Customer.class); <1>
+// initialize state of "cust"
+container.persist(cust);
+----
+<1> where `container` is an instance of xref:rg.adoc#_rg_services-api_manpage-DomainObjectContainer[`DomainObjectContainer`].
+
+View models are created similarly:
+
+[source,java]
+----
+ToDoAppDashboard dashboard = container.newViewModelInstance(ToDoAppDashboard.class);
+----
+
+
+If you prefer, though, you can simply instantiate domain objects using "new" and then inject domain services manually:
+
+
+[source,java]
+----
+Customer cust = new Customer();
+container.injectServicesInto(cust);
+// initialize state of "cust"
+container.persist(cust);
+----
+
+
+or if you prefer:
+
+[source,java]
+----
+Customer cust = container.injectServicesInto(new Customer());
+// initialize state of "cust"
+container.persist(cust);
+----
+
+
+[NOTE]
+====
+There is one subtle difference between using `DomainObjectContainer#newTransientInstance(...)` and `DomainObjectContainer#injectServicesInto(...)`, in that with the former Isis will automatically initialize all fields to their default values.
+
+This isn't a particular useful feature (and indeed can sometimes be rather confusing) so you may well wish to standardize on using `injectServicesInto(...)` throughout.
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-MemberGroupLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-MemberGroupLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-MemberGroupLayout.adoc
new file mode 100644
index 0000000..549de22
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-MemberGroupLayout.adoc
@@ -0,0 +1,20 @@
+[[_rg_annotations_manpage-MemberGroupLayout]]
+= `@MemberGroupLayout`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@MemberGroupLayout` annotation specifies how an object's properties and collections are grouped together into columns, also specifying the relative positioning of those columns. It works in conjunction with the xref:rg.adoc#_rg_annotations_manpage-MemberOrder[`@MemberOrder`] annotation.
+
+
+The `@MemberOrder` annotation is used to specify the relative order of domain object members, that is: properties, collections and actions. It works in conjunction with the xref:rg.adoc#_rg_annotations_manpage-MemberGroupLayout[`@MemberGroupLayout`] annotation.
+
+The annotation defines two attributes, `name()` and `sequence()`. Broadly speaking the `name()` attribute is used to group or associate members together, while the `sequence()` attribute orders members once they have been grouped.
+
+
+[IMPORTANT]
+====
+As this is an important topic, there is a xref:rg.adoc#_rg_object-layout[separate chapter] that discussed object layout in full.
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-MemberOrder.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-MemberOrder.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-MemberOrder.adoc
new file mode 100644
index 0000000..5fe5462
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-MemberOrder.adoc
@@ -0,0 +1,25 @@
+[[_rg_annotations_manpage-MemberOrder]]
+= `@MemberOrder`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@MemberOrder` annotation is used to specify the relative order of domain object members, that is: properties, collections and actions. It works in conjunction with the xref:rg.adoc#_rg_annotations_manpage-MemberGroupLayout[`@MemberGroupLayout`] annotation.
+
+The annotation defines four attributes:
+
+* `columnSpans()` -- of type `int[]` -- which specifies the relative column sizes of the three columns that render properties as well as a fourth column that renders only collections
+
+* `left()` -- of type `String[]` - that specifies the order of the property groups (inferred from `@MemberOrder#name()`) as applied to properties) in the left-most column
+
+* `middle()` -- of type `String[]` - that specifies the order of the property groups (if any) as applied to properties) in the middle column
+
+* `right()` -- of type `String[]` - that specifies the order of the property groups (if any) as applied to properties) in the right-most column
+
+Collections are always rendered in the "last" column. This can appear either below the columns holding properties (if their column spans = 12), or can be rendered to the right of the property columns (if the spans of the property columns come to <12 leaving enough room for the span of the collection column).
+
+[IMPORTANT]
+====
+As this is an important topic, there is a xref:rg.adoc#_rg_object-layout[separate chapter] that discussed object layout in full.
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-MinLength.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-MinLength.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-MinLength.adoc
new file mode 100644
index 0000000..dc69be3
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-MinLength.adoc
@@ -0,0 +1,32 @@
+[[_rg_annotations_manpage-MinLength]]
+= `@MinLength`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@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.
+
+
+For example:
+
+[source,java]
+----
+public ToDoItem add(
+ @TypicalLength(20)
+ final ToDoItem toDoItem) {
+ getDependencies().add(toDoItem);
+ return this;
+}
+public List<ToDoItem> autoComplete0Add(
+ final @MinLength(2)
+ String search) {
+ final List<ToDoItem> list = toDoItems.autoComplete(search);
+ list.removeAll(getDependencies());
+ list.remove(this);
+ return list;
+}
+----
+
+
+The `@Parameter(minLength=...)`e can also be used (even though strictly speaking the search argument is not a parameter of the action).
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-NotPersistent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-NotPersistent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-NotPersistent.adoc
new file mode 100644
index 0000000..21047ec
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-NotPersistent.adoc
@@ -0,0 +1,18 @@
+[[_rg_annotations_manpage-NotPersistent]]
+= `@NotPersistent` (`javax.jdo`)
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@javax.jdo.annotation.NotPersistent` annotation is used by JDO/DataNucleus to indicate that a property should not be persisted to the database.
+
+Apache Isis also uses this annotation, though (currently) only in the very minimal way to suppress checking of inconsistent metadata between JDO and Isis annotations (eg `@Column#allowsNull()` vs `@Property#optionality()`, or `@Column#length()` and `@Property#maxLength()`).
+
+[NOTE]
+====
+Isis parses the `@NotPersistent` annotation from the Java source code; it does not query the JDO metamodel. This means that it the `@NotPersistent` annotation must be used rather than the equivalent `<field>` link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/fields_properties.html[XML metadata].
+
+Moreover, while JDO/DataNucleus will recognize annotations on either the field or the getter method, Isis (currently) only inspects the getter method. Therefore ensure that the annotation is placed there.
+====
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Parameter.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Parameter.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Parameter.adoc
new file mode 100644
index 0000000..f2fe2d1
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Parameter.adoc
@@ -0,0 +1,96 @@
+[[_rg_annotations_manpage-Parameter]]
+= `@Parameter`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@Parameter` annotation applies to action parameters collecting together all domain semantics within a single annotation.
+
+The table below summarizes the annotation's attributes.
+
+.`@Paramter` attributes
+[cols="2,2,4a", options="header"]
+|===
+
+| Attribute
+| Values (default)
+| Description
+
+
+|xref:rg.adoc#_rg_annotations_manpage-Parameter_maxLength[`maxLength()`]
+|Positive integer
+|maximum number of characters for string parameters; ignored otherwise
+
+
+|`minLength()`
+|Positive integer
+|Deprecated; use xref:rg.adoc#_rg_annotations_manpage-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.
+
+
+|xref:rg.adoc#_rg_annotations_manpage-Parameter_mustSatisfy[`mustSatisfy()`]
+|implementation of `o.a.i.applib.spec.Specification`
+|allows arbitrary validation to be applied
+
+
+|xref:rg.adoc#_rg_annotations_manpage-Parameter_optionality[`optionality()`]
+|`MANDATORY`, `OPTIONAL` (`MANDATORY`)
+|specifies a parameter is optional rather than mandatory
+
+
+|xref:rg.adoc#_rg_annotations_manpage-Parameter_regexPattern[regexPattern()]
+|regular expression
+|validates the contents of a string parameter against the regular expression pattern
+
+
+|`regexPatternFlags()`
+|value of flags as normally passed to `java.util.regex.` +
+`Pattern#compile(...)`
+|modifies the compilation of the regular expression
+
+
+|`regexPatternReplacement()`
+|
+|Unused.
+
+
+|===
+
+
+
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ public static class EmailSpecification extends AbstractSpecification<String> {
+ public String satisfiesSafely(String proposed) {
+ return EmailUtil.ensureValidEmail(proposed); // <1>
+ }
+ }
+ @Action(semantics=SemanticsOf.IDEMPOTENT)
+ public Customer updateEmail(
+ @Parameter(
+ maxLength=30,
+ mustSatisfy=EmailSpecification.class,
+ optionality=Optionality.OPTIONAL,
+ regexPattern = "(\\w+\\.)*\\w+@(\\w+\\.)+[A-Za-z]+",
+ regexPatternFlags=Pattern.CASE_INSENSITIVE
+ )
+ @ParameterLayout(named="New Email Address")
+ final String newEmailAddress
+ ...
+ }
+}
+----
+<1> the (fictitious) `EmailUtil.ensureValid(...)` (omitted for brevity) returns a string explaining if an email is invalid
+
+include::_rg_annotations_manpage-Parameter_maxLength.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-Parameter_mustSatisfy.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-Parameter_optionality.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-Parameter_regexPattern.adoc[leveloffset=+1]
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout.adoc
new file mode 100644
index 0000000..82981b1
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout.adoc
@@ -0,0 +1,112 @@
+[[_rg_annotations_manpage-ParameterLayout]]
+= `@ParameterLayout`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@ParameterLayout` annotation applies to action parameters, collecting together all UI hints within a single annotation.
+
+The table below summarizes the annotation's attributes.
+
+.`@ParameterLayout` attributes
+[cols="2,2,4a", options="header"]
+|===
+
+| Attribute
+| Values (default)
+| Description
+
+
+|xref:rg.adoc#_rg_annotations_manpage-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:ug.adoc#_ug_runtime_application-specific_application-css[`application.css`]
+
+
+|xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_describedAs[`describedAs()`]
+|String
+|description of this parameter, eg to be rendered in a tooltip.
+
+
+|xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_labelPosition[`labelPosition()`]
+|`LEFT`, `TOP`, `RIGHT`, `NONE` +
+(`LEFT`)
+|in forms, the positioning of the label relative to the property value. +
+
+Default is `LEFT`, unless xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_multiLine[`multiLine`] in which case `TOP`. The value `RIGHT` is only supported for boolean parameters.
+
+
+|xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_multiLine[`multiLine()`]
+|Positive integer
+|for string parameters, render as a text area over multiple lines. +
+
+If set > 1, then then xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_labelPosition[`labelPosition`] defaults to `TOP`.
+
+
+|xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_named[`named()`]
+|String
+|the name of this parameter. +
+
+For Java 7 this is generally required. For Java 8, the name can often be inferred from the code so this attribute allows the name to be overridden. A typical use case is if the desired name is a reserved Java keyword, such as `default` or `package`.
+
+
+|`namedEscaped()`
+|`true`, `false` (`true`)
+|whether to HTML escape the name of this parameter.
+
+
+|xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_renderedAsDayBefore[`renderedAsDayBefore()`]
+|
+|for date parameters only, render the date as one day prior to the actually stored date (eg the end date of an open interval into a closed interval)
+
+
+|xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_typicalLength[`typicalLength()`]
+|
+|the typical entry length of a field, use to determine the optimum width for display
+
+|===
+
+
+
+
+
+For example:
+
+[source,java]
+----
+public class ToDoItem {
+ public ToDoItem updateDescription(
+ @ParameterLayout(
+ cssClass="x-key",
+ describedAs="What needs to be done",
+ labelPosition=LabelPosition.LEFT,
+ named="Description of this <i>item</i>",
+ namedEscaped=false,
+ typicalLength=80)
+ final String description) {
+ setDescription(description);
+ return this;
+ }
+ ...
+}
+----
+
+
+
+[NOTE]
+====
+Note that there is (currently) no support for specifying UI hints for domain services through the dynamic xref:rg.adoc#_rg_object-layout_dynamic[`.layout.json`] file (only for properties, collections and actions are supported).
+====
+
+
+
+include::_rg_annotations_manpage-ParameterLayout_cssClass.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-ParameterLayout_describedAs.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-ParameterLayout_labelPosition.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-ParameterLayout_multiLine.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-ParameterLayout_named.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-ParameterLayout_renderedAsDayBefore.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-ParameterLayout_typicalLength.adoc[leveloffset=+1]
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout_cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout_cssClass.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout_cssClass.adoc
new file mode 100644
index 0000000..e4a70dd
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout_cssClass.adoc
@@ -0,0 +1,29 @@
+[[_rg_annotations_manpage-ParameterLayout_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()` attribute can be used to render additional CSS classes in the HTML (a wrapping `<div>`) that represents the action parameter. xref:ug.adoc#_ug_runtime_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:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_cssClass[domain objects], xref:rg.adoc#_rg_annotations_manpage-ViewModelLayout_cssClass[view models], xref:rg.adoc#_rg_annotations_manpage-ActionLayout_cssClass[actions] xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_cssClass[properties], xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_cssClass[collections] and xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_cssClass[parameters].
+
+For example:
+
+[source,java]
+----
+public class ToDoItem {
+ public ToDoItem postpone(
+ @ParameterLayout(
+ named="until",
+ cssClass="x-key"
+ )
+ LocalDate until
+ ) { ... }
+ ...
+}
+----
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout_describedAs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout_describedAs.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout_describedAs.adoc
new file mode 100644
index 0000000..4013caa
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout_describedAs.adoc
@@ -0,0 +1,38 @@
+[[_rg_annotations_manpage-ParameterLayout_describedAs]]
+= `describedAs()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `describedAs()` attribute is used to provide a short description of the action parameter to the user. In the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] it is displayed as a 'tool tip'. The `describedAs()` attribute can also be specified for xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_describedAs[collections], xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_describedAs[properties], xref:rg.adoc#_rg_annotations_manpage-ActionLayout_describedAs[actions], xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_describedAs[domain objects] and xref:rg.adoc#_rg_annotations_manpage-ViewModelLayout_describedAs[view models].
+
+Descriptions may be provided for objects, members (properties,
+collections and actions), and for individual parameters within an action
+method. `@DescribedAs` therefore works in a very similar manner to
+`@Named` <!--(see ?)-->.
+
+
+To provide a description for an individual action parameter, use the
+`@DescribedAs` annotation in-line i.e. immediately before the parameter
+declaration.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ public Order placeOrder(
+ Product product,
+ @ParameterLayout(
+ named="Quantity",
+ describedAs="The quantity of the product being ordered"
+ )
+ int quantity) {
+ ...
+ }
+ ...
+}
+----
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout_labelPosition.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout_labelPosition.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout_labelPosition.adoc
new file mode 100644
index 0000000..82edd42
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout_labelPosition.adoc
@@ -0,0 +1,41 @@
+[[_rg_annotations_manpage-ParameterLayout_labelPosition]]
+= `labelPosition()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `labelPosition()` attribute determines the positioning of labels for parameters. This attribute can also be specified for xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_labelPosition[properties].
+
+The positioning of labels is typically `LEFT`, but can be positioned to the `TOP`. The one exception is xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_multiLine[`multiLine()`] string parameters, where the label defaults to `TOP` automatically (to provide as much real-estate for the multiline text field as possible).
+
+For boolean parameters a positioning of `RIGHT` is also allowed; this is ignored for all other types.
+
+It is also possible to suppress the label altogether, using `NONE`.
+
+For example:
+
+[source,java]
+----
+public class Order {
+ public Order changeStatus(
+ OrderStatus newStatus
+ @Parameter(
+ optionality=Optionality.OPTIONAL
+ )
+ @ParameterLayout(
+ named="Reason",
+ labelPosition=LabelPosition.TOP
+ )
+ String reason) {
+ ...
+ }
+ ...
+}
+----
+
+
+To get an idea of how these are rendered (in the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer]), see xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_labelPosition[PropertyLayout#labelPosition()].
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout_multiLine.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout_multiLine.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout_multiLine.adoc
new file mode 100644
index 0000000..c8d311a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout_multiLine.adoc
@@ -0,0 +1,32 @@
+[[_rg_annotations_manpage-ParameterLayout_multiLine]]
+= `multiLine()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `multiLine()` attribute specifies that the text field for a string parameter should span multiple lines. It is ignored for other parameter types. The attribute is also supported for xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_multiLine[properties].
+
+For example:
+
+[source,java]
+----
+public class BugReport {
+ public BugReport updateStepsToReproduce(
+ @Parameter(named="Steps")
+ @ParameterLayout(
+ numberOfLines=10
+ )
+ final String steps) {
+ ...
+ }
+ ...
+}
+----
+
+[NOTE]
+====
+If set > 1 (as would normally be the case), then the default xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_labelPosition[`labelPosition`] defaults to `TOP` (rather than `LEFT`, as would normally be the case).
+====
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout_named.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout_named.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout_named.adoc
new file mode 100644
index 0000000..44f2670
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout_named.adoc
@@ -0,0 +1,44 @@
+[[_rg_annotations_manpage-ParameterLayout_named]]
+= `named()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `named()` attribute explicitly specifies the action parameter's name. This attribute can also be specified for xref:rg.adoc#_rg_annotations_manpage-ActionLayout_named[actions], xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_named[collections], xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_named[properties], xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_named[domain objects], xref:rg.adoc#_rg_annotations_manpage-ViewModelLayout_named[view models] and xref:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_named[domain services].
+
+Unlike most other aspects of the Isis metamodel, the name of method parameters cannot (prior to Java 8, at least) be inferred from the Java source code. Without other information, Isis uses the object's type (`int`, `String` etc) as the name instead. This can be sufficient for application-specific reference types (eg `ToDoItem`) but is generally not sufficient for primitives and other value types.
+
+The `named()` attribute (or the xref:rg.adoc#_rg_annotations_aaa_deprecated[deprecated `@Named`] annotation) is therefore often required to specify the parameter name.
+
+As of Java 8, the Java reflection API has been extended. The (non-ASF) http://github.com/isisaddons/isis-metamodel-paraname8[Isis addons' paraname8] metamodel extension provides support for this. Note that your application must (obviously) be running on Java 8, and be compiled with the `-parameters` compile flag for javac.
+
+
+
+By default the name is HTML escaped. To allow HTML markup, set the related `namedEscaped()` attribute to `false`.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ public Order placeOrder(
+ final Product product
+ ,@ParameterLayout(named="Quantity")
+ final int quantity) {
+ Order order = newTransientInstance(Order.class);
+ order.modifyCustomer(this);
+ order.modifyProduct(product);
+ order.setQuantity(quantity);
+ return order;
+ }
+ ...
+}
+----
+
+
+[TIP]
+====
+The framework also provides a separate, powerful mechanism for xref:ug.adoc#_ug_more-advanced_i18n[internationalization].
+====
[27/45] isis git commit: ISIS-1133: breaking out reference guide and
devenv guide;
moving appendices' release notes and migration notes to other docs;
improving the documentation page.
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_testing_fixture-scripts_sudo-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_testing_fixture-scripts_sudo-service.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_testing_fixture-scripts_sudo-service.adoc
new file mode 100644
index 0000000..2c1172e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_testing_fixture-scripts_sudo-service.adoc
@@ -0,0 +1,59 @@
+[[_ug_testing_fixture-scripts_sudo-service]]
+= `SudoService`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 in our fixture scripts we want to perform a business action running as a particular user. This might be for the usual reason - so that our fixtures accurately reflect the reality of the system with all business constraints enforced using the `WrapperFactory` - or more straightforwardly it might be simply that the action depends on the identity of the user invoking the action.
+
+An example of the latter case is in the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp]'s `ToDoItem` class:
+
+[source,java]
+.Production code that depends on current user
+----
+public ToDoItem newToDo(
+ @Parameter(regexPattern = "\\w[@&:\\-\\,\\.\\+ \\w]*") @ParameterLayout(named="Description")
+ final String description,
+ @ParameterLayout(named="Category")
+ final Category category,
+ @Parameter(optionality = Optionality.OPTIONAL) @ParameterLayout(named="Subcategory")
+ final Subcategory subcategory,
+ @Parameter(optionality = Optionality.OPTIONAL) @ParameterLayout(named="Due by")
+ final LocalDate dueBy,
+ @Parameter(optionality = Optionality.OPTIONAL) @ParameterLayout(named="Cost")
+ final BigDecimal cost) {
+ return newToDo(description, category, subcategory, currentUserName(), dueBy, cost);
+}
+private String currentUserName() {
+ return container.getUser().getName(); // <1>
+}
+----
+<1> is the current user.
+
+The fixture for this can use the `SudoService` to run a block of code as a specified user:
+
+[source,java]
+.Fixture Script
+----
+final String description = ...
+final Category category = ...
+final Subcategory subcategory = ...
+final LocalDate dueBy = ...
+final BigDecimal cost = ...
+final Location location = ...
+
+toDoItem = sudoService.sudo(username,
+ new Callable<ToDoItem>() {
+ @Override
+ public ToDoItem call() {
+ final ToDoItem toDoItem = wrap(toDoItems).newToDo(
+ description, category, subcategory, dueBy, cost);
+ wrap(toDoItem).setLocation(location);
+ return toDoItem;
+ }
+ });
+----
+
+Behind the scenes the `SudoService` simply talks to the `DomainObjectContainer` to override the user returned by the `getUser()` API. It is possible to override both users and roles.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_testing_integ-test-support.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_testing_integ-test-support.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_testing_integ-test-support.adoc
new file mode 100644
index 0000000..f103703
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_testing_integ-test-support.adoc
@@ -0,0 +1,24 @@
+[[_ug_testing_integ-test-support]]
+= Integration Test 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/
+
+
+As discussed in the introductory overview of this chapter, Apache Isis allows you to integration test your domain objects from within JUnit. There are several parts to this:
+
+* configuring the Isis runtime so it can be bootstrapped (mostly boilerplate)
+* defining a base class to perform said bootstrapping
+* using fixture scripts to set up the app
+* using `WrapperFactory` so that the UI can be simulated.
+
+We'll get to all that shortly, but let's start by taking a look at what a typical integration test looks like.
+
+
+include::_ug_testing_integ-test-support_typical-usage.adoc[leveloffset=+1]
+include::_ug_testing_integ-test-support_bootstrapping.adoc[leveloffset=+1]
+include::_ug_testing_integ-test-support_wrapper-factory.adoc[leveloffset=+1]
+include::_ug_testing_integ-test-support_maven-configuration.adoc[leveloffset=+1]
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_testing_integ-test-support_bootstrapping.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_testing_integ-test-support_bootstrapping.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_testing_integ-test-support_bootstrapping.adoc
new file mode 100644
index 0000000..41957ea
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_testing_integ-test-support_bootstrapping.adoc
@@ -0,0 +1,231 @@
+[[_ug_testing_integ-test-support_bootstrapping]]
+= 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/
+
+
+Integration tests instantiate an Isis "runtime" (as a singleton) within a JUnit test. Because (depending on the size of your app) it takes a little time to bootstrap Isis, the framework caches the runtime on a thread-local from one test to the next.
+
+Nevertheless, we do need to bootstrap the runtime for the very first test.
+
+Since the integration tests don't depend on the `webapp` module, it's necessary to repeat all the (relevant) all the configuration in `isis.properties` and related files. That said, in practice the relevant information isn't all that much.
+
+[NOTE]
+====
+We hope to simplify the way this works in future versions of Isis.
+====
+
+The example code in this section is taken from the app generated by the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype].
+
+
+
+
+== Builder
+
+The bootstrapping itself is mostly performed by a subclass of the `IsisSystemForTest.Builder` class:
+
+[source,java]
+----
+private static class SimpleAppSystemBuilder extends IsisSystemForTest.Builder { // <1>
+
+ public SimpleAppSystemBuilder() {
+ withLoggingAt(org.apache.log4j.Level.INFO);
+ with(testConfiguration());
+ with(new DataNucleusPersistenceMechanismInstaller()); // <2>
+
+ withServicesIn( "domainapp" ); // <3>
+ }
+
+ private static IsisConfiguration testConfiguration() {
+ final IsisConfigurationForJdoIntegTests testConfiguration =
+ new IsisConfigurationForJdoIntegTests(); // <4>
+
+ testConfiguration.addRegisterEntitiesPackagePrefix("domainapp.dom.modules"); // <5>
+ return testConfiguration;
+ }
+}
+----
+<1> subclass the framework-provided `IsisSystemForTest.Builder`.
+<2> equivalent to `isis.persistor=datanucleus` in `isis.properties`
+<3> specify the `isis.services` key in `isis.properties` (where "domainapp" is the base package for all classes within the app)
+<4> `IsisConfigurationForJdoIntegTests` has pre-canned configuration for using an in-memory HSQLDB and other standard settings; more on this below.
+<5> equivalent to `isis.persistor.datanucleus.RegisterEntities.packagePrefix` key (typically in `persistor_datanucleus.properties`
+
+
+
+
+=== IsisConfigurationForJdoIntegTests
+
+Integration tests are configured programmatically, with a default set of properties to bootstrap the JDO/DataNucleus objectstore using an HSQLDB in-memory database.
+
+To remove a little bit of boilerplate, the `IsisConfigurationForJdoIntegTests` class (in the `org.apache.isis.objectstore.jdo.datanucleus` package) can be used to bootstrap the application. If necessary, this class can be subclassed to override these defaults.
+
+
+.Default Configuration Properties for Integration Tests
+[cols="2a,1,3a", options="header"]
+|===
+|Property
+|Value
+|Description
+
+|`isis.persistor.datanucleus.impl.` +
+`javax.jdo.option.ConnectionURL`
+|jdbc:hsqldb:mem:test
+|JDBC URL
+
+|`isis.persistor.datanucleus.impl.` +
+`javax.jdo.option.ConnectionDriverName`
+|org.hsqldb.jdbcDriver
+|JDBC Driver
+
+|`isis.persistor.datanucleus.impl.` +
+`javax.jdo.option.ConnectionUserName`
+|sa
+|Username
+
+|`isis.persistor.datanucleus.impl.` +
+`javax.jdo.option.ConnectionPassword`
+|<empty string>
+|Password
+
+|`isis.persistor.datanucleus.impl.` +
+`datanucleus.schema.autoCreateAll`
+|true
+|Recreate DB for each test run (an in-memory database)
+
+|`isis.persistor.datanucleus.impl.` +
+`datanucleus.schema.validateAll`
+|false
+|Disable validations (minimize bootstrap time)
+
+|`isis.persistor.datanucleus.impl.` +
+`datanucleus.persistenceByReachabilityAtCommit`
+|false
+|As per WEB-INF/persistor_datanucleus.properties
+
+|`isis.persistor.datanucleus.impl.` +
+`datanucleus.identifier.case`
+|MixedCase
+|As per WEB-INF/persistor_datanucleus.properties
+
+|`isis.persistor.datanucleus.impl.` +
+`datanucleus.cache.level2.type`
+|none
+|As per WEB-INF/persistor_datanucleus.properties
+
+|`isis.persistor.datanucleus.impl.` +
+`datanucleus.cache.level2.mode`
+|ENABLE_SELECTIVE
+|As per WEB-INF/persistor_datanucleus.properties
+
+|`isis.persistor.datanucleus.` +
+`install-fixtures`
+|true
+|Automatically install any fixtures that might have been registered
+
+|`isis.persistor.` +
+`enforceSafeSemantics`
+|false
+|
+
+|`isis.deploymentType`
+|server_prototype
+|
+|===
+
+
+
+
+
+== System Initializer
+
+The builder is defined and used within a class we call the system initializer that is responsible for instantiating the Isis runtime, and binding it to a thread-local. This is performed within a static `initIsft()` method.
+
+Here's the code:
+
+[source,java]
+----
+public class SimpleAppSystemInitializer {
+ public static void initIsft() {
+ IsisSystemForTest isft = IsisSystemForTest.getElseNull();
+ if(isft == null) {
+ isft = new SimpleAppSystemBuilder() // <1>
+ .build()
+ .setUpSystem();
+ IsisSystemForTest.set(isft); // <2>
+ }
+ }
+ private static class SimpleAppSystemBuilder
+ extends IsisSystemForTest.Builder { ... }
+
+}
+----
+<1> instantiates and initializes the Isis runtime (the `IsisSystemForTest` class)
+<2> binds the runtime to a thread-local.
+
+
+
+
+== Abstract Class
+
+We recommend defining a base class for all your other classes to integration classes to inherit from. The main responsibility of this class is tocall the system initializer, described earlier. We only need the initialization to be performed once, so this call is performed in a `@BeforeClass` hook.
+
+The code below shows the general form:
+
+[source,java]
+----
+public abstract class SimpleAppIntegTest {
+ @BeforeClass
+ public static void initClass() {
+ org.apache.log4j.PropertyConfigurator.configure("logging.properties"); // <1>
+ SimpleAppSystemInitializer.initIsft(); // <2>
+ new ScenarioExecutionForIntegration(); // <3>
+ }
+}
+----
+<1> ensure that logging messages don't get swallowed
+<2> initialize the Isis runtime
+<3> primarily exists to support the writing of xref:ug.adoc#_ug_testing_bdd-spec-support[BDD specifications], but also enables finer-grained management of sessions/transactions (discussed below).
+
+
+
+=== `IntegrationTestAbstract`
+
+In fact, we recommend that your base class inherit from Isis' `IntegrationTestAbstract` class:
+
+[source,java]
+----
+public abstract class SimpleAppIntegTest extends IntegrationTestAbstract {
+ ...
+}
+----
+
+Although not mandatory, this provides a number of helper/convenience methods and JUnit rules:
+
+[source,java]
+----
+ @Rule
+ public IsisTransactionRule isisTransactionRule = // <1>
+ new IsisTransactionRule();
+ @Rule
+ public JUnitRuleMockery2 context = // <2>
+ JUnitRuleMockery2.createFor(Mode.INTERFACES_AND_CLASSES);
+ @Rule
+ public ExpectedException expectedExceptions = // <3>
+ ExpectedException.none();
+ @Rule
+ public ExceptionRecognizerTranslate exceptionRecognizerTranslations = // <4>
+ ExceptionRecognizerTranslate.create();
+----
+<1> ensures an Isis session/transaction running for each test
+<2> sets up a JMock context (using Isis' extension to JMock as described in <<JMock Extensions>>
+<3> standard JUnit rule for writing tests that throw exceptions
+<4> to capture messages that require translation, as described in xref:ug.adoc#_ug_more-advanced_i18n[i18 support].
+
+All of these rules could be inlined in your own base class; as we say, they are a convenience.
+
+In addition, `IntegrationTestAbstract` provides a number of helper/convenience methods. Most important amongst these are `nextSession()` and `nextTransaction()` that to allow tests to simulate multiple separate user interactions (each of which would normally occur in a separate transaction).
+
+It also provides `wrap(...)` and `unwrap(...)` which delegate to the `WrapperFactory`. We talk about these methods in the next section
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_testing_integ-test-support_maven-configuration.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_testing_integ-test-support_maven-configuration.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_testing_integ-test-support_maven-configuration.adoc
new file mode 100644
index 0000000..e56a865
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_testing_integ-test-support_maven-configuration.adoc
@@ -0,0 +1,46 @@
+[[_ug_testing_integ-test-support_maven-configuration]]
+= Maven Configuration
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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' 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:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.isis.core</groupId>
+ <artifactId>isis-core-integtestsupport</artifactId>
+</dependency>
+<dependency>
+ <groupId>org.apache.isis.core</groupId>
+ <artifactId>isis-core-wrapper</artifactId>
+</dependency>
+----
+
+We also recommend that you configure the `maven-surefire-plugin` to pick up the following class patterns:
+
+[source,xml]
+----
+<plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-surefire-plugin</artifactId>
+ <version>2.10</version>
+ <configuration>
+ <includes>
+ <include>**/*Test.java</include>
+ <include>**/*Test_*.java</include>
+ <include>**/*Spec*.java</include>
+ </includes>
+ <excludes>
+ <exclude>**/Test*.java</exclude>
+ <exclude>**/*ForTesting.java</exclude>
+ <exclude>**/*Abstract*.java</exclude>
+ </excludes>
+ <useFile>true</useFile>
+ <printSummary>true</printSummary>
+ <outputDirectory>${project.build.directory}/surefire-reports</outputDirectory>
+ </configuration>
+</plugin>
+----
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_testing_integ-test-support_typical-usage.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_testing_integ-test-support_typical-usage.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_testing_integ-test-support_typical-usage.adoc
new file mode 100644
index 0000000..66c9936
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_testing_integ-test-support_typical-usage.adoc
@@ -0,0 +1,124 @@
+[[_ug_testing_integ-test-support_typical-usage]]
+= Typical Usage
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 example adapted from the link:http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] (non-ASF). The code we want to test (simplified) is:
+
+[source,java]
+----
+public class ToDoItem ... {
+
+ private boolean complete;
+ @Property( editing = Editing.DISABLED )
+ public boolean isComplete() {
+ return complete;
+ }
+ public void setComplete(final boolean complete) {
+ this.complete = complete;
+ }
+
+ @Action()
+ public ToDoItem completed() {
+ setComplete(true);
+ ...
+ return this;
+ }
+ public String disableCompleted() {
+ return isComplete() ? "Already completed" : null;
+ }
+ ...
+}
+----
+
+We typically put the bootstrapping of Isis into a superclass (`AbstractToDoIntegTest` below), then subclass as required.
+
+For this test (of the "completed()" action) we need an instance of a `ToDoItem` that is not yet complete. Here's the setup:
+
+[source,java]
+----
+public class ToDoItemIntegTest extends AbstractToDoIntegTest {
+
+ @Inject
+ FixtureScripts fixtureScripts; // <1>
+ @Inject
+ ToDoItems toDoItems; // <2>
+ ToDoItem toDoItem; // <3>
+
+ @Before
+ public void setUp() throws Exception {
+ RecreateToDoItemsForCurrentUser fixtureScript = // <4>
+ new RecreateToDoItemsForCurrentUser();
+ fixtureScripts.runFixtureScript(fixtureScript, null);
+ final List<ToDoItem> all = toDoItems.notYetComplete(); // <5>
+ toDoItem = wrap(all.get(0)); // <6>
+ }
+ ...
+}
+----
+<1> the xref:rg.adoc#_rg_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
+<5> we lookup one of the just-created todo items...
+<6> and then wrap it so that our interactions with it are as if through the UI
+
+
+
+The following code tests the happy case, that a not-yet-completed `ToDoItem` can be completed by invoking the `completed()` action:
+
+[source,java]
+----
+public class ToDoItemIntegTest ... {
+ ...
+ public static class Completed extends ToDoItemIntegTest { // <1>
+ @Test
+ public void happyCase() throws Exception {
+ // given
+ assertThat(toDoItem.isComplete()).isFalse(); // <2>
+ // when
+ toDoItem.completed();
+ // then
+ assertThat(toDoItem.isComplete()).isTrue();
+ }
+ ...
+ }
+}
+----
+<1> the idiom we follow is to use nested static classes to identify the class responsibility being tested
+<2> the http://github.com/isisaddons/isis-app-todoapp[todoapp] uses link:http://joel-costigliola.github.io/assertj[AssertJ].
+
+What about when a todo item is already completed? The `disableCompleted()` method in the class says that it shouldn't be allowed (the action would be greyed out in the UI with an appropriate tooltip). The following test verifies this:
+
+[source,java]
+----
+ @Test
+ public void cannotCompleteIfAlreadyCompleted() throws Exception {
+ // given
+ unwrap(toDoItem).setComplete(true); // <1>
+ // expect
+ expectedExceptions.expectMessage("Already completed"); // <2>
+ // when
+ toDoItem.completed();
+ }
+----
+<1> we unwrap the domain object in order to set its state directly
+<2> the expectedExceptions link:http://junit.org/apidocs/org/junit/rules/ExpectedException.html[JUnit rule] (defined by a superclass) verifies that the appropiate exception is indeed thrown (in the "when")
+
+
+And what about the fact that the underlying "complete" property is disabled (the `@Disabled` annotation?). If the `ToDoItem` is put into edit mode in the UI, the complete checkbox should remain read-only. Here's a verify similar test that verifies this also:
+
+[source,java]
+----
+ @Test
+ public void cannotSetPropertyDirectly() throws Exception {
+ // expect
+ expectedExceptions.expectMessage("Always disabled"); // <1>
+ // when
+ toDoItem.setComplete(true);
+ }
+----
+<1> again we use the exceptedExceptions rule.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_testing_integ-test-support_wrapper-factory.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_testing_integ-test-support_wrapper-factory.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_testing_integ-test-support_wrapper-factory.adoc
new file mode 100644
index 0000000..c298dc1
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_testing_integ-test-support_wrapper-factory.adoc
@@ -0,0 +1,162 @@
+[[_ug_testing_integ-test-support_wrapper-factory]]
+= Wrapper Factory
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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:rg.adoc#_rg_services-api_manpage-WrapperFactory[`WrapperFactory`] service is responsible for wrapping a domain object in a dynamic proxy, of the same type as the object being proxied. And the role of this wrapper is to simulate the UI.
+
+[NOTE]
+====
+`WrapperFactory` uses link:http://www.javassist.org[javassist] to perform its magic; this is the same technology that ORMs such as link:http://hibernate.org/[Hibernate] use to manage lazy loading/dirty tracking (DataNucleus uses a different mechanism).
+====
+
+
+
+It does this by allowing through method invocations that would be allowed if the user were interacting with the domain object through one of the viewers, but throwing an exception if the user attempts to interact with the domain object in a way that would not be possible if using the UI.
+
+The mechanics are as follows:
+
+. the integration test calls the `WrapperFactory` to obtain a wrapper for the domain object under test. This is usually done in the test's `setUp()` method.
+
+. the test calls the methods on the wrapper rather than the domain object itself
+
+. the wrapper performs a reverse lookup from the method invoked (a regular `java.lang.reflect.Method` instance) into the Isis metamodel
+
+. (like a viewer), the wrapper then performs the "see it/use it/do it" checks, checking that the member is visible, that it is enabled and (if there are arguments) that the arguments are valid
+
+. if the business rule checks pass, then the underlying member is invoked. Otherwise an exception is thrown.
+
+The type of exception depends upon what sort of check failed. It's straightforward enough: if the member is invisible then a `HiddenException` is thrown; if it's not usable then you'll get a `DisabledException`, if the args are not valid then catch an `InvalidException`.
+
+image::{_imagesdir}testing/wrapper-factory.png[width="600px"]
+
+Let's look in a bit more detail at what the test can do with the wrapper.
+
+
+
+
+
+== Wrapping and Unwrapping
+
+Wrapping a domain object is very straightforward; simply call `WrapperFactory#wrap(...)`.
+
+For example:
+
+[source,java]
+----
+Customer customer = ...;
+Customer wrappedCustomer = wrapperFactory.wrap(wrappedCustomer);
+----
+
+
+Going the other way -- getting hold of the underlying (wrapped) domain object -- is just as easy; just call `WrapperFactory#unwrap(...)`.
+
+For example:
+
+[source,java]
+----
+Customer wrappedCustomer = ...;
+Customer customer = wrapperFactory.unwrap(wrappedCustomer);
+----
+
+If you prefer, you also can get the underlying object from the wrapper itself, by downcasting to `WrappingObject` and calling `__isis_wrapped()` method:
+
+[source,java]
+----
+Customer wrappedCustomer = ...;
+Customer customer = (Customer)((WrappingObject)wrappedCustomer).__isis_wrapped());
+----
+
+We're not sure that's any easier (in fact we're certain it looks rather obscure). Stick with calling `unwrap(...)`!
+
+
+
+
+== Using the wrapper
+
+As the wrapper is intended to simulate the UI, only those methods that correspond to the "primary" methods of the domain object's members are allowed to be called. That means:
+
+* for *_object properties_* the test can call the getter or setter method
+
+* for *_object collections_* the test can call the getter. +
++
+If there is a supporting `addTo...()` or `removeFrom...()` method, then these can be called. It can also call `add(...)` or `remove(...)` on the collection (returned by the gettter) itself. +
++
+[NOTE]
+====
+In this respect the wrapper is more functional than the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] (which does not expose the ability to mutate collections directly).
+====
+
+* for *_object actions_* the test can call the action method itself.
+
+As a convenience, we also allow the test to call any `default...()`,`choices...()` or `autoComplete...()` method. These are often useful for obtaining a valid value to use.
+
+What the test can't call is any of the remaining supporting methods, such as `hide...()`, `disable...()` or `validate...()`. That's because their value is implied by the exception being thrown.
+
+The wrapper _does_ also allow the object's `title()` method or its `toString()` , however this is little use for objects whose title is built up using the `@Title` annotation. Instead, we recommend that your test verifies an object's title by calling `DomainObjectContainer#titleOf(...)` method.
+
+
+
+
+
+== Firing Domain Events
+
+As well as enforcing business rules, the wrapper has another important feature, namely that it will cause domain events to be fired.
+
+For example, if we have an action annotated with `@Action(domainEvent=...`):
+
+[source,java]
+----
+public class ToDoItem ... {
+ @Action(
+ domainEvent =CompletedEvent.class
+ )
+ public ToDoItem completed() { ... }
+ ...
+}
+----
+
+then invoking the action through the proxy will cause the event (`CompletedEvent` above) to be fired to any subscribers. A test might therefore look like:
+
+[source,java]
+----
+@Inject
+private EventBusService eventBusService; // <1>
+
+@Test
+public void subscriberReceivesEvents() throws Exception {
+
+ // given
+ final ToDoItem.CompletedEvent[] evHolder = new ToDoItem.CompletedEvent[1]; // <2>
+ eventBusService.register(new Object() {
+ @Subscribe
+ public void on(final ToDoItem.CompletedEvent ev) { // <3>
+ evHolder[0] = ev;
+ }
+ });
+
+ // when
+ toDoItem.completed(); // <4>
+
+ // then
+ then(evHolder[0].getSource()).isEqualTo(unwrap(toDoItem)); // <5>
+ then(evHolder[0].getIdentifier().getMemberName()).isEqualTo("completed");
+}
+----
+<1> inject xref:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`] into this test
+<2> holder for subscriber to capture event to
+<3> subscriber's callback, using the guava subscriber syntax
+<4> invoking the domain object using the wrapper
+<5> assert that the event was populated
+
+
+The wrapper will also fire domain events for properties (if annotated with `@Property(domainEvent=...)`) or collections (if annotated with `@Collection(domainEvent=...)`).
+
+
+[NOTE]
+====
+It isn't possible to use the `WrapperFactory` in a unit test, because there needs to be a running instance of Isis that holds the metamodel.
+====
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_testing_unit-test-support.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_testing_unit-test-support.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_testing_unit-test-support.adoc
new file mode 100644
index 0000000..2cb5ff8
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_testing_unit-test-support.adoc
@@ -0,0 +1,13 @@
+[[_ug_testing_unit-test-support]]
+= Unit Test 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/
+
+Isis Core provides a number of unit test helpers for you to use (if you wish) to unit test your domain objects.
+
+
+include::_ug_testing_unit-test-support_contract-tests.adoc[leveloffset=+1]
+include::_ug_testing_unit-test-support_jmock-extensions.adoc[leveloffset=+1]
+include::_ug_testing_unit-test-support_maven-configuration.adoc[leveloffset=+1]
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_testing_unit-test-support_contract-tests.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_testing_unit-test-support_contract-tests.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_testing_unit-test-support_contract-tests.adoc
new file mode 100644
index 0000000..75f9447
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_testing_unit-test-support_contract-tests.adoc
@@ -0,0 +1,171 @@
+[[_ug_testing_unit-test-support_contract-tests]]
+= Contract Tests
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+
+Contract tests ensure that all instances of a particular idiom/pattern that occur within your codebase are implemented correctly. You could think of them as being a way to enforce a certain type of coding standard. Implementation-wise they use link:https://code.google.com/p/reflections/[Reflections] library to scan for classes.
+
+
+
+== ``SortedSet``s Contract Test
+
+This contract test automatically checks that all fields of type `java.util.Collection` are declared as `java.util.SortedSet`. In other words, it precludes either `java.util.List` or `java.util.Set` from being used as a collection.
+
+For example, the following passes the contract test:
+
+[source,java]
+----
+public class Department {
+ private SortedSet<Employee> employees = new TreeSet<Employee>();
+ ...
+}
+----
+
+whereas this would not:
+
+[source,java]
+----
+public class SomeDomainObject {
+ private List<Employee> employees = new ArrayList<Employee>();
+ ...
+}
+----
+
+If using DataNucleus against an RDBMS (as you probably are) then we strongly recommend that you implement this test, for several reasons:
+
+* first, ``Set``s align more closely to the relational model than do `List`s. A `List` must have an additional index to specify order.
+
+* second, `SortedSet` is preferable to `Set` because then the order is well-defined and predictable (to an end user, to the programmer). +
++
+The <<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.
+
+To use the contract test, subclass `SortedSetsContractTestAbstract`, specifying the root package to search for domain classes.
+
+For example:
+
+[source,java]
+----
+public class SortedSetsContractTestAll extends SortedSetsContractTestAbstract {
+
+ public SortedSetsContractTestAll() {
+ super("org.estatio.dom");
+ withLoggingTo(System.out);
+ }
+}
+----
+
+
+
+== Bidirectional Contract Test
+
+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]
+
+[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:dg.adoc[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`).
+
+The following will exercise these relationships:
+
+[source,java]
+----
+public class BidirectionalRelationshipContractTestAll
+ extends BidirectionalRelationshipContractTestAbstract {
+
+ public BidirectionalRelationshipContractTestAll() {
+ super("org.apache.isis.core.unittestsupport.bidir",
+ ImmutableMap.<Class<?>,Instantiator>of(
+ ChildDomainObject.class, new InstantiatorForChildDomainObject(),
+ PeerDomainObject.class, new InstantiatorSimple(PeerDomainObjectForTesting.class)
+ ));
+ withLoggingTo(System.out);
+ }
+}
+----
+
+The first argument to the constructor scopes the search for domain objects; usually this would be something like `"com.mycompany.dom"`.
+
+The second argument provides a map of `Instantiator` for certain of the domain object types. This has two main purposes. First, for abstract classes, it nominates an alternative concrete class to be instantiated. Second, for classes (such as `ChildDomainObject`) that are `Comparable` and are held in a `SortedSet`), it provides the ability to ensure that different instances are unique when compared against each other. If no `Instantiator` is provided, then the contract test simply attempts to instantiates the class.
+
+If any of the supporting methods (`addToXxx()`, `removeFromXxx()`, `modifyXxx()` or `clearXxx()`) are missing, the relationship is skipped.
+
+To see what's going on (and to identify any skipped relationships), use the `withLoggingTo()` method call. If any assertion fails then the error should be descriptive enough to figure out the problem (without enabling logging).
+
+The example tests can be found https://github.com/apache/isis/tree/master/core/unittestsupport/src/test/java/org/apache/isis/core/unittestsupport/bidir[here].
+
+
+
+== Injected Services Method Contract Test
+
+It is quite common for some basic services to be injected in a project-specific domain object superclass; for example a `ClockService` might generally be injected everywhere:
+
+[source,java]
+----
+public abstract class EstatioDomainObject {
+ @javax.inject.Inject
+ protected ClockService clockService;
+}
+----
+
+If a subclass inadvertantly overrides this method and provides its own `ClockService` field, then the field in the superclass will never initialized. As you might imagine, ``NullPointerException``s could then arise.
+
+This contract test automatically checks that the `injectXxx(...)` method, to allow for injected services, is not overridable, ie `final`.
+
+[NOTE]
+====
+This contract test is semi-obsolete; most of the time you will want to use `@javax.inject.Inject` on fields rather than the `injectXxx()` method. The feature dates from a time before Isis supported the `@Inject` annotation.
+====
+
+
+To use the contract test, , subclass `SortedSetsContractTestAbstract`, specifying the root package to search for domain classes.
+
+For example:
+
+[source,java]
+----
+public class InjectServiceMethodMustBeFinalContractTestAll extends InjectServiceMethodMustBeFinalContractTestAbstract {
+
+ public InjectServiceMethodMustBeFinalContractTestAll() {
+ super("org.estatio.dom");
+ withLoggingTo(System.out);
+ }
+}
+----
+
+
+
+
+== Value Objects Contract Test
+
+The `ValueTypeContractTestAbstract` automatically tests that a custom value type implements `equals()` and `hashCode()` correctly.
+
+For example, testing JDK's own `java.math.BigInteger` can be done as follows:
+
+[source,java]
+----
+public class ValueTypeContractTestAbstract_BigIntegerTest extends ValueTypeContractTestAbstract<BigInteger> {
+
+ @Override
+ protected List<BigInteger> getObjectsWithSameValue() {
+ return Arrays.asList(new BigInteger("1"), new BigInteger("1"));
+ }
+
+ @Override
+ protected List<BigInteger> getObjectsWithDifferentValue() {
+ return Arrays.asList(new BigInteger("2"));
+ }
+}
+----
+
+The example unit tests can be found https://github.com/apache/isis/tree/master/core/unittestsupport/src/test/java/org/apache/isis/core/unittestsupport/value[here].
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_testing_unit-test-support_jmock-extensions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_testing_unit-test-support_jmock-extensions.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_testing_unit-test-support_jmock-extensions.adoc
new file mode 100644
index 0000000..4bf309f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_testing_unit-test-support_jmock-extensions.adoc
@@ -0,0 +1,59 @@
+[[_ug_testing_unit-test-support_jmock-extensions]]
+= JMock Extensions
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 noted earlier, for unit tests we tend to use link:http://www.jmock.org[JMock] as our mocking library. The usual given/when/then format gets an extra step:
+
+* *given* the system is in this state
+* *expecting* these interactions (set up the mock expectations here)
+* *when* I poke it with a stick
+* *then* these state changes and interactions with Mocks should have occurred.
+
+If using JMock then the interactions (in the "then") are checked automatically by a JUnit rule. However, you probably will still have some state changes to assert upon.
+
+[TIP]
+.Distinguish between queries vs mutators
+====
+For mock interactions that simply retrieve some data, your test should not need to verify that it occurred. If the system were to be refactored and starts caching some data, you don't really want your tests to start breaking because they are no longer performing a query that once they did. If using JMock API this means using the `allowing(..)` method to set up the expectation.
+
+On the other hand mocks that mutate the state of the system you probably should assert have occurred. If using JMock this typically means using the `oneOf(...)` method.
+
+For more tips on using JMock and mocking in general, check out the link:http://www.growing-object-oriented-software.com/[GOOS] book, written by JMock's authors, Steve Freeman and Nat Pryce and also link:http://natpryce.com/articles.html[Nat's blog].
+====
+
+Apache Isis' unit test support provides `JUnitRuleMockery2` which is an extension to the link:http://www.jmock.org/[JMock]'s `JunitRuleMockery`. It provides a simpler API and also providing support for autowiring.
+
+
+For example, here we see that the class under test, an instance of `CollaboratingUsingSetterInjection`, is automatically wired up with its `Collaborator`:
+
+[source,java]
+----
+public class JUnitRuleMockery2Test_autoWiring_setterInjection_happyCase {
+
+ @Rule
+ public JUnitRuleMockery2 context = JUnitRuleMockery2.createFor(Mode.INTERFACES_AND_CLASSES);
+
+ @Mock
+ private Collaborator collaborator;
+
+ @ClassUnderTest
+ private CollaboratingUsingSetterInjection collaborating;
+
+ @Test
+ public void wiring() {
+ assertThat(collaborating.collaborator, is(not(nullValue())));
+ }
+}
+----
+
+[NOTE]
+====
+Isis also includes (and automatically uses) a link:http://www.javassist.org[Javassist]-based implementation of JMock's link:http://www.jmock.org/mocking-classes.html[`ClassImposteriser`] interface, so that you can mock out concrete classes as well as interfaces. We've provided this rather than JMock's own cglib-based implementation (which is problematic for us given its own dependencies on link:http://asm.ow2.org/[asm]).
+====
+
+
+The example tests can be found https://github.com/apache/isis/tree/master/core/unittestsupport/src/test/java/org/apache/isis/core/unittestsupport/jmocking[here]
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_testing_unit-test-support_maven-configuration.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_testing_unit-test-support_maven-configuration.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_testing_unit-test-support_maven-configuration.adoc
new file mode 100644
index 0000000..0205920
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_testing_unit-test-support_maven-configuration.adoc
@@ -0,0 +1,46 @@
+[[_ug_testing_unit-test-support_maven-configuration]]
+= Maven Configuration
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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' 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:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.isis.core</groupId>
+ <artifactId>isis-core-unittestsupport</artifactId>
+ <scope>test</scope> // <1>
+</dependency>
+----
+<1> Normally `test`; usual Maven scoping rules apply.
+
+
+
+We also recommend that you configure the `maven-surefire-plugin` to pick up the following class patterns:
+
+[source,xml]
+----
+<plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-surefire-plugin</artifactId>
+ <version>2.10</version>
+ <configuration>
+ <includes>
+ <include>**/*Test.java</include>
+ <include>**/*Test_*.java</include>
+ <include>**/*Spec*.java</include>
+ </includes>
+ <excludes>
+ <exclude>**/Test*.java</exclude>
+ <exclude>**/*ForTesting.java</exclude>
+ <exclude>**/*Abstract*.java</exclude>
+ </excludes>
+ <useFile>true</useFile>
+ <printSummary>true</printSummary>
+ <outputDirectory>${project.build.directory}/surefire-reports</outputDirectory>
+ </configuration>
+</plugin>
+----
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_troubleshooting.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_troubleshooting.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_troubleshooting.adoc
new file mode 100644
index 0000000..39384d2
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_troubleshooting.adoc
@@ -0,0 +1,14 @@
+[[_ug_troubleshooting]]
+= Troubleshooting
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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
+
+## Logging
+
+include::_ug_troubleshooting_enabling-logging.adoc[leveloffset=+1]
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_troubleshooting_enabling-logging.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_troubleshooting_enabling-logging.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_troubleshooting_enabling-logging.adoc
new file mode 100644
index 0000000..712ea17
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_troubleshooting_enabling-logging.adoc
@@ -0,0 +1,39 @@
+[[_ug_troubleshooting_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
+
+=== HSQLDB Logging
+
+Add `;sqllog=3` to the end of the JDBC URL.
+
+=== PostgreSQL Logging
+
+In `postgresql\9.2\data\postgresql.conf`:
+
+Will then log to `postgresql\9.2\data\pg_log` directory.
+
+Note that you must restart the service for this to be picked up.
+
+=== MS SQL Server Logging
+
+Use the excellent SQL Profiler tool.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_tutorials.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_tutorials.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_tutorials.adoc
new file mode 100644
index 0000000..a4045ce
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_tutorials.adoc
@@ -0,0 +1,18 @@
+[[_ug_tutorials]]
+= Tutorials
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 contains a couple of tutorials for you to follow.
+
+* the "petclinic" tutorial takes you step-by-step through building a simple application of just three classes. There are example solutions in the github repo in case you get lost.
+
+* the "stop scaffolding, start coding" tutorial is taken from a conference workshop. It has less hand-holding, but lists out the steps for you to follow. It's a good cookbook to follow when you're readng to take things further.
+
+Have fun!
+
+include::_ug_tutorials_pet-clinic.adoc[leveloffset=+1]
+include::_ug_tutorials_stop-scaffolding-start-coding.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_tutorials_pet-clinic.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_tutorials_pet-clinic.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_tutorials_pet-clinic.adoc
new file mode 100644
index 0000000..dccc025
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_tutorials_pet-clinic.adoc
@@ -0,0 +1,557 @@
+[[_ug_tutorials_pet-clinic]]
+= Pet Clinic
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+This is a step-by-step tutorial to build up a simple "petclinic" application, starting from the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype].
+
+It consists of just three domain classes (http://yuml.me/edit/3db2078c[http://yuml.me/3db2078c]):
+
+image::{_imagesdir}tutorials/pet-clinic/domain-model.png[link="{_imagesdir}tutorials/pet-clinic/domain-model.png"]
+
+
+This supports the following use cases:
+
+* register a Pet
+* register an Owner
+* maintain a Pet's details
+* check in a Pet to visit the clinic
+* enter a diagnosis
+
+check out a Pet to visit the clinic
+
+Either follow along or check out the tags from the corresponding https://github.com/danhaywood/isis-app-petclinic[github repo].
+
+== Prerequisites
+
+You'll need:
+
+* Java 7 JDK
+* http://maven.apache.org/[Maven] 3.2.x
+* an IDE, such as http://www.eclipse.org/[Eclipse] or https://www.jetbrains.com/idea/[IntelliJ IDEA].
+
+
+
+
+== Run the archetype
+
+Throughout this tutorial you can, if you wish, just checkout from the github repo wherever you see a "git checkout" note:
+
+[TIP]
+====
+[source,bash]
+----
+git checkout https://github.com/danhaywood/isis-app-petclinic/commit/249abe476797438d83faa12ff88365da2c362451
+----
+
+====
+
+[NOTE]
+====
+This tutorial was developed against Apache Isis 1.8.0-SNAPSHOT. Since then 1.8.0 has been released, so simply replace "1.8.0-SNAPSHOT" for "1.8.0" wherever it appears in the `pom.xml` files.
+====
+
+
+As per the http://isis.apache.org/intro/getting-started/simpleapp-archetype.html[Isis website], run the simpleapp archetype to build an empty Isis application:
+
+
+[source,bash]
+----
+mvn archetype:generate \
+ -D archetypeGroupId=org.apache.isis.archetype \
+ -D archetypeArtifactId=simpleapp-archetype \
+ -D archetypeVersion=1.8.0 \
+ -D groupId=com.mycompany \
+ -D artifactId=petclinic \
+ -D version=1.0-SNAPSHOT \
+ -D archetypeRepository=http://repository-estatio.forge.cloudbees.com/snapshot/ \
+ -B
+----
+
+This will generate the app in a `petclinic` directory. Move the contents back:
+
+[source,bash]
+----
+mv petclinic/* .
+rmdir petclinic
+----
+
+
+
+
+== Build and run
+
+Start off by building the app from the command line:
+
+[source,bash]
+----
+mvn clean install
+----
+
+Once that's built then run using:
+
+[source,bash]
+----
+mvn antrun:run -P self-host
+----
+
+A splash screen should appear offering to start up the app. Go ahead and start; the web browser should be opened at http://localhost:8080[http://localhost:8080]
+
+Alternatively, you can run using the mvn-jetty-plugin:
+
+[source,bash]
+----
+mvn jetty:run
+----
+
+This will accomplish the same thing, though the webapp is mounted at a slightly different URL
+
+
+
+
+== Using the app
+
+Navigate to the Wicket UI (eg http://localhost:8080/wicket[http://localhost:8080/wicket]), and login (sven/pass).
+
+image::{_imagesdir}tutorials/pet-clinic/010-01-login-page.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/010-01-login-page.png"]
+
+
+
+The home page should be shown:
+
+image::{_imagesdir}tutorials/pet-clinic/010-02-home-page.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/010-02-home-page.png"]
+
+
+
+Install the fixtures (example test data) using the `Prototyping` menu:
+
+image::{_imagesdir}tutorials/pet-clinic/010-03-prototyping-menu.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/010-03-prototyping-menu.png"]
+
+
+
+List all objects using the `Simple Objects` menu:
+
+image::{_imagesdir}tutorials/pet-clinic/010-04-simpleobjects.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/010-04-simpleobjects.png"]
+
+
+To return the objects created:
+
+image::{_imagesdir}tutorials/pet-clinic/010-05-simpleobject-list.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/010-05-simpleobject-list.png"]
+
+
+
+Experiment some more, to:
+
+* create a new object
+* list all objects
+
+Go back to the splash screen, and quit the app. Note that the database runs in-memory (using HSQLDB) so any data created will be lost between runs.
+
+
+
+
+== Dev environment
+
+Set up xref:dg.adoc[an IDE] and import the project to be able to run and debug the app.
+
+Then set up a launch configuration so that you can run the app from within the IDE. To save having to run the fixtures
+every time, specify the following system properties:
+
+[source,bash]
+----
+-Disis.persistor.datanucleus.install-fixtures=true -Disis.fixtures=fixture.simple.scenario.SimpleObjectsFixture
+----
+
+For example, here's what a launch configuration in IntelliJ idea looks like:
+
+image::{_imagesdir}tutorials/pet-clinic/020-01-idea-configuration.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/020-01-idea-configuration.png"]
+
+
+
+where the "before launch" maven goal (to run the DataNucleus enhancer) is defined as:
+
+
+image::{_imagesdir}tutorials/pet-clinic/020-02-idea-configuration.png[width="400px",link="{_imagesdir}tutorials/pet-clinic/020-02-idea-configuration.png"]
+
+
+
+
+== Explore codebase
+
+Apache Isis applications are organized into several Maven modules. Within your IDE navigate to the various classes and correlate back to the generated UI:
+
+* `petclinic` : parent module
+* `petclinic-dom`: domain objects module
+** entity: `dom.simple.SimpleObject`
+** repository: `dom.simple.SimpleObjects`
+* `petclinic-fixture`: fixtures module
+** fixture script:`fixture.simple.SimpleObjectsFixture`
+* `petclinic-integtests`: integration tests module
+* `petclinic-webapp`: webapp module
+** (builds the WAR file)
+
+
+
+
+== Testing
+
+Testing is of course massively important, and Isis makes both unit testing and (end-to-end) integration testing easy. Building the app from the Maven command line ("mvn clean install") will run all tests, but you should also run the tests from within the IDE.
+
+* `myapp-dom` unit tests
+* run
+* inspect, eg
+ - `SimpleObjectTest`
+* `myapp-integtests` integration tests
+* run
+* inspect, eg:
+** `integration.tests.smoke.SimpleObjectsTest`
+** `integration.specs.simple.SimpleObjectSpec_listAllAndCreate.feature`
+* generated report, eg
+ - `myapp/integtests/target/cucumber-html-report/index.html`
+** change test in IDE, re-run (in Maven)
+
+If you have issues with the integration tests, make sure that the domain classes have been enhanced by the DataNucleus enhancer. (The exact mechanics depends on the IDE being used).
+
+
+
+
+== Update POM files
+
+[TIP]
+====
+[source,bash]
+----
+git checkout https://github.com/danhaywood/isis-app-petclinic/commit/68904752bc2de9ebb3c853b79236df2b3ad2c944
+----
+
+====
+
+The POM files generated by the simpleapp archetype describe the app as "SimpleApp". Update them to say "PetClinic" instead.
+
+
+
+
+== Delete the BDD specs
+
+[TIP]
+====
+[source,bash]
+----
+git checkout https://github.com/danhaywood/isis-app-petclinic/commit/9046226249429b269325dfa2baccf03635841c20
+----
+
+====
+
+
+During this tutorial we're going to keep the integration tests in-sync with the code, but we're going to stop short of writing BDD/Cucumber specs.
+
+Therefore delete the BDD feature spec and glue in the `integtest` module:
+
+* `integration/specs/*`
+* `integration/glue/*`
+
+
+
+
+== Rename artifacts
+
+[TIP]
+====
+[source,bash]
+----
+git checkout https://github.com/danhaywood/isis-app-petclinic/commit/bee3629c0b64058f939b6dd20f226be31810fc66
+----
+
+====
+
+
+Time to start refactoring the app. The heart of the PetClinic app is the `Pet` concept, so go through the code and refactor. While we're at it, refactor the app itself from "SimpleApp" to "PetClinicApp".
+
+See the git commit for more detail, but in outline, the renames required are:
+
+* in the `dom` module's production code
+** `SimpleObject` -> `Pet` (entity)
+** `SimpleObjects` -> `Pets` (repository domain service)
+** `SimpleObject.layout.json` -> `Pet.layout.json` (layout hints for the `Pet` entity)
+** delete the `SimpleObject.png`, and add a new `Pet.png` (icon shown against all `Pet` instances).
+* in the `dom` module's unit test code
+** `SimpleObjectTest` -> `PetTest` (unit tests for `Pet` entity)
+** `SimpleObjectsTest` -> `PetsTest` (unit tests for `Pets` domain service)
+* in the `fixture` module:
+** `SimpleObjectsFixturesService` -> `PetClinicAppFixturesService` (rendered as the prototyping menu in the UI)
+** `SimpleObjectsTearDownService` -> `PetClinicAppTearDownService` (tear down all objects between integration tests)
+** `SimpleObjectAbstract` -> `PetAbstract` (abstract class for setting up a single pet object
+*** and corresponding subclasses to set up sample data (eg `PetForFido`)
+** `SimpleObjectsFixture` -> `PetsFixture` (tear downs system and then sets up all pets)
+* in the `integtest` module:
+** `SimpleAppSystemInitializer` -> `PetClinicAppSystemInitializer` (bootstraps integration tests with domain service/repositories)
+** `SimpleAppIntegTest` -> `PetClinicAppIntegTest` (base class for integration tests)
+** `SimpleObjectTest` -> `PetTest` (integration test for `Pet` entity)
+** `SimpleObjectsTest` -> `PetsTest` (integration test for `Pets` domain service)
+* in the `webapp` module:
+** `SimpleApplication` -> `PetClinicApplication`
+** update `isis.properties`
+** update `web.xml`
+
+
+Note that `Pet` has both both Isis and JDO annotations:
+
+[source,java]
+----
+@javax.jdo.annotations.PersistenceCapable(identityType=IdentityType.DATASTORE) // <1>
+@javax.jdo.annotations.DatastoreIdentity( // <2>
+ strategy=javax.jdo.annotations.IdGeneratorStrategy.IDENTITY,
+ column="id")
+@javax.jdo.annotations.Version( // <3>
+ strategy=VersionStrategy.VERSION_NUMBER,
+ column="version")
+@javax.jdo.annotations.Unique(name="Pet_name_UNQ", members = {"name"}) // <4>
+@ObjectType("PET") // <5>
+@Bookmarkable // <6>
+public class Pet implements Comparable<Pet> {
+ ...
+}
+----
+
+where:
+
+<1> `@PersistenceCapable` and
+<2> `@DatastoreIdentity` specify a surrogate `Id` column to be used as the primary key
+<3> `@Version` provides support for optimistic locking
+<4> `@Unique` enforces a uniqueness constraint so that no two `Pet`s can have the same name (unrealistic, but can refactor later)
+<5> `@ObjectType` is used by Isis for its own internal "OID" identifier; this also appears in the URL in Isis' Wicket viewer and REST API
+<6> `@Bookmarkable` indicates that the object can be automatically bookmarked in Isis' Wicket viewer
+
+[NOTE]
+====
+The `@ObjectType` and `@Bookmarkable` annotations have since been deprecated, replaced with `@DomainObject(objectType=...)` and `@DomainObjectLayout(bookmarking=...)`
+====
+
+
+The `Pets` domain service also has Isis annotations:
+
+[source,java]
+----
+@DomainService(repositoryFor = Pet.class)
+@DomainServiceLayout(menuOrder = "10")
+public class Pets {
+ ...
+}
+----
+
+where:
+
+* `DomainService` indicates that the service should be instantiated automatically (as a singleton)
+* `DomainServiceLayout` provides UI hints, in this case the positioning of the menu for the actions provided by the service
+
+To run the application will require an update to the IDE configuration, for the changed name of the fixture class:
+
+
+image::{_imagesdir}tutorials/pet-clinic/030-01-idea-configuration-updated.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/030-01-idea-configuration-updated.png"]
+
+
+Running the app should now show `Pet`s:
+
+image::{_imagesdir}tutorials/pet-clinic/030-02-updated-app.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/030-02-updated-app.png"]
+
+
+
+
+
+== Update package names
+
+[TIP]
+====
+[source,bash]
+----
+git checkout https://github.com/danhaywood/isis-app-petclinic/commit/55ec36e520191f5fc8fe7f5b89956814eaf13317
+----
+
+====
+
+
+
+The classes created by the simpleapp archetype are by default in the `simple` package. Move these classes to `pets` package instead. Also adjust package names where they appear as strings:
+
+* in `PetClinicAppFixturesService`, change the package name from "fixture.simple" to "fixture.pets".
+* in `PetClinicAppSystemInitializer`, change the package name "dom.simple" to "dom.pets", and similarly "fixture.simple" to "fixture.pets"
+* in `WEB-INF/isis.properties`, similarly change the package name "dom.simple" to "dom.pets", and similarly "fixture.simple" to "fixture.pets"
+
+To run the application will require a further update to the IDE configuration, for the changed package of the fixture class:
+
+
+image::{_imagesdir}tutorials/pet-clinic/040-01-idea-configuration-updated.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/040-01-idea-configuration-updated.png"]
+
+
+
+== Add `PetSpecies` enum
+
+[TIP]
+====
+[source,bash]
+----
+git checkout https://github.com/danhaywood/isis-app-petclinic/commit/55c9cd28ff960220719b3dc7cb8abadace8d0829
+----
+
+====
+
+
+Each `Pet` is of a particular species. Model these as an enum called `PetSpecies`:
+
+[source,java]
+----
+public enum PetSpecies {
+ Cat,
+ Dog,
+ Budgie,
+ Hamster,
+ Tortoise
+}
+----
+
+Introduce a new property on `Pet` of this type:
+
+[source,java]
+----
+public class Pet {
+ ...
+ private PetSpecies species;
+ @javax.jdo.annotations.Column(allowsNull = "false")
+ public PetSpecies getSpecies() { return species; }
+ public void setSpecies(final PetSpecies species) { this.species = species; }
+ ...
+}
+----
+
+Update fixtures, unit tests and integration tests.
+
+
+
+
+== Icon to reflect pet species
+
+[TIP]
+====
+[source,bash]
+----
+git checkout https://github.com/danhaywood/isis-app-petclinic/commit/2212765694693eb463f8fa88bab1bad154add0cb
+----
+
+====
+
+
+Rather than using a single icon for a domain class, instead a different icon can be supplied for each instance. We can therefore have different icon files for each pet, reflecting that pet's species.
+
+[source,java]
+----
+public class Pet {
+ ...
+ public String iconName() {
+ return getSpecies().name();
+ }
+ ...
+}
+----
+
+Download corresponding icon files (`Dog.png`, `Cat.png` etc)
+
+Running the app shows the `Pet` and its associated icon:
+
+image::{_imagesdir}tutorials/pet-clinic/050-01-list-all.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/050-01-list-all.png"]
+
+
+
+with the corresponding view of the `Pet`:
+
+image::{_imagesdir}tutorials/pet-clinic/050-02-view-pet.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/050-02-view-pet.png"]
+
+
+== Add pet's `Owner`
+
+[TIP]
+====
+[source,bash]
+----
+git checkout https://github.com/danhaywood/isis-app-petclinic/commit/6f92a8ee8e76696d005da2a8b7a746444d017546
+----
+
+====
+
+
+Add the `Owner` entity and corresponding `Owners` domain service (repository). Add a query to find `Order`s by name:
+
+[source,java]
+----
+...
+@javax.jdo.annotations.Queries( {
+ @javax.jdo.annotations.Query(
+ name = "findByName", language = "JDOQL",
+ value = "SELECT "
+ + "FROM dom.owners.Owner "
+ + "WHERE name.matches(:name)")
+})
+public class Owner ... {
+ ...
+}
+----
+
+and `findByName(...)` in `Owners`:
+
+[source,java]
+----
+public class Owners {
+ ...
+ public List<Owner> findByName(
+ @ParameterLayout(named = "Name")
+ final String name) {
+ final String nameArg = String.format(".*%s.*", name);
+ final List<Owner> owners = container.allMatches(
+ new QueryDefault<>(
+ Owner.class,
+ "findByName",
+ "name", nameArg));
+ return owners;
+ }
+ ...
+}
+----
+
+Add an `owner` property to `Pet`, with supporting `autoCompleteXxx()` method (so that available owners are shown in a drop-down list box):
+
+[source,java]
+----
+public class Pet ... {
+ ...
+ private Owner owner;
+ @javax.jdo.annotations.Column(allowsNull = "false")
+ public Owner getOwner() { return owner; }
+ public void setOwner(final Owner owner) { this.owner = owner; }
+ public Collection<Owner> autoCompleteOwner(final @MinLength(1) String name) {
+ return owners.findByName(name);
+ }
+ ...
+}
+----
+
+Also updated fixture data to set up a number of `Owner`s, and associate each `Pet` with an `Owner`. Also add unit tests and integration tests for `Owner`/`Owners` and updated for `Pet`/`Pets`.
+
+When running the app, notice the new `Owners` menu:
+
+image::{_imagesdir}tutorials/pet-clinic/060-01-owners-menu.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/060-01-owners-menu.png"]
+
+which when invoked returns all `Owner` objects:
+
+image::{_imagesdir}tutorials/pet-clinic/060-02-owners-list.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/060-02-owners-list.png"]
+
+
+Each `Pet` also indicates its corresponding `Owner`:
+
+image::{_imagesdir}tutorials/pet-clinic/060-03-pets-list.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/060-03-pets-list.png"]
+
+
+And, on editing a `Pet`, a new `Owner` can be specified using the autoComplete:
+
+image::{_imagesdir}tutorials/pet-clinic/060-04-pet-owner-autoComplete.png[width="600px",link="{_imagesdir}tutorials/pet-clinic/060-04-pet-owner-autoComplete.png"]
+
[23/45] isis git commit: ISIS-1133: breaking out reference guide and
devenv guide;
moving appendices' release notes and migration notes to other docs;
improving the documentation page.
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/testing/fixture-scripts/organizing-fixture-scripts.pptx
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/testing/fixture-scripts/organizing-fixture-scripts.pptx b/adocs/documentation/src/main/asciidoc/guides/images/testing/fixture-scripts/organizing-fixture-scripts.pptx
new file mode 100644
index 0000000..268a738
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/testing/fixture-scripts/organizing-fixture-scripts.pptx differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/testing/fixture-scripts/prompt-specifying-number.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/testing/fixture-scripts/prompt-specifying-number.png b/adocs/documentation/src/main/asciidoc/guides/images/testing/fixture-scripts/prompt-specifying-number.png
new file mode 100644
index 0000000..e9b4ba2
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/testing/fixture-scripts/prompt-specifying-number.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/testing/fixture-scripts/prompt.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/testing/fixture-scripts/prompt.png b/adocs/documentation/src/main/asciidoc/guides/images/testing/fixture-scripts/prompt.png
new file mode 100644
index 0000000..6c22c49
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/testing/fixture-scripts/prompt.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/testing/fixture-scripts/prototyping-menu.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/testing/fixture-scripts/prototyping-menu.png b/adocs/documentation/src/main/asciidoc/guides/images/testing/fixture-scripts/prototyping-menu.png
new file mode 100644
index 0000000..ed85463
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/testing/fixture-scripts/prototyping-menu.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/testing/fixture-scripts/result-list-specifying-number.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/testing/fixture-scripts/result-list-specifying-number.png b/adocs/documentation/src/main/asciidoc/guides/images/testing/fixture-scripts/result-list-specifying-number.png
new file mode 100644
index 0000000..2ac7e88
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/testing/fixture-scripts/result-list-specifying-number.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/testing/fixture-scripts/result-list.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/testing/fixture-scripts/result-list.png b/adocs/documentation/src/main/asciidoc/guides/images/testing/fixture-scripts/result-list.png
new file mode 100644
index 0000000..abe4a0e
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/testing/fixture-scripts/result-list.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/testing/integ-tests.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/testing/integ-tests.png b/adocs/documentation/src/main/asciidoc/guides/images/testing/integ-tests.png
new file mode 100644
index 0000000..7c47d7e
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/testing/integ-tests.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/testing/integ-tests.pptx
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/testing/integ-tests.pptx b/adocs/documentation/src/main/asciidoc/guides/images/testing/integ-tests.pptx
new file mode 100644
index 0000000..df192b8
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/testing/integ-tests.pptx differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/testing/wrapper-factory.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/testing/wrapper-factory.png b/adocs/documentation/src/main/asciidoc/guides/images/testing/wrapper-factory.png
new file mode 100644
index 0000000..ee68cd5
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/testing/wrapper-factory.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/010-01-login-page.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/010-01-login-page.png b/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/010-01-login-page.png
new file mode 100644
index 0000000..068c3a8
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/010-01-login-page.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/010-02-home-page.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/010-02-home-page.png b/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/010-02-home-page.png
new file mode 100644
index 0000000..59c2726
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/010-02-home-page.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/010-03-prototyping-menu.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/010-03-prototyping-menu.png b/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/010-03-prototyping-menu.png
new file mode 100644
index 0000000..ed85463
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/010-03-prototyping-menu.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/010-04-simpleobjects.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/010-04-simpleobjects.png b/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/010-04-simpleobjects.png
new file mode 100644
index 0000000..324083d
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/010-04-simpleobjects.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/010-05-simpleobject-list.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/010-05-simpleobject-list.png b/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/010-05-simpleobject-list.png
new file mode 100644
index 0000000..79bfffa
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/010-05-simpleobject-list.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/020-01-idea-configuration.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/020-01-idea-configuration.png b/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/020-01-idea-configuration.png
new file mode 100644
index 0000000..1ee8280
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/020-01-idea-configuration.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/020-02-idea-configuration.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/020-02-idea-configuration.png b/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/020-02-idea-configuration.png
new file mode 100644
index 0000000..99be18b
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/020-02-idea-configuration.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/030-01-idea-configuration-updated.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/030-01-idea-configuration-updated.png b/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/030-01-idea-configuration-updated.png
new file mode 100644
index 0000000..c836f14
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/030-01-idea-configuration-updated.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/030-02-updated-app.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/030-02-updated-app.png b/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/030-02-updated-app.png
new file mode 100644
index 0000000..c438315
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/030-02-updated-app.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/040-01-idea-configuration-updated.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/040-01-idea-configuration-updated.png b/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/040-01-idea-configuration-updated.png
new file mode 100644
index 0000000..acddc93
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/040-01-idea-configuration-updated.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/050-01-list-all.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/050-01-list-all.png b/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/050-01-list-all.png
new file mode 100644
index 0000000..1c87cca
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/050-01-list-all.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/050-02-view-pet.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/050-02-view-pet.png b/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/050-02-view-pet.png
new file mode 100644
index 0000000..77824ce
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/050-02-view-pet.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/060-01-owners-menu.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/060-01-owners-menu.png b/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/060-01-owners-menu.png
new file mode 100644
index 0000000..642f9dc
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/060-01-owners-menu.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/060-02-owners-list.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/060-02-owners-list.png b/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/060-02-owners-list.png
new file mode 100644
index 0000000..db0ec25
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/060-02-owners-list.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/060-03-pets-list.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/060-03-pets-list.png b/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/060-03-pets-list.png
new file mode 100644
index 0000000..f2b9230
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/060-03-pets-list.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/060-04-pet-owner-autoComplete.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/060-04-pet-owner-autoComplete.png b/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/060-04-pet-owner-autoComplete.png
new file mode 100644
index 0000000..d301b59
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/060-04-pet-owner-autoComplete.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/domain-model.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/domain-model.png b/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/domain-model.png
new file mode 100644
index 0000000..268e998
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/tutorials/pet-clinic/domain-model.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/about-page/about-page.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/about-page/about-page.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/about-page/about-page.png
new file mode 100644
index 0000000..ae5dfc8
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/about-page/about-page.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/application-menu/dividers.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/application-menu/dividers.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/application-menu/dividers.png
new file mode 100644
index 0000000..dcb415d
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/application-menu/dividers.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/application-menu/layout-menus.pdn
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/application-menu/layout-menus.pdn b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/application-menu/layout-menus.pdn
new file mode 100644
index 0000000..01453f7
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/application-menu/layout-menus.pdn differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/application-menu/layout-menus.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/application-menu/layout-menus.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/application-menu/layout-menus.png
new file mode 100644
index 0000000..0bc73d1
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/application-menu/layout-menus.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/application-menu/tertiary.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/application-menu/tertiary.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/application-menu/tertiary.png
new file mode 100644
index 0000000..f2d2281
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/application-menu/tertiary.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/bookmarked-pages/panel-940.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/bookmarked-pages/panel-940.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/bookmarked-pages/panel-940.png
new file mode 100644
index 0000000..c572707
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/bookmarked-pages/panel-940.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/bookmarked-pages/panel-estatio-940.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/bookmarked-pages/panel-estatio-940.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/bookmarked-pages/panel-estatio-940.png
new file mode 100644
index 0000000..2fad852
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/bookmarked-pages/panel-estatio-940.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/bookmarked-pages/panel-estatio.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/bookmarked-pages/panel-estatio.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/bookmarked-pages/panel-estatio.png
new file mode 100644
index 0000000..0fa0cfa
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/bookmarked-pages/panel-estatio.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/bookmarked-pages/panel.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/bookmarked-pages/panel.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/bookmarked-pages/panel.png
new file mode 100644
index 0000000..b0d85f7
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/bookmarked-pages/panel.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/brand-logo/brand-logo-signin.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/brand-logo/brand-logo-signin.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/brand-logo/brand-logo-signin.png
new file mode 100644
index 0000000..92a022d
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/brand-logo/brand-logo-signin.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/brand-logo/brand-logo.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/brand-logo/brand-logo.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/brand-logo/brand-logo.png
new file mode 100644
index 0000000..7ab8ab3
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/brand-logo/brand-logo.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/copy-link/010-copy-link-button-940.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/copy-link/010-copy-link-button-940.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/copy-link/010-copy-link-button-940.png
new file mode 100644
index 0000000..bf70a84
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/copy-link/010-copy-link-button-940.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/copy-link/010-copy-link-button.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/copy-link/010-copy-link-button.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/copy-link/010-copy-link-button.png
new file mode 100644
index 0000000..ef64d29
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/copy-link/010-copy-link-button.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/copy-link/020-copy-link-dialog-940.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/copy-link/020-copy-link-dialog-940.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/copy-link/020-copy-link-dialog-940.png
new file mode 100644
index 0000000..84d050a
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/copy-link/020-copy-link-dialog-940.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/copy-link/020-copy-link-dialog.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/copy-link/020-copy-link-dialog.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/copy-link/020-copy-link-dialog.png
new file mode 100644
index 0000000..6be3190
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/copy-link/020-copy-link-dialog.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/copy-link/030-hints-940.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/copy-link/030-hints-940.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/copy-link/030-hints-940.png
new file mode 100644
index 0000000..3a4f690
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/copy-link/030-hints-940.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/copy-link/030-hints.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/copy-link/030-hints.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/copy-link/030-hints.png
new file mode 100644
index 0000000..5010132
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/copy-link/030-hints.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/copy-link/040-copy-link-with-hints-940.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/copy-link/040-copy-link-with-hints-940.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/copy-link/040-copy-link-with-hints-940.png
new file mode 100644
index 0000000..29ccf3b
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/copy-link/040-copy-link-with-hints-940.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/copy-link/040-copy-link-with-hints.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/copy-link/040-copy-link-with-hints.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/copy-link/040-copy-link-with-hints.png
new file mode 100644
index 0000000..da9674f
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/copy-link/040-copy-link-with-hints.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/copy-link/050-title-url-940.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/copy-link/050-title-url-940.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/copy-link/050-title-url-940.png
new file mode 100644
index 0000000..955e6b2
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/copy-link/050-title-url-940.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/copy-link/050-title-url.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/copy-link/050-title-url.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/copy-link/050-title-url.png
new file mode 100644
index 0000000..7fbf6d5
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/copy-link/050-title-url.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/embedded-view/no-footer.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/embedded-view/no-footer.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/embedded-view/no-footer.png
new file mode 100644
index 0000000..48d3a39
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/embedded-view/no-footer.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/embedded-view/no-header-no-footer.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/embedded-view/no-header-no-footer.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/embedded-view/no-header-no-footer.png
new file mode 100644
index 0000000..4e238f6
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/embedded-view/no-header-no-footer.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/embedded-view/no-header.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/embedded-view/no-header.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/embedded-view/no-header.png
new file mode 100644
index 0000000..22e245b
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/embedded-view/no-header.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/embedded-view/regular.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/embedded-view/regular.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/embedded-view/regular.png
new file mode 100644
index 0000000..926fb7d
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/embedded-view/regular.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/010-attachment-field-940.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/010-attachment-field-940.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/010-attachment-field-940.png
new file mode 100644
index 0000000..96cbb31
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/010-attachment-field-940.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/010-attachment-field.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/010-attachment-field.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/010-attachment-field.png
new file mode 100644
index 0000000..013f6e2
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/010-attachment-field.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/020-edit-choose-file-940.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/020-edit-choose-file-940.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/020-edit-choose-file-940.png
new file mode 100644
index 0000000..7f90bea
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/020-edit-choose-file-940.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/020-edit-choose-file.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/020-edit-choose-file.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/020-edit-choose-file.png
new file mode 100644
index 0000000..a7e3dc4
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/020-edit-choose-file.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/030-choose-file-using-browser-520.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/030-choose-file-using-browser-520.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/030-choose-file-using-browser-520.png
new file mode 100644
index 0000000..6a32d1b
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/030-choose-file-using-browser-520.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/030-choose-file-using-browser.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/030-choose-file-using-browser.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/030-choose-file-using-browser.png
new file mode 100644
index 0000000..700c325
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/030-choose-file-using-browser.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/040-edit-chosen-file-indicated-940.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/040-edit-chosen-file-indicated-940.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/040-edit-chosen-file-indicated-940.png
new file mode 100644
index 0000000..d6bc924
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/040-edit-chosen-file-indicated-940.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/040-edit-chosen-file-indicated.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/040-edit-chosen-file-indicated.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/040-edit-chosen-file-indicated.png
new file mode 100644
index 0000000..60ea5b3
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/040-edit-chosen-file-indicated.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/050-ok-if-image-then-rendered-940.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/050-ok-if-image-then-rendered-940.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/050-ok-if-image-then-rendered-940.png
new file mode 100644
index 0000000..302bbbc
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/050-ok-if-image-then-rendered-940.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/050-ok-if-image-then-rendered.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/050-ok-if-image-then-rendered.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/050-ok-if-image-then-rendered.png
new file mode 100644
index 0000000..50799b2
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/050-ok-if-image-then-rendered.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/060-download-940.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/060-download-940.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/060-download-940.png
new file mode 100644
index 0000000..41b4b27
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/060-download-940.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/060-download.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/060-download.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/060-download.png
new file mode 100644
index 0000000..f726d0d
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/060-download.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/070-edit-clear-940.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/070-edit-clear-940.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/070-edit-clear-940.png
new file mode 100644
index 0000000..0eae54e
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/070-edit-clear-940.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/070-edit-clear.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/070-edit-clear.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/070-edit-clear.png
new file mode 100644
index 0000000..57c2a24
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/file-upload-download/070-edit-clear.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/layouts/estatio-Invoice.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/layouts/estatio-Invoice.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/layouts/estatio-Invoice.png
new file mode 100644
index 0000000..be7e917
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/layouts/estatio-Invoice.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/layouts/estatio-Lease.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/layouts/estatio-Lease.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/layouts/estatio-Lease.png
new file mode 100644
index 0000000..e80ecb2
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/layouts/estatio-Lease.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/layouts/estatio-LeaseItem.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/layouts/estatio-LeaseItem.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/layouts/estatio-LeaseItem.png
new file mode 100644
index 0000000..993d498
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/layouts/estatio-LeaseItem.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/layouts/todoapp-ToDoItem.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/layouts/todoapp-ToDoItem.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/layouts/todoapp-ToDoItem.png
new file mode 100644
index 0000000..3218651
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/layouts/todoapp-ToDoItem.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/recent-pages/recent-pages-940.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/recent-pages/recent-pages-940.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/recent-pages/recent-pages-940.png
new file mode 100644
index 0000000..2e55860
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/recent-pages/recent-pages-940.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/recent-pages/recent-pages.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/recent-pages/recent-pages.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/recent-pages/recent-pages.png
new file mode 100644
index 0000000..8be97de
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/recent-pages/recent-pages.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/suppress-password-reset/login-page-default.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/suppress-password-reset/login-page-default.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/suppress-password-reset/login-page-default.png
new file mode 100644
index 0000000..fdf2dee
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/suppress-password-reset/login-page-default.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/suppress-password-reset/login-page-suppress-password-reset.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/suppress-password-reset/login-page-suppress-password-reset.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/suppress-password-reset/login-page-suppress-password-reset.png
new file mode 100644
index 0000000..b557269
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/suppress-password-reset/login-page-suppress-password-reset.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/suppress-remember-me/login-page-default.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/suppress-remember-me/login-page-default.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/suppress-remember-me/login-page-default.png
new file mode 100644
index 0000000..fdf2dee
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/suppress-remember-me/login-page-default.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/suppress-remember-me/login-page-suppress-remember-me.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/suppress-remember-me/login-page-suppress-remember-me.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/suppress-remember-me/login-page-suppress-remember-me.png
new file mode 100644
index 0000000..fe69496
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/suppress-remember-me/login-page-suppress-remember-me.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/suppress-sign-up/login-page-default.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/suppress-sign-up/login-page-default.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/suppress-sign-up/login-page-default.png
new file mode 100644
index 0000000..fdf2dee
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/suppress-sign-up/login-page-default.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/suppress-sign-up/login-page-suppress-sign-up.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/suppress-sign-up/login-page-suppress-sign-up.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/suppress-sign-up/login-page-suppress-sign-up.png
new file mode 100644
index 0000000..8ff8bc3
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/suppress-sign-up/login-page-suppress-sign-up.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/theme-chooser/example-1.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/theme-chooser/example-1.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/theme-chooser/example-1.png
new file mode 100644
index 0000000..4db4b18
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/theme-chooser/example-1.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/theme-chooser/example-2.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/theme-chooser/example-2.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/theme-chooser/example-2.png
new file mode 100644
index 0000000..435194d
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/theme-chooser/example-2.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/user-registration/login-page-default.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/user-registration/login-page-default.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/user-registration/login-page-default.png
new file mode 100644
index 0000000..fdf2dee
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/user-registration/login-page-default.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/user-registration/sign-up-after-registration.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/user-registration/sign-up-after-registration.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/user-registration/sign-up-after-registration.png
new file mode 100644
index 0000000..59902f9
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/user-registration/sign-up-after-registration.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/user-registration/sign-up-email-with-verification-link.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/user-registration/sign-up-email-with-verification-link.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/user-registration/sign-up-email-with-verification-link.png
new file mode 100644
index 0000000..021b642
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/user-registration/sign-up-email-with-verification-link.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/user-registration/sign-up-login-page-after-sign-up.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/user-registration/sign-up-login-page-after-sign-up.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/user-registration/sign-up-login-page-after-sign-up.png
new file mode 100644
index 0000000..3402bf6
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/user-registration/sign-up-login-page-after-sign-up.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/user-registration/sign-up-page.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/user-registration/sign-up-page.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/user-registration/sign-up-page.png
new file mode 100644
index 0000000..8e3bdaa
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/user-registration/sign-up-page.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/user-registration/sign-up-registration-page.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/user-registration/sign-up-registration-page.png b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/user-registration/sign-up-registration-page.png
new file mode 100644
index 0000000..189965a
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/wicket-viewer/user-registration/sign-up-registration-page.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/resources/core-concepts/Pawson-Naked-Objects-thesis.pdf
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/resources/core-concepts/Pawson-Naked-Objects-thesis.pdf b/adocs/documentation/src/main/asciidoc/guides/resources/core-concepts/Pawson-Naked-Objects-thesis.pdf
new file mode 100644
index 0000000..aca07e4
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/resources/core-concepts/Pawson-Naked-Objects-thesis.pdf differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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..4f93c97
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rg.adoc
@@ -0,0 +1,14 @@
+[[rg]]
+= Reference Guide
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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:
+
+
+include::_rg_annotations.adoc[leveloffset=+1]
+include::_rg_methods.adoc[leveloffset=+1]
+include::_rg_services-api.adoc[leveloffset=+1]
+include::_rg_services-spi.adoc[leveloffset=+1]
+include::_rg_classes.adoc[leveloffset=+1]
+include::_rg_object-layout.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..9083741
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ug.adoc
@@ -0,0 +1,27 @@
+[[ug]]
+= User Guide
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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:
+
+
+include::_ug_core-concepts.adoc[leveloffset=+1]
+include::_ug_getting-started.adoc[leveloffset=+1]
+include::_ug_tutorials.adoc[leveloffset=+1]
+
+include::_ug_how-tos.adoc[leveloffset=+1]
+include::_ug_more-advanced.adoc[leveloffset=+1]
+
+include::_ug_wicket-viewer.adoc[leveloffset=+1]
+include::_ug_restfulobjects-viewer.adoc[leveloffset=+1]
+include::_ug_security.adoc[leveloffset=+1]
+include::_ug_runtime.adoc[leveloffset=+1]
+
+include::_ug_isis-maven-plugin.adoc[leveloffset=+1]
+include::_ug_deployment.adoc[leveloffset=+1]
+include::_ug_testing.adoc[leveloffset=+1]
+include::_ug_headless-access.adoc[leveloffset=+1]
+include::_ug_extending.adoc[leveloffset=+1]
+include::_ug_troubleshooting.adoc[leveloffset=+1]
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/how-isis-works.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/how-isis-works.adoc b/adocs/documentation/src/main/asciidoc/how-isis-works.adoc
index c978b8f..9264c93 100644
--- a/adocs/documentation/src/main/asciidoc/how-isis-works.adoc
+++ b/adocs/documentation/src/main/asciidoc/how-isis-works.adoc
@@ -15,6 +15,6 @@ video::ludOLyi6VyY[youtube,width="840px",height="630px"]
[NOTE]
====
-Note that this screencast shows an earlier version of the xref:_ug_wicket-viewer[Wicket viewer] UI (specifically, pre 1.8.0).
+Note that this screencast shows an earlier version of the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] UI (specifically, pre 1.8.0).
====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/powered-by.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/powered-by.adoc b/adocs/documentation/src/main/asciidoc/powered-by.adoc
index 7cb27a2..054745c 100644
--- a/adocs/documentation/src/main/asciidoc/powered-by.adoc
+++ b/adocs/documentation/src/main/asciidoc/powered-by.adoc
@@ -12,7 +12,12 @@ pass:[<br/><br/>]
Here are some freely accessible (and sometimes open source) applications that are powered by Isis.
->If you have written an app in Isis that you'd like to share, please mention it on the link:./support.html[mailing list].
+[TIP]
+====
+If you have written an app in Isis that you'd like to share, please mention it on the link:./support.html[mailing list].
+====
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/release-notes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/release-notes.adoc b/adocs/documentation/src/main/asciidoc/release-notes.adoc
index a6b6d92..007e597 100644
--- a/adocs/documentation/src/main/asciidoc/release-notes.adoc
+++ b/adocs/documentation/src/main/asciidoc/release-notes.adoc
@@ -6,6 +6,136 @@
:toc: right
+
+== Summary
+
+This table summarises all releases of Apache Isis to date.
+
+[cols="1,1,2a,3a"]
+|===
+| Version | Date | Components | Notes
+
+| xref:r1.8.0[1.8.0]
+| 24-feb-2015
+| * link:https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311171&version=12328845[core-1.8.0]
+* link:https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311171&version=12328847[archetype-1.8.0]
+| Wicket viewer moved into core; todoapp archetype moved to link:http://www.isisaddons.org[Isis Addons] (non-ASF).
+
+| xref:r1.7.0[1.7.0]
+| 18-oct-2014
+| * link:https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311171&version=12326453[core-1.7.0]
+* link:https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311171&version=12326460[viewer-wicket-1.7.0]
+* link:https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311171&version=12327441[archetype-simpleapp-1.7.0]
+* link:https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311171&version=12327440[archetype-todoapp-1.7.0]
+| Module functionality previously in 1.6.0 now retired; use http://isisaddons.org[Isis Addons] (non-ASF) instead.
+
+| xref:r1.6.0[1.6.0]
+| 28-jul-2014
+| * link:https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311171&version=12325314[core-1.6.0]
+* link:https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311171&version=12325318[viewer-wicket-1.6.0]
+* link:https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311171&version=12326462[archetype-simpleapp-1.6.0]
+* link:https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311171&version=12326461[archetype-todoapp-1.6.0]
+| Restful Objects viewer, JDO/Datanucleus Objectstore and Shiro Security all moved into core. Quickstart-wrj archetype renamed to todoapp; simple-wrj archetype renamed to simpleapp. Some functionality copied/refactored as link:http://www.isisaddons.org[Isis Addons] (non-ASF).
+
+| xref:r1.5.0[1.5.0]
+| 08-jun-2014
+| * link:https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311171&version=12326524[core-1.5.0]
+* link:https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311171&version=12326525[objectstore-jdo-1.5.0]
+* link:https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311171&version=12326529[security-shiro-1.5.0]
+* link:https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311171&version=12326947[viewer-restfulobjects-2.3.0]
+* link:https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311171&version=12326526[viewer-wicket-1.5.0]
+* link:https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311171&version=12326528[archetype-simple-wrj-1.5.0]
+* link:https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311171&version=12326527[archetype-quickstart-wrj-1.5.0]
+| No longer releasing security-file
+
+| xref:r1.4.1[1.4.1]
+| 14-mar-2014
+| * objectstore-jdo-1.4.1
+* viewer-wicket-1.4.1
+* archetype-simple-wrj-1.4.1
+* archetype-quickstart-wrj-1.4.1
+| Patch release
+
+| xref:r1.4.0[1.4.0]
+| 11-mar-2014
+| * core-1.4.0
+* objectstore-jdo-1.4.0
+* security-file-1.4.0
+* security-shiro-1.4.0
+* viewer-restfulobjects-2.2.0
+* viewer-wicket-1.4.0
+* archetype-simple-wrj-1.4.0
+* archetype-quickstart-wrj-1.4.0
+|
+
+| xref:r1.3.1[1.3.1]
+| 7-nov-2013
+| * viewer-wicket-1.3.1
+* archetype-simple-wrj-1.3.1
+* archetype-quickstart-wrj-1.3.1
+| Patch release
+
+| xref:r1.8.0[1.3.0]
+| 25-oct-2013
+| * core-1.3.0
+* objectstore-jdo-1.3.0
+* security-file-1.0.2
+* security-shiro-1.3.0
+* viewer-restfulobjects-2.1.0
+* viewer-wicket-1.3.0
+* archetype-simple-wrj-1.3.0
+* archetype-quickstart-wrj-1.3.0
+| WRJ archetype renamed to Quickstart WRJ. Simple WRJ archetype added.
+
+| xref:r1.2.0[1.2.0]
+| 30-may-2013
+| * core-1.2.0
+* objectstore-jdo-1.2.0
+* security-file-1.0.1
+* security-shiro-1.1.1
+* viewer-restfulobjects-2.0.0
+* viewer-wicket-1.2.0
+* archetype-wrj-1.0.3
+|
+
+| xref:r1.1.0[1.1.0]
+| 31-jan-2013
+|* core-1.1.0
+* security-shiro-1.1.0
+* viewer-wicket-1.1.0
+* archetype-wrj-1.0.2
+|
+
+| xref:r1.0.1[1.0.1]
+| 10-jan-2013
+| * security-shiro-1.0.0
+* archetype-wrj-1.0.1
+| Combining RestfulObjects and Wicket viewers into a single webapp, along with Shiro security
+
+| xref:r1.0.0[1.0.0]
+| 24-dec-2012
+|* core-1.0.0
+* security-file-1.0.0
+* viewer-wicket-1.0.0
+* viewer-restfulobjects-1.0.0
+* archetype-wrj-1.0.0
+| First release having graduated
+
+
+| 0.2.0-incubating
+| 20-feb-2012
+| * 0.2.0-incubating
+|
+
+| 0.1.2-incubating
+| 13-jul-2011
+| * 0.1.2-incubating
+| First release in the ASF incubator
+|===
+
+
+
+[[r1.8.0]]
== 1.8.0
Isis 1.8.0 incorporates the Wicket viewer, which was previously a separately released component. Other components that are included in core (that were previously released separately are: the Restful Objects viewer, Shiro Security and the JDO/DataNucleus ObjectStore.
@@ -127,7 +257,7 @@ Isis 1.8.0 incorporates the Wicket viewer, which was previously a separately rel
-
+[[r1.7.0]]
== 1.7.0
@@ -246,7 +376,7 @@ Moved to (non-ASF) link:http://isisaddons.org[Isis Addons]
-
+[[r1.6.0]]
== 1.6.0
=== Core
@@ -332,7 +462,7 @@ Isis core 1.6.0 also incorporates the Restful Objects viewer, Shiro Security and
-
+[[r1.5.0]]
== 1.5.0
=== Core
@@ -451,7 +581,7 @@ Isis core 1.6.0 also incorporates the Restful Objects viewer, Shiro Security and
-
+[[r1.4.1]]
== 1.4.1
=== Wicket Viewer
@@ -475,7 +605,7 @@ Isis core 1.6.0 also incorporates the Restful Objects viewer, Shiro Security and
-
+[[r1.4.0]]
== 1.4.0
=== Core
@@ -713,7 +843,7 @@ Isis core 1.6.0 also incorporates the Restful Objects viewer, Shiro Security and
-
+[[r1.3.1]]
== 1.3.1
=== Wicket Viewer
@@ -737,7 +867,7 @@ Isis core 1.6.0 also incorporates the Restful Objects viewer, Shiro Security and
-
+[[r1.3.0]]
== 1.3.0
=== Core
@@ -941,9 +1071,6 @@ Isis core 1.6.0 also incorporates the Restful Objects viewer, Shiro Security and
=== JDO ObjectStore
-
-
-
==== New Feature
* link:https://issues.apache.org/jira/browse/ISIS-322[ISIS-322] - Allow JDO objectstore to run on the Google App Engine
@@ -993,7 +1120,7 @@ Isis core 1.6.0 also incorporates the Restful Objects viewer, Shiro Security and
-
+[[r1.2.0]]
== 1.2.0
=== Core
@@ -1122,7 +1249,7 @@ Isis core 1.6.0 also incorporates the Restful Objects viewer, Shiro Security and
-
+[[r1.1.0]]
== 1.1.0
=== Core
@@ -1256,9 +1383,24 @@ Isis core 1.6.0 also incorporates the Restful Objects viewer, Shiro Security and
+
+[[r1.0.1]]
+== 1.0.1
+
+=== Shiro Security
+
+
+
+==== New Feature
+
+* link:https://issues.apache.org/jira/browse/ISIS-290[ISIS-290] - Use shiro for security (implementation of Authentication and Authorization Manager)
+
+
+
+
+
-
-
+[[r1.0.0]]
== 1.0.0
=== Core
@@ -1363,22 +1505,6 @@ Isis core 1.6.0 also incorporates the Restful Objects viewer, Shiro Security and
* link:https://issues.apache.org/jira/browse/ISIS-256[ISIS-256] - NullPointerReference exceptions when attempting to persist an object
-
-
-
-
-
-
-=== Shiro Security
-
-
-
-==== New Feature
-
-* link:https://issues.apache.org/jira/browse/ISIS-290[ISIS-290] - Use shiro for security (implementation of Authentication and Authorization Manager)
-
-
-
=== JDO ObjectStore
@@ -1393,3 +1519,9 @@ Isis core 1.6.0 also incorporates the Restful Objects viewer, Shiro Security and
==== Improvement
* link:https://issues.apache.org/jira/browse/ISIS-246[ISIS-246] - DataNucleus
+
+
+
+
+
+include::_release-notes_migration-notes.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/release-process-one-pager.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/release-process-one-pager.adoc b/adocs/documentation/src/main/asciidoc/release-process-one-pager.adoc
index 6c2c1f8..2e78554 100644
--- a/adocs/documentation/src/main/asciidoc/release-process-one-pager.adoc
+++ b/adocs/documentation/src/main/asciidoc/release-process-one-pager.adoc
@@ -99,7 +99,7 @@ mvn clean install -o
Actually, you may want to defer this and do after cutting the release (ie beginning of a new dev cycle)
====
-==== Update plugin versions
+=== Update plugin versions
[source]
@@ -108,7 +108,7 @@ mvn versions:display-plugin-updates > /tmp/foo
grep "\->" /tmp/foo | /bin/sort -u
----
-==== Newer dependencies:
+=== Newer dependencies:
[source]
----
@@ -118,7 +118,7 @@ grep "\->" /tmp/foo | /bin/sort -u
== Update license information
-==== Missing license headers in files:
+=== Missing license headers in files:
[source]
----
@@ -126,7 +126,7 @@ mvn org.apache.rat:apache-rat-plugin:check -D rat.numUnapprovedLicenses=50 -o
for a in `/bin/find . -name rat.txt -print`; do grep '!???' $a; done
----
-==== Missing/spurious `supplemental-models.xml`
+=== Missing/spurious `supplemental-models.xml`
[source]
----
@@ -154,7 +154,7 @@ git commit -am "ISIS-nnnn: updates to pom.xml etc for release"
Make sure you are in the correct directory (eg `core`, or `example/archetype/zzz`)
====
-==== Prepare:
+=== Prepare:
first the dry run:
@@ -178,7 +178,7 @@ mvn release:prepare -P apache-release -DskipTests=true -Dresume=false \
-Dtag=$ISISART-$ISISREL-$ISISRC
----
-==== Confirm:
+=== Confirm:
[source]
----
@@ -204,7 +204,7 @@ cat DEPENDENCIES
popd
----
-==== Perform:
+=== Perform:
[source]
----
@@ -237,4 +237,4 @@ Then push tag:
----
git push origin refs/tags/$ISISART-$ISISREL-$ISISRC:refs/tags/$ISISART-$ISISREL-$ISISRC
git fetch
-----
\ No newline at end of file
+----
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/screencasts.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/screencasts.adoc b/adocs/documentation/src/main/asciidoc/screencasts.adoc
index 0d4424e..a772c2d 100644
--- a/adocs/documentation/src/main/asciidoc/screencasts.adoc
+++ b/adocs/documentation/src/main/asciidoc/screencasts.adoc
@@ -53,7 +53,7 @@ _How to import an Apache Isis maven-based application into Eclipse and configure
NB: when configuring DataNucleus for the *dom* project, make sure you are in the 'Java perspective', not the 'Java EE perspective'). +
-Learn more link:./user-guide/ug.html#_ug_appendices_dev-env_eclipse[here]
+Learn more link:./guides/dg.html#_dg_eclipse[here]
|video::RgcYfjQ8yJA[youtube,width="420px",height="315px"]
@@ -63,7 +63,7 @@ Learn more link:./user-guide/ug.html#_ug_appendices_dev-env_eclipse[here]
_How to import an Apache Isis maven-based application into IntelliJ and run the app._ +
-Learn more link:./user-guide/ug.html#_ug_appendices_dev-env_intellij[here]
+Learn more link:./guides/dg.html#_dg_intellij[here]
|video::lwKsyTbTSnA[youtube,width="420px",height="315px"]
@@ -132,7 +132,7 @@ _Using the (non-ASF) http://github.com/isisaddons/isis-module-excel[Isis addons'
_How to layout properties and collections dynamically_ +
-Learn more link:./user-guide/ug.html#_ug_reference-object-layout[here]
+Learn more link:./user-guide/rg.html#_rg-object-layout[here]
|video::zmrg49WeEPc[youtube,width="420px",height="236px"]
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/simpleapp-archetype.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/simpleapp-archetype.adoc b/adocs/documentation/src/main/asciidoc/simpleapp-archetype.adoc
index bf3eb66..6dd2b37 100644
--- a/adocs/documentation/src/main/asciidoc/simpleapp-archetype.adoc
+++ b/adocs/documentation/src/main/asciidoc/simpleapp-archetype.adoc
@@ -96,7 +96,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:../../user-guide/ug.html#_ug_wicket-viewer[Wicket viewer] and the link:../../user-guide/ug.html#_ug_restfulobjects-viewer[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/ug.html#_ug_wicket-viewer[Wicket viewer] and the link:./guides/ug.html#_ug_restfulobjects-viewer[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.
@@ -170,7 +170,7 @@ The app itself is configured to run using shiro security, as configured in the `
== Modifying the App
-Once you are familiar with the generated app, you'll want to start modifying it. Check out our the link:../../user-guide/ug.html[User Guide], which has how-tos and a complete reference guide (as well as some background concepts and discussion of more advanced techniques).
+Once you are familiar with the generated app, you'll want to start modifying it. Check out our the link:.guides/ug.html[User Guide], which has how-tos and a complete reference guide (as well as some background concepts and discussion of more advanced techniques).
If you use IntelliJ or Eclipse, you'll also want to set up your IDE; this is also described in the user guide appendices.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices.adoc
deleted file mode 100644
index b36f3ff..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices.adoc
+++ /dev/null
@@ -1,11 +0,0 @@
-[[_ug_appendices]]
-= Appendices
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-include::_ug_appendices_dev-env.adoc[leveloffset=+1]
-include::_ug_appendices_release-notes.adoc[leveloffset=+1]
-include::_ug_appendices_migration-notes.adoc[leveloffset=+1]
-include::_ug_appendices_articles-and-presentations.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_articles-and-presentations.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_articles-and-presentations.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_articles-and-presentations.adoc
deleted file mode 100644
index 26abf57..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_articles-and-presentations.adoc
+++ /dev/null
@@ -1,125 +0,0 @@
-[[_ug_appendices_articles-and-presentations]]
-= Articles, Conferences etc
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 articles and recorded material relating to either Apache Isis (or its predecessor, the Naked Objects framework), or its 'sister' open source project on the .NET platform, Naked Objects .NET. We've *highlighted* some of the better ones?
-
-
-[cols="1,1,5a", options="header"]
-|===
-
-|When
-|Where
-|Description
-
-.2+|2014
-|Presentation, BDD Exchange
-|https://skillsmatter.com/skillscasts/5638-to-those-whom-much-is-given-much-is-expected[To those whom much is given, much is expected? ] (45 min. video)
-
-| Presentation, JEEConf
-| https://www.youtube.com/watch?v=BNGUqZ6YE-M[Extremely rapid application development with Apache Isis] (50 min. video)
-
-.5+| 2013
-| Presentation, Oredev
-| http://oredev.org/2013/wed-fri-conference/rrraddd-ridiculously-rapid-domain-driven-and-restful-apps-with-apache-isis[RRRADDD! Ridiculously Rapid Domain-driven (and Restful) Apps With Apache Isis] (50 min. video)
-
-| *Article, Methods and Tools *
-| *http://www.methodsandtools.com/PDF/mt201302.pdf[Introducing Apache Isis]*
-
-| Article, SDJournal
-| http://sdjournal.org/software-developers-journal-open-012013-2/[Introducing Isis]
-
-| Article, SDJournal
-| http://sdjournal.org/software-developers-journal-open-012013-2/[Restful Objects on Apache Isis]
-
-|
-| A Prezi http://prezi.com/cunfhjsf8dqg/braiv-apache-isis/[presentation on Naked Objects and Apache Isis], mixed by Thomas Eck
-
-
-
-.2+|2012
-|*Article, InfoQ*
-|*http://www.infoq.com/articles/Intro_Restful_Objects[Introducing Restful Objects]*
-
-|Presentation, Skillsmatter
-|http://skillsmatter.com/podcast/java-jee/restful-objects[Restful Objects - A Hypermedia API For Domain Object Models]
-
-
-
-.2+|2011
-|*Presentation, InfoQ*
-|*http://www.infoq.com/presentations/Large-scale-Pure-OO-Irish-Government[Case study: Large-scale Pure OO at the Irish Government]* (1 hr video)
-
-| Article, InfoQ
-|http://www.infoq.com/articles/haywood-ddd-no[Interview and Book Excerpt: Dan Haywood's Domain Driven Design using Naked Objects]
-
-
-
-
-.3+|2010
-|Presentation, Skillsmatter
-|http://skillsmatter.com/podcast/java-jee/have-your-ddd-cake-eat-it-too[How to have your domain-driven design cake and eat it, too] (1 hr video)
-
-|Article, InfoQ
-|http://www.infoq.com/articles/Nacked-MVC[Fulfilling the Promise of MVC] (Naked Objects .NET)
-
-
-|*Podcast, Hanselminutes*
-|*http://www.hanselman.com/blog/HanselminutesPodcast233InsideTheNakedObjectsFrameworkWithRichardPawson.aspx[Inside the Naked Objects Framework with Richard Pawson]* (Naked Objects .NET) (30 min)
-
-
-
-.5+|2009
-|*Article, Methods and Tools*
-|*http://www.methodsandtools.com/archive/archive.php?id=97[An Introduction to Domain Driven Design]*
-
-|Presentation, Skillsmatter
-|http://skillsmatter.com/podcast/design-architecture/exploring-domains-and-collaborating-with-domain-experts[Exploring Domains and Collaborating with Domain Experts] (1 hr video)
-
-|Presentation, Devoxx
-|http://www.parleys.com/#id=1671&st=5[Introducing Scimpi] (30 min video)
-
-|Article, PragPub
-|http://pragprog.com/magazines/2009-12[Going Naked]
-
-|*Book, PragProg*
-|*Domain Driven Design using Naked Objects, Dan Haywood*
-
-
-
-
-|2008
-|Article, InfoQ
-|http://www.infoq.com/articles/RAD-Naked-Objects[Rapid Application Development using Naked Objects for .NET] (Naked Objects .NET)
-
-
-
-
-.2+|2004
-|University College, Dublin
-|*Richard Pawson's link:resources/core-concepts/Pawson-Naked-Objects-thesis.pdf[PhD thesis on Naked Objects]*
-
-|Article series, TheServerSide
-|* Part 1 - http://www.theserverside.com/news/1365562/Part-1-The-Case-for-Naked-Objects-Getting-Back-to-the-Object-Oriented-Ideal[The Case for Naked Objects - Getting Back to the Object-Oriented Ideal]
-
-* *Part 2 - http://www.theserverside.com/news/1365568/Part-2-Challenging-the-Dominant-Design-of-the-4-Layer-Architecture[Challenging the Dominant Design of the 4-Layer Architecture]*
-
-* Part 3 - http://www.theserverside.com/news/1365570/Part-3-Write-an-application-in-Java-and-deploy-it-on-Net[Write an application in Java and deploy it on .Net]
-
-* Part 4 - http://www.theserverside.com/news/1366868/Part-4-Modeling-simultaneously-in-UML-Java-and-User-Perspectives[Modeling simultaneously in UML, Java, and User Perspectives]
-
-* Part 5 - http://www.theserverside.com/news/1366871/Part-5-Building-Rich-Internet-Applications-with-Naked-Objects[Building Rich Internet Applications with Naked Objects]
-
-
-
-
-|2002
-|*Book, Wiley*
-|*Naked Objects, Richard Pawson and Robert Matthews.*
-
-|===
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_dev-env.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_dev-env.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_dev-env.adoc
deleted file mode 100644
index 7d800f2..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_dev-env.adoc
+++ /dev/null
@@ -1,12 +0,0 @@
-[[_ug_appendices_dev-env]]
-= Setting up a Development Environment
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-This section describes how to build Isis applications either from the command line (as per your link:http://en.wikipedia.org/wiki/Continuous_integration[continuous integration] server or within an IDE.
-
-include::_ug_appendices_dev-env_cmd-line.adoc[leveloffset=+1]
-include::_ug_appendices_dev-env_intellij.adoc[leveloffset=+1]
-include::_ug_appendices_dev-env_eclipse.adoc[leveloffset=+1]
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_dev-env_cmd-line.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_dev-env_cmd-line.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_dev-env_cmd-line.adoc
deleted file mode 100644
index 936bc54..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_dev-env_cmd-line.adoc
+++ /dev/null
@@ -1,9 +0,0 @@
-[[_ug_appendices_dev-env_cmd-line]]
-= Developing from the Command Line
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../../../
-:_imagesdir: images/
-:toc: right
-
-IMPORTANT: TODO
-
[28/45] isis git commit: ISIS-1133: breaking out reference guide and
devenv guide;
moving appendices' release notes and migration notes to other docs;
improving the documentation page.
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_security_shiro-isis-enhanced-wildcard-permission.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_security_shiro-isis-enhanced-wildcard-permission.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_security_shiro-isis-enhanced-wildcard-permission.adoc
new file mode 100644
index 0000000..f656dda
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_security_shiro-isis-enhanced-wildcard-permission.adoc
@@ -0,0 +1,61 @@
+[[_ug_security_shiro-isis-enhanced-wildcard-permission]]
+= Enhanced Wildcard Permission
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 using the text-based xref:ug.adoc#_ug_security_shiro-ini-realm[`IniRealm`] or xref:ug.adoc#_ug_security_shiro-isis-ldap-realm[Isis' LDAP realm], then note that Shiro also allows the string representation of the permissions to be mapped (resolved) to alternative `Permission` instances. Isis provides its own `IsisPermission` which introduces the concept of a "veto".
+
+A vetoing permission is one that prevents access to a feature, rather than grants it. This is useful in some situations where most users have access to most features, and only a small number of features are particularly sensitive. The configuration can therefore be set up to grant fairly broad-brush permissions and then veto permission for the sensitive features for those users that do not have access.
+
+The string representation of the `IsisPermission` uses the following format:
+
+[source,ini]
+----
+([!]?)([^/]+)[/](.+)
+----
+
+where:
+
+* the optional `!` prefix indicates this permission is a vetoing permission
+* the optional `xxx/` prefix is a permission group that scopes any vetoing permissions
+* the remainder of the string is the permission (possibly wildcarded, with :rw as optional suffix)
+
+
+For example:
+
+[source,ini]
+----
+user_role = !reg/org.estatio.api,\
+ !reg/org.estatio.webapp.services.admin,\
+ reg/* ; \
+api_role = org.estatio.api ;\
+admin_role = adm/*
+----
+
+sets up:
+
+* the `user_role` with access to all permissions except those in `org.estatio.api` and `org.estatio.webapp.services.admin`
+* the `api_role` with access to all permissions in `org.estatio.api`
+* the `admin_role` with access to everything.
+
+The permission group concept is required to scope the applicability of any veto permission. This is probably best explained by an example. Suppose that a user has both `admin_role` and `user_role`; we would want the `admin_role` to trump the vetos of the `user_role`, in other words to give the user access to everything.
+
+
+Because of the permission groups, the two "+++!reg/...+""" vetos in user_role only veto out selected permissions granted by the "+++reg/*+++" permissions, but they do not veto the permissions granted by a different scope, namely "+++adm/*+++".
+
+The net effect is therefore what we would want: that a user with both `admin_role` and `user_role` would have access to everything, irrespective of those two veto permissions of the `user_role`.
+
+
+
+Finally, the Isis permission resolver is specified in `WEB-INF/shiro.ini` file:
+
+[source,ini]
+----
+permissionResolver = org.apache.isis.security.shiro.authorization.IsisPermissionResolver
+myRealm.permissionResolver = $permissionResolver # <1>
+----
+<1> `myRealm` is the handle to the configured realm, eg `$iniRealm` or `$isisLdapRealm` etc.
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_security_shiro-isis-ldap-realm.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_security_shiro-isis-ldap-realm.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_security_shiro-isis-ldap-realm.adoc
new file mode 100644
index 0000000..a7feadc
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_security_shiro-isis-ldap-realm.adoc
@@ -0,0 +1,146 @@
+[[_ug_security_shiro-isis-ldap-realm]]
+= Isis Ldap Realm
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 ships with an implementation of http://shiro.apache.org[Apache Shiro]'s `Realm` class that allows user authentication and authorization to be performed against an LDAP server.
+
+image::{_imagesdir}security/security-apis-impl/configure-shiro-to-use-isis-ldap-realm.png[width="600px"]
+
+The LDAP database stores the user/passwords and user groups, while the `shiro.ini` file is used to map the LDAP groups to roles, and to map the roles to permissions.
+
+== Shiro Configuration
+
+To use LDAP involves telling Shiro how to instantiate the realm. This bootstrapping info lives in the `WEB-INF/shiro.ini`:
+
+[source,ini]
+----
+contextFactory = org.apache.isis.security.shiro.IsisLdapContextFactory
+contextFactory.url = ldap://localhost:10389
+contextFactory.systemUsername = uid=admin,ou=system # <1>
+contextFactory.systemPassword = secret
+contextFactory.authenticationMechanism = CRAM-MD5 # <2>
+contextFactory.systemAuthenticationMechanism = simple
+
+ldapRealm = org.apache.isis.security.shiro.IsisLdapRealm # <3>
+ldapRealm.contextFactory = $contextFactory
+
+ldapRealm.searchBase = ou=groups,o=mojo # <4>
+ldapRealm.groupObjectClass = groupOfUniqueNames # <5>
+ldapRealm.uniqueMemberAttribute = uniqueMember # <6>
+ldapRealm.uniqueMemberAttributeValueTemplate = uid={0}
+
+# optional mapping from physical groups to logical application roles
+ldapRealm.rolesByGroup = \ # <7>
+ LDN_USERS: user_role,\
+ NYK_USERS: user_role,\
+ HKG_USERS: user_role,\
+ GLOBAL_ADMIN: admin_role,\
+ DEMOS: self-install_role
+
+ldapRealm.permissionsByRole=\ # <8>
+ user_role = *:ToDoItemsJdo:*:*,\
+ *:ToDoItem:*:*; \
+ self-install_role = *:ToDoItemsFixturesService:install:* ; \
+ admin_role = *
+
+securityManager.realms = $ldapRealm
+----
+<1> user accounts are searched using a dedicated service account
+<2> SASL (CRAM-MD5) authentication is used for this authentication
+<3> Isis' implementation of the LDAP realm.
+<4> groups are searched under `ou=groups,o=mojo` (where `mojo` is the company name)
+<5> each group has an LDAP objectClass of `groupOfUniqueNames`
+<6> each group has a vector attribute of `uniqueMember`
+<7> groups looked up from LDAP can optionally be mapped to logical roles; otherwise groups are used as role names directly
+<8> roles are mapped in turn to permissions
+
+The value of `uniqueMember` is in the form `uid=xxx`, with `xxx` being the uid of the user
+* users searched under `ou=system`
+* users have, at minimum, a `uid` attribute and a password
+* the users credentials are used to verify their user/password
+
+The above configuration has been tested against http://directory.apache.org/apacheds/[ApacheDS], v1.5.7. This can be administered using http://directory.apache.org/studio/[Apache Directory Studio], v1.5.3.
+
+
+[TIP]
+.Shiro Realm Mappings
+====
+When configuring role based permission mapping, there can only be one of these entries per realm:
+
+[source,ini]
+----
+realm.groupToRolesMappings = ...
+----
+
+and
+
+[source,ini]
+----
+realm.roleToPermissionsMappings = ...
+----
+
+This forces you to put everything on one line for each of the above. This is, unfortunately, a Shiro "feature". And if you repeat the entries above then it's "last one wins".)
+
+To make the configuration maintainable, use "\" to separate the mappings onto separate lines in the file. Use this technique for both group to roles mapping and role to permission mapping. If you use the '' after the "," that separates the key:value pairs it is more readable.
+====
+
+
+
+
+
+
+== Externalizing role perms
+
+As an alternative to injecting the `permissionsByRole` property, the role/permission mapping can alternatively be specified by injecting a resource path:
+
+[source,ini]
+----
+ldapRealm.resourcePath=classpath:webapp/myroles.ini
+----
+
+where `myroles.ini` is in `src/main/resources/webapp`, and takes the form:
+
+[source,ini]
+----
+[roles]
+user_role = *:ToDoItemsJdo:*:*,\
+ *:ToDoItem:*:*
+self-install_role = *:ToDoItemsFixturesService:install:*
+admin_role = *
+----
+
+This separation of the role/mapping can be useful if Shiro is configured to support multiple realms (eg an LdapRealm based one and also an TextRealm)
+
+
+
+
+== Active DS LDAP tutorial
+
+The screenshots below show how to setup LDAP accounts in ApacheDS using the Apache Directory Studio.
+
+The setup here was initially based on http://krams915.blogspot.co.uk/2011/01/ldap-apache-directory-studio-basic.html[this tutorial], however we have moved the user accounts so that they are defined in a separate LDAP node.
+
+To start, create a partition in order to hold the mojo node (holding the groups):
+
+image::{_imagesdir}/configuration/configuring-shiro/ldap/activeds-ldap-mojo-partition.png[ActiveDS LDAP Users]
+
+Create the `ou=groups,o=mojo` hierarchy:
+
+image::{_imagesdir}/configuration/configuring-shiro/ldap/activeds-ldap-mojo-root-dse.png[ActiveDS LDAP Users]
+
+Configure SASL authentication. This means that the checking of user/password is done implicitly by virtue of Isis connecting to LDAP using these credentials:
+
+image::{_imagesdir}/configuration/configuring-shiro/ldap/activeds-ldap-sasl-authentication.png[ActiveDS LDAP Users]
+
+In order for SASL to work, it seems to be necessary to put users under `o=system`. (This is why the setup is slightly different than the tutorial mentioned above):
+
+image::{_imagesdir}/configuration/configuring-shiro/ldap/activeds-ldap-users.png[ActiveDS LDAP Users]
+
+Configure the users into the groups:
+
+image::{_imagesdir}/configuration/configuring-shiro/ldap/activeds-ldap-groups.png[ActiveDS LDAP Users]
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_security_shiro-isisaddons-security-module-realm.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_security_shiro-isisaddons-security-module-realm.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_security_shiro-isisaddons-security-module-realm.adoc
new file mode 100644
index 0000000..558ae54
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_security_shiro-isisaddons-security-module-realm.adoc
@@ -0,0 +1,36 @@
+[[_ug_security_shiro-isisaddons-security-module-realm]]
+= Security Module Realm
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 https://github.com/isisaddons/isis-module-security[Isis Addons' security module] (not ASF) provides a complete
+security subdomain for users, roles, permissions; all are persisted as domain entities.
+
+What that means, of course, that they can also be administered through your Isis application. Moreover, the set of permissions (to features) is derived completely from your application's metamodel; in essence the permissions are "type-safe".
+
+
+In order to play along, the module includes a Shiro realm, which fits in as follows:
+
+The general configuration is as follows:
+
+image::{_imagesdir}security/security-apis-impl/configure-shiro-to-use-isisaddons-security-module-realm.png[width="600px"]
+
+where the `IsisModuleSecurityRealm` realm is the implementation provided by the module.
+
+In the configuration above user passwords are stored in the database. The module uses link:http://www.mindrot.org/projects/jBCrypt/[jBCrypt] so that passwords are only stored in a (one-way) encrypted form in the database.
+
+
+
+The security module also supports a slightly more sophisticated configuration. Most organizations use LDAP for user credentials, and maintaining two separate user accounts would be less than ideal. The `IsisModuleSecurityRealm` can therefore be configured with a subsidiary "delegate" realm that is responsible for performing the primary authentication of the user; if that passes then a user is created (as a domain entity) automatically.
+In most cases this delegate realm will be the LDAP realm, and so the architecture becomes:
+
+image::{_imagesdir}security/security-apis-impl/configure-shiro-to-use-isisaddons-security-module-realm-with-delegate-realm.png[width="600px"]
+
+
+The security module has many more features than are described here, all of which are described in the module's link:https://github.com/isisaddons/isis-module-security[README]. The README also explains in detail how to configure an existing app to use this module.
+
+You can also look at the Isisaddons https://github.com/isisaddons/isis-app-todoapp[todoapp example] (not ASF), which is preconfigured to use the security module.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_security_shiro-jdbc-realm.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_security_shiro-jdbc-realm.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_security_shiro-jdbc-realm.adoc
new file mode 100644
index 0000000..ba901f3
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_security_shiro-jdbc-realm.adoc
@@ -0,0 +1,113 @@
+[[_ug_security_shiro-jdbc-realm]]
+= Shiro JDBC Realm
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 is nothing to stop you from using some other `Realm` implementation (or indeed writing one yourself). For example, you could use Shiro's own JDBC realm that loads user/password details from a database.
+
+[WARNING]
+====
+If you are happy to use a database then we strongly recommend you use the http://github.com/isisaddons/isis-module-security[Isis addons' security] module instead of a vanilla JDBC; it is far more sophisticated and moreover gives you the ability to administer the system from within your Isis application.
+====
+
+If you go down this route, then the architecture is as follows:
+
+image::{_imagesdir}security/security-apis-impl/configure-shiro-to-use-custom-jdbc-realm.png[width="600px"]
+
+
+
+
+There's quite a lot of configuration required (in `WEB-INF/shiro.ini`) to set up a JDBC realm, so we'll break it out into sections.
+
+First, we need to set up the connection to JDBC:
+
+[source,ini]
+----
+jdbcRealm=org.apache.shiro.realm.jdbc.JdbcRealm # <1>
+
+jof = org.apache.shiro.jndi.JndiObjectFactory # <2>
+jof.resourceName = jdbc/postgres # <3>
+jof.requiredType = javax.sql.DataSource
+jof.resourceRef = true
+
+jdbcRealm.dataSource = $jof # <4>
+----
+<1> instantiate the JDBC realm
+<2> instantiate factory object to lookup DataSource from servlet container
+<3> name of the datasource (as configured in `web.xml`)
+<4> instruct JDBC realm to obtain datasource from the JNDI
+
+
+We next need to tell the realm how to query the database. Shiro supports any schema; what matters is the input search argument and the output results.
+
+[source,ini]
+----
+
+jdbcRealm.authenticationQuery = \ # <1>
+ select password \
+ from users \
+ where username = ?
+
+jdbcRealm.userRolesQuery = \ # <2>
+ select r.label \
+ from users_roles ur \
+ inner join roles r \
+ on ur.role_id = r.id \
+ where user_id = ( \
+ select id \
+ from users \
+ where username = ?); \
+
+jdbcRealm.permissionsQuery= \ # <3>
+ select p.permission \
+ from roles_permissions rp \
+ inner join permissions p \
+ on rp.permission_id = p.id \
+ where rp.role_id = ( \
+ select id \
+ from roles \
+ where label = ?);
+
+jdbcRealm.permissionsLookupEnabled=true # <4>
+----
+<1> query to find password for user
+<2> query to find roles for user
+<3> query to find permissions for role
+<4> enable permissions lookup
+
+[WARNING]
+====
+The `permissionsLookupEnabled` is very important, otherwise Shiro just returns an empty list of permissions and your users will have no access to any features(!).
+====
+
+We also should ensure that the passwords are not stored as plain-text:
+
+[source,ini]
+----
+dps = org.apache.shiro.authc.credential.DefaultPasswordService # <1>
+pm = org.apache.shiro.authc.credential.PasswordMatcher # <2>
+pm.passwordService = $dps
+jdbcRealm.credentialsMatcher = $pm # <3>
+----
+<1> mechanism to encrypts password
+<2> service to match passwords
+<3> instruct JDBC realm to use password matching service when authenticating
+
+
+And finally we need to tell Shiro to use the realm, in the usual fashion:
+
+[source,ini]
+----
+securityManager.realms = $jdbcRealm
+----
+
+Using the above configuration you will also need to setup a `DataSource`. The details vary by servlet container, for example this is link:https://tomcat.apache.org/tomcat-8.0-doc/jndi-datasource-examples-howto.html[how to do the setup on Tomcat 8.0].
+
+[WARNING]
+====
+The name of the `DataSource` can also vary by servlet container; see for example link:http://stackoverflow.com/questions/17441019/how-to-configure-jdbcrealm-to-obtain-its-datasource-from-jndi/23784702#23784702[this StackOverflow answer].
+====
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_security_usage-by-isis-viewers.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_security_usage-by-isis-viewers.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_security_usage-by-isis-viewers.adoc
new file mode 100644
index 0000000..c21dbe6
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_security_usage-by-isis-viewers.adoc
@@ -0,0 +1,208 @@
+[[_ug_security_usage-by-isis-viewers]]
+= Usage by Isis' Viewers
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 and large the security mechanisms within Isis are transparent to the rest of the framework (the xref:ug.adoc#_ug_wicket-viewer[Wicket Viewer] and xref:ug.adoc#_ug_restfulobjects-viewer[Restful Objects viewer], and the overall xref:ug.adoc#_ug_runtime[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.
+
+
+
+
+== Wicket Viewer
+
+The xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] defines a relatively small number of pages (by which we mean subclasses of link:http://ci.apache.org/projects/wicket/apidocs/6.0.x/org/apache/wicket/markup/html/WebPage.html[`org.apache.wicket.markup.html.WebPage`]):
+
+* about page
+* action prompt page
+* entity page
+* error page
+* home page
+* standalone collection page
+* value page
+* void return page
+
+All of these (except about page) are annotated with the Wicket annotation:
+
+[source,java]
+----
+@AuthorizeInstantiation("org.apache.isis.viewer.wicket.roles.USER")
+----
+
+which means that they can only be accessed by a user with an authenticated session that has this special, reserved role. If not, Wicket will automatically redirect the user to the sign-in page.
+
+[TIP]
+====
+The sign-in page to render is pluggable; see xref:ug.adoc#_ug_extending_wicket-viewer_custom-pages[extensions chapter] for details.
+====
+
+In the sign-in page the viewer calls to the Isis Authenticator API, and obtains back a user/role. It also adds in its special reserved role (per the annotation above) and then continues on to whichever page the user was attempting to access (usually the home page).
+
+And that's really all there is to it. When the viewer renders a domain object it queries the Isis metamodel, and suppresses from the view any object members (properties, actions etc) that are invisible. These may be invisible because the user has no (read ) permission, or they may be invisible because of domain object logic (eg a `hideXxx()` method). The viewer neither knows nor cares.
+
+Similarly, for those object members that _are_ visible, the viewer also checks if they are enabled or disabled. Again, an object member will be disabled if the user does not have (write) permission, or it could be disabled because of domain object logic (eg a `disableXxx()` method).
+
+
+=== User-registration
+
+As well as providing a sign-in screen, the Wicket viewer also provides the ability for xref:_user_registration[users to self-register]. By and large this operates outside of Isis' security mechanisms; indeed the various pages (sign-up, sign-up verification, password reset) are all rendered _without_ there being any current user session. These pages all "reach inside" Isis framework using a mechanism similar to <<_headless_access>> in order to actually do their stuff.
+
+[TIP]
+====
+The sign-in verification page to render is pluggable; see xref:ug.adoc#_ug_extending_wicket-viewer_custom-pages[extensions chapter] for details.
+====
+
+User registration is only available if the xref:_user_registration_service[`UserRegistrationService`] is configured; this is used by the framework to actually create new instances of the user as accessed by the corresponding (Shiro) realm.
+
+Because Shiro realms are pluggable, the Isis framework does not provide default implementations of this service. However, if you are using the http://github.com/isisaddons/isis-module-security[Isis addons' security] module (non-ASF), then this module _does_ provide an implementation (that, as you might expect, creates new "user" domain entities).
+
+If you are using an LDAP realm and want to enable user-self registration then you'll need to write your own implementation of this service.
+
+
+
+== Restful Objects Viewer
+
+Unlike the Wicket viewer, the xref:ug.adoc#_ug_restfulobjects-viewer[Restful Objects viewer] does _not_ provide any sort of login page; rather it provides a pluggable authentication strategy, delegated to by the `IsisSessionFilter` filter defined in `web.xml`. The authentication strategy is responsible for ensuring that a session is available for the REST resource.
+
+The API of `AuthenticationSessionStrategy` is simply:
+
+[source,java]
+----
+package org.apache.isis.core.webapp.auth;
+...
+public interface AuthenticationSessionStrategy {
+ AuthenticationSession lookupValid( // <1>
+ ServletRequest servletRequest,
+ ServletResponse servletResponse);
+ void bind( // <2>
+ ServletRequest servletRequest,
+ ServletResponse servletResponse,
+ AuthenticationSession authSession);
+}
+
+----
+<1> returns a valid `AuthenticationSession` for the specified request, response
+<2> binds (associates the provided `AuthenticationSession`) to the request and response
+
+Here `AuthenticationSession` is Isis' internal API that represents a signed-on user.
+
+The framework provides a number of simple strategies:
+
+* `AuthenticationSessionStrategyBasicAuth` implements the HTTP basic auth protocol (the pop-up dialog box shown by the web browser)
+* `AuthenticationSessionStrategyHeader` that simply reads the user identity from an HTTP header
+* `AuthenticationSessionStrategyTrusted` that always logs in with a special "exploration" user
+
+As you can see, none of these should be considered production-quality.
+
+The strategy is configured in `web.xml`; for example:
+
+[source,xml]
+----
+<filter>
+ <filter-name>IsisSessionFilterForRestfulObjects</filter-name>
+ <filter-class>org.apache.isis.core.webapp.IsisSessionFilter</filter-class>
+ <init-param>
+ <param-name>authenticationSessionStrategy</param-name>
+ <param-value> <!--1-->
+ org.apache.isis.viewer.restfulobjects.server.authentication.AuthenticationSessionStrategyBasicAuth
+ </param-value>
+ </init-param>
+ <init-param>
+ <param-name>whenNoSession</param-name>
+ <param-value>basicAuthChallenge</param-value> <!--2-->
+ </init-param>
+</filter>
+----
+<1> configure basic auth strategy
+<2> what to do if no session was found; we indicate to issue a 401 basic authentication challenge
+
+The `IsisSessionFilter` has a further plugin point if no session was found (that is, if `AuthenticationSessionStrategy#lookupValid()` returns null), which is how to respond. The value "basicAuthChallenge" means to return a 401, which is what triggers the web browser to pop-up the basic HTTP challenge dialog box.
+
+The above filter must then be chained before the servlet that actually handles the REST requests:
+
+[source,xml]
+----
+<filter-mapping>
+ <filter-name>IsisSessionFilterForRestfulObjects</filter-name>
+ <servlet-name>RestfulObjectsRestEasyDispatcher</servlet-name>
+</filter-mapping>
+...
+<servlet>
+ <servlet-name>RestfulObjectsRestEasyDispatcher</servlet-name>
+ <servlet-class>org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher</servlet-class>
+</servlet>
+----
+
+[NOTE]
+====
+The above `web.xml` fragments do _not_ constitute the full configuration for the Restful Objects viewer, just those parts that pertain to security.
+====
+
+
+
+=== User-registration
+
+Isis currently does not have any out-of-the-box support for user-registration for applications using only the Restful viewer. However, in principal the pieces do exist to put together a solution.
+
+The general idea is similar to the design of the Wicket viewer; define some subsidiary resources that can operate _without_ a user session in place, and which "reach into" the framework using headless access in order to setup the user.
+
+[TIP]
+====
+An alternative approach, possibly less work and overall of more value, would be to implement `AuthenticationSessionStrategy` for oAuth, in other words allow users to use their existing Google or Facebook account.
+====
+
+The following steps sketch out the solution in a little more detail:
+
+* Define some new Restful resources (cf link:https://github.com/apache/isis/blob/master/core/viewer-restfulobjects-server/src/main/java/org/apache/isis/viewer/restfulobjects/server/resources/DomainObjectResourceServerside.java[`DomainServiceResourceServerside`] that correspond to sign-up/register page, eg `SignupResource` +
++
+[source,java]
+----
+@Path("/signup")
+public class SignupResource {
+ ...
+}
+----
+
+* Create a new subclass of `RestfulObjectsApplication`, eg "CustomRestfulObjectsApplication" and register your resources +
++
+[source,java]
+----
+public class CustomRestfulObjectsApplication extends RestfulObjectsApplication {
+ public CustomRestfulObjectsApplication() {
+ addClass(SignupResource.class);
+ }
+}
+----
+
+* Register your application class in `web.xml` instead of the default: +
++
+[source,xml]
+----
+<context-param>
+ <param-name>javax.ws.rs.Application</param-name>
+ <param-value>com.mycompany.myapp.CustomRestfulObjectsApplication</param-value>
+</context-param>
+----
+
+So far this is just standard javax.rs stuff.
+
+Next, we need to ensure that a client can hit your new resource *with* the Isis runtime in place, but without there being an Isis session. For that....
+
+* create a subclass of the `AuthenticationSessionStrategy` that automatically returns a dummy session if the resource being accessed is "/restful/signup", say. +
++
+You could do this by subclassing `AuthenticationSessionStrategyBasicAuth`, but then using code from `AuthenticationSessionStrategyBasicAuth` to return an "exploration" (or better, "signup") session if accessing the "/restful/signup" resource.
+
+* in the `SignUpResource` resource, you can then do a lookup of the `UserRegistrationService` in order to allow the user to be created: +
++
+[source,java]
+----
+final UserRegistrationService userRegistrationService =
+ IsisContext.getPersistenceSession().getServicesInjector().lookupService(UserRegistrationService.class);
+userRegistrationService.registerUser(userDetails);
+----
+
+Obviously the methods exposed by the `SignupResource` are up to you; ultimately they need to be able to gather information to populate the `UserDetails` object as passed to the `UserRegistrationService`.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_testing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_testing.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_testing.adoc
new file mode 100644
index 0000000..b92624a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_testing.adoc
@@ -0,0 +1,17 @@
+[[_ug_testing]]
+= Testing
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 you are going to use Apache Isis for developing complex business-critical applications, then being able to write automated tests for those applications becomes massively important. As such Apache Isis treats the topic of testing very seriously, and (though we say it ourselves) has support that goes way above what is provided by other application frameworks.
+
+
+include::_ug_testing_aaa.adoc[leveloffset=+1]
+include::_ug_testing_unit-test-support.adoc[leveloffset=+1]
+include::_ug_testing_integ-test-support.adoc[leveloffset=+1]
+include::_ug_testing_bdd-spec-support.adoc[leveloffset=+1]
+include::_ug_testing_fixture-scripts.adoc[leveloffset=+1]
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_testing_aaa.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_testing_aaa.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_testing_aaa.adoc
new file mode 100644
index 0000000..488686e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_testing_aaa.adoc
@@ -0,0 +1,166 @@
+[[_ug_testing_aaa]]
+= Overview
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+== Unit tests vs Integ tests
+
+We divide automated tests into two broad categories:
+
+- unit tests exercise a single unit (usually a method) of a domain object, in isolation. +
++
+Dependencies of that object are mocked out. These are written by a developer and for a developer; they are to ensure that a particular "cog in the machine" works correctly
+
+- integration tests exercise the application as a whole, usually focusing on one particular business operation (action). +
++
+These are tests that represent the acceptance criteria of some business story; their intent should make sense to the domain expert (even if the domain expert is "non-technical")
+
+To put it another way:
+
+[TIP]
+====
+Integration tests help ensure that you are *_building the right system_*
+
+Unit tests help ensure that you are *_building the system right_*.
+====
+
+
+
+== Integ tests vs BDD Specs
+
+We further sub-divide integration tests into:
+
+* those that are implemented in Java and JUnit (we call these simply _"integration tests"_) +
++
+Even if a domain expert understands the intent of these tests, the actual implementation will be opaque to them. Also, the only output from the tests is a (hopefully) green CI job
+
+* tests (or rather, specifications) that are implemented in a _behaviour-driven design_ (BDD) language such as link:https://cucumber.io/[Cucumber] (we call these _"BDD specs"_) +
++
+The natural language specification then maps down onto some glue code that is used to drive the application. But the benefits of taking a BDD approach include the fact that your domain expert will be able to read the tests/specifications, and that when you run the specs, you also get documentation of the application's behaviour ("living documentation").
+
+It's up to you whether you use BDD specs for your apps; it will depend on your development process and company culture. But you if don't then you certainly should write integration tests: acceptance criteria for user stories should be automated!
+
+
+
+
+
+== Simulated UI (`WrapperFactory`)
+
+When we talk about integration tests/specs here, we mean tests that exercise the domain object logic, through to the actual database. But we also want the tests to exercise the app from the users's perspective, which means including the user interface.
+
+For most other frameworks that would require having to test the application in a very heavy weight/fragile fashion using a tool such as link:http://docs.seleniumhq.org/[Selenium], driving a web browser to navigate . In this regard though, Isis has a significant trick up its sleeve. Because Isis implements the naked objects pattern, it means that the UI is generated automatically from the UI. This therefore allows for other implementations of the UI.
+
+The xref:rg.adoc#_rg_services-api_manpage-WrapperFactory[`WrapperFactory`] domain service allows a test to wrap domain objects and thus to interact with said objects "as if" through the UI:
+
+image::{_imagesdir}testing/integ-tests.png[width="700px"]
+
+If the test invokes an action that is disabled, then the wrapper will throw an appropriate exception. If the action is ok to invoke, it delegates through.
+
+What this means is that an Isis application can be tested end-to-end without having to deploy it onto a webserver; the whole app can be tested while running in-memory. Although integration tests re (necessarily) slower than unit tests, they are not any harder to write (in fact, in some respects they are easier).
+
+
+
+
+== Dependency Injection
+
+Isis provides autowiring dependency injection into every domain object. This is most useful when writing unit tests; simply mock out the service and inject into the domain object.
+
+There are a number of syntaxes supported, but the simplest is to use `@javax.inject.Inject` annotation; for example:
+
+[source,java]
+----
+@javax.inject.Inject
+CustomerRepository customers;
+----
+
+Isis can inject into this even if the field has package-level (or even `private`) visibility. We recommend that you use package-level visibility, though, so that your unit tests (in the same package as the class under test) are able to inject mocks.
+
+Isis does also support a couple of other syntaxes:
+
+[source,java]
+----
+public void setCustomerRepository(CustomerRepository customers) { ... }
+----
+
+or
+
+[source,java]
+----
+public void injectCustomerRepository(CustomerRepository customers) { ... }
+----
+
+
+[TIP]
+====
+Apache Isis also supports automatic dependency injection into integration tests; just declare the service dependency in the usual fashion and it will be automatically injected.
+====
+
+
+
+
+== Given/When/Then
+
+Whatever type of test/spec you are writing, we recommend you follow the given/when/then idiom:
+
+* *given* the system is in this state (preconditions)
+* *when* I poke it with a stick
+* *then* it looks like this (postconditions)
+
+A good test should be 5 to 10 lines long; the test should be there to help you reason about the behaviour of the system. Certainly if the test becomes more than 20 lines it'll be too difficult to understand.
+
+The "when" part is usually a one-liner, and in the "then" part there will often be only two or three assertions that you want to make that the system has changed as it should.
+
+For unit test the "given" part shouldn't be too difficult either: just instantiate the class under test, wire in the appropriate mocks and set up the expectations. And if there are too many mock expectations to set up, then "listen to the tests" ... they are telling you your design needs some work.
+
+Where things get difficult though is the "given" for integration tests; which is the topic of the next section...
+
+
+
+
+== Fixture Management
+
+In the previous section we discussed using given/when/then as a form of organizing tests, and why you should keep your tests small.
+
+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 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.
+
+
+
+
+
+== Fake data
+
+In any given test there are often quite a few variables involved, to initialize the state of the objects, or to act as arguments for invoking a method, or when asserting on post-conditions. Sometimes those values are important (eg verifying that an `Order`'s state went from PENDING to SHIPPED, say), but often they aren't (a customer's name, for example) but nevertheless need to be set up (especially in integration tests).
+
+We want our tests to be easily understood, and we want the reader's eye to be drawn to the values that are significant and ignore those that are not.
+
+One way to do this is to use random (or fake) values for any insignificant data. This in effect tells the reader that "any value will do". Moreover, if it turns out that any data won't do, and that there's some behaviour that is sensitive to the value, then the test will start to flicker, passing and then failing depending on inputs. This is A Good Thing™.
+
+Apache Isis does not, itself, ship with a fake data library. However, the http://github.com/isisaddons/isis-module-fakedata[Isis addons' fakedata] module (non-ASF) does provide exactly this capability.
+
+[TIP]
+====
+Using fake data works very well with fixture scripts; the fixture script can invoke the business action with sensible (fake/random) defaults, and only require that the essential information is passed into it by the test.
+====
+
+
+
+
+== Feature Toggles
+
+Writing automated tests is just good development practice. Also good practice is developing on the mainline (master, trunk); so that your continuous integration system really is integrating all code. Said another way: link:http://martinfowler.com/bliki/FeatureBranch.html[don't use branches]!
+
+Sometimes, though, a feature will take longer to implement than your iteration cycle. In such a case, how do you use continuous integration to keep everyone working on the mainline without revealing a half-implemented feature on your releases? One option is to use link:http://martinfowler.com/bliki/FeatureToggle.html[feature toggle]s.
+
+Apache Isis does not, itself, ship with a feature toggle library. However, the http://github.com/isisaddons/isis-module-togglz[Isis addons' togglz] module (non-ASF) does provide exactly this capability.
+
+
+
+
+
+With all that said, let's look in detail at the testing features provided by Apache Isis.
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_testing_bdd-spec-support.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_testing_bdd-spec-support.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_testing_bdd-spec-support.adoc
new file mode 100644
index 0000000..4589f8f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_testing_bdd-spec-support.adoc
@@ -0,0 +1,22 @@
+[[_ug_testing_bdd-spec-support]]
+= BDD Spec 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/
+
+
+link:http://en.wikipedia.org/wiki/Behavior-driven_development[Behaviour-driven design] (BDD) redefines testing not as an after-the-fact "let's check the system works", but rather as a means to work with the domain expert to (a) specify the behaviour of the feature _before_ starting implementation, and (b) provide a means that the domain expert can verify the feature after it has been implemented.
+
+Since domain experts are usually non-technical (at least, they are unlikely to be able to read or want to learn how to read JUnit/Java code), then applying BDD typically requires writing specifications in using structured English text and (ASCII) tables. The BDD tooling parses this text and uses it to actually interact with the system under test. As a byproduct the BDD frameworks generate readable output of some form; this is often an annotated version of the original specification, marked up to indicate which specifications passed, which have failed. This readable output is a form of "living documentation"; it captures the actual behaviour of the system, and so is guaranteed to be accurate.
+
+There are many BDD tools out there; Apache Isis provides an integration with link:https://cucumber.io/docs/reference/jvm#java[Cucumber JVM] (see also the https://github.com/cucumber/cucumber-jvm[github site]):
+
+
+
+include::_ug_testing_bdd-spec-support_how-it-works.adoc[leveloffset=+1]
+include::_ug_testing_bdd-spec-support_key-classes.adoc[leveloffset=+1]
+include::_ug_testing_bdd-spec-support_writing-a-bdd-spec.adoc[leveloffset=+1]
+include::_ug_testing_bdd-spec-support_bdd-tooling.adoc[leveloffset=+1]
+include::_ug_testing_bdd-spec-support_maven-configuration.adoc[leveloffset=+1]
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_testing_bdd-spec-support_bdd-tooling.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_testing_bdd-spec-support_bdd-tooling.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_testing_bdd-spec-support_bdd-tooling.adoc
new file mode 100644
index 0000000..384e684
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_testing_bdd-spec-support_bdd-tooling.adoc
@@ -0,0 +1,14 @@
+[[_ug_testing_bdd-spec-support_bdd-tooling]]
+= BDD Tooling
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 help write feature files and generate step definitions, we recommend https://github.com/rlogiacco/Natural[Roberto Lo Giacco's Eclipse plugin]. For more information, see Dan's short http://danhaywood.com/2013/07/05/cucumber-editors-in-eclipse/[blog post]. It works very well. Of interest: this is implemented using http://www.eclipse.org/Xtext/[XText].
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_testing_bdd-spec-support_how-it-works.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_testing_bdd-spec-support_how-it-works.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_testing_bdd-spec-support_how-it-works.adoc
new file mode 100644
index 0000000..ce3da2f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_testing_bdd-spec-support_how-it-works.adoc
@@ -0,0 +1,20 @@
+[[_ug_testing_bdd-spec-support_how-it-works]]
+= How it works
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+At a high level, here's how Cucumber works
+
+* specifications are written in the https://github.com/cucumber/cucumber/wiki/Gherkin[Gherkin] DSL, following the https://github.com/cucumber/cucumber/wiki/Given-When-Then["given/when/then"] format.
+
+* Cucumber-JVM itself is a JUnit runner, and searches for https://github.com/cucumber/cucumber/wiki/Feature-Introduction[feature files] on the classpath.
+
+* These in turn are matched to link:https://github.com/cucumber/cucumber/wiki/Step-Definitions[step definition]s through regular expressions. +
++
+It is the step definitions (the "glue") that exercise the system.
+
+The code that goes in step definitions is broadly the same as the code that goes in an integration test method. One benefit of using step definitions (rather than integration tests) is that the step definitions are reusable across scenarios, so there may be less code overall to maintain. For example, if you have a step definition that maps to "given an uncompleted todo item", then this can be used for all the scenarios that start with that as their precondition.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_testing_bdd-spec-support_key-classes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_testing_bdd-spec-support_key-classes.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_testing_bdd-spec-support_key-classes.adoc
new file mode 100644
index 0000000..3047e00
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_testing_bdd-spec-support_key-classes.adoc
@@ -0,0 +1,59 @@
+[[_ug_testing_bdd-spec-support_key-classes]]
+= Key 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/
+
+
+
+
+There are some key framework classes that make up the spec support; these are discussed below.
+
+NOTE: some of these are also used by Isis' xref:ug.adoc#_ug_testing_integ-test-support[Integration Test support].
+
+
+
+
+== `IsisSystemForTest`
+
+The `IsisSystemForTest` class allows a complete running instance of Isis to be bootstrapped (with the JDO objectstore); this is then held on a a `ThreadLocal` from one test to another.
+
+Typically bootstrapping code is used to lazily instantiate the `IsisSystemForTest` once and once only. The mechanism for doing this is line-for-line identical in both BDD step defs and integration tests.
+
+
+
+
+== `ScenarioExecution`
+
+The `ScenarioExecution` provides a context for a scenario that is being executed. It is Cucumber that determines which step definitions are run, and in which order, and so state cannot be passed between step definitions using local variables or instance variables. Instead the `ScenarioExecution` acts like a hashmap, allowing each step to put data (eg "given an uncompleted todoitem") into the map or get data ("when I complete the todoitem") from the map. This is done using the `putVar(...)` and `getVar(...)` methods.
+
+[TIP]
+====
+This corresponds broadly to the "World" object in Ruby-flavoured Cucumber.
+====
+
+The `ScenarioExecution` also provids access to the configured domain services (using the `service(...)` method) and the `DomainObjectContainer` (through the `container()` method).
+
+[NOTE]
+====
+This could probably be refactored; Cucumber JVM provides automatic dependency injection into setp definitions, but Isis does not currently leverage or exploit this capability.
+====
+
+Like the `IsisSystemForTest` class, the `ScenarioExecution` class binds an instance of itself onto a `ThreadLocal`. It can then be accessed in BDD step definitions using `ScenarioExecution.current()` static method.
+
+
+
+== `WrapperFactory`
+
+As with integration tests, the UI can be simulated by "wrapping" each domain object in a proxy using the `WrapperFactory`.
+
+
+
+
+== `CukeGlueAbstract`
+
+The `CukeGlueAbstract` acts as a convenience superclass for writing BDD step definitions (analogous to the `IntegrationTestAbstract` for integation tests). Underneath the covers it delegates to an underlying `ScenarioExecution`.
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_testing_bdd-spec-support_maven-configuration.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_testing_bdd-spec-support_maven-configuration.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_testing_bdd-spec-support_maven-configuration.adoc
new file mode 100644
index 0000000..4d008b8
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_testing_bdd-spec-support_maven-configuration.adoc
@@ -0,0 +1,73 @@
+[[_ug_testing_bdd-spec-support_maven-configuration]]
+= Maven Configuration
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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' 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:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.isis.core</groupId>
+ <artifactId>isis-core-specsupport</artifactId>
+ <scope>test</scope> // <1>
+</dependency>
+----
+<1> Normally `test`; usual Maven scoping rules apply.
+
+
+We also recommend that you configure the `maven-surefire-plugin` to pick up the following class patterns:
+
+
+[source,xml]
+----
+<plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-surefire-plugin</artifactId>
+ <version>2.10</version>
+ <configuration>
+ <includes>
+ <include>**/*Test.java</include>
+ <include>**/*Test_*.java</include>
+ <include>**/*Spec*.java</include>
+ </includes>
+ <excludes>
+ <exclude>**/Test*.java</exclude>
+ <exclude>**/*ForTesting.java</exclude>
+ <exclude>**/*Abstract*.java</exclude>
+ </excludes>
+ <useFile>true</useFile>
+ <printSummary>true</printSummary>
+ <outputDirectory>${project.build.directory}/surefire-reports</outputDirectory>
+ </configuration>
+</plugin>
+----
+
+
+You may also find it more convenient to place the `.feature` files in `src/test/java`, rather than `src/test/resources`. If you wish to do this, then your integtest module's `pom.xml` must contain:
+
+[source,xml]
+----
+<build>
+ <testResources>
+ <testResource>
+ <filtering>false</filtering>
+ <directory>src/test/resources</directory>
+ </testResource>
+ <testResource>
+ <filtering>false</filtering>
+ <directory>src/test/java</directory>
+ <includes>
+ <include>**</include>
+ </includes>
+ <excludes>
+ <exclude>**/*.java</exclude>
+ </excludes>
+ </testResource>
+ </testResources>
+</build>
+----
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_testing_bdd-spec-support_writing-a-bdd-spec.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_testing_bdd-spec-support_writing-a-bdd-spec.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_testing_bdd-spec-support_writing-a-bdd-spec.adoc
new file mode 100644
index 0000000..9412045
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_testing_bdd-spec-support_writing-a-bdd-spec.adoc
@@ -0,0 +1,141 @@
+[[_ug_testing_bdd-spec-support_writing-a-bdd-spec]]
+= Writing a BDD spec
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+
+BDD specifications contain:
+
+* a `XxxSpec.feature` file, describing the feature and the scenarios (given/when/then)s that constitute its acceptance criteria
+
+* a `RunSpecs.java` class file to run the specification (all boilerplate). This will run all `.feature` files in the same package or subpackages.
+
+* one or several `XxxGlue` constituting the step definitions to be matched against. +
++
+The "glue" (step definitions) are intended to be reused across features. We therefore recommend that they reside in a separate package, and are organized by the entity type upon which they act. +
++
+For example, given a feature that involves `Customer` and `Order`, have the step definitions pertaining to `Customer` reside in `CustomerGlue`, and the step definitions pertaining to `Order` reside in `OrderGlue`. +
++
+The `glue` attribute of the Cucumber-JVM JUnit runner eallows you to indicate which package(s) should be recursively searched to find any glue.
+
+* a system initializer class. You can reuse the system initializer from any integration tests (as described in xref:ug.adoc#_ug_testing_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]:
+
+[source,java]
+----
+@SimpleObjectsFixture
+Feature: List and Create New Simple Objects
+
+ @integration
+ Scenario: Existing simple objects can be listed and new ones created
+ Given there are initially 3 simple objects
+ When I create a new simple object
+ Then there are 4 simple objects
+----
+
+The `@SimpleObjectsFixture` is a custom tag we've specified to indicate the prerequisite fixtures to be loaded; more on this in a moment. The `@integration` tag, meanwhile, says that this feature should be run with integration-level scope.
+
+
+[NOTE]
+====
+Although BDD specs are most commonly used for end-to-end tests (ie at the same scope as an integration test), the two concerns (expressability of a test to a business person vs granularity of the test) should not be conflated. There are a couple of http://silkandspinach.net/2013/01/18/a-testing-strategy/[good] blog http://claysnow.co.uk/the-testing-iceberg/[posts] discussing http://claysnow.co.uk/living-documentation-can-be-readable-and-fast/[this]. The basic idea is to avoid the overhead of a heavy-duty integration test if possible.
+
+Apache Isis does also support running BDD specs in unit test mode; by annotating the scenario with the `@unit` (rather than `@integration` tag). When running under unit-level scope, the Isis system is _not_ instantiated. Instead, the `ScenarioExecution` class returns JMock mocks (except for the `WrapperFactory`, if configured).
+
+To support unit testing scope 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 Isis can support this.
+
+====
+
+
+The `RunSpecs` class to run this feature (and any other features in this package or subpackages) is just boilerplate
+
+[source,java]
+----
+@RunWith(Cucumber.class)
+@CucumberOptions(
+ format = {
+ "html:target/cucumber-html-report"
+ ,"json:target/cucumber.json"
+ },
+ glue={"classpath:domainapp.integtests.specglue"},
+ strict = true,
+ tags = { "~@backlog", "~@ignore" })
+public class RunSpecs {
+ // intentionally empty
+}
+----
+
+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 bootstrapping of Isis can be moved into a `BootstrappingGlue` step definition:
+
+[source,java]
+----
+public class BootstrappingGlue extends CukeGlueAbstract {
+ @Before(value={"@integration"}, order=100)
+ public void beforeScenarioIntegrationScope() {
+ org.apache.log4j.PropertyConfigurator.configure("logging.properties");
+ SimpleAppSystemInitializer.initIsft();
+
+ before(ScenarioExecutionScope.INTEGRATION);
+ }
+ @After
+ public void afterScenario(cucumber.api.Scenario sc) {
+ assertMocksSatisfied();
+ after(sc);
+ }
+}
+----
+
+The fixture to run also lives in its own step definition, https://github.com/apache/isis/blob/07fe61ef3fb029ae36427f60da2afeeb931e4f88/example/application/simpleapp/integtests/src/test/java/domainapp/integtests/specglue/CatalogOfFixturesGlue.java#L24[`CatalogOfFixturesGlue`]:
+
+[source,java]
+----
+public class CatalogOfFixturesGlue extends CukeGlueAbstract {
+ @Before(value={"@integration", "@SimpleObjectsFixture"}, order=20000)
+ public void integrationFixtures() throws Throwable {
+ scenarioExecution().install(new RecreateSimpleObjects());
+ }
+}
+----
+
+Note that this is annotated with a tag (`@SimpleObjectsFixture`) so that the correct fixture runs. (We might have a whole variety of these).
+
+The step definitions pertaining to `SimpleObject` domain entity then reside in the https://github.com/apache/isis/blob/07fe61ef3fb029ae36427f60da2afeeb931e4f88/example/application/simpleapp/integtests/src/test/java/domainapp/integtests/specglue/modules/simple/SimpleObjectGlue.java#L31[`SimpleObjectGlue`] class. This is where the heavy lifting gets done:
+
+[source,java]
+----
+public class SimpleObjectGlue extends CukeGlueAbstract {
+ @Given("^there are.* (\\d+) simple objects$")
+ public void there_are_N_simple_objects(int n) throws Throwable {
+ try {
+ final List<SimpleObject> findAll = service(SimpleObjects.class).listAll();
+ assertThat(findAll.size(), is(n));
+ putVar("list", "all", findAll);
+
+ } finally {
+ assertMocksSatisfied();
+ }
+ }
+ @When("^I create a new simple object$")
+ public void I_create_a_new_simple_object() throws Throwable {
+ service(SimpleObjects.class).create(UUID.randomUUID().toString());
+ }
+}
+----
+
+[TIP]
+====
+If using Java 8, note that Cucumber JVM supports a link:https://cucumber.io/docs/reference/jvm#java-8-lambdas[simplified syntax using lambdas].
+====
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_testing_fixture-scripts.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_testing_fixture-scripts.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_testing_fixture-scripts.adoc
new file mode 100644
index 0000000..2f311b7
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_testing_fixture-scripts.adoc
@@ -0,0 +1,44 @@
+[[_ug_testing_fixture-scripts]]
+= Fixture Scripts
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 writing integration tests (and implementing the glue for BDD specs) 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.
+
+On a very simple system you could probably get away with using SQL to insert directly into the database, or you could use a toolkit such as link:http://dbunit.sourceforge.net/howto.html[dbunit] to upload data from flat files. Such approaches aren't particularly maintainable though. If in the future the domain entities (and therefore corresponding database tables) change their structure, then all of those data sets will need updating.
+
+Even more significantly, there's no way to guarantee that the data that's being loaded is logically consistent with the business behaviour of the domain objects themselves. That is, there's nothing to stop your test from putting data into the database that would be invalid if one attempted to add it through the app.
+
+The solution that Isis provides is a small library called *_fixture scripts_*. A fixture script is basically a wrapper for executing arbitrary work, but that work almost always invoking a business action.
+
+[TIP]
+====
+If you want to learn more on this topic (with live coding!), check out this https://skillsmatter.com/skillscasts/5638-to-those-whom-much-is-given-much-is-expected[presentation] given at BDD Exchange 2014.
+====
+
+There is another benefit to Isis' fixture script approach; the fixtures can be (in prototyping mode) run from your application. This means that fixture scripts can actually help all the way through the development lifecycle:
+
+* when specifying a new feature, you can write a fixture script to get the system into the "given" state, and then start exploring the required functionality with the domain expert actually _within_ the application +
++
+And if you can't write a fixture script for the story, it probably means that there's some prerequisite feature that needs implementing that you hadn't previously recognized
+
+* when the developer implements the story, s/he has a precanned script to run when they manually verify the functionality works
+
+* when the developer automates the story's acceptance test as an integration test, they already have the "given" part of the test implemented
+
+* when you want to pass the feature over to the QA/tester for additional manual exploratory testing, they have a fixture script to get them to a jumping off point for their explorations
+
+* when you want to demonstrate the implemented feature to your domain expert, your demo can use the fixture script so you don't bore your audience in performing lots of boring setup before getting to the actual feature
+
+* when you want to roll out training to your users, you can write fixture scripts as part of their training exercises
+
+
+The following sections explain the API and how to go about using the API.
+
+
+include::_ug_testing_fixture-scripts_api-and-usage.adoc[leveloffset=+1]
+include::_ug_testing_fixture-scripts_sudo-service.adoc[leveloffset=+1]
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_testing_fixture-scripts_api-and-usage.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_testing_fixture-scripts_api-and-usage.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_testing_fixture-scripts_api-and-usage.adoc
new file mode 100644
index 0000000..450fa40
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_testing_fixture-scripts_api-and-usage.adoc
@@ -0,0 +1,286 @@
+[[_ug_testing_fixture-scripts_api-and-usage]]
+= API and Usage
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 parts to using fixture scripts: the `FixtureScripts` domain service class, and the `FixtureScript` view model class, both being `abstract`.
+
+* The job of the `FixtureScripts` domain service is to locate all fixture scripts from the classpath and to let them be invoked, either from an integration test/BDD spec or from the UI of your Isis app.
+
+* With `FixtureScript` meanwhile you subclass for each of the scenarios that you want to define. You can also subclass from `FixtureScript` to create helpers; more on this below.
+
+Let's look at `FixtureScripts` domain service in more detail first.
+
+== `FixtureScripts`
+
+In your code you subclass `FixtureScripts` domain service primarily just to specify which package to search for. For example, here's the service that's generated by the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype]:
+
+[source,java]
+----
+@DomainService
+@DomainServiceLayout(
+ menuBar = DomainServiceLayout.MenuBar.SECONDARY, // <1>
+ named="Prototyping", // <2>
+ menuOrder = "500"
+)
+public class DomainAppFixturesService extends FixtureScripts { // <3>
+
+ public DomainAppFixturesService() {
+ super(
+ "domainapp", // <4>
+ MultipleExecutionStrategy.EXECUTE); // <5>
+ }
+ @Override
+ public FixtureScript default0RunFixtureScript() {
+ return findFixtureScriptFor(RecreateSimpleObjects.class); // <6>
+ }
+ @Override
+ public List<FixtureScript> choices0RunFixtureScript() { // <7>
+ return super.choices0RunFixtureScript();
+ }
+}
+----
+<1> in the UI, render the on the right hand side (secondary) menu bar...
+<2> ... under the "Prototyping" menu
+<3> inherit from `org.apache.isis.applib.fixturescripts.FixtureScripts`
+<4> search for all fixture scripts under the "domainapp" package; in your code this would probably be "com.mycompany.myapp" or similar
+<5> if the same fixture script (class) is encountered more than once, then run anyway; more on this in <<Organizing Fixture scripts>>.
+<6> (optional) specify a default fixture script to run, in this case `RecreateSimpleObjects` fixture script (see below)
+<7> make all fixture scripts found available as a drop-down (by increasing the visibility of this method to `public`)
+
+
+Here's how the domain service looks like in the UI:
+
+image::{_imagesdir}testing/fixture-scripts/prototyping-menu.png[width="700px",link="{_imagesdir}testing/fixture-scripts/prototyping-menu.png"]
+
+
+and here's what the `runFixtureScript` action prompt looks like:
+
+image::{_imagesdir}testing/fixture-scripts/prompt.png[width="700px",link="{_imagesdir}testing/fixture-scripts/prompt.png"]
+
+
+when this is executed, the resultant objects (actually, instances of FixtureResult`) are shown in the UI:
+
+image::{_imagesdir}testing/fixture-scripts/result-list.png[width="700px",link="{_imagesdir}testing/fixture-scripts/result-list.png"]
+
+
+
+If you had defined many fixture scripts then a drop-down might become unwieldy, in which case your code would probably override the `autoComplete...())` instead:
+
+[source,java]
+----
+ @Override
+ public List<FixtureScript> autoComplete0RunFixtureScript(final @MinLength(1) String searchArg) {
+ return super.autoComplete0RunFixtureScript(searchArg);
+ }
+
+----
+
+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:
+
+[source,java]
+----
+ @Action(
+ restrictTo = RestrictTo.PROTOTYPING
+ )
+ @ActionLayout(
+ cssClassFa="fa fa-refresh"
+ )
+ @MemberOrder(sequence="20")
+ public Object recreateObjectsAndReturnFirst() {
+ final List<FixtureResult> run = findFixtureScriptFor(RecreateSimpleObjects.class).run(null);
+ return run.get(0).getObject();
+ }
+----
+
+Let's now look at the `FixtureScript` class, where there's a bit more going on.
+
+== `FixtureScript`
+
+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]:
+
+[source,java]
+----
+public class RecreateSimpleObjects extends FixtureScript { // <1>
+
+ public final List<String> NAMES = Collections.unmodifiableList(Arrays.asList(
+ "Foo", "Bar", "Baz", "Frodo", "Froyo",
+ "Fizz", "Bip", "Bop", "Bang", "Boo")); // <2>
+ public RecreateSimpleObjects() {
+ withDiscoverability(Discoverability.DISCOVERABLE); // <3>
+ }
+ private Integer number; // <4>
+ public Integer getNumber() { return number; }
+ public RecreateSimpleObjects setNumber(final Integer number) {
+ this.number = number;
+ return this;
+ }
+ private final List<SimpleObject> simpleObjects = Lists.newArrayList(); // <5>
+ public List<SimpleObject> getSimpleObjects() {
+ return simpleObjects;
+ }
+ @Override
+ protected void execute(final ExecutionContext ec) { // <6>
+ // defaults
+ final int number = defaultParam("number", ec, 3); // <7>
+ // validate
+ if(number < 0 || number > NAMES.size()) {
+ throw new IllegalArgumentException(
+ String.format("number must be in range [0,%d)", NAMES.size()));
+ }
+ // execute
+ ec.executeChild(this, new SimpleObjectsTearDown()); // <8>
+ for (int i = 0; i < number; i++) {
+ final SimpleObjectCreate fs =
+ new SimpleObjectCreate().setName(NAMES.get(i));
+ ec.executeChild(this, fs.getName(), fs); // <9>
+ simpleObjects.add(fs.getSimpleObject()); // <10>
+ }
+ }
+}
+----
+<1> inherit from `org.apache.isis.applib.fixturescripts.FixtureScript`
+<2> a hard-coded list of values for the names. Note that the http://github.com/isisaddons/isis-module-fakedata[Isis addons' fakedata] module (non-ASF) could also have been used
+<3> whether the script is "discoverable"; in other words whether it should be rendered in the drop-down by the `FixtureScripts` service
+<4> input property: the number of objects to create, up to 10; for the calling test to specify, but note this is optional and has a default (see below). It's important that a wrapper class is used (ie `java.lang.Integer`, not `int`)
+<5> output property: the generated list of objects, for the calling test to grab
+<6> the mandatory execute(...) API
+<7> the `defaultParam(...)` (inherited from `FixtureScript`) will default the `number` property (using Java's Reflection API) if none was specified
+<8> call another fixture script (`SimpleObjectsTearDown`) using the provided `ExecutionContext`. Note that although the fixture script is a view model, it's fine to simply instantiate it (rather than using `DomainObjectContainer#newTransientInstance(...)`).
+<9> calling another fixture script (`SimpleObjectCreate`) using the provided `ExecutionContext`
+<10> adding the created object to the list, for the calling object to use.
+
+
+Because this script has exposed a "number" property, it's possible to set this from within the UI. For example:
+
+image::{_imagesdir}testing/fixture-scripts/prompt.png[width="700px"]
+
+
+When this is executed, the framework will parse the text and attempt to reflectively set the corresponding properties on the fixture result. So, in this case, when the fixture script is executed we actually get 6 objects created:
+
+image::{_imagesdir}testing/fixture-scripts/result-list.png[width="700px"]
+
+
+
+It's commonplace for one fixture script to call another. In the above example this script called `SimpleObjectsTearDown` and `SimpleObjectCreate`. Let's take a quick look at `SimpleObjectCreate`:
+
+[source,java]
+----
+public class SimpleObjectCreate extends FixtureScript { // <1>
+
+ private String name; // <2>
+ public String getName() { return name; }
+ public SimpleObjectCreate setName(final String name) {
+ this.name = name;
+ return this;
+ }
+ private SimpleObject simpleObject; // <3>
+ public SimpleObject getSimpleObject() {
+ return simpleObject;
+ }
+ @Override
+ protected void execute(final ExecutionContext ec) { // <4>
+ String name = checkParam("name", ec, String.class); // <5>
+ this.simpleObject = wrap(simpleObjects) // <6>
+ .create(name); // <7>
+ ec.addResult(this, simpleObject); // <8>
+ }
+ @javax.inject.Inject
+ private SimpleObjects simpleObjects; // <9>
+}
+----
+<1> inherit from `org.apache.isis.applib.fixturescripts.FixtureScript`, as above
+<2> input property: name of the object; this time it is required
+<3> output property: the created simple object
+<4> the mandatory execute(...) API
+<5> the `checkParam(...)` (inherited from `FixtureScript`) will check that the "name" property has been populated (using Java's Reflection API) and throw an exception if not
+<6> wrap the injected `SimpleObjects` domain service (using the xref:rg.adoc#_rg_services-api_manpage-WrapperFactory[`WrapperFactory`]) to simulate interaction through the UI...
+<7> .. and actually create the object using the "create" business action of that service
+<8> add the resulting object to the execution context; this makes the object available to access if run from the UI
+<9> inject the domain service into the fixture script
+
+
+
+
+
+
+
+== Using within Tests
+
+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]:
+
+[source,java]
+----
+public class SimpleObjectIntegTest extends SimpleAppIntegTest {
+ @Inject
+ FixtureScripts fixtureScripts; // <1>
+ SimpleObject simpleObjectWrapped;
+ @Before
+ public void setUp() throws Exception {
+ // given
+ RecreateSimpleObjects fs =
+ new RecreateSimpleObjects().setNumber(1); // <2>
+ fixtureScripts.runFixtureScript(fs, null); // <3>
+
+ SimpleObject simpleObjectPojo =
+ fs.getSimpleObjects().get(0); // <4>
+ assertThat(simpleObjectPojo).isNotNull();
+
+ simpleObjectWrapped = wrap(simpleObjectPojo); // <5>
+ }
+ @Test
+ public void accessible() throws Exception {
+ // when
+ final String name = simpleObjectWrapped.getName();
+ // then
+ assertThat(name).isEqualTo(fs.NAMES.get(0));
+ }
+ ...
+}
+----
+<1> inject the `FixtureScripts` domain service (just like any other domain service)
+<2> instantiate the fixture script for this test, and configure
+<3> execute the fixture script
+<4> obtain the object under test from the fixture
+<5> wrap the object (to simulate being interacted with through the UI)
+
+
+
+== Organizing Fixture scripts
+
+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];
+
+* 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].
+
+These two styles are probably best illustrated with, well, some illustrations. Here's a fixture script in the "flat" style for setting up a customer with some orders, a number of which has been placed:
+
+image::{_imagesdir}testing/fixture-scripts/flat-1.png[width="700px",link="{_imagesdir}testing/fixture-scripts/flat-1.png"]
+
+Notice how we have a single script that's in control of the overall process, and takes responsibility for passing data from one fixture script to the next.
+
+Here's a similar, simpler script, from the same fictional app, to set up two customers:
+
+image::{_imagesdir}testing/fixture-scripts/flat-2.png[width="500px",link="{_imagesdir}testing/fixture-scripts/flat-2.png"]
+
+We can reuse the same fixture "customer" script, either calling it twice or (perhaps better) passing it an array of customer details to set up.
+
+With the composite style, we rely on each fixture script to set up its own prerequisites. Thus:
+
+image::{_imagesdir}testing/fixture-scripts/composite.png[width="550px",link="{_imagesdir}testing/fixture-scripts/composite.png"]
+
+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).
+
+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.
+
+
+
[18/45] isis git commit: ISIS-1133: breaking out reference guide and
devenv guide;
moving appendices' release notes and migration notes to other docs;
improving the documentation page.
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_i18n.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_i18n.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_i18n.adoc
deleted file mode 100644
index aa22f98..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_i18n.adoc
+++ /dev/null
@@ -1,378 +0,0 @@
-[[_ug_more-advanced_i18n]]
-= i18n
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-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 messages resulting from any business rule violations (eg `disableXxx()` or `validateXxx()`, 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
-
-
-
-== Implementation Approach
-
-Most Java frameworks tackle i18n by using Java's own `ResourceBundle` API. However, there are some serious drawbacks in this approach, such as:
-
-* if a string appears more than once (eg "name" or "description") then it must be translated everywhere it appears in every resource bundle file
-* there is no support for plural forms (see this link:http://stackoverflow.com/questions/14326653/java-internationalization-i18n-with-proper-plurals/14327683#14327683[SO answer])
-* there is no tooling support for translators
-
-Apache Isis therefore takes a different approach, drawing inspiration from GNU's https://www.gnu.org/software/gettext/manual/index.html[gettext] API and specifically its `.pot` and `.po` files. These are intended to be used as follows:
-
-* the `.pot` (portable object template) file holds the message text to be translated
-* this file is translated into multiple `.po` (portable object) files, one per supported locale
-* these `.po` files are renamed according to their locale, and placed into the 'appropriate' location to be picked up by the runtime. The name of each `.po` resolved in a very similar way to resource bundles.
-
-The format of the `.pot` and `.po` files is identical; the only difference is that the `.po` file has translations for each of the message strings. These message strings can also have singular and plural forms.
-
-
-[IMPORTANT]
-====
-Although Isis' implementation is modelled after GNU's API, it does _not_ use any GNU software. This is for two reasons: (a) to simplify the toolchain/developer experience, and (b) because GNU software is usually GPL, which would be incompatible with the Apache license).
-====
-
-This design tackles all the issues of ``ResourceBundle``s:
-
-* the `.po` message format is such that any given message text to translate need only be translated once, even if it appears in multiple places in the application (eg "Name")
-* the `.po` message format includes translations for (optional) plural form as well as singular form
-* there are lots of freely available editors https://www.google.co.uk/search?q=.po+file+editor[to be found], many summarized on this https://www.drupal.org/node/11131[Drupal.org] webpage. +
-+
-In fact, there are also online communities/platforms of translators to assist with translating files. One such is https://crowdin.com/[crowdin] (nb: this link does not imply endorsement).
-
-In Isis' implementation, if the translation is missing from the `.po` file then the original message text from the `.pot` file will be returned. In fact, it isn't even necessary for there to be any `.po` files; `.po` translations can be added piecemeal as the need arises.
-
-
-
-
-== `TranslationService`
-
-The cornerstone of Isis' support for i18n is the `TranslationService` service. This is defined in the applib with the following API:
-
-[source,java]
-----
-public interface TranslationService {
- public String translate( // <1>
- final String context,
- final String text);
- public String translate( // <2>
- final String context,
- final String singularText,
- final String pluralText,
- final int num);
- public enum Mode {
- READ,
- WRITE;
- }
- Mode getMode(); // <3>
-}
-----
-<1> is to translate the singular form of the text
-<2> is to translate the plural form of the text
-<3> indicates whether the translation service is in read or write mode.
-
-The `translate(...)` methods are closely modelled on GNU's gettext API. The first version is used when no translation is required, the second is when both a singular and plural form will be required, with the `num` parameter being used to select which is returned. In both cases the `context` parameter provides some contextual information for the translator; this generally corresponds to the class member.
-
-The mode meanwhile determines the behaviour of the service. More on this below.
-
-
-
-=== `TranslationServicePo`
-
-Isis provides a default implementation of `TranslationService`, namely `TranslationServicePo`.
-
-If the service is running in the normal read mode, then it simply provides translations for the locale of the current user. This means locates the appropriate `.po` file (based on the requesting user's locale), finds the translation and returns it.
-
-If however the service is configured to run in write mode, then it instead records the fact that the message was requested to be translated (a little like a spy/mock in unit testing mock), and returns the original message. The service can then be queried to discover which messages need to be translated. All requested translations are written into the `.pot` file.
-
-To make the service as convenient as possible to use, the service configures itself as follows:
-
-* if running in xref:_ug_runtime_deployment-types[prototype mode] 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 xref:_ug_runtime_deployment-types[server (production) mode], 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.
-
-
-
-
-
-== Imperative messages
-
-The `TranslationService` is used internally by Isis when building up the metamodel; the name and description of every class, property, collection, action and action parameter is automatically translated. Thus the simple act of bootstrapping Isis will cause most of the messages requiring translation (that is: those for the Isis metamodel) to be captured by the `TranslationService`.
-
-However, for an application to be fully internationalized, any validation messages (from either `disableXxx()` or `validateXxx()` supporting methods) and also possibly an object's title (from the `title()` method) will also require translation. Moreover, these messages must be captured in the `.pot` file such that they can be translated.
-
-
-=== `TranslatableString`
-
-The first part of the puzzle is tackled by an extension to 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_getting-started_simpleapp-archetype[SimpleApp archetype]:
-
-[source,java]
-----
-public TranslatableString validateUpdateName(final String name) {
- return name.contains("!")? TranslatableString.tr("Exclamation mark is not allowed"): null;
-}
-----
-
-This corresponds to the following entry in the `.pot` file:
-
-[source,ini]
-----
-#: dom.simple.SimpleObject#updateName()
-msgid "Exclamation mark is not allowed"
-msgstr ""
-----
-
-The full API of `TranslatableString` is modelled on the design of GNU gettext (in particular the https://code.google.com/p/gettext-commons/wiki/Tutorial[gettext-commons] library):
-
-[source,java]
-----
-public final class TranslatableString {
- public static TranslatableString tr( // <1>
- final String pattern,
- final Object... paramArgs) { ... }
- public static TranslatableString trn( // <2>
- final String singularPattern,
- final String pluralPattern,
- final int number,
- final Object... paramArgs) { ... }
- public String translate( // <3>
- final TranslationService translationService,
- final String context) { ... }
-}
-----
-<1> returns a translatable string with a single pattern for both singular and plural forms.
-<2> returns a translatable string with different patterns for singular and plural forms; the one to use is determined by the 'number' argument
-<3> translates the string using the provided `TranslationService`, using the appropriate singular/regular or plural form, and interpolating any arguments.
-
-The interpolation uses the format `{xxx}`, where the placeholder can occur multiple times.
-
-For example:
-
-[source,java]
-----
-final TranslatableString ts = TranslatableString.tr(
- "My name is {lastName}, {firstName} {lastName}.",
- "lastName", "Bond", "firstName", "James");
-----
-
-would interpolate (for the English locale) as "My name is Bond, James Bond".
-
-For a German user, on the other hand, if the translation in the corresponding `.po` file was:
-
-[source,ini]
-----
-#: xxx.yyy.Whatever#context()
-msgid "My name is {lastName}, {firstName} {lastName}."
-msgstr "Iche heisse {firstName} {lastName}."
-----
-
-then the translation would be: "Ich heisse James Bond".
-
-
-The same class is used in xref:_ug_reference-services-api_manpage-DomainObjectContainer[`DomainObjectContainer`] so that you can raise translatable info, warning and error messages; each of the relevant methods are overloaded.
-
-For example:
-
-[source,java]
-----
-public interface DomainObjectContainer {
- void informUser(String message);
- void informUser(
- TranslatableMessage message,
- final Class<?> contextClass, final String contextMethod); // <1>
- ...
-}
-----
-<1> are concatenated together to form the context for the `.pot` file.
-
-
-=== `TranslatableException`
-
-Another mechanism by which messages can be rendered to the user are as the result of exception messages thrown and recognized by an xref:_ug_reference-services-spi_manpage-ExceptionRecognizer[`ExceptionRecognizer`].
-
-In this case, if the exception implements `TranslatableException`, then the message will automatically be translated before being rendered. The `TranslatableException` itself takes the form:
-
-[source,java]
-----
-public interface TranslatableException {
- TranslatableString getTranslatableMessage(); // <1>
- String getTranslationContext(); // <2>
-}
-
-----
-<1> the message to translate. If returns `null`, then the `Exception#getMessage()` is used as a fallback
-<2> the context to use when translating the message
-
-
-
-
-
-== Integration Testing
-
-So much for the API; but as noted, it is also necessary to ensure that the required translations are recorded (by the `TranslationService`) into the `.pot` file.
-
-For this, we recommend that you ensure that all such methods are tested through an xref:_ug_testing_integ-test-support[integration test] (not unit test).
-
-For example, here's the corresponding integration test for the "Exclamation mark" example from the simpleapp (above):
-
-[source,java]
-----
-@Rule
-public ExpectedException expectedException = ExpectedException.none();
-
-@Inject
-FixtureScripts fixtureScripts;
-
-@Test
-public void failsValidation() throws Exception {
- // given
- RecreateSimpleObjects fs = new RecreateSimpleObjects().setNumber(1);
- fixtureScripts.runFixtureScript(fs, null);
- SimpleObject simpleObjectWrapped = wrap(fs.getSimpleObjects().get(0));
-
- // expect
- expectedExceptions.expect(InvalidException.class);
- expectedExceptions.expectMessage("Exclamation mark is not allowed");
-
- // when
- simpleObjectWrapped.updateName("new name!");
-}
-----
-
-Running this test will result in the framework calling the `validateUpdateName(...)` method, and thus to record that a translation is required in the `.pot` file.
-
-When the integration tests are complete (that is, when Isis is shutdown), the `TranslationServicePo` will write out all captured translations to its log (more on this below). This will include all the translations captured from the Isis metamodel, along with all translations as exercised by the integration tests.
-
-To ensure your app is fully internationalized app, you must therefore:
-
-* use `TranslatableString` rather than `String` for all validation/disable and title methods.
-* ensure that (at a minimum) all validation messages and title methods are integration tested.
-
-[NOTE]
-====
-We make no apologies for this requirement: one of the reasons that we decided to implement Isis' i18n support in this way is because it encourages/requires the app to be properly tested.
-
-Behind the scenes Isis uses a JUnit rule (`ExceptionRecognizerTranslate`) to intercept any exceptions that are thrown. These are simply passed through to the registered xref:_ug_reference-services-spi_manpage-ExceptionRecognizer[`ExceptionRecognizer`]s so that any messages are recorded as requiring translation.
-====
-
-
-
-
-
-
-== Configuration
-
-There are several different aspects of the translation service that can be configured.
-
-=== Logging
-
-To configure the `TranslationServicePo` to write to out the `translations.pot` file, add the following to the _integtests_ `logging.properties` file:
-
-[source,ini]
-----
-log4j.appender.translations-po=org.apache.log4j.FileAppender
-log4j.appender.translations-po.File=./translations.pot
-log4j.appender.translations-po.Append=false
-log4j.appender.translations-po.layout=org.apache.log4j.PatternLayout
-log4j.appender.translations-po.layout.ConversionPattern=%m%n
-
-log4j.logger.org.apache.isis.core.runtime.services.i18n.po.PoWriter=INFO,translations-po
-log4j.additivity.org.apache.isis.core.runtime.services.i18n.po.PotWriter=false
-----
-
-Just to repeat, this is _not_ the `WEB-INF/logging.properties` file, it should instead be added to the `integtests/logging.properties` file.
-
-=== Location of the `.po` files
-
-The default location of the translated `.po` files is in the `WEB-INF` directory. These are named and searched for similarly to regular Java resource bundles.
-
-For example, assuming these translations:
-
-[source,ini]
-----
-/WEB-INF/translations-en-US.po
- /translations-en.po
- /translations-fr-FR.po
- /translations.po
-----
-
-then:
-
-* a user with `en-US` locale will use `translations-en-US.po`
-* a user with `en-GB` locale will use `translations-en.po`
-* a user with `fr-FR` locale will use `translations-fr-FR.po`
-* a user with `fr-CA` locale will use `translations.po`
-
-The basename for translation files is always `translations`; this cannot be altered.
-
-
-=== Externalized translation files
-
-Normally Isis configuration files are read from the `WEB-INF` file. However, Isis can be configured to read config files from an xref:_ug_deployment_externalized-configuration[external directory]; this is also supported for translations.
-
-Thus, if in `web.xml` the external configuration directory has been set:
-
-[source,xml]
-----
-<context-param>
- <param-name>isis.config.dir</param-name>
- <param-value>location of external config directory</param-value>
-</context-param>
-----
-
-Then this directory will be used as the base for searching for translations (rather than the default 'WEB-INF/' directory).
-
-=== Force read mode
-
-As noted above, if running in prototype mode then `TranslationServicePo` will be in write mode, if in production mode then will be in read mode. To force read mode (ie use translations) even if in prototype mode, add the following configuration property to `isis.properties`:
-
-[source,ini]
-----
-isis.services.translation.po.mode=read
-----
-
-== Supporting services
-
-The `TranslationServicePo` has a number of supporting/related services.
-
-=== `LocaleProvider`
-
-The `LocaleProvider` API is used by the `TranslationServicePo` implementation to obtain the locale of the "current user".
-
-A default implementation is provided by the Wicket viewer.
-
-[NOTE]
-====
-Note that this default implementation does not support requests made through the Restful Objects viewer (there is no Wicket 'application' object available); the upshot is that requests through Restful Objects are never translated. Registering a different implementation of `LocaleProvider` that taps into appropriate REST (RestEasy?) APIs would be the way to address this.
-====
-
-
-=== `TranslationsResolver`
-
-The `TranslationResolver` is used by the `TranslationService` implementation to lookup translations for a specified locale. It is this service that reads from the `WEB-INF/` (or externalized directory).
-
-
-=== `TranslationServicePoMenu`
-
-The `TranslationServicePoMenu` provides a couple of menu actions in the UI (prototype mode only) that interacts with the underlying `TranslationServicePo`:
-
-* the `downloadTranslationsFile()` action - available only in write mode - allows the current `.pot` file to be downloaded. +
-+
-[NOTE]
-====
-While this will contain all the translations from the metamodel, it will not necessarily contain all translations for all imperative methods returning `TranslatableString` instances; which are present and which are missing will depend on which imperative methods have been called (recorded by the service) prior to downloading.
-====
-
-* the `clearTranslationsCache()` action - available only in read mode - will clear the cache so that new translations can be loaded. +
-+
-This allows a translator to edit the appropriate `translations-xx-XX.po` file and check the translation is correct without having to restart the app.
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_mapping-rdbms-views.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_mapping-rdbms-views.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_mapping-rdbms-views.adoc
deleted file mode 100644
index 1cb9286..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_mapping-rdbms-views.adoc
+++ /dev/null
@@ -1,9 +0,0 @@
-[[_ug_more-advanced_mapping-rdbms-views]]
-= Mapping RDBMS Views
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 - as used in link:http://github.com/estatio/estatio[Estatio]
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_multi-tenancy.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_multi-tenancy.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_multi-tenancy.adoc
deleted file mode 100644
index 690f608..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_multi-tenancy.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-[[_ug_more-advanced_multi-tenancy]]
-= Multi-tenancy
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-IMPORTANT: TODO - as supported by (non-ASF) http://github.com/isisaddons/isis-module-security[Isis addons' security] module.
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_overriding-jdo-annotations.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_overriding-jdo-annotations.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_overriding-jdo-annotations.adoc
deleted file mode 100644
index 586110b..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_overriding-jdo-annotations.adoc
+++ /dev/null
@@ -1,55 +0,0 @@
-[[_ug_more-advanced_overriding-jdo-annotations]]
-= Overriding JDO Annotations
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-The JDO Objectstore (or rather, the underlying DataNucleus implementation) builds its own persistence metamodel by reading both annotations on the class and also by searching for metadata in XML files. The metadata in the XML files takes precedence over the annotations, and so can be used to override metadata that is "hard-coded" in annotations.
-
-For example, as of 1.9.0-SNAPSHOT the various http://www.isisaddons.org[Isis addons] modules (not ASF) use schemas for each entity. For example, the `AuditEntry` entity in the http://github.com/isisaddons/isis-module-audit[audit module] is annotated as:
-
-[source,java]
-----
-@javax.jdo.annotations.PersistenceCapable(
- identityType=IdentityType.DATASTORE,
- schema = "IsisAddonsAudit",
- table="AuditEntry")
-public class AuditEntry {
- ...
-}
-----
-
-This will map the `AuditEntry` class to a table `"IsisAddonsAudit"."AuditEntry"`; that is using a custom schema to own the object.
-
-Suppose though that for whatever reason we didn't want to use a custom schema but would rather use the default. We can override the above annotation using a `package.jdo` file, for example:
-
-[source,xml]
-----
-<?xml version="1.0" encoding="UTF-8" ?>
-<jdo xmlns="http://xmlns.jcp.org/xml/ns/jdo/jdo"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/jdo/jdo
- http://xmlns.jcp.org/xml/ns/jdo/jdo_3_0.xsd" version="3.0">
- <package name="org.isisaddons.module.audit.dom">
- <class name="AuditEntry" schema="PUBLIC" table="IsisAddonsAuditEntry">
- </class>
- </package>
-</jdo>
-----
-
-This file should be placed can be placed in `src/main/java/META-INF` within your application's `dom` module.
-
-[NOTE]
-====
-* The same approach should work for any other JDO metadata, but some experimentation might be required.+
-+
-For example, in writing up the above example we found that writing `schema=""` (in an attempt to say, "use the default schema for this table") actually caused the original annotation value to be used instead.
-
-* Forcing the schema to "PUBLIC" (as in the above example) works, but it isn't ideal because the name "PUBLIC" is not vendor-neutral (it works for HSQLDB, but MS SQL Server uses "dbo" as its default).
-
-* As of 1.9.0-SNAPSHOT Apache Isis will automatically (attempt) to create the owning schema for a given table if it does not exist. This behaviour can be customized, as described in the section on xref:_using_modules[using modules].
-====
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_persistence-lifecycle.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_persistence-lifecycle.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_persistence-lifecycle.adoc
deleted file mode 100644
index 5765118..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_persistence-lifecycle.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-[[_ug_more-advanced_persistence-lifecycle]]
-= Persistence Lifecycle
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-IMPORTANT: TODO
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_tips-n-tricks.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_tips-n-tricks.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_tips-n-tricks.adoc
deleted file mode 100644
index f272734..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_tips-n-tricks.adoc
+++ /dev/null
@@ -1,15 +0,0 @@
-[[_ug_more-advanced_tips-n-tricks]]
-= Tips n Tricks
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 a miscellaneous collection of hints-and-tips.
-
-include::_ug_more-advanced_tips-n-tricks_are-you-sure.adoc[leveloffset=+1]
-include::_ug_more-advanced_tips-n-tricks_simulating-collections-of-values.adoc[leveloffset=+1]
-include::_ug_more-advanced_tips-n-tricks_render-all-properties-in-tables.adoc[leveloffset=+1]
-include::_ug_more-advanced_tips-n-tricks_per-user-themes.adoc[leveloffset=+1]
-include::_ug_more-advanced_tips-n-tricks_enhance-only.adoc[leveloffset=+1]
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_tips-n-tricks_are-you-sure.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_tips-n-tricks_are-you-sure.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_tips-n-tricks_are-you-sure.adoc
deleted file mode 100644
index 194c07b..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_tips-n-tricks_are-you-sure.adoc
+++ /dev/null
@@ -1,55 +0,0 @@
-[[_ug_more-advanced_tips-n-tricks_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/
-
-If providing an action that will perform irreversible changes, include a
-mandatory boolean parameter that must be explicitly checked by the end-user
-in order for the action to proceed.
-
-
-
-== Screenshots
-
-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:_ug_wicket-viewer[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[]
-
-
-
-
-== Code example
-
-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:_ug_reference-methods_prefixes_manpage-validate[`validate...()`] method.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_tips-n-tricks_enhance-only.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_tips-n-tricks_enhance-only.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_tips-n-tricks_enhance-only.adoc
deleted file mode 100644
index 1854a30..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_tips-n-tricks_enhance-only.adoc
+++ /dev/null
@@ -1,17 +0,0 @@
-[[_ug_more-advanced_tips-n-tricks_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 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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_tips-n-tricks_per-user-themes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_tips-n-tricks_per-user-themes.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_tips-n-tricks_per-user-themes.adoc
deleted file mode 100644
index 19c950f..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_tips-n-tricks_per-user-themes.adoc
+++ /dev/null
@@ -1,85 +0,0 @@
-[[_ug_more-advanced_tips-n-tricks_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 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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_tips-n-tricks_render-all-properties-in-tables.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_tips-n-tricks_render-all-properties-in-tables.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_tips-n-tricks_render-all-properties-in-tables.adoc
deleted file mode 100644
index cf2432c..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_tips-n-tricks_render-all-properties-in-tables.adoc
+++ /dev/null
@@ -1,49 +0,0 @@
-[[_ug_more-advanced_tips-n-tricks_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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_tips-n-tricks_simulating-collections-of-values.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_tips-n-tricks_simulating-collections-of-values.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_tips-n-tricks_simulating-collections-of-values.adoc
deleted file mode 100644
index 4297a96..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_tips-n-tricks_simulating-collections-of-values.adoc
+++ /dev/null
@@ -1,23 +0,0 @@
-[[_ug_more-advanced_tips-n-tricks_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
-
-IMPORTANT: TODO
-
-
-
-== Persistence Concerns
-
-IMPORTANT: WIP - easiest to simply store using DataNucleus' support for collections, marked as xref:_ug_reference-annotations_manpage-Programmatic[`@Programmatic`] so that it is ignored by 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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_transactions-and-errors.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_transactions-and-errors.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_transactions-and-errors.adoc
deleted file mode 100644
index 84a5e08..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_transactions-and-errors.adoc
+++ /dev/null
@@ -1,33 +0,0 @@
-[[_ug_more-advanced_transactions-and-errors]]
-= Transactions and Errors
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 Isis, every action invocation (in fact, every interaction) is automatically wrapped in a transaction, and any repository query automatically does a flush.
-
-What that means is that there's no need to explicitly start or commit transactions in Isis; this will be done for you. Indeed, if you do try to manage transactions (eg by reaching into the JDO `PersistenceManager` exposed by the xref:_ug_reference-services-api_manpage-IsisJdoSupport[IsisJdoSupport] domain service, then you are likely to confuse Isis and get a stack trace for your trouble.
-
-
-
-
-== Aborting Transactions
-
-If you want to abort Isis' transaction, this can be done by throwing `RecoverableException` (or any subclass, eg `ApplicationException`). The transaction will be aborted, and the exception message will be displayed to the user.
-
-If you throw any other exception (ie not a subclass of `RecoverableException`), then the users will see an error page (if Wicket viewer) or a 500 (if Restful Objects viewer).
-
-
-
-
-
-== Raise message/errors to users
-
-IMPORTANT: TODO - xref:_ug_reference-services-api_manpage-DomainObjectContainer_messages-api[`DomainObjectContainer`]
-
-
-
-== Exception Recognizers
-
-IMPORTANT: TODO - xref:_ug_reference-services-spi_manpage-ExceptionRecognizer[`ExceptionRecognizer`] service
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_view-models.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_view-models.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_view-models.adoc
deleted file mode 100644
index e70dc0e..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_view-models.adoc
+++ /dev/null
@@ -1,22 +0,0 @@
-[[_ug_more-advanced_view-models]]
-= View Models
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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: WIP - xref:_ug_reference-annotations_manpage-ViewModel[`@ViewModel`], xref:_ug_reference-classes_super_manpage-AbstractViewModel[`AbstractViewModel`], xref:_ug_reference-annotations_manpage-DomainObject_nature[`@DomainObject#nature()`]
-
-
-Nature of view models
-
-* inmemory-entity
-* external_entity
-* application layer
-
-Consumers of view models
-
-* within the Wicket viewer
-* within the REST viewer, as an external client consuming a stable API
-
-An alternative to using view models is to map the domain object using the xref:_ug_reference-services-spi_manpage-ContentMappingService[`ContentMappingService`].
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations.adoc
deleted file mode 100644
index 3c6520f..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations.adoc
+++ /dev/null
@@ -1,63 +0,0 @@
-[[_ug_reference-annotations]]
-= Reference: Annotations
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-Apache Isis uses annotations to provide additional metadata about the domain objects.
-
-To give just a few examples:
-
-* 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)`
-* if a class is a domain service and should be automatically instantiated as a singleton, then it can be annotated using `@DomainService`
-* if an action is idempotent, then it can be annotated using `@Action(semantics=SemanticsOf.IDEMPOTENT)`.
-* if an action parameter is optional, it can be annotated using `@Parameter(optionality=Optionality.OPTIONAL)`
-
-Some annotations act as UI hints, for example:
-
-* if a collection should be rendered "open" rather than collapsed, it can be annotated using `@CollectionLayout(render=RenderType.EAGERLY)`
-* 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 chapter documents all the annotations currently supported by Isis. It also identifies a number of annotations that are now deprecated, and indicates their replacement.
-
-
-include::_ug_reference-annotations_aaa.adoc[leveloffset=+1]
-
-include::_ug_reference-annotations_manpage-Action.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-ActionLayout.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-Collection.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-Collectionlayout.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-Column.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-Digits.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-Discriminator.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-DomainObject.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-DomainObjectLayout.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-DomainService.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-DomainServiceLayout.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-Facets.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-HomePage.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-Inject.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-MemberGroupLayout.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-MemberOrder.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-NotPersistent.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-MinLength.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-Parameter.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-ParameterLayout.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-PersistenceCapable.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-PostConstruct.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-PreDestroy.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-PrimaryKey.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-Programmatic.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-Property.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-PropertyLayout.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-RequestScoped.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-Title.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-Viewmodel.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-ViewmodelLayout.adoc[leveloffset=+1]
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa.adoc
deleted file mode 100644
index 2854c92..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa.adoc
+++ /dev/null
@@ -1,17 +0,0 @@
-[[_ug_reference-annotations_aaa]]
-= Summary
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 summarizes the various annotations supported by Isis. They break out into five categories.
-
-include::_ug_reference-annotations_aaa_main.adoc[leveloffset=+1]
-include::_ug_reference-annotations_aaa_other.adoc[leveloffset=+1]
-include::_ug_reference-annotations_aaa_jdo.adoc[leveloffset=+1]
-include::_ug_reference-annotations_aaa_jee.adoc[leveloffset=+1]
-include::_ug_reference-annotations_aaa_deprecated.adoc[leveloffset=+1]
-include::_ug_reference-annotations_aaa_partial.adoc[leveloffset=+1]
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa_deprecated.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa_deprecated.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa_deprecated.adoc
deleted file mode 100644
index a54caa7..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa_deprecated.adoc
+++ /dev/null
@@ -1,342 +0,0 @@
-[[_ug_reference-annotations_aaa_deprecated]]
-= Deprecated Annotations
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-As Apache Isis has evolved and grown, we found ourselves adding more and more annotations; but most of these related to either an object type (entity, view model, service) or an object member (property, collection, action). Over time it became harder and harder for end programmers to discover these new features.
-
-Accordingly, (in v1.8.0) we decided to unify the semantics into the main (core) annotations listed xref:_ug_reference-annotations_aaa_main[above].
-
-The annotations listed in the table below are still supported by Apache Isis, but will be retired in Isis v2.0.
-
-
-.Deprecated Annotations
-[cols="2,4a,3a,1,1", options="header"]
-|===
-|Annotation
-|Purpose
-|Use instead
-|Layer
-|xref:_ug_reference-object-layout_dynamic[Dynamic layout]?
-
-|`@ActionOrder`
-|Order of buttons and menu items representing actions.
-|xref:_ug_reference-annotations_manpage-MemberOrder[`@MemberOrder`]
-|UI
-|Yes
-
-|`@ActionInteraction`
-|Enable subscribers on the Event Bus Service to either veto, validate or take further steps before/after an action has been invoked.
-|xref:_ug_reference-annotations_manpage-Action_domainEvent[`@Action#domainEvent()`]
-|Domain
-|
-
-|`@ActionSemantics`
-|Query-only, idempotent or non-idempotent.
-|xref:_ug_reference-annotations_manpage-Action_semantics[`@Action#semantics()`]
-|Domain
-|
-
-|`@Audited`
-|Audit changes to an object.
-|xref:_ug_reference-annotations_manpage-DomainObject_auditing[`@DomainObject#` +
-`auditing()`]
-|Domain
-|
-
-|`@AutoComplete`
-|Repository method to search for entities
-|xref:_ug_reference-annotations_manpage-DomainObject_autoCompleteRepository[`@DomainObject` +
-`#autoCompleteRepository()`]
-|UI/Domain
-|
-
-|`@Bookmarkable`
-|Whether (and how) to create a bookmark for visited object.
-|xref:_ug_reference-annotations_manpage-DomainObjectLayout_bookmarking[`@DomainObjectLayout` +
-`#bookmarking()`]
-|UI
-|
-
-|`@Bounded`
-|Bounded (and limited) number of instances of an entity type, translates into a drop-down for any property of that type.
-|xref:_ug_reference-annotations_manpage-DomainObject_bounded[`@DomainObject#bounded()`]
-|Domain
-|
-
-|`@Bulk`
-|Indicates an action is a bulk action, can be applied to multiple instances.
-|xref:_ug_reference-annotations_manpage-Action_invokeOn[`@Action#invokeOn()`]
-|UI, Domain
-|
-
-|`@CollectionInteraction`
-|Enable subscribers on the Event Bus Service to either veto, validate or take further steps before/after a collection has been added to or removed from.
-|xref:_ug_reference-annotations_manpage-Collection_domainEvent[`@Collection#domainEvent()`]
-|Domain
-|
-
-|`@Command`
-|Action invocation should be reified as a command object, optionally persistable for profiling and enhanced auditing, and background/async support.
-|xref:_ug_reference-annotations_manpage-Action_command[`@Action#command()`]
-|Domain
-|
-
-|`@CssClass`
-|Allow visual representation of individual objects or object members layout to be customized by application-specific CSS.
-|`#cssClass()` attribute for: xref:_ug_reference-annotations_manpage-DomainObjectLayout_cssClass[`@DomainObjectLayout`], xref:_ug_reference-annotations_manpage-PropertyLayout_cssClass[`@PropertyLayout`], xref:_ug_reference-annotations_manpage-CollectionLayout_cssClass[`@CollectionLayout`], xref:_ug_reference-annotations_manpage-ActionLayout_cssClass[`@ActionLayout`] and xref:_ug_reference-annotations_manpage-ParameterLayout_cssClass[`@ParameterLayout`]
-|UI
-|Yes
-
-|`@CssClassFa`
-|So that font awesome icons can be applied to action buttons/menu items and optionally as an object icon.
-|`cssClassFa()` attribute for: xref:_ug_reference-annotations_manpage-ActionLayout_cssClassFa[`@ActionLayout`], xref:_ug_reference-annotations_manpage-DomainObjectLayout_cssClassFa[`DomainObjectLayout`] and xref:_ug_reference-annotations_manpage-ViewModelLayout_cssClassFa[`ViewModelLayout`]
-|UI
-|Yes
-
-|`@Debug`
-|Action only invokable in debug mode.
-|Not supported by either the xref:_ug_wicket-viewer[Wicket viewer] or the xref:_ug_restfulobjects-viewer[RestfulObjects viewer]; use prototype mode instead (xref:_ug_reference-annotations_manpage-Action_restrictTo[`@Action#restrictTo()`])
-|UI
-|
-
-|`@DescribedAs`
-|Provide a longer description/tool-tip of an object or object member.
-|`#describedAs()` attribute for xref:_ug_reference-annotations_manpage-DomainObject_describedAs[`@DomainObjectLayout`], xref:_ug_reference-annotations_manpage-PropertyLayout_describedAs[`@PropertyLayout`], xref:_ug_reference-annotations_manpage-CollectionLayout_describedAs[`@CollectionLayout`], xref:_ug_reference-annotations_manpage-ActionLayout_describedAs[`@ActionLayout`] and xref:_ug_reference-annotations_manpage-ParameterLayout_describedAs[`@ParameterLayout`]
-|UI
-|Yes
-
-|`@Disabled`
-|Object property cannot be edited, an object collection cannot be added to/removed from, or an object action cannot be invoked.
-|`#editing()` attribute for xref:_ug_reference-annotations_manpage-Property_editing[`@Property`], xref:_ug_reference-annotations_manpage-Collection_editing[`@Collection`] and xref:_ug_reference-annotations_manpage-DomainObject_editing[`@DomainObject`]
-|UI, Domain
-|Yes
-
-|`@Exploration`
-|Action available in special 'exploration' mode.
-|Not supported by either the xref:_ug_wicket-viewer[Wicket viewer] or the xref:_ug_restfulobjects-viewer[RestfulObjects viewer]; use prototype mode instead (xref:_ug_reference-annotations_manpage-Action_restrictTo[`@Action#restrictTo()`])
-|UI
-|
-
-|`@FieldOrder`
-|Order of properties and collections.
-|xref:_ug_reference-annotations_manpage-MemberOrder[`@MemberOrder`]
-|UI
-|Yes
-
-|`@Hidden`
-|Object member is not visible, or on domain service (to indicate that none of its actions are visible).
-|For domain object members, use `#hidden()` attribute of xref:_ug_reference-annotations_manpage-Action_hidden[`Action`], xref:_ug_reference-annotations_manpage-Property_hidden[`Property`] or xref:_ug_reference-annotations_manpage-Collection_hidden[`Collection`]. +
-For domain service, use xref:_ug_reference-annotations_manpage-DomainService_nature[`@DomainService(` +
-`nature=DOMAIN)`]
-|UI, Domain
-|Yes
-
-|`@Idempotent`
-|Whether an action is idempotent (can be invoked multiple times with same post-condition).
-|xref:_ug_reference-annotations_manpage-Action_semantics[`@Action#semantics`]
-|Domain
-|
-
-|`@Ignore`
-|Exclude this method from the metamodel.
-|xref:_ug_reference-annotations_manpage-Programmatic[`@Programmatic`]. +
-
-`@Ignore` was deprecated because it can easily clash with `@org.junit.Ignore`.
-|Domain
-|
-
-|`@Immutable`
-|An object's state cannot be changed (properties cannot be edited, collections cannot be added to or removed from). Actions can still be invoked.
-|xref:_ug_reference-annotations_manpage-DomainObject_editing[`@DomainObject#editing()`]
-|Domain
-|
-
-|`@Mask`
-|How to parse/render values (never properly supported)
-|(None)
-|UI/domain
-|
-
-|`@MaxLength`
-|Maximum length of a property value (strings).
-|`#maxLength()` attribute for xref:_ug_reference-annotations_manpage-Property_maxLength[`@Property`] or xref:_ug_reference-annotations_manpage-Parameter_maxLength[`@Parameter`]
-|Domain
-|
-
-|`@MemberGroups`
-|Layout of properties and collections of a domain object or view model object.
-|xref:_ug_reference-annotations_manpage-MemberGroupLayout[`@MemberGroupLayout`]
-|UI
-|Yes
-
-|`@MultiLine`
-|Render string property over multiple lines (a textarea rather than a textbox).
-|`#multiLine()` attribute for xref:_ug_reference-annotations_manpage-Property_multiLine[`@Property`] or xref:_ug_reference-annotations_manpage-Parameter_multiLine[`@Parameter`]
-|UI
-|Yes
-
-|`@MustSatisfy`
-|Specify arbitrary specification constraints on a property or action parameter.
-|`#mustSatisfy()` attribute for xref:_ug_reference-annotations_manpage-Property_mustSatisfy[`@Property`] or xref:_ug_reference-annotations_manpage-Parameter_mustSatisfy[`@Parameter`]
-|Domain
-|
-
-|`@Named`
-|Override name inferred from class. Required for parameter names (prior to Java8).
-|`#named()` attribute for xref:_ug_reference-annotations_manpage-DomainServiceLayout_named[`@DomainServiceLayout`], xref:_ug_reference-annotations_manpage-DomainObjectLayout_named[`@DomainObjectLayout`], xref:_ug_reference-annotations_manpage-PropertyLayout_named[`@PropertyLayout`], xref:_ug_reference-annotations_manpage-CollectionLayout_named[`@CollectionLayout`], xref:_ug_reference-annotations_manpage-ActionLayout_named[`@ActionLayout`] and xref:_ug_reference-annotations_manpage-ParameterLayout_named[`@ParameterLayout`]
-|UI
-|Yes
-
-|`@NotContributed`
-|Indicates that a domain service action is not rendered as an action on the (entity) types of its parameters. For 1-arg query-only actions, controls whether the domain service action is rendered as a property or collection on the entity type of its parameter.
-|Use xref:_ug_reference-annotations_manpage-DomainService_nature[`@DomainService#nature()`] to specify whether any of the actions in a domain service should appear in the menu bars (applies at type level, not action level).
-For individual actions, use xref:_ug_reference-annotations_manpage-ActionLayout_contributedAs[`@ActionLayout#` +
-`contributedAs()`] to specify whether any individual action should be contributed only as an action or as an association (property or collection).
-|UI
-|
-
-|`@NotInServiceMenu`
-|Indicates that a domain service should not be rendered in the application menu (at top of page in Wicket viewer).
-|xref:_ug_reference-annotations_manpage-DomainService_nature[`@DomainService#nature()`] to signify that none of the actions in a domain service should appear in the menu bars
-|UI
-|
-
-|`@NotPersisted`
-|Indicates that an object property is not persisted (meaning it is excluded from view model mementos, and should not be audited).
-|`#notPersisted()` attribute of xref:_ug_reference-annotations_manpage-Property_notPersisted[`@Property`] and xref:_ug_reference-annotations_manpage-Collection_notPersisted[`@Collection`]
-|Domain, Persistence
-|
-
-|`@ObjectType`
-|For constructing the external identifier (URI) of an entity instance (part of its URL in both Wicket viewer and Restful Objects viewer). Also part of the toString representation of bookmarks, if using the Bookmark Service
-|xref:_ug_reference-annotations_manpage-DomainObject_objectType[`@DomainObject#objectType()`]
-|Domain
-|
-
-|`@Optional`
-|Specifies that a property or action parameter is not mandatory.
-|`#optionality()` attribute for xref:_ug_reference-annotations_manpage-Property_optionality[`@Property`] or xref:_ug_reference-annotations_manpage-Parameter_optionality[`@Parameter`]
-|Domain
-|
-
-|`@Paged`
-|Number of instances to display in tables representing (standalone or parented) collections.
-|`#paged()` attribute for xref:_ug_reference-annotations_manpage-DomainObjectLayout_paged[`@DomainObjectLayout`] or xref:_ug_reference-annotations_manpage-CollectionLayout_paged[`@CollectionLayout`]
-|UI
-|Yes
-
-|`@Plural`
-|For the irregular plural form of an entity type.
-|xref:_ug_reference-annotations_manpage-DomainObject_plural[`@DomainObjectLayout` +
-`#plural()`]
-|UI
-|
-
-|`@PostsAction` +
-`InvokedEvent`
-|Post a domain event to the Event Bus Service indicating that an action has been invoked.
-|xref:_ug_reference-annotations_manpage-Action_domainEvent[`@Action#domainEvent()`]
-|Domain
-|
-
-|`@PostsCollection` +
-`AddedToEvent`
-|Post a domain event to the Event Bus Service indicating that an element has been added to a collection.
-|xref:_ug_reference-annotations_manpage-Collection_domainEvent[`@Collection#domainEvent()`]
-|Domain
-|
-
-|`@PostsCollection` +
-`RemovedFromEvent`
-|Post a domain event to the Event Bus Service indicating that an element has been removed from a collection.
-|xref:_ug_reference-annotations_manpage-Collection_domainEvent[`@Collection#domainEvent()`]
-|Domain
-|
-
-|`@PostsProperty` +
-`ChangedEvent`
-|Post a domain event to the Event Bus Service indicating that the value of a property has changed.
-|xref:_ug_reference-annotations_manpage-Property_domainEvent[`@Property#domainEvent()`]
-|Domain
-|
-
-|`@PropertyInteraction`
-|Enable subscribers on the Event Bus Service to either veto, validate or take further steps before/after a property has been modified or cleared.
-|xref:_ug_reference-annotations_manpage-Property_domainEvent[`@Property#domainEvent()`]
-|Domain
-|
-
-|`@Prototype`
-|Indicates that an action should only be visible in 'prototype' mode.
-|xref:_ug_reference-annotations_manpage-Action_restrictTo[`@Action#restrictTo()`]
-|UI
-|Yes
-
-|`@PublishedAction`
-|Action invocation should be serialized and published by configured PublishingService (if any), eg to other systems.
-|xref:_ug_reference-annotations_manpage-Action_publishing[`@Action#publishing()`]
-|Domain
-|
-
-|`@PublishedObject`
-|Change to object should be serialized and published by configured PublishingService (if any), eg to other systems.
-|xref:_ug_reference-annotations_manpage-DomainObject_publishing[`@DomainObject#publishing()`]
-|Domain
-|
-
-|`@QueryOnly`
-|Whether an action is query-only (has no side-effects).
-|xref:_ug_reference-annotations_manpage-Action_semantics[`@Action#semantics()`]
-|Domain
-|
-
-|`@RegEx`
-|Validate change to value of string property.
-|`#regexPattern()` for xref:_ug_reference-annotations_manpage-Property_regexPattern[`@Property`] or xref:_ug_reference-annotations_manpage-Property_regexPattern[`@Parameter`].
-|Domain
-|
-
-|`@Render`
-|Eagerly (or lazily) render the contents of a collection.
-|xref:_ug_reference-annotations_manpage-CollectionLayout_render[`@CollectionLayout` +
-`#render()`]
-|UI
-|Yes
-
-|`@RenderedAsDayBefore`
-|Render dates as the day before; ie store [a,b) internally but render [a,b-1]) to end-user.
-|`#renderedAsDayBefore()` attribute for xref:_ug_reference-annotations_manpage-PropertyLayout_renderedAsDayBefore[`@PropertyLayout`] and xref:_ug_reference-annotations_manpage-ParameterLayout_renderedAsDayBefore[`@ParameterLayout`].
-|UI
-|
-
-|`@Resolve`
-|Eagerly (or lazily) render the contents of a collection (same as `@Render)`
-|xref:_ug_reference-annotations_manpage-CollectionLayout_render[`@CollectionLayout` +
-`#render()`]
-|UI
-|Yes
-
-|`@SortedBy`
-|Display instances in collections in the order determined by the provided Comparator.
-|xref:_ug_reference-annotations_manpage-CollectionLayout_sortedBy[`@CollectionLayout` +
-`#sortedBy()`]
-|UI
-|Yes
-
-|`@TypeOf`
-|The type of entity stored within a collection, or as the result of invoking an action, if cannot be otherwise inferred, eg from generics.
-|`#typeOf()` attribute for xref:_ug_reference-annotations_manpage-Collection_typeOf[`@Collection`] and xref:_ug_reference-annotations_manpage-Action_typeOf[`@Action`]
-|Domain
-|
-
-|`@TypicalLength`
-|The typical length of a string property, eg to determine a sensible length for a textbox.
-|`#typicalLength()` attribute for xref:_ug_reference-annotations_manpage-PropertyLayout_typicalLength[`@PropertyLayout`] and xref:_ug_reference-annotations_manpage-ParameterLayout_typicalLength[`@ParameterLayout`]
-|UI
-|Yes
-
-|===
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa_jdo.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa_jdo.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa_jdo.adoc
deleted file mode 100644
index d6ce89c..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa_jdo.adoc
+++ /dev/null
@@ -1,113 +0,0 @@
-[[_ug_reference-annotations_aaa_jee]]
-= JDO Annotations
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-Apache Isis uses JDO/DataNucleus as its ORM, and infers some of its own metadata from the JDO annotations.
-
-[WARNING]
-====
-Isis (currently) builds up metadata by parsing the JDO annotations from source, _not_ by querying the JDO metamodel. The upshot is that, for the annotations documented here at least, your domain entities must use JDO annotations rather than XML.
-
-Furthermore, note that although JDO (the property-related) annotations to be placed on either the field or on the getter, Isis requires that annotations are placed on the getter.
-====
-
-The table below lists the JDO annotations currently recognized by Isis.
-
-
-.JDO Annotations
-[cols="2,4a,1,1", options="header"]
-|===
-|Annotation
-|Purpose
-|Layer
-|Applies to
-
-
-|xref:_ug_reference-annotations_manpage-Column[`@javax.jdo.annotations.` +
-`Column`]
-|Used to determine whether a property is mandatory or optional. For `String` and `BigDecimal` properties, used to determine length/precision/scale.
-
-|Domain / persistence
-|Property
-
-
-|xref:_ug_reference-annotations_manpage-Discriminator[`@javax.jdo.annotations.` +
-`Discriminator`]
-|Override for the object type, as used in `Bookmark`s, URLs for xref:_ug_restfulobjects-viewer[RestfulObjects viewer] and elsewhere. +
-
-Note that the discriminator overrides the object type that may otherwise be inferred from the xref:_ug_reference-annotations_manpage-PersistenceCapable[`@PersistenceCapable`] annotation.
-|Domain / persistence
-|Class
-
-
-|xref:_ug_reference-annotations_manpage-NotPersistent[`@javax.jdo.annotations.` +
-`NotPersistent`]
-|Used to determine whether to enforce or skip some xref:_ug_extending_programming-model_custom-validator[metamodel validation] for `@Column` versus equivalent Isis annotations.
-
-|Domain / persistence
-|Property
-
-
-
-|xref:_ug_reference-annotations_manpage-PersistenceCapable[`@javax.jdo.annotations.` +
-`PersistenceCapable`]
-|Used to build Isis' own internal identifier for objects. +
-
-If the `schema()` attribute is specified (and if xref:_ug_reference-annotations_manpage-Discriminator[`@Discriminator`] _hasn't_ been specified), is also used to derive the object type, as used in `Bookmark`s, URLs for xref:_ug_restfulobjects-viewer[RestfulObjects viewer] and elsewhere.
-
-|Domain / persistence
-|Class
-
-
-|xref:_ug_reference-annotations_manpage-PrimaryKey[`@javax.jdo.annotations.` +
-`PrimaryKey`]
-|Used to ensure Isis does not overwrite application-defined primary keys, and to ensure is read-only in the UI.
-
-|Domain / persistence
-|Property
-
-
-
-|===
-
-
-
-Isis also parses the following JDO annotations, but the metadata is currently unused.
-
-.JDO Annotations (unused within Isis)
-[cols="2,4a,1,1", options="header"]
-|===
-|Annotation
-|Purpose
-|Layer
-|Applies to
-
-
-|`@javax.jdo.annotations.` +
-`DataStoreIdentity`
-|Unused
-|Persistence
-|Class
-
-
-|`@javax.jdo.annotations.` +
-`EmbeddedOnly`
-|Unused
-|Persistence
-|Class
-
-
-|`@javax.jdo.annotations.` +
-`Query`
-|Unused
-|Persistence
-|Class
-
-
-|===
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa_jee.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa_jee.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa_jee.adoc
deleted file mode 100644
index 152ba24..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa_jee.adoc
+++ /dev/null
@@ -1,59 +0,0 @@
-[[_ug_reference-annotations_aaa_jee]]
-= Java EE Annotations
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-While Apache Isis does, as of today, define a good number of its own annotations, the policy is to reuse standard Java/JEE annotations wherever they exist or are added to the Java platform.
-
-The table below lists the JEE annotations currently recognized. Expect to see more added in future releases of Isis.
-
-
-.Java EE Annotations
-[cols="2,4a,1,1", options="header"]
-|===
-|Annotation
-|Purpose
-|Layer
-|xref:_ug_reference-object-layout_dynamic[Dynamic layout]?
-
-|xref:_ug_reference-annotations_manpage-Digits[`@javax.validation.` +
-`constraints.` +
-`Digits`]
-|Precision/scale for BigDecimal values.
-|Domain
-|
-
-|xref:_ug_reference-annotations_manpage-Inject[`@javax.inject.` +
-`Inject`]
-|Inject domain service into a domain object (entity or view model) or another domain service.
-|Domain
-|
-
-|xref:_ug_reference-annotations_manpage-PostConstruct[`@javax.annotations.` +
-`PostConstruct`]
-|Callback for domain services (either singleton or xref:_ug_reference-annotations_manpage-RequestScoped[request-scoped]) to initialize themselves once instantiated.
-
-|Domain
-|
-
-|xref:_ug_reference-annotations_manpage-PreDestroy[`@javax.annotations.` +
-`PreDestroy`]
-|Callback for domain services (either singleton or xref:_ug_reference-annotations_manpage-RequestScoped[request-scoped]) to clean up resources prior to destruction.
-
-|Domain
-|
-
-|xref:_ug_reference-annotations_manpage-RequestScoped[`@javax.enterprise.` +
-`context.` +
-`RequestScoped`]
-|Specify that a domain service has request-scope (rather than a singleton).
-|Domain
-|
-
-
-|===
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa_main.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa_main.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa_main.adoc
deleted file mode 100644
index 2bbe4ab..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa_main.adoc
+++ /dev/null
@@ -1,103 +0,0 @@
-[[_ug_reference-annotations_aaa_main]]
-= Core annotations
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-In Apache Isis every domain object is either a domain entity, a view model or a domain service. And each of these are made up of properties, collections and actions (domain services only have actions).
-
-For each of these domain types and members there are two annotations. One covers the semantics intrinsic to the domain (eg whether an action parameter is optional or not), then other (suffix `...Layout`) captures semantics relating to the UI/presentation layer.
-
-[TIP]
-====
-Most UI semantics can also be specified using xref:_ug_reference-object-layout_dynamic[dynamic object layout].
-====
-
-
-The table below summarizes these most commonly used annotations in Isis.
-
-
-.Core annotations for domain objects, services and members (as of 1.8.0)
-[cols="2,4a,1,1", options="header"]
-|===
-|Annotation
-|Purpose
-|Layer
-|xref:_ug_reference-object-layout_dynamic[Dynamic layout]?
-
-|xref:_ug_reference-annotations_manpage-Action[`@Action`]
-|Domain semantics for actions
-|Domain
-|
-
-|xref:_ug_reference-annotations_manpage-ActionLayout[`@ActionLayout`]
-|User interface hints for actions
-|UI
-|Yes
-
-|xref:_ug_reference-annotations_manpage-Collection[`@Collection`]
-|Domain semantics for collections
-|Domain
-|
-
-|xref:_ug_reference-annotations_manpage-CollectionLayout[`@CollectionLayout`]
-|User interface hints for collections
-|UI
-|Yes
-
-|xref:_ug_reference-annotations_manpage-DomainObject[`@DomainObject`]
-|Domain semantics for domain object (entities and optionally view models, see also `@ViewModel)`
-|Domain
-|
-
-|xref:_ug_reference-annotations_manpage-DomainObjectLayout[`@DomainObjectLayout`]
-|User interface hints for domain object (entities and optionally view models, see also `@ViewModelLayout)`
-|UI
-|Yes
-
-|xref:_ug_reference-annotations_manpage-DomainService[`@DomainService`]
-|Class is a domain service (rather than an entity or view model)
-|Domain
-|
-
-|xref:_ug_reference-annotations_manpage-DomainServiceLayout[`@DomainServiceLayout`]
-|User interface hints for domain services
-|UI
-|
-
-|xref:_ug_reference-annotations_manpage-Parameter[`@Parameter`]
-|Domain semantics for action parameters
-|Domain
-|
-
-|xref:_ug_reference-annotations_manpage-ParameterLayout[`@ParameterLayout`]
-|Layout hints for an action parameter (currently: its label position either to top or the left).
-|UI
-|Yes
-
-|xref:_ug_reference-annotations_manpage-Property[`@Property`]
-|Domain semantics for properties
-|Domain
-|
-
-|xref:_ug_reference-annotations_manpage-PropertyLayout[`@PropertyLayout`]
-|Layout hints for a property
-|UI
-|Yes
-
-|xref:_ug_reference-annotations_manpage-ViewModel[`@ViewModel`]
-|Specify that a class is a view model (as opposed to an entity or domain service); equivalent to `@DomainObject(nature`=VIEW_MODEL).
-|Domain, Persistence
-|
-
-|xref:_ug_reference-annotations_manpage-ViewModelLayout[`@ViewModelLayout`]
-|User interface hints for view models.
-For use with `@ViewModel`. If specifying view models using `@DomainObject(nature=VIEW_MODEL)` then use `@DomainObjectLayout`)
-|UI
-|Yes
-
-|===
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa_other.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa_other.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa_other.adoc
deleted file mode 100644
index 6188247..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa_other.adoc
+++ /dev/null
@@ -1,57 +0,0 @@
-[[_ug_reference-annotations_aaa_other]]
-= Other Isis Annotations
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-These annotations are also commonly used, but relate _not_ to objects or object members but instead to other aspects of the Isis metamodel.
-
-.Other Isis Annotations
-[cols="2,4a,1,1", options="header"]
-|===
-|Annotation
-|Purpose
-|Layer
-|xref:_ug_reference-object-layout_dynamic[Dynamic layout]?
-
-|xref:_ug_reference-annotations_manpage-Facets[`@Facets`]
-|Install arbitrary facets within the Isis metamodel.
-|(any)
-|
-
-|xref:_ug_reference-annotations_manpage-HomePage[`@HomePage`]
-|Query-only action (on domain service) to be invoked, result of which is rendered as the user's home page.
-|UI
-|
-
-|xref:_ug_reference-annotations_manpage-MemberGroupLayout[`@MemberGroupLayout`]
-|Grouping of properties into groups, and organizing of properties, collections into columns.
-|UI
-|Yes
-
-
-|xref:_ug_reference-annotations_manpage-MemberOrder[`@MemberOrder`]
-|Ordering of properties, collections and actions, and also associating actions with either a property or a collection.
-|UI
-|Yes
-
-
-|xref:_ug_reference-annotations_manpage-MinLength[`@MinLength`]
-|Minimum number of characters required for an auto-complete search argument.
-|UI
-|
-
-
-|xref:_ug_reference-annotations_manpage-Programmatic[`@Programmatic`]
-|Ignore a public method, excluded from the Isis metamodel.
-|Domain
-|
-
-|xref:_ug_reference-annotations_manpage-Title[`@Title`]
-|Indicates which of the object's properties should be used to build up a title for the object.
-|UI
-
-|===
-
-
[12/45] isis git commit: ISIS-1133: breaking out reference guide and
devenv guide;
moving appendices' release notes and migration notes to other docs;
improving the documentation page.
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_utility_manpage-ObjectContracts.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_utility_manpage-ObjectContracts.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_utility_manpage-ObjectContracts.adoc
deleted file mode 100644
index 6a0ead0..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_utility_manpage-ObjectContracts.adoc
+++ /dev/null
@@ -1,107 +0,0 @@
-[[_ug_reference-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 entities:
-
- Party <->* AgreementRole <*-> Agreement
-
-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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_utility_manpage-Reasons.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_utility_manpage-Reasons.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_utility_manpage-Reasons.adoc
deleted file mode 100644
index c9fb7ab..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_utility_manpage-Reasons.adoc
+++ /dev/null
@@ -1,31 +0,0 @@
-[[_ug_reference-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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_utility_manpage-TitleBuffer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_utility_manpage-TitleBuffer.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_utility_manpage-TitleBuffer.adoc
deleted file mode 100644
index af2e45e..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_utility_manpage-TitleBuffer.adoc
+++ /dev/null
@@ -1,13 +0,0 @@
-[[_ug_reference-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:_ug_reference-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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_value-types.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_value-types.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_value-types.adoc
deleted file mode 100644
index d952b27..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_value-types.adoc
+++ /dev/null
@@ -1,119 +0,0 @@
-[[_ug_reference-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/
-
-IMPORTANT: 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,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::_ug_reference-classes_value-types_manpage-Blob.adoc[leveloffset=+1]
-include::_ug_reference-classes_value-types_manpage-Clob.adoc[leveloffset=+1]
-include::_ug_reference-classes_value-types_manpage-Color.adoc[leveloffset=+1]
-include::_ug_reference-classes_value-types_manpage-Money.adoc[leveloffset=+1]
-include::_ug_reference-classes_value-types_manpage-Password.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_value-types_manpage-Blob.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_value-types_manpage-Blob.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_value-types_manpage-Blob.adoc
deleted file mode 100644
index 43bbdd0..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_value-types_manpage-Blob.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-[[_ug_reference-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/
-
-
-IMPORTANT: TODO
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_value-types_manpage-Clob.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_value-types_manpage-Clob.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_value-types_manpage-Clob.adoc
deleted file mode 100644
index cd39586..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_value-types_manpage-Clob.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-[[_ug_reference-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/
-
-
-IMPORTANT: TODO
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_value-types_manpage-Color.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_value-types_manpage-Color.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_value-types_manpage-Color.adoc
deleted file mode 100644
index e23feb7..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_value-types_manpage-Color.adoc
+++ /dev/null
@@ -1,9 +0,0 @@
-[[_ug_reference-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/
-
-
-IMPORTANT: TODO
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_value-types_manpage-Money.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_value-types_manpage-Money.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_value-types_manpage-Money.adoc
deleted file mode 100644
index 14cf8dc..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_value-types_manpage-Money.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-[[_ug_reference-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/
-
-
-IMPORTANT: TODO
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_value-types_manpage-Password.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_value-types_manpage-Password.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_value-types_manpage-Password.adoc
deleted file mode 100644
index 40c1289..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-classes_value-types_manpage-Password.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-[[_ug_reference-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/
-
-
-IMPORTANT: TODO
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods.adoc
deleted file mode 100644
index 0090596..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods.adoc
+++ /dev/null
@@ -1,17 +0,0 @@
-[[_ug_reference-methods]]
-= Reference: 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:_ug_reference-annotations[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::_ug_reference-methods_prefixes.adoc[leveloffset=+1]
-include::_ug_reference-methods_reserved.adoc[leveloffset=+1]
-include::_ug_reference-methods_lifecycle.adoc[leveloffset=+1]
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_lifecycle.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_lifecycle.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_lifecycle.adoc
deleted file mode 100644
index 5f38dd7..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_lifecycle.adoc
+++ /dev/null
@@ -1,99 +0,0 @@
-[[_ug_reference-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 Isis rather than JDO. In the future we may deprecate them because they duplicate functionality already available in JDO.
-
-You may therefore want to consider using the JDO API directly; see xref:_ug_reference-methods_lifecycle_jdo-api[here] for further discussion.
-====
-
-The lifecycle callback methods supported by Isis are:
-
-.Lifecycle methods (partial support)
-[cols="1,4a", options="header"]
-|===
-
-|Method
-|Description
-
-|xref:_ug_reference-methods_lifecycle_manpage-created[`created()`]
-|called when an object has just been created using xref:_ug_reference-services-api_manpage-DomainObjectContainer[`newTransientInstance()`]
-
-|xref:_ug_reference-methods_lifecycle_manpage-loaded[`loaded()`]
-|called when a (persistent) object has just been loaded from the object store.
-
-|xref:_ug_reference-methods_lifecycle_manpage-persisted[`persisted()`]
-|called when object has just been persisted from the object store.
-
-|xref:_ug_reference-methods_lifecycle_manpage-persisting[`persisting()`]
-|called when a (not-yet-persistent) object is just about to be persisted from the object store
-
-|xref:_ug_reference-methods_lifecycle_manpage-removed[`removed()`]
-|called when a (persistent) object has just been deleted from the object store
-
-|xref:_ug_reference-methods_lifecycle_manpage-removing[`removing()`]
-|called when a (persistent) object is just about to be deleted from the object store
-
-|xref:_ug_reference-methods_lifecycle_manpage-updated[`updated()`]
-|called when a (persistent) object has just been updated in the object store
-
-|xref:_ug_reference-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:_ug_reference-methods_lifecycle_manpage-removed[`removed()`]
-
-|`deleting()`
-|Replaced by xref:_ug_reference-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:_ug_reference-methods_lifecycle_manpage-persisted[`persisted()`]
-
-|`saving()`
-|Replaced by xref:_ug_reference-methods_lifecycle_manpage-persisting[`persisting()`]
-
-|===
-
-
-
-
-include::_ug_reference-methods_lifecycle_manpage-created.adoc[leveloffset=+1]
-include::_ug_reference-methods_lifecycle_manpage-loaded.adoc[leveloffset=+1]
-include::_ug_reference-methods_lifecycle_manpage-persisted.adoc[leveloffset=+1]
-include::_ug_reference-methods_lifecycle_manpage-persisting.adoc[leveloffset=+1]
-include::_ug_reference-methods_lifecycle_manpage-removed.adoc[leveloffset=+1]
-include::_ug_reference-methods_lifecycle_manpage-removing.adoc[leveloffset=+1]
-include::_ug_reference-methods_lifecycle_manpage-updated.adoc[leveloffset=+1]
-include::_ug_reference-methods_lifecycle_manpage-updating.adoc[leveloffset=+1]
-
-include::_ug_reference-methods_lifecycle_jdo-api.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_lifecycle_jdo-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_lifecycle_jdo-api.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_lifecycle_jdo-api.adoc
deleted file mode 100644
index c8510f3..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_lifecycle_jdo-api.adoc
+++ /dev/null
@@ -1,50 +0,0 @@
-[[_ug_reference-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 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 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:_ug_reference-services-api_manpage-IsisJdoSupport[`IsisJdoSupport`] domain service.
-
-For example:
-
-[source,java]
-----
-@DomainService(nature=NatureOfService.DOMAIN)
-public class ObjectChangedListenerService
- implements javax.jdo.listener.StoreLifecycleListener { // <1>
- @Programmatic
- @PostConstruct
- public void init() {
- getPmFactory().addInstanceLifecycleListener(this);
- }
- @Programmatic
- @PreDestroy
- public void tidyUp() {
- getPmFactory().removeInstanceLifecycleListener(this);
- }
- private PersistenceManagerFactory getPmFactory() {
- return jdoSupport.getPersistenceManager()
- .getPersistenceManagerFactory(); // <2>
- }
- @Programmatic
- public void preStore (InstanceLifecycleEvent event) { ... }
- @Programmatic
- public void postStore (InstanceLifecycleEvent event) { ... }
- @Inject
- IsisJdoSupport jdoSupport;
-}
-----
-<1> implement whichever callback lifecycle listeners are of interest
-<2> register on the factory so set up for every subsequent session.
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_lifecycle_manpage-created.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_lifecycle_manpage-created.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_lifecycle_manpage-created.adoc
deleted file mode 100644
index 2e619e6..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_lifecycle_manpage-created.adoc
+++ /dev/null
@@ -1,11 +0,0 @@
-[[_ug_reference-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:_ug_reference-services-api_manpage-DomainObjectContainer[`newTransientInstance()`]
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_lifecycle_manpage-loaded.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_lifecycle_manpage-loaded.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_lifecycle_manpage-loaded.adoc
deleted file mode 100644
index f17f6b2..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_lifecycle_manpage-loaded.adoc
+++ /dev/null
@@ -1,10 +0,0 @@
-[[_ug_reference-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.
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_lifecycle_manpage-persisted.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_lifecycle_manpage-persisted.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_lifecycle_manpage-persisted.adoc
deleted file mode 100644
index 5eb0705..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_lifecycle_manpage-persisted.adoc
+++ /dev/null
@@ -1,12 +0,0 @@
-[[_ug_reference-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:_ug_reference-methods_lifecycle_manpage-persisting[`persisting()`].
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_lifecycle_manpage-persisting.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_lifecycle_manpage-persisting.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_lifecycle_manpage-persisting.adoc
deleted file mode 100644
index 6754217..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_lifecycle_manpage-persisting.adoc
+++ /dev/null
@@ -1,12 +0,0 @@
-[[_ug_reference-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:_ug_reference-methods_lifecycle_manpage-persisted[`persisted()`].
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_lifecycle_manpage-removed.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_lifecycle_manpage-removed.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_lifecycle_manpage-removed.adoc
deleted file mode 100644
index 685005f..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_lifecycle_manpage-removed.adoc
+++ /dev/null
@@ -1,12 +0,0 @@
-[[_ug_reference-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:_ug_reference-methods_lifecycle_manpage-removing[`removing()`].
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_lifecycle_manpage-removing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_lifecycle_manpage-removing.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_lifecycle_manpage-removing.adoc
deleted file mode 100644
index 58688c9..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_lifecycle_manpage-removing.adoc
+++ /dev/null
@@ -1,12 +0,0 @@
-[[_ug_reference-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:_ug_reference-methods_lifecycle_manpage-removed[`removed()`].
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_lifecycle_manpage-updated.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_lifecycle_manpage-updated.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_lifecycle_manpage-updated.adoc
deleted file mode 100644
index f779ead..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_lifecycle_manpage-updated.adoc
+++ /dev/null
@@ -1,14 +0,0 @@
-[[_ug_reference-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:_ug_reference-methods_lifecycle_manpage-updating[`updating()`].
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_lifecycle_manpage-updating.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_lifecycle_manpage-updating.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_lifecycle_manpage-updating.adoc
deleted file mode 100644
index 5912cd3..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_lifecycle_manpage-updating.adoc
+++ /dev/null
@@ -1,10 +0,0 @@
-[[_ug_reference-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:_ug_reference-methods_lifecycle_manpage-updated[`updated()`].
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes.adoc
deleted file mode 100644
index 8b229b8..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes.adoc
+++ /dev/null
@@ -1,219 +0,0 @@
-[[_ug_reference-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:_ug_reference-methods_prefixes_manpage-addTo[`addTo...()`]
-|
-|
-|Y
-|
-|
-|add object to a collection +
-
-[NOTE]
-====
-Directly mutable collections are not currently supported by the xref:_ug_wicket-viewer[Wicket viewer].
-====
-
-See also xref:_ug_reference-methods_prefixes_manpage-removeFrom[`removeFrom...()`]`
-
-
-|xref:_ug_reference-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:_ug_reference-annotations_manpage-DomainObject_autoCompleteRepository[`@DomainObject` +
-`#autoCompleteRepository`] +
-
-See also xref:_ug_reference-methods_prefixes_manpage-choices[`choices...()`]
-
-|xref:_ug_reference-methods_prefixes_manpage-choices[`choices...()`]
-|
-|Y
-|
-|
-|Y
-|Provide list of choices for a property or action parameter. +
-
-See also xref:_ug_reference-methods_prefixes_manpage-autoComplete[`autoComplete...()`].
-
-|xref:_ug_reference-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:_ug_reference-methods_prefixes_manpage-modify[`modify...()`]
-
-
-|xref:_ug_reference-methods_prefixes_manpage-default[`default...()`]
-|
-|Y
-|
-|
-|Y
-|Default value for a property or an action parameter.
-
-|xref:_ug_reference-methods_prefixes_manpage-disable[`disable...()`]
-|Y
-|Y
-|Y
-|Y
-|
-|Disables (makes read-only) a property, a collection or an action.
-
-|xref:_ug_reference-methods_prefixes_manpage-get[`get...()`]
-|
-|Y
-|Y
-|
-|
-|Access the value of a property or collection. +
-
-See also xref:_ug_reference-methods_prefixes_manpage-set[`set...()`].
-
-|xref:_ug_reference-methods_prefixes_manpage-hide[`hide...()`]
-|
-|Y
-|Y
-|Y
-|
-|Hides a property, a collection or an action.
-
-|xref:_ug_reference-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:_ug_reference-methods_prefixes_manpage-clear[`clear...()`]`.
-
-|xref:_ug_reference-methods_prefixes_manpage-removeFrom[`removeFrom...()`]
-|
-|
-|Y
-|
-|
-|remove object from a collection. +
-
-[NOTE]
-====
-Directly mutable collections are not currently supported by the xref:_ug_wicket-viewer[Wicket viewer].
-====
-
-See also xref:_ug_reference-methods_prefixes_manpage-addTo[`addTo...()`]`
-
-
-|xref:_ug_reference-methods_prefixes_manpage-set[`set...()`]
-|
-|Y
-|Y
-|
-|
-|Sets the value of a property or a collection.
-
-|xref:_ug_reference-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:_ug_reference-methods_prefixes_manpage-validateAddTo[`validateAddTo...()`] and xref:_ug_reference-methods_prefixes_manpage-validateRemoveFrom[`validateRemoveFrom...()`] to validate modifications to collections.
-
-|xref:_ug_reference-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:_ug_wicket-viewer[Wicket viewer].
-====
-
-See also xref:_ug_reference-methods_prefixes_manpage-validateRemoveFrom[`validateRemoveFrom...()`], and xref:_ug_reference-methods_prefixes_manpage-validate[`validate...()`] for properties and actions.
-
-|xref:_ug_reference-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:_ug_wicket-viewer[Wicket viewer].
-====
-
-See also xref:_ug_reference-methods_prefixes_manpage-validateAddTo[`validateAddTo...()`], and xref:_ug_reference-methods_prefixes_manpage-validate[`validate...()`] for properties and actions.
-
-|===
-
-
-
-include::_ug_reference-methods_prefixes_manpage-addTo.adoc[leveloffset=+1]
-include::_ug_reference-methods_prefixes_manpage-autoComplete.adoc[leveloffset=+1]
-include::_ug_reference-methods_prefixes_manpage-choices.adoc[leveloffset=+1]
-include::_ug_reference-methods_prefixes_manpage-clear.adoc[leveloffset=+1]
-include::_ug_reference-methods_prefixes_manpage-default.adoc[leveloffset=+1]
-include::_ug_reference-methods_prefixes_manpage-disable.adoc[leveloffset=+1]
-include::_ug_reference-methods_prefixes_manpage-get.adoc[leveloffset=+1]
-include::_ug_reference-methods_prefixes_manpage-hide.adoc[leveloffset=+1]
-include::_ug_reference-methods_prefixes_manpage-modify.adoc[leveloffset=+1]
-include::_ug_reference-methods_prefixes_manpage-removeFrom.adoc[leveloffset=+1]
-include::_ug_reference-methods_prefixes_manpage-set.adoc[leveloffset=+1]
-include::_ug_reference-methods_prefixes_manpage-validate.adoc[leveloffset=+1]
-include::_ug_reference-methods_prefixes_manpage-validateAddTo.adoc[leveloffset=+1]
-include::_ug_reference-methods_prefixes_manpage-validateRemoveFrom.adoc[leveloffset=+1]
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-addTo.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-addTo.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-addTo.adoc
deleted file mode 100644
index e732e41..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-addTo.adoc
+++ /dev/null
@@ -1,37 +0,0 @@
-[[_ug_reference-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:_ug_wicket-viewer[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:_ug_reference-methods_prefixes_manpage-removeFrom[`removeFrom...()`]`
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-autoComplete.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-autoComplete.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-autoComplete.adoc
deleted file mode 100644
index 688fa7d..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-autoComplete.adoc
+++ /dev/null
@@ -1,91 +0,0 @@
-[[_ug_reference-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:_ug_reference-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 Collection<T> autoCompleteNXxx(String search) { ... }
-----
-
-
-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:_ug_reference-annotations_manpage-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 Collection<T> autoCompleteXxx(String search) { ... }
-----
-
-
-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:_ug_reference-annotations_manpage-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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-choices.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-choices.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-choices.adoc
deleted file mode 100644
index 6491c10..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-choices.adoc
+++ /dev/null
@@ -1,143 +0,0 @@
-[[_ug_reference-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:_ug_reference-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_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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-clear.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-clear.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-clear.adoc
deleted file mode 100644
index c539cbd..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-clear.adoc
+++ /dev/null
@@ -1,32 +0,0 @@
-[[_ug_reference-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:_ug_reference-methods_prefixes_manpage-modify[`modify...()`]`
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-default.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-default.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-default.adoc
deleted file mode 100644
index a53d186..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-default.adoc
+++ /dev/null
@@ -1,129 +0,0 @@
-[[_ug_reference-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:_ug_reference-services-api_manpage-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_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:_ug_reference-methods_lifecycle_manpage-created[`created()`] callback, called by the framework when xref:_ug_reference-services-api_manpage-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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-disable.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-disable.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-disable.adoc
deleted file mode 100644
index c6dbd2c..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-disable.adoc
+++ /dev/null
@@ -1,93 +0,0 @@
-[[_ug_reference-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:_ug_wicket-viewer[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, Isis' xref:_ug_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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-get.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-get.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-get.adoc
deleted file mode 100644
index f781b37..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-get.adoc
+++ /dev/null
@@ -1,19 +0,0 @@
-[[_ug_reference-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 Isis prefixes) are interpreted as actions.
-
-Any methods "left over" that _do_ use one of the Isis prefixes, are interpreted to be orphaned. 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:_ug_reference-methods_prefixes_manpage-set[`set...()`].
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-hide.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-hide.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-hide.adoc
deleted file mode 100644
index a70e27d..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-hide.adoc
+++ /dev/null
@@ -1,82 +0,0 @@
-[[_ug_reference-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:_ug_reference-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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-modify.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-modify.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-modify.adoc
deleted file mode 100644
index 4178943..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-modify.adoc
+++ /dev/null
@@ -1,37 +0,0 @@
-[[_ug_reference-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:_ug_reference-methods_prefixes_manpage-clear[`clear...()`]`
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-removeFrom.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-removeFrom.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-removeFrom.adoc
deleted file mode 100644
index d8b014e..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-removeFrom.adoc
+++ /dev/null
@@ -1,37 +0,0 @@
-[[_ug_reference-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:_ug_wicket-viewer[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:_ug_reference-methods_prefixes_manpage-addTo[`addTo...()`]`
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-set.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-set.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-set.adoc
deleted file mode 100644
index 5792bd2..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-set.adoc
+++ /dev/null
@@ -1,13 +0,0 @@
-[[_ug_reference-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:_ug_reference-methods_prefixes_manpage-get[`get...()`].
[14/45] isis git commit: ISIS-1133: breaking out reference guide and
devenv guide;
moving appendices' release notes and migration notes to other docs;
improving the documentation page.
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout_named.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout_named.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout_named.adoc
deleted file mode 100644
index f50e419..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout_named.adoc
+++ /dev/null
@@ -1,44 +0,0 @@
-[[_ug_reference-annotations_manpage-ParameterLayout_named]]
-= `named()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `named()` attribute explicitly specifies the action parameter's name. This attribute can also be specified for xref:_ug_reference-annotations_manpage-ActionLayout_named[actions], xref:_ug_reference-annotations_manpage-CollectionLayout_named[collections], xref:_ug_reference-annotations_manpage-PropertyLayout_named[properties], xref:_ug_reference-annotations_manpage-DomainObjectLayout_named[domain objects], xref:_ug_reference-annotations_manpage-ViewModelLayout_named[view models] and xref:_ug_reference-annotations_manpage-DomainServiceLayout_named[domain services].
-
-Unlike most other aspects of the Isis metamodel, the name of method parameters cannot (prior to Java 8, at least) be inferred from the Java source code. Without other information, Isis uses the object's type (`int`, `String` etc) as the name instead. This can be sufficient for application-specific reference types (eg `ToDoItem`) but is generally not sufficient for primitives and other value types.
-
-The `named()` attribute (or the xref:_ug_reference-annotations_aaa_deprecated[deprecated `@Named`] annotation) is therefore often required to specify the parameter name.
-
-As of Java 8, the Java reflection API has been extended. The (non-ASF) http://github.com/isisaddons/isis-metamodel-paraname8[Isis addons' paraname8] metamodel extension provides support for this. Note that your application must (obviously) be running on Java 8, and be compiled with the `-parameters` compile flag for javac.
-
-
-
-By default the name is HTML escaped. To allow HTML markup, set the related `namedEscaped()` attribute to `false`.
-
-For example:
-
-[source,java]
-----
-public class Customer {
- public Order placeOrder(
- final Product product
- ,@ParameterLayout(named="Quantity")
- final int quantity) {
- Order order = newTransientInstance(Order.class);
- order.modifyCustomer(this);
- order.modifyProduct(product);
- order.setQuantity(quantity);
- return order;
- }
- ...
-}
-----
-
-
-[TIP]
-====
-The framework also provides a separate, powerful mechanism for xref:_ug_more-advanced_i18n[internationalization].
-====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout_renderedAsDayBefore.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout_renderedAsDayBefore.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout_renderedAsDayBefore.adoc
deleted file mode 100644
index 77e1f4b..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout_renderedAsDayBefore.adoc
+++ /dev/null
@@ -1,35 +0,0 @@
-[[_ug_reference-annotations_manpage-ParameterLayout_renderedAsDayBefore]]
-= `renderedAsDayBefore()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `renderedAsDayBefore()` attribute applies only to date parameters whereby the date will be rendered as the day before the value actually held in the domain object. It is ignored for parameters of other types. This attribute is also supported for xref:_ug_reference-annotations_manpage-PropertyLayout_renderedAsDayBefore[properties].
-
-This behaviour might at first glance appear odd, but the rationale is to support the use case of a sequence of instances that represent adjacent intervals of time. In such cases there would typically be `startDate` and `endDate` properties, eg for all of Q2. Storing this as a half-closed interval -- eg `[1-Apr-2015, 1-July-2015)` -- can substantially simplify internal algorithms; the `endDate` of one interval will correspond to the `startDate` of the next.
-
-However, from an end-user perspective the requirement may be to render the interval as a fully closed interval; eg the end date should be shown as `30-Jun-2015`.
-
-This attribute therefore bridges the gap; it presents the information in a way that makes sense to an end-user, but also stores the domain object in a way that is easy work with internally.
-
-For example:
-
-[source,java]
-----
-public class Tenancy {
- public void changeDates(
- @ParameterLayout(named="Start Date")
- LocalDate startDate,
- @ParameterLayout(
- named="End Date",
- renderedAsDayBefore=true
- )
- LocalDate endDate) {
- ...
- }
-}
-----
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout_typicalLength.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout_typicalLength.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout_typicalLength.adoc
deleted file mode 100644
index 3b4137b..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout_typicalLength.adoc
+++ /dev/null
@@ -1,36 +0,0 @@
-[[_ug_reference-annotations_manpage-ParameterLayout_typicalLength]]
-= `typicalLength()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `typicalLength()` attribute indicates the typical length of a string parameter. It is ignored for parameters of other types. The attribute is also supported for xref:_ug_reference-annotations_manpage-PropertyLayout_typicalLength[properties].
-
-The information is intended as a hint to the UI to determine the space that should be given to render a particular string parameter. That said, note that the xref:_ug_wicket-viewer[Wicket viewer] uses the maximum space available for all fields, so in effect ignores this attribute.
-
-For example:
-
-[source,java]
-----
-public class Customer {
- public Customer updateName(
- @Parameter(maxLength=30)
- @ParameterLayout(
- named="First name",
- typicalLength=20
- )
- final String firstName,
- @Parameter(maxLength=30)
- @ParameterLayout(
- named="Last name",
- typicalLength=20
- )
- final String lastName) {
- ...
- }
- ...
-}
-----
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter_maxLength.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter_maxLength.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter_maxLength.adoc
deleted file mode 100644
index 2a78ab9..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter_maxLength.adoc
+++ /dev/null
@@ -1,35 +0,0 @@
-[[_ug_reference-annotations_manpage-Parameter_maxLength]]
-= `maxLength()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `maxLength()` attribute applies only to `String` parameters, indicating the maximum number of characters that the user may enter (for example in a text field in the UI). It is ignored if applied to parameters of any other type. This attribute can also be applied to xref:_ug_reference-annotations_manpage-Property_maxLength[properties].
-
-For example:
-
-[source,java]
-----
-public class CustomerRepository {
- public Customer newCustomer(
- @Parameter(maxLength=30)
- @ParameterLayout(named="First Name") // <1>
- final String firstName,
- @Parameter(maxLength=50)
- @ParameterLayout(named="Last Name")
- final String lastName) {
- ...
- }
-}
-----
-<1> the `@ParameterLayout(named=...)` attribute is required for Java 7; for Java 8 it can be omitted if the (non-ASF) http://github.com/isisaddons/isis-metamodel-paraname8[Isis addons' paraname8] metamodel extension is used.
-
-
-
-
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter_mustSatisfy.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter_mustSatisfy.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter_mustSatisfy.adoc
deleted file mode 100644
index 4dabf87..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter_mustSatisfy.adoc
+++ /dev/null
@@ -1,50 +0,0 @@
-[[_ug_reference-annotations_manpage-Parameter_mustSatisfy]]
-= `mustSatisfy()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `mustSatisfy()` attribute allows arbitrary validation to be applied to parameters using an (implementation of a) `org.apache.isis.applib.spec.Specification` object. The attribute is also supported on xref:_ug_reference-annotations_manpage-Property_mustSatisfy[properties].
-
-[TIP]
-====
-The specification implementations can (of course) be reused between parameters and xref:_ug_reference-annotations_manpage-Property_mustSatisfy[properties].
-====
-
-The `Specification` is consulted during validation, being passed the proposed value. If the proposed value fails, then the value returned is the used as the invalidity reason.
-
-For example:
-
-[source,java]
-----
-public class StartWithCapitalLetterSpecification
- extends AbstractSpecification<String> { // <1>
- 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 CustomerRepository {
- public Customer newCustomer(
- @Parameter(
- mustSatisfy=StartWithCapitalLetterSpecification.class
- )
- @ParameterLayout(named="First Name")
- final String firstName,
- @Parameter(
- mustSatisfy=StartWithCapitalLetterSpecification.class
- )
- @ParameterLayout(named="Last Name")
- final String lastName) {
- ...
- }
- ...
-}
-----
-<1> the `AbstractSpecification` class conveniently handles type-safety and dealing with null values. The applib also provides `SpecificationAnd` and `SpecificationOr` to allow specifications to be combined "algebraically".
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter_optionality.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter_optionality.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter_optionality.adoc
deleted file mode 100644
index 777604b..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter_optionality.adoc
+++ /dev/null
@@ -1,36 +0,0 @@
-[[_ug_reference-annotations_manpage-Parameter_optionality]]
-= `optionality()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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, Apache Isis assumes that all parameters of an action are required (mandatory). The `optionality()` attribute allows this to be relaxed. The attribute is also supported for xref:_ug_reference-annotations_manpage-Property_optionality[properties].
-
-
-[TIP]
-====
-The attribute has no meaning for a primitive type such as `int`: primitives will always have a default value (e.g. zero). If optionality is required, then use the corresponding wrapper class (e.g. `java.lang.Integer`) and annotate with `Parameter#optionality()` as required.
-====
-
-The values for the attribute are simply `OPTIONAL` or `MANDATORY`.
-
-For example:
-
-[source,java]
-----
-public class Customer {
- public Order placeOrder(
- final Product product,
- @ParameterLayout(named = "Quantity")
- final int quantity,
- @Parameter(optionality = Optionality.OPTIONAL)
- @ParameterLayout(named = "Special Instructions")
- final String instr) {
- ...
- }
- ...
-}
-----
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter_regexPattern.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter_regexPattern.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter_regexPattern.adoc
deleted file mode 100644
index e027891..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter_regexPattern.adoc
+++ /dev/null
@@ -1,31 +0,0 @@
-[[_ug_reference-annotations_manpage-Parameter_regexPattern]]
-= `regexPattern()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `regexPattern()` attribute validates the contents of any string parameter with respect to a regular expression pattern. It is ignored if applied to parameters of any other type. This attribute can also be specified for xref:_ug_reference-annotations_manpage-Property_regexPattern[properties].
-
-The related `regexPatternFlags()` attribute specifies flags that modify the handling of the pattern. The values are those that would normally be passed to `java.util.regex.Pattern#compile(String,int)`.
-
-For example:
-
-[source,java]
-----
-public class Customer {
- public void updateEmail(
- @Parameter(
- regexPattern = "(\\w+\\.)*\\w+@(\\w+\\.)+[A-Za-z]+",
- regexPatternFlags=Pattern.CASE_INSENSITIVE
- )
- @ParameterLayout(named = "Email")
- final String email) {
- ...
- }
-)
-----
-
-The related `regexPatternReplacement()` attribute is currently unused.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PersistenceCapable.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PersistenceCapable.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PersistenceCapable.adoc
deleted file mode 100644
index 993d4c3..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PersistenceCapable.adoc
+++ /dev/null
@@ -1,90 +0,0 @@
-[[_ug_reference-annotations_manpage-PersistenceCapable]]
-= `@PersistenceCapable` (`javax.jdo`)
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@javax.jdo.annotation.PersistenceCapable` is used by JDO/DataNucleus to indicate that a class is a domain entity to be persisted to the database.
-
-Apache Isis also checks for this annotation, and if the `@PersistenceCapable#schema()` attribute is present will use it to form the object type.
-
-[NOTE]
-====
-Isis parses the `@PersistenceCapable` annotation from the Java source code; it does not query the JDO metamodel. This means that it the `@PersistenceCapable` annotation must be used rather than the equivalent `<class>` link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/class_mapping.html[XML metadata].
-
-Moreover, while JDO/DataNucleus will recognize annotations on either the field or the getter method, Isis (currently) only inspects the getter method. Therefore ensure that the annotation is placed there.
-====
-
-
-The object type is used internally by Isis to generate a string representation of an objects identity (the `Oid`). This can appear in several contexts, including:
-
-* as the value of `o.a.i.applib.services.bookmark.Bookmark#getObjectType()`
-* in the `toString()` value of `Bookmark`
-* in the URLs of the xref:_ug_restfulobjects-viewer[RestfulObjects viewer]
-* in the URLs of the xref:_ug_wicket-viewer[Wicket viewer] (in general and in particular if xref:_ug_wicket-viewer_features_hints-and-copy-url[copying URLs])
-* in XML snapshots generated by the xref:_ug_reference-services-api_manpage-XmlSnapshotService[`XmlSnapshotService`]
-
-
-The actual format of the object type used by Isis for the concatenation of `schema()` and `@PersistenceCapable#table()`. If the `table()` is not present, then the class' simple name is used instead.
-
-For example:
-
-[source,java]
-----
-@javax.jdo.annotations.PersistenceCapable(schema="custmgmt")
-public class Customer {
- ...
-}
-----
-
-has an object type of `custmgmt.Customer`, while:
-
-[source,java]
-----
-@javax.jdo.annotations.PersistenceCapable(schema="custmgmt", table="Address")
-public class AddressImpl {
- ...
-}
-----
-
-has an object type of `custmgmt.Address`.
-
-
-On the other hand:
-
-[source,java]
-----
-@javax.jdo.annotations.PersistenceCapable(table="Address")
-public class AddressImpl {
- ...
-}
-----
-
-does _not_ correspond to an object type, because the `schema()` attribute is missing.
-
-If the object type has not been specified, then Isis will use the fully qualified class name of the entity.
-
-
-
-[TIP]
-====
-This might be obvious, but to make explicit: we recommend that you use namespaces of some form or other.
-
-If the object type has not been specified (by either this annotation, or by xref:_ug_reference-annotations_manpage-Discriminator[`@Discriminator`], or by Isis' own xref:_ug_reference-annotations_manpage-ObjectType[`@DomainObject#objectType()`] annotation/attribute), then (as noted above) Isis will use the fully qualified class name of the entity.
-
-
-However, chances are that the fully qualified class name is liable to change over time, for example if the code is refactored or (more fundamentally) if your company/organization reorganizes/renames itself/is acquired.
-
-Isis' recognition of `@PersistenceCapable#schema()` makes namespacing of object types comparatively trivial, and moreover aligns the namespacing with the way in which the tables in the database are namespaced by the database schema.
-
-We therefore strongly recommend that you specify an object type for all entities, one way or another. Using `@PersistenceCapable#schema()` is probably the best choice in most cases.
-====
-
-
-
-[NOTE]
-====
-If the object type is not unique across all domain classes then the framework will fail-fast and fail to boot. An error message will be printed in the log to help you determine which classes have duplicate object tyoes.
-====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PostConstruct.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PostConstruct.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PostConstruct.adoc
deleted file mode 100644
index 71e65ee..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PostConstruct.adoc
+++ /dev/null
@@ -1,66 +0,0 @@
-[[_ug_reference-annotations_manpage-PostConstruct]]
-= `@PostConstruct` (`javax`)
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@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.
-
-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:_ug_reference-annotations_manpage-RequestScoped[`@RequestScoped`] domain services, the method is called at the beginning of the request.
-
-The signature of the method is:
-
-[source,java]
-----
-@PostConstruct
-@Programmatic <1>
-public void postConstruct() { ... } <2>
-----
-<1> The method should be annotated using xref:_ug_reference-annotations_manpage-Programmatic[`@Programmatic`] so that it is not interpreted as an action.
-<2> the method can have any name, but must have `public` visibility.
-
-In the form shown above the method can either accept no arguments. Alternatively, the method can accept a parameter of type `Map<String,String>`:
-
-[source,java]
-----
-@PostConstruct
-@Programmatic
-public void postConstruct(Map<String,String> properties) { ... }
-----
-Isis uses argument to pass in the configuration properties read from all xref:_ug_runtime_configuration-files[configuration files]:
-
-[TIP]
-====
-Alternatively, you could inject xref:_ug_reference-services-api_manpage-DomainObjectContainer[`DomainObjectContainer`] into the service and read configuration properties using `DomainObjectContainer#getProperty(...)` and related methods.
-====
-
-A common use case is for domain services that interact with the xref:_ug_reference-services-api_manpage-EventBusService[`EventBusService`]. For example:
-
-[source,java]
-----
-@DomainService(nature=NatureOfService.DOMAIN)
-public class MySubscribingService {
- @Programmatic
- @PostConstruct
- public void postConstruct() {
- eventBusService.register(this);
- }
- @Programmatic
- @PreDestroy
- public void preDestroy() {
- eventBusService.unregister(this);
- }
- ...
- @javax.inject.Inject
- EventBusService eventBusService;
-}
-----
-
-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.
-
-
-
-
-
-See also xref:_ug_reference-annotations_manpage-PreDestroy[`@PreDestroy`]
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PreDestroy.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PreDestroy.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PreDestroy.adoc
deleted file mode 100644
index e3dcc31..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PreDestroy.adoc
+++ /dev/null
@@ -1,50 +0,0 @@
-[[_ug_reference-annotations_manpage-PreDestroy]]
-= `@PreDestroy` (`javax`)
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@javax.annotation.PreDestroy` annotation, as defined in link:https://jcp.org/en/jsr/detail?id=250[JSR-250], recognized by Apache Isis as a callback method on domain services to be called just as they go out of scope.
-
-For the default application-scoped (singleton) domain services, this means that the method, if present, is called just prior to the termination of the application. For xref:_ug_reference-annotations_manpage-RequestScoped[`@RequestScoped`] domain services, the method is called at the end of the request.
-
-The signature of the method is:
-
-[source,java]
-----
-@PreDestroy
-@Programmatic <1>
-public void preDestroy() { ... } <2>
-----
-<1> The method should be annotated using xref:_ug_reference-annotations_manpage-Programmatic[`@Programmatic`] so that it is not interpreted as an action.
-<2> the method can have any name, but must have `public` visibility, and accept no arguments.
-
-A common use case is for domain services that interact with the xref:_ug_reference-services-api_manpage-EventBusService[`EventBusService`]. For example:
-
-[source,java]
-----
-@DomainService(nature=NatureOfService.DOMAIN)
-public class MySubscribingService {
- @Programmatic
- @PostConstruct
- public void postConstruct() {
- eventBusService.register(this);
- }
- @Programmatic
- @PreDestroy
- public void preDestroy() {
- eventBusService.unregister(this);
- }
- ...
- @javax.inject.Inject
- EventBusService eventBusService;
-}
-----
-
-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.
-
-
-
-See also xref:_ug_reference-annotations_manpage-PostConstruct[`@PostConstruct`]
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PrimaryKey.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PrimaryKey.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PrimaryKey.adoc
deleted file mode 100644
index 5be6424..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PrimaryKey.adoc
+++ /dev/null
@@ -1,19 +0,0 @@
-[[_ug_reference-annotations_manpage-PrimaryKey]]
-= `@PrimaryKey` (`javax.jdo`)
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@javax.jdo.annotation.PrimaryKey` annotation is used by JDO/DataNucleus to indicate that a property is used as the primary key for an entity with application-managed identity.
-
-Apache Isis also uses this annotation in a very minimal way: to ensure that the framework's own logic to initialize newly instantiated objects (eg using xref:_ug_reference-services-api_manpage-DomainObjectContainer[`DomainObjectContainer#newTransientInstance(...)`] does not touch the primary key, and also to ensure that the primary key property is always disabled (read-only).
-
-[NOTE]
-====
-Isis parses the `@NotPersistent` annotation from the Java source code; it does not query the JDO metamodel. This means that it the `@NotPersistent` annotation must be used rather than the equivalent `<field>` link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/application_identity.html[XML metadata].
-
-Moreover, while JDO/DataNucleus will recognize annotations on either the field or the getter method, Isis (currently) only inspects the getter method. Therefore ensure that the annotation is placed there.
-====
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Programmatic.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Programmatic.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Programmatic.adoc
deleted file mode 100644
index 064bf1d..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Programmatic.adoc
+++ /dev/null
@@ -1,27 +0,0 @@
-[[_ug_reference-annotations_manpage-Programmatic]]
-= `@Programmatic`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@Programmatic` annotation causes the method to be excluded completely from the Apache Isis metamodel. This means it won't appear in any UI, and it won't appear in any xref:_ug_reference-services-api_manpage-MementoService[memento]s or xref:_ug_reference-services-api_manpage-XmlSnapshotService[snapshot]s.
-
-A common use-case is to ignore implementation-level artifacts. For example:
-
-[source,java]
-----
-public class Customer implements Comparable<Customer> {
- ...
- @Programmatic
- public int compareTo(Customer c) {
- return getSalary() - c.getSalary();
- }
- ...
-}
-----
-
-
-Note that `@Programmatic` does not simply imply `@Hidden`; it actually means that the class member will not be part of the Isis metamodel.
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property.adoc
deleted file mode 100644
index 7fa9eb3..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property.adoc
+++ /dev/null
@@ -1,125 +0,0 @@
-[[_ug_reference-annotations_manpage-Property]]
-= `@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/
-
-
-The `@Property` annotation applies to properties collecting together all domain semantics within a single annotation.
-
-It is also possible to apply the annotation to actions of domain services that are acting as link:../../more-advanced-topics/how-to-01-062-How-to-decouple-dependencies-using-contributions.html[contributed properties].
-
-
-
-.`@Property` attributes
-[cols="2,2,4a", options="header"]
-|===
-
-| Attribute
-| Values (default)
-| Description
-
-
-|xref:_ug_reference-annotations_manpage-Property_domainEvent[`domainEvent()`]
-|subtype of `PropertyDomainEvent` +
-(`PropertyDomainEvent.Default`)
-|the event type to be posted to the xref:_ug_reference-services-api_manpage-EventBusService[`EventBusService`] to broadcast the property's business rule checking (hide, disable, validate) and its modification (before and after).
-
-
-|xref:_ug_reference-annotations_manpage-Property_editing[`editing()`]
-|`ENABLED`, `DISABLED`, `AS_CONFIGURED` +
-(`AS_CONFIGURED`)
-|whether a property can be modified or cleared from within the UI
-
-
-|xref:_ug_reference-annotations_manpage-Property_hidden[`hidden()`]
-|`EVERYWHERE`, `OBJECT_FORMS`, `PARENTED_TABLES`, `STANDALONE_TABLES`, `ALL_TABLES`, `NOWHERE` +
-(`NOWHERE`)
-|indicates where (in the UI) the property should be hidden from the user.
-
-
-|xref:_ug_reference-annotations_manpage-Property_maxLength[`maxLength()`]
-|
-|maximum number of characters for string parameters; ignored otherwise +
-
-In many/most cases you should however use xref:_ug_reference-annotations_manpage-Column[`@Column#length()`]
-
-
-|xref:_ug_reference-annotations_manpage-Property_mustSatisfy[`mustSatisfy()`]
-|implementation of `o.a.i.applib.spec.Specification`
-|allows arbitrary validation to be applied
-
-
-|xref:_ug_reference-annotations_manpage-Property_notPersisted[`notPersisted()`]
-|`true`, `false` +
-(`false`)
-|whether to exclude from snapshots. +
-
-[WARNING]
-====
-Property must also be annotated with `@javax.jdo.annotations.NotPersistent` in order to not be persisted.
-====
-
-
-|xref:_ug_reference-annotations_manpage-Property_optionality[`optionality()`]
-|
-|specifies a property is optional rather than mandatory +
-
-In many/most cases you should however use xref:_ug_reference-annotations_manpage-Column[`@Column#allowNulls()`]
-
-
-
-|xref:_ug_reference-annotations_manpage-Property_regexPattern[`regexPattern()`]
-|regular expression
-|validates the contents of a string parameter against the regular expression pattern
-
-
-|`regexPatternFlags()`
-|value of flags as normally passed to `java.util.regex.` +
-`Pattern#compile(...)`
-|modifies the compilation of the regular expression
-
-
-|===
-
-
-For example:
-
-[source,java]
-----
-@DomainObject
-public class Customer {
- public static class EmailSpecification extends AbstractSpecification<String> {
- public String satisfiesSafely(String proposed) {
- return EmailUtil.ensureValidEmail(proposed); // <1>
- }
- }
- @javax.jdo.annotations.Column(allowNulls="true") // <2>
- @Property(
- maxLength=30,
- minLength=5,
- mustSatisfy=EmailSpecification.class,
- regexPattern = "(\\w+\\.)*\\w+@(\\w+\\.)+[A-Za-z]+",
- regexPatternFlags=Pattern.CASE_INSENSITIVE
- )
- public String getEmailAddress() { ... }
- public void setEmailAddress(String emailAddress) { ... }
- ...
-}
-----
-<1> the (fictitious) `EmailUtil.ensureValid(...)` (omitted for brevity) returns a string explaining if an email is invalid
-<2> generally use instead of the `@Property#optionality()` attribute
-
-
-
-include::_ug_reference-annotations_manpage-Property_domainEvent.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-Property_editing.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-Property_hidden.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-Property_maxLength.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-Property_mustSatisfy.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-Property_notPersisted.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-Property_optionality.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-Property_regexPattern.adoc[leveloffset=+1]
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout.adoc
deleted file mode 100644
index 773cd8d..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout.adoc
+++ /dev/null
@@ -1,135 +0,0 @@
-[[_ug_reference-annotations_manpage-PropertyLayout]]
-= `@PropertyLayout`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@PropertyLayout` annotation applies to properties collecting together all UI hints within a single annotation.
-
-
-The table below summarizes the annotation's attributes.
-
-.`@PropertyLayout` attributes
-[cols="2,2,4a", options="header"]
-|===
-
-| Attribute
-| Values (default)
-| Description
-
-
-|xref:_ug_reference-annotations_manpage-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:_ug_runtime_application-specific_application-css[`application.css`]
-
-
-|xref:_ug_reference-annotations_manpage-PropertyLayout_describedAs[`describedAs()`]
-|String
-|description of this property, eg to be rendered in a tooltip.
-
-
-|xref:_ug_reference-annotations_manpage-PropertyLayout_hidden[`hidden()`]
-|`EVERYWHERE`, `OBJECT_FORMS`, `PARENTED_TABLES`, `STANDALONE_TABLES`, `ALL_TABLES`, `NOWHERE` +
-(`NOWHERE`)
-|indicates where (in the UI) the property should be hidden from the user.
-
-
-|xref:_ug_reference-annotations_manpage-PropertyLayout_labelPosition[`labelPosition()`]
-|`LEFT`, `TOP`, `RIGHT`, `NONE` +
-(`LEFT`)
-|in forms, the positioning of the label relative to the property value. +
-
-Defaults is `LEFT`, unless xref:_ug_reference-annotations_manpage-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:_ug_runtime_configuring-core_isis-viewers-propertyLayout-labelPosition[configuration property]
-
-
-|xref:_ug_reference-annotations_manpage-PropertyLayout_multiLine[`multiLine()`]
-|Positive integer
-|for string properties, render as a text area over multiple lines. +
-
-If set > 1, then xref:_ug_reference-annotations_manpage-PropertyLayout_labelPosition[`labelPosition`] defaults to TOP.
-
-
-|xref:_ug_reference-annotations_manpage-PropertyLayout_named[`named()`]
-|String
-|to override the name inferred from the collection's name in code. +
-
-A typical use case is if the desired name is a reserved Java keyword, such as `default` or `package`.
-
-
-|`namedEscaped()`
-|`true`, `false` +
-(`true`)
-|whether to HTML escape the name of this property.
-
-
-|xref:_ug_reference-annotations_manpage-PropertyLayout_renderedAsDayBefore[`renderedAsDayBefore()`]
-|`true`, `false` +
-(`false`)
-|for date properties only, render the date as one day prior to the actually stored date.
-
-
-|xref:_ug_reference-annotations_manpage-PropertyLayout_typicalLength[`typicalLength()`]
-|Positive integer.
-|the typical entry length of a field, use to determine the optimum width for display
-
-|===
-
-
-
-
-For example:
-
-[source,java]
-----
-public class ToDoItem {
- @PropertyLayout(
- cssClass="x-key",
- named="Description of this <i>item</i>",
- namedEscaped=false,
- describedAs="What needs to be done",
- labelPosition=LabelPosition.LEFT,
- typicalLength=80
- )
- public String getDescription() { ... }
- ...
-}
-----
-
-It is also possible to apply the annotation to actions of domain services that are acting as link:../../more-advanced-topics/how-to-01-062-How-to-decouple-dependencies-using-contributions.html[contributed properties].
-
-
-
-As an alternative to using the `@PropertyLayout` annotation, a dynamic layout using xref:_ug_reference-object-layout_dynamic[`.layout.json`] file can be specified; for example:
-
-[source,javascript]
-----
-"description": {
- "propertyLayout": {
- "cssClass": "x-key",
- "describedAs": "What needs to be done",
- "labelPosition": "LEFT",
- "typicalLength": 80
- }
-}
-----
-
-
-
-
-
-include::_ug_reference-annotations_manpage-PropertyLayout_cssClass.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-PropertyLayout_describedAs.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-PropertyLayout_labelPosition.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-PropertyLayout_multiLine.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-PropertyLayout_named.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-PropertyLayout_renderedAsDayBefore.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-PropertyLayout_typicalLength.adoc[leveloffset=+1]
-
-
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout_cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout_cssClass.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout_cssClass.adoc
deleted file mode 100644
index dd2d1d5..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout_cssClass.adoc
+++ /dev/null
@@ -1,36 +0,0 @@
-[[_ug_reference-annotations_manpage-PropertyLayout_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()` attribute can be used to render additional CSS classes in the HTML (a wrapping `<div>`) that represents the property. xref:_ug_runtime_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:_ug_reference-annotations_manpage-DomainObjectLayout_cssClass[domain objects], xref:_ug_reference-annotations_manpage-ViewModelLayout_cssClass[view models], xref:_ug_reference-annotations_manpage-ActionLayout_cssClass[actions] xref:_ug_reference-annotations_manpage-CollectionLayout_cssClass[collections] and xref:_ug_reference-annotations_manpage-ParameterLayout_cssClass[parameters].
-
-
-For example:
-
-[source,java]
-----
-public class ToDoItem {
- @PropertyLayout(cssClass="x-key")
- public LocalDate getDueBy() { ... }
-}
-----
-
-
-
-
-As an alternative to using the annotation, the dynamic xref:_ug_reference-object-layout_dynamic[`.layout.json`]
-can be used instead, eg:
-
-[source,javascript]
-----
-"dueBy": {
- "propertyLayout": { "cssClass": "x-key" }
-}
-----
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout_describedAs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout_describedAs.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout_describedAs.adoc
deleted file mode 100644
index f4c6675..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout_describedAs.adoc
+++ /dev/null
@@ -1,33 +0,0 @@
-[[_ug_reference-annotations_manpage-PropertyLayout_describedAs]]
-= `describedAs()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `describedAs()` attribute is used to provide a short description of the property to the user. In the xref:_ug_wicket-viewer[Wicket viewer] it is displayed as a 'tool tip'. The attribute can also be specified for xref:_ug_reference-annotations_manpage-CollectionLayout_describedAs[collections], xref:_ug_reference-annotations_manpage-ActionLayout_describedAs[actions], xref:_ug_reference-annotations_manpage-ParameterLayout_describedAs[parameters], xref:_ug_reference-annotations_manpage-DomainObjectLayout_describedAs[domain objects] and xref:_ug_reference-annotations_manpage-ViewModelLayout_describedAs[view models].
-
-For example:
-
-[source,java]
-----
-public class Customer {
- @DescribedAs("The name that the customer has indicated that they wish to be " +
- "addressed as (e.g. Johnny rather than Jonathan)")
- public String getFirstName() { ... }
-}
-----
-
-
-As an alternative to using the annotation, the dynamic xref:_ug_reference-object-layout_dynamic[`.layout.json`]
-can be used instead, eg:
-
-[source,javascript]
-----
-"firstName:" {
- "propertyLayout": {
- "describedAs": "The name that the customer has indicated that they wish to be addressed as (e.g. Johnny rather than Jonathan)"
- }
-}
-----
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout_hidden.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout_hidden.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout_hidden.adoc
deleted file mode 100644
index 1ae767b..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout_hidden.adoc
+++ /dev/null
@@ -1,78 +0,0 @@
-[[_ug_reference-annotations_manpage-PropertyLayout_hidden]]
-= `hidden()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `hidden()` attribute indicates where (in the UI) the property should be hidden from the user. This attribute can also be applied to xref:_ug_reference-annotations_manpage-Action_hidden[actions] and xref:_ug_reference-annotations_manpage-Collection_hidden[collections].
-
-[TIP]
-====
-It is also possible to use xref:_ug_reference-annotations_manpage-PropertyLayout_hidden[`@PropertyLayout#hidden()`] or xref:_ug_reference-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.
-====
-
-
-For example:
-
-[source,java]
-----
-public class Customer {
- @PropertyLayout(
- hidden=Where.ALL_TABLES
- )
- public int getInternalId() { ... }
- ...
-}
-----
-
-The acceptable values for the `where` parameter are:
-
-* `Where.EVERYWHERE` or `Where.ANYWHERE` +
-+
-The property should be hidden everywhere.
-
-* `Where.ANYWHERE` +
-+
-Synonym for everywhere.
-
-* `Where.OBJECT_FORMS` +
-+
-The property should be hidden when displayed within an object form.
-
-* `Where.PARENTED_TABLES` +
-+
-The property should be hidden when displayed as a column of a table within a parent object's collection.
-
-* `Where.STANDALONE_TABLES` +
-+
-The property should be hidden when displayed as a column of a table showing a standalone list of objects, for example as returned by a repository query.
-
-* `Where.ALL_TABLES` +
-+
-The property should be hidden when displayed as a column of a table, either an object's * collection or a standalone list. This combines `PARENTED_TABLES` and `STANDALONE_TABLES`.
-
-* `Where.NOWHERE` +
-+
-The property should not be hidden, overriding any other metadata/conventions that would normally cause the property to be hidden. +
-
-For example, if a property is annotated with xref:_ug_reference-annotations_manpage-Title[`@Title`], then normally this should be hidden from all
-tables. Annotating with `@Property(where=Where.NOWHERE)` overrides this.
-
-
-[NOTE]
-====
-The xref:_ug_restfulobjects-viewer[RestfulObjects viewer] has only partial support for these `Where` enums.
-====
-
-
-As an alternative to using the annotation, the dynamic xref:_ug_reference-object-layout_dynamic[`.layout.json`]
-can be used instead, eg:
-
-[source,javascript]
-----
-"internalId": {
- "propertyLayout": { "hidden": "ALL_TABLES" }
-}
-----
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout_labelPosition.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout_labelPosition.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout_labelPosition.adoc
deleted file mode 100644
index d0c31f1..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout_labelPosition.adoc
+++ /dev/null
@@ -1,96 +0,0 @@
-[[_ug_reference-annotations_manpage-PropertyLayout_labelPosition]]
-= `labelPosition()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `labelPosition()` attribute determines the positioning of labels for properties. This attribute can also be specified for xref:_ug_reference-annotations_manpage-ParameterLayout_labelPosition[parameters].
-
-The positioning of labels is typically `LEFT`, but can be positioned to the `TOP`. The one exception is xref:_ug_reference-annotations_manpage-ParameterLayout_multiLine[`multiLine()`] string properties, where the label defaults to `TOP` automatically (to provide as much real-estate for the multiline text field as possible).
-
-For boolean properties a positioning of `RIGHT` is also allowed; this is ignored for all other types.
-
-It is also possible to suppress the label altogether, using `NONE`.
-
-For example:
-
-[source,java]
-----
-public class ToDoItem {
- @PropertyLayout(
- labelPosition=LabelPosition.TOP
- )
- public String getDescription() { ... }
- public void setDescription(String description) { ... }
- ...
-}
-----
-
-
-To get an idea of how these are rendered (in the xref:_ug_wicket-viewer[Wicket viewer]), we can look at the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] that happens to have examples of most of these various label positions.
-
-The default `LEFT` label positioning is used by the `cost` property:
-
-image::{_imagesdir}reference-annotations/PropertyLayout/labelPosition-LEFT.png[width="720px",link="{_imagesdir}reference-annotations/PropertyLayout/labelPosition-LEFT.png"]
-
-
-The `TOP` label positioning is used by the `category` property:
-
-image::{_imagesdir}reference-annotations/PropertyLayout/labelPosition-TOP.png[width="720px",link="{_imagesdir}reference-annotations/PropertyLayout/labelPosition-TOP.png"]
-
-
-Labels are suppressed, using `NONE`, for the `subcategory` property:
-
-image::{_imagesdir}reference-annotations/PropertyLayout/labelPosition-NONE.png[width="720px",link="{_imagesdir}reference-annotations/PropertyLayout/labelPosition-NONE.png"]
-
-
-The todoapp's `complete` (boolean) property renders the label to the LEFT (the default):
-
-image::{_imagesdir}reference-annotations/PropertyLayout/labelPosition-boolean-LEFT.png[width="720px",link="{_imagesdir}reference-annotations/PropertyLayout/labelPosition-boolean-LEFT.png"]
-
-Moving the label to the `RIGHT` looks like:
-
-image::{_imagesdir}reference-annotations/PropertyLayout/labelPosition-boolean-RIGHT.png[width="720px",link="{_imagesdir}reference-annotations/PropertyLayout/labelPosition-boolean-RIGHT.png"]
-
-
-
-
-As an alternative to using the annotation, the dynamic xref:_ug_reference-object-layout_dynamic[`.layout.json`]
-can be used instead, eg:
-
-[source,javascript]
-----
-"description": {
- "propertyLayout": {
- "labelPosition": "TOP"
- }
-}
-----
-
-
-
-[TIP]
-.Specifying a default setting for label positions
-====
-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:_ug_runtime_configuring-core[configuration property] in `isis.properties`:
-
-[source,ini]
-----
-isis.viewers.propertyLayout.labelPosition=TOP
-----
-
-or
-
-[source,ini]
-----
-isis.viewers.propertyLayout.labelPosition=LEFT
-----
-
-If these are not present then 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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout_multiLine.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout_multiLine.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout_multiLine.adoc
deleted file mode 100644
index cb89a01..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout_multiLine.adoc
+++ /dev/null
@@ -1,44 +0,0 @@
-[[_ug_reference-annotations_manpage-PropertyLayout_multiLine]]
-= `multiLine()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `multiLine()` attribute specifies that the text field for a string property should span multiple lines. It is ignored for other property types. The attribute is also supported for xref:_ug_reference-annotations_manpage-ParameterLayout_multiLine[parameters].
-
-For example:
-
-[source,java]
-----
-public class BugReport {
- @PropertyLayout(
- numberOfLines=10
- )
- public String getStepsToReproduce() { ... }
- public void setStepsToReproduce(String stepsToReproduce) { ... }
- ...
-}
-----
-
-Here the `stepsToReproduce` will be displayed in a text area of 10 rows.
-
-
-
-As an alternative to using the annotation, the dynamic xref:_ug_reference-object-layout_dynamic[`.layout.json`]
-can be used instead, eg:
-
-[source,javascript]
-----
-"stepsToReproduce": {
- "propertyLayout": {
- "numberOfLines": 10
- }
-}
-----
-
-
-[NOTE]
-====
-If set > 1 (as would normally be the case), then the default xref:_ug_reference-annotations_manpage-PropertyLayout_labelPosition[`labelPosition`] defaults to `TOP` (rather than `LEFT`, as would normally be the case).
-====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout_named.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout_named.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout_named.adoc
deleted file mode 100644
index 1a0b556..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout_named.adoc
+++ /dev/null
@@ -1,51 +0,0 @@
-[[_ug_reference-annotations_manpage-PropertyLayout_named]]
-= named()
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `named()` attribute explicitly specifies the property's name, overriding the name that would normally be inferred from the Java source code. This attribute can also be specified for xref:_ug_reference-annotations_manpage-ActionLayout_named[actions], xref:_ug_reference-annotations_manpage-CollectionLayout_named[collections], xref:_ug_reference-annotations_manpage-ParameterLayout_named[parameters], xref:_ug_reference-annotations_manpage-DomainObjectLayout_named[domain objects], xref:_ug_reference-annotations_manpage-ViewModelLayout_named[view models] and xref:_ug_reference-annotations_manpage-DomainServiceLayout_named[domain services].
-
-[TIP]
-====
-Following the link:http://en.wikipedia.org/wiki/Don%27t_repeat_yourself[don't repeat yourself] principle, we recommend that you only use this attribute when the desired name cannot be used in Java source code. Examples of that include a name that would be a reserved Java keyword (eg "package"), or a name that has punctuation, eg apostrophes.
-====
-
-
-By default the name is HTML escaped. To allow HTML markup, set the related `namedEscaped()` attribute to `false`.
-
-For example:
-
-[source,java]
-----
-public class ToDoItem {
- @PropertyLayout(
- named="Description of this <i>item</i>",
- namedEscaped=false
- )
- public String getDescription() { ... }
- ...
-}
-----
-
-
-
-As an alternative to using the annotation, the dynamic xref:_ug_reference-object-layout_dynamic[`.layout.json`]
-can be used instead, eg:
-
-[source,javascript]
-----
-"description": {
- "propertyLayout": {
- "named": "Description of this <i>item</i>",
- "namedEscaped": false
- }
-}
-----
-
-
-[TIP]
-====
-The framework also provides a separate, powerful mechanism for xref:_ug_more-advanced_i18n[internationalization].
-====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout_renderedAsDayBefore.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout_renderedAsDayBefore.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout_renderedAsDayBefore.adoc
deleted file mode 100644
index 2510d01..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout_renderedAsDayBefore.adoc
+++ /dev/null
@@ -1,45 +0,0 @@
-[[_ug_reference-annotations_manpage-PropertyLayout_renderedAsDayBefore]]
-= `renderedAsDayBefore()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `renderedAsDayBefore()` attribute applies only to date properties whereby the date will be rendered as the day before the value actually held in the domain object. It is ignored for properties of other types. This attribute is also supported for xref:_ug_reference-annotations_manpage-ParameterLayout_renderedAsDayBefore[parameters].
-
-This behaviour might at first glance appear odd, but the rationale is to support the use case of a sequence of instances that represent adjacent intervals of time. In such cases there would typically be `startDate` and `endDate` properties, eg for all of Q2. Storing this as a half-closed interval -- eg `[1-Apr-2015, 1-July-2015)` -- can substantially simplify internal algorithms; the `endDate` of one interval will correspond to the `startDate` of the next.
-
-However, from an end-user perspective the requirement may be to render the interval as a fully closed interval; eg the end date should be shown as `30-Jun-2015`.
-
-This attribute therefore bridges the gap; it presents the information in a way that makes sense to an end-user, but also stores the domain object in a way that is easy work with internally.
-
-For example:
-
-[source,java]
-----
-public class Tenancy {
- public LocalDate getStartDate() { ... }
- public void setStartDate(LocalDate startDate) { ... }
- @PropertyLayout(
- renderedAsDayBefore=true
- )
- public LocalDate getEndDate() { ... }
- public void setEndDate(LocalDate EndDate) { ... }
- ...
-}
-----
-
-
-
-As an alternative to using the annotation, the dynamic xref:_ug_reference-object-layout_dynamic[`.layout.json`]
-can be used instead, eg:
-
-[source,javascript]
-----
-"endDate": {
- "propertyLayout": {
- "renderedAsDayBefore": true
- }
-}
-----
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout_typicalLength.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout_typicalLength.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout_typicalLength.adoc
deleted file mode 100644
index e0235a0..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-PropertyLayout_typicalLength.adoc
+++ /dev/null
@@ -1,25 +0,0 @@
-[[_ug_reference-annotations_manpage-PropertyLayout_typicalLength]]
-= `typicalLength()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `typicalLength()` attribute indicates the typical length of a string property. It is ignored for properties of other types. The attribute is also supported for xref:_ug_reference-annotations_manpage-ParameterLayout_typicalLength[parameters].
-
-The information is intended as a hint to the UI to determine the space that should be given to render a particular string property. That said, note that the xref:_ug_wicket-viewer[Wicket viewer] uses the maximum space available for all fields, so in effect ignores this attribute.
-
-For example:
-
-[source,java]
-----
-public class Customer {
- @javax.jdo.annotations.Column(length=30)
- @ParameterLayout(typicalLength=20)
- public String getFirstName() { ... }
- public void setFirstName(String firstName) { ... }
- ...
-}
-----
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_domainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_domainEvent.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_domainEvent.adoc
deleted file mode 100644
index bc87edc..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_domainEvent.adoc
+++ /dev/null
@@ -1,150 +0,0 @@
-[[_ug_reference-annotations_manpage-Property_domainEvent]]
-= `domainEvent()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-Whenever a domain object (or list of domain objects) is to be rendered, the framework fires off multiple domain events for every property, collection and action of the domain object. In the cases of the domain object's properties, the events that are fired are:
-
-* hide phase: to check that the property is visible (has not been hidden)
-* disable phase: to check that the property is usable (has not been disabled)
-* validate phase: to check that the property's arguments are valid (to modify/clear its value)
-* pre-execute phase: before the modification of the property
-* post-execute: after the modification of the property
-
-Subscribers subscribe through the xref:_ug_reference-services-api_manpage-EventBusService[`EventBusService`] using either link:https://github.com/google/guava[Guava] or link:http://www.axonframework.org/[Axon Framework] annotations and can influence each of these phases.
-
-By default the event raised is `PropertyDomainEvent.Default`. For example:
-
-[source,java]
-----
-public class ToDoItem {
- @Property()
- public LocalDate getDueBy() { ... }
- ...
-}
-----
-
-The purpose of the `domainEvent()` attribute is to allows a custom subclass to be emitted instead. This attribute is also supported for xref:_ug_reference-annotations_manpage-Action_domainEvent[actions] and xref:_ug_reference-annotations_manpage-Property_domainEvent[properties].
-
-
-For example:
-
-[source,java]
-----
-public class ToDoItem {
- public static class DueByChangedEvent extends PropertyDomainEvent<ToDoItem, LocalDate> { // <1>
- private static final long serialVersionUID = 1L;
- public DueByChangedEvent( // <2>
- ToDoItem source, // <3>
- Identifier identifier, // <4>
- LocalDate oldValue, // <5>
- LocalDate newValue) { // <6>
- super(source, identifier, oldValue, newValue);
- }
- }
- @Property(domainEvent=ToDoItem.DueByChangedEvent)
- public LocalDate getDueBy() { ... }
- ...
-}
-----
-<1> inherit from `PropertyDomainEvent<T,P>` where `T` is the type of the domain object being interacted with, and `P` is the type of the property (`LocalDate` in this example)
-<2> constructor called reflectively by the framework
-<3> populated with the object being interacted with (the source of the event)
-<4> identifier of the property
-<5> current value of the property
-<6> proposed new value for the property; if being cleared then will be `null`.
-
-The benefit is that subscribers can be more targetted as to the events that they subscribe to.
-
-
-
-
-== Subscribers
-
-Subscribers (which must be domain services) subscribe using either the link:https://github.com/google/guava[Guava] API or (if the xref:_ug_reference-services-api_manpage-EventBusService[`EventBusService`] has been appropriately configured) using the link:http://www.axonframework.org/[Axon Framework] API. The examples below use the Guava API.
-
-Subscribers can be either coarse-grained (if they subscribe to the top-level event type):
-
-[source,java]
-----
-@DomainService
-public class SomeSubscriber {
-
- @Programmatic
- @com.google.common.eventbus.Subscribe
- public void on(PropertyInteractionEvent ev) {
-
- ...
- }
-
-}
-----
-
-or can be fine-grained (by subscribing to specific event subtypes):
-
-[source,java]
-----
-@DomainService
-public class SomeSubscriber {
-
- @Programmatic
- @com.google.common.eventbus.Subscribe
- public void on(ToDoItem.DueByChangedEvent ev) {
-
- ...
- }
-
-}
-----
-
-[TIP]
-====
-If the AxonFramework is being used, replace `@com.google.common.eventbus.Subscribe` with `@org.axonframework.eventhandling.annotation.EventHandler`.
-====
-
-The subscriber's method is called (up to) 5 times:
-
-* whether to veto visibility (hide)
-* whether to veto usability (disable)
-* whether to veto execution (validate)
-* steps to perform prior to the property being modified
-* steps to perform after the property has been modified.
-
-The subscriber can distinguish these by calling `ev.getPhase()`. Thus the general form is:
-
-[source,java]
-----
-@Programmatic
-@com.google.common.eventbus.Subscribe
-public void on(PropertyDomainEvent ev) {
- switch(ev.getPhase()) {
- case HIDE:
- // call ev.hide() or ev.veto("") to hide the property
- break;
- case DISABLE:
- // call ev.disable("...") or ev.veto("...") to disable the property
- break;
- case VALIDATE:
- // call ev.invalidate("...") or ev.veto("...")
- // if proposed property value is invalid
- break;
- case EXECUTING:
- break;
- case EXECUTED:
- break;
- }
-}
-----
-
-It is also possible to abort the transaction during the executing or executed phases by throwing an exception. If the exception is a subtype of `RecoverableException` then the exception will be rendered as a user-friendly warning (eg Growl/toast) rather than an error.
-
-
-
-
-== Raising events programmatically
-
-Normally events are only raised for interactions through the UI. However, events can be raised programmatically by
-wrapping the target object using the xref:_ug_reference-services-api_manpage-WrapperFactory[`WrapperFactory`] service.
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_editing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_editing.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_editing.adoc
deleted file mode 100644
index b16839d..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Property_editing.adoc
+++ /dev/null
@@ -1,43 +0,0 @@
-[[_ug_reference-annotations_manpage-Property_editing]]
-= `editing()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `editing()` attribute can be used to prevent a property from being modified or cleared, ie to make it read-only. This attribute can also be specified for xref:_ug_reference-annotations_manpage-Collection_editing[collections], and can also be specified for the xref:_ug_reference-annotations_manpage-DomainObject_editing[domain object].
-
-The related `editingDisabledReason()` attribute specifies the a hard-coded reason why the property cannot be modified directly.
-
-Whether a property is enabled or disabled depends upon these factors:
-
-* whether the domain object has been configured as immutable through the xref:_ug_reference-annotations_manpage-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:_ug_runtime_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
-
-* else, the result of invoking any supporting xref:_ug_reference-methods_prefixes_manpage-disable[`disable...()`] supporting methods
-
-
-Thus, to make a property read-only even if the object would otherwise be editable, use:
-
-[source,java]
-----
-public class Customer {
- @Property(
- editing=Editing.DISABLED,
- editingDisabledReason="The credit rating is derived from multiple factors"
- )
- public int getInitialCreditRating(){ ... }
- public void setInitialCreditRating(int initialCreditRating) { ... }
-}
-----
-
-[NOTE]
-====
-To reiterate, it is _not_ possible to enable editing for a property if editing has been disabled at the object-level.
-====
-
-
-
[33/45] isis git commit: ISIS-1133: breaking out reference guide and
devenv guide;
moving appendices' release notes and migration notes to other docs;
improving the documentation page.
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-UserProfileService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-UserProfileService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-UserProfileService.adoc
new file mode 100644
index 0000000..3850741
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-UserProfileService.adoc
@@ -0,0 +1,44 @@
+[[_rg_services-spi_manpage-UserProfileService]]
+= `UserProfileService`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `UserProfileService` provides the ability for the domain application to return supplementary metadata about the current user. This information is used (by the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer]) to customize the appearance of the tertiary "Me" menu bar (top right). For example, rather than display the username, instead the user's first and last name could be displayed.
+
+Another use case is to allow the user to switch context in some fashion or other. This might be to emulate a sort of "sudo"-like function, or perhaps to focus on some particular set of data.
+
+
+
+== SPI
+
+The SPI defined by the service is:
+
+[source,java]
+----
+public interface UserProfileService {
+ @Programmatic
+ String userProfileName(); // <1>
+}
+----
+<1> is used (in the Wicket viewer) as the menu name of the tertiary "Me" menu bar.
+
+If the method returns `null` or throws an exception then the framework will default to using the current user name.
+
+In the future this API may be expanded; one obvious possibility is to return a profile photo or avatar URL.
+
+
+
+== Implementation
+
+The (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] has a simple implementation of this service:
+
+image::{_imagesdir}reference-services-spi/UserProfileService/todoapp.png[width="800px",link="{_imagesdir}reference-services-spi/UserProfileService/todoapp.png"]
+
+
+[NOTE]
+====
+Currently this feature is not integrated with Isis' authentication mechanisms; the information provided is purely metadata provided for presentation purposes only.
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-UserRegistrationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-UserRegistrationService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-UserRegistrationService.adoc
new file mode 100644
index 0000000..83aa0ff
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-UserRegistrationService.adoc
@@ -0,0 +1,81 @@
+[[_rg_services-spi_manpage-UserRegistrationService]]
+= `UserRegistrationService`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `UserRegistrationService` provides the ability for users to sign-up to access an application by providing a valid email address, and also provides the capability for users to reset their password if forgotten.
+
+For user sign-up, the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] will check whether an implementation of this service (and also the xref:rg.adoc#_rg_services-spi_manpage-EmailNotificationService[`EmailNotificationService`]) is available, and if so will render a sign-up page where the user enters their email address. A verification email is sent (using the aforementioned `EmailNotificationService`) which includes a link back to the running application; this allows the user then to complete their registration process (choose user name, password and so on). When the user has provided the additional details, the Wicket viewer calls _this_ service in order to create an account for them, and then logs the user on.
+
+For the password reset feature, the Wicket viewer will render a password reset page, and use the `EmailNotificationService` to send a "password forgotten" email. This service provides the ability to reset a password based on the user's email address.
+
+It is of course possible for domain objects to use this service; it will be injected into domain object or other domain services in the usual way. That said, we expect that such use cases will be comparatively rare; the primary use case is for the Wicket viewer's sign-up page.
+
+[NOTE]
+====
+For further details on the user registration feature (as supported by the Wicket viewer), see xref:ug.adoc#_ug_wicket-viewer_features_user-registration[here].
+====
+
+
+
+== SPI
+
+The SPI defined by the service is:
+
+[source,java]
+----
+public interface UserRegistrationService {
+ @Programmatic
+ boolean usernameExists(String username); // <1>
+ @Programmatic
+ boolean emailExists(String emailAddress); // <2>
+ @Programmatic
+ void registerUser(String username, String password, String emailAddress); // <3>
+ @Programmatic
+ boolean updatePasswordByEmail(String emailAddress, String password); // <4>
+}
+----
+<1> checks if there is already a user with the specified username
+<2> checks if there is already a user with the specified email address
+<3> creates the user, with specified password and email address. The username and email address must both be unique (not being used by an existing user)
+<4> allows the user to reset their password
+
+
+
+
+== Implementation
+
+The core Isis framework itself defines only an API; there is no default implementation. Rather, the implementation will depend on the security mechanism being used.
+
+That said, if you have configured your app to use the http://github.com/isisaddons/isis-module-security[Isis addons security module], then note that the security module does provide an abstract implementation (`SecurityModuleAppUserRegistrationServiceAbstract`) of the `UserRegistrationService`. You will need to extend that service and provide implementation for the two abstract methods: `getInitialRole()` and `getAdditionalInitialRoles()`.
+
+This is needed so that the self-registered users are assigned automatically to your application role(s) and be able to use the application. Without any role such user will be able only to see/use the logout link of the application.
+
+
+
+
+== Registering the Services
+
+Assuming that the `configuration-and-annotation` services installer is configured:
+
+[source,ini]
+----
+isis.services-installer=configuration-and-annotation
+----
+
+then (if using the (non-ASF) http://github.com/isisaddons/isis-module-security[Isis addons' security] module) you will need to register your concrete implementation of `SecurityModuleAppUserRegistrationServiceAbstract`.
+
+
+
+
+== Related Services
+
+The most common use case is to allow users to sign-up through Isis' Wicket viewer. Because the process requires email to be sent, the following services must be configured:
+
+* xref:rg.adoc#_rg_services-api_manpage-EmailService[`EmailService`]
+* xref:rg.adoc#_rg_services-spi_manpage-EmailNotificationService[`EmailNotificationService`]
+* `UserRegistrationService` (this service)
+
+The `EmailService` in particular requires additional xref:ug.adoc#_ug_runtime_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/9c5dafab/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
new file mode 100644
index 0000000..f7b255c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts.adoc
@@ -0,0 +1,22 @@
+[[_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/9c5dafab/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
new file mode 100644
index 0000000..83777e3
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_add-ons.adoc
@@ -0,0 +1,35 @@
+[[_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 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 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/9c5dafab/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
new file mode 100644
index 0000000..80e045d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_building-blocks.adoc
@@ -0,0 +1,93 @@
+[[_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/
+
+IMPORTANT: TODO
+
+## A MetaModel with Explicit and Inferred Semantics
+
+IMPORTANT: TODO
+
+* use of annotations
+** reuse JEE annotations where possible
+* layout hints are overridable, to avoid restarting the app/speed up feedback
+
+
+## Domain Objects and Domain Services
+
+IMPORTANT: TODO
+
+* domain model
+** domain objects
+*** domain entity
+*** view model
+** domain service
+** value type
+
+Anything else can be (should be) ignored by annotating with `@Programmatic`.
+
+
+
+## Properties, Collections and Actions
+
+IMPORTANT: TODO
+
+
+## Domain Entities vs View Models
+
+IMPORTANT: TODO
+
+`@DomainObject(nature=...)`
+
+
+
+## Domain Services
+
+Domain services consist of a set of logically grouped actions, and as such follow the same conventions as for entities. However, a service cannot have (persisted) properties, nor can it have (persisted) collections.
+
+Domain services are instantiated once and once only by the framework, and are used to centralize any domain logic that does not logically belong in a domain entity or value. Isis will automatically inject services into every domain entity that requests them, and into each other.
+
+For convenience you can inherit from AbstractService or one of its subclasses, but this is not mandatory.
+
+
+### Domain Services vs View Services
+
+IMPORTANT: 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.
+****
+
+
+
+
+## Value Objects (Primitives)
+
+IMPORTANT: TODO
+
+
+
+## Contributions
+
+IMPORTANT: TODO
+
+
+
+
+## Event Bus
+
+IMPORTANT: TODO
+
+
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..719a234
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_framework-provided-services.adoc
@@ -0,0 +1,54 @@
+[[_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:rg.adoc#_rg_services-api_manpage-DomainObjectContainer[`DomainObjectContainer`]
+* xref:rg.adoc#_rg_services-api_manpage-ClockService[`ClockService`]
+* xref:rg.adoc#_rg_services-api_manpage-IsisSupportJdo[`IsisSupportJdo`]
+* xref:rg.adoc#_rg_services-api_manpage-WrapperFactory[`WrapperFactory`]
+* xref:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`]
+* xref:rg.adoc#_rg_services-api_manpage-EmailService[`EmailService`]
+
+Commands/Background/Auditing:
+
+* xref:rg.adoc#_rg_services-api_manpage-CommandContext[`CommandContext`] (SPI)
+* xref:rg.adoc#_rg_services-spi_manpage-CommandService[`CommandService`] (SPI)
+* xref:rg.adoc#_rg_services-spi_manpage-AuditingService[`AuditingService`] (SPI)
+* xref:rg.adoc#_rg_services-api_manpage-BackgroundService[`BackgroundService`]
+* xref:rg.adoc#_rg_services-spi_manpage-BackgroundCommandService[`BackgroundCommandService`] (SPI)
+* xref:rg.adoc#_rg_services-spi_manpage-PublishingService[`PublishingService`] (SPI)
+
+Information Sharing:
+
+* xref:rg.adoc#_rg_services-api_manpage-ScratchPad[`ScratchPad`]
+* xref:rg.adoc#_rg_services-api_manpage-ActionInvocationContext[`ActionInvocationContext`]
+* xref:rg.adoc#_rg_services-api_manpage-QueryResultsCache[`QueryResultsCache`]
+
+
+UserManagement:
+
+* xref:rg.adoc#_rg_services-spi_manpage-UserProfileService[`UserProfileService`] (SPI)
+* xref:rg.adoc#_rg_services-spi_manpage-UserRegistrationService[`UserRegistrationService`] (SPI)
+* xref:rg.adoc#_rg_services-spi_manpage-EmailNotificationService[`EmailNotificationService`] (SPI)
+
+
+Bookmarks and Mementos:
+
+* xref:rg.adoc#_rg_services-api_manpage-BookmarkService[`BookmarkService`]
+* xref:rg.adoc#_rg_services-api_manpage-MementoService[`MementoService`]
+* xref:rg.adoc#_rg_services-api_manpage-DeepLinkService[`DeepLinkService`]
+* xref:rg.adoc#_rg_services-api_manpage-XmlSnapshotService[`XmlSnapshotService`]
+
+
+A full list of services can be found in the xref:rg.adoc#_rg_services-api[Domain Services (API)] and xref:rg.adoc#_rg_services-spi[Domain Services (SPI)] chapters of the reference guide.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..2b671b5
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_other-deployment-options.adoc
@@ -0,0 +1,81 @@
+[[_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 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 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 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 Isis, there can be a lot of value in using 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 teamEnum (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 Isis deliberately minimizes the dependencies on the rest of the framework. In fact, the only hard dependency that the domain model classes have on Isis is through the `org.apache.isis.applib` classes, mostly to pick up annotations such as `@Disabled`.
+So, if you have used 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; 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 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 Isis provides "out-of-the-box" (eg xref:rg.adoc#_rg_services-api_manpage-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. Isis' <<_restfulobjects_viewer, Restful Objects viewer] is an implementation of that spec, making any 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 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 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/9c5dafab/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
new file mode 100644
index 0000000..b31b507
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy.adoc
@@ -0,0 +1,21 @@
+[[_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/9c5dafab/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
new file mode 100644
index 0000000..7e3b0a2
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_aop.adoc
@@ -0,0 +1,36 @@
+[[_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; and many tend to think of xref:ug.adoc#_ug_core-concepts_philosophy_domain-driven-design,DDD>> as an updated treatise on good object modelling[in the same vein as Rebecca Wirf Brock's link:http://en.wikipedia.org/wiki/Responsibility-driven_design[Responsibility Driven Design], say. Meanwhile the <<_naked_objects_pattern, naked objects pattern] very much comes from an OO background (it even has 'object' in its name); and 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 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:ug.adoc#_ug_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. 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 s
ection, 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 Isis' AOP support for mixins (xref:ug.adoc#_ug_more-advanced_decoupling_contributions[contributions]) and interceptors (the xref:ug.adoc#_ug_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/9c5dafab/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
new file mode 100644
index 0000000..1e4c916
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_dci.adoc
@@ -0,0 +1,9 @@
+[[_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/
+
+
+IMPORTANT: TODO ... Trygve Reenskaug
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..764df57
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_domain-driven-design.adoc
@@ -0,0 +1,80 @@
+[[_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/
+
+This section describes some of the core ideas and architectural patterns upon which Apache Isis builds.
+
+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.
+
+== 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 again be thinking of design documents and design diagrams. 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/9c5dafab/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
new file mode 100644
index 0000000..7e33166
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_hexagonal-architecture.adoc
@@ -0,0 +1,29 @@
+[[_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*. Isis' viewers act as user-side adapters and use the 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 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/9c5dafab/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
new file mode 100644
index 0000000..95637bd
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_how-eases-ddd.adoc
@@ -0,0 +1,74 @@
+[[_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 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.
+
+
+
+== Abstract models are difficult to represent
+
+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.
+
+
+
+
+== Layered architectures are easily compromised
+
+_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. 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/9c5dafab/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
new file mode 100644
index 0000000..e870754
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_naked-objects-pattern.adoc
@@ -0,0 +1,60 @@
+[[_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 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/9c5dafab/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
new file mode 100644
index 0000000..96b6fac
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping.adoc
@@ -0,0 +1,18 @@
+[[_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/9c5dafab/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
new file mode 100644
index 0000000..da52685
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles.adoc
@@ -0,0 +1,16 @@
+[[_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/9c5dafab/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
new file mode 100644
index 0000000..cb4bcda
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs.adoc
@@ -0,0 +1,36 @@
+[[_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]
+
+
+
+== vs CQRS
+
+IMPORTANT: TODO
+
+== vs Event Sourcing
+
+IMPORTANT: TODO
+
+
+== vs Angular
+
+IMPORTANT: TODO
+
+
+
+include::_ug_core-concepts_principles_apache-isis-vs_metawidget.adoc[leveloffset=+1]
+
+
+
+== vs OpenXava
+
+IMPORTANT: TODO
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..30adc9f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_metawidget.adoc
@@ -0,0 +1,16 @@
+[[_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:ug.adoc#_ug_restfulobjects-viewer[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 Isis' own metamodel as an implementation of the MetaWidget API. This would allow MetaWidget to be able to render an Isis domain application.
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..a873888
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_mvc-server-side-frameworks.adoc
@@ -0,0 +1,19 @@
+[[_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:ug.adoc#_ug_extending_wicket-viewer[extending Isis' Wicket viewer] or by writing a bespoke UI leveraging the REST (hypermedia) API automatically exposed by xref:ug.adoc#_ug_restfulobjects-viewer[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 Isis' REST API.
+
+Although these frameworks all provide their own ecosystems of extensions, 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. Isis' support is similar. Where Isis differs though is that it enables end-to-end testing without the need for slow and fragile Selenium tests. Instead, Isis provides a "xref:ug.adoc#_ug_testing_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/9c5dafab/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
new file mode 100644
index 0000000..8997d46
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_isis-itself.adoc
@@ -0,0 +1,47 @@
+[[_ug_core-concepts_principles_isis-itself]]
+= 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
+
+IMPORTANT: TODO
+
+
+== Focuses on its USP
+
+IMPORTANT: TODO
+
+
+add-ons
+
+* 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 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
+
[35/45] isis git commit: ISIS-1133: breaking out reference guide and
devenv guide;
moving appendices' release notes and migration notes to other docs;
improving the documentation page.
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-EventBusService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-EventBusService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-EventBusService.adoc
new file mode 100644
index 0000000..eccd7c7
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-EventBusService.adoc
@@ -0,0 +1,381 @@
+[[_rg_services-api_manpage-EventBusService]]
+= `EventBusService`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `EventBusService` allows domain objects to emit events to subscribing domain services using an in-memory event bus.
+
+The primary user of the service is the framework itself, which automatically emit events for xref:rg.adoc#_rg_annotations_manpage-Action_domainEvent[actions], xref:rg.adoc#_rg_annotations_manpage-Property_domainEvent[properties] and xref:rg.adoc#_rg_annotations_manpage-Collection_domainEvent[collections]. Multiple events are generated:
+
+* when an object member is to be viewed, an event is fired; subscribers can veto (meaning that the member is hidden)
+* when an object member is to be enabled, the same event instance is fired; subscribers can veto (meaning that the member is disabled, ie cannot be edited/invoked)
+* when an object member is being validated, then a new event instance is fired; subscribers can veto (meaning that the candidate values/action arguments are rejected)
+* when an object member is about to be changed, then the same event instance is fired; subscribers can perform pre-execution operations
+* when an object member has been changed, then the same event instance is fired; subscribers can perform post-execution operations
+
+If a subscriber throws an exception in the first three steps, then the interaction is vetoed. If a subscriber throws an exception in the last two steps, then the transaction is aborted. For more on this topic, see xref:rg.adoc#_rg_annotations_manpage-Action_domainEvent[`@Action#domainEvent()`], xref:rg.adoc#_rg_annotations_manpage-Property_domainEvent[`@Property#domainEvent()`] and xref:rg.adoc#_rg_annotations_manpage-Collection_domainEvent[`@Collection#domainEvent()`].
+
+It is also possible for domain objects to programmatically generate domain events. However the events are published, the primary use case is to decoupling interactions from one module/package/namespace and another.
+
+Two implementations are available, using either link:https://code.google.com/p/guava-libraries/[Guava]'s https://code.google.com/p/guava-libraries/wiki/EventBusExplained[`EventBus`], or alternatively using the link:http://www.axonframework.org/[AxonFramework]'s link:http://www.axonframework.org/docs/2.4/single.html#d5e1489[SimpleEventBus]. It is also possible to plug in a custom implementation.
+
+
+
+[[_rg_services-api_manpage-EventBusService_api-and-implementation]]
+== API & Implementation
+
+The API defined by `EventBusService` is:
+
+[source,java]
+----
+public abstract class EventBusService {
+ @Programmatic
+ public void post(Object event) { ... } // <1>
+ @Programmatic
+ public void register(final Object domainService) { ... } // <2>
+ @Programmatic
+ public void unregister(final Object domainService) { ... } // <3>
+}
+----
+<1> posts the event onto event bus
+<2> allows domain services to register themselves. This should be done in their xref:rg.adoc#_rg_annotations_manpage-PostConstruct[`@PostConstruct`] initialization method (for both singleton and xref:rg.adoc#_rg_annotations_manpage-RequestScoped[`@RequestScoped`] domain services.
+<3> exists for symmetry, but need never be called (it is in fact deliberately a no-op).
+
+Isis provides a default implementation of the service, `o.a.i.objectstore.jdo.datanucleus.service.eventbus.EventBusServiceJdo`.
+
+
+
+
+
+== Registering Subscribers
+
+The `register()` method should be called in the xref:rg.adoc#_rg_annotations_manpage-PostConstruct[`@PostConstruct`] lifecycle method. It is valid and probably the least confusing to readers to also "unregister" in the xref:rg.adoc#_rg_annotations_manpage-PreDestroy[`@PreDestroy`] lifecycle method (though as noted xref:rg.adoc#_rg_services-api_manpage-EventBusService_api-and-implementation[above], unregistering is actually a no-op).
+
+For example:
+
+[source,java]
+----
+@DomainService(nature=NatureOfService.DOMAIN)
+public class MySubscribingDomainService {
+ @PostConstruct
+ public void postConstruct() {
+ eventBusService.register(this);
+ }
+ @PreDestroy
+ public void preDestroy() {
+ eventBusService.unregister(this);
+ }
+ ...
+ @javax.inject.Inject
+ EventBusService eventBusService;
+}
+----
+
+This works for both singleton (application-scoped) and also xref:rg.adoc#_rg_annotations_manpage-RequestScoped[`@RequestScoped`] domain services.
+
+
+
+
+
+== Annotating Members
+
+As discussed in the introduction, the framework will automatically emit domain events for all of the object members (actions, properties or collections) of an object whenever that object is rendered or (more generally) interacted with.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ @Action
+ public Customer placeOrder(Product product, @ParameterLayout(named="Quantity") int qty) { ... }
+ ...
+}
+----
+
+will propagate an instance of the default `o.a.i.applib.services.eventbus.ActionDomainEvent.Default` class. If using the Guava event bus this can be subscribed to using:
+
+[source,java]
+----
+@DomainService(nature=NatureOfService.DOMAIN)
+public class MySubscribingDomainService
+ @Programmatic
+ @com.google.common.eventbus.Subscribe
+ public void on(ActionDomainEvent ev) { ... }
+ ...
+}
+----
+
+or if using Axonframework, the subscriber uses a different annotation:
+
+[source,java]
+----
+@DomainService(nature=NatureOfService.DOMAIN)
+public class MySubscribingDomainService
+ @Programmatic
+ @org.axonframework.eventhandling.annotation.EventHandle
+ public void on(ActionDomainEvent ev) { ... }
+ ...
+}
+----
+
+More commonly though you will probably want to emit domain events of a specific subtype. As a slightly more interesting example, suppose in a library domain that a `LibraryMember` wants to leave the library. A letter should be sent out detailing any books that they still have out on loan:
+
+In the `LibraryMember` class, we publish the event by way of an annotation:
+
+[source,java]
+----
+public class LibraryMember {
+ @Action(domainEvent=LibraryMemberLeaveEvent.class) // <1>
+ public void leave() { ... }
+ ...
+}
+----
+<1> `LibraryMemberLeaveEvent` is a subclass of `o.a.i.applib.eventbus.ActionDomainEvent`. The topic of subclassing is discussed in more detail xref:rg.adoc#_rg_services-api_manpage-EventBusService_event-hierarchy[below].
+
+Meanwhile, in the `BookRepository` domain service, we subscribe to the event and act upon it. For example:
+
+[source,java]
+----
+public class BookRepository {
+ @Programmatic
+ @com.google.common.eventbus.Subscribe
+ public void onLibraryMemberLeaving(LibraryMemberLeaveEvent e) {
+ LibraryMember lm = e.getLibraryMember();
+ List<Book> lentBooks = findBooksOnLoanFor(lm);
+ if(!lentBooks.isEmpty()) {
+ sendLetter(lm, lentBooks);
+ }
+ }
+ ...
+}
+----
+
+This design allows the `libraryMember` module to be decoupled from the `book` module.
+
+
+
+[[_rg_services-api_manpage-EventBusService_event-hierarchy]]
+== Event hierarchy
+
+By creating domain event subtypes we can be more semantically precise and in turn providesmore flexibility for subscribers: they can choose whether to be broadly applicable (by subscribing to a superclass) or to be tightly focussed (by subscribing to a subclass).
+
+We recommend that you define event classes at (up to) four scopes:
+
+* at the top "global" scope is the Isis-defined `o.a.i.applib.event.ActionDomainEvent`
+* for the "module" scope, create a static class to represent the module itself, and creating nested classes within
+* for each "class" scope, create a nested static event class in the domain object's class for all of the domain object's actions
+* for each "action" scope, create a nested static event class for that action, inheriting from the "domain object" class.
+
+To put all that into code; at the module level we can define:
+
+[source,java]
+----
+package com.mycompany.modules.libmem;
+...
+public static class LibMemModule {
+ private LibMemModule() {}
+ public abstract static class ActionDomainEvent<S>
+ extends org.apache.isis.applib.event.ActionDomainEvent<S> {
+ private static final long serialVersionUID = 1L;
+ public ActionDomainEvent(
+ final S source,
+ final Identifier identifier,
+ final Object... arguments) {
+ super(source, identifier, arguments);
+ }
+ }
+ ... // <1>
+}
+----
+<1> similar events for properties and collections should also be defined
+
+For the class-level we can define:
+
+[source,java]
+----
+public static class LibraryMember {
+ public abstract static class ActionDomainEvent extends LibMemModule.ActionDomainEvent<LibraryMember> {
+ private static final long serialVersionUID = 1L;
+ public ActionDomainEvent(
+ final LibraryMember source,
+ final Identifier identifier,
+ final Object... arguments) {
+ super(source, identifier, arguments);
+ }
+ }
+ ... // <1>
+}
+----
+<1> similar events for properties and collections should also be defined
+
+and finally at the action level we can define:
+
+[source,java]
+----
+public class LibraryMember {
+ ...
+ public static class LeaveEvent extends LibraryMember.ActionDomainEvent {
+ private static final long serialVersionUID = 1L;
+ public PlaceOrderEvent(
+ final Customer source,
+ final Identifier identifier,
+ final Object... arguments) {
+ super(source, identifier, arguments);
+ }
+ }
+ @Action(domainEvent=LeaveEvent.class)
+ public void leave() { ... }
+ ...
+}
+----
+
+The subscriber can subscribe either to the general superclass (as before), or to any of the classes in the hierarchy.
+
+
+
+
+
+== Programmatic posting
+
+To programmatically post an event, simply call `#post()`.
+
+The `LibraryMember` example described above could for example be rewritten into:
+
+[source,java]
+----
+public class LibraryMember {
+ ...
+ public void leave() {
+ ...
+ eventBusService.post(new LibraryMember.LeaveEvent(...)); // <1>
+ }
+ ...
+}
+----
+<1> `LibraryMember.LeaveEvent` could be _any_ class, not just a subclass of `o.a.i.applib.event.ActionDomainEvent`.
+
+In practice we suspect there will be few cases where the programmatic approach is required rather than the declarative approach afforded by xref:rg.adoc#_rg_annotations_manpage-Action_domainEvent[`@Action#domainEvent()`] et al.
+
+
+
+== Using `WrapperFactory`
+
+An alternative way to cause events to be posted is through the xref:rg.adoc#_rg_services-api_manpage-WrapperFactory[`WrapperFactory`]. This is useful when you wish to enforce a (lack-of-) trust boundary between the caller and the callee.
+
+For example, suppose that `Customer#placeOrder(...)` emits a `PlaceOrderEvent`, which is subscribed to by a `ReserveStockSubscriber`. This subscriber in turn calls `StockManagementService#reserveStock(...)`. Any business rules on `#reserveStock(...)` should be enforced.
+
+In the `ReserveStockSubscriber`, we therefore use the `WrapperFactory`:
+
+[source,java]
+----
+@DomainService(nature=NatureOfService.DOMAIN)
+public class ReserveStockSubscriber {
+ @Programmatic
+ @Subscribe
+ public void on(Customer.PlaceOrderEvent ev) {
+ wrapperFactory.wrap(stockManagementService)
+ .reserveStock(ev.getProduct(), ev.getQuantity());
+ }
+ ...
+ @Inject
+ StockManagementService stockManagementService;
+ @Inject
+ WrapperFactory wrapperFactory;
+}
+----
+
+
+== Implementation SPI
+
+The implementation of `EventBusService` provided by 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. Which is used is specified through configuration property (described xref:rg.adoc#_rg_services-api_manpage-EventBusService_Configuration[below]).
+
+[NOTE]
+.Guava vs Axon, which to use?
+====
+Guava actually queues up events; they are not guaranteed to be dispatched immediately. This generally is not problem, but can be for cases where the subscriber may in turn want to post its own events (using xref:rg.adoc#_rg_services-api_manpage-WrapperFactory[`WrapperFactory`]).
+
+The Axon `SimpleEventBus`-based implementation on the other hand is fully synchronous; events are dispatched as soon as they are posted. This works well in all scenarios (that we have tested).
+====
+
+
+It is also possible to use some other implementation.
+
+[source,java]
+----
+public interface EventBusImplementation {
+ void register(Object domainService);
+ void unregister(Object domainService);
+ void post(Object event);
+}
+----
+
+As is probably obvious, the `EventBusService` just delegates down to these method calls when its own similarly named methods are called.
+
+If you do provide your own implementation of this SPI, be aware that your subscribers will need to use whatever convention is required (eg different annotations) such that the events are correctly routed through to your subscribers.
+
+
+
+[[_rg_services-api_manpage-EventBusService_Configuration]]
+== Configuration
+
+The implementation of `EventBusService` provided by 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:ug.adoc#_ug_runtime_configuring-core[configuration property] `isis.services.eventbus.implementation`:
+
+[source,ini]
+----
+isis.services.eventbus.implementation=guava
+----
+
+or
+
+[source,ini]
+----
+isis.services.eventbus.implementation=axon
+----
+
+If you have written your own implementation of the `EventBusServiceImplementation` SPI, then specify instead its fully-qualified class name:
+
+[source,ini]
+----
+isis.services.eventbus.implementation=com.mycompany.isis.MyEventBusServiceImplementation
+----
+
+
+
+In addition, there is one further configuration property, whether to allow "late registration":
+
+[source,ini]
+----
+isis.services.eventbus.allowLateRegistration=false
+----
+
+Late registration refers to the idea that a domain service can register itself with the `EventBusService` after events have been posted. Since domain services are set up at boot time, this almost certainly constitutes a bug in the code and so by default late registration is _not_ allowed. Setting the above property to `true` disables this check.
+
+
+
+
+
+== Registering the Services
+
+Assuming that the `configuration-and-annotation` services installer is configured:
+
+[source,ini]
+----
+isis.services-installer=configuration-and-annotation
+----
+
+then Isis' core implementation of `EventBusService` service is automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
+
+
+
+
+
+== Related Services
+
+The `EventBusService` is intended for fine-grained publish/subscribe for object-to-object interactions within an 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).
+
+The xref:rg.adoc#_rg_services-spi_manpage-PublishingService[`PublishingService`] meanwhile is intended for coarse-grained publish/subscribe for system-to-system interactions, from Isis to some other system. Here the only events published are those that action invocations (for actions annotated with xref:rg.adoc#_rg_annotations_manpage-Action_publishing[`@Action#publishing()`]) and of changed objects (for objects annotated with xref:rg.adoc#_rg_annotations_manpage-DomainObject_publishing[`@DomainObject#publishing()`]).
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-GuiceBeanProvider.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-GuiceBeanProvider.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-GuiceBeanProvider.adoc
new file mode 100644
index 0000000..dfa5fb6
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-GuiceBeanProvider.adoc
@@ -0,0 +1,90 @@
+[[_rg_services-api_manpage-GuiceBeanProvider]]
+= `GuiceBeanProvider`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `GuiceBeanProvider` domain service acts as a bridge between Isis' xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] internal bootstrapping using link:https://github.com/google/guice[Google Guice].
+
+This service operates at a very low-level, and you are unlikely to have a need for it. It is used internally by the framework, in the default implementation of the xref:rg.adoc#_rg_services-api_manpage-DeepLinkService[`DeepLinkService`].
+
+[NOTE]
+====
+Currently Isis uses a combination of Guice (within the Wicket viewer only) and a home-grown dependency injection framework. In future versions we intended to refactor the framework to use CDI throughout. At that time this service is likely to become redundant because we will allow any of the internal components of Isis to be injected into your domain object code.
+====
+
+
+== API & Implementation
+
+The API defined by this service is:
+
+[source,java]
+----
+public interface GuiceBeanProvider {
+ @Programmatic
+ <T> T lookup(Class<T> beanType);
+ @Programmatic
+ <T> T lookup(Class<T> beanType, final Annotation qualifier);
+}
+----
+
+The xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] this provides an implementation of this service.
+
+
+
+== Usage
+
+Using the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] requires subclassing of `IsisWicketApplication`. In the subclass it is commonplace to override `newIsisWicketModule()`, for example:
+
+[source,java]
+----
+@Override
+protected Module newIsisWicketModule() {
+ final Module isisDefaults = super.newIsisWicketModule();
+ final Module overrides = new AbstractModule() {
+ @Override
+ protected void configure() {
+ bind(String.class).annotatedWith(Names.named("applicationName"))
+ .toInstance("ToDo App");
+ bind(String.class).annotatedWith(Names.named("applicationCss"))
+ .toInstance("css/application.css");
+ bind(String.class).annotatedWith(Names.named("applicationJs"))
+ .toInstance("scripts/application.js");
+ ...
+ }
+ };
+ return Modules.override(isisDefaults).with(overrides);
+}
+----
+
+This "module" is in fact a Guice module, and so the `GuiceBeanProvider` service can be used to lookup any of the components bound into it.
+
+For example:
+
+[source,java]
+----
+public class SomeDomainObject {
+ private String lookupApplicationName() {
+ return guiceBeanProvider.lookup(String.class, Names.named("applicationName"));
+ }
+ @Inject
+ GuiceBeanProvider guiceBeanProvider;
+}
+----
+
+should return "ToDo App".
+
+
+
+== Registering the Services
+
+Assuming that the `configuration-and-annotation` services installer is configured:
+
+[source,ini]
+----
+isis.services-installer=configuration-and-annotation
+----
+
+and that the xref:ug.adoc#_ug_wicket-viewer[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/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-IsisJdoSupport.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-IsisJdoSupport.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-IsisJdoSupport.adoc
new file mode 100644
index 0000000..8cd4969
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-IsisJdoSupport.adoc
@@ -0,0 +1,276 @@
+[[_rg_services-api_manpage-IsisJdoSupport]]
+= `IsisJdoSupport`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `IsisJdoSupport` service provides a number of general purpose methods for working with the JDO/DataNucleus objectstore. In general these act at a lower-level of abstraction than the APIs normally used (specifically, those of xref:rg.adoc#_rg_services-api_manpage-DomainObjectContainer[`DomainObjectContainer`]), but nevertheless deal with some of the most common use cases. For service also provides access to the underlying JDO `PersistenceManager` for full control.
+
+The following sections discuss the functionality provided by the service, broken out into categories.
+
+
+
+
+[[_rg_services-api_manpage-IsisJdoSupport_executing-sql]]
+== Executing SQL
+
+You can use the `IsisJdoSupportService` to perform arbitrary SQL SELECTs or UPDATEs:
+
+[source,java]
+----
+public interface IsisJdoSupport {
+ @Programmatic
+ List<Map<String, Object>> executeSql(String sql);
+ @Programmatic
+ Integer executeUpdate(String sql);
+ ...
+}
+----
+
+
+The `executeSql(...)` method allows arbitrary SQL `SELECT` queries to be submitted:
+
+[source,java]
+----
+List<Map<String, Object>> results = isisJdoSupport.executeSql("select * from custMgmt.customers");
+----
+
+The result set is automatically converted into a list of maps, where the map key is the column name.
+
+
+In a similar manner, the `executeUpdate(...)` allows arbitrary SQL ``UPDATE``s to be performed.
+
+[source,java]
+----
+int count = isisJdoSupport.executeUpdate("select count(*) from custMgmt.customers);
+----
+
+The returned value is the number of rows updated.
+
+[TIP]
+====
+As an alternative, consider using DataNucleus' link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/jdoql_typesafe.html[type-safe JDO query API], discussed xref:rg.adoc#_rg_services-api_manpage-IsisJdoSupport_type-safe-query-api[below].
+====
+
+
+
+
+[[_rg_services-api_manpage-IsisJdoSupport_type-safe-jdoql-queries]]
+== Type-safe JDOQL Queries
+
+DataNucleus provides an link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/jdoql_typesafe.html[extension to JDO], so that JDOQL queries can be built up and executed using a set of type-safe classes.
+
+The types in question for type safe queries are not the domain entities, but rather are companion "Q..." query classes. These classes are generated dynamically by an link:https://www.jcp.org/en/jsr/detail?id=269[annotation processor] as a side-effect of compilation, one "Q..." class for each of the xref:rg.adoc#_rg_annotations_manpage-PersistenceCapable[`@PersistenceCapable`] domain entity in your application. For example, a `ToDoItem` domain entity will give rise to a `QToDoItem` query class. These "Q..." classes mirror the structure of domain entity, but expose properties that allow predicates to be built up for querying instances, as well as other functions in support of order by. group by and other clauses.
+
+[NOTE]
+====
+Most IDEs (including IntelliJ and Eclipse) enable annotation processing by default, as does Maven. The DataNucleus' link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/jdoql_typesafe.html[documentation] offers some guidance on confirming that APT is enabled.
+====
+
+The `IsisJdoSupport` service offers two methods at different levels of abstraction:
+
+[source,java]
+----
+public interface IsisJdoSupport {
+ @Programmatic
+ <T> List<T> executeQuery(final Class<T> cls, final BooleanExpression be);
+ @Programmatic
+ <T> TypesafeQuery<T> newTypesafeQuery(Class<T> cls);
+ ...
+}
+----
+
+
+The `executeQuery(...)` method supports the common case of obtaining a set of objects that meet some criteria, filtered using the provided `BooleanExpression`. To avoid memory leaks, the returned list is cloned and the underlying query closed.
+
+For example, in the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] there is an implementation of `ToDoItemRepository` using type-safe queries. The following JDOQL:
+
+[source,sql]
+----
+SELECT
+FROM todoapp.dom.module.todoitem.ToDoItem
+WHERE atPath.indexOf(:atPath) == 0
+ && complete == :complete")
+----
+
+can be expressed using type-safe queries as follows:
+
+[source,java]
+----
+public List<ToDoItem> findByAtPathAndCategory(final String atPath, final Category category) {
+ final QToDoItem q = QToDoItem.candidate();
+ return isisJdoSupport.executeQuery(ToDoItem.class,
+ q.atPath.eq(atPath).and(
+ q.category.eq(category)));
+}
+----
+
+[NOTE]
+====
+You can find the full example of the JDOQL equivalent in the xref:rg.adoc#_rg_services-api_manpage-DomainObjectContainer_generic-repository-api[`DomainObjectContainer`]
+====
+
+
+The `newTypesafeQuery(...)` method is a lower-level API that allows a type safe query to be instantiated for most sophisticated querying, eg using group by or order by clauses. See the
+DataNucleus link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/jdoql_typesafe.html[documentation] for full details of using this.
+
+One thing to be aware of is that after the query has been executed, it should be closed, using `query.closeAll()`. If calling `query.executeList()` we also recommend cloning the resultant list first. The following utility method does both of these tasks:
+
+[source,java]
+----
+private static <T> List<T> executeListAndClose(final TypesafeQuery<T> query) {
+ final List<T> elements = query.executeList();
+ final List<T> list = Lists.newArrayList(elements);
+ query.closeAll();
+ return list;
+}
+----
+
+
+
+[[_rg_services-api_manpage-IsisJdoSupport_fixture-support]]
+== Fixture support
+
+When writing xref:ug.adoc#_ug_testing_integ-test-support[integration tests] you'll usually need to tear down some/all mutable transactional data before each test. One way to do that is to use the `executeUpdate(...)` method described xref:rg.adoc#_rg_services-api_manpage-IsisJdoSupport_executing-sql[above].
+
+Alternatively, the `deleteAll(...)` method will let your test delete all instances of a class without resorting to SQL:
+
+[source,java]
+----
+public interface IsisJdoSupport {
+ @Programmatic
+ void deleteAll(Class<?>... pcClasses);
+ ...
+}
+----
+
+For example:
+
+[source,java]
+----
+public class TearDownAll extends FixtureScriptAbstract {
+ @Override
+ protected void execute(final ExecutionContext ec) {
+ isisJdoSupport.deleteAll(Order.class);
+ isisJdoSupport.deleteAll(CustomerAddress.class);
+ isisJdoSupport.deleteAll(Customer.class);
+ }
+ @Inject
+ IsisJdoSupport isisJdoSupport;
+}
+----
+
+[NOTE]
+====
+It can occasionally be the case that Isis' internal adapter for the domain object is
+still in memory. JDO/DataNucleus seems to bump up the version of the object prior to its deletion,
+which under normal circumstances would cause Isis to throw a concurrency exception. Therefore
+to prevent this from happening (ie to _force_ the deletion of all instances), concurrency checking
+is temporarily disabled while this method is performed.
+====
+
+
+
+
+[[_rg_services-api_manpage-IsisJdoSupport_reloading-entities]]
+== Reloading entities
+
+An http://www.datanucleus.org/products/datanucleus/jdo/orm/relationships.html[(intentional) limitation] of JDO/DataNucleus is that persisting a child entity (in a 1:n bidirectional relationship) does not cause the parent's collection to be updated.
+
+[source,java]
+----
+public interface IsisJdoSupport {
+ @Programmatic
+ <T> T refresh(T domainObject);
+ @Programmatic
+ void ensureLoaded(Collection<?> collectionOfDomainObjects);
+ ...
+}
+----
+
+
+
+The `refresh(T domainObject)` method can be used to reload the parent object (or indeed any object). Under the covers it uses the JDO `PersistenceManager#refresh(...)` API.
+
+
+For example:
+
+[source,java]
+----
+@DomainService(nature=NatureOfService.VIEW_CONTRIBUTIONS_ONLY)
+public class OrderContributions {
+ public Order newOrder(final Customer customer) {
+ Order order = newTransientInstance(Order.class);
+ order.setCustomer(customer);
+ container.persist(customer);
+ container.flush(); // <1>
+ isisJdoSupport.refresh(customer); // <2>
+ return order;
+ }
+ @Inject
+ DomainObjectContainer container;
+ @Inject
+ IsisJdoSupport isisJdoSupport;
+}
+----
+<1> flush to database, ensuring that the database row corresponding to the `Order` exists in its `order` table.
+<2> reload the parent (customer) from the database, so that its collection of ``Order``s is accurate.
+
+
+[NOTE]
+====
+The particular example that led to this method being added was a 1:m bidirectional relationship,
+analogous to `Customer 1<-->* Order`. Persisting the child `Order` object did not cause
+the parent ``Customer``'s collection of orders to be updated. In fact, JDO does not make any
+such guarantee to do so. Options are therefore either to maintain the collection in code, or to
+refresh the parent.
+====
+
+
+The `ensureLoaded(...)` method allows a collection of domain objects to be loaded from the database in a single hit. This can be valuable as a performance optimization to avoid multiple roundtrips to the database. Under the covers it uses the `PersistenceManager#retrieveAll(...)` API.
+
+
+
+
+
+[[_rg_services-api_manpage-IsisJdoSupport_jdo-persistencemanager]]
+== JDO `PersistenceManager`
+
+The functionality provided by `IsisJdoSupport` focus only on the most common use cases. If you require more flexibility than this, eg for dynamically constructed queries, then you can use the service to access the underlying JDO `PersistenceManager` API:
+
+[source,java]
+----
+public interface IsisJdoSupport {
+ @Programmatic
+ PersistenceManager getJdoPersistenceManager();
+ ...
+}
+----
+
+For example:
+
+[source,java]
+----
+public List<Order> findOrders(...) {
+ javax.jdo.PersistenceManager pm = isisJdoSupport.getPersistenceManager();
+
+ // knock yourself out...
+
+ return someListOfOrders;
+}
+----
+
+
+
+
+== Registering the Services
+
+Assuming that the `configuration-and-annotation` services installer is configured:
+
+[source,ini]
+----
+isis.services-installer=configuration-and-annotation
+----
+
+then 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/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-MementoService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-MementoService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-MementoService.adoc
new file mode 100644
index 0000000..8bc6025
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-MementoService.adoc
@@ -0,0 +1,131 @@
+[[_rg_services-api_manpage-MementoService]]
+= `MementoService`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `MementoService` was originally introduced to simplify the implementation of xref:ug.adoc#_ug_more-advanced_view-models[ViewModel]s which are required by the framework to return string representation of all of their backing state, moreover which is safe for use within a URL.
+
+However, it can also be used to create a memento of arbitrary objects. Indeed, it is used internally by the core implementation of xref:rg.adoc#_rg_services-api_manpage-BackgroundService[`BackgroundService`] to capture the state of action invocations so that they can be executed by a background process.
+
+
+
+
+== API & Implementation
+
+The API defined by `MementoService` is:
+
+[source,java]
+----
+public interface MementoService {
+ public static interface Memento {
+ @Programmatic
+ public Memento set(String name, Object value);
+ @Programmatic
+ public <T> T get(String name, Class<T> cls);
+ @Programmatic
+ public String asString();
+ public Set<String> keySet();
+ }
+ @Programmatic
+ public Memento create();
+ @Programmatic
+ public Memento parse(final String str);
+ @Programmatic
+ public boolean canSet(Object input);
+}
+----
+
+The core framework provides a default implementation of this API, namely `o.a.i.core.runtime.services.memento.MementoServiceDefault`. The string returned (from `Memento#asString()`) is a base-64 URL encoded representation of the underlying format (an XML string).
+
+[NOTE]
+====
+In fact, the `MementoServiceDefault` implementation does provide a mechanism to disable the URL encoding, but this is not part of the `MementoService` public API. Note also that the encoding method is not pluggable.
+
+However, you are of course free to write some other implementation of `MementoService`, perhaps based on `MementoServiceDefault` code if you wish.
+====
+
+The types of objects that are supported by the `MementoService` are implementation-specific, but would typically include all the usual value types as well as Isis' `Bookmark` class (to represent references to arbitrary entities). Nulls can also be set.
+
+In the case of the default implementation provided by the core framework, the types supported are:
+
+* `java.lang.String`
+* `java.lang.Boolean`, `boolean`
+* `java.lang.Byte`, `byte`
+* `java.lang.Short`, `short`
+* `java.lang.Integer`, `int`
+* `java.lang.Long`, `long`
+* `java.lang.Float`, `float`
+* `java.lang.Double`, `double`
+* `java.lang.Character`, `char`
+* `java.math.BigDecimal`
+* `java.math.BigInteger`
+* `org.joda.time.LocalDate`
+* `org.apache.isis.applib.services.bookmark.Bookmark`
+
+If using another implementation, the `canSet(...)` method can be used to check if the candidate object's type is supported.
+
+
+
+== 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.
+
+[TIP]
+====
+Rather than implementing `ViewModel`, it's usually easier to annotate your view models with xref:rg.adoc#_rg_annotations_manpage-ViewModel[`@ViewModel`] (or equivalently xref:rg.adoc#_rg_annotations_manpage-DomainObject_nature[`@DomainObject#nature=EXTERNAL_ENTITY`] or xref:rg.adoc#_rg_annotations_manpage-DomainObject_nature[`@DomainObject#nature=INMEMORY_ENTITY`].
+====
+
+For example, suppose you were implementing a view model that represents an external entity in a SOAP web service. To access this service the view model needs to store (say) the hostname, port number and an id to the object.
+
+Using an injected `MementoService` the view model can roundtrip to and from this string, thus implementing the `ViewModel` API:
+
+[source,java]
+----
+public class ExternalEntity implements ViewModel {
+ private String hostname;
+ private int port;
+ private String id;
+ public String viewModelMemento() { // <1>
+ return mementoService.create()
+ .set("hostname", hostname)
+ .set("port", port)
+ .set("id", id)
+ .asString();
+ }
+ public void viewModelInit(String mementoStr) { // <2>
+ Memento memento = mementoService.parse(mementoStr);
+ hostname = memento.get("hostname", String.class);
+ port = memento.get("port", int.class);
+ id = memento.get("id", String.class);
+ ...
+ @Inject
+ MementoService mementoService;
+}
+----
+<1> part of the `ViewModel` API
+<2> part of the `ViewModel` API
+
+
+
+
+
+== Related Services
+
+The memento service is used by the xref:rg.adoc#_rg_services-api_manpage-CommandContext[`CommandContext`] service and also xref:rg.adoc#_rg_services-spi_manpage-BackgroundCommandService[`BackgroundCommandService`]. These both use a memento to capture a representation of an action invocation.
+
+
+
+
+== Registering the Service
+
+Assuming that the `configuration-and-annotation` services installer is configured:
+
+[source,ini]
+----
+isis.services-installer=configuration-and-annotation
+----
+
+then 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/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-MetamodelService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-MetamodelService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-MetamodelService.adoc
new file mode 100644
index 0000000..0feac25
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-MetamodelService.adoc
@@ -0,0 +1,42 @@
+[[_rg_services-api_manpage-MetamodelService]]
+= `MetamodelService`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `MetaModelService` provides access (albeit currently extremely limited) to aspects of Isis' internal metamodel.
+
+Currently this is limited to looking up the object type (as specified in xref:rg.adoc#_rg_annotations_manpage-DomainObject_objectType[`@DomainObject#objectType()`] and equivalent mechanisms, and as used in xref:rg.adoc#_rg_services-api_manpage-BookmarkService[`Bookmark`]s and elsewhere) from an object's class, and vice versa. In the future we expect other aspects of the metamodel to also be formally surfaced through this API.
+
+
+== API & Implementation
+
+The API defined by the service is:
+
+[source,java]
+----
+public interface MetaModelService {
+ @Programmatic
+ Class<?> fromObjectType(final String objectType); // <1>
+ @Programmatic
+ String toObjectType(final Class<?> domainType); // <2>
+}
+----
+<1> reverse lookup of a domain class' object type
+<2> lookup of a domain class' object type
+
+
+
+
+== Registering the Service
+
+Assuming that the `configuration-and-annotation` services installer is configured:
+
+[source,ini]
+----
+isis.services-installer=configuration-and-annotation
+----
+
+then 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/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-QueryResultsCache.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-QueryResultsCache.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-QueryResultsCache.adoc
new file mode 100644
index 0000000..b8d2274
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-QueryResultsCache.adoc
@@ -0,0 +1,127 @@
+[[_rg_services-api_manpage-QueryResultsCache]]
+= `QueryResultsCache`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 purpose of the `QueryResultsCache` is to improve response times to the user, by providing a short-term (link:../../more-advanced-topics/how-to-09-020-How-to-write-a-typical-domain-service.html[request-scoped]) cache of the value of some (safe or idempotent) method call. This will typically be as the result of running a query, but could be any expensive operation.
+
+Caching such values is useful for code that loops "naively" through a bunch of stuff, performing an expensive operation each time. If the data is such that the same expensive operation is made many times, then the query cache is a perfect fit.
+
+
+[NOTE]
+====
+This service was inspired by similar functionality that exists in relational databases, for example Sybase's http://infocenter.sybase.com/help/index.jsp?topic=/com.sybase.dc20023_1251/html/optimizer/X43480.htm[subquery results cache] and Oracle's http://www.dba-oracle.com/oracle11g/oracle_11g_result_cache_sql_hint.htm[result_cache] hint.
+====
+
+
+
+== API & Implementation
+
+The API defined by `QueryResultsCache` is:
+
+[source,java]
+----
+@RequestScoped
+public class QueryResultsCache {
+ public static class Key {
+ public Key(Class<?> callingClass, String methodName, Object... keys) {...}
+ public Class<?> getCallingClass() { ... }
+ public String getMethodName() { ... }
+ public Object[] getKeys() { ... }
+ }
+ public static class Value<T> {
+ public Value(T result) { ... }
+ private T result;
+ public T getResult() {
+ return result;
+ }
+ }
+ @Programmatic
+ public <T> T execute(
+ final Callable<T> callable,
+ final Class<?> callingClass, final String methodName, final Object... keys) { ... }
+ @Programmatic
+ public <T> T execute(final Callable<T> callable, final Key cacheKey) { ... }
+ @Programmatic
+ public <T> Value<T> get(
+ final Class<?> callingClass, final String methodName, final Object... keys) { ... }
+ @Programmatic
+ public <T> Value<T> get(final Key cacheKey) { ... }
+ @Programmatic
+ public <T> void put(final Key cacheKey, final T result) { ... }
+}
+----
+
+This class (`o.a.i.applib.services.queryresultscache.QueryResultsCache`) is also the implementation.
+
+
+
+
+== Usage
+
+Suppose that there's a `TaxService` that calculates tax on `Taxable` items, with respect to some `TaxType`, and for a given `LocalDate`. To calculate tax it must run a database query and then perform some additional calculations.
+
+Our original implementation is:
+
+[source,java]
+----
+@DomainService
+public class TaxService {
+ public BigDecimal calculateTax(
+ final Taxable t, final TaxType tt, final LocalDate d) {
+ // query against DB using t, tt, d
+ // further expensive calculations
+ }
+}
+----
+
+Suppose now that this service is called in a loop, for example iterating over a bunch of orders, where several of those orders are for the same taxable products, say. In this case the result of the calculation would always be the same for any given product.
+
+We can therefore refactor the method to use the query cache as follows:
+
+[source,java]
+----
+public class TaxService {
+ public BigDecimal calculateTax(
+ final Taxable t, final TaxType tt, final LocalDate d) {
+ return queryResultsCache.execute(
+ new Callable<BigDecimal>(){ // <1>
+ public BigDecimal call() throws Exception {
+ // query against DB using t, tt, d
+ // further expensive calculations
+ }
+ },
+ TaxService.class, // <2>
+ "calculateTax",
+ t, tt, d);
+ }
+}
+----
+<1> the `Callable` is the original code
+<2> the remaining parameters in essence uniquely identify the method call.
+
+This refactoring will be worthwhile provided that enough of the orders being processed reference the same taxable products. If however every order is for a different product, then no benefit will be gained from the refactoring.
+
+
+
+
+== Registering the Service
+
+Assuming that the `configuration-and-annotation` services installer is configured:
+
+[source,ini]
+----
+isis.services-installer=configuration-and-annotation
+----
+
+then Isis' core implementation of `QueryResultsCache` service is automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
+
+
+
+
+== Related Services
+
+The xref:rg.adoc#_rg_services-api_manpage-Scratchpad[`Scratchpad`] service is also intended for actions that are called many times, allowing arbitrary information to be shared between them. Those methods could be called from some outer loop in domain code, or by the framework itself if the action invoked has the xref:rg.adoc#_rg_annotations_manpage-Action_invokeOn[`@Action#invokeOn()`] annotation attribute set to `OBJECT_AND_COLLECTION` or `COLLECTION_ONLY`.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-ScratchPad.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-ScratchPad.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-ScratchPad.adoc
new file mode 100644
index 0000000..22331cc
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-ScratchPad.adoc
@@ -0,0 +1,127 @@
+[[_rg_services-api_manpage-Scratchpad]]
+= `Scratchpad`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `Scratchpad` service is a link:../../more-advanced-topics/how-to-09-020-How-to-write-a-typical-domain-service.html[request-scoped] service to allow objects to exchange information even if they do not directly call each other.
+
+
+
+
+== API & Implementation
+
+The API of `Scratchpad` service is:
+
+[source,java]
+----
+@RequestScoped
+public class Scratchpad {
+ @Programmatic
+ public Object get(Object key) { ... }
+ @Programmatic
+ public void put(Object key, Object value) { ... }
+ @Programmatic
+ public void clear() { ... }
+}
+----
+
+This class (`o.a.i.applib.services.scratchpad.Scratchpad`) is also the implementation. And, as you can see, the service is just a request-scoped wrapper around a `java.util.Map`.
+
+
+
+
+
+== Usage
+
+The most common use-case is for xref:rg.adoc#_rg_annotations_manpage-Action_invokeOn[bulk] actions that act upon multiple objects in a list. The (same) `Scratchpad` service is injected into each of these objects, and so they can use pass information.
+
+For example, the Isis addons example https://github.com/isisaddons/isis-app-todoapp/[todoapp] (not ASF) demonstrates how the `Scratchpad` service can be used to calculate the total cost of the selected `ToDoItem`s:
+
+
+[source,java]
+----
+@ActionSemantics(Of.SAFE)
+@Bulk(AppliesTo.BULK_ONLY)
+public BigDecimal totalCost() {
+ BigDecimal total = (BigDecimal) scratchpad.get("runningTotal");
+ if(getCost() != null) {
+ total = total != null ? total.add(getCost()) : getCost();
+ scratchpad.put("runningTotal", total);
+ }
+ return total.setScale(2);
+}
+@Inject
+Scratchpad scratchpad;
+----
+
+A more complex example could use a xref:ug.adoc#_ug_more-advanced_view-models[view model] to enable bulk updates to a set of objects. The view model's job is to gather track of the items to be updated:
+
+[source,java]
+----
+public class ToDoItemUpdateBulkUpdate extends AbstractViewModel {
+ private List<ToDoItem> _items = ...;
+ public ToDoItemBulkUpdate add(ToDoItem item) {
+ _items.add(item);
+ return this;
+ }
+ ... // <1>
+}
+----
+<1> not shown - the implementation of `ViewModel` for converting the list of `_items` into a string.
+
+The bulk action in the objects simply adds the selected item to the view model:
+
+[source,java]
+----
+@Action(
+ invokeOn=InvokeOn.COLLECTIONS_ONLY
+ semantics=SemanticsOf.SAFE
+)
+public ToDoItemBulkUpdate bulkUpdate() {
+ return lookupBulkUpdateViewModel().add(this);
+}
+private ToDoItemBulkUpdate lookupBulkUpdateViewModel() {
+ ToDoItemBulkUpdate bulkUpdate =
+ (ToDoItemBulkUpdate) scratchpad.get("bulkUpdateViewModel"); // <1>
+ if(bulkUpdate == null) {
+ bulkUpdate = container.injectServicesInto(new ToDoItemBulkUpdate());
+ scratchpad.put("bulkUpdateViewModel", bulkUpdate); // <2>
+ }
+ return bulkUpdate;
+}
+@Inject
+Scratchpad scratchpad;
+----
+<1> look for the `ToDoItemBulkUpdate` in the scratchpad...
+<2> ... and add one if there isn't one (ie for the first object returned).
+
+If using the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer], the `ToDoItemBulkUpdate` view model returned from the last action invoked will be displayed. Thereafter this view model can be used to perform a bulk update of the "enlisted" items.
+
+
+
+
+
+== Registering the Service
+
+Assuming that the `configuration-and-annotation` services installer is configured:
+
+[source,ini]
+----
+isis.services-installer=configuration-and-annotation
+----
+
+then Isis' core implementation of `Scratchpad` service is automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
+
+
+
+
+
+
+== Related Services
+
+The xref:rg.adoc#_rg_services-api_manpage-ActionInteractionContext[`ActionInteractionContext`] service allows xref:rg.adoc#_rg_annotations_manpage-Action_invokeOn[bulk actions] to co-ordinate with each other.
+
+The xref:rg.adoc#_rg_services-api_manpage-QueryResultsCache[`QueryResultsCache`] is useful for caching the results of expensive method calls.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-SudoService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-SudoService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-SudoService.adoc
new file mode 100644
index 0000000..3bc0710
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-SudoService.adoc
@@ -0,0 +1,68 @@
+[[_rg_services-api_manpage-SudoService]]
+= `SudoService`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `SudoService` allows the current user reported by the `DomainObjectContainer` to be temporarily changed to some
+other user. This is useful both for xref:ug.adoc#_ug_testing_integ-test-support[integration testing] (eg if testing a workflow system whereby objects are moved from one user to another) and while running xref:ug.adoc#_ug_testing_fixture-scripts[fixture scripts] (eg setting up objects that would normally require several users to have acted upon the objects).
+
+
+== API & Implementation
+
+The API provided by the service is:
+
+[source,java]
+----
+public interface SudoService {
+ @Programmatic
+ void sudo(String username, final Runnable runnable);
+ @Programmatic
+ <T> T sudo(String username, final Callable<T> callable);
+ @Programmatic
+ void sudo(String username, List<String> roles, final Runnable runnable);
+ @Programmatic
+ <T> T sudo(String username, List<String> roles, final Callable<T> callable);
+}
+----
+
+which will run the provided block of code (a `Runnable` or a `Callable`) in a way such that calls to `DomainObjectContainer#getUser()` will return the specified user (and roles, if specified)
+
+The core framework provides a default implementation of this service (`o.a.i.core.runtime.services.sudo.SudoServiceDefault`)
+
+
+
+
+== Usage
+
+A good example can be found in the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] which uses the `SudoService` in a fixture script to set up `ToDoItem` objects:
+
+[source,java]
+----
+protected void execute(final ExecutionContext ec) {
+ ...
+ sudoService.sudo(getUsername(),
+ new Runnable() {
+ @Override
+ public void run() {
+ wrap(toDoItem).completed();
+ }
+ });
+ ...
+}
+----
+
+
+
+== Registering the Service
+
+Assuming that the `configuration-and-annotation` services installer is configured:
+
+[source,ini]
+----
+isis.services-installer=configuration-and-annotation
+----
+
+then 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/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-WrapperFactory.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-WrapperFactory.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-WrapperFactory.adoc
new file mode 100644
index 0000000..47bfeba
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-WrapperFactory.adoc
@@ -0,0 +1,162 @@
+[[_rg_services-api_manpage-WrapperFactory]]
+= `WrapperFactory`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `WrapperFactory` provides the ability to enforce business rules for programmatic interactions between domain objects. If there is a (lack-of-) trust boundary between the caller and callee -- eg if they reside in different modules -- then the wrapper factory is a useful mechanism to ensure that any business constraints defined by te callee are honoured.
+
+For example, if the calling object attempts to modify an unmodifiable property on the target object, then an exception will be thrown. Said another way: interactions are performed "as if" they are through the viewer.
+
+[NOTE]
+====
+For a discussion of the use of the `WrapperFactory` within integration tests (the primary or at least original use case for this service) can be found xref:ug.adoc#_ug_testing_integ-test-support_wrapper-factory[here]
+====
+
+This capability goes beyond enforcing the (imperative) constraints within the `hideXxx()`, `disableXxx()` and `validateXxx()` supporting methods; it also enforces (declarative) constraints such as those represented by annotations, eg `@MaxLength` or `@Regex`.
+
+This capability is frequently used within xref:ug.adoc#_ug_testing_integ-test-support[integration tests], but can also be used in production code. (There are analogies that can be drawn here with the way that JEE beans can interact through an EJB local interface).
+
+
+
+
+== API
+
+The API provided by the service is:
+
+[source,java]
+----
+public interface WrapperFactory {
+ @Programmatic
+ <T> T wrap(T domainObject); // <1>
+ @Programmatic
+ <T> T unwrap(T possibleWrappedDomainObject); // <2>
+ @Programmatic
+ <T> boolean isWrapper(T possibleWrappedDomainObject); // <3>
+
+ public static enum ExecutionMode { // <4>
+ EXECUTE(true,true),
+ SKIP_RULES(false, true), // <5>
+ NO_EXECUTE(true, false); // <6>
+ }
+ @Programmatic
+ <T> T wrap(T domainObject, ExecutionMode mode); // <7>
+ @Programmatic
+ <T> T wrapNoExecute(T domainObject); // <8>
+ @Programmatic
+ <T> T wrapSkipRules(T domainObject); // <9>
+ ...
+ }
+----
+<1> wraps the underlying domain object. If it is already wrapped, returns the object back unchanged.
+<2> Obtains the underlying domain object, if wrapped. If the object is not wrapped, returns back unchanged.
+<3> whether the supplied object has been wrapped.
+<4> enumerates how the wrapper interacts with the underlying domain object.
+<5> validate all business rules and then execute.
+<6> skip all business rules and then execute (including creating xref:rg.adoc#_rg_annotations_manpage-Action_command[command]s and firing pre- and post-execute xref:rg.adoc#_rg_annotations_manpage-Action_domainEvent[domain event]s).
+<7> validate all business rules (including those from xref:rg.adoc#_rg_annotations_manpage-Action_domainEvent[domain event]s) but do not execute.
+<8> convenience method to invoke `wrap(...)` with `ExecuteMode#NO_EXECUTE` (make this feature more discoverable)
+<9> convenience method to invoke `wrap(...)` with `ExecuteMode#SKIP_RULES` (make this feature more discoverable)
+
+
+
+The service works by returning a "wrapper" around a supplied domain object (a link:http://www.javassist.org[javassist] proxy), and it is this wrapper that ensures that the hide/disable/validate rules implies by the Isis programming model are enforced. The wrapper can be interacted with as follows:
+
+* a `get...()` method for properties or collections
+* a `set...()` method for properties
+* an `addTo...()` or `removeFrom...()` method for collections
+* any action
+
+Calling any of the above methods may result in a (subclass of) `InteractionException` if the object disallows it. For example, if a property is annotated with `@Hidden` then a `HiddenException` will be thrown. Similarly if an action has a `validateXxx()` method and the supplied arguments are invalid then an `InvalidException` will be thrown.
+
+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
+
+An exception will be thrown if any other methods are thrown.
+
+
+
+
+
+== Usage
+
+The caller will typically obtain the target object (eg from some repository) and then use the injected `WrapperFactory` to wrap it before interacting with it.
+
+For example:
+
+[source,java]
+----
+public class CustomerAgent {
+ @Action
+ public void refundOrder(final Order order) {
+ final Order wrappedOrder = wrapperFactory.wrap(order);
+ try {
+ wrappedOrder.refund();
+ } catch(InteractionException ex) { // <1>
+ container.raiseError(ex.getMessage()); // <2>
+ return;
+ }
+ }
+ ...
+ @Inject
+ WrapperFactory wrapperFactory;
+ @Inject
+ DomainObjectContainer container;
+}
+----
+<1> if any constraints on the `Order`'s `refund()` action would be violated, then ...
+<2> ... these will be trapped and raised to the user as a warning.
+
+[NOTE]
+====
+It ought to be possible to implement an xref:rg.adoc#_rg_services-spi_manpage-ExceptionRecognizer[`ExceptionRecognizer`]s that would allow the above boilerplate to be removed. This recognizer service would recognize the `InteractionException` and convert to a suitable message.
+
+At the time of writing Isis does not provide an out-of-the-box implementation of such an `ExceptionRecognizer`; but it should be simple enough to write one…
+====
+
+
+
+
+== Listener API
+
+The `WrapperFactory` also provides a listener API to allow other services to listen in on interactions.
+
+[source,java]
+----
+public interface WrapperFactory {
+ ...
+ @Programmatic
+ List<InteractionListener> getListeners(); // <1>
+ @Programmatic
+ public boolean addInteractionListener(InteractionListener listener); // <2>
+ @Programmatic
+ public boolean removeInteractionListener(InteractionListener listener); // <3>
+ @Programmatic
+ public void notifyListeners(InteractionEvent ev); // <4>
+}
+----
+<1> all ``InteractionListener``s that have been registered.
+<2> registers an `InteractionListener`, to be notified of interactions on all wrappers. The listener will be notified of interactions even on wrappers created before the listener was installed. (From an implementation perspective this is because the wrappers delegate back to the container to fire the events).
+<3> remove an `InteractionListener`, to no longer be notified of interactions on wrappers.
+<4> used by the framework itself
+
+The original intent of this API was to enable test transcripts to be captured (in a BDD-like fashion) from integration tests. No such feature has yet been implemented however. Also, the capabilities have by and large been superceded by Isis' support for domain events. We may therefore deprecate this API in the future.
+
+
+
+
+== Registering the Service
+
+Assuming that the `configuration-and-annotation` services installer is configured:
+
+[source,ini]
+----
+isis.services-installer=configuration-and-annotation
+----
+
+then 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/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-XmlSnapshotService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-XmlSnapshotService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-XmlSnapshotService.adoc
new file mode 100644
index 0000000..d4d0d2f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-XmlSnapshotService.adoc
@@ -0,0 +1,214 @@
+[[_rg_services-api_manpage-XmlSnapshotService]]
+= `XmlSnapshotService`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `XmlSnapshotService` provides the capability to generate XML snapshots (and if required corresponding XSD schemas) based on graphs of domain objects.
+
+Typical use cases include creating mementos for business-focused auditing, such that a report could be generated as to which end-user performed a business action (perhaps for legal reasons). For one system that we know of, a digest of this snapshot of data is signed with the public encryption key so as to enforce non-repudiation.
+
+Another use case is to grab raw data such that it could be merged into a report template or communication.
+
+The service offers a basic API to create a snapshot of a single object, and an more flexible API that allows the size of the graph to be customized.
+
+The core framework provides an implementation of this service (`o.a.i.core.runtime.services.xmlsnapshot.XmlSnapshotServiceDefault`).
+
+
+
+== Standard API
+
+The (basic) API of `XmlSnapshotService` is:
+
+[source]
+----
+public interface XmlSnapshotService {
+ public interface Snapshot {
+ Document getXmlDocument();
+ Document getXsdDocument();
+ String getXmlDocumentAsString();
+ String getXsdDocumentAsString();
+ }
+ @Programmatic
+ public XmlSnapshotService.Snapshot snapshotFor(Object domainObject);
+ ...
+}
+----
+
+
+The most straight-forward usage of this service is simply:
+
+[source,java]
+----
+XmlSnapshot snapshot = xmlsnapshotService.snapshotFor(customer);
+Element customerAsXml = snapshot.getXmlElement();
+----
+
+This will return an XML (document) element that contains the names and values of each of the customer's value properties, along with the titles of reference properties, and also the number of items in collections.
+
+
+As well as obtaining the XML snapshot, it is also possible to obtain an XSD schema that the XML snapshot conforms to.
+
+[source]
+----
+XmlSnapshot snapshot = ...;
+Element customerAsXml = snapshot.getXmlElement();
+Element customerXsd = snapshot.getXsdElement();
+----
+
+This can be useful for some tools. For example, link:http://www.altova.com/stylevision.html[Altova Stylevision] can use the XML and XSD to transform into reports. Please note that this link does not imply endorsement (nor even a recommendation that this is a good design).
+
+
+
+
+
+== Builder API
+
+The contents of the snapshot can be adjusted by including "paths" to other references or collections. To do this, the
+builder is used. The API for this is:
+
+[source,java]
+----
+public interface XmlSnapshotService {
+ ...
+ public interface Builder {
+ void includePath(final String path);
+ void includePathAndAnnotation(String path, String annotation);
+ XmlSnapshotService.Snapshot build();
+ }
+ @Programmatic
+ public XmlSnapshotService.Builder builderFor(Object domainObject);
+}
+----
+
+We start by obtaining a builder:
+
+[source,java]
+----
+XmlSnapshot.Builder builder = xmlsnapshotService.builderFor(customer);
+----
+
+Suppose now that we want the snapshot to also include details of the customer's address, where `address` in this case is a reference property to an instance of the `Address` class. We can "walk-the-graph" by including these references within the builder.
+
+[source,java]
+----
+builder.includePath("address");
+----
+
+We could then go further and include details of every order in the customer's `orders` collection, and details of every
+product of every order:
+
+[source,java]
+----
+builder.includePath("orders/product");
+----
+
+When all paths are included, then the builder can build the snapshot:
+
+[source,java]
+----
+XmlSnapshot snapshot = builder.build();
+Element customerAsXml = snapshot.getXmlElement();
+----
+
+All of this can be strung together in a fluent API:
+
+[source,java]
+----
+Element customerAsXml = xmlsnapshotService.builderFor(customer)
+ .includePath("address")
+ .includePath("orders/product")
+ .build()
+ .getXmlElement();
+----
+
+
+As you might imagine, the resultant XML document can get quite large very quickly with only a few "include"s.
+
+
+[NOTE]
+====
+If an XSD schema is beng generated (using `snapshot.getXsdElement()` then note that for the XSD to be correct, the object being snapshotted must have non-null values for the paths that are `include()`'d. If this isn't done then the XSD will not be correct reflect for another snapshotted object that does have non-null values.
+====
+
+
+
+
+== Automatic inclusions
+
+If the domain object being snapshotted implements the `SnapshottableWithInclusions` interace, then this moves the
+responsibility for determining what is included within the snapshot from the caller to the snapshottable object itself:
+
+[source]
+----
+public interface SnapshottableWithInclusions extends Snapshottable {
+ List<String> snapshotInclusions();
+}
+----
+
+If necessary, both approaches can be combined.
+
+
+[TIP]
+====
+As an alternative to using `include()`, you might consider building a view model domain object which can reference only the relevant information required for the snapshot. For example, if only the 5 most recent Orders for a Customer were required, a `CustomerAndRecentOrders` view model could hold a collection of just those 5 ``Order``s. Typically such view models would implement `SnapshottableWithInclusions`.
+
+One reason for doing this is to provide a stable API between the domain model and whatever it is that might be consuming the XML. With a view model you can refactor the domain entities but still preserve a view model such that the XML is the same.
+====
+
+
+
+== Convenience API
+
+The `XmlSnapshotService` also provides some API for simply manipulating XML:
+
+[source]
+----
+public interface XmlSnapshotService {
+ ...
+ @Programmatic
+ public Document asDocument(String xmlStr); // <1>
+ @Programmatic
+ public <T> T getChildElementValue( // <2>
+ Element el, String tagname, Class<T> expectedCls);
+ @Programmatic
+ public Element getChildElement( // <3>
+ Element el, String tagname);
+ @Programmatic
+ public String getChildTextValue(Element el); // <4>
+}
+----
+<1> is a convenience method to convert xml string back into a W3C Document
+<2> is a convenience method to extract the value of an XML element, based on its type.
+<3> is a convenience method to walk XML document.
+<4> is a convenience method to obtain value of child text node.
+
+
+
+
+
+
+
+== Registering the Service
+
+Assuming that the `configuration-and-annotation` services installer is configured:
+
+[source,ini]
+----
+isis.services-installer=configuration-and-annotation
+----
+
+then Isis' core implementation of `XmlSnapshotService` service is automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
+
+
+== Related Services
+
+The xref:rg.adoc#_rg_services-api_manpage-BookmarkService[`BookmarkService`] provides a mechanism for obtaining a string representations of a single domain object.
+
+The xref:rg.adoc#_rg_services-api_manpage-MementoService[`MementoService`] also provides a mechanism for generating string representations of domain objects.
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi.adoc
new file mode 100644
index 0000000..b4a3f45
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi.adoc
@@ -0,0 +1,270 @@
+[[_rg_services-spi]]
+= Domain Services SPI
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 includes an extensive number of domain services for your domain objects to use; these are listed in xref:rg.adoc#_rg_services-api[Reference: Domain Services (API)] chapter.
+
+There are other domain services that constitute not an API but an SPI; if present they are used by Isis itself rather than by your domain objects. A good example of this is the xref:rg.adoc#_rg_services-spi_manpage-AuditingService[`AuditingService`] service; if an implementation is present then Isis will call that service in order to record audit log entries. If no implementation is available then Isis will carry on regardless.
+
+Some domain services can be considered both API and SPI; a good example is the xref:rg.adoc#_rg_services-api_manpage-EmailService[`EmailService`] that is of direct use for domain objects wishing to send out emails, but is also used by the framework to support the xref:ug.adoc#_ug_wicket-viewer_features_user-registration[user registration] functionality supported by the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer]. The same is true of the xref:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`]; this can be used by domain objects to broadcast arbitrary events, but is also used by the framework to automatically emit events for xref:rg.adoc#_rg_annotations_manpage-Action_domainEvent[`@Action#domainEvent()`] etc.
+
+For these hybrid services we have categorized the service as an "API" service. This chapter therefore contains only the strictly SPI services.
+
+
+The table below lists the SPIs that are defined in the Isis applib (`o.a.i.core:isis-core-applib` module).
+
+
+.Applib SPI Services
+[cols="2,4a,1,1", options="header"]
+|===
+
+
+|SPI
+|Description
+|Implementation
+|Notes
+
+
+|xref:rg.adoc#_rg_services-spi_manpage-AuditingService[`o.a.i.applib.` +
+`services.audit` +
+`AuditingService3`]
+|Create an audit record for every changed property of every changed object within a transaction.
+|`AuditingService` +
+``o.ia.m.audit`` +
+``isis-module-audit``
+|related services:
+`AuditingService-` +
+`Contributions`,
+`AuditingService-` +
+`Repository`
+
+|xref:rg.adoc#_rg_services-spi_manpage-BackgroundCommandService[`o.a.i.applib.` +
+`services.background` +
+`BackgroundCommandService`]
+|Persisted a memento of an action invocation such that it can be executed asynchronously ("in the background") eg by a scheduler.
+|`BackgroundCommandServiceJdo` +
+``o.ia.m.command`` +
+``isis-module-command``
+|related services:
+`BackgroundCommandService-` +
+`JdoContributions`,
+`BackgroundCommandService-` +
+`JdoRepository`
+
+
+|xref:rg.adoc#_rg_services-spi_manpage-ClassDiscoveryService[`o.a.i.applib.` +
+`services.classdiscovery` +
+`ClassDiscoveryService`]
+|Mechanism to locate (from the classpath) classes with a specific annotation (eg xref:rg.adoc#_rg_annotations_manpage-DomainService[`@DomainService`])
+
+Subtypes of a given type (eg xref:rg.adoc#_rg_classes_super_manpage-FixtureScript[`FixtureScript`]).
+|`ClassDiscoveryService-` +
+`UsingReflections` +
+``o.a.i.core`` +
+``isis-core-applib``
+|requires `org.reflections:reflections` as Maven dependency
+
+
+|xref:rg.adoc#_rg_services-spi_manpage-CommandService[`o.a.i.applib.` +
+`services.command.spi` +
+`CommandService`]
+|Service to act as a factory and repository (create and save) of command instances, ie representations of an action invocation. Used for command/auditing and background services.
+|`CommandServiceJdo` +
+``o.ia.m.command`` +
+``isis-module-command``
+|related services: +
+`CommandService-` ++
+`JdoContributions`,
+`CommandService-` ++
+`JdoRepository`
+
+
+|xref:rg.adoc#_rg_services-spi_manpage-EmailNotificationService[`o.a.i.applib.` +
+`services.userreg` +
+`EmailNotificationService`]
+|Notify a user during xref:rg.adoc#_rg_services-spi_manpage-UserRegistrationService[self-registration] of users.
+|`EmailNotificationService-` +
+`Default` +
+``o.a.i.core`` +
+``isis-core-runtime``
+|depends on: +
+a configured `EmailService`
+
+|xref:rg.adoc#_rg_services-spi_manpage-EventSerializer[`o.a.i.applib.` +
+`services.publish` +
+`EventSerializer`]
+|Creates a representation of either an action invocation or a changed object being published through the xref:rg.adoc#_rg_services-spi_manpage-PublishingService[`PublishingService`].
+|`RestfulObjects-` +
+`SpecEventSerializer` +
+``o.ia.m.publishing`` +
+``isis-module-publishing``
+|
+
+
+|xref:rg.adoc#_rg_services-spi_manpage-ExceptionRecognizer[`o.a.i.applib.` +
+`services.exceprecog` +
+`ExceptionRecognizer2`]
+|Convert certain exceptions (eg foreign or unique key violation in the database) into a format that can be rendered to the end-user.
+|`ExceptionRecognizer-` +
+`CompositeFor-` +
+`JdoObjectStore` +
+``o.a.i.core`` +
+``isis-core-applib``
+|Extensible using composite pattern if required
+
+
+|xref:rg.adoc#_rg_services-spi_manpage-LocaleProvider[`o.a.i.applib.` +
+`services.i18n` +
+`LocaleProvider`]
+|Request-scoped service to return the locale of the current user, in support of i18n (ie so that the app's UI, messages and exceptions can be translated to the required locale by the xref:rg.adoc#_rg_services-spi_manpage-TranslationService[`TranslationService`].
+|`LocaleProviderWicket` +
+``o.a.i.viewer`` +
+``isis-viewer-wicket-impl``
+|
+
+|xref:rg.adoc#_rg_services-spi_manpage-PublishingService[`o.a.i.applib.` +
+`services.publish` +
+`PublishingService`]
+|Publish any action invocations and changed objects, typically for interchange with an external system in a different bounded context.
+|`PublishingService` +
+``o.ia.m.publishing`` +
+``isis-module-publishing``
+|related services:
+`PublishingService-` ++
+`Contributions`,
+`PublishingService-` ++
+`Repository`. +
+depends on: +
+`EventSerializer`
+
+
+|xref:rg.adoc#_rg_services-spi_manpage-TranslationService[`o.a.i.applib.` +
+`services.i18n` +
+`TranslationService`]
+|Translate an app's UI, messages and exceptions for the current user (as per the locale provided by xref:rg.adoc#_rg_services-spi_manpage-LocaleProvider[`LocalProvider`].
+|`TranslationServicePo` +
+``o.a.i.core`` +
+``isis-core-runtime``
+|related services: `TranslationServicePoMenu` +
+depends on: +
+`TranslationsResolver`, `LocaleProvider`
+
+
+|xref:rg.adoc#_rg_services-spi_manpage-TranslationsResolver[`o.a.i.applib.` +
+`services.i18n` +
+`TranslationsResolver`]
+|Obtain translations for a particuar phrase and locale, in support of i18n (ie so that the app's UI, messages and exceptions can be translated to the required locale by the xref:rg.adoc#_rg_services-spi_manpage-TranslationService[`TranslationService`]
+|`TranslationsResolverWicket` +
+``o.a.i.viewer`` +
+``isis-viewer-wicket-impl``
+|
+
+
+|xref:rg.adoc#_rg_services-spi_manpage-UserProfileService[`o.a.i.applib.` +
+`services.userprof` +
+`UserProfileService`]
+|Obtain an alternative (usually enriched/customized) name for the current user, to render in the UI.
+|
+|
+
+|xref:rg.adoc#_rg_services-spi_manpage-UserRegistrationService[`o.a.i.applib.` +
+`services.userreg` +
+`UserRegistrationService`]
+|Create a new user account with the configured security mechanism.
+|`SecurityModule-` +
+`AppUserRegistrationService` +
+``o.ia.m.security`` +
+``isis-module-security``
+|depends (implicitly) on: +
+a configured `EmailService`
+
+
+|===
+
+
+Key:
+
+* `o.a.i` is an abbreviation for `org.apache.isis`
+* `o.ia.m` is an abbreviation for `org.isisaddons.module`
+
+
+Where an implementation is available (on the classpath) then it is always registered automatically (that is, they are all (with one exception) annotated with xref:rg.adoc#_rg_annotations_manpage-DomainService[`@DomainService`]. The one exception is xref:rg.adoc#_rg_services-spi_manpage-ExceptionRecognizer[`ExceptionRecognizer`], which must be registered explicitly in `isis.properties`; this makes the service extensible (for new exceptions to be recognized).
+
+
+
+
+There are also some "internal" SPI services whose definitions depend on the internals of the framework (rather than the applib).
+
+[WARNING]
+====
+We do not guarantee that link:http://semver.org[semantic versioning] will be honoured for these APIs.
+====
+
+
+
+."Internal" SPI Services
+[cols="3,3,2,2a", options="header"]
+|===
+
+|SPI
+|Maven Module +
+Impl'n (g: a:)
+|Implementation
+|Notes
+
+
+|xref:rg.adoc#_rg_services-spi_manpage-ContentMappingService[`o.a.i.v.ro.` +
+`rendering.service.conneg.` +
+`ContentMappingService`]
+|(Attempt to) map the returned data into the representation required by the client's HTTP `Accept` header.
+|
+|No default implementation.
+
+|xref:rg.adoc#_rg_services-spi_manpage-ContentNegotiationService[`o.a.i.v.ro.` +
+`rendering.service.conneg.` +
+`ContentNegotiationService`]
+|Encodes the algorithm that delegates to any registered xref:rg.adoc#_rg_services-spi_manpage-ContentMappingService[`ContentMappingService`]s.
+|`ContentNegotiationService-` +
+`XRoDomainType` +
+``o.a.i.core`` +
+`isis-core-viewer-restfulobjects-rendering`
+|
+
+
+|xref:rg.adoc#_rg_services-spi_manpage-RepresentationService[`o.a.i.v.ro.` +
+`rendering.service.` +
+`RepresentationService`]
+|Generates the representations, delegating to any registered xref:rg.adoc#_rg_services-spi_manpage-ContentNegotiationService[`ContentNegotiationService`]s.
+|`RepresentationService-` +
+`ForRestfulObjects` +
+``o.a.i.core`` +
+`isis-core-viewer-restfulobjects-rendering`
+|
+
+
+|===
+
+Key:
+
+* `o.a.i.v.ro` is an abbreviation for `org.apache.isis.viewer.restfulobjects`
+
+
+include::_rg_services-spi_manpage-AuditingService.adoc[leveloffset=+1]
+include::_rg_services-spi_manpage-BackgroundCommandService.adoc[leveloffset=+1]
+include::_rg_services-spi_manpage-ClassDiscoveryService.adoc[leveloffset=+1]
+include::_rg_services-spi_manpage-CommandService.adoc[leveloffset=+1]
+include::_rg_services-spi_manpage-ContentMappingService.adoc[leveloffset=+1]
+include::_rg_services-spi_manpage-ContentNegotiationService.adoc[leveloffset=+1]
+include::_rg_services-spi_manpage-EmailNotificationService.adoc[leveloffset=+1]
+include::_rg_services-spi_manpage-EventSerializer.adoc[leveloffset=+1]
+include::_rg_services-spi_manpage-ExceptionRecognizer.adoc[leveloffset=+1]
+include::_rg_services-spi_manpage-LocaleProvider.adoc[leveloffset=+1]
+include::_rg_services-spi_manpage-PublishingService.adoc[leveloffset=+1]
+include::_rg_services-spi_manpage-RepresentationService.adoc[leveloffset=+1]
+include::_rg_services-spi_manpage-TranslationService.adoc[leveloffset=+1]
+include::_rg_services-spi_manpage-TranslationsResolver.adoc[leveloffset=+1]
+include::_rg_services-spi_manpage-UserProfileService.adoc[leveloffset=+1]
+include::_rg_services-spi_manpage-UserRegistrationService.adoc[leveloffset=+1]
[25/45] isis git commit: ISIS-1133: breaking out reference guide and
devenv guide;
moving appendices' release notes and migration notes to other docs;
improving the documentation page.
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_customisation_welcome-page.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_customisation_welcome-page.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_customisation_welcome-page.adoc
new file mode 100644
index 0000000..bb3d26c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_customisation_welcome-page.adoc
@@ -0,0 +1,42 @@
+[[_ug_wicket-viewer_customisation_welcome-page]]
+= Welcome page
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+It's possible to customize the application name, welcome message and about message can also be customized. This is done by adjusting the Guice bindings (part of Isis' bootstrapping) in your custom subclass of `IsisWicketApplication`:
+
+[source,java]
+----
+public class MyAppApplication extends IsisWicketApplication {
+ @Override
+ protected Module newIsisWicketModule() {
+ final Module isisDefaults = super.newIsisWicketModule();
+ final Module myAppOverrides = new AbstractModule() {
+ @Override
+ protected void configure() {
+ ...
+ bind(String.class)
+ .annotatedWith(Names.named("applicationName"))
+ .toInstance("My Wonderful App");
+ bind(String.class)
+ .annotatedWith(Names.named("welcomeMessage"))
+ .toInstance(readLines("welcome.html")); // <1>
+ bind(String.class)
+ .annotatedWith(Names.named("aboutMessage"))
+ .toInstance("My Wonderful App v1.0");
+ ...
+ }
+ };
+
+ return Modules.override(isisDefaults).with(myAppOverrides);
+ }
+}
+----
+<1> the `welcome.html` file is resolved relative to `src/main/webapp`.
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_features.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_features.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_features.adoc
new file mode 100644
index 0000000..0345b5b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_features.adoc
@@ -0,0 +1,26 @@
+[[_ug_wicket-viewer_features]]
+= Features/end-user usage
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 features of the wicket viewer from the perspective of an end-user actually using your Isis application.
+
+
+include::_ug_wicket-viewer_features_recent-pages.adoc[leveloffset=+1]
+include::_ug_wicket-viewer_features_bookmarked-pages.adoc[leveloffset=+1]
+include::_ug_wicket-viewer_features_hints-and-copy-url.adoc[leveloffset=+1]
+include::_ug_wicket-viewer_features_titles-in-tables.adoc[leveloffset=+1]
+include::_ug_wicket-viewer_features_file-upload-download.adoc[leveloffset=+1]
+include::_ug_wicket-viewer_features_user-registration.adoc[leveloffset=+1]
+
+
+
+
+
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_features_bookmarked-pages.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_features_bookmarked-pages.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_features_bookmarked-pages.adoc
new file mode 100644
index 0000000..530f4df
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_features_bookmarked-pages.adoc
@@ -0,0 +1,107 @@
+[[_ug_wicket-viewer_features_bookmarked-pages]]
+= Bookmarked pages
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 Wicket viewer supports the bookmarking of both domain objects and query-only (xref:rg.adoc#_rg_annotations_manpage-Action_semantics[@Action(semantics=...)]) actions.
+
+Domain objects, if bookmarkable, can be nested.
+
+Bookmarking is automatic; whenever a bookmarkable object/action is visited, then a bookmark is created. To avoid the number of bookmarks from indefinitely growing, bookmarks that have not been followed after a whle are automatically removed (an MRU/LRU algorithm). The number of bookmarks to preserve can be configured.
+
+
+
+
+== Screenshots
+
+The following screenshot, taken from https://github.com/isisaddons/isis-app-todoapp[Isisaddons example todoapp] (not ASF) shows how the bookmarks are listed in a sliding panel.
+
+image::{_imagesdir}wicket-viewer/bookmarked-pages/panel.png[width="800px",link="{_imagesdir}wicket-viewer/bookmarked-pages/panel.png"]
+
+[NOTE]
+====
+Note that these screenshots show an earlier version of the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] UI (specifically, pre 1.8.0).
+====
+
+Note how the list contains both domain objects and an action ("not yet complete").
+
+Bookmarks can also form a hierarchy. The following screenshot, also taken from the https://github.com/estatio/estatio[Estatio] application, shows a variety of different bookmarked objects with a nested structure:
+
+image::{_imagesdir}wicket-viewer/bookmarked-pages/panel-estatio.png[width="800px",link="{_imagesdir}wicket-viewer/bookmarked-pages/panel-estatio.png"]
+
+Some - like `Property`, `Lease` and `Party` - are root nodes. However, `LeaseItem` is bookmarkable as a child of `Lease`, and `LeaseTerm` is bookmarkable only as a child of `LeaseItem`. This parent/child relationship is reflected in the layout.
+
+
+
+
+== Domain Code
+
+To indicate a class is bookmarkable, use the xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout[@DomainObjectLayout] annotation:
+
+[source,java]
+----
+@DomainObjectLayout(
+ bookmarking=BookmarkPolicy.AS_ROOT
+)
+public class Lease { ... }
+----
+
+To indicate a class is bookmarkable but only as a child of some parent bookmark, specify the bookmark policy:
+
+[source,java]
+----
+@DomainObjectLayout(
+ bookmarking=BookmarkPolicy.AS_CHILD
+)
+public class LeaseItem { ... }
+----
+
+To indicate that a safe (query only) action is bookmarkable, use the xref:rg.adoc#_rg_annotations_manpage-ActionLayout[@ActionLayout] annotation:
+
+[source,java]
+----
+public class ToDoItem ... {
+ ...
+ @ActionLayout(
+ bookmarking=BookmarkPolicy.AS_ROOT
+ )
+ @ActionSemantics(Of.SAFE)
+ public List<ToDoItem> notYetComplete() { ... }
+ ...
+}
+----
+
+[NOTE]
+====
+The BookmarkPolicy.AS_CHILD does not have a meaning for actions; if the `bookmarking` attribute is set to any other value, it will be ignored.
+====
+
+
+
+
+== User Experience
+
+The sliding panel appears whenever the mouse pointer hovers over the thin blue tab (to the left of the top header region).
+
+Alternatively, `alt+[` will toggle open/close the panel; it can also be closed using `Esc` key.
+
+
+=== Related functionality
+
+The xref:ug.adoc#_ug_wicket-viewer_features_recent-pages[Recent Pages] also lists recently visited pages, selected from a drop-down.
+
+
+
+
+
+== Configuration
+
+By default, the bookmarked pages panel will show a maximum of 15 'root' pages. This can be overridden using a property (in `isis.properties`), for example:
+
+[source,ini]
+----
+isis.viewer.wicket.bookmarkedPages.maxSize=20
+----
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_features_file-upload-download.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_features_file-upload-download.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_features_file-upload-download.adoc
new file mode 100644
index 0000000..3ca2ef9
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_features_file-upload-download.adoc
@@ -0,0 +1,121 @@
+[[_ug_wicket-viewer_features_file-upload-download]]
+= File upload/download
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 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]
+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:
+
+
+
+
+== Screenshots
+
+The following screenshots are taken from the Isis addons example https://github.com/isisaddons/isis-app-todoapp[todoapp] (not ASF):
+
+
+
+=== View mode, empty
+
+`Blob` field rendered as attachment (with no data):
+
+image::{_imagesdir}wicket-viewer/file-upload-download/010-attachment-field-940.png[width="800px",link="{_imagesdir}wicket-viewer/file-upload-download/010-attachment-field.png"]
+
+[NOTE]
+====
+Note that these screenshots show an earlier version of the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] UI (specifically, pre 1.8.0).
+====
+
+
+=== Edit mode
+
+Hit edit; 'choose file' button appears:
+
+image::{_imagesdir}wicket-viewer/file-upload-download/020-edit-choose-file-940.png[width="800px",link="{_imagesdir}wicket-viewer/file-upload-download/020-edit-choose-file.png"]
+
+
+
+=== Choose file
+
+Choose file using the regular browser window:
+
+image::{_imagesdir}wicket-viewer/file-upload-download/030-choose-file-using-browser-520.png[width="520px",link="{_imagesdir}wicket-viewer/file-upload-download/030-choose-file-using-browser.png"]
+
+
+Chosen file is indicated:
+
+image::{_imagesdir}wicket-viewer/file-upload-download/040-edit-chosen-file-indicated-940.png[width="800px",link="{_imagesdir}wicket-viewer/file-upload-download/040-edit-chosen-file-indicated.png"]
+
+
+
+=== Image rendered
+
+Back in view mode (ie once hit OK) if the `Blob` is an image, then it is shown:
+
+image::{_imagesdir}wicket-viewer/file-upload-download/050-ok-if-image-then-rendered-940.png[width="800px",link="{_imagesdir}wicket-viewer/file-upload-download/050-ok-if-image-then-rendered.png"]
+
+
+
+=== Download
+
+`Blob` can be downloaded:
+
+image::{_imagesdir}wicket-viewer/file-upload-download/060-download-940.png[width="800px",link="{_imagesdir}wicket-viewer/file-upload-download/060-download.png"]
+
+
+
+=== Clear
+
+Back in edit mode, can choose a different file or clear (assuming property is not mandatory):
+
+image::{_imagesdir}wicket-viewer/file-upload-download/070-edit-clear-940.png[width="800px",link="{_imagesdir}wicket-viewer/file-upload-download/070-edit-clear.png"]
+
+
+
+
+
+== Domain Code
+
+To define a `Blob`, use:
+
+[source,java]
+----
+private Blob attachment;
+@javax.jdo.annotations.Persistent(defaultFetchGroup="false")
+ @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 = "BLOB")
+ })
+@Property(
+ domainEvent = AttachmentDomainEvent.class,
+ optionality = Optionality.OPTIONAL
+)
+public Blob getAttachment() { return attachment; }
+public void setAttachment(final Blob attachment) { this.attachment = attachment; }
+----
+
+To define a `Clob`, use:
+
+[source,java]
+----
+private Clob doc;
+@javax.jdo.annotations.Persistent(defaultFetchGroup="false", columns = {
+ @javax.jdo.annotations.Column(name = "doc_name"),
+ @javax.jdo.annotations.Column(name = "doc_mimetype"),
+ @javax.jdo.annotations.Column(name = "doc_chars", jdbcType = "CLOB", sqlType = "CLOB")
+})
+@Property(
+ optionality = Optionality.OPTIONAL
+)
+public Clob getDoc() { return doc; }
+public void setDoc(final Clob doc) { this.doc = doc; }
+----
+
+The `Blob` and `Clob` types can also be used as parameters to actions.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_features_hints-and-copy-url.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_features_hints-and-copy-url.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_features_hints-and-copy-url.adoc
new file mode 100644
index 0000000..291a18c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_features_hints-and-copy-url.adoc
@@ -0,0 +1,79 @@
+[[_ug_wicket-viewer_features_hints-and-copy-url]]
+= Hints and copy URL
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+While the user can often copy the URL of a domain object directly from the browser's address bar, the Wicket viewer also allows the URL of domain objects to be easily copied from a dialog.
+
+More interestingly, this URL can also contain hints capturing any sorting or page numbering, or hiding/viewing of collections. End-users can therefore share these URLs as a form of deep linking into a particular view on a domain object.
+
+The copy URL and hinting is automatic.
+
+
+
+
+== Screenshots
+
+The following screenshots are taken from the [Estatio](https://github.com/estatio/estatio) application.
+
+=== Copy URL
+
+This screenshot shows the copy URL button (top right):
+
+image::{_imagesdir}wicket-viewer/copy-link/010-copy-link-button.png[width="800px",link="{_imagesdir}wicket-viewer/copy-link/010-copy-link-button.png"]
+
+[NOTE]
+====
+Note that these screenshots show an earlier version of the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] UI (specifically, pre 1.8.0).
+====
+
+Clicking on this button brings up a dialog with the URL preselected:
+
+image::{_imagesdir}wicket-viewer/copy-link/020-copy-link-dialog.png[width="800px",link="{_imagesdir}wicket-viewer/copy-link/020-copy-link-dialog.png"]
+
+
+The URL in this case is something like:
+
+ http://localhost:8080/wicket/entity/org.estatio.dom.lease.Lease:0
+
+The user can copy the link (eg `ctrl+C`) into the clipboard, then hit `OK` or `Esc` to dismiss the dialog.
+
+
+=== Hints
+
+Using the viewer the user can hide/show collection tables, can sort the tables by header columns:
+
+image::{_imagesdir}wicket-viewer/copy-link/030-hints.png[width="800px",link="{_imagesdir}wicket-viewer/copy-link/030-hints.png"]
+
+
+Also, if the collection spans multiple pages, then the individual page can be selected.
+
+Once the view has been customised, the URL shown in the copy URL dialog is in an extended form:
+
+image::{_imagesdir}wicket-viewer/copy-link/040-copy-link-with-hints.png[width="800px",link="{_imagesdir}wicket-viewer/copy-link/040-copy-link-with-hints.png"]
+
+The URL in this case is something like:
+
+ http://localhost:8080/wicket/entity/org.estatio.dom.lease.Lease:0?hint-1:collectionContents-view=3&hint-1:collectionContents:collectionContents-3:table-DESCENDING=value&hint-1:collectionContents:collectionContents-3:table-pageNumber=0&hint-2:collectionContents-view=0&hint-2:collectionContents:collectionContents-2:table-pageNumber=0&hint-3:collectionContents-view=2&hint-3:collectionContents:collectionContents-2:table-pageNumber=0&hint-4:collectionContents-view=3&hint-4:collectionContents:collectionContents-3:table-ASCENDING=exerciseDate&hint-4:collectionContents:collectionContents-3:table-pageNumber=0&hint-5:collectionContents-view=0&hint-5:collectionContents:collectionContents-3:table-pageNumber=0
+
+
+
+=== Copy URL from title
+
+When the user invokes an action on the object, the URL (necessarily) changes to indicate that the action was invoked. This URL is specific to the user's session and cannot be shared with others.
+
+A quick way for the user to grab a shareable URL is simply by clicking on the object's title:
+
+image::{_imagesdir}wicket-viewer/copy-link/050-title-url.png[width="800px",link="{_imagesdir}wicket-viewer/copy-link/050-title-url.png"]
+
+
+
+
+== User Experience
+
+The copy URL dialog is typically obtained by clicking on the icon.
+
+Alternatively, `alt+]` will also open the dialog. It can be closed with either `OK` or the `Esc` key.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_features_recent-pages.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_features_recent-pages.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_features_recent-pages.adoc
new file mode 100644
index 0000000..82ce149
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_features_recent-pages.adoc
@@ -0,0 +1,53 @@
+[[_ug_wicket-viewer_features_recent-pages]]
+= Recent pages (drop down)
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 Wicket viewer provides a recent pages drop-down that acts as a breadcrumb trail. Using it, the user can quickly open a recently accessed domain object.
+
+
+
+== Screenshots
+
+The following screenshot, taken from the https://github.com/estatio/estatio[Estatio] application, shows the recent pages drop-down after a number of pages have been accessed.
+
+image::{_imagesdir}wicket-viewer/recent-pages/recent-pages.png[width="800px",link="{_imagesdir}wicket-viewer/recent-pages/recent-pages.png"]
+
+
+[NOTE]
+====
+Note that this screenshot show an earlier version of the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] UI (specifically, pre 1.8.0).
+====
+
+
+
+
+
+== Domain Code
+
+The recent pages drop-down is automatically populated; no changes need to be made to the domain classes.
+
+
+
+
+== User Experience
+
+Selecting the domain object from the list causes the viewer to automatically navigate to the page for the selected object.
+
+
+
+
+== Related functionality
+
+The xref:ug.adoc#_ug_wicket-viewer_features_bookmarked-pages[bookmarked pages] (sliding panel) also provides links to recently visited objects, but only those explicitly marked as `@DomainObject(bookmarking=...)`. The bookmarks panel also nests related objects together hierarchically (the recent pages drop-down does not).
+
+
+
+
+== Configuration
+
+The number of objects is hard-coded as 10; it cannot currently be configured.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_features_titles-in-tables.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_features_titles-in-tables.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_features_titles-in-tables.adoc
new file mode 100644
index 0000000..8e81ed0
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_features_titles-in-tables.adoc
@@ -0,0 +1,76 @@
+[[_ug_wicket-viewer_features_titles-in-tables]]
+= Titles 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/
+
+
+Object titles can often be quite long if the intention is to uniquely identify the object. While this is appropriate for the object view, it can be cumbersome within tables.
+
+If an object's title is specified with from `@Title` annotation then the Wicket viewer will (for parented collections) automatically "contextualize" a title by excluding the part of the title corresponding to a reference to the owning (parent) object.
+
+In other words, suppose we have:
+
+image::{_imagesdir}how-tos/ui-hints/object-titles-and-icons/cust-order-product.png[width="579px",link="{_imagesdir}how-tos/ui-hints/object-titles-and-icons/cust-order-product.png"]
+
+so that `Customer` has a collection of `Order`s:
+
+[source,java]
+----
+public class Customer {
+ public Set<Order> getOrders() { ... }
+ ...
+}
+----
+
+and `Product` also has a collection of `Order`s (please forgive the suspect domain modelling in this example (!)):
+
+[source,java]
+----
+public class Product {
+ public Set<Order> getOrders() { ... }
+ ...
+}
+----
+
+and where the `Order` class references both `Customer` and `Product`.
+
+The `Order`'s might involve each of these:
+
+[source,java]
+----
+public class Order {
+ @Title(sequence="1")
+ public Customer getCustomer() { ... }
+ @Title(sequence="2")
+ public Product getProduct() { ... }
+ @Title(sequence="3")
+ public String getOtherInfo() { ... }
+ ...
+}
+----
+
+In this case, if we view a `Customer` with its collection of `Order`s, then in that parented collection's table the customer's property will be automatically excluded from the title of the `Order` (but it would show the product). Conversely, if a `Product` is viewed then its collection of `Order`s would suppress product (but would show the customer).
+
+[TIP]
+====
+This feature is a close cousin of the `@PropertyLayout(hidden=Where.REFERENCES_PARENT)` annotation, which will cause the property itself to be hidden as a column in the table. An Isis idiom is therefore:
+
+[source,java]
+----
+public class Order {
+ @Title(sequence="1")
+ @PropertyLayout(hidden=Where.REFERENCES_PARENT)
+ public Customer getCustomer() { ... }
+ ...
+}
+----
+
+====
+
+The above annotations mean that titles usually "just work", altering according to the context in which they are viewed.
+
+[TIP]
+====
+It is also possible to configure the Wicket viewer to xref:ug.adoc#_ug_wicket-viewer_configuration-properties_abbreviating-titles[abbreviate titles or suppress them] completely.
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_features_user-registration.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_features_user-registration.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_features_user-registration.adoc
new file mode 100644
index 0000000..c425960
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_features_user-registration.adoc
@@ -0,0 +1,81 @@
+[[_ug_wicket-viewer_features_user-registration]]
+= User Registration
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 Wicket viewer provides the ability for users to sign-up by providing a valid email address:
+
+* from the login page the user can instead follow a link to take them to a sign-up page, where they enter their email address.
+* a verification email is sent using this service; the email includes a link back to the running application.
+* the user then completes the registration process by choosing a user name and password.
+* the Wicket viewer then creates an account for them and logs them in.
+
+In a similar way, if the user has forgotten their password then they can request a reset link to be sent to their email, again by providing their email address.
+
+To support this the framework requires three services to be registered and configured:
+
+* the xref:rg.adoc#_rg_services-spi_manpage-UserRegistrationService[user registration service], which provides an API to create the user account
+* the xref:rg.adoc#_rg_services-spi_manpage-EmailNotificationService[email notification service], which provides an API for to send the verification emails
+* the xref:rg.adoc#_rg_services-api_manpage-EmailService[email service], that is used by the email notification service to actually send the email.
+
+The Isis core framework provides a default implementation of both the email notification service and the email service. If your application uses the https://github.com/isisaddons/isis-module-security[Isis addons security module] (not ASF) then an implementation is provided by that module; just add to the classpath. Otherwise you will need to provide your own implementation.
+
+[NOTE]
+====
+There is _no_ default implementation of the user registration service in the core framework.
+====
+
+
+
+== Screenshots
+
+The user is presented with a login page:
+
+image::{_imagesdir}wicket-viewer/user-registration/login-page-default.png[width="300px",link="{_imagesdir}wicket-viewer/user-registration/login-page-default.png"]
+
+
+Navigate to the sign up page. Complete the page, and verify:
+
+image::{_imagesdir}wicket-viewer/user-registration/sign-up-page.png[width="300px",link="{_imagesdir}wicket-viewer/user-registration/sign-up-page.png"]
+
+
+Back to the login page:
+
+image::{_imagesdir}wicket-viewer/user-registration/sign-up-login-page-after-sign-up.png[width="300px",link="{_imagesdir}wicket-viewer/user-registration/sign-up-login-page-after-sign-up.png"]
+
+
+Email arrives, with link:
+
+image::{_imagesdir}wicket-viewer/user-registration/sign-up-email-with-verification-link.png[width="500px",link="{_imagesdir}wicket-viewer/user-registration/sign-up-email-with-verification-link.png"]
+
+
+Follow the link, complete the page:
+
+image::{_imagesdir}wicket-viewer/user-registration/sign-up-registration-page.png[width="300px",link="{_imagesdir}wicket-viewer/user-registration/sign-up-registration-page.png"]
+
+
+Automatically logged in:
+
+image::{_imagesdir}wicket-viewer/user-registration/sign-up-after-registration.png[width="800px",link="{_imagesdir}wicket-viewer/user-registration/sign-up-after-registration.png"]
+
+
+
+
+== Configuration
+
+There are two prerequisites:
+
+* register an implementation of the xref:_user_registration_service[user registration service] (eg by using the https://github.com/isisaddons/isis-module-security[Isis addons security module])
+
+* configure the xref:rg.adoc#_rg_services-api_manpage-EmailService[email service]
+
+The latter is required if you are using the default email notification service and email service. If you are using your own alternative implementation of the email notification service then it may be omitted (and configure your own alternative implementation as required).
+
+It is also possible to configure the Wicket viewer to suppress xref:ug.adoc#_ug_wicket-viewer_configuration-properties_suppressing-sign-up[the sign-up page link] and/or the xref:ug.adoc#_ug_wicket-viewer_configuration-properties_suppressing-password-reset[password reset page].
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_isis-addons.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_isis-addons.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_isis-addons.adoc
new file mode 100644
index 0000000..2e499d7
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_isis-addons.adoc
@@ -0,0 +1,33 @@
+[[_ug_wicket-viewer_isis-addons]]
+= Isis Add-ons (not ASF)
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 (non-ASF) link:http://www.isisaddons.org[Isis Addons] website provides a number of extensions to the Wicket viewer (leveraging the APIs described in <<Extending the Wicket viewer>> section, later. While you are free to fork and adapt any of them to your needs, they are also intended for use "out-of-the-box".
+
+[WARNING]
+====
+Note that Isis addons, while maintained by Isis committers, are not part of the ASF.
+====
+
+This short section gives an overview of their capabilities. For full information, check out the README on their respective github repo. Each wicket extension also includes a demo app so you can (a) see what the extension does and (b) see how to use it within your own code.
+
+
+== Excel download
+
+IMPORTANT: TODO
+
+== Fullcalendar2
+
+IMPORTANT: TODO
+
+== Gmap3
+
+IMPORTANT: TODO
+
+== Wicked charts
+
+IMPORTANT: TODO
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_layout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_layout.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_layout.adoc
new file mode 100644
index 0000000..327a345
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_layout.adoc
@@ -0,0 +1,97 @@
+[[_ug_wicket-viewer_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/
+
+
+
+The wicket viewer has full support for the various methods of specifying the xref:rg.adoc#_rg_object-layout[layout of objects], either statically or dynamically.
+
+Dynamic reloading is automatically supported when running in xref:ug.adoc#_ug_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.
+
+
+[TIP]
+====
+To pick up a change, edit the `.layout.json` file in the IDE and rebuild. Then click on the title of the object _*twice*_.
+
+The first click will cause Isis to pick up the new metadata, but too late in the process to adjust the rendering. The second click will re-render the object with the new metadata.
+====
+
+
+The screenshots below show some of the effects that can be accomplished, for the open source link:https://github.com/estatio/estatio[Estatio] app.
+
+
+
+First, an `Invoice`. This places the properties in three equal-sized columns, with collections underneath:
+
+image::{_imagesdir}wicket-viewer/layouts/estatio-Invoice.png[width="800px",link="{_imagesdir}wicket-viewer/layouts/estatio-Invoice.png"]
+
+
+
+Next, `Lease`. This places its properties in two columns (one wide, one narrow), with its collections shown in the right-most column:
+
+image::{_imagesdir}wicket-viewer/layouts/estatio-Lease.png[width="800px",link="{_imagesdir}wicket-viewer/layouts/estatio-Lease.png"]
+
+
+
+Next, `LeaseItem`. This is similar to `Lease`, with two columns for properties and the third column for collections:
+
+image::{_imagesdir}wicket-viewer/layouts/estatio-LeaseItem.png[width="800px",link="{_imagesdir}wicket-viewer/layouts/estatio-LeaseItem.png"]
+
+
+
+And finally, from the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp], its `ToDoItem`. This puts its properties in two columns; the collections (not visible in the screenshot below) are underneath (like Estatio's `Invoice`):
+
+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:rg.adoc#_rg_object-layout[object layout] chapter.
+
+
+
+== Screencast
+
+How to layout properties and collections dynamically, in the Wicket viewer.
+
+video::zmrg49WeEPc[youtube,width="530px",height="354px"]
+
+
+
+[NOTE]
+====
+Note that this screencast shows an earlier version of the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] UI (specifically, pre 1.8.0).
+====
+
+
+
+
+== Required updates to the dom project's pom.xml
+
+If using the `.layout.json` files, these must be compiled and available in the classpath. When using an IDE such as Eclipse+M2E, any `.layout.json` files in `src/main/java` or `src/main/resources` will be part of the classpath automatically. However, unless the `pom.xml` is changed, these will not be part of the compiled WAR.
+
+Therefore, make sure the following is added to the dom project's `pom.xml`:
+
+[source.xml]
+----
+<resources>
+ <resource>
+ <filtering>false</filtering>
+ <directory>src/main/resources</directory>
+ </resource>
+ <resource>
+ <filtering>false</filtering>
+ <directory>src/main/java</directory>
+ <includes>
+ <include>**</include>
+ </includes>
+ <excludes>
+ <exclude>**/*.java</exclude>
+ </excludes>
+ </resource>
+</resources>
+----
+
+If using an Isis xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype], then the POM is already correctly configured.
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_request-parameters.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_request-parameters.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_request-parameters.adoc
new file mode 100644
index 0000000..53e4cd6
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_wicket-viewer_request-parameters.adoc
@@ -0,0 +1,53 @@
+[[_ug_wicket-viewer_request-parameters]]
+= Request 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/
+
+
+This section describes features that are dependent on HTTP request parameters (*not* by setting configuration properties in `isis.properties`).
+
+== Suppressing Header and Footer (Embedded View)
+
+The Wicket viewer provides some support such that an Isis application can be embedded within a host webapp, for example within an iframe.
+
+Currently this support consists simply of being able to suppress the header and/or footer.
+
+=== Screenshots
+
+For example, the regular view is:
+
+image::{_imagesdir}wicket-viewer/embedded-view/regular.png[width="720px",link="{_imagesdir}wicket-viewer/embedded-view/regular.png"]
+
+
+With the header and footer both suppressed only the main content is shown:
+
+image::{_imagesdir}wicket-viewer/embedded-view/no-header-no-footer.png[width="720px",link="{_imagesdir}wicket-viewer/embedded-view/no-header-no-footer.png"]
+
+
+It is also possible to suppress just the header, or just the footer.
+
+
+=== Request parameters
+
+To suppress the header, add the following as a request parameter:
+
+[source,ini]
+----
+isis.no.header
+----
+
+and to suppress the header, add the following as a request parameter:
+
+[source,ini]
+----
+isis.no.footer
+----
+
+For example,
+
+[source,ini]
+----
+http://localhost:8080/wicket/entity/TODO:0?isis.no.header&isis.no.footer
+----
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_xxx.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_xxx.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_xxx.adoc
new file mode 100644
index 0000000..cfbb258
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_xxx.adoc
@@ -0,0 +1 @@
+[[_ug_xxx]]
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/dg.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg.adoc b/adocs/documentation/src/main/asciidoc/guides/dg.adoc
new file mode 100644
index 0000000..d2e1c98
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/dg.adoc
@@ -0,0 +1,15 @@
+[[dg]]
+= Development Environment Guide
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+pass:[<br/><br/>]
+
+This guide describes how to build an Isis applications either from the command line (as per your link:http://en.wikipedia.org/wiki/Continuous_integration[continuous integration] server or within an IDE.
+
+include::_dg_cmd-line.adoc[leveloffset=+1]
+include::_dg_intellij.adoc[leveloffset=+1]
+include::_dg_eclipse.adoc[leveloffset=+1]
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/eclipse/eclipse-010-windows-preferences.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/eclipse/eclipse-010-windows-preferences.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/eclipse/eclipse-010-windows-preferences.png
new file mode 100644
index 0000000..149a23b
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/eclipse/eclipse-010-windows-preferences.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/eclipse/eclipse-025-project-properties.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/eclipse/eclipse-025-project-properties.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/eclipse/eclipse-025-project-properties.png
new file mode 100644
index 0000000..120856c
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/eclipse/eclipse-025-project-properties.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/eclipse/eclipse-100-project-support.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/eclipse/eclipse-100-project-support.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/eclipse/eclipse-100-project-support.png
new file mode 100644
index 0000000..7068fb4
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/eclipse/eclipse-100-project-support.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/eclipse/eclipse-110-project-support.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/eclipse/eclipse-110-project-support.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/eclipse/eclipse-110-project-support.png
new file mode 100644
index 0000000..49d04a8
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/eclipse/eclipse-110-project-support.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/eclipse/eclipse-120-console.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/eclipse/eclipse-120-console.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/eclipse/eclipse-120-console.png
new file mode 100644
index 0000000..1e77587
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/eclipse/eclipse-120-console.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/eclipse/eclipse-200-enhancer-fails-duplicates.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/eclipse/eclipse-200-enhancer-fails-duplicates.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/eclipse/eclipse-200-enhancer-fails-duplicates.png
new file mode 100644
index 0000000..8d7e10a
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/eclipse/eclipse-200-enhancer-fails-duplicates.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/eclipse/eclipse-210-enhancer-fails-duplicates.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/eclipse/eclipse-210-enhancer-fails-duplicates.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/eclipse/eclipse-210-enhancer-fails-duplicates.png
new file mode 100644
index 0000000..5350251
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/eclipse/eclipse-210-enhancer-fails-duplicates.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/eclipse/eclipse-220-enhancer-fails-duplicates.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/eclipse/eclipse-220-enhancer-fails-duplicates.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/eclipse/eclipse-220-enhancer-fails-duplicates.png
new file mode 100644
index 0000000..dbe247e
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/eclipse/eclipse-220-enhancer-fails-duplicates.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/010-installing/010-welcome-page.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/010-installing/010-welcome-page.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/010-installing/010-welcome-page.png
new file mode 100644
index 0000000..24fbed3
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/010-installing/010-welcome-page.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/010-installing/020-choose-location.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/010-installing/020-choose-location.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/010-installing/020-choose-location.png
new file mode 100644
index 0000000..1d0cb46
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/010-installing/020-choose-location.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/010-installing/030-installation-options.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/010-installing/030-installation-options.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/010-installing/030-installation-options.png
new file mode 100644
index 0000000..01fbe56
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/010-installing/030-installation-options.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/010-installing/040-start-menu-folder.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/010-installing/040-start-menu-folder.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/010-installing/040-start-menu-folder.png
new file mode 100644
index 0000000..dc850cc
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/010-installing/040-start-menu-folder.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/010-installing/050-completing.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/010-installing/050-completing.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/010-installing/050-completing.png
new file mode 100644
index 0000000..7b80e17
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/010-installing/050-completing.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/010-installing/060-import-settings-or-not.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/010-installing/060-import-settings-or-not.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/010-installing/060-import-settings-or-not.png
new file mode 100644
index 0000000..0054c4c
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/010-installing/060-import-settings-or-not.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/010-installing/070-set-ui-theme.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/010-installing/070-set-ui-theme.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/010-installing/070-set-ui-theme.png
new file mode 100644
index 0000000..247fc64
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/010-installing/070-set-ui-theme.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/020-create-new-project/010-new-project-create.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/020-create-new-project/010-new-project-create.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/020-create-new-project/010-new-project-create.png
new file mode 100644
index 0000000..a950887
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/020-create-new-project/010-new-project-create.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/020-create-new-project/020-java-project-setup-jdk.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/020-create-new-project/020-java-project-setup-jdk.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/020-create-new-project/020-java-project-setup-jdk.png
new file mode 100644
index 0000000..16fe8d1
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/020-create-new-project/020-java-project-setup-jdk.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/020-create-new-project/030-java-project-select-jdk.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/020-create-new-project/030-java-project-select-jdk.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/020-create-new-project/030-java-project-select-jdk.png
new file mode 100644
index 0000000..d0214c6
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/020-create-new-project/030-java-project-select-jdk.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/020-create-new-project/040-sdk-selected.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/020-create-new-project/040-sdk-selected.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/020-create-new-project/040-sdk-selected.png
new file mode 100644
index 0000000..b9399d6
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/020-create-new-project/040-sdk-selected.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/020-create-new-project/050-name-and-location.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/020-create-new-project/050-name-and-location.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/020-create-new-project/050-name-and-location.png
new file mode 100644
index 0000000..7f3b8d6
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/020-create-new-project/050-name-and-location.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/020-create-new-project/060-create-dir.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/020-create-new-project/060-create-dir.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/020-create-new-project/060-create-dir.png
new file mode 100644
index 0000000..287478a
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/020-create-new-project/060-create-dir.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/030-import-settings/010-settings-import-jar.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/030-import-settings/010-settings-import-jar.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/030-import-settings/010-settings-import-jar.png
new file mode 100644
index 0000000..c607856
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/030-import-settings/010-settings-import-jar.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/030-import-settings/020-select-all.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/030-import-settings/020-select-all.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/030-import-settings/020-select-all.png
new file mode 100644
index 0000000..8e63a35
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/030-import-settings/020-select-all.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/030-import-settings/030-restart.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/030-import-settings/030-restart.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/030-import-settings/030-restart.png
new file mode 100644
index 0000000..c20e0ac
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/030-import-settings/030-restart.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/040-other-settings/010-maven-installation.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/040-other-settings/010-maven-installation.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/040-other-settings/010-maven-installation.png
new file mode 100644
index 0000000..9fef693
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/040-other-settings/010-maven-installation.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/040-other-settings/020-maven-configuration.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/040-other-settings/020-maven-configuration.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/040-other-settings/020-maven-configuration.png
new file mode 100644
index 0000000..945968d
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/040-other-settings/020-maven-configuration.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/040-other-settings/030-build-automatically.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/040-other-settings/030-build-automatically.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/040-other-settings/030-build-automatically.png
new file mode 100644
index 0000000..b383b3c
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/040-other-settings/030-build-automatically.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/040-other-settings/040-auto-import.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/040-other-settings/040-auto-import.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/040-other-settings/040-auto-import.png
new file mode 100644
index 0000000..293d2c3
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/040-other-settings/040-auto-import.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/050-some-plugins/010-some-plugins.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/050-some-plugins/010-some-plugins.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/050-some-plugins/010-some-plugins.png
new file mode 100644
index 0000000..9e2230b
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/050-some-plugins/010-some-plugins.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/050-some-plugins/020-some-plugins-confirmation.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/050-some-plugins/020-some-plugins-confirmation.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/050-some-plugins/020-some-plugins-confirmation.png
new file mode 100644
index 0000000..037c967
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/050-some-plugins/020-some-plugins-confirmation.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/010-maven-modules-view.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/010-maven-modules-view.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/010-maven-modules-view.png
new file mode 100644
index 0000000..a5b8944
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/010-maven-modules-view.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/020-adding-another-module.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/020-adding-another-module.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/020-adding-another-module.png
new file mode 100644
index 0000000..b8e9ba9
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/020-adding-another-module.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/030-other-module-added.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/030-other-module-added.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/030-other-module-added.png
new file mode 100644
index 0000000..58b42f0
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/030-other-module-added.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/040-ignoring-modules.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/040-ignoring-modules.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/040-ignoring-modules.png
new file mode 100644
index 0000000..0421f99
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/040-ignoring-modules.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/050-ignoring-modules-2.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/050-ignoring-modules-2.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/050-ignoring-modules-2.png
new file mode 100644
index 0000000..6bf26ac
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/050-ignoring-modules-2.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/060-ignored-modules.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/060-ignored-modules.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/060-ignored-modules.png
new file mode 100644
index 0000000..b16086b
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/100-maven-module-mgmt/060-ignored-modules.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/110-running-the-app/010-run-configuration.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/110-running-the-app/010-run-configuration.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/110-running-the-app/010-run-configuration.png
new file mode 100644
index 0000000..0c6a929
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/110-running-the-app/010-run-configuration.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/110-running-the-app/020-datanucleus-enhancer-goal.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/110-running-the-app/020-datanucleus-enhancer-goal.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/110-running-the-app/020-datanucleus-enhancer-goal.png
new file mode 100644
index 0000000..2dae157
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/110-running-the-app/020-datanucleus-enhancer-goal.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/110-running-the-app/030-running-unit-tests.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/110-running-the-app/030-running-unit-tests.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/110-running-the-app/030-running-unit-tests.png
new file mode 100644
index 0000000..b4e042a
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/110-running-the-app/030-running-unit-tests.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/110-running-the-app/040-running-unit-tests-run-configuration.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/110-running-the-app/040-running-unit-tests-run-configuration.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/110-running-the-app/040-running-unit-tests-run-configuration.png
new file mode 100644
index 0000000..83a4a70
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/110-running-the-app/040-running-unit-tests-run-configuration.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/110-running-the-app/050-running-integration-tests-run-configuration.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/110-running-the-app/050-running-integration-tests-run-configuration.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/110-running-the-app/050-running-integration-tests-run-configuration.png
new file mode 100644
index 0000000..6b0ad89
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/110-running-the-app/050-running-integration-tests-run-configuration.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/200-project-sdk/010-file-project-structure.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/200-project-sdk/010-file-project-structure.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/200-project-sdk/010-file-project-structure.png
new file mode 100644
index 0000000..544a185
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/200-project-sdk/010-file-project-structure.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/200-project-sdk/020-select-jdk.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/200-project-sdk/020-select-jdk.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/200-project-sdk/020-select-jdk.png
new file mode 100644
index 0000000..90865f1
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/200-project-sdk/020-select-jdk.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/200-project-sdk/030-select-jdk-directory.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/200-project-sdk/030-select-jdk-directory.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/200-project-sdk/030-select-jdk-directory.png
new file mode 100644
index 0000000..f5675b2
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/200-project-sdk/030-select-jdk-directory.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/200-project-sdk/040-set-project-level.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/200-project-sdk/040-set-project-level.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/200-project-sdk/040-set-project-level.png
new file mode 100644
index 0000000..026a821
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/200-project-sdk/040-set-project-level.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/200-project-sdk/050-isis-language-level-7.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/200-project-sdk/050-isis-language-level-7.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/200-project-sdk/050-isis-language-level-7.png
new file mode 100644
index 0000000..62e220b
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/200-project-sdk/050-isis-language-level-7.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/200-project-sdk/060-app-language-level-8.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/200-project-sdk/060-app-language-level-8.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/200-project-sdk/060-app-language-level-8.png
new file mode 100644
index 0000000..5723524
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/200-project-sdk/060-app-language-level-8.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/250-new-project/010-new-project.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/250-new-project/010-new-project.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/250-new-project/010-new-project.png
new file mode 100644
index 0000000..edc97cf
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/250-new-project/010-new-project.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/250-new-project/020-new-project-name.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/250-new-project/020-new-project-name.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/250-new-project/020-new-project-name.png
new file mode 100644
index 0000000..15b78a7
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/250-new-project/020-new-project-name.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/250-new-project/030-new-project-new-window.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/250-new-project/030-new-project-new-window.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/250-new-project/030-new-project-new-window.png
new file mode 100644
index 0000000..b8d8e61
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/250-new-project/030-new-project-new-window.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/250-new-project/040-new-module-from-existing-sources.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/250-new-project/040-new-module-from-existing-sources.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/250-new-project/040-new-module-from-existing-sources.png
new file mode 100644
index 0000000..160b3b9
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/250-new-project/040-new-module-from-existing-sources.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/250-new-project/050-specify-source-folder.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/250-new-project/050-specify-source-folder.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/250-new-project/050-specify-source-folder.png
new file mode 100644
index 0000000..5eecb9c
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/250-new-project/050-specify-source-folder.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/250-new-project/060-import-using-maven.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/250-new-project/060-import-using-maven.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/250-new-project/060-import-using-maven.png
new file mode 100644
index 0000000..55a5db3
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/250-new-project/060-import-using-maven.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/250-new-project/070-import-module-settings.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/250-new-project/070-import-module-settings.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/250-new-project/070-import-module-settings.png
new file mode 100644
index 0000000..6828802
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/250-new-project/070-import-module-settings.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/250-new-project/080-maven-profiles.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/250-new-project/080-maven-profiles.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/250-new-project/080-maven-profiles.png
new file mode 100644
index 0000000..fcc12aa
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/250-new-project/080-maven-profiles.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/250-new-project/090-maven-coordinates.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/250-new-project/090-maven-coordinates.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/250-new-project/090-maven-coordinates.png
new file mode 100644
index 0000000..fc6691f
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/250-new-project/090-maven-coordinates.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/250-new-project/100-annotation-processing.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/250-new-project/100-annotation-processing.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/250-new-project/100-annotation-processing.png
new file mode 100644
index 0000000..dbb7b6a
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/250-new-project/100-annotation-processing.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/250-new-project/110-parameter8.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/250-new-project/110-parameter8.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/250-new-project/110-parameter8.png
new file mode 100644
index 0000000..a7c4d8d
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/250-new-project/110-parameter8.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/250-new-project/120-clean-generate-sources.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/250-new-project/120-clean-generate-sources.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/250-new-project/120-clean-generate-sources.png
new file mode 100644
index 0000000..5a9182b
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/250-new-project/120-clean-generate-sources.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/300-paraname8-support/010-configuring-the-compiler.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/300-paraname8-support/010-configuring-the-compiler.png b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/300-paraname8-support/010-configuring-the-compiler.png
new file mode 100644
index 0000000..50a043f
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/appendices/dev-env/intellij-idea/300-paraname8-support/010-configuring-the-compiler.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/images/configuration/configuring-shiro/ldap/activeds-ldap-groups.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/configuration/configuring-shiro/ldap/activeds-ldap-groups.png b/adocs/documentation/src/main/asciidoc/guides/images/configuration/configuring-shiro/ldap/activeds-ldap-groups.png
new file mode 100644
index 0000000..0496a84
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/configuration/configuring-shiro/ldap/activeds-ldap-groups.png differ
[11/45] isis git commit: ISIS-1133: breaking out reference guide and
devenv guide;
moving appendices' release notes and migration notes to other docs;
improving the documentation page.
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-validate.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-validate.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-validate.adoc
deleted file mode 100644
index 9cc30d2..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-validate.adoc
+++ /dev/null
@@ -1,113 +0,0 @@
-[[_ug_reference-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, Isis' xref:_ug_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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-validateAddTo.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-validateAddTo.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-validateAddTo.adoc
deleted file mode 100644
index 0151793..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-validateAddTo.adoc
+++ /dev/null
@@ -1,45 +0,0 @@
-[[_ug_reference-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:_ug_wicket-viewer[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). Isis' xref:_ug_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:_ug_reference-methods_prefixes_manpage-addTo[`addTo...()`] and xref:_ug_reference-methods_prefixes_manpage-validateRemoveFrom[`validateRemoveFrom...()`]`
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-validateRemoveFrom.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-validateRemoveFrom.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-validateRemoveFrom.adoc
deleted file mode 100644
index 586a411..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_prefixes_manpage-validateRemoveFrom.adoc
+++ /dev/null
@@ -1,45 +0,0 @@
-[[_ug_reference-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:_ug_wicket-viewer[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). Isis' xref:_ug_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:_ug_reference-methods_prefixes_manpage-removeFrom[`removeFrom...()`] and xref:_ug_reference-methods_prefixes_manpage-validateAddTo[`validateAddTo...()`]`
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved.adoc
deleted file mode 100644
index d967193..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved.adoc
+++ /dev/null
@@ -1,58 +0,0 @@
-[[_ug_reference-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:_ug_reference-methods_reserved_manpage-cssClass[`cssClass()`]
-|Provides a CSS class for this object instance. In conjunction with xref:_ug_runtime_application-specific_application-css[`application.css`], can therefore provide custom styling of an object instance wherever it is rendered. +
-
-See also xref:_ug_reference-methods_reserved_manpage-title[`title()`] and xref:_ug_reference-methods_reserved_manpage-iconName[`iconName()`].
-
-|xref:_ug_reference-methods_reserved_manpage-disable[`disable(...)`]
-|Disable all or some of an object's properties
-
-|xref:_ug_reference-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:_ug_reference-methods_reserved_manpage-hide[`hide(...)`]
-|Hide all or some of an object's properties
-
-|xref:_ug_reference-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:_ug_reference-methods_reserved_manpage-title[`title()`] and xref:_ug_reference-methods_reserved_manpage-cssClass[`cssClass()`]
-
-|xref:_ug_reference-methods_reserved_manpage-title[`title()`]
-|Provides a title for the object. +
-
-See also xref:_ug_reference-methods_reserved_manpage-iconName[`iconName()`] and xref:_ug_reference-methods_reserved_manpage-cssClass[`cssClass()`]
-
-|xref:_ug_reference-methods_reserved_manpage-validate[`validate()`]
-|Validate the object's state prior to persisting.
-
-|===
-
-
-
-
-include::_ug_reference-methods_reserved_manpage-cssClass.adoc[leveloffset=+1]
-include::_ug_reference-methods_reserved_manpage-disable.adoc[leveloffset=+1]
-include::_ug_reference-methods_reserved_manpage-getId.adoc[leveloffset=+1]
-include::_ug_reference-methods_reserved_manpage-hide.adoc[leveloffset=+1]
-include::_ug_reference-methods_reserved_manpage-iconName.adoc[leveloffset=+1]
-include::_ug_reference-methods_reserved_manpage-title.adoc[leveloffset=+1]
-include::_ug_reference-methods_reserved_manpage-validate.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved_manpage-cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved_manpage-cssClass.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved_manpage-cssClass.adoc
deleted file mode 100644
index f250cd9..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved_manpage-cssClass.adoc
+++ /dev/null
@@ -1,46 +0,0 @@
-[[_ug_reference-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:_ug_wicket-viewer[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:_ug_runtime_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:_ug_runtime_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:_ug_reference-methods_reserved_manpage-title[`title()`] and xref:_ug_reference-methods_reserved_manpage-iconName[`iconName()`].
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved_manpage-disable.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved_manpage-disable.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved_manpage-disable.adoc
deleted file mode 100644
index 37b8a48..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved_manpage-disable.adoc
+++ /dev/null
@@ -1,102 +0,0 @@
-[[_ug_reference-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 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:_ug_reference-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 Isis' xref:_ug_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:_ug_reference-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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved_manpage-getId.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved_manpage-getId.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved_manpage-getId.adoc
deleted file mode 100644
index 34bda78..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved_manpage-getId.adoc
+++ /dev/null
@@ -1,19 +0,0 @@
-[[_ug_reference-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:_ug_reference-annotations_manpage-DomainObject_objectType[`objectType()`] attribute for domain objects; it is used as an internal identifier but also appears in URLs within the xref:_ug_restfulobjects-viewer[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:_ug_reference-annotations_manpage-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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved_manpage-hide.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved_manpage-hide.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved_manpage-hide.adoc
deleted file mode 100644
index af3c492..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved_manpage-hide.adoc
+++ /dev/null
@@ -1,39 +0,0 @@
-[[_ug_reference-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 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:_ug_reference-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:_ug_reference-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:_ug_reference-methods_reserved_manpage-disable[here].
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved_manpage-iconName.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved_manpage-iconName.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved_manpage-iconName.adoc
deleted file mode 100644
index 03e7cde..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved_manpage-iconName.adoc
+++ /dev/null
@@ -1,36 +0,0 @@
-[[_ug_reference-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:_ug_wicket-viewer[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:_ug_reference-methods_reserved_manpage-title[`title()`] and xref:_ug_reference-methods_reserved_manpage-cssClass[`cssClass()`]
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved_manpage-title.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved_manpage-title.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved_manpage-title.adoc
deleted file mode 100644
index e740d6d..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved_manpage-title.adoc
+++ /dev/null
@@ -1,65 +0,0 @@
-[[_ug_reference-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 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 Isis' xref:_ug_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:_ug_reference-classes_utility_manpage-TitleBuffer[tility class] to help construct the title string
-<2> imperative conditional logic
-<3> using the xref:_ug_reference-services-api_manpage-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:_ug_reference-annotations_manpage-Title[`@Title`] annotation.
-
-
-See also xref:_ug_reference-methods_reserved_manpage-iconName[`iconName()`] and xref:_ug_reference-methods_reserved_manpage-cssClass[`cssClass()`]
-
-
-
-
-
-
-
-
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved_manpage-validate.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved_manpage-validate.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved_manpage-validate.adoc
deleted file mode 100644
index 0afba4b..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved_manpage-validate.adoc
+++ /dev/null
@@ -1,27 +0,0 @@
-[[_ug_reference-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 Isis' xref:_ug_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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-object-layout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-object-layout.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-object-layout.adoc
deleted file mode 100644
index 36be141..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-object-layout.adoc
+++ /dev/null
@@ -1,20 +0,0 @@
-[[_ug_reference-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_reference-object-layout_static.adoc[leveloffset=+1]
-include::_ug_reference-object-layout_dynamic.adoc[leveloffset=+1]
-include::_ug_reference-object-layout_application-menu.adoc[leveloffset=+1]
-include::_ug_reference-object-layout_static-vs-dynamic.adoc[leveloffset=+1]
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-object-layout_application-menu.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-object-layout_application-menu.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-object-layout_application-menu.adoc
deleted file mode 100644
index 4e37577..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-object-layout_application-menu.adoc
+++ /dev/null
@@ -1,171 +0,0 @@
-[[_ug_reference-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 of a service's actions within a menu
-
-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="...")` 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:_ug_more-advanced_decoupling_vetoing-visibility[vetoing subscriber].
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-object-layout_dynamic.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-object-layout_dynamic.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-object-layout_dynamic.adoc
deleted file mode 100644
index 0d9db57..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-object-layout_dynamic.adoc
+++ /dev/null
@@ -1,113 +0,0 @@
-[[_ug_reference-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_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 file
-
-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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-object-layout_static-vs-dynamic.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-object-layout_static-vs-dynamic.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-object-layout_static-vs-dynamic.adoc
deleted file mode 100644
index dd90bd2..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-object-layout_static-vs-dynamic.adoc
+++ /dev/null
@@ -1,26 +0,0 @@
-[[_ug_reference-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_reference-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_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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-object-layout_static.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-object-layout_static.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-object-layout_static.adoc
deleted file mode 100644
index 3217ef5..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-object-layout_static.adoc
+++ /dev/null
@@ -1,159 +0,0 @@
-[[_ug_reference-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:_ug_reference-annotations_manpage-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:_ug_reference-annotations_manpage-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:_ug_reference-annotations_manpage-ActionLayout, [`@ActionLayout`] xref:_ug_reference-annotations_manpage-CollectionLayout[`@CollectionLayout`], xref:_ug_reference-annotations_manpage-DomainObjectLayout[`@DomainObjectLayout`], xref:_ug_reference-annotations_manpage-DomainServiceLayout[`@DomainServiceLayout`], xref:_ug_reference-annotations_manpage-ParameterLayout[`@ParameterLayout`], xref:_ug_reference-annotations_manpage-PropertyLayout[`@PropertyLayout`], and xref:_ug_reference-annotations_manpage-ViewModelLayout[`@ViewModelLayout`]
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api.adoc
deleted file mode 100644
index 781cb5c..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api.adoc
+++ /dev/null
@@ -1,282 +0,0 @@
-[[_ug_reference-services-api]]
-= Reference: Domain Services 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/
-
-
-Apache Isis includes an extensive number of domain services for your domain objects to use; simply define the service as an annotated field and Isis will inject the service into your object. These services' API are all defined in Isis' applib (`o.a.i.core:isis-core-applib` module); this minimizes the coupling between your code and Isis. It also allows you to easily mock out these services in your unit tests.
-
-[NOTE]
-====
-In addition there are a number of domain services that constitute an SPI; if present they are used by Isis itself rather than by your domain objects. A good example of this is the xref:_ug_reference-services-spi_manpage-AuditingService[`AuditingService3`] service. The SPI services are covered in the xref:_ug_reference-services-spi[Domain Services (SPI) chapter].
-====
-
-
-
-The table below summarizes all the APIs defined by Apache Isis. It also lists their corresponding implementation, either a default implementation provided by Isis itself, or provided by one of the in (non-ASF) link:http://www.isisaddons.org[Isis Addons] modules.
-
-.Domain Services
-[cols="3,3a,3a,3a", options="header"]
-|===
-
-|API
-|Description
-|Implementation
-|Notes
-
-
-|xref:_ug_reference-services-api_manpage-ActionInvocationContext[`o.a.i.applib.` +
-`services.actinv` +
-`ActionInvocation-` +
-`Context`]
-|Request-scoped access to whether action is invoked on object and/or on collection of objects
-|`ActionInvocationContext` +
-``o.a.i.core`` +
-``isis-core-applib``
-|API is also concrete class
-
-
-|xref:_ug_reference-services-api_manpage-BackgroundService[`o.a.i.applib.` +
-`services.background` +
-`BackgroundService`]
-|Programmatic persistence of commands to be persisted (so can be executed by a background mechanism, eg scheduler)
-|`BackgroundServiceDefault` +
-``o.a.i.core`` +
-``isis-core-runtime``
-|depends on: +
-xref:_ug_reference-services-spi_manpage-BackgroundCommandService[`BackgroundCommand-Service`]
-
-
-|xref:_ug_reference-services-api_manpage-BookmarkService[`o.a.i.applib.` +
-`services.bookmark` +
-`BookmarkService`]
-|Convert object reference to a serializable "bookmark", and vice versa
-|`BookmarkServiceDefault` +
-``o.a.i.core`` +
-``isis-core-metamodel``
-|related services:
-`BookmarkHolder-` +
-`ActionContributions`,
-`BookmarkHolder-` +
-`Association-` +
-`Contributions`
-
-
-|xref:_ug_reference-services-api_manpage-ClockService[`o.a.i.applib.` +
-`services.clock` +
-`ClockService`]
-|Access the current time (and for testing, allow the time to be changed)
-|`ClockService` +
-``o.a.i.core`` +
-``isis-core-applib``
-|API is also a concrete class.
-
-
-|xref:_ug_reference-services-api_manpage-CommandContext[`o.a.i.applib.` +
-`services.command` +
-`CommandContext`]
-|Request-scoped access the current action that is being invoked, represented as a command object
-|`CommandContext` +
-``o.a.i.core`` +
-``isis-core-applib``
-|API is also a concrete class. +
-depends on: +
-xref:_ug_reference-services-spi_manpage-CommandService[`CommandService`] for persistent `Command`, else in-memory impl. used
-
-|xref:_ug_reference-services-api_manpage-DeepLinkService[`o.a.i.applib` +
-`services.deeplink` +
-`DeepLinkService`]
-|Obtain a URL to a domain object (eg for use within an email or report)
-|`DeepLinkServiceWicket` +
-``o.a.i.viewer`` +
-``isis-viewer-wicket-impl``
-|Implementation only usable within Wicket viewer
-
-
-|xref:_ug_reference-services-api_manpage-DomainObjectContainer[`o.a.i.applib` +
-`DomainObjectContainer`]
-|Generic repository to search, create and delete objects. Also miscellaneous other functions, eg obtain title of object.
-|`DomainObjectContainer-` +
-`Default` +
-``o.a.i.core`` +
-``isis-core-metamodel``
-|
-
-
-|xref:_ug_reference-services-api_manpage-EmailService[`o.a.i.applib.` +
-`services.email` +
-`EmailService`]
-|Send a HTML email, optionally with attachments.
-|`EmailServiceDefault` +
-``o.a.i.core`` +
-``isis-core-runtime``
-|
-
-
-|xref:_ug_reference-services-api_manpage-EventBusService[`o.a.i.applib.` +
-`services.eventbus` +
-`EventBusService`]
-|Programmatically post events to the internal event bus. Also used by Isis itself to broadcast domain events:
-
-* xref:_ug_reference-annotations_manpage-Action_domainEvent[`Action#domainEvent()`]
-* xref:_ug_reference-annotations_manpage-Property_domainEvent[`Property#domainEvent()`]
-* xref:_ug_reference-annotations_manpage-Collection_domainEvent[`Collection#domainEvent()`]
-|`EventBusServiceJdo` +
-``o.a.i.core`` +
-``isis-core-objectstore-jdo-datanucleus``
-|
-
-
-|xref:_ug_reference-services-api_manpage-GuiceBeanProvider[`o.a.i.applib.` +
-`services.guice` +
-`GuiceBeanProvider`]
-|Access to internal framework services initialized using Guice DI.
-|`GuiceBeanProviderWicket` +
-``o.a.i.core`` +
-``isis-viewer-wicket-impl``
-|
-
-
-|xref:_ug_reference-services-api_manpage-IsisJdoSupport[`o.a.i.applib.` +
-`services.jdosupport` +
-`IsisJdoSupport`]
-|Lower level access to the JDO Persistence API.
-|`IsisJdoSupportImpl` +
-``o.a.i.core`` +
-``isis-core-objectstore-jdo-datanucleus``
-|
-
-
-|xref:_ug_reference-services-api_manpage-MementoService[`o.a.i.applib.` +
-`services.memento` +
-`MementoService`]
-|Capture a serializable memento of a set of primitives or xref:_ug_reference-services-api_manpage-BookmarkService[bookmarks]. Primarily used internally, eg in support of commands/auditing.
-|`MementoServiceDefault` +
-``o.a.i.core`` +
-``isis-core-runtime``
-|
-
-
-|xref:_ug_reference-services-api_manpage-MetaModelService[`o.a.i.applib.` +
-`services.metamodel` +
-`MetaModelService`]
-|Access to certain information from the Isis metamodel.
-|`MetaModelServiceDefault` +
-``o.a.i.core`` +
-``isis-core-metamodel``
-|
-
-
-|xref:_ug_reference-services-api_manpage-QueryResultsCache[`o.a.i.applib.` +
-`services.` +
-`queryresultscache` +
-`QueryResultsCache`]
-|Request-scoped caching of the results of queries (or any data set generated by a given set of input arguments).
-|`QueryResultsCache` +
-``o.a.i.core`` +
-``isis-core-applib``
-|API is also a concrete class
-
-
-|xref:_ug_reference-services-api_manpage-ScratchPad[`o.a.i.applib.` +
-`services.scratchpad` +
-`Scratchpad`]
-|Request-scoped service for interchanging information between and aggregating over multiple method calls; in particular for use by "bulk" actions (invoking of an action for all elements of a collection)
-|`Scratchpad` +
-``o.a.i.core`` +
-``isis-core-applib``
-|API is also a concrete class
-
-
-|xref:_ug_reference-services-api_manpage-SudoService[`o.a.i.applib.` +
-`services.sudo` +
-`SudoService`]
-|For use in testing while running xref:_ug_reference-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``
-|API is also a concrete class
-
-
-|xref:_ug_reference-services-api_manpage-WrapperFactory[`o.a.i.applib.` +
-`services.wrapper` +
-`WrapperFactory`]
-|Interact with another domain object "as if" through the UI (enforcing business rules, firing domain events)
-|`WrapperFactoryDefault` +
-``o.a.i.core`` +
-``isis-core-wrapper``
-|
-
-
-|xref:_ug_reference-services-api_manpage-XmlSnapshotService[`o.a.i.applib.` +
-`services.xmlsnapshot` +
-`XmlSnapshotService`]
-|Generate an XML representation of an object and optionally a graph of related objects.
-|`XmlSnapshotServiceDefault` +
-``o.a.i.core`` +
-``isis-core-runtime``
-|
-
-|===
-
-Key:
-
-* `o.a.i` is an abbreviation for `org.apache.isis`
-* `o.ia.m` is an abbreviation for `org.isisaddons.module`
-
-
-
-
-
-There is also a number of deprecated domain services.
-
-.Deprecated Domain Services
-[cols="3,3a,3a,3a", options="header"]
-|===
-
-|API
-|Description
-|Implementation
-|Notes
-
-|`o.a.i.applib.` +
-`annotation`
-`Bulk.InteractionContext`
-|Request-scoped access to whether action is invoked on object and/or on collection of objects
-|`Bulk.InteractionContext` +
-``o.a.i.core`` +
-``isis-core-applib``
-|Replaced by xref:_ug_reference-services-api_manpage-ActionInvocationContext[`ActionInvocationContext`]
-
-
-
-|===
-
-Key:
-
-* `o.a.i` is an abbreviation for `org.apache.isis`
-* `o.ia.m` is an abbreviation for `org.isisaddons.module`
-
-
-
-include::_ug_reference-services-api_manpage-ActionInvocationContext.adoc[leveloffset=+1]
-include::_ug_reference-services-api_manpage-BackgroundService.adoc[leveloffset=+1]
-include::_ug_reference-services-api_manpage-BookmarkService.adoc[leveloffset=+1]
-include::_ug_reference-services-api_manpage-ClockService.adoc[leveloffset=+1]
-include::_ug_reference-services-api_manpage-CommandContext.adoc[leveloffset=+1]
-include::_ug_reference-services-api_manpage-DeepLinkService.adoc[leveloffset=+1]
-include::_ug_reference-services-api_manpage-DomainObjectContainer.adoc[leveloffset=+1]
-include::_ug_reference-services-api_manpage-EmailService.adoc[leveloffset=+1]
-include::_ug_reference-services-api_manpage-EventBusService.adoc[leveloffset=+1]
-include::_ug_reference-services-api_manpage-GuiceBeanProvider.adoc[leveloffset=+1]
-include::_ug_reference-services-api_manpage-IsisJdoSupport.adoc[leveloffset=+1]
-include::_ug_reference-services-api_manpage-MementoService.adoc[leveloffset=+1]
-include::_ug_reference-services-api_manpage-MetamodelService.adoc[leveloffset=+1]
-include::_ug_reference-services-api_manpage-QueryResultsCache.adoc[leveloffset=+1]
-include::_ug_reference-services-api_manpage-ScratchPad.adoc[leveloffset=+1]
-include::_ug_reference-services-api_manpage-SudoService.adoc[leveloffset=+1]
-include::_ug_reference-services-api_manpage-WrapperFactory.adoc[leveloffset=+1]
-include::_ug_reference-services-api_manpage-XmlSnapshotService.adoc[leveloffset=+1]
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-ActionInvocationContext.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-ActionInvocationContext.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-ActionInvocationContext.adoc
deleted file mode 100644
index e5d81f2..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-ActionInvocationContext.adoc
+++ /dev/null
@@ -1,98 +0,0 @@
-[[_ug_reference-services-api_manpage-ActionInvocationContext]]
-= `ActionInvocationContext`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `ActionInvocationContext` domain service is a xref:_ug_reference-annotations_manpage-RequestScoped[`@RequestScoped`] service intended to support the implementation of "bulk" actions annotated with xref:_ug_reference-annotations_manpage-Action_invokeOn[`@Action#invokeOn()`]. This allows the user to select multiple objects in a table and then invoke the same action against all of them.
-
-When an action is invoked in this way, this service allows each object instance to "know where it is" in the collection; it acts a little like an iterator. In particular, an object can determine if it is the last object to be called, and so can perform special processing, eg to return a summary calculated result.
-
-== API
-
-The API defined by the service is:
-
-[source,java]
-----
-@DomainService(nature = NatureOfService.DOMAIN)
-@RequestScoped // <1>
-public static class ActionInvocationContext {
- public InvokedOn getInvokedOn() { ... } // <2>
- public List<Object> getDomainObjects() { ... } // <3>
- public int getSize() { ... }
- public int getIndex() { ... } // <4>
- public boolean isFirst() { ... }
- public boolean isLast() { ... }
-}
-----
-<1> is xref:_ug_reference-annotations_manpage-RequestScoped[`@RequestScoped`], so this domain service instance is scoped to a particular request and is then destroyed
-<2> an enum set to either `OBJECT` (if action has been invoked on a single object) or `COLLECTION` (if has been invoked on a collection).
-<3> returns the list of domain objects which are being acted upon
-<4> is the 0-based index to the object being acted upon.
-
-
-
-== Usage
-
-For actions that are void or that return null, Isis will return to the list once executed. But for bulk actions that are non-void, Isis will render the returned object/value from the last object invoked (and simply discards the object/value of all actions except the last).
-
-One idiom is for the domain objects to also use the xref:_ug_reference-services-api_manpage-Scratchpad[`Scratchpad`] service to share information, for example to aggregate values. The `ActionInvocationContext#isLast()` method can then be used to determine if all the information has been gathered, and then do something with it (eg derive variance across a range of values, render a graph etc).
-
-More prosaically, the `ActoinInvocationContext` can be used to ensure that the action behaves appropriately depending on how it has been invoked (on a single object and/or a collection) whether it is called in bulk mode or regular mode. Here's a snippet of code from the bulk action in the Isis addon example https://github.com/isisaddons/isis-app-todoapp/[todoapp] (not ASF):
-
-[source,java]
-----
-public class ToDoItem ... {
- @Action(invokeOn=InvokeOn.OBJECTS_AND_COLLECTIONS)
- public ToDoItem completed() {
- setComplete(true);
- ...
- return actionInteractionContext.getInvokedOn() == InvokedOn.OBJECT
- ? this // <1>
- : null; // <2>
- }
- @Inject
- ActionInteractionContext actionInteractionContext;
-}
-----
-<1> if invoked as a regular action, return this object;
-<2> otherwise (if invoked on collection of objects), return null, so that the xref:_ug_wicket-viewer[Wicket viewer] will re-render the list of objects
-
-
-
-
-== Registering the Service
-
-Assuming that the `configuration-and-annotation` services installer is configured:
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then Isis' default implementation of `ActionInvocationContext` class is automatically registered (it is annotated with `@DomainService`) so no further configuration is required.
-
-
-
-== Unit testing support
-
-The `ActionInvocationContext` class also has a couple of static factory methods intended to support unit testing:
-
-[source,java]
-----
-@DomainService(nature = NatureOfService.DOMAIN)
-@RequestScoped
-public class ActionInvocationContext {
- public static ActionInvocationContext onObject(final Object domainObject) {
- return new ActionInvocationContext(InvokedOn.OBJECT, Collections.singletonList(domainObject));
- }
- public static ActionInvocationContext onCollection(final Object... domainObjects) {
- return onCollection(Arrays.asList(domainObjects));
- }
- public static ActionInvocationContext onCollection(final List<Object> domainObjects) {
- return new ActionInvocationContext(InvokedOn.COLLECTION, domainObjects);
- }
- ...
-}
-----
\ No newline at end of file
[45/45] isis git commit: ISIS-1133: breaking out reference guide and
devenv guide;
moving appendices' release notes and migration notes to other docs;
improving the documentation page.
Posted by da...@apache.org.
ISIS-1133: breaking out reference guide and devenv guide; moving appendices' release notes and migration notes to other docs; improving the documentation page.
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/9c5dafab
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/9c5dafab
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/9c5dafab
Branch: refs/heads/master
Commit: 9c5dafab076d3836b0c647d8aedda768ba191bc2
Parents: 461e51b
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Tue Jun 16 06:41:07 2015 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Tue Jun 16 06:41:07 2015 +0100
----------------------------------------------------------------------
adocs/documentation/monitor.rb | 8 +-
adocs/documentation/play.rb | 24 +
.../_release-notes_migration-notes.adoc | 563 +++++++++++++++
.../src/main/asciidoc/common-use-cases.adoc | 4 +-
.../src/main/asciidoc/documentation.adoc | 27 +-
.../src/main/asciidoc/git-policy.adoc | 2 -
.../src/main/asciidoc/guides/_dg_cmd-line.adoc | 9 +
.../src/main/asciidoc/guides/_dg_eclipse.adoc | 136 ++++
.../src/main/asciidoc/guides/_dg_intellij.adoc | 374 ++++++++++
.../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 | 134 ++++
.../_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 | 146 ++++
.../_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 | 36 +
.../_rg_annotations_manpage-Action_typeOf.adoc | 31 +
.../_rg_annotations_manpage-Collection.adoc | 106 +++
...rg_annotations_manpage-CollectionLayout.adoc | 121 ++++
...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 | 158 +++++
..._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 | 76 +++
...nnotations_manpage-DomainObject_bounded.adoc | 36 +
...nnotations_manpage-DomainObject_editing.adoc | 61 ++
...annotations_manpage-DomainObject_nature.adoc | 59 ++
...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 | 110 +++
...g_annotations_manpage-MemberGroupLayout.adoc | 20 +
.../_rg_annotations_manpage-MemberOrder.adoc | 25 +
.../_rg_annotations_manpage-MinLength.adoc | 32 +
.../_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 | 50 ++
...notations_manpage-Parameter_optionality.adoc | 36 +
...otations_manpage-Parameter_regexPattern.adoc | 31 +
..._annotations_manpage-PersistenceCapable.adoc | 90 +++
.../_rg_annotations_manpage-PostConstruct.adoc | 66 ++
.../_rg_annotations_manpage-PreDestroy.adoc | 50 ++
.../_rg_annotations_manpage-PrimaryKey.adoc | 19 +
.../_rg_annotations_manpage-Programmatic.adoc | 27 +
.../_rg_annotations_manpage-Property.adoc | 125 ++++
.../_rg_annotations_manpage-PropertyLayout.adoc | 135 ++++
...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 | 150 ++++
...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 | 46 ++
...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 | 14 +
.../asciidoc/guides/_rg_classes_mixins.adoc | 56 ++
...classes_mixins_manpage-HasTransactionId.adoc | 9 +
.../_rg_classes_mixins_manpage-HasUserName.adoc | 9 +
.../main/asciidoc/guides/_rg_classes_super.adoc | 136 ++++
...s_super_manpage-AbstractContainedObject.adoc | 9 +
...asses_super_manpage-AbstractDomainEvent.adoc | 9 +
...sses_super_manpage-AbstractDomainObject.adoc | 9 +
...ses_super_manpage-AbstractDomainService.adoc | 9 +
...er_manpage-AbstractFactoryAndRepository.adoc | 9 +
...g_classes_super_manpage-AbstractService.adoc | 9 +
...classes_super_manpage-AbstractViewModel.adoc | 9 +
...classes_super_manpage-ActionDomainEvent.adoc | 9 +
...ses_super_manpage-CollectionDomainEvent.adoc | 9 +
..._rg_classes_super_manpage-FixtureScript.adoc | 9 +
...rg_classes_super_manpage-FixtureScripts.adoc | 9 +
...asses_super_manpage-PropertyDomainEvent.adoc | 9 +
.../asciidoc/guides/_rg_classes_utility.adoc | 15 +
.../_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 | 99 +++
.../guides/_rg_methods_lifecycle_jdo-api.adoc | 50 ++
.../_rg_methods_lifecycle_manpage-created.adoc | 11 +
.../_rg_methods_lifecycle_manpage-loaded.adoc | 10 +
..._rg_methods_lifecycle_manpage-persisted.adoc | 12 +
...rg_methods_lifecycle_manpage-persisting.adoc | 12 +
.../_rg_methods_lifecycle_manpage-removed.adoc | 12 +
.../_rg_methods_lifecycle_manpage-removing.adoc | 12 +
.../_rg_methods_lifecycle_manpage-updated.adoc | 14 +
.../_rg_methods_lifecycle_manpage-updating.adoc | 10 +
.../asciidoc/guides/_rg_methods_prefixes.adoc | 219 ++++++
.../_rg_methods_prefixes_manpage-addTo.adoc | 37 +
...g_methods_prefixes_manpage-autoComplete.adoc | 91 +++
.../_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 | 20 +
.../_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 +++++
.../main/asciidoc/guides/_rg_services-api.adoc | 282 ++++++++
...ces-api_manpage-ActionInvocationContext.adoc | 98 +++
..._services-api_manpage-BackgroundService.adoc | 123 ++++
...roundService_BackgroundCommandExecution.adoc | 25 +
...es-api_manpage-BackgroundService_Quartz.adoc | 162 +++++
...rg_services-api_manpage-BookmarkService.adoc | 117 ++++
...ices-api_manpage-BulkInteractionContext.adoc | 9 +
.../_rg_services-api_manpage-ClockService.adoc | 104 +++
..._rg_services-api_manpage-CommandContext.adoc | 217 ++++++
...rg_services-api_manpage-DeepLinkService.adoc | 57 ++
...vices-api_manpage-DomainObjectContainer.adoc | 43 ++
...nObjectContainer_generic-repository-api.adoc | 89 +++
...page-DomainObjectContainer_messages-api.adoc | 50 ++
...mainObjectContainer_object-creation-api.adoc | 40 ++
...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 | 98 +++
...rg_services-api_manpage-EventBusService.adoc | 381 +++++++++++
..._services-api_manpage-GuiceBeanProvider.adoc | 90 +++
..._rg_services-api_manpage-IsisJdoSupport.adoc | 276 ++++++++
..._rg_services-api_manpage-MementoService.adoc | 131 ++++
...g_services-api_manpage-MetamodelService.adoc | 42 ++
..._services-api_manpage-QueryResultsCache.adoc | 127 ++++
.../_rg_services-api_manpage-ScratchPad.adoc | 127 ++++
.../_rg_services-api_manpage-SudoService.adoc | 68 ++
..._rg_services-api_manpage-WrapperFactory.adoc | 162 +++++
...services-api_manpage-XmlSnapshotService.adoc | 214 ++++++
.../main/asciidoc/guides/_rg_services-spi.adoc | 270 ++++++++
...rg_services-spi_manpage-AuditingService.adoc | 84 +++
...es-spi_manpage-BackgroundCommandService.adoc | 129 ++++
...vices-spi_manpage-ClassDiscoveryService.adoc | 81 +++
..._rg_services-spi_manpage-CommandService.adoc | 99 +++
...vices-spi_manpage-ContentMappingService.adoc | 106 +++
...s-spi_manpage-ContentNegotiationService.adoc | 189 +++++
...es-spi_manpage-EmailNotificationService.adoc | 80 +++
...rg_services-spi_manpage-EventSerializer.adoc | 72 ++
...ervices-spi_manpage-ExceptionRecognizer.adoc | 123 ++++
..._rg_services-spi_manpage-LocaleProvider.adoc | 71 ++
..._services-spi_manpage-PublishingService.adoc | 163 +++++
...vices-spi_manpage-RepresentationService.adoc | 106 +++
...services-spi_manpage-TranslationService.adoc | 79 +++
...rvices-spi_manpage-TranslationsResolver.adoc | 67 ++
...services-spi_manpage-UserProfileService.adoc | 44 ++
...ces-spi_manpage-UserRegistrationService.adoc | 81 +++
.../main/asciidoc/guides/_ug_core-concepts.adoc | 22 +
.../guides/_ug_core-concepts_add-ons.adoc | 35 +
.../_ug_core-concepts_building-blocks.adoc | 93 +++
...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 | 80 +++
...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 | 36 +
...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 | 37 +
.../main/asciidoc/guides/_ug_deployment.adoc | 19 +
.../guides/_ug_deployment_cmd-line.adoc | 30 +
...g_deployment_externalized-configuration.adoc | 9 +
.../asciidoc/guides/_ug_deployment_gae.adoc | 48 ++
.../guides/_ug_deployment_jvm-flags.adoc | 9 +
.../asciidoc/guides/_ug_deployment_neo4j.adoc | 59 ++
.../asciidoc/guides/_ug_deployment_tomcat.adoc | 35 +
.../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 | 44 ++
.../_ug_extending_restfulobjects-viewer.adoc | 51 ++
.../guides/_ug_extending_wicket-viewer.adoc | 26 +
...ng_wicket-viewer_custom-bootstrap-theme.adoc | 34 +
...ug_extending_wicket-viewer_custom-pages.adoc | 92 +++
...ng_wicket-viewer_isis-addons-extensions.adoc | 17 +
...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 | 300 ++++++++
.../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 | 283 ++++++++
.../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 | 164 +++++
.../_ug_how-tos_drop-downs-and-defaults.adoc | 65 ++
.../_ug_how-tos_entity-relationships.adoc | 15 +
...aged-1-to-m-bidirectional-relationships.adoc | 58 ++
.../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 +++
.../asciidoc/guides/_ug_isis-maven-plugin.adoc | 9 +
.../main/asciidoc/guides/_ug_more-advanced.adoc | 26 +
.../guides/_ug_more-advanced_bulk-actions.adoc | 8 +
.../guides/_ug_more-advanced_decoupling.adoc | 26 +
..._more-advanced_decoupling_contributions.adoc | 8 +
..._ug_more-advanced_decoupling_db-schemas.adoc | 151 ++++
.../_ug_more-advanced_decoupling_event-bus.adoc | 11 +
...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 | 55 ++
...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 | 81 +++
.../src/main/asciidoc/guides/_ug_runtime.adoc | 29 +
.../_ug_runtime_application-specific.adoc | 13 +
...me_application-specific_application-css.adoc | 8 +
...ime_application-specific_application-js.adoc | 9 +
.../guides/_ug_runtime_configuration-files.adoc | 36 +
.../guides/_ug_runtime_configuring-core.adoc | 239 +++++++
.../_ug_runtime_configuring-datanucleus.adoc | 18 +
...s_disabling-persistence-by-reachability.adoc | 88 +++
...atanucleus_eagerly-registering-entities.adoc | 44 ++
...configuring-datanucleus_persistence-xml.adoc | 10 +
...time_configuring-datanucleus_properties.adoc | 64 ++
...ring-datanucleus_using-jndi-data-source.adoc | 75 ++
.../guides/_ug_runtime_deployment-types.adoc | 12 +
.../_ug_runtime_specifying-components.adoc | 72 ++
.../asciidoc/guides/_ug_runtime_web-xml.adoc | 35 +
.../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 | 286 ++++++++
...ug_testing_fixture-scripts_sudo-service.adoc | 59 ++
.../guides/_ug_testing_integ-test-support.adoc | 24 +
...esting_integ-test-support_bootstrapping.adoc | 231 +++++++
..._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 | 13 +
...esting_unit-test-support_contract-tests.adoc | 171 +++++
...ting_unit-test-support_jmock-extensions.adoc | 59 ++
...g_unit-test-support_maven-configuration.adoc | 46 ++
.../asciidoc/guides/_ug_troubleshooting.adoc | 14 +
.../_ug_troubleshooting_enabling-logging.adoc | 39 ++
.../src/main/asciidoc/guides/_ug_tutorials.adoc | 18 +
.../guides/_ug_tutorials_pet-clinic.adoc | 557 +++++++++++++++
...tutorials_stop-scaffolding-start-coding.adoc | 684 +++++++++++++++++++
.../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 | 109 +++
..._customisation_using-different-css-file.adoc | 36 +
...icket-viewer_customisation_welcome-page.adoc | 42 ++
.../guides/_ug_wicket-viewer_features.adoc | 26 +
...wicket-viewer_features_bookmarked-pages.adoc | 107 +++
...et-viewer_features_file-upload-download.adoc | 121 ++++
...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 ++
.../src/main/asciidoc/guides/_ug_xxx.adoc | 1 +
.../src/main/asciidoc/guides/dg.adoc | 15 +
.../eclipse/eclipse-010-windows-preferences.png | Bin 0 -> 37417 bytes
.../eclipse/eclipse-025-project-properties.png | Bin 0 -> 76584 bytes
.../eclipse/eclipse-100-project-support.png | Bin 0 -> 54952 bytes
.../eclipse/eclipse-110-project-support.png | Bin 0 -> 53218 bytes
.../dev-env/eclipse/eclipse-120-console.png | Bin 0 -> 12887 bytes
.../eclipse-200-enhancer-fails-duplicates.png | Bin 0 -> 47581 bytes
.../eclipse-210-enhancer-fails-duplicates.png | Bin 0 -> 11776 bytes
.../eclipse-220-enhancer-fails-duplicates.png | Bin 0 -> 54752 bytes
.../010-installing/010-welcome-page.png | Bin 0 -> 29192 bytes
.../010-installing/020-choose-location.png | Bin 0 -> 24433 bytes
.../010-installing/030-installation-options.png | Bin 0 -> 18300 bytes
.../010-installing/040-start-menu-folder.png | Bin 0 -> 26120 bytes
.../010-installing/050-completing.png | Bin 0 -> 26499 bytes
.../060-import-settings-or-not.png | Bin 0 -> 11691 bytes
.../010-installing/070-set-ui-theme.png | Bin 0 -> 87739 bytes
.../010-new-project-create.png | Bin 0 -> 14048 bytes
.../020-java-project-setup-jdk.png | Bin 0 -> 29837 bytes
.../030-java-project-select-jdk.png | Bin 0 -> 16597 bytes
.../020-create-new-project/040-sdk-selected.png | Bin 0 -> 24884 bytes
.../050-name-and-location.png | Bin 0 -> 11407 bytes
.../020-create-new-project/060-create-dir.png | Bin 0 -> 8424 bytes
.../010-settings-import-jar.png | Bin 0 -> 24084 bytes
.../030-import-settings/020-select-all.png | Bin 0 -> 8863 bytes
.../030-import-settings/030-restart.png | Bin 0 -> 8209 bytes
.../010-maven-installation.png | Bin 0 -> 43353 bytes
.../020-maven-configuration.png | Bin 0 -> 53554 bytes
.../030-build-automatically.png | Bin 0 -> 50767 bytes
.../040-other-settings/040-auto-import.png | Bin 0 -> 31963 bytes
.../050-some-plugins/010-some-plugins.png | Bin 0 -> 45812 bytes
.../020-some-plugins-confirmation.png | Bin 0 -> 35687 bytes
.../010-maven-modules-view.png | Bin 0 -> 103134 bytes
.../020-adding-another-module.png | Bin 0 -> 23846 bytes
.../030-other-module-added.png | Bin 0 -> 111516 bytes
.../040-ignoring-modules.png | Bin 0 -> 120475 bytes
.../050-ignoring-modules-2.png | Bin 0 -> 17050 bytes
.../060-ignored-modules.png | Bin 0 -> 92428 bytes
.../010-run-configuration.png | Bin 0 -> 34826 bytes
.../020-datanucleus-enhancer-goal.png | Bin 0 -> 8491 bytes
.../030-running-unit-tests.png | Bin 0 -> 29351 bytes
...040-running-unit-tests-run-configuration.png | Bin 0 -> 37582 bytes
...ning-integration-tests-run-configuration.png | Bin 0 -> 40655 bytes
.../010-file-project-structure.png | Bin 0 -> 19261 bytes
.../200-project-sdk/020-select-jdk.png | Bin 0 -> 43375 bytes
.../030-select-jdk-directory.png | Bin 0 -> 20740 bytes
.../200-project-sdk/040-set-project-level.png | Bin 0 -> 40868 bytes
.../050-isis-language-level-7.png | Bin 0 -> 53883 bytes
.../060-app-language-level-8.png | Bin 0 -> 58257 bytes
.../250-new-project/010-new-project.png | Bin 0 -> 20564 bytes
.../250-new-project/020-new-project-name.png | Bin 0 -> 11273 bytes
.../030-new-project-new-window.png | Bin 0 -> 9785 bytes
.../040-new-module-from-existing-sources.png | Bin 0 -> 27953 bytes
.../050-specify-source-folder.png | Bin 0 -> 23884 bytes
.../250-new-project/060-import-using-maven.png | Bin 0 -> 11739 bytes
.../070-import-module-settings.png | Bin 0 -> 36175 bytes
.../250-new-project/080-maven-profiles.png | Bin 0 -> 9922 bytes
.../250-new-project/090-maven-coordinates.png | Bin 0 -> 13546 bytes
.../100-annotation-processing.png | Bin 0 -> 54602 bytes
.../250-new-project/110-parameter8.png | Bin 0 -> 41948 bytes
.../120-clean-generate-sources.png | Bin 0 -> 5988 bytes
.../010-configuring-the-compiler.png | Bin 0 -> 40826 bytes
.../ldap/activeds-ldap-groups.png | Bin 0 -> 128224 bytes
.../ldap/activeds-ldap-mojo-partition.png | Bin 0 -> 123256 bytes
.../ldap/activeds-ldap-mojo-root-dse.png | Bin 0 -> 113723 bytes
.../ldap/activeds-ldap-sasl-authentication.png | Bin 0 -> 119544 bytes
.../ldap/activeds-ldap-users.png | Bin 0 -> 123030 bytes
.../philosophy/hexagonal-architecture.png | Bin 0 -> 85844 bytes
.../philosophy/hexagonal-architecture.pptx | Bin 0 -> 263812 bytes
.../simpleapp-webapp-with-fixtures.png | Bin 0 -> 36797 bytes
.../images/getting-started/simpleapp-webapp.png | Bin 0 -> 33311 bytes
.../using-simple-app/010-root-page.png | Bin 0 -> 70336 bytes
.../020-login-to-wicket-viewer.png | Bin 0 -> 38080 bytes
.../030-home-page-run-fixture-scripts.png | Bin 0 -> 48682 bytes
.../using-simple-app/040-first-object.png | Bin 0 -> 38474 bytes
.../using-simple-app/050-update-name-prompt.png | Bin 0 -> 47597 bytes
.../using-simple-app/060-object-updated.png | Bin 0 -> 39452 bytes
.../using-simple-app/070-list-all-prompt.png | Bin 0 -> 42560 bytes
.../using-simple-app/080-list-all.png | Bin 0 -> 36487 bytes
.../using-simple-app/090-create.png | Bin 0 -> 41232 bytes
.../using-simple-app/100-create-prompt.png | Bin 0 -> 44741 bytes
.../using-simple-app/110-object-created.png | Bin 0 -> 39691 bytes
.../using-simple-app/120-list-all.png | Bin 0 -> 37239 bytes
.../220-login-to-restful-viewer.png | Bin 0 -> 72319 bytes
.../using-simple-app/230-home-page.png | Bin 0 -> 74329 bytes
.../using-simple-app/240-list-all-invoke.png | Bin 0 -> 78260 bytes
.../using-simple-app/250-list-all-results.png | Bin 0 -> 89138 bytes
.../BackgroundCommandExecution.png | Bin 0 -> 26916 bytes
...ExecutionFromBackgroundCommandServiceJdo.png | Bin 0 -> 38373 bytes
.../hexagonal-architecture-addons.png | Bin 0 -> 128533 bytes
.../tips-n-tricks/are-you-sure-happy-case.png | Bin 0 -> 9993 bytes
.../tips-n-tricks/are-you-sure-sad-case.png | Bin 0 -> 10515 bytes
.../how-tos/tips-n-tricks/are-you-sure.png | Bin 0 -> 9312 bytes
.../cust-order-product.png | Bin 0 -> 11125 bytes
.../ActionLayout/bookmarking.png | Bin 0 -> 93128 bytes
.../ActionLayout/position-BELOW.png | Bin 0 -> 8122 bytes
.../ActionLayout/position-PANEL.png | Bin 0 -> 6912 bytes
.../ActionLayout/position-PANEL_DROPDOWN.png | Bin 0 -> 9009 bytes
.../ActionLayout/position-RIGHT.png | Bin 0 -> 9430 bytes
.../CollectionLayout/sortedby-dependencies.png | Bin 0 -> 23917 bytes
.../DomainObjectLayout/bookmarking-nested.png | Bin 0 -> 103969 bytes
.../DomainObjectLayout/bookmarking.png | Bin 0 -> 93128 bytes
.../DomainServiceLayout/menuBar-primary.png | Bin 0 -> 115609 bytes
.../DomainServiceLayout/menuBar-secondary.png | Bin 0 -> 124133 bytes
.../DomainServiceLayout/menuBar-tertiary.png | Bin 0 -> 112894 bytes
.../DomainServiceLayout/menuOrder.png | Bin 0 -> 44876 bytes
.../reference-annotations/HomePage/HomePage.png | Bin 0 -> 134848 bytes
.../PropertyLayout/labelPosition-LEFT.png | Bin 0 -> 1534 bytes
.../PropertyLayout/labelPosition-NONE.png | Bin 0 -> 3367 bytes
.../PropertyLayout/labelPosition-TOP.png | Bin 0 -> 2355 bytes
.../labelPosition-boolean-LEFT.png | Bin 0 -> 6037 bytes
.../labelPosition-boolean-RIGHT.png | Bin 0 -> 5818 bytes
.../guides/images/reference-layout/4-0-8-0.png | Bin 0 -> 20662 bytes
.../guides/images/reference-layout/4-4-4-12.png | Bin 0 -> 21012 bytes
.../guides/images/reference-layout/6-6-0-12.png | Bin 0 -> 21100 bytes
.../isis-layout-show-facets.css | 3 +
.../images/reference-layout/isis-layout.css | 253 +++++++
.../images/reference-layout/layout-4-0-8-0.html | 198 ++++++
.../reference-layout/layout-4-4-4-12.html | 205 ++++++
.../reference-layout/layout-6-6-0-12.html | 203 ++++++
.../prefixes/choices/dependent.png | Bin 0 -> 71875 bytes
.../reserved/cssClass/strikethrough.png | Bin 0 -> 134835 bytes
.../reserved/iconName/differing.pdn | Bin 0 -> 28973 bytes
.../reserved/iconName/differing.png | Bin 0 -> 9326 bytes
.../reserved/iconName/png-files.png | Bin 0 -> 2843 bytes
.../ContentNegotiationService/accept-json.png | Bin 0 -> 80775 bytes
.../ContentNegotiationService/accept-xml.png | Bin 0 -> 94207 bytes
.../facade-choices.png | Bin 0 -> 16635 bytes
.../facade-choices.pptx | Bin 0 -> 46685 bytes
.../action-invocation-published-to-stderr.png | Bin 0 -> 22377 bytes
.../changed-object-published-to-stderr.png | Bin 0 -> 16645 bytes
.../PublishingService/yuml.me-23db58a4.png | Bin 0 -> 96892 bytes
.../service-collaborations.png | Bin 0 -> 10368 bytes
.../service-collaborations.pptx | Bin 0 -> 52460 bytes
.../UserProfileService/todoapp.png | Bin 0 -> 65234 bytes
.../party-agreementrole-agreement.png | Bin 0 -> 10310 bytes
.../configure-isis-to-use-bypass.PNG | Bin 0 -> 12091 bytes
.../configure-isis-to-use-shiro.png | Bin 0 -> 11356 bytes
...configure-shiro-to-use-custom-jdbc-realm.png | Bin 0 -> 33149 bytes
.../configure-shiro-to-use-ini-realm.PNG | Bin 0 -> 29914 bytes
.../configure-shiro-to-use-isis-ldap-realm.PNG | Bin 0 -> 32310 bytes
...ecurity-module-realm-with-delegate-realm.PNG | Bin 0 -> 45089 bytes
...-to-use-isisaddons-security-module-realm.PNG | Bin 0 -> 38713 bytes
.../security-apis-impl/security-apis-impl.pptx | Bin 0 -> 56892 bytes
.../testing/fixture-scripts/composite.png | Bin 0 -> 24021 bytes
.../images/testing/fixture-scripts/flat-1.png | Bin 0 -> 22627 bytes
.../images/testing/fixture-scripts/flat-2.png | Bin 0 -> 10212 bytes
.../organizing-fixture-scripts.pptx | Bin 0 -> 56572 bytes
.../prompt-specifying-number.png | Bin 0 -> 53895 bytes
.../images/testing/fixture-scripts/prompt.png | Bin 0 -> 52869 bytes
.../fixture-scripts/prototyping-menu.png | Bin 0 -> 59183 bytes
.../result-list-specifying-number.png | Bin 0 -> 63100 bytes
.../testing/fixture-scripts/result-list.png | Bin 0 -> 50272 bytes
.../guides/images/testing/integ-tests.png | Bin 0 -> 19263 bytes
.../guides/images/testing/integ-tests.pptx | Bin 0 -> 50694 bytes
.../guides/images/testing/wrapper-factory.png | Bin 0 -> 16094 bytes
.../tutorials/pet-clinic/010-01-login-page.png | Bin 0 -> 31965 bytes
.../tutorials/pet-clinic/010-02-home-page.png | Bin 0 -> 54415 bytes
.../pet-clinic/010-03-prototyping-menu.png | Bin 0 -> 59183 bytes
.../pet-clinic/010-04-simpleobjects.png | Bin 0 -> 57805 bytes
.../pet-clinic/010-05-simpleobject-list.png | Bin 0 -> 29631 bytes
.../pet-clinic/020-01-idea-configuration.png | Bin 0 -> 35012 bytes
.../pet-clinic/020-02-idea-configuration.png | Bin 0 -> 7430 bytes
.../030-01-idea-configuration-updated.png | Bin 0 -> 35122 bytes
.../tutorials/pet-clinic/030-02-updated-app.png | Bin 0 -> 32215 bytes
.../040-01-idea-configuration-updated.png | Bin 0 -> 35349 bytes
.../tutorials/pet-clinic/050-01-list-all.png | Bin 0 -> 33299 bytes
.../tutorials/pet-clinic/050-02-view-pet.png | Bin 0 -> 34270 bytes
.../tutorials/pet-clinic/060-01-owners-menu.png | Bin 0 -> 65309 bytes
.../tutorials/pet-clinic/060-02-owners-list.png | Bin 0 -> 31905 bytes
.../tutorials/pet-clinic/060-03-pets-list.png | Bin 0 -> 36166 bytes
.../060-04-pet-owner-autoComplete.png | Bin 0 -> 40468 bytes
.../tutorials/pet-clinic/domain-model.png | Bin 0 -> 27464 bytes
.../wicket-viewer/about-page/about-page.png | Bin 0 -> 59612 bytes
.../wicket-viewer/application-menu/dividers.png | Bin 0 -> 22657 bytes
.../application-menu/layout-menus.pdn | Bin 0 -> 97348 bytes
.../application-menu/layout-menus.png | Bin 0 -> 50330 bytes
.../wicket-viewer/application-menu/tertiary.png | Bin 0 -> 11491 bytes
.../bookmarked-pages/panel-940.png | Bin 0 -> 99602 bytes
.../bookmarked-pages/panel-estatio-940.png | Bin 0 -> 136219 bytes
.../bookmarked-pages/panel-estatio.png | Bin 0 -> 172961 bytes
.../wicket-viewer/bookmarked-pages/panel.png | Bin 0 -> 121632 bytes
.../brand-logo/brand-logo-signin.png | Bin 0 -> 40644 bytes
.../wicket-viewer/brand-logo/brand-logo.png | Bin 0 -> 74471 bytes
.../copy-link/010-copy-link-button-940.png | Bin 0 -> 162348 bytes
.../copy-link/010-copy-link-button.png | Bin 0 -> 180619 bytes
.../copy-link/020-copy-link-dialog-940.png | Bin 0 -> 137995 bytes
.../copy-link/020-copy-link-dialog.png | Bin 0 -> 151995 bytes
.../wicket-viewer/copy-link/030-hints-940.png | Bin 0 -> 152386 bytes
.../wicket-viewer/copy-link/030-hints.png | Bin 0 -> 170567 bytes
.../copy-link/040-copy-link-with-hints-940.png | Bin 0 -> 132720 bytes
.../copy-link/040-copy-link-with-hints.png | Bin 0 -> 156147 bytes
.../copy-link/050-title-url-940.png | Bin 0 -> 143541 bytes
.../wicket-viewer/copy-link/050-title-url.png | Bin 0 -> 105989 bytes
.../wicket-viewer/embedded-view/no-footer.png | Bin 0 -> 72940 bytes
.../embedded-view/no-header-no-footer.png | Bin 0 -> 67630 bytes
.../wicket-viewer/embedded-view/no-header.png | Bin 0 -> 70717 bytes
.../wicket-viewer/embedded-view/regular.png | Bin 0 -> 76211 bytes
.../010-attachment-field-940.png | Bin 0 -> 96945 bytes
.../010-attachment-field.png | Bin 0 -> 111347 bytes
.../020-edit-choose-file-940.png | Bin 0 -> 98472 bytes
.../020-edit-choose-file.png | Bin 0 -> 113234 bytes
.../030-choose-file-using-browser-520.png | Bin 0 -> 88615 bytes
.../030-choose-file-using-browser.png | Bin 0 -> 241045 bytes
.../040-edit-chosen-file-indicated-940.png | Bin 0 -> 98163 bytes
.../040-edit-chosen-file-indicated.png | Bin 0 -> 113800 bytes
.../050-ok-if-image-then-rendered-940.png | Bin 0 -> 129718 bytes
.../050-ok-if-image-then-rendered.png | Bin 0 -> 245863 bytes
.../file-upload-download/060-download-940.png | Bin 0 -> 138702 bytes
.../file-upload-download/060-download.png | Bin 0 -> 249736 bytes
.../file-upload-download/070-edit-clear-940.png | Bin 0 -> 99377 bytes
.../file-upload-download/070-edit-clear.png | Bin 0 -> 114433 bytes
.../wicket-viewer/layouts/estatio-Invoice.png | Bin 0 -> 181572 bytes
.../wicket-viewer/layouts/estatio-Lease.png | Bin 0 -> 261553 bytes
.../wicket-viewer/layouts/estatio-LeaseItem.png | Bin 0 -> 162789 bytes
.../wicket-viewer/layouts/todoapp-ToDoItem.png | Bin 0 -> 97649 bytes
.../recent-pages/recent-pages-940.png | Bin 0 -> 166966 bytes
.../wicket-viewer/recent-pages/recent-pages.png | Bin 0 -> 186541 bytes
.../login-page-default.png | Bin 0 -> 11372 bytes
.../login-page-suppress-password-reset.png | Bin 0 -> 10615 bytes
.../suppress-remember-me/login-page-default.png | Bin 0 -> 11372 bytes
.../login-page-suppress-remember-me.png | Bin 0 -> 10935 bytes
.../suppress-sign-up/login-page-default.png | Bin 0 -> 11372 bytes
.../login-page-suppress-sign-up.png | Bin 0 -> 10273 bytes
.../wicket-viewer/theme-chooser/example-1.png | Bin 0 -> 88088 bytes
.../wicket-viewer/theme-chooser/example-2.png | Bin 0 -> 76430 bytes
.../user-registration/login-page-default.png | Bin 0 -> 11372 bytes
.../sign-up-after-registration.png | Bin 0 -> 45653 bytes
.../sign-up-email-with-verification-link.png | Bin 0 -> 11960 bytes
.../sign-up-login-page-after-sign-up.png | Bin 0 -> 13570 bytes
.../user-registration/sign-up-page.png | Bin 0 -> 8911 bytes
.../sign-up-registration-page.png | Bin 0 -> 11446 bytes
.../Pawson-Naked-Objects-thesis.pdf | Bin 0 -> 2082131 bytes
.../src/main/asciidoc/guides/rg.adoc | 14 +
.../src/main/asciidoc/guides/ug.adoc | 27 +
.../src/main/asciidoc/how-isis-works.adoc | 2 +-
.../src/main/asciidoc/powered-by.adoc | 7 +-
.../src/main/asciidoc/release-notes.adoc | 192 +++++-
.../asciidoc/release-process-one-pager.adoc | 16 +-
.../src/main/asciidoc/screencasts.adoc | 6 +-
.../src/main/asciidoc/simpleapp-archetype.adoc | 4 +-
.../asciidoc/user-guide/_ug_appendices.adoc | 11 -
...g_appendices_articles-and-presentations.adoc | 125 ----
.../user-guide/_ug_appendices_dev-env.adoc | 12 -
.../_ug_appendices_dev-env_cmd-line.adoc | 9 -
.../_ug_appendices_dev-env_eclipse.adoc | 136 ----
.../_ug_appendices_dev-env_intellij.adoc | 374 ----------
.../_ug_appendices_migration-notes.adoc | 563 ---------------
.../_ug_appendices_release-notes.adoc | 127 ----
.../asciidoc/user-guide/_ug_core-concepts.adoc | 22 -
.../user-guide/_ug_core-concepts_add-ons.adoc | 35 -
.../_ug_core-concepts_building-blocks.adoc | 93 ---
...re-concepts_framework-provided-services.adoc | 54 --
..._core-concepts_other-deployment-options.adoc | 81 ---
.../_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 | 80 ---
...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 -
.../_ug_core-concepts_principles.adoc | 16 -
...core-concepts_principles_apache-isis-vs.adoc | 36 -
...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 | 37 -
.../asciidoc/user-guide/_ug_deployment.adoc | 19 -
.../user-guide/_ug_deployment_cmd-line.adoc | 30 -
...g_deployment_externalized-configuration.adoc | 9 -
.../asciidoc/user-guide/_ug_deployment_gae.adoc | 48 --
.../user-guide/_ug_deployment_jvm-flags.adoc | 9 -
.../user-guide/_ug_deployment_neo4j.adoc | 59 --
.../user-guide/_ug_deployment_tomcat.adoc | 35 -
.../main/asciidoc/user-guide/_ug_extending.adoc | 14 -
.../_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 | 44 --
.../_ug_extending_restfulobjects-viewer.adoc | 51 --
.../user-guide/_ug_extending_wicket-viewer.adoc | 26 -
...ng_wicket-viewer_custom-bootstrap-theme.adoc | 34 -
...ug_extending_wicket-viewer_custom-pages.adoc | 92 ---
...ng_wicket-viewer_isis-addons-extensions.adoc | 17 -
...g_wicket-viewer_replacing-page-elements.adoc | 167 -----
.../user-guide/_ug_getting-started.adoc | 37 -
...ug_getting-started_datanucleus-enhancer.adoc | 107 ---
..._ug_getting-started_simpleapp-archetype.adoc | 300 --------
.../user-guide/_ug_headless-access.adoc | 27 -
...less-access_AbstractIsisSessionTemplate.adoc | 40 --
...dless-access_BackgroundCommandExecution.adoc | 45 --
.../main/asciidoc/user-guide/_ug_how-tos.adoc | 20 -
.../user-guide/_ug_how-tos_business-rules.adoc | 72 --
.../user-guide/_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 | 283 --------
.../_ug_how-tos_contributed-members.adoc | 69 --
.../asciidoc/user-guide/_ug_how-tos_crud.adoc | 29 -
.../user-guide/_ug_how-tos_derived-members.adoc | 48 --
.../user-guide/_ug_how-tos_domain-services.adoc | 164 -----
.../_ug_how-tos_drop-downs-and-defaults.adoc | 65 --
.../_ug_how-tos_entity-relationships.adoc | 15 -
...aged-1-to-m-bidirectional-relationships.adoc | 58 --
.../user-guide/_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 --
.../user-guide/_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 ---
.../user-guide/_ug_isis-maven-plugin.adoc | 9 -
.../asciidoc/user-guide/_ug_more-advanced.adoc | 26 -
.../_ug_more-advanced_bulk-actions.adoc | 8 -
.../_ug_more-advanced_decoupling.adoc | 26 -
..._more-advanced_decoupling_contributions.adoc | 8 -
..._ug_more-advanced_decoupling_db-schemas.adoc | 151 ----
.../_ug_more-advanced_decoupling_event-bus.adoc | 11 -
...ore-advanced_decoupling_pushing-changes.adoc | 140 ----
...-advanced_decoupling_vetoing-visibility.adoc | 15 -
.../user-guide/_ug_more-advanced_i18n.adoc | 378 ----------
.../_ug_more-advanced_mapping-rdbms-views.adoc | 9 -
.../_ug_more-advanced_multi-tenancy.adoc | 8 -
...ore-advanced_overriding-jdo-annotations.adoc | 55 --
..._ug_more-advanced_persistence-lifecycle.adoc | 8 -
.../_ug_more-advanced_tips-n-tricks.adoc | 15 -
...ore-advanced_tips-n-tricks_are-you-sure.adoc | 55 --
...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 -
.../_ug_more-advanced_view-models.adoc | 22 -
.../user-guide/_ug_reference-annotations.adoc | 63 --
.../_ug_reference-annotations_aaa.adoc | 17 -
...ug_reference-annotations_aaa_deprecated.adoc | 342 ----------
.../_ug_reference-annotations_aaa_jdo.adoc | 113 ---
.../_ug_reference-annotations_aaa_jee.adoc | 59 --
.../_ug_reference-annotations_aaa_main.adoc | 103 ---
.../_ug_reference-annotations_aaa_other.adoc | 57 --
.../_ug_reference-annotations_aaa_partial.adoc | 92 ---
...ug_reference-annotations_manpage-Action.adoc | 134 ----
...erence-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 ---
...ence-annotations_manpage-Action_command.adoc | 134 ----
...-annotations_manpage-Action_domainEvent.adoc | 146 ----
...rence-annotations_manpage-Action_hidden.adoc | 49 --
...nce-annotations_manpage-Action_invokeOn.adoc | 64 --
...e-annotations_manpage-Action_publishing.adoc | 53 --
...e-annotations_manpage-Action_restrictTo.adoc | 30 -
...ce-annotations_manpage-Action_semantics.adoc | 36 -
...rence-annotations_manpage-Action_typeOf.adoc | 31 -
...eference-annotations_manpage-Collection.adoc | 106 ---
...ce-annotations_manpage-CollectionLayout.adoc | 121 ----
...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 | 158 -----
...-annotations_manpage-Collection_editing.adoc | 48 --
...e-annotations_manpage-Collection_hidden.adoc | 54 --
...tations_manpage-Collection_notPersisted.adoc | 57 --
...e-annotations_manpage-Collection_typeOf.adoc | 26 -
...ug_reference-annotations_manpage-Column.adoc | 154 -----
...ug_reference-annotations_manpage-Digits.adoc | 35 -
...rence-annotations_manpage-Discriminator.adoc | 59 --
...erence-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 | 76 ---
...nnotations_manpage-DomainObject_bounded.adoc | 36 -
...nnotations_manpage-DomainObject_editing.adoc | 61 --
...annotations_manpage-DomainObject_nature.adoc | 59 --
...tations_manpage-DomainObject_objectType.adoc | 46 --
...tations_manpage-DomainObject_publishing.adoc | 49 --
...rence-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 -
...ug_reference-annotations_manpage-Facets.adoc | 15 -
..._reference-annotations_manpage-HomePage.adoc | 52 --
...ug_reference-annotations_manpage-Inject.adoc | 110 ---
...e-annotations_manpage-MemberGroupLayout.adoc | 20 -
...ference-annotations_manpage-MemberOrder.adoc | 25 -
...reference-annotations_manpage-MinLength.adoc | 32 -
...rence-annotations_manpage-NotPersistent.adoc | 18 -
...reference-annotations_manpage-Parameter.adoc | 96 ---
...nce-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 | 50 --
...notations_manpage-Parameter_optionality.adoc | 36 -
...otations_manpage-Parameter_regexPattern.adoc | 31 -
...-annotations_manpage-PersistenceCapable.adoc | 90 ---
...rence-annotations_manpage-PostConstruct.adoc | 66 --
...eference-annotations_manpage-PreDestroy.adoc | 50 --
...eference-annotations_manpage-PrimaryKey.adoc | 19 -
...erence-annotations_manpage-Programmatic.adoc | 27 -
..._reference-annotations_manpage-Property.adoc | 125 ----
...ence-annotations_manpage-PropertyLayout.adoc | 135 ----
...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 | 150 ----
...ce-annotations_manpage-Property_editing.adoc | 43 --
...nce-annotations_manpage-Property_hidden.adoc | 66 --
...-annotations_manpage-Property_maxLength.adoc | 49 --
...nnotations_manpage-Property_mustSatisfy.adoc | 46 --
...notations_manpage-Property_notPersisted.adoc | 61 --
...nnotations_manpage-Property_optionality.adoc | 129 ----
...notations_manpage-Property_regexPattern.adoc | 28 -
...rence-annotations_manpage-RequestScoped.adoc | 50 --
..._ug_reference-annotations_manpage-Title.adoc | 38 --
...reference-annotations_manpage-ViewModel.adoc | 44 --
...nce-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 -
.../user-guide/_ug_reference-classes.adoc | 14 -
.../_ug_reference-classes_mixins.adoc | 56 --
...classes_mixins_manpage-HasTransactionId.adoc | 9 -
...ence-classes_mixins_manpage-HasUserName.adoc | 9 -
.../user-guide/_ug_reference-classes_super.adoc | 136 ----
...s_super_manpage-AbstractContainedObject.adoc | 9 -
...asses_super_manpage-AbstractDomainEvent.adoc | 9 -
...sses_super_manpage-AbstractDomainObject.adoc | 9 -
...ses_super_manpage-AbstractDomainService.adoc | 9 -
...er_manpage-AbstractFactoryAndRepository.adoc | 9 -
...e-classes_super_manpage-AbstractService.adoc | 9 -
...classes_super_manpage-AbstractViewModel.adoc | 9 -
...classes_super_manpage-ActionDomainEvent.adoc | 9 -
...ses_super_manpage-CollectionDomainEvent.adoc | 9 -
...nce-classes_super_manpage-FixtureScript.adoc | 9 -
...ce-classes_super_manpage-FixtureScripts.adoc | 9 -
...asses_super_manpage-PropertyDomainEvent.adoc | 9 -
.../_ug_reference-classes_utility.adoc | 15 -
...reference-classes_utility_manpage-Enums.adoc | 8 -
...classes_utility_manpage-ObjectContracts.adoc | 107 ---
...ference-classes_utility_manpage-Reasons.adoc | 31 -
...nce-classes_utility_manpage-TitleBuffer.adoc | 13 -
.../_ug_reference-classes_value-types.adoc | 119 ----
...erence-classes_value-types_manpage-Blob.adoc | 8 -
...erence-classes_value-types_manpage-Clob.adoc | 8 -
...rence-classes_value-types_manpage-Color.adoc | 9 -
...rence-classes_value-types_manpage-Money.adoc | 8 -
...ce-classes_value-types_manpage-Password.adoc | 8 -
.../user-guide/_ug_reference-methods.adoc | 17 -
.../_ug_reference-methods_lifecycle.adoc | 99 ---
..._ug_reference-methods_lifecycle_jdo-api.adoc | 50 --
...rence-methods_lifecycle_manpage-created.adoc | 11 -
...erence-methods_lifecycle_manpage-loaded.adoc | 10 -
...nce-methods_lifecycle_manpage-persisted.adoc | 12 -
...ce-methods_lifecycle_manpage-persisting.adoc | 12 -
...rence-methods_lifecycle_manpage-removed.adoc | 12 -
...ence-methods_lifecycle_manpage-removing.adoc | 12 -
...rence-methods_lifecycle_manpage-updated.adoc | 14 -
...ence-methods_lifecycle_manpage-updating.adoc | 10 -
.../_ug_reference-methods_prefixes.adoc | 219 ------
...eference-methods_prefixes_manpage-addTo.adoc | 37 -
...e-methods_prefixes_manpage-autoComplete.adoc | 91 ---
...erence-methods_prefixes_manpage-choices.adoc | 143 ----
...eference-methods_prefixes_manpage-clear.adoc | 32 -
...erence-methods_prefixes_manpage-default.adoc | 129 ----
...erence-methods_prefixes_manpage-disable.adoc | 93 ---
..._reference-methods_prefixes_manpage-get.adoc | 19 -
...reference-methods_prefixes_manpage-hide.adoc | 82 ---
...ference-methods_prefixes_manpage-modify.adoc | 37 -
...nce-methods_prefixes_manpage-removeFrom.adoc | 37 -
..._reference-methods_prefixes_manpage-set.adoc | 13 -
...rence-methods_prefixes_manpage-validate.adoc | 113 ---
...-methods_prefixes_manpage-validateAddTo.adoc | 45 --
...ods_prefixes_manpage-validateRemoveFrom.adoc | 45 --
.../_ug_reference-methods_reserved.adoc | 58 --
...rence-methods_reserved_manpage-cssClass.adoc | 46 --
...erence-methods_reserved_manpage-disable.adoc | 102 ---
...eference-methods_reserved_manpage-getId.adoc | 19 -
...reference-methods_reserved_manpage-hide.adoc | 39 --
...rence-methods_reserved_manpage-iconName.adoc | 36 -
...eference-methods_reserved_manpage-title.adoc | 65 --
...rence-methods_reserved_manpage-validate.adoc | 27 -
.../user-guide/_ug_reference-object-layout.adoc | 20 -
...eference-object-layout_application-menu.adoc | 171 -----
.../_ug_reference-object-layout_dynamic.adoc | 113 ---
...ference-object-layout_static-vs-dynamic.adoc | 26 -
.../_ug_reference-object-layout_static.adoc | 159 -----
.../user-guide/_ug_reference-services-api.adoc | 282 --------
...ces-api_manpage-ActionInvocationContext.adoc | 98 ---
...-services-api_manpage-BackgroundService.adoc | 123 ----
...roundService_BackgroundCommandExecution.adoc | 25 -
...es-api_manpage-BackgroundService_Quartz.adoc | 162 -----
...ce-services-api_manpage-BookmarkService.adoc | 117 ----
...ices-api_manpage-BulkInteractionContext.adoc | 9 -
...rence-services-api_manpage-ClockService.adoc | 104 ---
...nce-services-api_manpage-CommandContext.adoc | 217 ------
...ce-services-api_manpage-DeepLinkService.adoc | 57 --
...vices-api_manpage-DomainObjectContainer.adoc | 43 --
...nObjectContainer_generic-repository-api.adoc | 89 ---
...page-DomainObjectContainer_messages-api.adoc | 50 --
...mainObjectContainer_object-creation-api.adoc | 40 --
...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 -
...rence-services-api_manpage-EmailService.adoc | 98 ---
...ce-services-api_manpage-EventBusService.adoc | 381 -----------
...-services-api_manpage-GuiceBeanProvider.adoc | 90 ---
...nce-services-api_manpage-IsisJdoSupport.adoc | 276 --------
...nce-services-api_manpage-MementoService.adoc | 131 ----
...e-services-api_manpage-MetamodelService.adoc | 42 --
...-services-api_manpage-QueryResultsCache.adoc | 127 ----
...ference-services-api_manpage-ScratchPad.adoc | 127 ----
...erence-services-api_manpage-SudoService.adoc | 68 --
...nce-services-api_manpage-WrapperFactory.adoc | 162 -----
...services-api_manpage-XmlSnapshotService.adoc | 214 ------
.../user-guide/_ug_reference-services-spi.adoc | 270 --------
...ce-services-spi_manpage-AuditingService.adoc | 84 ---
...es-spi_manpage-BackgroundCommandService.adoc | 129 ----
...vices-spi_manpage-ClassDiscoveryService.adoc | 81 ---
...nce-services-spi_manpage-CommandService.adoc | 99 ---
...vices-spi_manpage-ContentMappingService.adoc | 106 ---
...s-spi_manpage-ContentNegotiationService.adoc | 189 -----
...es-spi_manpage-EmailNotificationService.adoc | 80 ---
...ce-services-spi_manpage-EventSerializer.adoc | 72 --
...ervices-spi_manpage-ExceptionRecognizer.adoc | 123 ----
...nce-services-spi_manpage-LocaleProvider.adoc | 71 --
...-services-spi_manpage-PublishingService.adoc | 163 -----
...vices-spi_manpage-RepresentationService.adoc | 106 ---
...services-spi_manpage-TranslationService.adoc | 79 ---
...rvices-spi_manpage-TranslationsResolver.adoc | 67 --
...services-spi_manpage-UserProfileService.adoc | 44 --
...ces-spi_manpage-UserRegistrationService.adoc | 81 ---
.../user-guide/_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 | 81 ---
.../main/asciidoc/user-guide/_ug_runtime.adoc | 29 -
.../_ug_runtime_application-specific.adoc | 13 -
...me_application-specific_application-css.adoc | 8 -
...ime_application-specific_application-js.adoc | 9 -
.../_ug_runtime_configuration-files.adoc | 36 -
.../_ug_runtime_configuring-core.adoc | 239 -------
.../_ug_runtime_configuring-datanucleus.adoc | 18 -
...s_disabling-persistence-by-reachability.adoc | 88 ---
...atanucleus_eagerly-registering-entities.adoc | 44 --
...configuring-datanucleus_persistence-xml.adoc | 10 -
...time_configuring-datanucleus_properties.adoc | 64 --
...ring-datanucleus_using-jndi-data-source.adoc | 75 --
.../_ug_runtime_deployment-types.adoc | 12 -
.../_ug_runtime_specifying-components.adoc | 72 --
.../user-guide/_ug_runtime_web-xml.adoc | 35 -
.../main/asciidoc/user-guide/_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 ---
.../user-guide/_ug_security_shiro-caching.adoc | 41 --
.../_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 -
.../_ug_security_shiro-jdbc-realm.adoc | 113 ---
.../_ug_security_usage-by-isis-viewers.adoc | 208 ------
.../main/asciidoc/user-guide/_ug_testing.adoc | 17 -
.../asciidoc/user-guide/_ug_testing_aaa.adoc | 166 -----
.../_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 ----
.../user-guide/_ug_testing_fixture-scripts.adoc | 44 --
...g_testing_fixture-scripts_api-and-usage.adoc | 286 --------
...ug_testing_fixture-scripts_sudo-service.adoc | 59 --
.../_ug_testing_integ-test-support.adoc | 24 -
...esting_integ-test-support_bootstrapping.adoc | 231 -------
..._integ-test-support_maven-configuration.adoc | 46 --
...esting_integ-test-support_typical-usage.adoc | 124 ----
...ting_integ-test-support_wrapper-factory.adoc | 162 -----
.../_ug_testing_unit-test-support.adoc | 13 -
...esting_unit-test-support_contract-tests.adoc | 171 -----
...ting_unit-test-support_jmock-extensions.adoc | 59 --
...g_unit-test-support_maven-configuration.adoc | 46 --
.../user-guide/_ug_troubleshooting.adoc | 14 -
.../_ug_troubleshooting_enabling-logging.adoc | 39 --
.../main/asciidoc/user-guide/_ug_tutorials.adoc | 18 -
.../user-guide/_ug_tutorials_pet-clinic.adoc | 557 ---------------
...tutorials_stop-scaffolding-start-coding.adoc | 684 -------------------
.../asciidoc/user-guide/_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 --
.../_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 | 109 ---
..._customisation_using-different-css-file.adoc | 36 -
...icket-viewer_customisation_welcome-page.adoc | 42 --
.../user-guide/_ug_wicket-viewer_features.adoc | 26 -
...wicket-viewer_features_bookmarked-pages.adoc | 107 ---
...et-viewer_features_file-upload-download.adoc | 121 ----
...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 ---
.../_ug_wicket-viewer_isis-addons.adoc | 33 -
.../user-guide/_ug_wicket-viewer_layout.adoc | 97 ---
.../_ug_wicket-viewer_request-parameters.adoc | 53 --
.../src/main/asciidoc/user-guide/_ug_xxx.adoc | 1 -
.../eclipse/eclipse-010-windows-preferences.png | Bin 37417 -> 0 bytes
.../eclipse/eclipse-025-project-properties.png | Bin 76584 -> 0 bytes
.../eclipse/eclipse-100-project-support.png | Bin 54952 -> 0 bytes
.../eclipse/eclipse-110-project-support.png | Bin 53218 -> 0 bytes
.../dev-env/eclipse/eclipse-120-console.png | Bin 12887 -> 0 bytes
.../eclipse-200-enhancer-fails-duplicates.png | Bin 47581 -> 0 bytes
.../eclipse-210-enhancer-fails-duplicates.png | Bin 11776 -> 0 bytes
.../eclipse-220-enhancer-fails-duplicates.png | Bin 54752 -> 0 bytes
.../010-installing/010-welcome-page.png | Bin 29192 -> 0 bytes
.../010-installing/020-choose-location.png | Bin 24433 -> 0 bytes
.../010-installing/030-installation-options.png | Bin 18300 -> 0 bytes
.../010-installing/040-start-menu-folder.png | Bin 26120 -> 0 bytes
.../010-installing/050-completing.png | Bin 26499 -> 0 bytes
.../060-import-settings-or-not.png | Bin 11691 -> 0 bytes
.../010-installing/070-set-ui-theme.png | Bin 87739 -> 0 bytes
.../010-new-project-create.png | Bin 14048 -> 0 bytes
.../020-java-project-setup-jdk.png | Bin 29837 -> 0 bytes
.../030-java-project-select-jdk.png | Bin 16597 -> 0 bytes
.../020-create-new-project/040-sdk-selected.png | Bin 24884 -> 0 bytes
.../050-name-and-location.png | Bin 11407 -> 0 bytes
.../020-create-new-project/060-create-dir.png | Bin 8424 -> 0 bytes
.../010-settings-import-jar.png | Bin 24084 -> 0 bytes
.../030-import-settings/020-select-all.png | Bin 8863 -> 0 bytes
.../030-import-settings/030-restart.png | Bin 8209 -> 0 bytes
.../010-maven-installation.png | Bin 43353 -> 0 bytes
.../020-maven-configuration.png | Bin 53554 -> 0 bytes
.../030-build-automatically.png | Bin 50767 -> 0 bytes
.../040-other-settings/040-auto-import.png | Bin 31963 -> 0 bytes
.../050-some-plugins/010-some-plugins.png | Bin 45812 -> 0 bytes
.../020-some-plugins-confirmation.png | Bin 35687 -> 0 bytes
.../010-maven-modules-view.png | Bin 103134 -> 0 bytes
.../020-adding-another-module.png | Bin 23846 -> 0 bytes
.../030-other-module-added.png | Bin 111516 -> 0 bytes
.../040-ignoring-modules.png | Bin 120475 -> 0 bytes
.../050-ignoring-modules-2.png | Bin 17050 -> 0 bytes
.../060-ignored-modules.png | Bin 92428 -> 0 bytes
.../010-run-configuration.png | Bin 34826 -> 0 bytes
.../020-datanucleus-enhancer-goal.png | Bin 8491 -> 0 bytes
.../030-running-unit-tests.png | Bin 29351 -> 0 bytes
...040-running-unit-tests-run-configuration.png | Bin 37582 -> 0 bytes
...ning-integration-tests-run-configuration.png | Bin 40655 -> 0 bytes
.../010-file-project-structure.png | Bin 19261 -> 0 bytes
.../200-project-sdk/020-select-jdk.png | Bin 43375 -> 0 bytes
.../030-select-jdk-directory.png | Bin 20740 -> 0 bytes
.../200-project-sdk/040-set-project-level.png | Bin 40868 -> 0 bytes
.../050-isis-language-level-7.png | Bin 53883 -> 0 bytes
.../060-app-language-level-8.png | Bin 58257 -> 0 bytes
.../250-new-project/010-new-project.png | Bin 20564 -> 0 bytes
.../250-new-project/020-new-project-name.png | Bin 11273 -> 0 bytes
.../030-new-project-new-window.png | Bin 9785 -> 0 bytes
.../040-new-module-from-existing-sources.png | Bin 27953 -> 0 bytes
.../050-specify-source-folder.png | Bin 23884 -> 0 bytes
.../250-new-project/060-import-using-maven.png | Bin 11739 -> 0 bytes
.../070-import-module-settings.png | Bin 36175 -> 0 bytes
.../250-new-project/080-maven-profiles.png | Bin 9922 -> 0 bytes
.../250-new-project/090-maven-coordinates.png | Bin 13546 -> 0 bytes
.../100-annotation-processing.png | Bin 54602 -> 0 bytes
.../250-new-project/110-parameter8.png | Bin 41948 -> 0 bytes
.../120-clean-generate-sources.png | Bin 5988 -> 0 bytes
.../010-configuring-the-compiler.png | Bin 40826 -> 0 bytes
.../ldap/activeds-ldap-groups.png | Bin 128224 -> 0 bytes
.../ldap/activeds-ldap-mojo-partition.png | Bin 123256 -> 0 bytes
.../ldap/activeds-ldap-mojo-root-dse.png | Bin 113723 -> 0 bytes
.../ldap/activeds-ldap-sasl-authentication.png | Bin 119544 -> 0 bytes
.../ldap/activeds-ldap-users.png | Bin 123030 -> 0 bytes
.../philosophy/hexagonal-architecture.png | Bin 85844 -> 0 bytes
.../philosophy/hexagonal-architecture.pptx | Bin 263812 -> 0 bytes
.../simpleapp-webapp-with-fixtures.png | Bin 36797 -> 0 bytes
.../images/getting-started/simpleapp-webapp.png | Bin 33311 -> 0 bytes
.../using-simple-app/010-root-page.png | Bin 70336 -> 0 bytes
.../020-login-to-wicket-viewer.png | Bin 38080 -> 0 bytes
.../030-home-page-run-fixture-scripts.png | Bin 48682 -> 0 bytes
.../using-simple-app/040-first-object.png | Bin 38474 -> 0 bytes
.../using-simple-app/050-update-name-prompt.png | Bin 47597 -> 0 bytes
.../using-simple-app/060-object-updated.png | Bin 39452 -> 0 bytes
.../using-simple-app/070-list-all-prompt.png | Bin 42560 -> 0 bytes
.../using-simple-app/080-list-all.png | Bin 36487 -> 0 bytes
.../using-simple-app/090-create.png | Bin 41232 -> 0 bytes
.../using-simple-app/100-create-prompt.png | Bin 44741 -> 0 bytes
.../using-simple-app/110-object-created.png | Bin 39691 -> 0 bytes
.../using-simple-app/120-list-all.png | Bin 37239 -> 0 bytes
.../220-login-to-restful-viewer.png | Bin 72319 -> 0 bytes
.../using-simple-app/230-home-page.png | Bin 74329 -> 0 bytes
.../using-simple-app/240-list-all-invoke.png | Bin 78260 -> 0 bytes
.../using-simple-app/250-list-all-results.png | Bin 89138 -> 0 bytes
.../BackgroundCommandExecution.png | Bin 26916 -> 0 bytes
...ExecutionFromBackgroundCommandServiceJdo.png | Bin 38373 -> 0 bytes
.../hexagonal-architecture-addons.png | Bin 128533 -> 0 bytes
.../tips-n-tricks/are-you-sure-happy-case.png | Bin 9993 -> 0 bytes
.../tips-n-tricks/are-you-sure-sad-case.png | Bin 10515 -> 0 bytes
.../how-tos/tips-n-tricks/are-you-sure.png | Bin 9312 -> 0 bytes
.../cust-order-product.png | Bin 11125 -> 0 bytes
.../ActionLayout/bookmarking.png | Bin 93128 -> 0 bytes
.../ActionLayout/position-BELOW.png | Bin 8122 -> 0 bytes
.../ActionLayout/position-PANEL.png | Bin 6912 -> 0 bytes
.../ActionLayout/position-PANEL_DROPDOWN.png | Bin 9009 -> 0 bytes
.../ActionLayout/position-RIGHT.png | Bin 9430 -> 0 bytes
.../CollectionLayout/sortedby-dependencies.png | Bin 23917 -> 0 bytes
.../DomainObjectLayout/bookmarking-nested.png | Bin 103969 -> 0 bytes
.../DomainObjectLayout/bookmarking.png | Bin 93128 -> 0 bytes
.../DomainServiceLayout/menuBar-primary.png | Bin 115609 -> 0 bytes
.../DomainServiceLayout/menuBar-secondary.png | Bin 124133 -> 0 bytes
.../DomainServiceLayout/menuBar-tertiary.png | Bin 112894 -> 0 bytes
.../DomainServiceLayout/menuOrder.png | Bin 44876 -> 0 bytes
.../reference-annotations/HomePage/HomePage.png | Bin 134848 -> 0 bytes
.../PropertyLayout/labelPosition-LEFT.png | Bin 1534 -> 0 bytes
.../PropertyLayout/labelPosition-NONE.png | Bin 3367 -> 0 bytes
.../PropertyLayout/labelPosition-TOP.png | Bin 2355 -> 0 bytes
.../labelPosition-boolean-LEFT.png | Bin 6037 -> 0 bytes
.../labelPosition-boolean-RIGHT.png | Bin 5818 -> 0 bytes
.../images/reference-layout/4-0-8-0.png | Bin 20662 -> 0 bytes
.../images/reference-layout/4-4-4-12.png | Bin 21012 -> 0 bytes
.../images/reference-layout/6-6-0-12.png | Bin 21100 -> 0 bytes
.../isis-layout-show-facets.css | 3 -
.../images/reference-layout/isis-layout.css | 253 -------
.../images/reference-layout/layout-4-0-8-0.html | 198 ------
.../reference-layout/layout-4-4-4-12.html | 205 ------
.../reference-layout/layout-6-6-0-12.html | 203 ------
.../prefixes/choices/dependent.png | Bin 71875 -> 0 bytes
.../reserved/cssClass/strikethrough.png | Bin 134835 -> 0 bytes
.../reserved/iconName/differing.pdn | Bin 28973 -> 0 bytes
.../reserved/iconName/differing.png | Bin 9326 -> 0 bytes
.../reserved/iconName/png-files.png | Bin 2843 -> 0 bytes
.../ContentNegotiationService/accept-json.png | Bin 80775 -> 0 bytes
.../ContentNegotiationService/accept-xml.png | Bin 94207 -> 0 bytes
.../facade-choices.png | Bin 16635 -> 0 bytes
.../facade-choices.pptx | Bin 46685 -> 0 bytes
.../action-invocation-published-to-stderr.png | Bin 22377 -> 0 bytes
.../changed-object-published-to-stderr.png | Bin 16645 -> 0 bytes
.../PublishingService/yuml.me-23db58a4.png | Bin 96892 -> 0 bytes
.../service-collaborations.png | Bin 10368 -> 0 bytes
.../service-collaborations.pptx | Bin 52460 -> 0 bytes
.../UserProfileService/todoapp.png | Bin 65234 -> 0 bytes
.../party-agreementrole-agreement.png | Bin 10310 -> 0 bytes
.../configure-isis-to-use-bypass.PNG | Bin 12091 -> 0 bytes
.../configure-isis-to-use-shiro.png | Bin 11356 -> 0 bytes
...configure-shiro-to-use-custom-jdbc-realm.png | Bin 33149 -> 0 bytes
.../configure-shiro-to-use-ini-realm.PNG | Bin 29914 -> 0 bytes
.../configure-shiro-to-use-isis-ldap-realm.PNG | Bin 32310 -> 0 bytes
...ecurity-module-realm-with-delegate-realm.PNG | Bin 45089 -> 0 bytes
...-to-use-isisaddons-security-module-realm.PNG | Bin 38713 -> 0 bytes
.../security-apis-impl/security-apis-impl.pptx | Bin 56892 -> 0 bytes
.../testing/fixture-scripts/composite.png | Bin 24021 -> 0 bytes
.../images/testing/fixture-scripts/flat-1.png | Bin 22627 -> 0 bytes
.../images/testing/fixture-scripts/flat-2.png | Bin 10212 -> 0 bytes
.../organizing-fixture-scripts.pptx | Bin 56572 -> 0 bytes
.../prompt-specifying-number.png | Bin 53895 -> 0 bytes
.../images/testing/fixture-scripts/prompt.png | Bin 52869 -> 0 bytes
.../fixture-scripts/prototyping-menu.png | Bin 59183 -> 0 bytes
.../result-list-specifying-number.png | Bin 63100 -> 0 bytes
.../testing/fixture-scripts/result-list.png | Bin 50272 -> 0 bytes
.../user-guide/images/testing/integ-tests.png | Bin 19263 -> 0 bytes
.../user-guide/images/testing/integ-tests.pptx | Bin 50694 -> 0 bytes
.../images/testing/wrapper-factory.png | Bin 16094 -> 0 bytes
.../tutorials/pet-clinic/010-01-login-page.png | Bin 31965 -> 0 bytes
.../tutorials/pet-clinic/010-02-home-page.png | Bin 54415 -> 0 bytes
.../pet-clinic/010-03-prototyping-menu.png | Bin 59183 -> 0 bytes
.../pet-clinic/010-04-simpleobjects.png | Bin 57805 -> 0 bytes
.../pet-clinic/010-05-simpleobject-list.png | Bin 29631 -> 0 bytes
.../pet-clinic/020-01-idea-configuration.png | Bin 35012 -> 0 bytes
.../pet-clinic/020-02-idea-configuration.png | Bin 7430 -> 0 bytes
.../030-01-idea-configuration-updated.png | Bin 35122 -> 0 bytes
.../tutorials/pet-clinic/030-02-updated-app.png | Bin 32215 -> 0 bytes
.../040-01-idea-configuration-updated.png | Bin 35349 -> 0 bytes
.../tutorials/pet-clinic/050-01-list-all.png | Bin 33299 -> 0 bytes
.../tutorials/pet-clinic/050-02-view-pet.png | Bin 34270 -> 0 bytes
.../tutorials/pet-clinic/060-01-owners-menu.png | Bin 65309 -> 0 bytes
.../tutorials/pet-clinic/060-02-owners-list.png | Bin 31905 -> 0 bytes
.../tutorials/pet-clinic/060-03-pets-list.png | Bin 36166 -> 0 bytes
.../060-04-pet-owner-autoComplete.png | Bin 40468 -> 0 bytes
.../tutorials/pet-clinic/domain-model.png | Bin 27464 -> 0 bytes
.../wicket-viewer/about-page/about-page.png | Bin 59612 -> 0 bytes
.../wicket-viewer/application-menu/dividers.png | Bin 22657 -> 0 bytes
.../application-menu/layout-menus.pdn | Bin 97348 -> 0 bytes
.../application-menu/layout-menus.png | Bin 50330 -> 0 bytes
.../wicket-viewer/application-menu/tertiary.png | Bin 11491 -> 0 bytes
.../bookmarked-pages/panel-940.png | Bin 99602 -> 0 bytes
.../bookmarked-pages/panel-estatio-940.png | Bin 136219 -> 0 bytes
.../bookmarked-pages/panel-estatio.png | Bin 172961 -> 0 bytes
.../wicket-viewer/bookmarked-pages/panel.png | Bin 121632 -> 0 bytes
.../brand-logo/brand-logo-signin.png | Bin 40644 -> 0 bytes
.../wicket-viewer/brand-logo/brand-logo.png | Bin 74471 -> 0 bytes
.../copy-link/010-copy-link-button-940.png | Bin 162348 -> 0 bytes
.../copy-link/010-copy-link-button.png | Bin 180619 -> 0 bytes
.../copy-link/020-copy-link-dialog-940.png | Bin 137995 -> 0 bytes
.../copy-link/020-copy-link-dialog.png | Bin 151995 -> 0 bytes
.../wicket-viewer/copy-link/030-hints-940.png | Bin 152386 -> 0 bytes
.../wicket-viewer/copy-link/030-hints.png | Bin 170567 -> 0 bytes
.../copy-link/040-copy-link-with-hints-940.png | Bin 132720 -> 0 bytes
.../copy-link/040-copy-link-with-hints.png | Bin 156147 -> 0 bytes
.../copy-link/050-title-url-940.png | Bin 143541 -> 0 bytes
.../wicket-viewer/copy-link/050-title-url.png | Bin 105989 -> 0 bytes
.../wicket-viewer/embedded-view/no-footer.png | Bin 72940 -> 0 bytes
.../embedded-view/no-header-no-footer.png | Bin 67630 -> 0 bytes
.../wicket-viewer/embedded-view/no-header.png | Bin 70717 -> 0 bytes
.../wicket-viewer/embedded-view/regular.png | Bin 76211 -> 0 bytes
.../010-attachment-field-940.png | Bin 96945 -> 0 bytes
.../010-attachment-field.png | Bin 111347 -> 0 bytes
.../020-edit-choose-file-940.png | Bin 98472 -> 0 bytes
.../020-edit-choose-file.png | Bin 113234 -> 0 bytes
.../030-choose-file-using-browser-520.png | Bin 88615 -> 0 bytes
.../030-choose-file-using-browser.png | Bin 241045 -> 0 bytes
.../040-edit-chosen-file-indicated-940.png | Bin 98163 -> 0 bytes
.../040-edit-chosen-file-indicated.png | Bin 113800 -> 0 bytes
.../050-ok-if-image-then-rendered-940.png | Bin 129718 -> 0 bytes
.../050-ok-if-image-then-rendered.png | Bin 245863 -> 0 bytes
.../file-upload-download/060-download-940.png | Bin 138702 -> 0 bytes
.../file-upload-download/060-download.png | Bin 249736 -> 0 bytes
.../file-upload-download/070-edit-clear-940.png | Bin 99377 -> 0 bytes
.../file-upload-download/070-edit-clear.png | Bin 114433 -> 0 bytes
.../wicket-viewer/layouts/estatio-Invoice.png | Bin 181572 -> 0 bytes
.../wicket-viewer/layouts/estatio-Lease.png | Bin 261553 -> 0 bytes
.../wicket-viewer/layouts/estatio-LeaseItem.png | Bin 162789 -> 0 bytes
.../wicket-viewer/layouts/todoapp-ToDoItem.png | Bin 97649 -> 0 bytes
.../recent-pages/recent-pages-940.png | Bin 166966 -> 0 bytes
.../wicket-viewer/recent-pages/recent-pages.png | Bin 186541 -> 0 bytes
.../login-page-default.png | Bin 11372 -> 0 bytes
.../login-page-suppress-password-reset.png | Bin 10615 -> 0 bytes
.../suppress-remember-me/login-page-default.png | Bin 11372 -> 0 bytes
.../login-page-suppress-remember-me.png | Bin 10935 -> 0 bytes
.../suppress-sign-up/login-page-default.png | Bin 11372 -> 0 bytes
.../login-page-suppress-sign-up.png | Bin 10273 -> 0 bytes
.../wicket-viewer/theme-chooser/example-1.png | Bin 88088 -> 0 bytes
.../wicket-viewer/theme-chooser/example-2.png | Bin 76430 -> 0 bytes
.../user-registration/login-page-default.png | Bin 11372 -> 0 bytes
.../sign-up-after-registration.png | Bin 45653 -> 0 bytes
.../sign-up-email-with-verification-link.png | Bin 11960 -> 0 bytes
.../sign-up-login-page-after-sign-up.png | Bin 13570 -> 0 bytes
.../user-registration/sign-up-page.png | Bin 8911 -> 0 bytes
.../sign-up-registration-page.png | Bin 11446 -> 0 bytes
.../Pawson-Naked-Objects-thesis.pdf | Bin 2082131 -> 0 bytes
.../src/main/asciidoc/user-guide/ug.adoc | 35 -
adocs/pom.xml | 2 +
1310 files changed, 29200 insertions(+), 29284 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/monitor.rb
----------------------------------------------------------------------
diff --git a/adocs/documentation/monitor.rb b/adocs/documentation/monitor.rb
index 8d9516f..cc81251 100644
--- a/adocs/documentation/monitor.rb
+++ b/adocs/documentation/monitor.rb
@@ -134,7 +134,7 @@ lastTimeGenerated = Time.now - 10
#
if processAll then
- files = Dir.glob("src/main/asciidoc/**")
+ files = Dir.glob("src/main/asciidoc/**/*")
puts ""
puts ""
@@ -164,7 +164,11 @@ puts ""
#
# then continue monitoring all directories
#
-directories = Dir.glob("src/main/asciidoc/**/")
+adocFiles = Dir.glob("src/main/asciidoc/**/*.adoc")
+directories = adocFiles.each{ |f| File.new(f) }.uniq{ |f| File.dirname(f) }.map{ |f| File.dirname(f) }
+
+puts "listening to: #{directories}"
+
fileListener = Listen.to(directories) do |modified, added, removed|
unless modified.length==0
modified.each { |file|
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/play.rb
----------------------------------------------------------------------
diff --git a/adocs/documentation/play.rb b/adocs/documentation/play.rb
new file mode 100644
index 0000000..daaaaa1
--- /dev/null
+++ b/adocs/documentation/play.rb
@@ -0,0 +1,24 @@
+require 'rubygems'
+require 'pathname'
+require 'fileutils'
+require 'bundler/setup'
+require "slop"
+require 'launchy'
+require 'webrick'
+
+Bundler.require(:default)
+
+include WEBrick
+
+# to (try to) suppress some debugs
+$CELLULOID_DEBUG=false
+$CELLULOID_TEST=false
+
+
+
+adocFiles = Dir.glob("src/main/asciidoc/**/*.adoc")
+
+files = adocFiles.each{ |f| File.new(f) }.uniq{ |f| File.dirname(f) }.map{ |f| File.dirname(f) }
+
+puts "listening to: #{files}"
+
[06/45] isis git commit: ISIS-1133: breaking out reference guide and
devenv guide;
moving appendices' release notes and migration notes to other docs;
improving the documentation page.
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_deployment-types.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_deployment-types.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_deployment-types.adoc
deleted file mode 100644
index efc3d0d..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_deployment-types.adoc
+++ /dev/null
@@ -1,12 +0,0 @@
-[[_ug_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/
-
-
-
-IMPORTANT: TODO - xref:_ug_reference-annotations_manpage-Action_restrictTo[`@Action#restrictTo()`]
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_specifying-components.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_specifying-components.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_specifying-components.adoc
deleted file mode 100644
index d38191f..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_specifying-components.adoc
+++ /dev/null
@@ -1,72 +0,0 @@
-[[_ug_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/
-
-
-
-The `isis.properties` file has four configuration properties in particular that specify the major components of Isis to use.
-
-They are:
-
-.Core Configuration Properties
-[cols="2a,1,3a", options="header"]
-|===
-|Property
-|Value +
-(_default value_)
-|Implements
-
-|`isis.authentication`
-|`shiro`, `bypass`, `FQCN` +
-(`_shiro_`)
-|`o.a.i.core.runtime.authentication.` `AuthenticationManagerInstaller`
-
-|`isis.authorization`
-|`shiro`, `bypass`, `FQCN` +
-(`_shiro_`)
-|`o.a.i.core.runtime.authorization.` `AuthorizationManagerInstaller`
-
-|`isis.persistor`
-|`datanucleus`, `inmemory`, `FQCN` +
-(`_datanucleus_`)
-|`o.a.i.core.runtime.installerregistry.installerapi.` `PersistenceMechanismInstaller`
-
-|`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.
-
-
-
-|===
-
-[TIP]
-====
-The values "datanucleus", "shiro" etc are actually aliases for concrete implementations listed in 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 any of these components. This is probably feasible for the two security APIs and the `services-installer` API; but replacing the persistor (JDO/DataNucleus) is much trickier because we rely on the JDO/DN for certain functionality (such as object dirtying and lazy loading) that is not defined within this API.
-
-As for the viewers, these are specified indirectly by way of the filters and servlets in the `web.xml` file (discussed xref:_ug_runtime_web-xml[below]). However, the configuration of which viewers to initialize is declared through 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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_web-xml.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_web-xml.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_web-xml.adoc
deleted file mode 100644
index 5c91c24..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_web-xml.adoc
+++ /dev/null
@@ -1,35 +0,0 @@
-[[_ug_runtime_web-xml]]
-= `web.xml`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-IMPORTANT: TODO
-
-
-== Init Params
-
-`<isis.viewers>`
-
-
-
-
-== Filters
-
-IMPORTANT: TODO
-
-
-
-
-== Servlets
-
-IMPORTANT: TODO
-
-
-
-
-== Running RO Viewer only
-
-IMPORTANT: TODO
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_security.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security.adoc
deleted file mode 100644
index 38f2caa..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security.adoc
+++ /dev/null
@@ -1,53 +0,0 @@
-[[_ug_security]]
-= Security
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 has built-in support for authentication and authorization:
-
-* By "authentication" we mean logging into the application using some credentials, typically a username and password. Authentication also means looking up the set of roles to which a user belongs.
-
-* By "authorization" we mean permissions: granting roles to have access to features (object member) of the app.
-
-Isis has two levels of permissions. _Read_ permission means that the user can view the object member; it will be rendered in the UI. An action with only read permission will be shown disabled ("greyed out". _Write_ permission means that the object member can be changed. For actions this means that they can be invoked.
-
-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_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. Isis in turn extends this with its `IsisLdapRealm`, which provides more flexibility for both group/role and role/permissions management.
-
-In addition, the (non-ASF) link:http://www.isisaddons.org[Isis Addons] provides the http://github.com/isisaddons/isis-module-security[Isis addons' security] module, which also provides an implementation of the Shiro `Realm` API. However, the security module also represents users, roles and permissions as domain objects, allowing them to be administered through Isis itself. Moreover, the security module can optionally delegate password management to a subsidiary (delegate) realm (usually LDAP as discussed above).
-
-In addition to Isis' Shiro-based implementation of its authentication and authorization APIs, Isis also provides a "bypass" implementation, useful for quick-n-dirty prototyping when you want to in effect disable (bypass) security completely.
-
-[NOTE]
-.What about auditing?
-====
-A further aspect of security is auditing: recording what data was modified by which user. Apache Isis does define two service APIs -- xref:_ug_reference-services-spi_manpage-CommandService[`CommandService`] and xref:_ug_reference-services-spi_manpage-AuditingService[`AuditingService`] -- that provide hooks to track which actions (commands) are invoked, and what data was modified as a result (auditing).
-
-Isis does not itself provide any in-built implementations of these APIs, but there are implementations within (non-ASF) link:http://www.isisaddons.org[Isis Addons], namely the http://github.com/isisaddons/isis-module-command[Isis addons' command] module and the http://github.com/isisaddons/isis-module-audit[Isis addons' auditing] module.
-====
-
-
-
-include::_ug_security_configuring-isis-to-use-shiro.adoc[leveloffset=+1]
-
-include::_ug_security_shiro-ini-realm.adoc[leveloffset=+1]
-
-include::_ug_security_shiro-isis-ldap-realm.adoc[leveloffset=+1]
-
-include::_ug_security_shiro-isisaddons-security-module-realm.adoc[leveloffset=+1]
-
-include::_ug_security_shiro-jdbc-realm.adoc[leveloffset=+1]
-
-include::_ug_security_shiro-isis-enhanced-wildcard-permission.adoc[leveloffset=+1]
-
-include::_ug_security_configuring-isis-to-use-bypass.adoc[leveloffset=+1]
-
-include::_ug_security_api-for-applications.adoc[leveloffset=+1]
-
-include::_ug_security_usage-by-isis-viewers.adoc[leveloffset=+1]
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_api-for-applications.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_api-for-applications.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_api-for-applications.adoc
deleted file mode 100644
index 39b445c..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_api-for-applications.adoc
+++ /dev/null
@@ -1,63 +0,0 @@
-[[_ug_security_api-for-applications]]
-= API for 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/
-
-
-
-Generally speaking your domain objects (or more generally your application) should be agnostic of the user/roles that are interacting with them; applying security permissions is the responsibility of the framework.
-
-Still, on very rare occasion you may have a need, in which case you can either use Isis' `DomainObjectContainer` API or you can reach further down the stack and use the JEE Servlet API.
-
-
-== `DomainObjectContainer` API
-
-The xref:_ug_reference-services-api_manpage-DomainObjectContainer[`DomainObjectContainer`] service exposes the following API:
-
-[source,java]
-----
-final UserMemento user = container.getUser();
-final List<RoleMemento> roles = user.getRoles();
-for (RoleMemento role : roles) {
- String roleName = role.getName();
- ...
-}
-----
-
-Each role's `name` property encodes both the realm that provided the role, and the role identity itself.
-
-For example, in the simpleapp, if logging in as `dick` with the following entries for `realm1`:
-
-[source,ini]
-----
-dick = pass, user_role, analysis_role, self-install_role
-----
-
-then this corresponds to the roles "realm1:user_role", "realm1:self-install_role" and "realm1:analysis_role".
-
-If using the Wicket viewer, then note there will also be another role which is used internally (namely "org.apache.isis.viewer.wicket.roles.USER").
-
-
-
-
-
-== Servlet API
-
-On occasion you may find it necessary to reach below Isis and to the underlying servlet API. For example, the http://github.com/isisaddons/isis-module-togglz[Isis addons' togglz] module (non-ASF) has a requirement to do this in order to expose its embedded togglz web console. (
-
-[TIP]
-====
-If you do need to access the servlet API and are running within the context of Wicket viewer, the http://github.com/isisaddons/isis-module-servletapi[Isis addons' servletapi] module can provide access to the `HttpServletRequest`, `HttpServletResponse` and `ServletContext`.
-====
-
-In this situation, you can still obtain some information about the user and its roles:
-
-[source,java]
-----
-Principal principal = httpServletRequest.getPrincipal();
-String username = principal.getName();
-boolean analyst = httpServletRequest.isUserInRole("analysis_role");
-----
-
-However, it isn't possible to obtain any role permissions for the user.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_configuring-isis-to-use-bypass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_configuring-isis-to-use-bypass.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_configuring-isis-to-use-bypass.adoc
deleted file mode 100644
index 277b0fb..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_configuring-isis-to-use-bypass.adoc
+++ /dev/null
@@ -1,23 +0,0 @@
-[[_ug_security_configuring-isis-to-use-bypass]]
-= Bypassing security
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 bypass security component consists of an implementation of both the `AuthenticationManager` and `AuthorizationManager` APIs, and are intended for prototyping use only.
-
-The authentication manager allows access with any credentials (in a sense, "bypassing" authentication), while the authorization manager provides access to all class members (in a sense, "bypassing" authorization).
-
-
-To tell Apache Isis to bypass security, just update the `WEB-INF/isis.properties` file:
-
-[source,ini]
-----
-isis.authentication=bypass
-isis.authorization=bypass
-----
-
-This installs the appropriate no-op implementations for both authentication and authorization:
-
-image::{_imagesdir}security/security-apis-impl/configure-isis-to-use-bypass.png[width="600px"]
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_configuring-isis-to-use-shiro.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_configuring-isis-to-use-shiro.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_configuring-isis-to-use-shiro.adoc
deleted file mode 100644
index 155305c..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_configuring-isis-to-use-shiro.adoc
+++ /dev/null
@@ -1,76 +0,0 @@
-[[_ug_security_configuring-isis-to-use-shiro]]
-= Configuring Isis to use Shiro
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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' security mechanism is configurable, specifying an `Authenticator` and an `Authorizor` (non-public) APIs. The Shiro security mechanism is an integration wih Apache Shiro that implements both interfaces.
-
-[TIP]
-====
-The xref:_ug_getting-started_simpleapp-archetype[SimpleApp archetype] is pre-configured to use Apache Shiro, so much of what follows is set up already.
-====
-
-== Telling Isis to use Shiro
-
-To tell Apache Isis to use Shiro, update the `WEB-INF/isis.properties` file:
-
-[source,ini]
-----
-isis.authentication=shiro
-isis.authorization=shiro
-----
-
-This installs the appropriate implementation (the `ShiroAuthenticatorOrAuthorizor` class) that use Shiro's APIs to perform authentication and authorization:
-
-image::{_imagesdir}security/security-apis-impl/configure-isis-to-use-shiro.png[width="600px"]
-
-The figure above doesn't tell the whole story; we haven't yet seen how Shiro itself is configured to use realms. The `ShiroAuthenticatorOrAuthorizor` is in essence the glue between the Isis runtime and Shiro.
-
-== Bootstrapping Shiro
-
-The Shiro environment (in essence, thread-locals holding the security credentials) needs to be bootstrapped using the following settings in the `WEB-INF/web.xml` file:
-
-[source,xml]
-----
-<listener>
- <listener-class>org.apache.shiro.web.env.EnvironmentLoaderListener</listener-class>
-</listener>
-<filter>
- <filter-name>ShiroFilter</filter-name>
- <filter-class>org.apache.shiro.web.servlet.ShiroFilter</filter-class>
-</filter>
-<filter-mapping>
- <filter-name>ShiroFilter</filter-name>
- <url-pattern>/*</url-pattern>
-</filter-mapping>
-----
-
-Based on this Shiro will then read `WEB-INF/shiro.ini` file to configure its Realm definitions for authentication and authorization.
-
-
-
-== `WEB-INF/shiro.ini`
-
-The `shiro.ini` file is used to specify the realm(s) that Shiro will delegate to:
-
-[source,ini]
-----
-securityManager.realms = $realmName
-----
-
-Shiro's ini file supports a "poor-man's" dependency injection (link:https://shiro.apache.org/configuration.html[their words]), and so `$realmName` in the above example is a reference to a realm defined elsewhere in `shiro.ini`. The subsequent sections describe the specifics for thevarious realm implementations available to you.
-
-
-It's also possible to configure Shiro to support multiple realms.
-
-[source,ini]
-----
-securityManager.realms = $realm1,$realm2
-----
-
-You can learn more about Shiro realms in the link:http://shiro.apache.org/realm.html[Shiro documentation].
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-caching.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-caching.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-caching.adoc
deleted file mode 100644
index c3b37a1..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-caching.adoc
+++ /dev/null
@@ -1,41 +0,0 @@
-[[_ug_security_shiro-caching]]
-= Caching and other Shiro 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/
-
-
-We don't want to repeat the entire link:http://shiro.apache.org/documentation.html[Shiro documentation set] here, but we should flag a number of otherof other features that are worth checking out.
-
-
-
-
-== Caching
-
-To ensure that security operations does not impede performance, Shiro supports caching. For example, this sets up a simple memory-based cache manager:
-
-[source,ini]
-----
-memoryCacheManager = org.apache.shiro.cache.MemoryConstrainedCacheManager
-securityManager.cacheManager = $memoryCacheManager
-----
-
-Other implementations can be plugged in; see the Shiro link:http://shiro.apache.org/caching.html[documentation] for further details.
-
-
-
-
-== Further Reading
-
-
-* Shiro's documentation page can be found link:http://shiro.apache.org/documentation.html[here].
-
-* community-contributed articles can be found link:http://shiro.apache.org/articles.html[here]. +
-+
-These include for instance link:http://meri-stuff.blogspot.co.uk/2011/04/apache-shiro-part-2-realms-database-and.html[this interesting article] describing how to perform certificate-based authentication (ie login using Google or Facebook credentials).
-
-
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-ini-realm.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-ini-realm.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-ini-realm.adoc
deleted file mode 100644
index b69f2c7..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-ini-realm.adoc
+++ /dev/null
@@ -1,133 +0,0 @@
-[[_ug_security_shiro-ini-realm]]
-= Shiro Ini Realm
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-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_getting-started_simpleapp-archetype[SimpleApp archetype] is configured to use this realm.
-
-The diagram below shows the Isis and components involved:
-
-image::{_imagesdir}security/security-apis-impl/configure-shiro-to-use-ini-realm.png[width="600px"]
-
-The realm is responsible for validating the user credentials, and then creates a Shiro link:http://shiro.apache.org/static/latest/apidocs/org/apache/shiro/subject/Subject.html[`Subject`] which represents the user (for the current request). Isis `Authenticator` component then interacts with the `Subject` in order to check permissions.
-
-
-
-
-== Shiro Configuration
-
-To use the built-in `IniRealm`, we add the following to `WEB-INF/shiro.ini`:
-
-[source,ini]
-----
-securityManager.realms = $iniRealm
-----
-
-(Unlike other realms) there is no need to "define" `$iniRealm`; it is automatically available to us.
-
-Specifying `$iniRealm` means that the usernames/passwords, roles and permissions are read from the `shiro.ini` file itself. Specifically:
-
-* the users/passwords and their roles from the `[users]` sections;
-* the roles are mapped to permissions in the `[roles]` section.
-
-The format of these is described below.
-
-=== `[users]` section
-
-This section lists users, passwords and their roles.
-
-For example:
-
-[source,ini]
-----
-sven = pass, admin_role
-dick = pass, user_role, analysis_role, self-install_role
-bob = pass, user_role, self-install_role
-----
-The first value is the password (eg "pass", the remaining values are the role(s).
-
-
-=== `[roles]` section
-
-This section lists roles and their corresponding permissions.
-
-For example:
-
-[source,ini]
-----
-user_role = *:ToDoItems:*:*,\
- *:ToDoItem:*:*,\
- *:ToDoAppDashboard:*:*
-analysis_role = *:ToDoItemAnalysis:*:*,\
- *:ToDoItemsByCategoryViewModel:*:*,\
- *:ToDoItemsByDateRangeViewModel:*:*
-self-install_role = *:ToDoItemsFixturesService:install:*
-admin_role = *
-----
-
-The value is a comma-separated list of permissions for the role. The format is:
-
-[source,ini]
-----
-packageName:className:memberName:r,w
-----
-
-where:
-
-* `memberName` is the property, collection or action name.
-* `r` indicates that the member is visible
-* `w` indicates that the member is usable (editable or invokable)
-
-and where each of the parts of the permission string can be wildcarded using `*`.
-
-Because these are wildcards, a '*' can be used at any level. Additionally, missing levels assume wildcards.
-
-Thus:
-
-[source,ini]
-----
-com.mycompany.myapp:Customer:firstName:r,w # view or edit customer's firstName
-com.mycompany.myapp:Customer:lastName:r # view customer's lastName only
-com.mycompany.myapp:Customer:placeOrder:* # view and invoke placeOrder action
-com.mycompany.myapp:Customer:placeOrder # ditto
-com.mycompany.myapp:Customer:*:r # view all customer class members
-com.mycompany.myapp:*:*:r # view-only access for all classes in myapp package
-com.mycompany.myapp:*:*:* # view/edit for all classes in myapp package
-com.mycompany.myapp:*:* # ditto
-com.mycompany.myapp:* # ditto
-com.mycompany.myapp # ditto
-* # view/edit access to everything
-----
-
-[TIP]
-====
-The format of the permissions string is configurable in Shiro, and Isis uses this to provide an extended wildcard format, described xref:_ug_security_shiro-isis-enhanced-wildcard-permission[here].
-====
-
-
-
-
-== Externalized IniRealm
-
-There's no requirement for all users/roles to be defined in the `shiro.ini` file. Instead, a realm can be defined that loads its users/roles from some other resource.
-
-For example:
-
-[source,ini]
-----
-$realm1=org.apache.shiro.realm.text.IniRealm # <1>
-realm1.resourcePath=classpath:webapp/realm1.ini # <2>
-----
-<1> happens to (coincidentally) be the link:http://shiro.apache.org/static/latest/apidocs/org/apache/shiro/realm/text/IniRealm.html[same implementation] as Shiro's built-in $iniRealm
-<2> in this case load the users/roles from the `src/main/resources/webapp/realm1.ini` file.
-
-Note that a URL could be provided as the `resourcePath`, so a centralized config file could be used. Even so, the
-
-[NOTE]
-====
-If configured this way then the `[users]` and `[roles]` sections of `shiro.ini` become unused. Instead, the corresponding sections from for `realm1.ini` are used instead.
-====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-isis-enhanced-wildcard-permission.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-isis-enhanced-wildcard-permission.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-isis-enhanced-wildcard-permission.adoc
deleted file mode 100644
index d20e94f..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-isis-enhanced-wildcard-permission.adoc
+++ /dev/null
@@ -1,61 +0,0 @@
-[[_ug_security_shiro-isis-enhanced-wildcard-permission]]
-= Enhanced Wildcard Permission
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 using the text-based xref:_ug_security_shiro-ini-realm[`IniRealm`] or xref:_ug_security_shiro-isis-ldap-realm[Isis' LDAP realm], then note that Shiro also allows the string representation of the permissions to be mapped (resolved) to alternative `Permission` instances. Isis provides its own `IsisPermission` which introduces the concept of a "veto".
-
-A vetoing permission is one that prevents access to a feature, rather than grants it. This is useful in some situations where most users have access to most features, and only a small number of features are particularly sensitive. The configuration can therefore be set up to grant fairly broad-brush permissions and then veto permission for the sensitive features for those users that do not have access.
-
-The string representation of the `IsisPermission` uses the following format:
-
-[source,ini]
-----
-([!]?)([^/]+)[/](.+)
-----
-
-where:
-
-* the optional `!` prefix indicates this permission is a vetoing permission
-* the optional `xxx/` prefix is a permission group that scopes any vetoing permissions
-* the remainder of the string is the permission (possibly wildcarded, with :rw as optional suffix)
-
-
-For example:
-
-[source,ini]
-----
-user_role = !reg/org.estatio.api,\
- !reg/org.estatio.webapp.services.admin,\
- reg/* ; \
-api_role = org.estatio.api ;\
-admin_role = adm/*
-----
-
-sets up:
-
-* the `user_role` with access to all permissions except those in `org.estatio.api` and `org.estatio.webapp.services.admin`
-* the `api_role` with access to all permissions in `org.estatio.api`
-* the `admin_role` with access to everything.
-
-The permission group concept is required to scope the applicability of any veto permission. This is probably best explained by an example. Suppose that a user has both `admin_role` and `user_role`; we would want the `admin_role` to trump the vetos of the `user_role`, in other words to give the user access to everything.
-
-
-Because of the permission groups, the two "+++!reg/...+""" vetos in user_role only veto out selected permissions granted by the "+++reg/*+++" permissions, but they do not veto the permissions granted by a different scope, namely "+++adm/*+++".
-
-The net effect is therefore what we would want: that a user with both `admin_role` and `user_role` would have access to everything, irrespective of those two veto permissions of the `user_role`.
-
-
-
-Finally, the Isis permission resolver is specified in `WEB-INF/shiro.ini` file:
-
-[source,ini]
-----
-permissionResolver = org.apache.isis.security.shiro.authorization.IsisPermissionResolver
-myRealm.permissionResolver = $permissionResolver # <1>
-----
-<1> `myRealm` is the handle to the configured realm, eg `$iniRealm` or `$isisLdapRealm` etc.
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-isis-ldap-realm.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-isis-ldap-realm.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-isis-ldap-realm.adoc
deleted file mode 100644
index a7feadc..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-isis-ldap-realm.adoc
+++ /dev/null
@@ -1,146 +0,0 @@
-[[_ug_security_shiro-isis-ldap-realm]]
-= Isis Ldap Realm
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 ships with an implementation of http://shiro.apache.org[Apache Shiro]'s `Realm` class that allows user authentication and authorization to be performed against an LDAP server.
-
-image::{_imagesdir}security/security-apis-impl/configure-shiro-to-use-isis-ldap-realm.png[width="600px"]
-
-The LDAP database stores the user/passwords and user groups, while the `shiro.ini` file is used to map the LDAP groups to roles, and to map the roles to permissions.
-
-== Shiro Configuration
-
-To use LDAP involves telling Shiro how to instantiate the realm. This bootstrapping info lives in the `WEB-INF/shiro.ini`:
-
-[source,ini]
-----
-contextFactory = org.apache.isis.security.shiro.IsisLdapContextFactory
-contextFactory.url = ldap://localhost:10389
-contextFactory.systemUsername = uid=admin,ou=system # <1>
-contextFactory.systemPassword = secret
-contextFactory.authenticationMechanism = CRAM-MD5 # <2>
-contextFactory.systemAuthenticationMechanism = simple
-
-ldapRealm = org.apache.isis.security.shiro.IsisLdapRealm # <3>
-ldapRealm.contextFactory = $contextFactory
-
-ldapRealm.searchBase = ou=groups,o=mojo # <4>
-ldapRealm.groupObjectClass = groupOfUniqueNames # <5>
-ldapRealm.uniqueMemberAttribute = uniqueMember # <6>
-ldapRealm.uniqueMemberAttributeValueTemplate = uid={0}
-
-# optional mapping from physical groups to logical application roles
-ldapRealm.rolesByGroup = \ # <7>
- LDN_USERS: user_role,\
- NYK_USERS: user_role,\
- HKG_USERS: user_role,\
- GLOBAL_ADMIN: admin_role,\
- DEMOS: self-install_role
-
-ldapRealm.permissionsByRole=\ # <8>
- user_role = *:ToDoItemsJdo:*:*,\
- *:ToDoItem:*:*; \
- self-install_role = *:ToDoItemsFixturesService:install:* ; \
- admin_role = *
-
-securityManager.realms = $ldapRealm
-----
-<1> user accounts are searched using a dedicated service account
-<2> SASL (CRAM-MD5) authentication is used for this authentication
-<3> Isis' implementation of the LDAP realm.
-<4> groups are searched under `ou=groups,o=mojo` (where `mojo` is the company name)
-<5> each group has an LDAP objectClass of `groupOfUniqueNames`
-<6> each group has a vector attribute of `uniqueMember`
-<7> groups looked up from LDAP can optionally be mapped to logical roles; otherwise groups are used as role names directly
-<8> roles are mapped in turn to permissions
-
-The value of `uniqueMember` is in the form `uid=xxx`, with `xxx` being the uid of the user
-* users searched under `ou=system`
-* users have, at minimum, a `uid` attribute and a password
-* the users credentials are used to verify their user/password
-
-The above configuration has been tested against http://directory.apache.org/apacheds/[ApacheDS], v1.5.7. This can be administered using http://directory.apache.org/studio/[Apache Directory Studio], v1.5.3.
-
-
-[TIP]
-.Shiro Realm Mappings
-====
-When configuring role based permission mapping, there can only be one of these entries per realm:
-
-[source,ini]
-----
-realm.groupToRolesMappings = ...
-----
-
-and
-
-[source,ini]
-----
-realm.roleToPermissionsMappings = ...
-----
-
-This forces you to put everything on one line for each of the above. This is, unfortunately, a Shiro "feature". And if you repeat the entries above then it's "last one wins".)
-
-To make the configuration maintainable, use "\" to separate the mappings onto separate lines in the file. Use this technique for both group to roles mapping and role to permission mapping. If you use the '' after the "," that separates the key:value pairs it is more readable.
-====
-
-
-
-
-
-
-== Externalizing role perms
-
-As an alternative to injecting the `permissionsByRole` property, the role/permission mapping can alternatively be specified by injecting a resource path:
-
-[source,ini]
-----
-ldapRealm.resourcePath=classpath:webapp/myroles.ini
-----
-
-where `myroles.ini` is in `src/main/resources/webapp`, and takes the form:
-
-[source,ini]
-----
-[roles]
-user_role = *:ToDoItemsJdo:*:*,\
- *:ToDoItem:*:*
-self-install_role = *:ToDoItemsFixturesService:install:*
-admin_role = *
-----
-
-This separation of the role/mapping can be useful if Shiro is configured to support multiple realms (eg an LdapRealm based one and also an TextRealm)
-
-
-
-
-== Active DS LDAP tutorial
-
-The screenshots below show how to setup LDAP accounts in ApacheDS using the Apache Directory Studio.
-
-The setup here was initially based on http://krams915.blogspot.co.uk/2011/01/ldap-apache-directory-studio-basic.html[this tutorial], however we have moved the user accounts so that they are defined in a separate LDAP node.
-
-To start, create a partition in order to hold the mojo node (holding the groups):
-
-image::{_imagesdir}/configuration/configuring-shiro/ldap/activeds-ldap-mojo-partition.png[ActiveDS LDAP Users]
-
-Create the `ou=groups,o=mojo` hierarchy:
-
-image::{_imagesdir}/configuration/configuring-shiro/ldap/activeds-ldap-mojo-root-dse.png[ActiveDS LDAP Users]
-
-Configure SASL authentication. This means that the checking of user/password is done implicitly by virtue of Isis connecting to LDAP using these credentials:
-
-image::{_imagesdir}/configuration/configuring-shiro/ldap/activeds-ldap-sasl-authentication.png[ActiveDS LDAP Users]
-
-In order for SASL to work, it seems to be necessary to put users under `o=system`. (This is why the setup is slightly different than the tutorial mentioned above):
-
-image::{_imagesdir}/configuration/configuring-shiro/ldap/activeds-ldap-users.png[ActiveDS LDAP Users]
-
-Configure the users into the groups:
-
-image::{_imagesdir}/configuration/configuring-shiro/ldap/activeds-ldap-groups.png[ActiveDS LDAP Users]
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-isisaddons-security-module-realm.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-isisaddons-security-module-realm.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-isisaddons-security-module-realm.adoc
deleted file mode 100644
index 558ae54..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-isisaddons-security-module-realm.adoc
+++ /dev/null
@@ -1,36 +0,0 @@
-[[_ug_security_shiro-isisaddons-security-module-realm]]
-= Security Module Realm
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 https://github.com/isisaddons/isis-module-security[Isis Addons' security module] (not ASF) provides a complete
-security subdomain for users, roles, permissions; all are persisted as domain entities.
-
-What that means, of course, that they can also be administered through your Isis application. Moreover, the set of permissions (to features) is derived completely from your application's metamodel; in essence the permissions are "type-safe".
-
-
-In order to play along, the module includes a Shiro realm, which fits in as follows:
-
-The general configuration is as follows:
-
-image::{_imagesdir}security/security-apis-impl/configure-shiro-to-use-isisaddons-security-module-realm.png[width="600px"]
-
-where the `IsisModuleSecurityRealm` realm is the implementation provided by the module.
-
-In the configuration above user passwords are stored in the database. The module uses link:http://www.mindrot.org/projects/jBCrypt/[jBCrypt] so that passwords are only stored in a (one-way) encrypted form in the database.
-
-
-
-The security module also supports a slightly more sophisticated configuration. Most organizations use LDAP for user credentials, and maintaining two separate user accounts would be less than ideal. The `IsisModuleSecurityRealm` can therefore be configured with a subsidiary "delegate" realm that is responsible for performing the primary authentication of the user; if that passes then a user is created (as a domain entity) automatically.
-In most cases this delegate realm will be the LDAP realm, and so the architecture becomes:
-
-image::{_imagesdir}security/security-apis-impl/configure-shiro-to-use-isisaddons-security-module-realm-with-delegate-realm.png[width="600px"]
-
-
-The security module has many more features than are described here, all of which are described in the module's link:https://github.com/isisaddons/isis-module-security[README]. The README also explains in detail how to configure an existing app to use this module.
-
-You can also look at the Isisaddons https://github.com/isisaddons/isis-app-todoapp[todoapp example] (not ASF), which is preconfigured to use the security module.
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-jdbc-realm.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-jdbc-realm.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-jdbc-realm.adoc
deleted file mode 100644
index ba901f3..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-jdbc-realm.adoc
+++ /dev/null
@@ -1,113 +0,0 @@
-[[_ug_security_shiro-jdbc-realm]]
-= Shiro JDBC Realm
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 is nothing to stop you from using some other `Realm` implementation (or indeed writing one yourself). For example, you could use Shiro's own JDBC realm that loads user/password details from a database.
-
-[WARNING]
-====
-If you are happy to use a database then we strongly recommend you use the http://github.com/isisaddons/isis-module-security[Isis addons' security] module instead of a vanilla JDBC; it is far more sophisticated and moreover gives you the ability to administer the system from within your Isis application.
-====
-
-If you go down this route, then the architecture is as follows:
-
-image::{_imagesdir}security/security-apis-impl/configure-shiro-to-use-custom-jdbc-realm.png[width="600px"]
-
-
-
-
-There's quite a lot of configuration required (in `WEB-INF/shiro.ini`) to set up a JDBC realm, so we'll break it out into sections.
-
-First, we need to set up the connection to JDBC:
-
-[source,ini]
-----
-jdbcRealm=org.apache.shiro.realm.jdbc.JdbcRealm # <1>
-
-jof = org.apache.shiro.jndi.JndiObjectFactory # <2>
-jof.resourceName = jdbc/postgres # <3>
-jof.requiredType = javax.sql.DataSource
-jof.resourceRef = true
-
-jdbcRealm.dataSource = $jof # <4>
-----
-<1> instantiate the JDBC realm
-<2> instantiate factory object to lookup DataSource from servlet container
-<3> name of the datasource (as configured in `web.xml`)
-<4> instruct JDBC realm to obtain datasource from the JNDI
-
-
-We next need to tell the realm how to query the database. Shiro supports any schema; what matters is the input search argument and the output results.
-
-[source,ini]
-----
-
-jdbcRealm.authenticationQuery = \ # <1>
- select password \
- from users \
- where username = ?
-
-jdbcRealm.userRolesQuery = \ # <2>
- select r.label \
- from users_roles ur \
- inner join roles r \
- on ur.role_id = r.id \
- where user_id = ( \
- select id \
- from users \
- where username = ?); \
-
-jdbcRealm.permissionsQuery= \ # <3>
- select p.permission \
- from roles_permissions rp \
- inner join permissions p \
- on rp.permission_id = p.id \
- where rp.role_id = ( \
- select id \
- from roles \
- where label = ?);
-
-jdbcRealm.permissionsLookupEnabled=true # <4>
-----
-<1> query to find password for user
-<2> query to find roles for user
-<3> query to find permissions for role
-<4> enable permissions lookup
-
-[WARNING]
-====
-The `permissionsLookupEnabled` is very important, otherwise Shiro just returns an empty list of permissions and your users will have no access to any features(!).
-====
-
-We also should ensure that the passwords are not stored as plain-text:
-
-[source,ini]
-----
-dps = org.apache.shiro.authc.credential.DefaultPasswordService # <1>
-pm = org.apache.shiro.authc.credential.PasswordMatcher # <2>
-pm.passwordService = $dps
-jdbcRealm.credentialsMatcher = $pm # <3>
-----
-<1> mechanism to encrypts password
-<2> service to match passwords
-<3> instruct JDBC realm to use password matching service when authenticating
-
-
-And finally we need to tell Shiro to use the realm, in the usual fashion:
-
-[source,ini]
-----
-securityManager.realms = $jdbcRealm
-----
-
-Using the above configuration you will also need to setup a `DataSource`. The details vary by servlet container, for example this is link:https://tomcat.apache.org/tomcat-8.0-doc/jndi-datasource-examples-howto.html[how to do the setup on Tomcat 8.0].
-
-[WARNING]
-====
-The name of the `DataSource` can also vary by servlet container; see for example link:http://stackoverflow.com/questions/17441019/how-to-configure-jdbcrealm-to-obtain-its-datasource-from-jndi/23784702#23784702[this StackOverflow answer].
-====
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_usage-by-isis-viewers.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_usage-by-isis-viewers.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_usage-by-isis-viewers.adoc
deleted file mode 100644
index 16f778c..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_usage-by-isis-viewers.adoc
+++ /dev/null
@@ -1,208 +0,0 @@
-[[_ug_security_usage-by-isis-viewers]]
-= Usage by Isis' Viewers
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 and large the security mechanisms within Isis are transparent to the rest of the framework (the xref:_ug_wicket-viewer[Wicket Viewer] and xref:_ug_restfulobjects-viewer[Restful Objects viewer], and the overall xref:_ug_runtime[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.
-
-
-
-
-== Wicket Viewer
-
-The xref:_ug_wicket-viewer[Wicket viewer] defines a relatively small number of pages (by which we mean subclasses of link:http://ci.apache.org/projects/wicket/apidocs/6.0.x/org/apache/wicket/markup/html/WebPage.html[`org.apache.wicket.markup.html.WebPage`]):
-
-* about page
-* action prompt page
-* entity page
-* error page
-* home page
-* standalone collection page
-* value page
-* void return page
-
-All of these (except about page) are annotated with the Wicket annotation:
-
-[source,java]
-----
-@AuthorizeInstantiation("org.apache.isis.viewer.wicket.roles.USER")
-----
-
-which means that they can only be accessed by a user with an authenticated session that has this special, reserved role. If not, Wicket will automatically redirect the user to the sign-in page.
-
-[TIP]
-====
-The sign-in page to render is pluggable; see xref:_ug_extending_wicket-viewer_custom-pages[extensions chapter] for details.
-====
-
-In the sign-in page the viewer calls to the Isis Authenticator API, and obtains back a user/role. It also adds in its special reserved role (per the annotation above) and then continues on to whichever page the user was attempting to access (usually the home page).
-
-And that's really all there is to it. When the viewer renders a domain object it queries the Isis metamodel, and suppresses from the view any object members (properties, actions etc) that are invisible. These may be invisible because the user has no (read ) permission, or they may be invisible because of domain object logic (eg a `hideXxx()` method). The viewer neither knows nor cares.
-
-Similarly, for those object members that _are_ visible, the viewer also checks if they are enabled or disabled. Again, an object member will be disabled if the user does not have (write) permission, or it could be disabled because of domain object logic (eg a `disableXxx()` method).
-
-
-=== User-registration
-
-As well as providing a sign-in screen, the Wicket viewer also provides the ability for xref:_user_registration[users to self-register]. By and large this operates outside of Isis' security mechanisms; indeed the various pages (sign-up, sign-up verification, password reset) are all rendered _without_ there being any current user session. These pages all "reach inside" Isis framework using a mechanism similar to <<_headless_access>> in order to actually do their stuff.
-
-[TIP]
-====
-The sign-in verification page to render is pluggable; see xref:_ug_extending_wicket-viewer_custom-pages[extensions chapter] for details.
-====
-
-User registration is only available if the xref:_user_registration_service[`UserRegistrationService`] is configured; this is used by the framework to actually create new instances of the user as accessed by the corresponding (Shiro) realm.
-
-Because Shiro realms are pluggable, the Isis framework does not provide default implementations of this service. However, if you are using the http://github.com/isisaddons/isis-module-security[Isis addons' security] module (non-ASF), then this module _does_ provide an implementation (that, as you might expect, creates new "user" domain entities).
-
-If you are using an LDAP realm and want to enable user-self registration then you'll need to write your own implementation of this service.
-
-
-
-== Restful Objects Viewer
-
-Unlike the Wicket viewer, the xref:_ug_restfulobjects-viewer[Restful Objects viewer] does _not_ provide any sort of login page; rather it provides a pluggable authentication strategy, delegated to by the `IsisSessionFilter` filter defined in `web.xml`. The authentication strategy is responsible for ensuring that a session is available for the REST resource.
-
-The API of `AuthenticationSessionStrategy` is simply:
-
-[source,java]
-----
-package org.apache.isis.core.webapp.auth;
-...
-public interface AuthenticationSessionStrategy {
- AuthenticationSession lookupValid( // <1>
- ServletRequest servletRequest,
- ServletResponse servletResponse);
- void bind( // <2>
- ServletRequest servletRequest,
- ServletResponse servletResponse,
- AuthenticationSession authSession);
-}
-
-----
-<1> returns a valid `AuthenticationSession` for the specified request, response
-<2> binds (associates the provided `AuthenticationSession`) to the request and response
-
-Here `AuthenticationSession` is Isis' internal API that represents a signed-on user.
-
-The framework provides a number of simple strategies:
-
-* `AuthenticationSessionStrategyBasicAuth` implements the HTTP basic auth protocol (the pop-up dialog box shown by the web browser)
-* `AuthenticationSessionStrategyHeader` that simply reads the user identity from an HTTP header
-* `AuthenticationSessionStrategyTrusted` that always logs in with a special "exploration" user
-
-As you can see, none of these should be considered production-quality.
-
-The strategy is configured in `web.xml`; for example:
-
-[source,xml]
-----
-<filter>
- <filter-name>IsisSessionFilterForRestfulObjects</filter-name>
- <filter-class>org.apache.isis.core.webapp.IsisSessionFilter</filter-class>
- <init-param>
- <param-name>authenticationSessionStrategy</param-name>
- <param-value> <!--1-->
- org.apache.isis.viewer.restfulobjects.server.authentication.AuthenticationSessionStrategyBasicAuth
- </param-value>
- </init-param>
- <init-param>
- <param-name>whenNoSession</param-name>
- <param-value>basicAuthChallenge</param-value> <!--2-->
- </init-param>
-</filter>
-----
-<1> configure basic auth strategy
-<2> what to do if no session was found; we indicate to issue a 401 basic authentication challenge
-
-The `IsisSessionFilter` has a further plugin point if no session was found (that is, if `AuthenticationSessionStrategy#lookupValid()` returns null), which is how to respond. The value "basicAuthChallenge" means to return a 401, which is what triggers the web browser to pop-up the basic HTTP challenge dialog box.
-
-The above filter must then be chained before the servlet that actually handles the REST requests:
-
-[source,xml]
-----
-<filter-mapping>
- <filter-name>IsisSessionFilterForRestfulObjects</filter-name>
- <servlet-name>RestfulObjectsRestEasyDispatcher</servlet-name>
-</filter-mapping>
-...
-<servlet>
- <servlet-name>RestfulObjectsRestEasyDispatcher</servlet-name>
- <servlet-class>org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher</servlet-class>
-</servlet>
-----
-
-[NOTE]
-====
-The above `web.xml` fragments do _not_ constitute the full configuration for the Restful Objects viewer, just those parts that pertain to security.
-====
-
-
-
-=== User-registration
-
-Isis currently does not have any out-of-the-box support for user-registration for applications using only the Restful viewer. However, in principal the pieces do exist to put together a solution.
-
-The general idea is similar to the design of the Wicket viewer; define some subsidiary resources that can operate _without_ a user session in place, and which "reach into" the framework using headless access in order to setup the user.
-
-[TIP]
-====
-An alternative approach, possibly less work and overall of more value, would be to implement `AuthenticationSessionStrategy` for oAuth, in other words allow users to use their existing Google or Facebook account.
-====
-
-The following steps sketch out the solution in a little more detail:
-
-* Define some new Restful resources (cf link:https://github.com/apache/isis/blob/master/core/viewer-restfulobjects-server/src/main/java/org/apache/isis/viewer/restfulobjects/server/resources/DomainObjectResourceServerside.java[`DomainServiceResourceServerside`] that correspond to sign-up/register page, eg `SignupResource` +
-+
-[source,java]
-----
-@Path("/signup")
-public class SignupResource {
- ...
-}
-----
-
-* Create a new subclass of `RestfulObjectsApplication`, eg "CustomRestfulObjectsApplication" and register your resources +
-+
-[source,java]
-----
-public class CustomRestfulObjectsApplication extends RestfulObjectsApplication {
- public CustomRestfulObjectsApplication() {
- addClass(SignupResource.class);
- }
-}
-----
-
-* Register your application class in `web.xml` instead of the default: +
-+
-[source,xml]
-----
-<context-param>
- <param-name>javax.ws.rs.Application</param-name>
- <param-value>com.mycompany.myapp.CustomRestfulObjectsApplication</param-value>
-</context-param>
-----
-
-So far this is just standard javax.rs stuff.
-
-Next, we need to ensure that a client can hit your new resource *with* the Isis runtime in place, but without there being an Isis session. For that....
-
-* create a subclass of the `AuthenticationSessionStrategy` that automatically returns a dummy session if the resource being accessed is "/restful/signup", say. +
-+
-You could do this by subclassing `AuthenticationSessionStrategyBasicAuth`, but then using code from `AuthenticationSessionStrategyBasicAuth` to return an "exploration" (or better, "signup") session if accessing the "/restful/signup" resource.
-
-* in the `SignUpResource` resource, you can then do a lookup of the `UserRegistrationService` in order to allow the user to be created: +
-+
-[source,java]
-----
-final UserRegistrationService userRegistrationService =
- IsisContext.getPersistenceSession().getServicesInjector().lookupService(UserRegistrationService.class);
-userRegistrationService.registerUser(userDetails);
-----
-
-Obviously the methods exposed by the `SignupResource` are up to you; ultimately they need to be able to gather information to populate the `UserDetails` object as passed to the `UserRegistrationService`.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing.adoc
deleted file mode 100644
index b92624a..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing.adoc
+++ /dev/null
@@ -1,17 +0,0 @@
-[[_ug_testing]]
-= Testing
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 you are going to use Apache Isis for developing complex business-critical applications, then being able to write automated tests for those applications becomes massively important. As such Apache Isis treats the topic of testing very seriously, and (though we say it ourselves) has support that goes way above what is provided by other application frameworks.
-
-
-include::_ug_testing_aaa.adoc[leveloffset=+1]
-include::_ug_testing_unit-test-support.adoc[leveloffset=+1]
-include::_ug_testing_integ-test-support.adoc[leveloffset=+1]
-include::_ug_testing_bdd-spec-support.adoc[leveloffset=+1]
-include::_ug_testing_fixture-scripts.adoc[leveloffset=+1]
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_aaa.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_aaa.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_aaa.adoc
deleted file mode 100644
index 4a74208..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_aaa.adoc
+++ /dev/null
@@ -1,166 +0,0 @@
-[[_ug_testing_aaa]]
-= Overview
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-== Unit tests vs Integ tests
-
-We divide automated tests into two broad categories:
-
-- unit tests exercise a single unit (usually a method) of a domain object, in isolation. +
-+
-Dependencies of that object are mocked out. These are written by a developer and for a developer; they are to ensure that a particular "cog in the machine" works correctly
-
-- integration tests exercise the application as a whole, usually focusing on one particular business operation (action). +
-+
-These are tests that represent the acceptance criteria of some business story; their intent should make sense to the domain expert (even if the domain expert is "non-technical")
-
-To put it another way:
-
-[TIP]
-====
-Integration tests help ensure that you are *_building the right system_*
-
-Unit tests help ensure that you are *_building the system right_*.
-====
-
-
-
-== Integ tests vs BDD Specs
-
-We further sub-divide integration tests into:
-
-* those that are implemented in Java and JUnit (we call these simply _"integration tests"_) +
-+
-Even if a domain expert understands the intent of these tests, the actual implementation will be opaque to them. Also, the only output from the tests is a (hopefully) green CI job
-
-* tests (or rather, specifications) that are implemented in a _behaviour-driven design_ (BDD) language such as link:https://cucumber.io/[Cucumber] (we call these _"BDD specs"_) +
-+
-The natural language specification then maps down onto some glue code that is used to drive the application. But the benefits of taking a BDD approach include the fact that your domain expert will be able to read the tests/specifications, and that when you run the specs, you also get documentation of the application's behaviour ("living documentation").
-
-It's up to you whether you use BDD specs for your apps; it will depend on your development process and company culture. But you if don't then you certainly should write integration tests: acceptance criteria for user stories should be automated!
-
-
-
-
-
-== Simulated UI (`WrapperFactory`)
-
-When we talk about integration tests/specs here, we mean tests that exercise the domain object logic, through to the actual database. But we also want the tests to exercise the app from the users's perspective, which means including the user interface.
-
-For most other frameworks that would require having to test the application in a very heavy weight/fragile fashion using a tool such as link:http://docs.seleniumhq.org/[Selenium], driving a web browser to navigate . In this regard though, Isis has a significant trick up its sleeve. Because Isis implements the naked objects pattern, it means that the UI is generated automatically from the UI. This therefore allows for other implementations of the UI.
-
-The xref:_ug_reference-services-api_manpage-WrapperFactory[`WrapperFactory`] domain service allows a test to wrap domain objects and thus to interact with said objects "as if" through the UI:
-
-image::{_imagesdir}testing/integ-tests.png[width="700px"]
-
-If the test invokes an action that is disabled, then the wrapper will throw an appropriate exception. If the action is ok to invoke, it delegates through.
-
-What this means is that an Isis application can be tested end-to-end without having to deploy it onto a webserver; the whole app can be tested while running in-memory. Although integration tests re (necessarily) slower than unit tests, they are not any harder to write (in fact, in some respects they are easier).
-
-
-
-
-== Dependency Injection
-
-Isis provides autowiring dependency injection into every domain object. This is most useful when writing unit tests; simply mock out the service and inject into the domain object.
-
-There are a number of syntaxes supported, but the simplest is to use `@javax.inject.Inject` annotation; for example:
-
-[source,java]
-----
-@javax.inject.Inject
-CustomerRepository customers;
-----
-
-Isis can inject into this even if the field has package-level (or even `private`) visibility. We recommend that you use package-level visibility, though, so that your unit tests (in the same package as the class under test) are able to inject mocks.
-
-Isis does also support a couple of other syntaxes:
-
-[source,java]
-----
-public void setCustomerRepository(CustomerRepository customers) { ... }
-----
-
-or
-
-[source,java]
-----
-public void injectCustomerRepository(CustomerRepository customers) { ... }
-----
-
-
-[TIP]
-====
-Apache Isis also supports automatic dependency injection into integration tests; just declare the service dependency in the usual fashion and it will be automatically injected.
-====
-
-
-
-
-== Given/When/Then
-
-Whatever type of test/spec you are writing, we recommend you follow the given/when/then idiom:
-
-* *given* the system is in this state (preconditions)
-* *when* I poke it with a stick
-* *then* it looks like this (postconditions)
-
-A good test should be 5 to 10 lines long; the test should be there to help you reason about the behaviour of the system. Certainly if the test becomes more than 20 lines it'll be too difficult to understand.
-
-The "when" part is usually a one-liner, and in the "then" part there will often be only two or three assertions that you want to make that the system has changed as it should.
-
-For unit test the "given" part shouldn't be too difficult either: just instantiate the class under test, wire in the appropriate mocks and set up the expectations. And if there are too many mock expectations to set up, then "listen to the tests" ... they are telling you your design needs some work.
-
-Where things get difficult though is the "given" for integration tests; which is the topic of the next section...
-
-
-
-
-== Fixture Management
-
-In the previous section we discussed using given/when/then as a form of organizing tests, and why you should keep your tests small.
-
-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 Isis provides is a domain service called xref:_ug_reference-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.
-
-
-
-
-
-== Fake data
-
-In any given test there are often quite a few variables involved, to initialize the state of the objects, or to act as arguments for invoking a method, or when asserting on post-conditions. Sometimes those values are important (eg verifying that an `Order`'s state went from PENDING to SHIPPED, say), but often they aren't (a customer's name, for example) but nevertheless need to be set up (especially in integration tests).
-
-We want our tests to be easily understood, and we want the reader's eye to be drawn to the values that are significant and ignore those that are not.
-
-One way to do this is to use random (or fake) values for any insignificant data. This in effect tells the reader that "any value will do". Moreover, if it turns out that any data won't do, and that there's some behaviour that is sensitive to the value, then the test will start to flicker, passing and then failing depending on inputs. This is A Good Thing™.
-
-Apache Isis does not, itself, ship with a fake data library. However, the http://github.com/isisaddons/isis-module-fakedata[Isis addons' fakedata] module (non-ASF) does provide exactly this capability.
-
-[TIP]
-====
-Using fake data works very well with fixture scripts; the fixture script can invoke the business action with sensible (fake/random) defaults, and only require that the essential information is passed into it by the test.
-====
-
-
-
-
-== Feature Toggles
-
-Writing automated tests is just good development practice. Also good practice is developing on the mainline (master, trunk); so that your continuous integration system really is integrating all code. Said another way: link:http://martinfowler.com/bliki/FeatureBranch.html[don't use branches]!
-
-Sometimes, though, a feature will take longer to implement than your iteration cycle. In such a case, how do you use continuous integration to keep everyone working on the mainline without revealing a half-implemented feature on your releases? One option is to use link:http://martinfowler.com/bliki/FeatureToggle.html[feature toggle]s.
-
-Apache Isis does not, itself, ship with a feature toggle library. However, the http://github.com/isisaddons/isis-module-togglz[Isis addons' togglz] module (non-ASF) does provide exactly this capability.
-
-
-
-
-
-With all that said, let's look in detail at the testing features provided by Apache Isis.
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support.adoc
deleted file mode 100644
index 4589f8f..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support.adoc
+++ /dev/null
@@ -1,22 +0,0 @@
-[[_ug_testing_bdd-spec-support]]
-= BDD Spec 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/
-
-
-link:http://en.wikipedia.org/wiki/Behavior-driven_development[Behaviour-driven design] (BDD) redefines testing not as an after-the-fact "let's check the system works", but rather as a means to work with the domain expert to (a) specify the behaviour of the feature _before_ starting implementation, and (b) provide a means that the domain expert can verify the feature after it has been implemented.
-
-Since domain experts are usually non-technical (at least, they are unlikely to be able to read or want to learn how to read JUnit/Java code), then applying BDD typically requires writing specifications in using structured English text and (ASCII) tables. The BDD tooling parses this text and uses it to actually interact with the system under test. As a byproduct the BDD frameworks generate readable output of some form; this is often an annotated version of the original specification, marked up to indicate which specifications passed, which have failed. This readable output is a form of "living documentation"; it captures the actual behaviour of the system, and so is guaranteed to be accurate.
-
-There are many BDD tools out there; Apache Isis provides an integration with link:https://cucumber.io/docs/reference/jvm#java[Cucumber JVM] (see also the https://github.com/cucumber/cucumber-jvm[github site]):
-
-
-
-include::_ug_testing_bdd-spec-support_how-it-works.adoc[leveloffset=+1]
-include::_ug_testing_bdd-spec-support_key-classes.adoc[leveloffset=+1]
-include::_ug_testing_bdd-spec-support_writing-a-bdd-spec.adoc[leveloffset=+1]
-include::_ug_testing_bdd-spec-support_bdd-tooling.adoc[leveloffset=+1]
-include::_ug_testing_bdd-spec-support_maven-configuration.adoc[leveloffset=+1]
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_bdd-tooling.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_bdd-tooling.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_bdd-tooling.adoc
deleted file mode 100644
index 384e684..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_bdd-tooling.adoc
+++ /dev/null
@@ -1,14 +0,0 @@
-[[_ug_testing_bdd-spec-support_bdd-tooling]]
-= BDD Tooling
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 help write feature files and generate step definitions, we recommend https://github.com/rlogiacco/Natural[Roberto Lo Giacco's Eclipse plugin]. For more information, see Dan's short http://danhaywood.com/2013/07/05/cucumber-editors-in-eclipse/[blog post]. It works very well. Of interest: this is implemented using http://www.eclipse.org/Xtext/[XText].
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_how-it-works.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_how-it-works.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_how-it-works.adoc
deleted file mode 100644
index ce3da2f..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_how-it-works.adoc
+++ /dev/null
@@ -1,20 +0,0 @@
-[[_ug_testing_bdd-spec-support_how-it-works]]
-= How it works
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-At a high level, here's how Cucumber works
-
-* specifications are written in the https://github.com/cucumber/cucumber/wiki/Gherkin[Gherkin] DSL, following the https://github.com/cucumber/cucumber/wiki/Given-When-Then["given/when/then"] format.
-
-* Cucumber-JVM itself is a JUnit runner, and searches for https://github.com/cucumber/cucumber/wiki/Feature-Introduction[feature files] on the classpath.
-
-* These in turn are matched to link:https://github.com/cucumber/cucumber/wiki/Step-Definitions[step definition]s through regular expressions. +
-+
-It is the step definitions (the "glue") that exercise the system.
-
-The code that goes in step definitions is broadly the same as the code that goes in an integration test method. One benefit of using step definitions (rather than integration tests) is that the step definitions are reusable across scenarios, so there may be less code overall to maintain. For example, if you have a step definition that maps to "given an uncompleted todo item", then this can be used for all the scenarios that start with that as their precondition.
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_key-classes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_key-classes.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_key-classes.adoc
deleted file mode 100644
index d562401..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_key-classes.adoc
+++ /dev/null
@@ -1,59 +0,0 @@
-[[_ug_testing_bdd-spec-support_key-classes]]
-= Key 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/
-
-
-
-
-There are some key framework classes that make up the spec support; these are discussed below.
-
-NOTE: some of these are also used by Isis' xref:_ug_testing_integ-test-support[Integration Test support].
-
-
-
-
-== `IsisSystemForTest`
-
-The `IsisSystemForTest` class allows a complete running instance of Isis to be bootstrapped (with the JDO objectstore); this is then held on a a `ThreadLocal` from one test to another.
-
-Typically bootstrapping code is used to lazily instantiate the `IsisSystemForTest` once and once only. The mechanism for doing this is line-for-line identical in both BDD step defs and integration tests.
-
-
-
-
-== `ScenarioExecution`
-
-The `ScenarioExecution` provides a context for a scenario that is being executed. It is Cucumber that determines which step definitions are run, and in which order, and so state cannot be passed between step definitions using local variables or instance variables. Instead the `ScenarioExecution` acts like a hashmap, allowing each step to put data (eg "given an uncompleted todoitem") into the map or get data ("when I complete the todoitem") from the map. This is done using the `putVar(...)` and `getVar(...)` methods.
-
-[TIP]
-====
-This corresponds broadly to the "World" object in Ruby-flavoured Cucumber.
-====
-
-The `ScenarioExecution` also provids access to the configured domain services (using the `service(...)` method) and the `DomainObjectContainer` (through the `container()` method).
-
-[NOTE]
-====
-This could probably be refactored; Cucumber JVM provides automatic dependency injection into setp definitions, but Isis does not currently leverage or exploit this capability.
-====
-
-Like the `IsisSystemForTest` class, the `ScenarioExecution` class binds an instance of itself onto a `ThreadLocal`. It can then be accessed in BDD step definitions using `ScenarioExecution.current()` static method.
-
-
-
-== `WrapperFactory`
-
-As with integration tests, the UI can be simulated by "wrapping" each domain object in a proxy using the `WrapperFactory`.
-
-
-
-
-== `CukeGlueAbstract`
-
-The `CukeGlueAbstract` acts as a convenience superclass for writing BDD step definitions (analogous to the `IntegrationTestAbstract` for integation tests). Underneath the covers it delegates to an underlying `ScenarioExecution`.
-
-
-
-
[30/45] isis git commit: ISIS-1133: breaking out reference guide and
devenv guide;
moving appendices' release notes and migration notes to other docs;
improving the documentation page.
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..43be73e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_object-titles-and-icons.adoc
@@ -0,0 +1,97 @@
+[[_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:ug.adoc#_ug_wicket-viewer_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:rg.adoc#_rg_annotations_manpage-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
+
+IMPORTANT: TODO - see xref:rg.adoc#_rg_methods_reserved_manpage-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).
+
+IMPORTANT: TODO - xref:rg.adoc#_rg_methods_reserved_manpage-iconName[`iconName()`], xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_cssClassFa[`@DomainObjectLayout#cssClassFa()`]
+
+
+
+
+== 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:ug.adoc#_ug_wicket-viewer_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.
+
+IMPORTANT: TODO - xref:rg.adoc#_rg_methods_reserved_manpage-cssClass[`cssClass()`], xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_cssClass[`@DomainObjectLayout#cssClass()`] xref:rg.adoc#_rg_annotations_manpage-ActionLayout_cssClass[`@ActionLayout#cssClass()`], xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_cssClass[`@PropertyLayout#cssClass()`], xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_cssClass[`@CollectionLayout#cssClass()`]
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_isis-maven-plugin.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_isis-maven-plugin.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_isis-maven-plugin.adoc
new file mode 100644
index 0000000..a9a72b6
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_isis-maven-plugin.adoc
@@ -0,0 +1,9 @@
+[[_ug_isis-maven-plugin]]
+= Isis Maven Plugin
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../../
+:_imagesdir: images/
+:toc: right
+
+IMPORTANT: TODO
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced.adoc
new file mode 100644
index 0000000..4b61cb2
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced.adoc
@@ -0,0 +1,26 @@
+[[_ug_more-advanced]]
+= More Advanced Techniques
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 pulls together a number of more advanced techniques that we've discovered and developed while building our own Isis applications.
+
+
+include::_ug_more-advanced_decoupling.adoc[leveloffset=+1]
+include::_ug_more-advanced_overriding-jdo-annotations.adoc[leveloffset=+1]
+include::_ug_more-advanced_bulk-actions.adoc[leveloffset=+1]
+include::_ug_more-advanced_view-models.adoc[leveloffset=+1]
+include::_ug_more-advanced_mapping-rdbms-views.adoc[leveloffset=+1]
+include::_ug_more-advanced_transactions-and-errors.adoc[leveloffset=+1]
+include::_ug_more-advanced_i18n.adoc[leveloffset=+1]
+include::_ug_more-advanced_multi-tenancy.adoc[leveloffset=+1]
+include::_ug_more-advanced_persistence-lifecycle.adoc[leveloffset=+1]
+include::_ug_more-advanced_tips-n-tricks.adoc[leveloffset=+1]
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_bulk-actions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_bulk-actions.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_bulk-actions.adoc
new file mode 100644
index 0000000..066e313
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_bulk-actions.adoc
@@ -0,0 +1,8 @@
+[[_ug_more-advanced_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/
+
+IMPORTANT: TODO - xref:rg.adoc#_rg_annotations_manpage-Action_invokeOn[`@Action#invokeOn()`]
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_decoupling.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_decoupling.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_decoupling.adoc
new file mode 100644
index 0000000..cd8e635
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_decoupling.adoc
@@ -0,0 +1,26 @@
+[[_ug_more-advanced_decoupling]]
+= Decoupling
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+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, or module.
+
+This section describes how to use Isis' features to ensure that your domain application remains decoupled. The techniques described here are also the ones that have been adopted by the various http://github.com/isisaddons[Isis Addons] modules (not ASF) for security, commands, auditing etc.
+
+The following sections describe how to re-assemble an application, in particular where some modules are in-house but others are potentially third-party (eg the Isis Addons modules).
+
+[NOTE]
+====
+There is some overlap with OSGi and Java 9's Jigsaw concepts of "module"; in the future we expect to refactor Isis to leverage these module systems.
+====
+
+include::_ug_more-advanced_decoupling_db-schemas.adoc[leveloffset=+1]
+include::_ug_more-advanced_decoupling_contributions.adoc[leveloffset=+1]
+include::_ug_more-advanced_decoupling_vetoing-visibility.adoc[leveloffset=+1]
+include::_ug_more-advanced_decoupling_event-bus.adoc[leveloffset=+1]
+include::_ug_more-advanced_decoupling_pushing-changes.adoc[leveloffset=+1]
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_decoupling_contributions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_decoupling_contributions.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_decoupling_contributions.adoc
new file mode 100644
index 0000000..ead0886
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_decoupling_contributions.adoc
@@ -0,0 +1,8 @@
+[[_ug_more-advanced_decoupling_contributions]]
+= Contributions
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+IMPORTANT: TODO
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_decoupling_db-schemas.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_decoupling_db-schemas.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_decoupling_db-schemas.adoc
new file mode 100644
index 0000000..06189a0
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_decoupling_db-schemas.adoc
@@ -0,0 +1,151 @@
+[[_ug_more-advanced_decoupling_db-schemas]]
+= Database Schemas
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 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. As of 1.9.0-SNAPSHOT, all the link:http://www.isisaddons.org[Isis Addons] (non-ASF) modules do this, for example:
+
+
+
+[source,java]
+----
+@javax.jdo.annotations.PersistenceCapable( ...
+ schema = "isissecurity",
+ table = "ApplicationUser")
+public class ApplicationUser ... { ... }
+----
+
+results in a `CREATE TABLE` statement of:
+
+[source,sql]
+----
+CREATE TABLE isissecurity."ApplicationUser" (
+ ...
+)
+----
+
+
+while:
+
+[source,java]
+----
+@javax.jdo.annotations.PersistenceCapable( ...
+ schema = "isisaudit",
+ table="AuditEntry")
+public class AuditEntry ... { ... }
+----
+
+similarly results in:
+
+[source,sql]
+----
+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:ug.adoc#_ug_runtime_configuring-datanucleus[configuring DataNucleus Overriding Annotations] for more details.
+====
+
+
+
+
+== Listener to create schema
+
+JDO/DataNucleus does not automatically create these schema objects, but it _does_ provide a listener callback API
+on the initialization of each class into the JDO metamodel.
+
+[TIP]
+====
+Actually, the above statement isn't quite true. In DN 3.2.x (as used by Isis up to v1.8.0) there was no support for schemas. As of Isis 1.9.0-SNAPSHOT and DN 4.0 there is now support. But we implemented this feature initially against DN 3.2.x, and it still works, so for now we've decided to leave it in.
+====
+
+Therefore Apache Isis attaches a listener, `CreateSchemaObjectFromClassMetadata`, that checks for the schema's existence, and creates the schema if required.
+
+The guts of its implementation is:
+
+[source,java]
+----
+public class CreateSchemaObjectFromClassMetadata
+ implements MetaDataListener,
+ PersistenceManagerFactoryAware,
+ DataNucleusPropertiesAware {
+ @Override
+ public void loaded(final AbstractClassMetaData cmd) { ... }
+
+ protected String buildSqlToCheck(final AbstractClassMetaData cmd) {
+ final String schemaName = schemaNameFor(cmd);
+ return String.format(
+ "SELECT count(*) FROM INFORMATION_SCHEMA.SCHEMATA where SCHEMA_NAME = '%s'", schemaName);
+ }
+ protected String buildSqlToExec(final AbstractClassMetaData cmd) {
+ final String schemaName = schemaNameFor(cmd);
+ return String.format("CREATE SCHEMA \"%s\"", schemaName);
+ }
+}
+----
+
+where `MetaDataListener` is the DataNucleus listener API:
+
+[source,java]
+----
+public interface MetaDataListener {
+ void loaded(AbstractClassMetaData cmd);
+}
+----
+
+Although not formal API, the default `CreateSchemaObjectFromClassMetadata` has been designed to be easily overrideable if you
+need to tweak it to support other RDBMS'. Any implementation must implement `org.datanucleus.metadata.MetaDataListener`:
+
+The implementation provided has has been tested for HSQLDB, PostgreSQL and MS SQL Server, and is used automatically unless an alternative implementation is specified (as described in the section below).
+
+
+
+
+
+== Alternative implementation
+
+An alternative implementation can be registered and used through the following configuration property:
+
+[source,ini]
+----
+isis.persistor.datanucleus.classMetadataLoadedListener=\
+ org.apache.isis.objectstore.jdo.datanucleus.CreateSchemaObjectFromClassMetadata
+----
+
+
+Because this pertains to the JDO Objectstore we suggest you put this configuration property in `WEB-INF/persistor_datanucleus.properties`; but putting it in `isis.properties` will also work.
+
+Any implementation must implement `org.datanucleus.metadata.MetaDataListener`. In many cases simply subclassing from `CreateSchemaObjectFromClassMetadata` and overriding `buildSqlToCheck(...)` and `buildSqlToExec(...)` should suffice.
+
+If you _do_ need more control, your implementation can also optionally implement `org.apache.isis.objectstore.jdo.datanucleus.PersistenceManagerFactoryAware`:
+
+[source,java]
+----
+public interface PersistenceManagerFactoryAware {
+ public void setPersistenceManagerFactory(final PersistenceManagerFactory persistenceManagerFactory);
+}
+----
+
+and also `org.apache.isis.objectstore.jdo.datanucleus.DataNucleusPropertiesAware`:
+
+[source,java]
+----
+public interface DataNucleusPropertiesAware {
+ public void setDataNucleusProperties(final Map<String, String> properties);
+}
+----
+
+This latter interface provides access to the properties passed through to JDO/DataNucleus.
+
+
+[IMPORTANT]
+====
+If you do extend Isis' `CreateSchemaObjectFromClassMetadata` class for some other database, please https://issues.apache.org/jira/browse/ISIS[contribute back] your improvements.
+====
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_decoupling_event-bus.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_decoupling_event-bus.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_decoupling_event-bus.adoc
new file mode 100644
index 0000000..a1bec52
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_decoupling_event-bus.adoc
@@ -0,0 +1,11 @@
+[[_ug_more-advanced_decoupling_event-bus]]
+= Event Bus
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`], xref:rg.adoc#_rg_annotations_manpage-Action_domainEvent[`@Action#domainEvent()`], xref:rg.adoc#_rg_annotations_manpage-Property_domainEvent[`@Property#domainEvent()`], xref:rg.adoc#_rg_annotations_manpage-Collection_domainEvent[`@Collection#domainEvent()`], xref:rg.adoc#_rg_services-api_manpage-WrapperFactory[`WrapperFactory`].
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_decoupling_pushing-changes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_decoupling_pushing-changes.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_decoupling_pushing-changes.adoc
new file mode 100644
index 0000000..cb6d2c4
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_decoupling_pushing-changes.adoc
@@ -0,0 +1,140 @@
+[[_ug_more-advanced_decoupling_pushing-changes]]
+= Pushing Changes
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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]
+====
+This technique is much less powerful than using xref:ug.adoc#_ug_more-advanced_decoupling_event-bus[the event bus] . We present it mostly for completeness.
+====
+
+
+
+
+== When a property is changed
+
+If you want to invoke functionality whenever a property is changed by the user, then you should create a supporting `modifyXxx()` method and include the functionality within that. The syntax is:
+
+[source,java]
+--
+public void modifyPropertyName(PropertyType param) { ... }
+--
+
+Why not just put this functionality in the setter? Well, the setter is used by the object store to recreate the state of an already persisted object. Putting additional behaviour in the setter would cause it to be triggered incorrectly.
+
+For example:
+
+[source,java]
+--
+public class Order() {
+ public Integer getAmount() { ... }
+ public void setAmount(Integer amount) { ... }
+ public void modifyAmount(Integer amount) { // <1>
+ setAmount(amount); // <3>
+ addToTotal(amount); // <2>
+ }
+ ...
+}
+--
+<1> The `modifyAmount()` method calls ...
+<2> ... the `addToTotal()` (not shown) to maintain some running total.
+
+We don't want this `addToCall()` method to be called when pulling the object back from the object store, so we put it into the modify, not the setter.
+
+You may optionally also specify a `clearXxx()` which works the same way as modify `modify Xxx()` but is called when the property is cleared by the user (i.e. the current value replaced by nothing). The syntax is:
+
+[source,java]
+--
+public void clearPropertyName() { ... }
+--
+
+To extend the above example:
+
+[source,java]
+--
+public class Order() {
+ public Integer getAmount() { ... }
+ public void setAmount(Integer amount) { ... }
+ public void modifyAmount(Integer amount) { ... }
+ public void clearAmount() {
+ removeFromTotal(this.amount);
+ setAmount(null);
+ }
+ ...
+}
+--
+
+
+
+
+== When a collection is modified
+
+A collection may have a corresponding `addToXxx()` and/or
+`removeFromXxx()` method. If present, and direct manipulation of the
+contents of the connection has not been disabled (see ?), then they will
+be called (instead of adding/removing an object directly to the
+collection returned by the accessor).
+
+The reason for this behaviour is to allow other behaviour to be
+triggered when the contents of the collection is altered. That is, it is
+directly equivalent to the supporting `modifyXxx()` and `clearXxx()`
+methods for properties (see ?).
+
+The syntax is:
+
+[source,java]
+--
+public void addTo<CollectionName>(EntityType param) { ... }
+--
+
+and
+
+[source,java]
+--
+public void removeFromCollectionName(EntityType param) { ... }
+--
+
+where `EntityType` is the same type as the generic collection type.
+
+For example:
+
+[source,java]
+--
+public class Employee { ... }
+
+public class Department {
+
+ private int numMaleEmployees; // <1>
+ private int numFemaleEmployees; // <2>
+
+ private Set<Employee> employees = new TreeSet<Employee>();
+ public Set<Employee> getEmployees() {
+ return employees;
+ }
+ private void setEmployees(Set<Employee> employees) {
+ this.employees = employees;
+ }
+ public void addToEmployees(Employee employee) { // <3>
+ numMaleEmployees += countOneMale(employee);
+ numFemaleEmployees += countOneFemale(employee);
+ employees.add(employee);
+ }
+ public void removeFromEmployees(Employee employee) { // <4>
+ numMaleEmployees -= countOneMale(employee);
+ numFemaleEmployees -= countOneFemale(employee);
+ employees.remove(employee);
+ }
+ private int countOneMale(Employee employee) { return employee.isMale()?1:0; }
+ private int countOneFemale(Employee employee) { return employee.isFemale()?1:0; }
+
+ ...
+}
+--
+<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-removeTo[`removeTo...()`] method similarly decrements the derived properties
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_decoupling_vetoing-visibility.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_decoupling_vetoing-visibility.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_decoupling_vetoing-visibility.adoc
new file mode 100644
index 0000000..a3d7c33
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_decoupling_vetoing-visibility.adoc
@@ -0,0 +1,15 @@
+[[_ug_more-advanced_decoupling_vetoing-visibility]]
+= Vetoing Visibility
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+IMPORTANT: TODO - a write-up of the "vetoing subscriber" design pattern, eg as described in the xref:rg.adoc#_rg_services-api_manpage-BookmarkService[`BookmarkService`]
+
+
+eg if included an addon such as auditing or security.
+
+solution is to write a domain event subscriber that vetoes the visibility
+
+All the addons actions inherit from common base classes so this can be as broad-brush or fine-grained as required
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_i18n.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_i18n.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_i18n.adoc
new file mode 100644
index 0000000..2250553
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_i18n.adoc
@@ -0,0 +1,378 @@
+[[_ug_more-advanced_i18n]]
+= i18n
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+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 messages resulting from any business rule violations (eg `disableXxx()` or `validateXxx()`, 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
+
+
+
+== Implementation Approach
+
+Most Java frameworks tackle i18n by using Java's own `ResourceBundle` API. However, there are some serious drawbacks in this approach, such as:
+
+* if a string appears more than once (eg "name" or "description") then it must be translated everywhere it appears in every resource bundle file
+* there is no support for plural forms (see this link:http://stackoverflow.com/questions/14326653/java-internationalization-i18n-with-proper-plurals/14327683#14327683[SO answer])
+* there is no tooling support for translators
+
+Apache Isis therefore takes a different approach, drawing inspiration from GNU's https://www.gnu.org/software/gettext/manual/index.html[gettext] API and specifically its `.pot` and `.po` files. These are intended to be used as follows:
+
+* the `.pot` (portable object template) file holds the message text to be translated
+* this file is translated into multiple `.po` (portable object) files, one per supported locale
+* these `.po` files are renamed according to their locale, and placed into the 'appropriate' location to be picked up by the runtime. The name of each `.po` resolved in a very similar way to resource bundles.
+
+The format of the `.pot` and `.po` files is identical; the only difference is that the `.po` file has translations for each of the message strings. These message strings can also have singular and plural forms.
+
+
+[IMPORTANT]
+====
+Although Isis' implementation is modelled after GNU's API, it does _not_ use any GNU software. This is for two reasons: (a) to simplify the toolchain/developer experience, and (b) because GNU software is usually GPL, which would be incompatible with the Apache license).
+====
+
+This design tackles all the issues of ``ResourceBundle``s:
+
+* the `.po` message format is such that any given message text to translate need only be translated once, even if it appears in multiple places in the application (eg "Name")
+* the `.po` message format includes translations for (optional) plural form as well as singular form
+* there are lots of freely available editors https://www.google.co.uk/search?q=.po+file+editor[to be found], many summarized on this https://www.drupal.org/node/11131[Drupal.org] webpage. +
++
+In fact, there are also online communities/platforms of translators to assist with translating files. One such is https://crowdin.com/[crowdin] (nb: this link does not imply endorsement).
+
+In Isis' implementation, if the translation is missing from the `.po` file then the original message text from the `.pot` file will be returned. In fact, it isn't even necessary for there to be any `.po` files; `.po` translations can be added piecemeal as the need arises.
+
+
+
+
+== `TranslationService`
+
+The cornerstone of Isis' support for i18n is the `TranslationService` service. This is defined in the applib with the following API:
+
+[source,java]
+----
+public interface TranslationService {
+ public String translate( // <1>
+ final String context,
+ final String text);
+ public String translate( // <2>
+ final String context,
+ final String singularText,
+ final String pluralText,
+ final int num);
+ public enum Mode {
+ READ,
+ WRITE;
+ }
+ Mode getMode(); // <3>
+}
+----
+<1> is to translate the singular form of the text
+<2> is to translate the plural form of the text
+<3> indicates whether the translation service is in read or write mode.
+
+The `translate(...)` methods are closely modelled on GNU's gettext API. The first version is used when no translation is required, the second is when both a singular and plural form will be required, with the `num` parameter being used to select which is returned. In both cases the `context` parameter provides some contextual information for the translator; this generally corresponds to the class member.
+
+The mode meanwhile determines the behaviour of the service. More on this below.
+
+
+
+=== `TranslationServicePo`
+
+Isis provides a default implementation of `TranslationService`, namely `TranslationServicePo`.
+
+If the service is running in the normal read mode, then it simply provides translations for the locale of the current user. This means locates the appropriate `.po` file (based on the requesting user's locale), finds the translation and returns it.
+
+If however the service is configured to run in write mode, then it instead records the fact that the message was requested to be translated (a little like a spy/mock in unit testing mock), and returns the original message. The service can then be queried to discover which messages need to be translated. All requested translations are written into the `.pot` file.
+
+To make the service as convenient as possible to use, the service configures itself as follows:
+
+* if running in xref:ug.adoc#_ug_runtime_deployment-types[prototype mode] 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 xref:ug.adoc#_ug_runtime_deployment-types[server (production) mode], 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.
+
+
+
+
+
+== Imperative messages
+
+The `TranslationService` is used internally by Isis when building up the metamodel; the name and description of every class, property, collection, action and action parameter is automatically translated. Thus the simple act of bootstrapping Isis will cause most of the messages requiring translation (that is: those for the Isis metamodel) to be captured by the `TranslationService`.
+
+However, for an application to be fully internationalized, any validation messages (from either `disableXxx()` or `validateXxx()` supporting methods) and also possibly an object's title (from the `title()` method) will also require translation. Moreover, these messages must be captured in the `.pot` file such that they can be translated.
+
+
+=== `TranslatableString`
+
+The first part of the puzzle is tackled by an extension to 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]:
+
+[source,java]
+----
+public TranslatableString validateUpdateName(final String name) {
+ return name.contains("!")? TranslatableString.tr("Exclamation mark is not allowed"): null;
+}
+----
+
+This corresponds to the following entry in the `.pot` file:
+
+[source,ini]
+----
+#: dom.simple.SimpleObject#updateName()
+msgid "Exclamation mark is not allowed"
+msgstr ""
+----
+
+The full API of `TranslatableString` is modelled on the design of GNU gettext (in particular the https://code.google.com/p/gettext-commons/wiki/Tutorial[gettext-commons] library):
+
+[source,java]
+----
+public final class TranslatableString {
+ public static TranslatableString tr( // <1>
+ final String pattern,
+ final Object... paramArgs) { ... }
+ public static TranslatableString trn( // <2>
+ final String singularPattern,
+ final String pluralPattern,
+ final int number,
+ final Object... paramArgs) { ... }
+ public String translate( // <3>
+ final TranslationService translationService,
+ final String context) { ... }
+}
+----
+<1> returns a translatable string with a single pattern for both singular and plural forms.
+<2> returns a translatable string with different patterns for singular and plural forms; the one to use is determined by the 'number' argument
+<3> translates the string using the provided `TranslationService`, using the appropriate singular/regular or plural form, and interpolating any arguments.
+
+The interpolation uses the format `{xxx}`, where the placeholder can occur multiple times.
+
+For example:
+
+[source,java]
+----
+final TranslatableString ts = TranslatableString.tr(
+ "My name is {lastName}, {firstName} {lastName}.",
+ "lastName", "Bond", "firstName", "James");
+----
+
+would interpolate (for the English locale) as "My name is Bond, James Bond".
+
+For a German user, on the other hand, if the translation in the corresponding `.po` file was:
+
+[source,ini]
+----
+#: xxx.yyy.Whatever#context()
+msgid "My name is {lastName}, {firstName} {lastName}."
+msgstr "Iche heisse {firstName} {lastName}."
+----
+
+then the translation would be: "Ich heisse James Bond".
+
+
+The same class is used in xref:rg.adoc#_rg_services-api_manpage-DomainObjectContainer[`DomainObjectContainer`] so that you can raise translatable info, warning and error messages; each of the relevant methods are overloaded.
+
+For example:
+
+[source,java]
+----
+public interface DomainObjectContainer {
+ void informUser(String message);
+ void informUser(
+ TranslatableMessage message,
+ final Class<?> contextClass, final String contextMethod); // <1>
+ ...
+}
+----
+<1> are concatenated together to form the context for the `.pot` file.
+
+
+=== `TranslatableException`
+
+Another mechanism by which messages can be rendered to the user are as the result of exception messages thrown and recognized by an xref:rg.adoc#_rg_services-spi_manpage-ExceptionRecognizer[`ExceptionRecognizer`].
+
+In this case, if the exception implements `TranslatableException`, then the message will automatically be translated before being rendered. The `TranslatableException` itself takes the form:
+
+[source,java]
+----
+public interface TranslatableException {
+ TranslatableString getTranslatableMessage(); // <1>
+ String getTranslationContext(); // <2>
+}
+
+----
+<1> the message to translate. If returns `null`, then the `Exception#getMessage()` is used as a fallback
+<2> the context to use when translating the message
+
+
+
+
+
+== Integration Testing
+
+So much for the API; but as noted, it is also necessary to ensure that the required translations are recorded (by the `TranslationService`) into the `.pot` file.
+
+For this, we recommend that you ensure that all such methods are tested through an xref:ug.adoc#_ug_testing_integ-test-support[integration test] (not unit test).
+
+For example, here's the corresponding integration test for the "Exclamation mark" example from the simpleapp (above):
+
+[source,java]
+----
+@Rule
+public ExpectedException expectedException = ExpectedException.none();
+
+@Inject
+FixtureScripts fixtureScripts;
+
+@Test
+public void failsValidation() throws Exception {
+ // given
+ RecreateSimpleObjects fs = new RecreateSimpleObjects().setNumber(1);
+ fixtureScripts.runFixtureScript(fs, null);
+ SimpleObject simpleObjectWrapped = wrap(fs.getSimpleObjects().get(0));
+
+ // expect
+ expectedExceptions.expect(InvalidException.class);
+ expectedExceptions.expectMessage("Exclamation mark is not allowed");
+
+ // when
+ simpleObjectWrapped.updateName("new name!");
+}
+----
+
+Running this test will result in the framework calling the `validateUpdateName(...)` method, and thus to record that a translation is required in the `.pot` file.
+
+When the integration tests are complete (that is, when Isis is shutdown), the `TranslationServicePo` will write out all captured translations to its log (more on this below). This will include all the translations captured from the Isis metamodel, along with all translations as exercised by the integration tests.
+
+To ensure your app is fully internationalized app, you must therefore:
+
+* use `TranslatableString` rather than `String` for all validation/disable and title methods.
+* ensure that (at a minimum) all validation messages and title methods are integration tested.
+
+[NOTE]
+====
+We make no apologies for this requirement: one of the reasons that we decided to implement Isis' i18n support in this way is because it encourages/requires the app to be properly tested.
+
+Behind the scenes Isis uses a JUnit rule (`ExceptionRecognizerTranslate`) to intercept any exceptions that are thrown. These are simply passed through to the registered xref:rg.adoc#_rg_services-spi_manpage-ExceptionRecognizer[`ExceptionRecognizer`]s so that any messages are recorded as requiring translation.
+====
+
+
+
+
+
+
+== Configuration
+
+There are several different aspects of the translation service that can be configured.
+
+=== Logging
+
+To configure the `TranslationServicePo` to write to out the `translations.pot` file, add the following to the _integtests_ `logging.properties` file:
+
+[source,ini]
+----
+log4j.appender.translations-po=org.apache.log4j.FileAppender
+log4j.appender.translations-po.File=./translations.pot
+log4j.appender.translations-po.Append=false
+log4j.appender.translations-po.layout=org.apache.log4j.PatternLayout
+log4j.appender.translations-po.layout.ConversionPattern=%m%n
+
+log4j.logger.org.apache.isis.core.runtime.services.i18n.po.PoWriter=INFO,translations-po
+log4j.additivity.org.apache.isis.core.runtime.services.i18n.po.PotWriter=false
+----
+
+Just to repeat, this is _not_ the `WEB-INF/logging.properties` file, it should instead be added to the `integtests/logging.properties` file.
+
+=== Location of the `.po` files
+
+The default location of the translated `.po` files is in the `WEB-INF` directory. These are named and searched for similarly to regular Java resource bundles.
+
+For example, assuming these translations:
+
+[source,ini]
+----
+/WEB-INF/translations-en-US.po
+ /translations-en.po
+ /translations-fr-FR.po
+ /translations.po
+----
+
+then:
+
+* a user with `en-US` locale will use `translations-en-US.po`
+* a user with `en-GB` locale will use `translations-en.po`
+* a user with `fr-FR` locale will use `translations-fr-FR.po`
+* a user with `fr-CA` locale will use `translations.po`
+
+The basename for translation files is always `translations`; this cannot be altered.
+
+
+=== Externalized translation files
+
+Normally Isis configuration files are read from the `WEB-INF` file. However, Isis can be configured to read config files from an xref:ug.adoc#_ug_deployment_externalized-configuration[external directory]; this is also supported for translations.
+
+Thus, if in `web.xml` the external configuration directory has been set:
+
+[source,xml]
+----
+<context-param>
+ <param-name>isis.config.dir</param-name>
+ <param-value>location of external config directory</param-value>
+</context-param>
+----
+
+Then this directory will be used as the base for searching for translations (rather than the default 'WEB-INF/' directory).
+
+=== Force read mode
+
+As noted above, if running in prototype mode then `TranslationServicePo` will be in write mode, if in production mode then will be in read mode. To force read mode (ie use translations) even if in prototype mode, add the following configuration property to `isis.properties`:
+
+[source,ini]
+----
+isis.services.translation.po.mode=read
+----
+
+== Supporting services
+
+The `TranslationServicePo` has a number of supporting/related services.
+
+=== `LocaleProvider`
+
+The `LocaleProvider` API is used by the `TranslationServicePo` implementation to obtain the locale of the "current user".
+
+A default implementation is provided by the Wicket viewer.
+
+[NOTE]
+====
+Note that this default implementation does not support requests made through the Restful Objects viewer (there is no Wicket 'application' object available); the upshot is that requests through Restful Objects are never translated. Registering a different implementation of `LocaleProvider` that taps into appropriate REST (RestEasy?) APIs would be the way to address this.
+====
+
+
+=== `TranslationsResolver`
+
+The `TranslationResolver` is used by the `TranslationService` implementation to lookup translations for a specified locale. It is this service that reads from the `WEB-INF/` (or externalized directory).
+
+
+=== `TranslationServicePoMenu`
+
+The `TranslationServicePoMenu` provides a couple of menu actions in the UI (prototype mode only) that interacts with the underlying `TranslationServicePo`:
+
+* the `downloadTranslationsFile()` action - available only in write mode - allows the current `.pot` file to be downloaded. +
++
+[NOTE]
+====
+While this will contain all the translations from the metamodel, it will not necessarily contain all translations for all imperative methods returning `TranslatableString` instances; which are present and which are missing will depend on which imperative methods have been called (recorded by the service) prior to downloading.
+====
+
+* the `clearTranslationsCache()` action - available only in read mode - will clear the cache so that new translations can be loaded. +
++
+This allows a translator to edit the appropriate `translations-xx-XX.po` file and check the translation is correct without having to restart the app.
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_mapping-rdbms-views.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_mapping-rdbms-views.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_mapping-rdbms-views.adoc
new file mode 100644
index 0000000..1cb9286
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_mapping-rdbms-views.adoc
@@ -0,0 +1,9 @@
+[[_ug_more-advanced_mapping-rdbms-views]]
+= Mapping RDBMS Views
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 - as used in link:http://github.com/estatio/estatio[Estatio]
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_multi-tenancy.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_multi-tenancy.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_multi-tenancy.adoc
new file mode 100644
index 0000000..690f608
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_multi-tenancy.adoc
@@ -0,0 +1,8 @@
+[[_ug_more-advanced_multi-tenancy]]
+= Multi-tenancy
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+IMPORTANT: TODO - as supported by (non-ASF) http://github.com/isisaddons/isis-module-security[Isis addons' security] module.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_overriding-jdo-annotations.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_overriding-jdo-annotations.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_overriding-jdo-annotations.adoc
new file mode 100644
index 0000000..586110b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_overriding-jdo-annotations.adoc
@@ -0,0 +1,55 @@
+[[_ug_more-advanced_overriding-jdo-annotations]]
+= Overriding JDO Annotations
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+The JDO Objectstore (or rather, the underlying DataNucleus implementation) builds its own persistence metamodel by reading both annotations on the class and also by searching for metadata in XML files. The metadata in the XML files takes precedence over the annotations, and so can be used to override metadata that is "hard-coded" in annotations.
+
+For example, as of 1.9.0-SNAPSHOT the various http://www.isisaddons.org[Isis addons] modules (not ASF) use schemas for each entity. For example, the `AuditEntry` entity in the http://github.com/isisaddons/isis-module-audit[audit module] is annotated as:
+
+[source,java]
+----
+@javax.jdo.annotations.PersistenceCapable(
+ identityType=IdentityType.DATASTORE,
+ schema = "IsisAddonsAudit",
+ table="AuditEntry")
+public class AuditEntry {
+ ...
+}
+----
+
+This will map the `AuditEntry` class to a table `"IsisAddonsAudit"."AuditEntry"`; that is using a custom schema to own the object.
+
+Suppose though that for whatever reason we didn't want to use a custom schema but would rather use the default. We can override the above annotation using a `package.jdo` file, for example:
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8" ?>
+<jdo xmlns="http://xmlns.jcp.org/xml/ns/jdo/jdo"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/jdo/jdo
+ http://xmlns.jcp.org/xml/ns/jdo/jdo_3_0.xsd" version="3.0">
+ <package name="org.isisaddons.module.audit.dom">
+ <class name="AuditEntry" schema="PUBLIC" table="IsisAddonsAuditEntry">
+ </class>
+ </package>
+</jdo>
+----
+
+This file should be placed can be placed in `src/main/java/META-INF` within your application's `dom` module.
+
+[NOTE]
+====
+* The same approach should work for any other JDO metadata, but some experimentation might be required.+
++
+For example, in writing up the above example we found that writing `schema=""` (in an attempt to say, "use the default schema for this table") actually caused the original annotation value to be used instead.
+
+* Forcing the schema to "PUBLIC" (as in the above example) works, but it isn't ideal because the name "PUBLIC" is not vendor-neutral (it works for HSQLDB, but MS SQL Server uses "dbo" as its default).
+
+* As of 1.9.0-SNAPSHOT Apache Isis will automatically (attempt) to create the owning schema for a given table if it does not exist. This behaviour can be customized, as described in the section on xref:_using_modules[using modules].
+====
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_persistence-lifecycle.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_persistence-lifecycle.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_persistence-lifecycle.adoc
new file mode 100644
index 0000000..5765118
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_persistence-lifecycle.adoc
@@ -0,0 +1,8 @@
+[[_ug_more-advanced_persistence-lifecycle]]
+= Persistence Lifecycle
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+IMPORTANT: TODO
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_tips-n-tricks.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_tips-n-tricks.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_tips-n-tricks.adoc
new file mode 100644
index 0000000..f272734
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_tips-n-tricks.adoc
@@ -0,0 +1,15 @@
+[[_ug_more-advanced_tips-n-tricks]]
+= Tips n Tricks
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 a miscellaneous collection of hints-and-tips.
+
+include::_ug_more-advanced_tips-n-tricks_are-you-sure.adoc[leveloffset=+1]
+include::_ug_more-advanced_tips-n-tricks_simulating-collections-of-values.adoc[leveloffset=+1]
+include::_ug_more-advanced_tips-n-tricks_render-all-properties-in-tables.adoc[leveloffset=+1]
+include::_ug_more-advanced_tips-n-tricks_per-user-themes.adoc[leveloffset=+1]
+include::_ug_more-advanced_tips-n-tricks_enhance-only.adoc[leveloffset=+1]
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_tips-n-tricks_are-you-sure.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_tips-n-tricks_are-you-sure.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_tips-n-tricks_are-you-sure.adoc
new file mode 100644
index 0000000..7fb1a73
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_tips-n-tricks_are-you-sure.adoc
@@ -0,0 +1,55 @@
+[[_ug_more-advanced_tips-n-tricks_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/
+
+If providing an action that will perform irreversible changes, include a
+mandatory boolean parameter that must be explicitly checked by the end-user
+in order for the action to proceed.
+
+
+
+== Screenshots
+
+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:ug.adoc#_ug_wicket-viewer[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[]
+
+
+
+
+== Code example
+
+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:rg.adoc#_rg_methods_prefixes_manpage-validate[`validate...()`] method.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_tips-n-tricks_enhance-only.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_tips-n-tricks_enhance-only.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_tips-n-tricks_enhance-only.adoc
new file mode 100644
index 0000000..1854a30
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_tips-n-tricks_enhance-only.adoc
@@ -0,0 +1,17 @@
+[[_ug_more-advanced_tips-n-tricks_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 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/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_tips-n-tricks_per-user-themes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_tips-n-tricks_per-user-themes.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_tips-n-tricks_per-user-themes.adoc
new file mode 100644
index 0000000..19c950f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_tips-n-tricks_per-user-themes.adoc
@@ -0,0 +1,85 @@
+[[_ug_more-advanced_tips-n-tricks_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 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/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_tips-n-tricks_render-all-properties-in-tables.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_tips-n-tricks_render-all-properties-in-tables.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_tips-n-tricks_render-all-properties-in-tables.adoc
new file mode 100644
index 0000000..cf2432c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_tips-n-tricks_render-all-properties-in-tables.adoc
@@ -0,0 +1,49 @@
+[[_ug_more-advanced_tips-n-tricks_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/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_tips-n-tricks_simulating-collections-of-values.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_tips-n-tricks_simulating-collections-of-values.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_tips-n-tricks_simulating-collections-of-values.adoc
new file mode 100644
index 0000000..58a3a0f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_tips-n-tricks_simulating-collections-of-values.adoc
@@ -0,0 +1,23 @@
+[[_ug_more-advanced_tips-n-tricks_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
+
+IMPORTANT: TODO
+
+
+
+== Persistence Concerns
+
+IMPORTANT: WIP - easiest to simply store using DataNucleus' support for collections, marked as xref:rg.adoc#_rg_annotations_manpage-Programmatic[`@Programmatic`] so that it is ignored by 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/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_transactions-and-errors.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_transactions-and-errors.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_transactions-and-errors.adoc
new file mode 100644
index 0000000..14ddd61
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_transactions-and-errors.adoc
@@ -0,0 +1,33 @@
+[[_ug_more-advanced_transactions-and-errors]]
+= Transactions and Errors
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 Isis, every action invocation (in fact, every interaction) is automatically wrapped in a transaction, and any repository query automatically does a flush.
+
+What that means is that there's no need to explicitly start or commit transactions in Isis; this will be done for you. Indeed, if you do try to manage transactions (eg by reaching into the JDO `PersistenceManager` exposed by the xref:rg.adoc#_rg_services-api_manpage-IsisJdoSupport[IsisJdoSupport] domain service, then you are likely to confuse Isis and get a stack trace for your trouble.
+
+
+
+
+== Aborting Transactions
+
+If you want to abort Isis' transaction, this can be done by throwing `RecoverableException` (or any subclass, eg `ApplicationException`). The transaction will be aborted, and the exception message will be displayed to the user.
+
+If you throw any other exception (ie not a subclass of `RecoverableException`), then the users will see an error page (if Wicket viewer) or a 500 (if Restful Objects viewer).
+
+
+
+
+
+== Raise message/errors to users
+
+IMPORTANT: TODO - xref:rg.adoc#_rg_services-api_manpage-DomainObjectContainer_messages-api[`DomainObjectContainer`]
+
+
+
+== Exception Recognizers
+
+IMPORTANT: TODO - xref:rg.adoc#_rg_services-spi_manpage-ExceptionRecognizer[`ExceptionRecognizer`] service
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_view-models.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_view-models.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_view-models.adoc
new file mode 100644
index 0000000..2cebc7b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_view-models.adoc
@@ -0,0 +1,22 @@
+[[_ug_more-advanced_view-models]]
+= View Models
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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: WIP - xref:rg.adoc#_rg_annotations_manpage-ViewModel[`@ViewModel`], xref:rg.adoc#_rg_classes_super_manpage-AbstractViewModel[`AbstractViewModel`], xref:rg.adoc#_rg_annotations_manpage-DomainObject_nature[`@DomainObject#nature()`]
+
+
+Nature of view models
+
+* inmemory-entity
+* external_entity
+* application layer
+
+Consumers of view models
+
+* within the Wicket viewer
+* within the REST viewer, as an external client consuming a stable API
+
+An alternative to using view models is to map the domain object using the xref:rg.adoc#_rg_services-spi_manpage-ContentMappingService[`ContentMappingService`].
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_restfulobjects-viewer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_restfulobjects-viewer.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_restfulobjects-viewer.adoc
new file mode 100644
index 0000000..256a6cd
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_restfulobjects-viewer.adoc
@@ -0,0 +1,25 @@
+[[_ug_restfulobjects-viewer]]
+= Restful Objects 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/
+
+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.
+
+The Restful Objects viewer also provides a number of proprietary extensions.
+
+
+
+include::_ug_restfulobjects-viewer_features.adoc[leveloffset=+1]
+
+include::_ug_restfulobjects-viewer_configuration-properties.adoc[leveloffset=+1]
+
+include::_ug_restfulobjects-viewer_hints-and-tips.adoc[leveloffset=+1]
+
+
+== Extending the viewer
+
+... is discussed in xref:ug.adoc#_ug_extending_restfulobjects-viewer[Extending the Restful Objects viewer].
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_restfulobjects-viewer_configuration-properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_restfulobjects-viewer_configuration-properties.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_restfulobjects-viewer_configuration-properties.adoc
new file mode 100644
index 0000000..147238d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_restfulobjects-viewer_configuration-properties.adoc
@@ -0,0 +1,72 @@
+[[_ug_restfulobjects-viewer_configuration-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/
+
+
+The Restful Objects viewer provides a number 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).
+
+[WARNING]
+====
+These configuration settings should be considered beta, and may change in the future in response to emerging requirements.
+
+Also, be aware enabling these settings makes the representations with respect to the http://restfulobjects.org[Restful Object spec]. (Based on experience in Isis, in the future the spec may be updated to allow such extensions).
+====
+
+
+.Restful Objects Viewer Configuration Properties
+[cols="2a,1,3", options="header"]
+|===
+|Property
+|Value +
+(_default value_)
+|Description
+
+|`isis.viewer.restfulobjects.` +
+`honorUiHints`
+| `true`,`false` (`_false_`)
+| See xref:ug.adoc#_ug_restfulobjects-viewer_configuration-properties_honor-ui-hints[discussion], below.
+
+|`isis.viewer.restfulobjects.` +
+`suppressDescribedByLinks`
+| `true`,`false` (`_false_`)
+.6+| See xref:ug.adoc#_ug_restfulobjects-viewer_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:ug.adoc#_ug_restfulobjects-viewer_configuration-properties_simplified-object[discussion], below.
+
+|===
+
+
+
+
+include::_ug_restfulobjects-viewer_configuration-properties_honor-ui-hints.adoc[leveloffset=+1]
+include::_ug_restfulobjects-viewer_configuration-properties_suppressing-elements.adoc[leveloffset=+1]
+include::_ug_restfulobjects-viewer_configuration-properties_simplified-object-representation.adoc[leveloffset=+1]
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_restfulobjects-viewer_configuration-properties_honor-ui-hints.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_restfulobjects-viewer_configuration-properties_honor-ui-hints.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_restfulobjects-viewer_configuration-properties_honor-ui-hints.adoc
new file mode 100644
index 0000000..c9122cc
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_restfulobjects-viewer_configuration-properties_honor-ui-hints.adoc
@@ -0,0 +1,27 @@
+[[_ug_restfulobjects-viewer_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 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.
+====
+
+
+
[31/45] isis git commit: ISIS-1133: breaking out reference guide and
devenv guide;
moving appendices' release notes and migration notes to other docs;
improving the documentation page.
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_headless-access.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_headless-access.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_headless-access.adoc
new file mode 100644
index 0000000..7a6bb7b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_headless-access.adoc
@@ -0,0 +1,27 @@
+[[_ug_headless-access]]
+= Headless access
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 tackles the topic of enabling access to an Isis application directly, or at least, not through either the xref:ug.adoc#_ug_wicket-viewer[Wicket] or xref:ug.adoc#_ug_restfulobjects-viewer[Restful] viewers.
+
+There are several main use-cases:
+
+* enabling background execution, eg of a thread managed by Quartz scheduler and running within the webapp
+
+* integration from other systems, eg for a subscriber on a pub/sub mechanism such as Camel, pushing changes through an Isis domain model.
+
+* leveraging an Isis application within a batch process
+
+Note that the calling thread runs in the same process space as the Isis domain object model (must be physically linked to the JAR files containing the domain classes). For use cases where the calling thread runs in some other process space (eg migrating data from a legacy system), then the xref:ug.adoc#_ug_restfulobjects-viewer[Restful Objects viewer] is usually the way to go.
+
+The API described in this chapter is reasonably low-level, allowing code to interact very directly with the Isis metamodel and runtime. Such callers should be considered trusted: they do not (by default) honour any business rules eg implicit in the Isis annotations or hide/disable/validate methods. However the <<WrapperFactory>> service could be used to enforce such business rules if required.
+
+
+
+include::_ug_headless-access_AbstractIsisSessionTemplate.adoc[leveloffset=+1]
+include::_ug_headless-access_BackgroundCommandExecution.adoc[leveloffset=+1]
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_headless-access_AbstractIsisSessionTemplate.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_headless-access_AbstractIsisSessionTemplate.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_headless-access_AbstractIsisSessionTemplate.adoc
new file mode 100644
index 0000000..7402a2e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_headless-access_AbstractIsisSessionTemplate.adoc
@@ -0,0 +1,40 @@
+[[_ug_headless-access_AbstractIsisSessionTemplate]]
+= AbstractIsisSessionTemplate
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `AbstractIsisSessionTemplate` class (whose name is inspired by the Spring framework's naming convention for similar classes that query http://docs.spring.io/spring/docs/2.5.x/reference/jdbc.html#jdbc-JdbcTemplate[JDBC], http://docs.spring.io/spring/docs/2.5.x/reference/jms.html#jms-jmstemplate[JMS], http://docs.spring.io/spring/docs/2.5.x/reference/orm.html#orm-jpa-template[JPA] etc.) provides the mechanism to open up a 'session' within the Isis framework, in order to resolve and interact with entities.
+
+The class itself is intended to be subclassed:
+
+[source,java]
+----
+public abstract class AbstractIsisSessionTemplate {
+
+ public void execute(final AuthenticationSession authSession, final Object context) { ... } //<1>
+ protected abstract void doExecute(Object context); // <2>
+
+ protected ObjectAdapter adapterFor(final Object targetObject) { ... }
+ protected ObjectAdapter adapterFor(final RootOid rootOid) { ... }
+
+ protected PersistenceSession getPersistenceSession() { ... }
+ protected IsisTransactionManager getTransactionManager() { ... }
+ protected AdapterManager getAdapterManager() { ... }
+}
+----
+<1> `execute(...)` sets up the `IsisSession` and delegates to ...
+<2> `doExecute(...)`, the mandatory hook method for subclasses to implement.
+The passed object represents passes a context from the caller (eg the scheduler, cron job, JMS etc) that instantiated and executed the class.
+
+The `protected` methods expose key internal APIs within Isis, for the subclass to use as necessary.
+
+
+[TIP]
+====
+One notable feature of `AbstractIsisSessionTemplate` is that it will automatically inject any domain services into itself. Thus, it is relatively easy for the subclass to "reach into" the domain, through injected repository services.
+====
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_headless-access_BackgroundCommandExecution.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_headless-access_BackgroundCommandExecution.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_headless-access_BackgroundCommandExecution.adoc
new file mode 100644
index 0000000..1c82eff
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_headless-access_BackgroundCommandExecution.adoc
@@ -0,0 +1,45 @@
+[[_ug_headless-access_BackgroundCommandExecution]]
+= BackgroundCommandExecution
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `BackgroundCommandExecution` class (a subclass of <<AbstractIsisSessionTemplate>>) is intended to simplify the execution of background ``Command``s persisted by way of the <<CommandService>> and the <<BackgroundCommandService>>.
+
+Its signature is:
+
+[source,java]
+----
+public abstract class BackgroundCommandExecution extends AbstractIsisSessionTemplate {
+ protected void doExecute(Object context) { ... }
+ protected abstract List<? extends Command> findBackgroundCommandsToExecute(); // <1>
+}
+----
+<1> `findBackgroundCommandsToExecute()` is a mandatory hook method for subclasses to implement.
+
+This allows for different implementations of the `CommandService` and `BackgroundCommandService` to persist to wherever.
+
+The diagram below (http://yuml.me/edit/363b335f[yuml.me/363b335f]) shows the dependencies between these various classes:
+
+.Inheritance Hierarchy for `BackgroundCommandExecution`
+image::{_imagesdir}headless-access/BackgroundCommandExecution.png[width="400px"]
+
+
+
+
+
+
+
+== Background Execution
+
+The `BackgroundCommandExecutionFromBackgroundCommandServiceJdo` is a concrete subclass of `BackgroundCommandExecution` (see the xref:rg.adoc#_rg_services-api_manpage-BackgroundService[`BackgroundCommandService`]), the intended use being for the class to be instantiated regularly (eg every 10 seconds) by a scheduler such as http://quartz-scheduler.org[Quartz]) to poll for ``Command``s to be executed, and then execute them.
+
+This implementation queries for ``Command``s persisted by the link:http://www.isisaddons.org/isis-module-command[Isis addons Command Module]'s implementations of xref:rg.adoc#_rg_services-spi_manpage-CommandService[`CommandService`] and xref:rg.adoc#_rg_services-spi_manpage-BackgroundCommandService[`BackgroundCommandService`] using the `BackgroundCommandServiceJdoRepository`.
+
+The diagram below (link:http://yuml.me/edit/25343da1[yuml.me/25343da1]) shows the inheritance hierarchy for this class:
+
+.Inheritance Hierarchy for `BackgroundCommandExecutionFromBackgroundCommandServiceJdo`
+image::{_imagesdir}headless-access/BackgroundCommandExecutionFromBackgroundCommandServiceJdo.png[width="500px"]
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..d03210e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos.adoc
@@ -0,0 +1,20 @@
+[[_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 instructions on how to go about actually developing 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]
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..4b0fdd0
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_business-rules.adoc
@@ -0,0 +1,72 @@
+[[_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/
+
+IMPORTANT: TODO
+
+
+
+== Visibility ("see it")
+
+IMPORTANT: TODO - xref:rg.adoc#_rg_methods_prefixes_manpage-hide[`hide...()`]
+
+### Hide a Property
+
+### Hide a Collection
+
+### Hide an Action
+
+### Hide a Contributed Property, Collection or Action
+
+### All Members Hidden
+
+
+
+
+== Usability ("use it")
+
+IMPORTANT: TODO - xref:rg.adoc#_rg_methods_prefixes_manpage-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")
+
+IMPORTANT: 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()`]
+
+
+### 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
+
+IMPORTANT: TODO - using xref:rg.adoc#_rg_annotations_manpage-Action_mustSatisfy[`@Action#mustSatisfy()`], xref:rg.adoc#_rg_annotations_manpage-Property_mustSatisfy[`@Property#mustSatisfy()`]
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..860a5a3
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure.adoc
@@ -0,0 +1,38 @@
+[[_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, view models 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 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 Isis programming model.
+
+[TIP]
+====
+In fact, Isis programming model is extensible; you can teach 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 Isis programming model xref:ug.adoc#_ug_extending_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/9c5dafab/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
new file mode 100644
index 0000000..d19d7fe
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_action-parameters.adoc
@@ -0,0 +1,26 @@
+[[_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/
+
+
+IMPORTANT: TODO
+
+
+
+== ``String``s (Length)
+
+IMPORTANT: TODO
+
+
+== ``BigDecimal``s (Precision)
+
+IMPORTANT: TODO
+
+
+== Optional
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..fe7fef2
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_actions.adoc
@@ -0,0 +1,19 @@
+[[_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/
+
+
+
+IMPORTANT: TODO
+
+
+[NOTE]
+====
+While Isis support actions whose parameters' types are scalar (values such as `String`, `int`, or references such as `Customer`), the framework (currently) does not support parameter types that are collections or maps.
+
+The workaround is to mark the collection as `@Programmatic`, as described in xref:ug.adoc#_ug_how-tos_class-structure_ignoring-methods[Ignoring Methods]. This ensures that the collection is ignored by Isis.
+====
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..ed7c1c6
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_class-definition.adoc
@@ -0,0 +1,24 @@
+[[_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/
+
+
+
+IMPORTANT: WIP
+
+
+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:ug.adoc#_ug_more-advanced_decoupling[decoupling].
+====
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..b23920d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_collections.adoc
@@ -0,0 +1,26 @@
+[[_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/
+
+
+IMPORTANT: WIP
+
+
+[NOTE]
+====
+While Isis support collections of references, the framework (currently) does not support collections of values. That is, it isn't possible to define a collection of type `Set<String>`.
+
+Or, actually, you can, because that is a valid mapping supported by JDO/DataNucleus . However, Isis has no default visualization.
+
+One workaround is to mark the collection as xref:rg.adoc#_rg_annotations_manpage-Progammatic[`@Progammatic`]. This ensures that the collection is ignored by Isis.
+
+Another workaround is to wrap each value in a view model, as explained in this xref:ug.adoc#_ug_more-advanced_tips-n-tricks_simulating-collections-of-values[tip].
+====
+
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..523668b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_ignoring-methods.adoc
@@ -0,0 +1,16 @@
+[[_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/
+
+
+
+IMPORTANT: WIP
+
+
+Sometimes you want to define a `public` method on a domain object that is not intended to be rendered in Isis' UI.
+
+To exclude such methods, use the xref:rg.adoc#_rg_annotations_manpage-Programmatic[`@Programmatic`] annotation.
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..175499d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_inject-services.adoc
@@ -0,0 +1,83 @@
+[[how-to-inject-services-into-a-domain-entity-or-other-service]]
+= 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 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/9c5dafab/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
new file mode 100644
index 0000000..91cec84
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_properties-vs-parameters.adoc
@@ -0,0 +1,45 @@
+[[_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/
+
+
+
+IMPORTANT: WIP
+
+
+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 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 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/9c5dafab/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
new file mode 100644
index 0000000..c6d9b25
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure_properties.adoc
@@ -0,0 +1,283 @@
+[[_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/
+
+
+IMPORTANT: TODO
+
+
+
+
+
+== Value vs Reference Types
+
+IMPORTANT: WIP
+
+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 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 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 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 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 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)
+
+IMPORTANT: 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 = "BLOB")
+})
+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 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 = "BLOB",
+ allowsNull="false")
+})
+private Blob attachment;
+@Property(
+ optionality = Optionality.MANDATORY
+)
+public Blob getAttachment() {
+return attachment;
+}
+public void setAttachment(final Blob attachment) {
+this.attachment = attachment;
+}
+----
+
+=== Mapping Clobs
+
+Mapping `Clob`s works in a very similar way, but the `@Column#sqlType` attribute will be `CLOB`:
+
+[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", sqlType = "CLOB")
+})
+private Clob doc;
+@Property(
+ optionality = Optionality.OPTIONAL
+)
+public Clob getDoc() {
+ return doc;
+}
+public void setDoc(final Clob doc) {
+ this.doc = doc;
+}
+----
+
+
+=== Mapping to VARBINARY or VARCHAR
+
+Instead of mapping to a `Blob` or `Clob` datatype, you might also specify map to a `VARBINARY` or `VARCHAR`. In this case you will need to specify a length. For example:
+
+
+[source,java]
+----
+@javax.jdo.annotations.Column(name = "attachment_bytes", sqlType = "VARBINARY", length=2048)
+----
+
+or
+
+[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/9c5dafab/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
new file mode 100644
index 0000000..b45b6fd
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_contributed-members.adoc
@@ -0,0 +1,69 @@
+[[_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/
+
+
+
+IMPORTANT: WIP - 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
+
+IMPORTANT: TODO
+
+## Contributed Property
+
+IMPORTANT: TODO
+
+## Contributed Collection
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..cbe7393
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_crud.adoc
@@ -0,0 +1,29 @@
+[[_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/
+
+IMPORTANT: TODO
+
+
+## Instantiating and Persisting Objects
+
+IMPORTANT: TODO - using ``DomainObjectContainer``'s support for xref:rg.adoc#_rg_services-api_manpage-DomainObjectContainer_object-creation-api[creation] and xref:rg.adoc#_rg_services-api_manpage-DomainObjectContainer_object-persistence-api[persistence]
+
+## Finding Objects
+
+IMPORTANT: TODO - using xref:rg.adoc#_rg_services-api_manpage-DomainObjectContainer_generic-repository-api[`DomainObjectContainer`]
+
+### Using DataNucleus type-safe queries
+
+IMPORTANT: TODO - as described xref:rg.adoc#_rg_services-api_manpage-IsisJdoSupport_type-safe-jdoql-queries[here]
+
+
+
+## Deleting Objects
+
+IMPORTANT: TODO using ``DomainObjectContainer``'s support for xref:rg.adoc#_rg_services-api_manpage-DomainObjectContainer_object-persistence-api[persistence]
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..8c6a8e5
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_derived-members.adoc
@@ -0,0 +1,48 @@
+[[_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/
+
+IMPORTANT: TODO
+
+
+
+
+== Derived Property
+
+IMPORTANT: TODO
+
+
+
+
+== Derived Collection
+
+IMPORTANT: WIP
+
+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
+
+IMPORTANT: TODO - xref:rg.adoc#_rg_methods_prefixes_manpage-modify[`modify...()`], xref:rg.adoc#_rg_methods_prefixes_manpage-clear[`clear...()`]
+
+
+
+== Trigger on collection change
+
+IMPORTANT: TODO - xref:rg.adoc#_rg_methods_prefixes_manpage-addTo[`addTo...()`], xref:rg.adoc#_rg_methods_prefixes_manpage-removeFrom[`removeFrom...()`]
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..cc26c90
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_domain-services.adoc
@@ -0,0 +1,164 @@
+[[_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/
+
+
+
+
+It's worth extending the <<_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"]
+
+Here, we can see that the addons provide services both to the Isis framework (for example security, command and auditing) and also - by way of dependency injection - to the domain objects (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:rg.adoc#_rg_services-api[here] and xref:rg.adoc#_rg_services-spi[here].
+
+
+
+
+
+== 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:rg.adoc#_rg_annotations_manpage-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:rg.adoc#_rg_services-api[here] and xref:rg.adoc#_rg_services-spi[here] for further details.
+
+
+
+
+== Registering domain services
+
+
+IMPORTANT: TODO - discuss @DomainService if `isis.services-installer=annotation-and-configuration`; how to override these defaults by explicit registration
+
+Domain services (which includes repositories and factories) can be registered 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:rg.adoc#_rg_services-api[here] and _rg_services-spi[here] for further details.
+
+
+
+
+
+== Contributions
+
+IMPORTANT: WIP - just xref xref:ug.adoc#_ug_how-tos_contributed-members[contributed members] section.
+
+
+
+
+
+
+== Menu items
+
+IMPORTANT: WIP - update to new annotations, including @DomainService(nature=...)
+
+
+By default every action of a service (by which we also mean repositories and factories) will be rendered in the viewer, eg as a menu item for that service menu. This behaviour can be suppressed by annotating the action using `@org.apache.isis.applib.annotations.NotInServiceMenu`.
+
+For example:
+
+[source,java]
+----
+public interface Library {
+ @NotInServiceMenu
+ public Loan borrow(Loanable l, Borrower b);
+}
+----
+
+Note that an action annotated as being `@NotInServiceMenu` will still be contributed. If an action should neither be contributed nor appear in service menu items, then simply annotate it as `@Hidden`.
+
+Alternatively, this can be performed using a supporting method:
+
+[source,java]
+----
+public class LibraryImpl implements Library {
+ public Loan borrow(Loanable l, Borrower b) { ... }
+ public boolean notInServiceMenuBorrow() { ... }
+}
+----
+
+
+
+
+== Menus
+
+IMPORTANT: WIP - update to new annotations, including @DomainService(nature=...)
+
+If none of the service menu items should appear, then the service itself should be annotated as `@Hidden`.
+
+For example:
+
+[source,java]
+----
+@Hidden
+public interface EmailService {
+ public void sendEmail(String to, String from, String subject, String body);
+ public void forwardEmail(String to, String from, String subject, String body);
+}
+----
+
+
+
+
+== 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 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:rg.adoc#_rg_annotations_manpage-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:rg.adoc#_rg_annotations_manpage-PreDestroy[`@PreDestroy`].
+
+
+
+
+== 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.
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..0ac05e7
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_drop-downs-and-defaults.adoc
@@ -0,0 +1,65 @@
+[[_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/
+
+IMPORTANT: TODO
+
+
+== For Properties
+
+IMPORTANT: WIP
+
+### Choices for Property
+
+IMPORTANT: TODO - xref:rg.adoc#_rg_methods_prefixes_manpage-choices[`choices...()`]
+
+### Auto-complete for property
+
+IMPORTANT: TODO - xref:rg.adoc#_rg_methods_prefixes_manpage-autoComplete[`autoComplete...()`]
+
+### Default for property
+
+IMPORTANT: TODO - xref:rg.adoc#_rg_methods_prefixes_manpage-default[`default...()`]
+
+
+
+
+== For Action Parameters
+
+IMPORTANT: WIP
+
+### Choices for action parameter
+
+IMPORTANT: TODO - xref:rg.adoc#_rg_methods_prefixes_manpage-choices[`choices...()`]
+
+### Dependent choices for action params
+
+IMPORTANT: TODO - xref:rg.adoc#_rg_methods_prefixes_manpage-choices[`choices...()`]
+
+### Auto-complete for action param
+
+IMPORTANT: TODO - xref:rg.adoc#_rg_methods_prefixes_manpage-autoComplete[`autoComplete...()`]
+
+### Default for action param
+
+IMPORTANT: TODO - xref:rg.adoc#_rg_methods_prefixes_manpage-default[`default...()`]
+
+
+
+
+
+== For both Properties and Action Parameters
+
+IMPORTANT: WIP
+
+
+### Drop-down for limited number of instances
+
+IMPORTANT: TODO - xref:rg.adoc#_rg_annotations_manpage-DomainObject_bounded[`@DomainObject#bounded()`]
+
+
+### Auto-complete (repository-based)
+
+xref:rg.adoc#_rg_annotations_manpage-DomainObject_autoComplete[`@DomainObject#autoComplete()`]
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..611946b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_entity-relationships.adoc
@@ -0,0 +1,15 @@
+[[_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/
+
+
+IMPORTANT: TODO
+
+== Mandatory and Optional
+
+IMPORTANT: 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/9c5dafab/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
new file mode 100644
index 0000000..ec5681e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships.adoc
@@ -0,0 +1,58 @@
+[[_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: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.
+
+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 (as of Isis 1.4.1) hit an NullPointerException. This may be a bug in DataNucleus, we are not completely sure, but the above idiom seems to fix the issue.
+
+For more information, see http://isis.markmail.org/thread/ipu2lzqqikqdglox[this thread] on the 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/9c5dafab/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
new file mode 100644
index 0000000..62a57b6
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints.adoc
@@ -0,0 +1,15 @@
+[[_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 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]
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..29c2827
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_action-icons-and-css.adoc
@@ -0,0 +1,58 @@
+[[_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
+
+IMPORTANT: WIP - xref:rg.adoc#_rg_annotations_manpage-ActionLayout_cssClass[`@ActionLayout#cssClass()`] and xref:rg.adoc#_rg_annotations_manpage-ActionLayout_cssClassFa[`@ActionLayout#cssClassFa()`]
+
+
+Alternatively, you can specify these hints dynamically in the xref:rg.adoc#_rg_object-layout[`Xxx.layout.json`] for the entity.
+
+
+== Per pattern matching
+
+Rather than annotating every action with xref:rg.adoc#_rg_annotations_manpage-ActionLayout_cssClassFa[`@ActionLayout#cssClassFa()`] and xref:rg.adoc#_rg_annotations_manpage-ActionLayout_cssClass[`@ActionLayout#cssClass()`] you can instead specify the UI hint globally using regular expressions.
+
+The xref:ug.adoc#_ug_runtime_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:ug.adoc#_ug_runtime_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:rg.adoc#_rg_annotations_manpage-ActionLayout_cssClassFa[`@ActionLayout#cssClassFa()`] or xref:rg.adoc#_rg_annotations_manpage-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/9c5dafab/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
new file mode 100644
index 0000000..bf35d00
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_eager-rendering.adoc
@@ -0,0 +1,58 @@
+[[_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:
+
+IMPORTANT: TODO - screenshot here
+
+For the more commonly used collections we want to show the table expanded:
+
+IMPORTANT: 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/9c5dafab/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
new file mode 100644
index 0000000..4af7fc5
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_layout.adoc
@@ -0,0 +1,9 @@
+[[_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:rg.adoc#_rg_object-layout[object layout] chapter.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..201b1ee
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_ui-hints_names-and-descriptions.adoc
@@ -0,0 +1,47 @@
+[[_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/
+
+IMPORTANT: TODO
+
+
+
+NOTE: see also xref:ug.adoc#_ug_more-advanced_i18n[Internationalization]
+
+== Class (object)
+
+IMPORTANT: TODO - xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_named[`@DomainObjectLayout#named()`], xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_describedAs[`@DomainObjectLayout#describedAs()`]
+
+
+== Property
+
+IMPORTANT: TODO - xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_named[`@PropertyLayout#named()`], xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_describedAs[`@PropertyLayout#describedAs()`]
+
+
+
+== Collections
+
+IMPORTANT: TODO - xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_named[`@CollectionLayout#named()`], xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_describedAs[`@CollectionLayout#describedAs()`]
+
+
+
+== Actions
+
+IMPORTANT: TODO - xref:rg.adoc#_rg_annotations_manpage-ActionLayout_named[`@ActionLayout#named()`], xref:rg.adoc#_rg_annotations_manpage-ActionLayout_describedAs[`@ActionLayout#describedAs()`]
+
+
+== Action Parameters
+
+IMPORTANT: TODO - xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_named[`@ParameterLayout#named()`], xref:rg.adoc#_rg_annotations_manpage-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:_upgrading_to_java_8_1_9_0_snapshot_and_later[upgrading to Java 8].
+====
+
+
+
+
[29/45] isis git commit: ISIS-1133: breaking out reference guide and
devenv guide;
moving appendices' release notes and migration notes to other docs;
improving the documentation page.
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_restfulobjects-viewer_configuration-properties_simplified-object-representation.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_restfulobjects-viewer_configuration-properties_simplified-object-representation.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_restfulobjects-viewer_configuration-properties_simplified-object-representation.adoc
new file mode 100644
index 0000000..b682dd7
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_restfulobjects-viewer_configuration-properties_simplified-object-representation.adoc
@@ -0,0 +1,68 @@
+[[_ug_restfulobjects-viewer_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:ug.adoc#_ug_restfulobjects-viewer_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:ug.adoc#_ug_extending_restfulobjects-viewer[Extending the Restful Objects viewer].
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_restfulobjects-viewer_configuration-properties_suppressing-elements.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_restfulobjects-viewer_configuration-properties_suppressing-elements.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_restfulobjects-viewer_configuration-properties_suppressing-elements.adoc
new file mode 100644
index 0000000..1942b9b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_restfulobjects-viewer_configuration-properties_suppressing-elements.adoc
@@ -0,0 +1,39 @@
+[[_ug_restfulobjects-viewer_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:ug.adoc#_ug_restfulobjects-viewer_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:ug.adoc#_ug_extending_restfulobjects-viewer[Extending the Restful Objects viewer] in the <<Extending>> chapter.
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_restfulobjects-viewer_features.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_restfulobjects-viewer_features.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_restfulobjects-viewer_features.adoc
new file mode 100644
index 0000000..905aeb2
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_restfulobjects-viewer_features.adoc
@@ -0,0 +1,23 @@
+[[_ug_restfulobjects-viewer_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 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.
+
+== Restful Objects Specification
+
+IMPORTANT: TODO - a brief summary here
+
+The Restful Objects spec can be downloaded link:http://restfulobjects.org[here].
+
+== Pretty printing
+
+The JSON representations generated by the Restful Objects viewer are in compact form if the xref:ug.adoc#_ug_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.
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_restfulobjects-viewer_hints-and-tips.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_restfulobjects-viewer_hints-and-tips.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_restfulobjects-viewer_hints-and-tips.adoc
new file mode 100644
index 0000000..b42c58a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_restfulobjects-viewer_hints-and-tips.adoc
@@ -0,0 +1,81 @@
+[[_ug_restfulobjects-viewer_hints-and-tips]]
+= Hints and Tips
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+Since the Restful Objects viewer is designed for computer programs to interact with (rather than human beings), it can be a little difficult to explore and generally "grok" how it works.
+
+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.
+
+video::_-TOvVYWCHc[youtube,width="840px",height="472px"]
+
+
+
+
+== AngularJS Tips
+
+The hypermedia API exposed by Isis' Restful Objects viewer is intended be support both bespoke custom-written viewers as well as generic viewers. Indeed, we expect most clients consuming the API will be bespoke, not generic.
+
+This page captures one or two tips on using AngularJS to write such a bespoke client.
+
+
+=== Invoking a GET link (eg invoking a query action)
+
+Suppose you have a `CustomerService` providing a `findCustomer` action:
+
+[source,java]
+----
+public class CustomerService {
+ public String id() { return "customers"; }
+ @ActionSemantics(Of.SAFE)
+ public Customer findCustomer(@Named("customerName") String customerName) { ... }
+}
+----
+
+Restful Objects will expose this as action with the following link that looks something like:
+
+[source,javascript]
+----
+{
+ "rel" : "urn:org.restfulobjects:rels/invoke",
+ "href" : "http://localhost:8080/restful/services/customers/actions/findCustomer/invoke",
+ "method" : "GET",
+ "type" : "application/json;profile=\"urn:org.restfulobjects:repr-types/action-result\"",
+ "arguments" : {
+ "customerName" : {
+ "value" : null
+ }
+ }
+}
+----
+
+You can then invoke this using AngularJs' `$resource` service as follows.
+
+[source,javascript]
+----
+var findCustomer = $resource("http://localhost:8080/restful/services/customers/actions/findCustomer/invoke?:queryString");
+var findCustomerArgs = {
+ "customerName": {
+ "value": "Fred"
+ }
+};
+findCustomer.get({queryString: JSON.stringify(findCustomerArgs)}, function(data) { ... } )
+----
+
+Here the `:queryString` placeholder in the initial `$resource` constructor is expanded with a stringified version of the JSON object representing the args. Note how the `findCustomerArgs` is the same as the `"arguments"` attribute in the original link (with a value provided instead of `null`).
+
+
+=== Invoking a PUT or POST link
+
+If the method is a PUT or a POST, then no `:queryString` placeholder is required in the URL, and the args are instead part of the body.
+
+Use `$resource.put(...)` or `$resource.post(...)` instead.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_runtime.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_runtime.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_runtime.adoc
new file mode 100644
index 0000000..633f79c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_runtime.adoc
@@ -0,0 +1,29 @@
+[[_ug_runtime]]
+= Runtime
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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:ug.adoc#_ug_wicket-viewer[Wicket Viewer] chapter and the <<Restful Objects Viewer>> chapter. Likewise[details of configuring security (Apache Shiro) can be found in the xref:ug.adoc#_ug_security[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 <<Deployment>> chapter.
+====
+
+
+include::_ug_runtime_deployment-types.adoc[leveloffset=+1]
+include::_ug_runtime_configuration-files.adoc[leveloffset=+1]
+include::_ug_runtime_specifying-components.adoc[leveloffset=+1]
+include::_ug_runtime_configuring-core.adoc[leveloffset=+1]
+include::_ug_runtime_configuring-datanucleus.adoc[leveloffset=+1]
+include::_ug_runtime_web-xml.adoc[leveloffset=+1]
+include::_ug_runtime_application-specific.adoc[leveloffset=+1]
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_application-specific.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_application-specific.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_application-specific.adoc
new file mode 100644
index 0000000..156fad5
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_application-specific.adoc
@@ -0,0 +1,13 @@
+[[_ug_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/
+
+IMPORTANT: TODO
+
+
+include::_ug_runtime_application-specific_application-css.adoc[leveloffset=+1]
+include::_ug_runtime_application-specific_application-js.adoc[leveloffset=+1]
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_application-specific_application-css.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_application-specific_application-css.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_application-specific_application-css.adoc
new file mode 100644
index 0000000..59fdc5a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_application-specific_application-css.adoc
@@ -0,0 +1,8 @@
+[[_ug_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/
+
+IMPORTANT: TODO - `WEB-INF/css/application.css`
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_application-specific_application-js.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_application-specific_application-js.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_application-specific_application-js.adoc
new file mode 100644
index 0000000..4b97f1b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_application-specific_application-js.adoc
@@ -0,0 +1,9 @@
+[[_ug_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/
+
+
+
+IMPORTANT: TODO - `WEB-INF/scripts/application.js`
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuration-files.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuration-files.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuration-files.adoc
new file mode 100644
index 0000000..04b8d82
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuration-files.adoc
@@ -0,0 +1,36 @@
+[[_ug_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 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:ug.adoc#_ug_wicket-viewer[Wicket UI (viewer)] is in use
+
+* `viewer_restfulobjects.properties` - if the xref:ug.adoc#_ug_restfulobjects-viewer[Restful Objects REST API (viewer)] is in use
+
+* `viewer.properties` - for any shared UI configuration
+
+* `persistor_datanucleus.properties` - assuming the JDO/DataNucleus objectstore is in use
+
+* `persistor.properties` - for any other objectstore configuration. This typically is used to hold `JDBC` ``URL``s
+
+* `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/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-core.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-core.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-core.adoc
new file mode 100644
index 0000000..8ce2e45
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-core.adoc
@@ -0,0 +1,239 @@
+[[_ug_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:ug.adoc#_ug_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:ug.adoc#_ug_wicket-viewer_configuration-properties[here for Wicket viewer], and xref:ug.adoc#_ug_restfulobjects-viewer_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:rg.adoc#_rg_annotations_manpage-DomainObject_editing[`@DomainObject#editing()`]); see xref:ug.adoc#_ug_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 Isis itself. (Note that there is no "datanucleus" in the property).
+
+|`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:_user-guide_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:_user-guide_how-tos_ui-hints_action-icons-and-css[UI hints] for more details.
+
+|`isis.reflector.facets`
+|`FQCN`
+|Fully qualified class names of a custom implementation of `ProgrammingModel` interface. +
+
+See xref:ug.adoc#_ug_extending_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:ug.adoc#_ug_extending_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:ug.adoc#_ug_extending_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:rg.adoc#_rg_object-layout_dynamic[dynamic layout]s. +
+
+See xref:ug.adoc#_ug_extending_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:ug.adoc#_ug_extending_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:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`]).
+
+
+|`isis.services.` +
+`audit.objects`
+| `all`, `none` (`all`)
+|Whether the changed properties of objects should be automatically audited (for objects annotated with xref:rg.adoc#_rg_annotations_manpage-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:rg.adoc#_rg_annotations_manpage-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.service.` +
+`email.tls.enabled` +
+| `true`,`false` (`_true_`)
+|Whether to enable TLS for the email SMTP connection (used by xref:rg.adoc#_rg_services-api_manpage-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:rg.adoc#_rg_services-api_manpage-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:rg.adoc#_rg_services-api_manpage-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:rg.adoc#_rg_services-api_manpage-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:rg.adoc#_rg_services-api_manpage-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:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`] as the underlying event bus.
+
+| `isis.services.` +
+`eventbus.allowLateRegistration` +
+| `true`, `false`, (`_false_`)
+|whether a domain service can register with the xref:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`] after any events have posted. +
+
+Since this almost certainly constitutes a bug in application code, by default this is disallowed.
+
+
+|`isis.services.` +
+`publish.objects`
+| `all`, `none` (`all`)
+|Whether changed objects should be automatically published (for objects annotated with xref:rg.adoc#_rg_annotations_manpage-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:rg.adoc#_rg_annotations_manpage-Action_publishing[`@Action(publishing=Publishing.AS_CONFIGURED)`]. +
+
+|`isis.services.` +
+`translation.po.mode`
+| `read`,`write`
+|Whether to force the `TranslationService` into either read or write mode. +
+
+See xref:ug.adoc#_ug_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:rg.adoc#_rg_annotations_manpage-PropertyLayout_labelPosition[`@PropertyLayout#labelPosition()`]
+
+|===
+
+
+
+
+[[_ug_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.
+
+
+
+[[_ug_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 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/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-datanucleus.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-datanucleus.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-datanucleus.adoc
new file mode 100644
index 0000000..9b2cb85
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-datanucleus.adoc
@@ -0,0 +1,18 @@
+[[_ug_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 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 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:ug.adoc#_ug_more-advanced_overriding-jdo-annotations[Overriding JDO Annotatons] for further discussion.
+
+
+include::_ug_runtime_configuring-datanucleus_properties.adoc[leveloffset=+1]
+include::_ug_runtime_configuring-datanucleus_persistence-xml.adoc[leveloffset=+1]
+include::_ug_runtime_configuring-datanucleus_eagerly-registering-entities.adoc[leveloffset=+1]
+include::_ug_runtime_configuring-datanucleus_disabling-persistence-by-reachability.adoc[leveloffset=+1]
+include::_ug_runtime_configuring-datanucleus_using-jndi-data-source.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-datanucleus_disabling-persistence-by-reachability.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-datanucleus_disabling-persistence-by-reachability.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-datanucleus_disabling-persistence-by-reachability.adoc
new file mode 100644
index 0000000..06a5722
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-datanucleus_disabling-persistence-by-reachability.adoc
@@ -0,0 +1,88 @@
+[[_ug_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 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 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/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-datanucleus_eagerly-registering-entities.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-datanucleus_eagerly-registering-entities.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-datanucleus_eagerly-registering-entities.adoc
new file mode 100644
index 0000000..8cc9744
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-datanucleus_eagerly-registering-entities.adoc
@@ -0,0 +1,44 @@
+[[_ug_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. Isis builds its metamodel by walking the graph of types from the services registered using `@DomainService` or explicitly registered in `isis.properties`. The JDO 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.
+
+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 `RegisterEntities` service can therefore be registered in order to do the eager registration. It searches for all `@PersistenceCapable` entities under specified package(s), and registers them all.
+
+[WARNING]
+====
+There's a chance that (from 1.6.0+) feature may be (partly?) broken; see https://issues.apache.org/jira/browse/ISIS-847[ISIS-847].
+====
+
+
+== Specify the Package Prefix(es)
+
+In the `persistor_datanucleus.properties`, specify the package prefix(es) of your application, to provide a hint for finding the `@PersistenceCapable` classes.
+
+The value of this property can be a comma-separated list (if there is more than one package or Maven module that holds persistable entities).
+
+
+== Integration Testing
+
+The `IsisConfigurationForJdoIntegTests`, recommended for use in xref:ug.adoc#_ug_testing_integ-test-support[Integration Testing] provides the `#addRegisterEntitiesPackagePrefix()` method to set up this configuration property:
+
+[source,java]
+.Integration test bootstrapping
+----
+private static class SimpleAppSystemBuilder extends IsisSystemForTest.Builder {
+ ...
+ private static IsisConfiguration testConfiguration() {
+ final IsisConfigurationForJdoIntegTests testConfiguration = new IsisConfigurationForJdoIntegTests();
+ testConfiguration.addRegisterEntitiesPackagePrefix("domainapp.dom.modules"); // <1>
+ return testConfiguration;
+ }
+}
+----
+<1> specify the package prefix(es) for integration testing.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-datanucleus_persistence-xml.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-datanucleus_persistence-xml.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-datanucleus_persistence-xml.adoc
new file mode 100644
index 0000000..cf8b777
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-datanucleus_persistence-xml.adoc
@@ -0,0 +1,10 @@
+[[_ug_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/
+
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-datanucleus_properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-datanucleus_properties.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-datanucleus_properties.adoc
new file mode 100644
index 0000000..3d8700c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-datanucleus_properties.adoc
@@ -0,0 +1,64 @@
+[[_ug_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)
+| of class names; specifies the entities early rather than allow DataNucleus to find the entities lazily. Strongly recommended (subtle issues can sometimes arise if lazy discovery is used).
+Further xref:ug.adoc#_ug_runtime_configuring-datanucleus_eagerly-registering-entities[discussion below].
+
+|`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:ug.adoc#_ug_runtime_configuring-datanucleus_disabling-persistence-by-reachability[discussion below].
+
+|===
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-datanucleus_using-jndi-data-source.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-datanucleus_using-jndi-data-source.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-datanucleus_using-jndi-data-source.adoc
new file mode 100644
index 0000000..25649c0
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_configuring-datanucleus_using-jndi-data-source.adoc
@@ -0,0 +1,75 @@
+[[_ug_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 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/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_deployment-types.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_deployment-types.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_deployment-types.adoc
new file mode 100644
index 0000000..6c9ec5a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_deployment-types.adoc
@@ -0,0 +1,12 @@
+[[_ug_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/
+
+
+
+IMPORTANT: TODO - xref:rg.adoc#_rg_annotations_manpage-Action_restrictTo[`@Action#restrictTo()`]
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_specifying-components.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_specifying-components.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_specifying-components.adoc
new file mode 100644
index 0000000..b4e45b6
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_specifying-components.adoc
@@ -0,0 +1,72 @@
+[[_ug_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/
+
+
+
+The `isis.properties` file has four configuration properties in particular that specify the major components of Isis to use.
+
+They are:
+
+.Core Configuration Properties
+[cols="2a,1,3a", options="header"]
+|===
+|Property
+|Value +
+(_default value_)
+|Implements
+
+|`isis.authentication`
+|`shiro`, `bypass`, `FQCN` +
+(`_shiro_`)
+|`o.a.i.core.runtime.authentication.` `AuthenticationManagerInstaller`
+
+|`isis.authorization`
+|`shiro`, `bypass`, `FQCN` +
+(`_shiro_`)
+|`o.a.i.core.runtime.authorization.` `AuthorizationManagerInstaller`
+
+|`isis.persistor`
+|`datanucleus`, `inmemory`, `FQCN` +
+(`_datanucleus_`)
+|`o.a.i.core.runtime.installerregistry.installerapi.` `PersistenceMechanismInstaller`
+
+|`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.
+
+
+
+|===
+
+[TIP]
+====
+The values "datanucleus", "shiro" etc are actually aliases for concrete implementations listed in 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 any of these components. This is probably feasible for the two security APIs and the `services-installer` API; but replacing the persistor (JDO/DataNucleus) is much trickier because we rely on the JDO/DN for certain functionality (such as object dirtying and lazy loading) that is not defined within this API.
+
+As for the viewers, these are specified indirectly by way of the filters and servlets in the `web.xml` file (discussed xref:ug.adoc#_ug_runtime_web-xml[below]). However, the configuration of which viewers to initialize is declared through 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/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_web-xml.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_web-xml.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_web-xml.adoc
new file mode 100644
index 0000000..5c91c24
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_runtime_web-xml.adoc
@@ -0,0 +1,35 @@
+[[_ug_runtime_web-xml]]
+= `web.xml`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+IMPORTANT: TODO
+
+
+== Init Params
+
+`<isis.viewers>`
+
+
+
+
+== Filters
+
+IMPORTANT: TODO
+
+
+
+
+== Servlets
+
+IMPORTANT: TODO
+
+
+
+
+== Running RO Viewer only
+
+IMPORTANT: TODO
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_security.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_security.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_security.adoc
new file mode 100644
index 0000000..319c1b1
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_security.adoc
@@ -0,0 +1,53 @@
+[[_ug_security]]
+= Security
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 has built-in support for authentication and authorization:
+
+* By "authentication" we mean logging into the application using some credentials, typically a username and password. Authentication also means looking up the set of roles to which a user belongs.
+
+* By "authorization" we mean permissions: granting roles to have access to features (object member) of the app.
+
+Isis has two levels of permissions. _Read_ permission means that the user can view the object member; it will be rendered in the UI. An action with only read permission will be shown disabled ("greyed out". _Write_ permission means that the object member can be changed. For actions this means that they can be invoked.
+
+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 also ships with an implementation of an LDAP-based realm; LDAP is often used to manage user/passwords and corresponding user groups. Isis in turn extends this with its `IsisLdapRealm`, which provides more flexibility for both group/role and role/permissions management.
+
+In addition, the (non-ASF) link:http://www.isisaddons.org[Isis Addons] provides the http://github.com/isisaddons/isis-module-security[Isis addons' security] module, which also provides an implementation of the Shiro `Realm` API. However, the security module also represents users, roles and permissions as domain objects, allowing them to be administered through Isis itself. Moreover, the security module can optionally delegate password management to a subsidiary (delegate) realm (usually LDAP as discussed above).
+
+In addition to Isis' Shiro-based implementation of its authentication and authorization APIs, Isis also provides a "bypass" implementation, useful for quick-n-dirty prototyping when you want to in effect disable (bypass) security completely.
+
+[NOTE]
+.What about auditing?
+====
+A further aspect of security is auditing: recording what data was modified by which user. Apache Isis does define two service APIs -- xref:rg.adoc#_rg_services-spi_manpage-CommandService[`CommandService`] and xref:rg.adoc#_rg_services-spi_manpage-AuditingService[`AuditingService`] -- that provide hooks to track which actions (commands) are invoked, and what data was modified as a result (auditing).
+
+Isis does not itself provide any in-built implementations of these APIs, but there are implementations within (non-ASF) link:http://www.isisaddons.org[Isis Addons], namely the http://github.com/isisaddons/isis-module-command[Isis addons' command] module and the http://github.com/isisaddons/isis-module-audit[Isis addons' auditing] module.
+====
+
+
+
+include::_ug_security_configuring-isis-to-use-shiro.adoc[leveloffset=+1]
+
+include::_ug_security_shiro-ini-realm.adoc[leveloffset=+1]
+
+include::_ug_security_shiro-isis-ldap-realm.adoc[leveloffset=+1]
+
+include::_ug_security_shiro-isisaddons-security-module-realm.adoc[leveloffset=+1]
+
+include::_ug_security_shiro-jdbc-realm.adoc[leveloffset=+1]
+
+include::_ug_security_shiro-isis-enhanced-wildcard-permission.adoc[leveloffset=+1]
+
+include::_ug_security_configuring-isis-to-use-bypass.adoc[leveloffset=+1]
+
+include::_ug_security_api-for-applications.adoc[leveloffset=+1]
+
+include::_ug_security_usage-by-isis-viewers.adoc[leveloffset=+1]
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_security_api-for-applications.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_security_api-for-applications.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_security_api-for-applications.adoc
new file mode 100644
index 0000000..1846f73
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_security_api-for-applications.adoc
@@ -0,0 +1,63 @@
+[[_ug_security_api-for-applications]]
+= API for 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/
+
+
+
+Generally speaking your domain objects (or more generally your application) should be agnostic of the user/roles that are interacting with them; applying security permissions is the responsibility of the framework.
+
+Still, on very rare occasion you may have a need, in which case you can either use Isis' `DomainObjectContainer` API or you can reach further down the stack and use the JEE Servlet API.
+
+
+== `DomainObjectContainer` API
+
+The xref:rg.adoc#_rg_services-api_manpage-DomainObjectContainer[`DomainObjectContainer`] service exposes the following API:
+
+[source,java]
+----
+final UserMemento user = container.getUser();
+final List<RoleMemento> roles = user.getRoles();
+for (RoleMemento role : roles) {
+ String roleName = role.getName();
+ ...
+}
+----
+
+Each role's `name` property encodes both the realm that provided the role, and the role identity itself.
+
+For example, in the simpleapp, if logging in as `dick` with the following entries for `realm1`:
+
+[source,ini]
+----
+dick = pass, user_role, analysis_role, self-install_role
+----
+
+then this corresponds to the roles "realm1:user_role", "realm1:self-install_role" and "realm1:analysis_role".
+
+If using the Wicket viewer, then note there will also be another role which is used internally (namely "org.apache.isis.viewer.wicket.roles.USER").
+
+
+
+
+
+== Servlet API
+
+On occasion you may find it necessary to reach below Isis and to the underlying servlet API. For example, the http://github.com/isisaddons/isis-module-togglz[Isis addons' togglz] module (non-ASF) has a requirement to do this in order to expose its embedded togglz web console. (
+
+[TIP]
+====
+If you do need to access the servlet API and are running within the context of Wicket viewer, the http://github.com/isisaddons/isis-module-servletapi[Isis addons' servletapi] module can provide access to the `HttpServletRequest`, `HttpServletResponse` and `ServletContext`.
+====
+
+In this situation, you can still obtain some information about the user and its roles:
+
+[source,java]
+----
+Principal principal = httpServletRequest.getPrincipal();
+String username = principal.getName();
+boolean analyst = httpServletRequest.isUserInRole("analysis_role");
+----
+
+However, it isn't possible to obtain any role permissions for the user.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_security_configuring-isis-to-use-bypass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_security_configuring-isis-to-use-bypass.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_security_configuring-isis-to-use-bypass.adoc
new file mode 100644
index 0000000..277b0fb
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_security_configuring-isis-to-use-bypass.adoc
@@ -0,0 +1,23 @@
+[[_ug_security_configuring-isis-to-use-bypass]]
+= Bypassing security
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 bypass security component consists of an implementation of both the `AuthenticationManager` and `AuthorizationManager` APIs, and are intended for prototyping use only.
+
+The authentication manager allows access with any credentials (in a sense, "bypassing" authentication), while the authorization manager provides access to all class members (in a sense, "bypassing" authorization).
+
+
+To tell Apache Isis to bypass security, just update the `WEB-INF/isis.properties` file:
+
+[source,ini]
+----
+isis.authentication=bypass
+isis.authorization=bypass
+----
+
+This installs the appropriate no-op implementations for both authentication and authorization:
+
+image::{_imagesdir}security/security-apis-impl/configure-isis-to-use-bypass.png[width="600px"]
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_security_configuring-isis-to-use-shiro.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_security_configuring-isis-to-use-shiro.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_security_configuring-isis-to-use-shiro.adoc
new file mode 100644
index 0000000..20ecac3
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_security_configuring-isis-to-use-shiro.adoc
@@ -0,0 +1,76 @@
+[[_ug_security_configuring-isis-to-use-shiro]]
+= Configuring Isis to use Shiro
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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' security mechanism is configurable, specifying an `Authenticator` and an `Authorizor` (non-public) APIs. The Shiro security mechanism is an integration wih Apache Shiro that implements both interfaces.
+
+[TIP]
+====
+The xref: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.
+====
+
+== Telling Isis to use Shiro
+
+To tell Apache Isis to use Shiro, update the `WEB-INF/isis.properties` file:
+
+[source,ini]
+----
+isis.authentication=shiro
+isis.authorization=shiro
+----
+
+This installs the appropriate implementation (the `ShiroAuthenticatorOrAuthorizor` class) that use Shiro's APIs to perform authentication and authorization:
+
+image::{_imagesdir}security/security-apis-impl/configure-isis-to-use-shiro.png[width="600px"]
+
+The figure above doesn't tell the whole story; we haven't yet seen how Shiro itself is configured to use realms. The `ShiroAuthenticatorOrAuthorizor` is in essence the glue between the Isis runtime and Shiro.
+
+== Bootstrapping Shiro
+
+The Shiro environment (in essence, thread-locals holding the security credentials) needs to be bootstrapped using the following settings in the `WEB-INF/web.xml` file:
+
+[source,xml]
+----
+<listener>
+ <listener-class>org.apache.shiro.web.env.EnvironmentLoaderListener</listener-class>
+</listener>
+<filter>
+ <filter-name>ShiroFilter</filter-name>
+ <filter-class>org.apache.shiro.web.servlet.ShiroFilter</filter-class>
+</filter>
+<filter-mapping>
+ <filter-name>ShiroFilter</filter-name>
+ <url-pattern>/*</url-pattern>
+</filter-mapping>
+----
+
+Based on this Shiro will then read `WEB-INF/shiro.ini` file to configure its Realm definitions for authentication and authorization.
+
+
+
+== `WEB-INF/shiro.ini`
+
+The `shiro.ini` file is used to specify the realm(s) that Shiro will delegate to:
+
+[source,ini]
+----
+securityManager.realms = $realmName
+----
+
+Shiro's ini file supports a "poor-man's" dependency injection (link:https://shiro.apache.org/configuration.html[their words]), and so `$realmName` in the above example is a reference to a realm defined elsewhere in `shiro.ini`. The subsequent sections describe the specifics for thevarious realm implementations available to you.
+
+
+It's also possible to configure Shiro to support multiple realms.
+
+[source,ini]
+----
+securityManager.realms = $realm1,$realm2
+----
+
+You can learn more about Shiro realms in the link:http://shiro.apache.org/realm.html[Shiro documentation].
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_security_shiro-caching.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_security_shiro-caching.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_security_shiro-caching.adoc
new file mode 100644
index 0000000..c3b37a1
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_security_shiro-caching.adoc
@@ -0,0 +1,41 @@
+[[_ug_security_shiro-caching]]
+= Caching and other Shiro 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/
+
+
+We don't want to repeat the entire link:http://shiro.apache.org/documentation.html[Shiro documentation set] here, but we should flag a number of otherof other features that are worth checking out.
+
+
+
+
+== Caching
+
+To ensure that security operations does not impede performance, Shiro supports caching. For example, this sets up a simple memory-based cache manager:
+
+[source,ini]
+----
+memoryCacheManager = org.apache.shiro.cache.MemoryConstrainedCacheManager
+securityManager.cacheManager = $memoryCacheManager
+----
+
+Other implementations can be plugged in; see the Shiro link:http://shiro.apache.org/caching.html[documentation] for further details.
+
+
+
+
+== Further Reading
+
+
+* Shiro's documentation page can be found link:http://shiro.apache.org/documentation.html[here].
+
+* community-contributed articles can be found link:http://shiro.apache.org/articles.html[here]. +
++
+These include for instance link:http://meri-stuff.blogspot.co.uk/2011/04/apache-shiro-part-2-realms-database-and.html[this interesting article] describing how to perform certificate-based authentication (ie login using Google or Facebook credentials).
+
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_security_shiro-ini-realm.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_security_shiro-ini-realm.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_security_shiro-ini-realm.adoc
new file mode 100644
index 0000000..f07b324
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_security_shiro-ini-realm.adoc
@@ -0,0 +1,133 @@
+[[_ug_security_shiro-ini-realm]]
+= Shiro Ini Realm
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+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.
+
+The diagram below shows the Isis and components involved:
+
+image::{_imagesdir}security/security-apis-impl/configure-shiro-to-use-ini-realm.png[width="600px"]
+
+The realm is responsible for validating the user credentials, and then creates a Shiro link:http://shiro.apache.org/static/latest/apidocs/org/apache/shiro/subject/Subject.html[`Subject`] which represents the user (for the current request). Isis `Authenticator` component then interacts with the `Subject` in order to check permissions.
+
+
+
+
+== Shiro Configuration
+
+To use the built-in `IniRealm`, we add the following to `WEB-INF/shiro.ini`:
+
+[source,ini]
+----
+securityManager.realms = $iniRealm
+----
+
+(Unlike other realms) there is no need to "define" `$iniRealm`; it is automatically available to us.
+
+Specifying `$iniRealm` means that the usernames/passwords, roles and permissions are read from the `shiro.ini` file itself. Specifically:
+
+* the users/passwords and their roles from the `[users]` sections;
+* the roles are mapped to permissions in the `[roles]` section.
+
+The format of these is described below.
+
+=== `[users]` section
+
+This section lists users, passwords and their roles.
+
+For example:
+
+[source,ini]
+----
+sven = pass, admin_role
+dick = pass, user_role, analysis_role, self-install_role
+bob = pass, user_role, self-install_role
+----
+The first value is the password (eg "pass", the remaining values are the role(s).
+
+
+=== `[roles]` section
+
+This section lists roles and their corresponding permissions.
+
+For example:
+
+[source,ini]
+----
+user_role = *:ToDoItems:*:*,\
+ *:ToDoItem:*:*,\
+ *:ToDoAppDashboard:*:*
+analysis_role = *:ToDoItemAnalysis:*:*,\
+ *:ToDoItemsByCategoryViewModel:*:*,\
+ *:ToDoItemsByDateRangeViewModel:*:*
+self-install_role = *:ToDoItemsFixturesService:install:*
+admin_role = *
+----
+
+The value is a comma-separated list of permissions for the role. The format is:
+
+[source,ini]
+----
+packageName:className:memberName:r,w
+----
+
+where:
+
+* `memberName` is the property, collection or action name.
+* `r` indicates that the member is visible
+* `w` indicates that the member is usable (editable or invokable)
+
+and where each of the parts of the permission string can be wildcarded using `*`.
+
+Because these are wildcards, a '*' can be used at any level. Additionally, missing levels assume wildcards.
+
+Thus:
+
+[source,ini]
+----
+com.mycompany.myapp:Customer:firstName:r,w # view or edit customer's firstName
+com.mycompany.myapp:Customer:lastName:r # view customer's lastName only
+com.mycompany.myapp:Customer:placeOrder:* # view and invoke placeOrder action
+com.mycompany.myapp:Customer:placeOrder # ditto
+com.mycompany.myapp:Customer:*:r # view all customer class members
+com.mycompany.myapp:*:*:r # view-only access for all classes in myapp package
+com.mycompany.myapp:*:*:* # view/edit for all classes in myapp package
+com.mycompany.myapp:*:* # ditto
+com.mycompany.myapp:* # ditto
+com.mycompany.myapp # ditto
+* # view/edit access to everything
+----
+
+[TIP]
+====
+The format of the permissions string is configurable in Shiro, and Isis uses this to provide an extended wildcard format, described xref:ug.adoc#_ug_security_shiro-isis-enhanced-wildcard-permission[here].
+====
+
+
+
+
+== Externalized IniRealm
+
+There's no requirement for all users/roles to be defined in the `shiro.ini` file. Instead, a realm can be defined that loads its users/roles from some other resource.
+
+For example:
+
+[source,ini]
+----
+$realm1=org.apache.shiro.realm.text.IniRealm # <1>
+realm1.resourcePath=classpath:webapp/realm1.ini # <2>
+----
+<1> happens to (coincidentally) be the link:http://shiro.apache.org/static/latest/apidocs/org/apache/shiro/realm/text/IniRealm.html[same implementation] as Shiro's built-in $iniRealm
+<2> in this case load the users/roles from the `src/main/resources/webapp/realm1.ini` file.
+
+Note that a URL could be provided as the `resourcePath`, so a centralized config file could be used. Even so, the
+
+[NOTE]
+====
+If configured this way then the `[users]` and `[roles]` sections of `shiro.ini` become unused. Instead, the corresponding sections from for `realm1.ini` are used instead.
+====
[38/45] isis git commit: ISIS-1133: breaking out reference guide and
devenv guide;
moving appendices' release notes and migration notes to other docs;
improving the documentation page.
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..8c14436
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_value-types.adoc
@@ -0,0 +1,119 @@
+[[_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/
+
+IMPORTANT: 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,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/9c5dafab/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
new file mode 100644
index 0000000..3ac61f0
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_value-types_manpage-Blob.adoc
@@ -0,0 +1,8 @@
+[[_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/
+
+
+IMPORTANT: TODO
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..3595fbd
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_value-types_manpage-Clob.adoc
@@ -0,0 +1,8 @@
+[[_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/
+
+
+IMPORTANT: TODO
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..45b581b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_value-types_manpage-Color.adoc
@@ -0,0 +1,9 @@
+[[_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/
+
+
+IMPORTANT: TODO
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..548bba2
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_value-types_manpage-Money.adoc
@@ -0,0 +1,8 @@
+[[_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/
+
+
+IMPORTANT: TODO
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..f7e49e2
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_value-types_manpage-Password.adoc
@@ -0,0 +1,8 @@
+[[_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/
+
+
+IMPORTANT: TODO
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..91f146c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_methods.adoc
@@ -0,0 +1,17 @@
+[[_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:rg.adoc#_rg_annotations[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/9c5dafab/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
new file mode 100644
index 0000000..4bf912e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle.adoc
@@ -0,0 +1,99 @@
+[[_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 Isis rather than JDO. In the future we may deprecate them because they duplicate functionality already available in JDO.
+
+You may therefore want to consider using the JDO API directly; see xref:rg.adoc#_rg_methods_lifecycle_jdo-api[here] for further discussion.
+====
+
+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:rg.adoc#_rg_services-api_manpage-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]
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..2bf7e9c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle_jdo-api.adoc
@@ -0,0 +1,50 @@
+[[_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 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 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:rg.adoc#_rg_services-api_manpage-IsisJdoSupport[`IsisJdoSupport`] domain service.
+
+For example:
+
+[source,java]
+----
+@DomainService(nature=NatureOfService.DOMAIN)
+public class ObjectChangedListenerService
+ implements javax.jdo.listener.StoreLifecycleListener { // <1>
+ @Programmatic
+ @PostConstruct
+ public void init() {
+ getPmFactory().addInstanceLifecycleListener(this);
+ }
+ @Programmatic
+ @PreDestroy
+ public void tidyUp() {
+ getPmFactory().removeInstanceLifecycleListener(this);
+ }
+ private PersistenceManagerFactory getPmFactory() {
+ return jdoSupport.getPersistenceManager()
+ .getPersistenceManagerFactory(); // <2>
+ }
+ @Programmatic
+ public void preStore (InstanceLifecycleEvent event) { ... }
+ @Programmatic
+ public void postStore (InstanceLifecycleEvent event) { ... }
+ @Inject
+ IsisJdoSupport jdoSupport;
+}
+----
+<1> implement whichever callback lifecycle listeners are of interest
+<2> register on the factory so set up for every subsequent session.
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..89c4152
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle_manpage-created.adoc
@@ -0,0 +1,11 @@
+[[_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:rg.adoc#_rg_services-api_manpage-DomainObjectContainer[`newTransientInstance()`]
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..9a5fa76
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle_manpage-loaded.adoc
@@ -0,0 +1,10 @@
+[[_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.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..5f1e683
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle_manpage-persisted.adoc
@@ -0,0 +1,12 @@
+[[_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()`].
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..96afbe8
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle_manpage-persisting.adoc
@@ -0,0 +1,12 @@
+[[_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()`].
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..6a85b5e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle_manpage-removed.adoc
@@ -0,0 +1,12 @@
+[[_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()`].
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..b45bc94
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle_manpage-removing.adoc
@@ -0,0 +1,12 @@
+[[_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()`].
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..b683b5f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle_manpage-updated.adoc
@@ -0,0 +1,14 @@
+[[_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()`].
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..b92ba8b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_lifecycle_manpage-updating.adoc
@@ -0,0 +1,10 @@
+[[_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()`].
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..7084c1f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes.adoc
@@ -0,0 +1,219 @@
+[[_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:ug.adoc#_ug_wicket-viewer[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:rg.adoc#_rg_annotations_manpage-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:ug.adoc#_ug_wicket-viewer[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:ug.adoc#_ug_wicket-viewer[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:ug.adoc#_ug_wicket-viewer[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/9c5dafab/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
new file mode 100644
index 0000000..a949ac8
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-addTo.adoc
@@ -0,0 +1,37 @@
+[[_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:ug.adoc#_ug_wicket-viewer[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/9c5dafab/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
new file mode 100644
index 0000000..43b47a7
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-autoComplete.adoc
@@ -0,0 +1,91 @@
+[[_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 Collection<T> autoCompleteNXxx(String search) { ... }
+----
+
+
+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:rg.adoc#_rg_annotations_manpage-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 Collection<T> autoCompleteXxx(String search) { ... }
+----
+
+
+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:rg.adoc#_rg_annotations_manpage-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/9c5dafab/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
new file mode 100644
index 0000000..c333132
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-choices.adoc
@@ -0,0 +1,143 @@
+[[_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/9c5dafab/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
new file mode 100644
index 0000000..1c8646a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-clear.adoc
@@ -0,0 +1,32 @@
+[[_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/9c5dafab/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
new file mode 100644
index 0000000..df43387
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-default.adoc
@@ -0,0 +1,129 @@
+[[_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:rg.adoc#_rg_services-api_manpage-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:rg.adoc#_rg_services-api_manpage-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/9c5dafab/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
new file mode 100644
index 0000000..14803c5
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-disable.adoc
@@ -0,0 +1,93 @@
+[[_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:ug.adoc#_ug_wicket-viewer[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, Isis' xref:ug.adoc#_ug_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/9c5dafab/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
new file mode 100644
index 0000000..4b00cf4
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-get.adoc
@@ -0,0 +1,19 @@
+[[_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 Isis prefixes) are interpreted as actions.
+
+Any methods "left over" that _do_ use one of the Isis prefixes, are interpreted to be orphaned. 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/9c5dafab/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
new file mode 100644
index 0000000..93aaaf6
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-hide.adoc
@@ -0,0 +1,82 @@
+[[_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/9c5dafab/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
new file mode 100644
index 0000000..87160a0
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-modify.adoc
@@ -0,0 +1,37 @@
+[[_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/9c5dafab/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
new file mode 100644
index 0000000..cd0a985
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-removeFrom.adoc
@@ -0,0 +1,37 @@
+[[_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:ug.adoc#_ug_wicket-viewer[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/9c5dafab/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
new file mode 100644
index 0000000..2e39781
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-set.adoc
@@ -0,0 +1,13 @@
+[[_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/9c5dafab/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
new file mode 100644
index 0000000..cbf5086
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-validate.adoc
@@ -0,0 +1,113 @@
+[[_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, Isis' xref:ug.adoc#_ug_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/9c5dafab/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
new file mode 100644
index 0000000..a9183c2
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-validateAddTo.adoc
@@ -0,0 +1,45 @@
+[[_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:ug.adoc#_ug_wicket-viewer[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). Isis' xref:ug.adoc#_ug_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/9c5dafab/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
new file mode 100644
index 0000000..254de8d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_prefixes_manpage-validateRemoveFrom.adoc
@@ -0,0 +1,45 @@
+[[_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:ug.adoc#_ug_wicket-viewer[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). Isis' xref:ug.adoc#_ug_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...()`]`
+
[10/45] isis git commit: ISIS-1133: breaking out reference guide and
devenv guide;
moving appendices' release notes and migration notes to other docs;
improving the documentation page.
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-BackgroundService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-BackgroundService.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-BackgroundService.adoc
deleted file mode 100644
index 0dab320..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-BackgroundService.adoc
+++ /dev/null
@@ -1,123 +0,0 @@
-[[_ug_reference-services-api_manpage-BackgroundService]]
-= `BackgroundService`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `BackgroundService`, and the companion xref:_ug_reference-services-spi_manpage-BackgroundCommandService[`BackgroundCommandService`] SPI service (used by Isis itself), enable action invocations to be persisted such that they may be invoked in the background.
-
-The `BackgroundService` is responsible for capturing a memento representing the action invocation in a typesafe way, and persisting it rather than executing it directly.
-
-The default `BackgroundServiceDefault` implementation (provided by isis-core) works by using a proxy wrapper around the target so that it can capture the action to invoke and its arguments using (a private copy of) xref:_ug_reference-services-api_manpage-MementoService[`MementoService`]. The persistence delegates the persistence of the memento to an appropriate implementation of the companion `BackgroundCommandService`. One such implementation of `BackgroundCommandService` is provided by (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module.
-
-The persisting of commands is only half the story; there needs to be a separate process to read the commands and execute them. The `BackgroundCommandExecution` abstract class (discussed xref:_ug_reference-services-api_manpage-BackgroundService_BackgroundCommandExecution[below]) provides infrastructure to do this; the concrete
-implementation of this class depends on the configured `BackgroundCommandService` (in order to query for the persisted (background) ``Command``s.
-
-
-
-== API & Implementation
-
-Returns a proxy around the object which is then used to obtain the signature of the action to be invoked in the background.
-
-[source,java]
-----
-public interface BackgroundService {
- @Programmatic
- <T> T execute(final T object);
-}
-----
-
-The default implementation is provided by core (`o.a.i.core.runtime.services.background.BackgroundServiceDefault`).
-
-
-
-== Usage
-
-Using the service is very straight-forward; wrap the target domain object using `BackgroundService#execute(...)` and invoke the method on the object returned by that method.
-
-For example:
-
-[source,java]
-----
-public void submitCustomerInvoices() {
- for(Customer customer: customerRepository.findCustomersToInvoice()) {
- backgroundService.execute(customer).submitInvoice();
- }
- container.informUser("Calculating...");
-}
-----
-
-This will create a bunch of background commands executing the `submitInvoice()` action for each of the customers returned from the customer repository.
-
-The action method invoked must be part of the Isis metamodel, which is to say it must be public, accept only scalar arguments, and must not be annotated with xref:_ug_reference-annotations_manpage-Programmatic[`@Programmatic`] or `@Ignore`. However, it may be annotated with xref:_ug_reference-annotations_manpage-Action_hidden[`@Action#hidden()`] or xref:_ug_reference-annotations_manpage-ActionLayout_hidden[`@ActionLayout#hidden()`] and it will still be invoked.
-
-In fact, when invoked by the background service, no business rules (hidden, disabled, validation) are enforced; the action method must take responsibility for performing appropriate validation and error checking.
-
-[TIP]
-====
-If you want to check business rules, you can use xref:_ug_reference-annotations_manpage-WrapperFactory[`@WrapperFactory#wrapNoExecute(...)`].
-====
-
-
-
-== End-user experience
-
-For the end-user, executing an action that delegates work off to the `BackgroundService` raises the problem of how does the user know the work is complete?
-
-One option is for the background jobs to take responsibility to notify the user themselves. In the above example, this would be the `submitInvoice()` method called upon each customer. One could imagine more complex designs where only the final command executed notifies the user.
-
-However, an alternative is to rely on the fact that the `BackgroundService` will automatically hint that the `Command` representing the original interaction (to `submitCustomerInvoices()` in the example above) should be persisted. This will be available if the related xref:_ug_reference-services-api_manpage-CommandContext[`CommandContext`] and xref:_ug_reference-services-spi_manpage-CommandService[`CommandService`] domain services are configured, and the `CommandService` supports persistent commands. Note that (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module does indeed provide such an implementation of `CommandService` (as well as of the required `BackgroundCommandService`).
-
-Thus, the original action can run a query to obtain it corresponding `Command`, and return this to the user. The upshot is that the child ``Command``s created by the `BackgroundService` will then be associated with `Command` for the original action.
-
-We could if we wanted write the above example as follows:
-
-[source,java]
-----
-public Command submitCustomerInvoices() {
- for(Customer customer: customerRepository.findCustomersToInvoice()) {
- backgroundService.execute(customer).submitInvoice();
- }
- return commandContext.getCommand();
-}
-@Inject
-CommandContext commandContext; // <1>
-----
-<1> the injected xref:_ug_reference-services-api_manpage-CommandContext[`CommandContext`] domain service.
-
-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:
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then Isis' core implementation of `BackgroundService` is automatically registered (it is annotated with `@DomainService`) so no further configuration is required.
-
-
-
-== Related Services
-
-This service is closely related to the xref:_ug_reference-services-api_manpage-CommandContext[`CommandContext`] and also that service's supporting xref:_ug_reference-services-spi_manpage-CommandService[`CommandService`] service.
-
-The `CommandContext` service is responsible for providing a parent `Command` with which the background ``Command``s can then be associated as children, while the `CommandService` is responsible for persisting those parent `Command`s. The latter is analogous to the way in which the `BackgroundCommandService` persists the child background `Command`s.
-
-The implementations of `CommandService` and `BackgroundCommandService` go together; typically both parent `Command`s and child background `Command`s will be persisted in the same way. The (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module provides implementations of both (see xref:_ug_reference-services-spi_manpage-CommandService[`CommandService`] and xref:_ug_reference-services-spi_manpage-BackgroundCommandService[`BackgroundCommandService`]).
-
-
-include::_ug_reference-services-api_manpage-BackgroundService_BackgroundCommandExecution.adoc[leveloffset=+1]
-include::_ug_reference-services-api_manpage-BackgroundService_Quartz.adoc[leveloffset=+1]
-
-
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-BackgroundService_BackgroundCommandExecution.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-BackgroundService_BackgroundCommandExecution.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-BackgroundService_BackgroundCommandExecution.adoc
deleted file mode 100644
index a493e1d..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-BackgroundService_BackgroundCommandExecution.adoc
+++ /dev/null
@@ -1,25 +0,0 @@
-[[_ug_reference-services-api_manpage-BackgroundService_BackgroundCommandExecution]]
-= `BackgroundCommandExecution` abstract class
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `BackgroundCommandExecution` (in isis-core) is an abstract template class provided by isis-core that defines an abstract hook method to obtain background `Command`s to be executed:
-
-[source,java]
-----
-public abstract class BackgroundCommandExecution
- extends AbstractIsisSessionTemplate {
- ...
- protected abstract List<? extends Command> findBackgroundCommandsToExecute();
- ...
-}
-----
-
-The developer is required to implement this hook method in a subclass.
-
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-BackgroundService_Quartz.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-BackgroundService_Quartz.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-BackgroundService_Quartz.adoc
deleted file mode 100644
index 227f8c2..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-BackgroundService_Quartz.adoc
+++ /dev/null
@@ -1,162 +0,0 @@
-[[_ug_reference-services-api_manpage-BackgroundService_Quartz]]
-= Quartz Scheduler Configuration
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 last part of the puzzle is to actually run the (appropriate implementation of) `BackgroundCommandExecution). This could be run in a batch job overnight, or run continually by, say, the http://quartz-scheduler.org[Quartz] scheduler or by http://camel.apache.org]Apache Camel]. This section looks at configuring Quartz.
-
-If using (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module, then note that this already provides a suitable concrete implementation, namely `org.isisaddons.module.command.dom.BackgroundCommandExecutionFromBackgroundCommandServiceJdo`. We therefore just need to schedule this to run as a Quartz job.
-
-
-First, we need to define a Quartz job, for example:
-
-[source,java]
-----
-import org.isisaddons.module.command.dom.BackgroundCommandExecutionFromBackgroundCommandServiceJdo;
-public class BackgroundCommandExecutionQuartzJob extends AbstractIsisQuartzJob {
- public BackgroundCommandExecutionQuartzJob() {
- super(new BackgroundCommandExecutionFromBackgroundCommandServiceJdo());
- }
-}
-----
-
-where `AbstractIsisQuartzJob` is in turn the following boilerplate:
-
-[source,java]
-----
-package domainapp.webapp.quartz;
-import org.quartz.Job;
-import org.quartz.JobExecutionContext;
-import org.quartz.JobExecutionException;
-...
-public class AbstractIsisQuartzJob implements Job {
- public static enum ConcurrentInstancesPolicy {
- SINGLE_INSTANCE_ONLY,
- MULTIPLE_INSTANCES
- }
-
- private final AbstractIsisSessionTemplate isisRunnable;
- private final ConcurrentInstancesPolicy concurrentInstancesPolicy;
- private boolean executing;
-
- public AbstractIsisQuartzJob(AbstractIsisSessionTemplate isisRunnable) {
- this(isisRunnable, ConcurrentInstancesPolicy.SINGLE_INSTANCE_ONLY);
- }
- public AbstractIsisQuartzJob(
- AbstractIsisSessionTemplate isisRunnable,
- ConcurrentInstancesPolicy concurrentInstancesPolicy) {
- this.isisRunnable = isisRunnable;
- this.concurrentInstancesPolicy = concurrentInstancesPolicy;
- }
-
- public void execute(final JobExecutionContext context)
- throws JobExecutionException {
- final AuthenticationSession authSession = newAuthSession(context);
- try {
- if(concurrentInstancesPolicy == ConcurrentInstancesPolicy.SINGLE_INSTANCE_ONLY &&
- executing) {
- return;
- }
- executing = true;
-
- isisRunnable.execute(authSession, context);
- } finally {
- executing = false;
- }
- }
-
- AuthenticationSession newAuthSession(JobExecutionContext context) {
- String user = getKey(context, SchedulerConstants.USER_KEY);
- String rolesStr = getKey(context, SchedulerConstants.ROLES_KEY);
- String[] roles = Iterables.toArray(
- Splitter.on(",").split(rolesStr), String.class);
- return new SimpleSession(user, roles);
- }
-
- String getKey(JobExecutionContext context, String key) {
- return context.getMergedJobDataMap().getString(key);
- }
-}
-----
-
-
-This job can then be configured to run using Quartz' `quartz-config.xml` file:
-
-[source,xml]
-----
-<?xml version="1.0" encoding="UTF-8"?>
-<job-scheduling-data
- xmlns="http://www.quartz-scheduler.org/xml/JobSchedulingData"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://www.quartz-scheduler.org/xml/JobSchedulingData
-http://www.quartz-scheduler.org/xml/job_scheduling_data_1_8.xsd"
- version="1.8">
- <schedule>
- <job>
- <name>BackgroundCommandExecutionJob</name>
- <group>Isis</group>
- <description>
- Poll and execute any background actions persisted by the BackgroundActionServiceJdo domain service
- </description>
- <job-class>domainapp.webapp.quartz.BackgroundCommandExecutionQuartzJob</job-class>
- <job-data-map>
- <entry>
- <key>webapp.scheduler.user</key>
- <value>scheduler_user</value>
- </entry>
- <entry>
- <key>webapp.scheduler.roles</key>
- <value>admin_role</value>
- </entry>
- </job-data-map>
- </job>
- <trigger>
- <cron>
- <name>BackgroundCommandExecutionJobEveryTenSeconds</name>
- <job-name>BackgroundCommandExecutionJob</job-name>
- <job-group>Isis</job-group>
- <cron-expression>0/10 * * * * ?</cron-expression>
- </cron>
- </trigger>
- </schedule>
-</job-scheduling-data>
-----
-
-The remaining two pieces of configuration are the `quartz.properties` file:
-
-[source,ini]
-----
-org.quartz.scheduler.instanceName = SchedulerQuartzConfigXml
-org.quartz.threadPool.threadCount = 1
-org.quartz.jobStore.class = org.quartz.simpl.RAMJobStore
-org.quartz.plugin.jobInitializer.class =org.quartz.plugins.xml.XMLSchedulingDataProcessorPlugin
-org.quartz.plugin.jobInitializer.fileNames = webapp/scheduler/quartz-config.xml
-org.quartz.plugin.jobInitializer.failOnFileNotFound = true
-----
-
-and the entry in `web.xml` for the Quartz servlet:
-
-[source,xml]
-----
-<servlet>
- <servlet-name>QuartzInitializer</servlet-name>
- <servlet-class>org.quartz.ee.servlet.QuartzInitializerServlet</servlet-class>
- <init-param>
- <param-name>config-file</param-name>
- <param-value>webapp/scheduler/quartz.properties</param-value>
- </init-param>
- <init-param>
- <param-name>shutdown-on-unload</param-name>
- <param-value>true</param-value>
- </init-param>
- <init-param>
- <param-name>start-scheduler-on-load</param-name>
- <param-value>true</param-value>
- </init-param>
- <load-on-startup>1</load-on-startup>
- </servlet>
-----
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-BookmarkService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-BookmarkService.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-BookmarkService.adoc
deleted file mode 100644
index 4866893..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-BookmarkService.adoc
+++ /dev/null
@@ -1,117 +0,0 @@
-[[_ug_reference-services-api_manpage-BookmarkService]]
-= `BookmarkService`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `BookmarkService` provides the ability to obtain a serializable `o.a.i.applib.bookmarks.Bookmark` for any (persisted) domain object, and to lookup domain objects given a `Bookmark`. This can then in turn be converted to and from a string.
-
-For example, a `Customer` object with:
-
-* an object type of "custmgmt.Customer" (as per xref:_ug_reference-annotations_manpage-DomainObject_objectType[`DomainObject#objectType()`] or equivalent) , and
-* an id=123
-
-could correspond to a `Bookmark` with a string representation of `custmgmt.Customer|123`.
-
-[NOTE]
-====
-A `Bookmark` is little more than an API equivalent of Isis' internal `Oid` (object identifier). Nevertheless, the ability to uniquely address _any_ domain object within an Isis system -- to in effect provide a URN -- is immensely useful.
-
-For example, a `Bookmark` could be converted into a barcode, and then this used for automated scanning of correspondence from a customer.
-====
-
-``Bookmark``s are used by several other domain services as a means of storing areference to an arbitrary object (a polymorphic relationship). For example, the (non-ASF) http://github.com/isisaddons/isis-module-auditing[Isis addons' auditing] module's implementation of xref:_ug_reference-services-spi_manpage-AuditingService[`AuditingService`] uses bookmarks to capture the object that is being audited.
-
-[TIP]
-====
-One downside of using ``Bookmark``s is that there is no way for the JDO/DataNucleus objectstore to enforce any kind of referental integrity. However, the (non-ASF) http://github.com/isisaddons/isis-module-poly[Isis addons' poly] module describes and supports a design pattern to address this requirement.
-====
-
-
-
-
-== API & Implementation
-
-The API defined by `BookmarkService` is:
-
-[source,java]
-----
-public interface BookmarkService {
- @Programmatic
- Object lookup(BookmarkHolder bookmarkHolder);
- @Programmatic
- Object lookup(Bookmark bookmark);
- @Programmatic
- <T> T lookup(Bookmark bookmark, Class<T> cls); // <1>
- @Programmatic
- Bookmark bookmarkFor(Object domainObject);
- @Programmatic
- Bookmark bookmarkFor(Class<?> cls, String identifier);
-}
-----
-<1> same as `lookup(Bookmark bookmark)`, but downcasts to the specified type.
-
-
-The core framework provides a default implementation of this API, namely `o.a.i.core.metamodel.services.bookmarks.BookmarkServiceDefault`
-
-
-== `BookmarkHolder`
-
-The `BookmarkHolder` interface is intended to be implemented by domain objects that use a `Bookmark` to reference a (single) domain object; an example might be a class such as the audit entry, mentioned above. The interface is simply:
-
-
-[source,java]
-----
-public interface BookmarkHolder {
- @Programmatic
- Bookmark bookmark();
-}
-
-----
-
-There are two services that will contribute to this interface:
-
-* `BookmarkHolderActionContributions` will provide a `lookup(...)` action
-* `BookmarkHolderAssociationContributions` provides an `object` property.
-
-Either of these can be suppressed, if required, using a vetoing subscriber. For example, to suppress the `object` property (so that only the `lookup(...)` action is ever shown for implementations of `BookmarkHolder`, define:
-
-[source,java]
-----
-@DomainObject
-public class AlwaysHideBookmarkHolderAssociationsObjectProperty {
- @Subscribe
- public void on(BookmarkHolderAssociationContributions.ObjectDomainEvent ev) {
- ev.hide();
- }
-}
-----
-
-A more sophisticated implementation could look inside the passed `ev` argument and selectively hide or not based on the contributee.
-
-
-
-
-== Usage by other services
-
-Bookmarks are used by the (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module's implementation of xref:_ug_reference-services-api_manpage-BackgroundCommandService[`BackgroundCommandService`], which uses a bookmark to capture the target object on which an action will be invoked subsequently.
-
-Bookmarks are also used by the (non-ASF) http://github.com/isisaddons/isis-module-publishing[Isis addons' publishing] module's implementation of xref:_ug_reference-services-spi_manpage-PublishingService[`PublishingService`], and by the (non-ASF) http://github.com/isisaddons/isis-module-auditing[Isis addons' auditing] module's implementation of xref:_ug_reference-services-spi_manpage-AuditingService[`AuditingService`].
-
-
-
-
-== Registering the Service
-
-Assuming that the `configuration-and-annotation` services installer is configured:
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then 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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-BulkInteractionContext.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-BulkInteractionContext.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-BulkInteractionContext.adoc
deleted file mode 100644
index 56ed2e4..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-BulkInteractionContext.adoc
+++ /dev/null
@@ -1,9 +0,0 @@
-[[_ug_reference-services-api_manpage-BulkInteractionContext]]
-= `BulkInteractionContext`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 service is deprecated, replaced by xref:_ug_reference-services-api_manpage-ActionInvocationContext[`ActionInvocationContext`].
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-ClockService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-ClockService.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-ClockService.adoc
deleted file mode 100644
index 4cf595e..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-ClockService.adoc
+++ /dev/null
@@ -1,104 +0,0 @@
-[[_ug_reference-services-api_manpage-ClockService]]
-= `ClockService`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 deal with dates and times in one way or another. For example, if an `Order` is placed, then the `Customer` may have 30 days to pay the `Invoice`, otherwise a penalty may be levied.
-
-However, such date/time related functionality can quickly complicate automated testing: "today+30" will be a different value every time the test is run.
-
-Even disregarding testing, there may be a requirement to ensure that date/times are obtained from an NNTP server (rather than the system PC). While instantiating a `java.util.Date` to current the current time is painless enough, we would not want complex technical logic for querying an NNTP server spread around domain logic code.
-
-Therefore it's common to provide a domain service whose responsibility is to provide the current time. This service can be injected into any domain object (and can be mocked out for unit testing). Isis provides such a facade through the `ClockService`.
-
-
-
-== API & Implementation
-
-The API defined by `ClockService` is:
-
-[source,java]
-----
-@DomainService(nature = NatureOfService.DOMAIN)
-public class ClockService {
- @Programmatic
- public LocalDate now() { ... }
- @Programmatic
- public LocalDateTime nowAsLocalDateTime() { ... }
- @Programmatic
- public DateTime nowAsDateTime() { ... }
- @Programmatic
- public Timestamp nowAsJavaSqlTimestamp() { ... }
- @Programmatic
- public long nowAsMillis() { ... }
-}
-----
-
-This class (`o.a.i.applib.services.clock.ClockService`) is also the default implementation. The time provided by this default implementation is based on the system clock.
-
-
-
-
-== Testing Support
-
-The default `ClockService` implementation in fact simply delegates to another class defined in the API, namely the `o.a.i.applib.clock.Clock`, an abstract singleton class. It is not recommended that your code use the `Clock` directly, but you should understand how this all works:
-
-* 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:_ug_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:_ug_runtime_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.
-
-
-
-=== Alternative Implementations
-
-Suppose you want (as discussed in the introduction to this service) to use a clock that delegates to NNTP. For most domain services this would amount to implementing the appropriate service and registering in `isis.properties` so that it is used in preference to any implementations provided by default by the framework.
-
-In the case of the `ClockService`, though, this approach (unfortunately) will not work, because parts of Isis (still) delegate to the `Clock` singleton rather than using the `ClockService` domain service.
-
-The workaround, therefore, is to implement your functionality as a subclass of `Clock`. You can write a domain service that will ensure that your implementation is used ahead of any implementations provided by the framework.
-
-For example:
-
-[source,java]
-----
-@DomainService(nature=NatureOfService.DOMAIN)
-public class NntpClockServiceInitializer {
- @Programmatic
- @PostConstruct
- public void postConstruct(Map<String,String> properties) {
- new NntpClock(properties); // <1>
- }
- private static class NntpClock extends Clock {
- NntpClock(Map<String,String> properties) { ... } // <2>
- protected long time() { ... } // <3>
- ... NNTP stuff here ...
- }
- }
-}
-----
-<1> enough to simply instantiate the `Clock`; it will register itself as singleton
-<2> connect to NNTP service using configuration properties from `isis.properties`
-<3> call to NNTP service here
-
-
-
-
-== Registering the Service
-
-Assuming that the `configuration-and-annotation` services installer is configured:
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then Isis' core implementation of `ClockService` is automatically registered (it is annotated with `@DomainService`) so no further configuration is required.
-
-If you want to use a different implementation of `Clock`, eg delegating to NNTP, then do _not_ register directly, but instead subclass from `o.a.i.applib.clock.Clock` singleton (as described in the section above).
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-CommandContext.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-CommandContext.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-CommandContext.adoc
deleted file mode 100644
index f462f96..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-CommandContext.adoc
+++ /dev/null
@@ -1,217 +0,0 @@
-[[_ug_reference-services-api_manpage-CommandContext]]
-= `CommandContext`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `CommandContext` service is a xref:_ug_reference-annotations_manpage-RequestScoped[request-scoped] service that reifies the invocation of an action on a domain object into an object itself. This reified information is encapsulated within the `Command` object.
-
-By default, the `Command` is held in-memory only; once the action invocation has completed, the `Command` object is gone. The optional
- supporting xref:_ug_reference-services-spi_manpage-CommandService[`CommandService`] enables the implementation of `Command` to be pluggable. With an appropriate implementation (eg as provided by the (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module's xref:_ug_reference-services-spi_manpage-CommandService[`CommandService`]) the `Command` may then be persisted.
-
-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:_ug_reference-services-api_manpage-BackgroundService[`BackgroundService`]
-* if xref:_ug_reference-services-spi_manpage-AuditingService[`AuditingService`] 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) through the unique `transactionId` GUID
-* if xref:_ug_reference-services-spi_manpage-PublishingService[`PublishingService`] is configured, they provide better traceability as the `Command` is also correlated with any published events, again through the unique `transactionId` GUID
-
-Assuming that the `CommandService` supports persistent `Command`s, the associated xref:_ug_reference-annotations_manpage-Action_command[`@Action#command()`] annotation 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.
-
-
-
-[[_ug_reference-services-api_manpage-CommandContext_screencast]]
-== Screencast
-
-
-The screencast provides a run-through of the command (profiling) service, auditing service, publishing service. It also shows how commands can be run in the background either explicitly by scheduling through the background service or implicitly by way of a framework annotation.
-
-video::tqXUZkPB3EI[youtube,width="640px",height="360px"]
-
-[NOTE]
-====
-Note that this screencast shows an earlier version of the xref:_ug_wicket-viewer[Wicket viewer] UI (specifically, pre 1.8.0).
-====
-
-
-
-
-== API & Implementation
-
-The `CommandContext` request-scoped service defines the following very simple API:
-
-[source,java]
-----
-@RequestScoped
-public class CommandContext {
- @Programmatic
- public Command getCommand() { ... }
-}
-----
-
-This class (`o.a.i.applib.services.CommandContext`) is also the default implementation. Under normal circumstances there shouldn't be any need to replace this implementation with another.
-
-The `Command` type referenced above is in fact an interface, defined as:
-
-[source,java]
-----
-public interface Command extends HasTransactionId {
-
- public abstract String getUser(); // <1>
- public abstract Timestamp getTimestamp(); // <2>
-
- public abstract Bookmark getTarget(); // <3>
- public abstract String getMemberIdentifier(); // <4>
- public abstract String getTargetClass(); // <5>
- public abstract String getTargetAction(); // <6>
- public String getArguments(); // <7>
- public String getMemento(); // <8>
-
- public ExecuteIn getExecuteIn(); // <9>
- public Executor getExecutor(); // <10>
- public Persistence getPersistence(); // <11>
- public boolean isPersistHint(); // <12>
-
- public abstract Timestamp getStartedAt(); // <13>
- public abstract Timestamp getCompletedAt(); // <14>
- public Command getParent(); // <15>
-
- public Bookmark getResult(); // <16>
- public String getException(); // <17>
-}
-----
-<1> `getUser()` - is the user that initiated the action.
-<2> `getTimestamp()` - the date/time at which this action was created.
-<3> `getTarget()` - bookmark of the target object (entity or service) on which this action was performed
-<4> `getMemberIdentifier()` - holds a string representation of the invoked action
-<5> `getTargetClass()` - a human-friendly description of the class of the target object
-<6> `getTargetAction()` - a human-friendly name of the action invoked on the target object
-<7> `getArguments()` - a human-friendly description of the arguments with which the action was invoked
-<8> `getMemento()` - a formal (XML or similar) specification of the action to invoke/being invoked
-<9> `getExecuteIn()` - whether this command is executed in the foreground or background
-<10> `getExecutor()` - the (current) executor of this command, either user, or background service, or other (eg redirect after post).
-<11> `getPersistence()`- the policy controlling whether this command should ultimately be persisted (either "persisted", "if hinted", or "not persisted")
-<12> `isPersistHint()` - whether that the command should be persisted, if persistence policy is "if hinted".
-<13> `getStartedAt()` - the date/time at which this action started (same as `timestamp` property for foreground commands)
-<14> `getCompletedAt()` - the date/time at which this action completed.
-<15> `getParent()` - for actions created through the `BackgroundService`, captures the parent action
-<16> `getResult()` - bookmark to object returned by action, if any
-<17> `getException()` - exception stack trace if action threw exception
-
-
-
-
-== Usage
-
-The typical way to indicate that an action should be treated as a command is to annotate it with the xref:_ug_reference-annotations_manpage-Action_command[`@Action#command()`] annotation.
-
-For example:
-
-[source,java]
-----
-public class ToDoItem ... {
- @Action(command=CommandReification.ENABLED)
- public ToDoItem completed() { ... }
-}
-----
-
-
-[TIP]
-====
-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:_ug_reference-annotations_manpage-Action_command[`@Action#command()`] and xref:_ug_runtime_configuring-core[runtime configuration] for further details.
-====
-
-
-The xref:_ug_reference-annotations_manpage-Action_command[`@Action#command()`] annotation can also be used to specify whether the command should be performed in the background, for example:
-
-[source,java]
-----
-public class ToDoItem ... {
- @Command(executeIn=ExecuteIn.BACKGROUND)
- public ToDoItem scheduleImplicitly() {
- completeSlowly(3000);
- return this;
- }
-}
-----
-
-When a background command is invoked, the user is returned the command object itself (to provide a handle to the command being invoked).
-
-This requires that an implementation of xref:_ug_reference-services-spi_manpage-CommandService[`CommandService`] that persists the commands (such as the (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module's `CommandService`) is configured. It also requires that a scheduler is configured to execute the background commands, see xref:_ug_reference-services-spi_manpage-BackgroundCommandService[`BackgroundCommandService`]).
-
-
-
-== Interacting with the services
-
-Typically the domain objects have little need to interact with the `CommandContext` and `Command` directly; what is more useful is that these are persisted in support of the various use cases identified above.
-
-One case however where a domain object might want to obtain the `Command` is to determine whether it has been invoked in the foreground, or in the background. It can do this using the `getExecutedIn()` method:
-
-Although not often needed, this then allows the domain object to access the `Command` object through the `CommandContext` service. To expand th above example:
-
-
-[source,java]
-----
-public class ToDoItem ... {
- @Action(
- command=CommandReification.ENABLED,
- commandExecuteIn=CommandExecuteIn.BACKGROUND
- )
- public ToDoItem completed() {
- ...
- Command currentCommand = commandContext.getCommand();
- ...
- }
- @Inject
- CommandContext commandContext;
-}
-----
-
-
-If run in the background, it might then notify the user (eg by email) if all work is done.
-
-This leads us onto a related point, distinguishing the current effective user vs the originating "real" user. When running in the foreground, the current user can be obtained from the `DomainObjectContainer`, using:
-
-[source,java]
-----
-String user = container.getUser().getName();
-----
-
-If running in the background, however, then the current user will be the credentials of the background process, for example as run by a Quartz scheduler job.
-
-The domain object can still obtain the original ("effective") user that caused the job to be created, using:
-
-[source,java]
-----
-String user = commandContext.getCommand().getUser();
-----
-
-
-
-
-
-== Registering the Services
-
-Assuming that the `configuration-and-annotation` services installer is configured:
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then Isis' core implementation of `CommandContext` service is automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
-
-
-
-
-
-
-== Related Services
-
-As discussed above, the supporting xref:_ug_reference-services-spi_manpage-CommandService[`CommandService`] enables `Command` objects to be persisted. Other related services are the xref:_ug_reference-services-api_manpage-BackgroundService[`BackgroundService`] and xref:_ug_reference-services-spi_manpage-BackgroundCommandService[`BackgroundCommandService`]). For `BackgroundService` captures commands for execution in the background, while the [BackgroundCommandService] persists such commands for execution.
-
-The implementations of `CommandService` and `BackgroundCommandService` are intended to go together, so that persistent parent `Command`s can be associated with their child background `Command`s.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-DeepLinkService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-DeepLinkService.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-DeepLinkService.adoc
deleted file mode 100644
index 15308bf..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-DeepLinkService.adoc
+++ /dev/null
@@ -1,57 +0,0 @@
-[[_ug_reference-services-api_manpage-DeepLinkService]]
-= `DeepLinkService`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `DeepLinkService` provides the ability to obtain a `java.net.URI` that links to a representation of any (persisted) domain entity or
-view model.
-
-A typical use case is to generate a clickable link for rendering in an email, PDF, tweet or other communication.
-
-
-
-== API & Implementation
-
-The API defined by `DeepLinkService` is:
-
-[source,java]
-----
-public interface DeepLinkService {
- URI deepLinkFor(Object domainObject); // <1>
-}
-----
-<1> Creates a URI that can be used to obtain a representation of the provided domain object in one of the Isis viewers.
-
-The xref:_ug_wicket-viewer[Wicket viewer] this provides an implementation for accessing the representation through this viewer. (For the xref:_ug_restfulobjects-viewer[RestfulObjects viewer], a URL can be constructed according to the link:http://www.restfulobjects.org[Restful Objects spec] in conjunction with a `Bookmark` obtained via the xref:_ug_reference-services-api_manpage-BookmarkService[`BookmarkService`]).
-
-
-
-== Usage within the framework
-
-The xref:_ug_reference-services-spi_manpage-EmailNotificationService[`EmailNotificationService`] uses this service in order to generate emails as part of xref:_ug_wicket-viewer_features_user-registration[user registration].
-
-
-
-== Implementations
-
-The Wicket viewer core framework provides a default implementation of this API:
-
-* `org.apache.isis.viewer.wicket.viewer.services.DeepLinkServiceWicket`
-
-
-
-
-== Registering the Services
-
-Assuming that the `configuration-and-annotation` services installer is configured:
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-and that the xref:_ug_wicket-viewer[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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-DomainObjectContainer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-DomainObjectContainer.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-DomainObjectContainer.adoc
deleted file mode 100644
index a94ab4e..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-DomainObjectContainer.adoc
+++ /dev/null
@@ -1,43 +0,0 @@
-[[_ug_reference-services-api_manpage-DomainObjectContainer]]
-= `DomainObjectContainer`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `DomainObjectContainer` service provides a set of general purpose functionality for domain objects to call. Principal amongst these are a generic APIs for querying objects and creating and persisting objects. In addition, the service provides access to security context (the "current user"), allows information and warning messages to be raised, and various other miscellaneous functions.
-
-[NOTE]
-====
-Compared to other services provided by Isis, the `DomainObjectContainer` provides by far the most number of methods, addressing several quite distinct responsibilities. This is a historical accident: in early versions of Isis the `DomainObjectContainer` was the one and only domain service provided by the framework.
-
-In the future we may deprecate this service and break out its responsibilities into a number of small services. However, given how important this service was in days past, we are unlikely to delete it as a service even once it has been deprecated.
-====
-
-The sections below discuss the functions provided by the service, broken out into categories.
-
-
-include::_ug_reference-services-api_manpage-DomainObjectContainer_object-creation-api.adoc[leveloffset=+1]
-include::_ug_reference-services-api_manpage-DomainObjectContainer_generic-repository-api.adoc[leveloffset=+1]
-include::_ug_reference-services-api_manpage-DomainObjectContainer_object-persistence-api.adoc[leveloffset=+1]
-include::_ug_reference-services-api_manpage-DomainObjectContainer_messages-api.adoc[leveloffset=+1]
-include::_ug_reference-services-api_manpage-DomainObjectContainer_security-api.adoc[leveloffset=+1]
-include::_ug_reference-services-api_manpage-DomainObjectContainer_presentation-api.adoc[leveloffset=+1]
-include::_ug_reference-services-api_manpage-DomainObjectContainer_validation-api.adoc[leveloffset=+1]
-include::_ug_reference-services-api_manpage-DomainObjectContainer_properties-api.adoc[leveloffset=+1]
-include::_ug_reference-services-api_manpage-DomainObjectContainer_services-api.adoc[leveloffset=+1]
-
-
-
-
-
-== Registering the Service
-
-Assuming that the `configuration-and-annotation` services installer is configured:
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then 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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-DomainObjectContainer_generic-repository-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-DomainObjectContainer_generic-repository-api.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-DomainObjectContainer_generic-repository-api.adoc
deleted file mode 100644
index c646c3b..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-DomainObjectContainer_generic-repository-api.adoc
+++ /dev/null
@@ -1,89 +0,0 @@
-[[_ug_reference-services-api_manpage-DomainObjectContainer_generic-repository-api]]
-= Generic Repository 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/
-
-
-
-The repository API acts as an abstraction over the JDO/DataNucleus objectstore. You can use it during prototyping to write naive queries (find all rows, then filter using the Guava `Predicate` API, or you can use it to call JDO link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/query.html#named[named queries] using JDOQL.
-
-As an alternative, you could also use link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/jdoql_typesafe.html[JDO typesafe queries] through the xref:_ug_reference-services-api_manpage-IsisJdoSupport[`IsisJdoSupport`] service.
-
-
-[source,java]
-----
-public interface DomainObjectContainer {
- @Programmatic
- public <T> List<T> allInstances(Class<T> ofType, long... range); // <1>
- @Programmatic
- <T> List<T> allMatches(Query<T> query); // <2>
- @Programmatic
- <T> List<T> allMatches(Class<T> ofType, Predicate<? super T> predicate, long... range); // <3>
- @Programmatic
- <T> List<T> allMatches(Class<T> ofType, String title, long... range); // <4>
- @Programmatic
- <T> List<T> allMatches(Class<T> ofType, T pattern, long... range); // <5>
- ...
-}
-----
-<1> all persisted instances of specified type. Mostly for prototyping, though can be useful to obtain all instances of domain entities if the number is known to be small. The optional varargs parameters are for paging control; more on this below.
-<2> all persistence instances matching the specified `Query`. Query itself is an Isis abstraction on top of JDO/DataNucleus' Query API. *This is the primary API used for querying*
-<3> all persistenced instances of specified type matching `Predicate`. Only really intended for prototyping because in effect constitutes a client-side WHERE clause
-<4> all persisted instances with the specified string as their title. Only very occasionally used
-<5> all persisted instances matching object (query-by-example). Only very occasionally used
-
-There are various implementations of the `Query` API, but these either duplicate functionality of the other overloads of `allMatches(...)` or they are not supported by the JDO/DataNucleus object store. The only significant implementation of `Query` to be aware of is `QueryDefault`, which identifies a named query and a set of parameter/argument tuples.
-
-For example, in the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] the `ToDoItem` is annotated:
-
-[source,java]
-----
-@javax.jdo.annotations.Queries( {
- @javax.jdo.annotations.Query(
- name = "findByAtPathAndComplete", language = "JDOQL", // <1>
- value = "SELECT "
- + "FROM todoapp.dom.module.todoitem.ToDoItem "
- + "WHERE atPath.indexOf(:atPath) == 0 " // <2>
- + " && complete == :complete"), // <3>
- ...
-})
-public class ToDoItem ... {
- ...
-}
-----
-<1> name of the query
-<2> defines the `atPath` parameter
-<3> defines the `complete` parameter
-
-This JDO query definitions are used in the `ToDoItemRepositoryImplUsingJdoql` service:
-
-[source,java]
-----
-@DomainService(nature = NatureOfService.DOMAIN)
-public class ToDoItemRepositoryImplUsingJdoql implements ToDoItemRepositoryImpl {
- @Programmatic
- public List<ToDoItem> findByAtPathAndCategory(final String atPath, final Category category) {
- return container.allMatches(
- new QueryDefault<>(ToDoItem.class,
- "findByAtPathAndCategory", // <1>
- "atPath", atPath, // <2>
- "category", category)); // <3>
- }
- ...
- @javax.inject.Inject
- DomainObjectContainer container;
-}
-----
-<1> corresponds to the "findByAtPathAndCategory" JDO named query
-<2> provide argument for the `atPath` parameter. The pattern is parameter, argument, parameter, argument, ... and so on.
-<3> provide argument for the `category` parameter. The pattern is parameter, argument, parameter, argument, ... and so on.
-
-Other JDOQL named queries (not shown) follow the exact same pattern.
-
-With respect to the other query APIs, the varargs parameters are optional, but allow for (client-side and managed) paging. The first parameter is the `start` (0-based, the second is the `count`.
-
-[TIP]
-====
-It is also possible to query using DataNucleus' type-safe query API. For more details, see xref:_ug_reference-services-api_manpage-IsisJdoSupport[`IsisJdoSupport`].
-====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-DomainObjectContainer_messages-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-DomainObjectContainer_messages-api.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-DomainObjectContainer_messages-api.adoc
deleted file mode 100644
index fd7b573..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-DomainObjectContainer_messages-api.adoc
+++ /dev/null
@@ -1,50 +0,0 @@
-[[_ug_reference-services-api_manpage-DomainObjectContainer_messages-api]]
-= Messages 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/
-
-
-
-The `DomainObjectContainer` allows domain objects to raise information, warning or error messages. These messages can either be simple strings, or can be translated.
-
-[source,java]
-----
-public interface DomainObjectContainer {
- @Programmatic
- void informUser(String message); // <1>
- @Programmatic
- String informUser(TranslatableString message, Class<?> contextClass, String contextMethod); // <2>
-
- @Programmatic
- void warnUser(String message); // <3>
- @Programmatic
- String warnUser(TranslatableString message, Class<?> contextClass, String contextMethod); // <4>
-
- @Programmatic
- void raiseError(String message); // <5>
- @Programmatic
- String raiseError(TranslatableString message, Class<?> contextClass, String contextMethod); // <6>
- ...
-}
-----
-<1> display as a transient message to the user (not requiring acknowledgement). In the xref:_ug_wicket-viewer[Wicket viewer] this is implemented as a toast that automatically disappears after a period of time.
-<2> ditto, but with translatable string, for xref:_ug_more-advanced_i18n[i18n support].
-<3> warn the user about a situation with the specified message. In the xref:_ug_wicket-viewer[Wicket viewer] this is implemented as a toast that must be closed by the end-user.
-<4> ditto, but with translatable string, for i18n support.
-<5> show the user an unexpected application error. In the xref:_ug_wicket-viewer[Wicket viewer] this is implemented as a toast (with a different colour) that must be closed by the end-user.
-<6> ditto, but with translatable string, for i18n support.
-
-
-For example:
-
-[source,java]
-----
-public Order addItem(Product product, @ParameterLayout(named="Quantity) int quantity) {
- if(productRepository.stockLevel(product) == 0) {
- container.warnUser(
- product.getDescription() + " out of stock; order fulfillment may be delayed");
- }
- ...
-}
-----
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-DomainObjectContainer_object-creation-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-DomainObjectContainer_object-creation-api.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-DomainObjectContainer_object-creation-api.adoc
deleted file mode 100644
index 0fd7131..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-DomainObjectContainer_object-creation-api.adoc
+++ /dev/null
@@ -1,40 +0,0 @@
-[[_ug_reference-services-api_manpage-DomainObjectContainer_object-creation-api]]
-= Object Creation 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/
-
-
-
-The object creation APIs are used to instantiate new domain objects or view models.
-
-[source,java]
-----
-public interface DomainObjectContainer {
- @Programmatic
- <T> T newTransientInstance(final Class<T> ofType); // <1>
- @Programmatic
- <T> T newViewModelInstance(final Class<T> ofType, final String memento); // <2>
- ...
-}
-----
-<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:_ug_reference-classes_super_manpage-AbstractViewModel[ViewModel#viewModelMemento()]. In general it is easier to just annotate with xref:_ug_reference-annotations_manpage-ViewModel[`@ViewModel`] and let Isis manage the memento automatically.
-
-For example:
-
-[source,java]
-----
-Customer cust = container.newTransientInstance(Customer.class);
-cust.setFirstName("Freddie");
-cust.setLastName("Mercury");
-container.persist(cust);
-----
-
-As an alternative to using `newTransientInstance(...)`, you could also simply `new()` up the object. Doing this will not inject any domain services, but they can be injected manually using xref:_ug_reference-services-api_manpage-DomainObjectContainer_services-api[#injectServicesInto(...)`].
-
-[NOTE]
-====
-Calling `new(...)` also this circumvents Isis' xref:_ug_reference-methods_reserved_manpage-created[`created()`] callback, and in addition any default values for properties (either explicitly set by xref:_ug_reference-methods_prefixes_manpage-default[`default...()`] or defaulted implicitly according to 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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-DomainObjectContainer_object-persistence-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-DomainObjectContainer_object-persistence-api.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-DomainObjectContainer_object-persistence-api.adoc
deleted file mode 100644
index 9911171..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-DomainObjectContainer_object-persistence-api.adoc
+++ /dev/null
@@ -1,62 +0,0 @@
-[[_ug_reference-services-api_manpage-DomainObjectContainer_object-persistence-api]]
-= Object Persistence 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/
-
-
-
-
-
-The persistence API is used to persist newly created objects (as per xref:_ug_reference-services-api_manpage-DomainObjectContainer_object-creation-api[`#newTransientInstance(...)`], above and to delete (remove) objects that are persistent.
-
-Note that there is no API for updating existing objects; the framework (or rather, JDO/DataNucleus) performs object dirty tracking and so any objects that are modified in the course of a request will be automatically updated).
-
-
-[source,java]
-----
-public interface DomainObjectContainer {
- @Programmatic
- boolean isPersistent(Object domainObject); // <1>
- @Programmatic
- boolean isViewModel(Object domainObject); // <2>
-
- @Programmatic
- void persist(Object domainObject); // <3>
- @Programmatic
- void persistIfNotAlready(Object domainObject); // <4>
-
- @Programmatic
- void remove(Object persistentDomainObject); // <5>
- @Programmatic
- void removeIfNotAlready(Object domainObject); // <6>
-
- @Programmatic
- boolean flush(); // <7>
- ...
-}
-----
-<1> test whether a particular domain object is persistent or not
-<2> test whether a particular domain object is a view model or not. Note that this includes any domain objects annotated with xref:_ug_reference-annotations_manpage-DomainObject_nature[`@DomainObject#nature=Nature.EXTERNAL_ENTITY)`] or xref:_ug_reference-annotations_manpage-DomainObject_nature[`@DomainObject#nature=Nature.INMEMORY_ENTITY`]
-<3> persist a transient object. Note though that this will throw an exception if the object is already persistent; this can happen if JDO/DataNucleus's link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/orm/cascading.html[persistence-by-reachability] is in effect. For this reason it is generally better to use:
-<4> persist an object but only if know to not have been persistent. But if the object is persistent, is a no-op
-<5> remove (ie DELETE) a persistent object. For similar reasons to the persistence, it is generally better to use:
-<6> remove (ie DELETE) an object only if known to be persistent. But if the object has already been deleted, then is a no-op.
-<7> flushes all pending changes to the objectstore. Explained further below.
-
-For example:
-
-[source,java]
-----
-Customer cust = container.newTransientInstance(Customer.class);
-cust.setFirstName("Freddie");
-cust.setLastName("Mercury");
-container.persistIfNotAlready(cust);
-----
-
-You should be aware that by default 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:_ug_reference-services-api_manpage-DomainObjectContainer_generic-repository-api[above]. However, this behaviour can be disabled using the xref:_ug_runtime_configuring-core[configuration property] `isis.services.container.disableAutoFlush`.
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-DomainObjectContainer_presentation-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-DomainObjectContainer_presentation-api.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-DomainObjectContainer_presentation-api.adoc
deleted file mode 100644
index 96066eb..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-DomainObjectContainer_presentation-api.adoc
+++ /dev/null
@@ -1,46 +0,0 @@
-[[_ug_reference-services-api_manpage-DomainObjectContainer_presentation-api]]
-= Presentation 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/
-
-
-
-
-A responsibility of every domain object is to return a title. This can be done declaratively using the xref:_ug_reference-annotations_manpage-Title[`@Title`] annotation on property/ies, or it can be done imperatively by writing a xref:_ug_reference-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 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.
-
-Similarly, it often makes sense if xref:_ug_reference-services-api_manpage-DomainObjectContainer_messages-api[raising messages] to use the title of an object in a message rather (than a some other property of the object), because this is how end-users will be used to identifying the object.
-
-The API defined by `DomainObjectContainer` is simply:
-
-[source,java]
-----
-public interface DomainObjectContainer {
- @Programmatic
- String titleOf(Object domainObject); // <1>
- ...
-}
-----
-<1> return the title of the object, as rendered in the UI by the Isis viewers.
-
-
-By way of example, here's some code from the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] showing the use of the API in an message:
-
-[source,java]
-----
- public List<ToDoItem> delete() {
- final String title = container.titleOf(this); // <1>
- ...
- container.removeIfNotAlready(this);
- container.informUser(
- TranslatableString.tr(
- "Deleted {title}", "title", title), // <2>
- this.getClass(), "delete");
- ...
- }
-
-----
-<1> the title is obtained first, because we're not allowed to reference object after it's been deleted
-<2> use the title in an i18n `TranslatableString`
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-DomainObjectContainer_properties-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-DomainObjectContainer_properties-api.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-DomainObjectContainer_properties-api.adoc
deleted file mode 100644
index a02df2a..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-DomainObjectContainer_properties-api.adoc
+++ /dev/null
@@ -1,54 +0,0 @@
-[[_ug_reference-services-api_manpage-DomainObjectContainer_properties-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/
-
-
-
-
-
-= Properties API
-
-The properties API allows domain objects to read the configuration properties aggregated from the various xref:_ug_runtime_configuration-files[configuration files].
-
-[source,java]
-----
-public interface DomainObjectContainer {
- @Programmatic
- String getProperty(String name); // <1>
- @Programmatic
- String getProperty(String name, String defaultValue); // <2>
- @Programmatic
- List<String> getPropertyNames(); // <3>
-}
-----
-<1> Return the configuration property with the specified name; else return null.
-<2> Return the configuration property with the specified name; if it doesn't exist then return the specified default value.
-<3> Return the names of all the available properties.
-
-For example, here's a fictitious service that might wrap link:http://twitter4j.org/en/configuration.html[Twitter4J]. say:
-
-[source,java]
-----
-@DomainService(nature=NatureOfService.DOMAIN)
-public class TweetService {
- @Programmatic
- @PostConstruct
- public void init() {
- this.oauthConsumerKey = container.getProperty("tweetservice.oauth.consumerKey");
- this.oauthConsumerSecret = container.getProperty("tweetservice.oauth.consumerSecret");
- this.oauthAccessToken = container.getProperty("tweetservice.oauth.accessToken");
- this.oauthAccessTokenSecret = container.getProperty("tweetservice.oauth.accessTokenSecret");
- }
- ...
- @Inject
- DomainObjectContainer container;
-}
-----
-
-[TIP]
-====
-If you _do_ have a domain service that needs to access properties, then note that an alternative is to define a xref:_ug_reference-annotations_manpage-PostConstruct[`@PostConstruct`] method and pass in a `Map<String,String>` of properties. The two techniques are almost identical; it's mostly a matter of taste.
-====
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-DomainObjectContainer_security-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-DomainObjectContainer_security-api.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-DomainObjectContainer_security-api.adoc
deleted file mode 100644
index e7c9d40..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-DomainObjectContainer_security-api.adoc
+++ /dev/null
@@ -1,48 +0,0 @@
-[[_ug_reference-services-api_manpage-DomainObjectContainer_security-api]]
-= Security 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/
-
-
-
-The security API allows the domain object to obtain the identity of the user interacting with said object.
-
-[source,java]
-----
-public interface DomainObjectContainer {
- @Programmatic
- UserMemento getUser();
- ...
-}
-----
-
-where in turn (the essence of) `UserMemento` is:
-
-[source,java]
-----
-public final class UserMemento {
- public String getName() { ... }
- public boolean isCurrentUser(final String userName) { ... }
-
- public List<RoleMemento> getRoles() { ... }
- public boolean hasRole(final RoleMemento role) { ... }
- public boolean hasRole(final String roleName) { ... }
- ...
-}
-----
-
-and `RoleMemento` is simpler still:
-
-[source,java]
-----
-public final class RoleMemento {
- public String getName() { ... }
- public String getDescription() { ... }
- ...
-}
-----
-
-The roles associated with the `UserMemento` will be based on the configured xref:_ug_security[security] (typically Shiro).
-
-In addition, when using the xref:_ug_wicket-viewer[Wicket viewer] there will be an additional "org.apache.isis.viewer.wicket.roles.USER" role; this is used internally to restrict access to web pages without authenticating.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-DomainObjectContainer_services-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-DomainObjectContainer_services-api.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-DomainObjectContainer_services-api.adoc
deleted file mode 100644
index a90f1e4..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-DomainObjectContainer_services-api.adoc
+++ /dev/null
@@ -1,37 +0,0 @@
-[[_ug_reference-services-api_manpage-DomainObjectContainer_services-api]]
-= Services 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/
-
-
-The services API allows your domain objects to programmatically inject services into arbitrary objects, as well as to look up services by type:
-
-[source,java]
-----
-public interface DomainObjectContainer {
- @Programmatic
- <T> T injectServicesInto(final T domainObject); // <1>
- @Programmatic
- <T> T lookupService(Class<T> service); // <2>
- @Programmatic
- <T> Iterable<T> lookupServices(Class<T> service); // <3>
- ...
-}
-----
-<1> injects services into domain object; used extensively internally by the framework (eg to inject to other services, or to entities, or integration test instances, or fixture scripts). Service injection is done automatically if objects are created using `#newTransientInstance()`, described xref:_ug_reference-services-api_manpage-DomainObjectContainer_object-creation-api[above]
-<2> returns the first registered service that implements the specified class
-<3> returns an `Iterable` in order to iterate over all registered services that implement the specified class
-
-The primary use case is to instantiate domain objects using a regular constructor ("new is the new new") rather than using the xref:_ug_reference-services-api_manpage-DomainObjectContainer_object-creation-api[`#newTransientInstance()`] API, and then using the `#injectServicesInto(...)` API to set up any dependencies.
-
-For example:
-
-[source,java]
-----
-Customer cust = container.injectServicesInto( new Customer());
-cust.setFirstName("Freddie");
-cust.setLastName("Mercury");
-container.persist(cust);
-----
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-DomainObjectContainer_validation-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-DomainObjectContainer_validation-api.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-DomainObjectContainer_validation-api.adoc
deleted file mode 100644
index 26a98c4..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-DomainObjectContainer_validation-api.adoc
+++ /dev/null
@@ -1,26 +0,0 @@
-[[_ug_reference-services-api_manpage-DomainObjectContainer_validation-api]]
-= Validation 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/
-
-
-
-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:_ug_reference-methods_reserved_manpage-validate[`validate()`].
-
-The API provided is:
-
-[source,java]
-----
-public interface DomainObjectContainer {
- @Programmatic
- boolean isValid(Object domainObject);
- @Programmatic
- String validate(Object domainObject);
- ...
-}
-----
-
-If an object is changed by editing its properties, then (using the xref:_ug_wicket-viewer[Wicket viewer] at least) 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:_ug_reference-methods_prefixes_manpage-validate[`validate...()`] or xref:_ug_reference-methods_prefixes_manpage-disable[`disable...()`] methods. However, this feature should be considered experimental; your mileage may vary.
\ No newline at end of file
[37/45] isis git commit: ISIS-1133: breaking out reference guide and
devenv guide;
moving appendices' release notes and migration notes to other docs;
improving the documentation page.
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..9416dd5
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved.adoc
@@ -0,0 +1,58 @@
+[[_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:ug.adoc#_ug_runtime_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/9c5dafab/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
new file mode 100644
index 0000000..b6a0c22
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved_manpage-cssClass.adoc
@@ -0,0 +1,46 @@
+[[_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:ug.adoc#_ug_wicket-viewer[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:ug.adoc#_ug_runtime_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:ug.adoc#_ug_runtime_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/9c5dafab/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
new file mode 100644
index 0000000..acf457d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved_manpage-disable.adoc
@@ -0,0 +1,102 @@
+[[_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 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 Isis' xref:ug.adoc#_ug_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/9c5dafab/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
new file mode 100644
index 0000000..026a756
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved_manpage-getId.adoc
@@ -0,0 +1,19 @@
+[[_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:rg.adoc#_rg_annotations_manpage-DomainObject_objectType[`objectType()`] attribute for domain objects; it is used as an internal identifier but also appears in URLs within the xref:ug.adoc#_ug_restfulobjects-viewer[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:rg.adoc#_rg_annotations_manpage-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/9c5dafab/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
new file mode 100644
index 0000000..594005c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved_manpage-hide.adoc
@@ -0,0 +1,39 @@
+[[_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 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].
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..5c79721
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved_manpage-iconName.adoc
@@ -0,0 +1,36 @@
+[[_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:ug.adoc#_ug_wicket-viewer[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/9c5dafab/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
new file mode 100644
index 0000000..fc3793d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved_manpage-title.adoc
@@ -0,0 +1,65 @@
+[[_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 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 Isis' xref:ug.adoc#_ug_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:rg.adoc#_rg_services-api_manpage-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:rg.adoc#_rg_annotations_manpage-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/9c5dafab/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
new file mode 100644
index 0000000..3f50754
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_methods_reserved_manpage-validate.adoc
@@ -0,0 +1,27 @@
+[[_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 Isis' xref:ug.adoc#_ug_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/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_object-layout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_object-layout.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_object-layout.adoc
new file mode 100644
index 0000000..bbe7e58
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_object-layout.adoc
@@ -0,0 +1,20 @@
+[[_rg_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::_rg_object-layout_static.adoc[leveloffset=+1]
+include::_rg_object-layout_dynamic.adoc[leveloffset=+1]
+include::_rg_object-layout_application-menu.adoc[leveloffset=+1]
+include::_rg_object-layout_static-vs-dynamic.adoc[leveloffset=+1]
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_object-layout_application-menu.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_object-layout_application-menu.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_object-layout_application-menu.adoc
new file mode 100644
index 0000000..3843f46
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_object-layout_application-menu.adoc
@@ -0,0 +1,171 @@
+[[_rg_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 of a service's actions within a menu
+
+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="...")` 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:ug.adoc#_ug_more-advanced_decoupling_vetoing-visibility[vetoing subscriber].
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_object-layout_dynamic.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_object-layout_dynamic.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_object-layout_dynamic.adoc
new file mode 100644
index 0000000..8bc6c02
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_object-layout_dynamic.adoc
@@ -0,0 +1,113 @@
+[[_rg_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 file
+
+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/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_object-layout_static-vs-dynamic.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_object-layout_static-vs-dynamic.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_object-layout_static-vs-dynamic.adoc
new file mode 100644
index 0000000..cb0d610
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_object-layout_static-vs-dynamic.adoc
@@ -0,0 +1,26 @@
+[[_rg_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:rg.adoc#_rg_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/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_object-layout_static.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_object-layout_static.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_object-layout_static.adoc
new file mode 100644
index 0000000..e8952d0
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_object-layout_static.adoc
@@ -0,0 +1,159 @@
+[[_rg_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:rg.adoc#_rg_annotations_manpage-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:rg.adoc#_rg_annotations_manpage-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:rg.adoc#_rg_annotations_manpage-ActionLayout, [`@ActionLayout`] xref:rg.adoc#_rg_annotations_manpage-CollectionLayout[`@CollectionLayout`], xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout[`@DomainObjectLayout`], xref:rg.adoc#_rg_annotations_manpage-DomainServiceLayout[`@DomainServiceLayout`], xref:rg.adoc#_rg_annotations_manpage-ParameterLayout[`@ParameterLayout`], xref:rg.adoc#_rg_annotations_manpage-PropertyLayout[`@PropertyLayout`], and xref:rg.adoc#_rg_annotations_manpage-ViewModelLayout[`@ViewModelLayout`]
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_services-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api.adoc
new file mode 100644
index 0000000..1e9b436
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api.adoc
@@ -0,0 +1,282 @@
+[[_rg_services-api]]
+= Domain Services 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/
+
+
+Apache Isis includes an extensive number of domain services for your domain objects to use; simply define the service as an annotated field and Isis will inject the service into your object. These services' API are all defined in Isis' applib (`o.a.i.core:isis-core-applib` module); this minimizes the coupling between your code and Isis. It also allows you to easily mock out these services in your unit tests.
+
+[NOTE]
+====
+In addition there are a number of domain services that constitute an SPI; if present they are used by Isis itself rather than by your domain objects. A good example of this is the xref:rg.adoc#_rg_services-spi_manpage-AuditingService[`AuditingService3`] service. The SPI services are covered in the xref:rg.adoc#_rg_services-spi[Domain Services (SPI) chapter].
+====
+
+
+
+The table below summarizes all the APIs defined by Apache Isis. It also lists their corresponding implementation, either a default implementation provided by Isis itself, or provided by one of the in (non-ASF) link:http://www.isisaddons.org[Isis Addons] modules.
+
+.Domain Services
+[cols="3,3a,3a,3a", options="header"]
+|===
+
+|API
+|Description
+|Implementation
+|Notes
+
+
+|xref:rg.adoc#_rg_services-api_manpage-ActionInvocationContext[`o.a.i.applib.` +
+`services.actinv` +
+`ActionInvocation-` +
+`Context`]
+|Request-scoped access to whether action is invoked on object and/or on collection of objects
+|`ActionInvocationContext` +
+``o.a.i.core`` +
+``isis-core-applib``
+|API is also concrete class
+
+
+|xref:rg.adoc#_rg_services-api_manpage-BackgroundService[`o.a.i.applib.` +
+`services.background` +
+`BackgroundService`]
+|Programmatic persistence of commands to be persisted (so can be executed by a background mechanism, eg scheduler)
+|`BackgroundServiceDefault` +
+``o.a.i.core`` +
+``isis-core-runtime``
+|depends on: +
+xref:rg.adoc#_rg_services-spi_manpage-BackgroundCommandService[`BackgroundCommand-Service`]
+
+
+|xref:rg.adoc#_rg_services-api_manpage-BookmarkService[`o.a.i.applib.` +
+`services.bookmark` +
+`BookmarkService`]
+|Convert object reference to a serializable "bookmark", and vice versa
+|`BookmarkServiceDefault` +
+``o.a.i.core`` +
+``isis-core-metamodel``
+|related services:
+`BookmarkHolder-` +
+`ActionContributions`,
+`BookmarkHolder-` +
+`Association-` +
+`Contributions`
+
+
+|xref:rg.adoc#_rg_services-api_manpage-ClockService[`o.a.i.applib.` +
+`services.clock` +
+`ClockService`]
+|Access the current time (and for testing, allow the time to be changed)
+|`ClockService` +
+``o.a.i.core`` +
+``isis-core-applib``
+|API is also a concrete class.
+
+
+|xref:rg.adoc#_rg_services-api_manpage-CommandContext[`o.a.i.applib.` +
+`services.command` +
+`CommandContext`]
+|Request-scoped access the current action that is being invoked, represented as a command object
+|`CommandContext` +
+``o.a.i.core`` +
+``isis-core-applib``
+|API is also a concrete class. +
+depends on: +
+xref:rg.adoc#_rg_services-spi_manpage-CommandService[`CommandService`] for persistent `Command`, else in-memory impl. used
+
+|xref:rg.adoc#_rg_services-api_manpage-DeepLinkService[`o.a.i.applib` +
+`services.deeplink` +
+`DeepLinkService`]
+|Obtain a URL to a domain object (eg for use within an email or report)
+|`DeepLinkServiceWicket` +
+``o.a.i.viewer`` +
+``isis-viewer-wicket-impl``
+|Implementation only usable within Wicket viewer
+
+
+|xref:rg.adoc#_rg_services-api_manpage-DomainObjectContainer[`o.a.i.applib` +
+`DomainObjectContainer`]
+|Generic repository to search, create and delete objects. Also miscellaneous other functions, eg obtain title of object.
+|`DomainObjectContainer-` +
+`Default` +
+``o.a.i.core`` +
+``isis-core-metamodel``
+|
+
+
+|xref:rg.adoc#_rg_services-api_manpage-EmailService[`o.a.i.applib.` +
+`services.email` +
+`EmailService`]
+|Send a HTML email, optionally with attachments.
+|`EmailServiceDefault` +
+``o.a.i.core`` +
+``isis-core-runtime``
+|
+
+
+|xref:rg.adoc#_rg_services-api_manpage-EventBusService[`o.a.i.applib.` +
+`services.eventbus` +
+`EventBusService`]
+|Programmatically post events to the internal event bus. Also used by Isis itself to broadcast domain events:
+
+* xref:rg.adoc#_rg_annotations_manpage-Action_domainEvent[`Action#domainEvent()`]
+* xref:rg.adoc#_rg_annotations_manpage-Property_domainEvent[`Property#domainEvent()`]
+* xref:rg.adoc#_rg_annotations_manpage-Collection_domainEvent[`Collection#domainEvent()`]
+|`EventBusServiceJdo` +
+``o.a.i.core`` +
+``isis-core-objectstore-jdo-datanucleus``
+|
+
+
+|xref:rg.adoc#_rg_services-api_manpage-GuiceBeanProvider[`o.a.i.applib.` +
+`services.guice` +
+`GuiceBeanProvider`]
+|Access to internal framework services initialized using Guice DI.
+|`GuiceBeanProviderWicket` +
+``o.a.i.core`` +
+``isis-viewer-wicket-impl``
+|
+
+
+|xref:rg.adoc#_rg_services-api_manpage-IsisJdoSupport[`o.a.i.applib.` +
+`services.jdosupport` +
+`IsisJdoSupport`]
+|Lower level access to the JDO Persistence API.
+|`IsisJdoSupportImpl` +
+``o.a.i.core`` +
+``isis-core-objectstore-jdo-datanucleus``
+|
+
+
+|xref:rg.adoc#_rg_services-api_manpage-MementoService[`o.a.i.applib.` +
+`services.memento` +
+`MementoService`]
+|Capture a serializable memento of a set of primitives or xref:rg.adoc#_rg_services-api_manpage-BookmarkService[bookmarks]. Primarily used internally, eg in support of commands/auditing.
+|`MementoServiceDefault` +
+``o.a.i.core`` +
+``isis-core-runtime``
+|
+
+
+|xref:rg.adoc#_rg_services-api_manpage-MetaModelService[`o.a.i.applib.` +
+`services.metamodel` +
+`MetaModelService`]
+|Access to certain information from the Isis metamodel.
+|`MetaModelServiceDefault` +
+``o.a.i.core`` +
+``isis-core-metamodel``
+|
+
+
+|xref:rg.adoc#_rg_services-api_manpage-QueryResultsCache[`o.a.i.applib.` +
+`services.` +
+`queryresultscache` +
+`QueryResultsCache`]
+|Request-scoped caching of the results of queries (or any data set generated by a given set of input arguments).
+|`QueryResultsCache` +
+``o.a.i.core`` +
+``isis-core-applib``
+|API is also a concrete class
+
+
+|xref:rg.adoc#_rg_services-api_manpage-ScratchPad[`o.a.i.applib.` +
+`services.scratchpad` +
+`Scratchpad`]
+|Request-scoped service for interchanging information between and aggregating over multiple method calls; in particular for use by "bulk" actions (invoking of an action for all elements of a collection)
+|`Scratchpad` +
+``o.a.i.core`` +
+``isis-core-applib``
+|API is also a concrete class
+
+
+|xref:rg.adoc#_rg_services-api_manpage-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.
+|`SudoServiceDefault` +
+``o.a.i.core`` +
+``isis-core-runtime``
+|API is also a concrete class
+
+
+|xref:rg.adoc#_rg_services-api_manpage-WrapperFactory[`o.a.i.applib.` +
+`services.wrapper` +
+`WrapperFactory`]
+|Interact with another domain object "as if" through the UI (enforcing business rules, firing domain events)
+|`WrapperFactoryDefault` +
+``o.a.i.core`` +
+``isis-core-wrapper``
+|
+
+
+|xref:rg.adoc#_rg_services-api_manpage-XmlSnapshotService[`o.a.i.applib.` +
+`services.xmlsnapshot` +
+`XmlSnapshotService`]
+|Generate an XML representation of an object and optionally a graph of related objects.
+|`XmlSnapshotServiceDefault` +
+``o.a.i.core`` +
+``isis-core-runtime``
+|
+
+|===
+
+Key:
+
+* `o.a.i` is an abbreviation for `org.apache.isis`
+* `o.ia.m` is an abbreviation for `org.isisaddons.module`
+
+
+
+
+
+There is also a number of deprecated domain services.
+
+.Deprecated Domain Services
+[cols="3,3a,3a,3a", options="header"]
+|===
+
+|API
+|Description
+|Implementation
+|Notes
+
+|`o.a.i.applib.` +
+`annotation`
+`Bulk.InteractionContext`
+|Request-scoped access to whether action is invoked on object and/or on collection of objects
+|`Bulk.InteractionContext` +
+``o.a.i.core`` +
+``isis-core-applib``
+|Replaced by xref:rg.adoc#_rg_services-api_manpage-ActionInvocationContext[`ActionInvocationContext`]
+
+
+
+|===
+
+Key:
+
+* `o.a.i` is an abbreviation for `org.apache.isis`
+* `o.ia.m` is an abbreviation for `org.isisaddons.module`
+
+
+
+include::_rg_services-api_manpage-ActionInvocationContext.adoc[leveloffset=+1]
+include::_rg_services-api_manpage-BackgroundService.adoc[leveloffset=+1]
+include::_rg_services-api_manpage-BookmarkService.adoc[leveloffset=+1]
+include::_rg_services-api_manpage-ClockService.adoc[leveloffset=+1]
+include::_rg_services-api_manpage-CommandContext.adoc[leveloffset=+1]
+include::_rg_services-api_manpage-DeepLinkService.adoc[leveloffset=+1]
+include::_rg_services-api_manpage-DomainObjectContainer.adoc[leveloffset=+1]
+include::_rg_services-api_manpage-EmailService.adoc[leveloffset=+1]
+include::_rg_services-api_manpage-EventBusService.adoc[leveloffset=+1]
+include::_rg_services-api_manpage-GuiceBeanProvider.adoc[leveloffset=+1]
+include::_rg_services-api_manpage-IsisJdoSupport.adoc[leveloffset=+1]
+include::_rg_services-api_manpage-MementoService.adoc[leveloffset=+1]
+include::_rg_services-api_manpage-MetamodelService.adoc[leveloffset=+1]
+include::_rg_services-api_manpage-QueryResultsCache.adoc[leveloffset=+1]
+include::_rg_services-api_manpage-ScratchPad.adoc[leveloffset=+1]
+include::_rg_services-api_manpage-SudoService.adoc[leveloffset=+1]
+include::_rg_services-api_manpage-WrapperFactory.adoc[leveloffset=+1]
+include::_rg_services-api_manpage-XmlSnapshotService.adoc[leveloffset=+1]
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-ActionInvocationContext.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-ActionInvocationContext.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-ActionInvocationContext.adoc
new file mode 100644
index 0000000..e7c7119
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-ActionInvocationContext.adoc
@@ -0,0 +1,98 @@
+[[_rg_services-api_manpage-ActionInvocationContext]]
+= `ActionInvocationContext`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `ActionInvocationContext` domain service is a xref:rg.adoc#_rg_annotations_manpage-RequestScoped[`@RequestScoped`] service intended to support the implementation of "bulk" actions annotated with xref:rg.adoc#_rg_annotations_manpage-Action_invokeOn[`@Action#invokeOn()`]. This allows the user to select multiple objects in a table and then invoke the same action against all of them.
+
+When an action is invoked in this way, this service allows each object instance to "know where it is" in the collection; it acts a little like an iterator. In particular, an object can determine if it is the last object to be called, and so can perform special processing, eg to return a summary calculated result.
+
+== API
+
+The API defined by the service is:
+
+[source,java]
+----
+@DomainService(nature = NatureOfService.DOMAIN)
+@RequestScoped // <1>
+public static class ActionInvocationContext {
+ public InvokedOn getInvokedOn() { ... } // <2>
+ public List<Object> getDomainObjects() { ... } // <3>
+ public int getSize() { ... }
+ public int getIndex() { ... } // <4>
+ public boolean isFirst() { ... }
+ public boolean isLast() { ... }
+}
+----
+<1> is xref:rg.adoc#_rg_annotations_manpage-RequestScoped[`@RequestScoped`], so this domain service instance is scoped to a particular request and is then destroyed
+<2> an enum set to either `OBJECT` (if action has been invoked on a single object) or `COLLECTION` (if has been invoked on a collection).
+<3> returns the list of domain objects which are being acted upon
+<4> is the 0-based index to the object being acted upon.
+
+
+
+== Usage
+
+For actions that are void or that return null, Isis will return to the list once executed. But for bulk actions that are non-void, Isis will render the returned object/value from the last object invoked (and simply discards the object/value of all actions except the last).
+
+One idiom is for the domain objects to also use the xref:rg.adoc#_rg_services-api_manpage-Scratchpad[`Scratchpad`] service to share information, for example to aggregate values. The `ActionInvocationContext#isLast()` method can then be used to determine if all the information has been gathered, and then do something with it (eg derive variance across a range of values, render a graph etc).
+
+More prosaically, the `ActoinInvocationContext` can be used to ensure that the action behaves appropriately depending on how it has been invoked (on a single object and/or a collection) whether it is called in bulk mode or regular mode. Here's a snippet of code from the bulk action in the Isis addon example https://github.com/isisaddons/isis-app-todoapp/[todoapp] (not ASF):
+
+[source,java]
+----
+public class ToDoItem ... {
+ @Action(invokeOn=InvokeOn.OBJECTS_AND_COLLECTIONS)
+ public ToDoItem completed() {
+ setComplete(true);
+ ...
+ return actionInteractionContext.getInvokedOn() == InvokedOn.OBJECT
+ ? this // <1>
+ : null; // <2>
+ }
+ @Inject
+ ActionInteractionContext actionInteractionContext;
+}
+----
+<1> if invoked as a regular action, return this object;
+<2> otherwise (if invoked on collection of objects), return null, so that the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] will re-render the list of objects
+
+
+
+
+== Registering the Service
+
+Assuming that the `configuration-and-annotation` services installer is configured:
+
+[source,ini]
+----
+isis.services-installer=configuration-and-annotation
+----
+
+then Isis' default implementation of `ActionInvocationContext` class is automatically registered (it is annotated with `@DomainService`) so no further configuration is required.
+
+
+
+== Unit testing support
+
+The `ActionInvocationContext` class also has a couple of static factory methods intended to support unit testing:
+
+[source,java]
+----
+@DomainService(nature = NatureOfService.DOMAIN)
+@RequestScoped
+public class ActionInvocationContext {
+ public static ActionInvocationContext onObject(final Object domainObject) {
+ return new ActionInvocationContext(InvokedOn.OBJECT, Collections.singletonList(domainObject));
+ }
+ public static ActionInvocationContext onCollection(final Object... domainObjects) {
+ return onCollection(Arrays.asList(domainObjects));
+ }
+ public static ActionInvocationContext onCollection(final List<Object> domainObjects) {
+ return new ActionInvocationContext(InvokedOn.COLLECTION, domainObjects);
+ }
+ ...
+}
+----
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-BackgroundService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-BackgroundService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-BackgroundService.adoc
new file mode 100644
index 0000000..7af9a1f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-BackgroundService.adoc
@@ -0,0 +1,123 @@
+[[_rg_services-api_manpage-BackgroundService]]
+= `BackgroundService`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `BackgroundService`, and the companion xref:rg.adoc#_rg_services-spi_manpage-BackgroundCommandService[`BackgroundCommandService`] SPI service (used by Isis itself), enable action invocations to be persisted such that they may be invoked in the background.
+
+The `BackgroundService` is responsible for capturing a memento representing the action invocation in a typesafe way, and persisting it rather than executing it directly.
+
+The default `BackgroundServiceDefault` implementation (provided by isis-core) works by using a proxy wrapper around the target so that it can capture the action to invoke and its arguments using (a private copy of) xref:rg.adoc#_rg_services-api_manpage-MementoService[`MementoService`]. The persistence delegates the persistence of the memento to an appropriate implementation of the companion `BackgroundCommandService`. One such implementation of `BackgroundCommandService` is provided by (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module.
+
+The persisting of commands is only half the story; there needs to be a separate process to read the commands and execute them. The `BackgroundCommandExecution` abstract class (discussed xref:rg.adoc#_rg_services-api_manpage-BackgroundService_BackgroundCommandExecution[below]) provides infrastructure to do this; the concrete
+implementation of this class depends on the configured `BackgroundCommandService` (in order to query for the persisted (background) ``Command``s.
+
+
+
+== API & Implementation
+
+Returns a proxy around the object which is then used to obtain the signature of the action to be invoked in the background.
+
+[source,java]
+----
+public interface BackgroundService {
+ @Programmatic
+ <T> T execute(final T object);
+}
+----
+
+The default implementation is provided by core (`o.a.i.core.runtime.services.background.BackgroundServiceDefault`).
+
+
+
+== Usage
+
+Using the service is very straight-forward; wrap the target domain object using `BackgroundService#execute(...)` and invoke the method on the object returned by that method.
+
+For example:
+
+[source,java]
+----
+public void submitCustomerInvoices() {
+ for(Customer customer: customerRepository.findCustomersToInvoice()) {
+ backgroundService.execute(customer).submitInvoice();
+ }
+ container.informUser("Calculating...");
+}
+----
+
+This will create a bunch of background commands executing the `submitInvoice()` action for each of the customers returned from the customer repository.
+
+The action method invoked must be part of the Isis metamodel, which is to say it must be public, accept only scalar arguments, and must not be annotated with xref:rg.adoc#_rg_annotations_manpage-Programmatic[`@Programmatic`] or `@Ignore`. However, it may be annotated with xref:rg.adoc#_rg_annotations_manpage-Action_hidden[`@Action#hidden()`] or xref:rg.adoc#_rg_annotations_manpage-ActionLayout_hidden[`@ActionLayout#hidden()`] and it will still be invoked.
+
+In fact, when invoked by the background service, no business rules (hidden, disabled, validation) are enforced; the action method must take responsibility for performing appropriate validation and error checking.
+
+[TIP]
+====
+If you want to check business rules, you can use xref:rg.adoc#_rg_annotations_manpage-WrapperFactory[`@WrapperFactory#wrapNoExecute(...)`].
+====
+
+
+
+== End-user experience
+
+For the end-user, executing an action that delegates work off to the `BackgroundService` raises the problem of how does the user know the work is complete?
+
+One option is for the background jobs to take responsibility to notify the user themselves. In the above example, this would be the `submitInvoice()` method called upon each customer. One could imagine more complex designs where only the final command executed notifies the user.
+
+However, an alternative is to rely on the fact that the `BackgroundService` will automatically hint that the `Command` representing the original interaction (to `submitCustomerInvoices()` in the example above) should be persisted. This will be available if the related xref:rg.adoc#_rg_services-api_manpage-CommandContext[`CommandContext`] and xref:rg.adoc#_rg_services-spi_manpage-CommandService[`CommandService`] domain services are configured, and the `CommandService` supports persistent commands. Note that (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module does indeed provide such an implementation of `CommandService` (as well as of the required `BackgroundCommandService`).
+
+Thus, the original action can run a query to obtain it corresponding `Command`, and return this to the user. The upshot is that the child ``Command``s created by the `BackgroundService` will then be associated with `Command` for the original action.
+
+We could if we wanted write the above example as follows:
+
+[source,java]
+----
+public Command submitCustomerInvoices() {
+ for(Customer customer: customerRepository.findCustomersToInvoice()) {
+ backgroundService.execute(customer).submitInvoice();
+ }
+ return commandContext.getCommand();
+}
+@Inject
+CommandContext commandContext; // <1>
+----
+<1> the injected xref:rg.adoc#_rg_services-api_manpage-CommandContext[`CommandContext`] domain service.
+
+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:
+
+[source,ini]
+----
+isis.services-installer=configuration-and-annotation
+----
+
+then Isis' core implementation of `BackgroundService` is automatically registered (it is annotated with `@DomainService`) so no further configuration is required.
+
+
+
+== Related Services
+
+This service is closely related to the xref:rg.adoc#_rg_services-api_manpage-CommandContext[`CommandContext`] and also that service's supporting xref:rg.adoc#_rg_services-spi_manpage-CommandService[`CommandService`] service.
+
+The `CommandContext` service is responsible for providing a parent `Command` with which the background ``Command``s can then be associated as children, while the `CommandService` is responsible for persisting those parent `Command`s. The latter is analogous to the way in which the `BackgroundCommandService` persists the child background `Command`s.
+
+The implementations of `CommandService` and `BackgroundCommandService` go together; typically both parent `Command`s and child background `Command`s will be persisted in the same way. The (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module provides implementations of both (see xref:rg.adoc#_rg_services-spi_manpage-CommandService[`CommandService`] and xref:rg.adoc#_rg_services-spi_manpage-BackgroundCommandService[`BackgroundCommandService`]).
+
+
+include::_rg_services-api_manpage-BackgroundService_BackgroundCommandExecution.adoc[leveloffset=+1]
+include::_rg_services-api_manpage-BackgroundService_Quartz.adoc[leveloffset=+1]
+
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-BackgroundService_BackgroundCommandExecution.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-BackgroundService_BackgroundCommandExecution.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-BackgroundService_BackgroundCommandExecution.adoc
new file mode 100644
index 0000000..971c6c8
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-BackgroundService_BackgroundCommandExecution.adoc
@@ -0,0 +1,25 @@
+[[_rg_services-api_manpage-BackgroundService_BackgroundCommandExecution]]
+= `BackgroundCommandExecution` abstract class
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `BackgroundCommandExecution` (in isis-core) is an abstract template class provided by isis-core that defines an abstract hook method to obtain background `Command`s to be executed:
+
+[source,java]
+----
+public abstract class BackgroundCommandExecution
+ extends AbstractIsisSessionTemplate {
+ ...
+ protected abstract List<? extends Command> findBackgroundCommandsToExecute();
+ ...
+}
+----
+
+The developer is required to implement this hook method in a subclass.
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-BackgroundService_Quartz.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-BackgroundService_Quartz.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-BackgroundService_Quartz.adoc
new file mode 100644
index 0000000..3802803
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-BackgroundService_Quartz.adoc
@@ -0,0 +1,162 @@
+[[_rg_services-api_manpage-BackgroundService_Quartz]]
+= Quartz Scheduler Configuration
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 last part of the puzzle is to actually run the (appropriate implementation of) `BackgroundCommandExecution). This could be run in a batch job overnight, or run continually by, say, the http://quartz-scheduler.org[Quartz] scheduler or by http://camel.apache.org]Apache Camel]. This section looks at configuring Quartz.
+
+If using (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module, then note that this already provides a suitable concrete implementation, namely `org.isisaddons.module.command.dom.BackgroundCommandExecutionFromBackgroundCommandServiceJdo`. We therefore just need to schedule this to run as a Quartz job.
+
+
+First, we need to define a Quartz job, for example:
+
+[source,java]
+----
+import org.isisaddons.module.command.dom.BackgroundCommandExecutionFromBackgroundCommandServiceJdo;
+public class BackgroundCommandExecutionQuartzJob extends AbstractIsisQuartzJob {
+ public BackgroundCommandExecutionQuartzJob() {
+ super(new BackgroundCommandExecutionFromBackgroundCommandServiceJdo());
+ }
+}
+----
+
+where `AbstractIsisQuartzJob` is in turn the following boilerplate:
+
+[source,java]
+----
+package domainapp.webapp.quartz;
+import org.quartz.Job;
+import org.quartz.JobExecutionContext;
+import org.quartz.JobExecutionException;
+...
+public class AbstractIsisQuartzJob implements Job {
+ public static enum ConcurrentInstancesPolicy {
+ SINGLE_INSTANCE_ONLY,
+ MULTIPLE_INSTANCES
+ }
+
+ private final AbstractIsisSessionTemplate isisRunnable;
+ private final ConcurrentInstancesPolicy concurrentInstancesPolicy;
+ private boolean executing;
+
+ public AbstractIsisQuartzJob(AbstractIsisSessionTemplate isisRunnable) {
+ this(isisRunnable, ConcurrentInstancesPolicy.SINGLE_INSTANCE_ONLY);
+ }
+ public AbstractIsisQuartzJob(
+ AbstractIsisSessionTemplate isisRunnable,
+ ConcurrentInstancesPolicy concurrentInstancesPolicy) {
+ this.isisRunnable = isisRunnable;
+ this.concurrentInstancesPolicy = concurrentInstancesPolicy;
+ }
+
+ public void execute(final JobExecutionContext context)
+ throws JobExecutionException {
+ final AuthenticationSession authSession = newAuthSession(context);
+ try {
+ if(concurrentInstancesPolicy == ConcurrentInstancesPolicy.SINGLE_INSTANCE_ONLY &&
+ executing) {
+ return;
+ }
+ executing = true;
+
+ isisRunnable.execute(authSession, context);
+ } finally {
+ executing = false;
+ }
+ }
+
+ AuthenticationSession newAuthSession(JobExecutionContext context) {
+ String user = getKey(context, SchedulerConstants.USER_KEY);
+ String rolesStr = getKey(context, SchedulerConstants.ROLES_KEY);
+ String[] roles = Iterables.toArray(
+ Splitter.on(",").split(rolesStr), String.class);
+ return new SimpleSession(user, roles);
+ }
+
+ String getKey(JobExecutionContext context, String key) {
+ return context.getMergedJobDataMap().getString(key);
+ }
+}
+----
+
+
+This job can then be configured to run using Quartz' `quartz-config.xml` file:
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<job-scheduling-data
+ xmlns="http://www.quartz-scheduler.org/xml/JobSchedulingData"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://www.quartz-scheduler.org/xml/JobSchedulingData
+http://www.quartz-scheduler.org/xml/job_scheduling_data_1_8.xsd"
+ version="1.8">
+ <schedule>
+ <job>
+ <name>BackgroundCommandExecutionJob</name>
+ <group>Isis</group>
+ <description>
+ Poll and execute any background actions persisted by the BackgroundActionServiceJdo domain service
+ </description>
+ <job-class>domainapp.webapp.quartz.BackgroundCommandExecutionQuartzJob</job-class>
+ <job-data-map>
+ <entry>
+ <key>webapp.scheduler.user</key>
+ <value>scheduler_user</value>
+ </entry>
+ <entry>
+ <key>webapp.scheduler.roles</key>
+ <value>admin_role</value>
+ </entry>
+ </job-data-map>
+ </job>
+ <trigger>
+ <cron>
+ <name>BackgroundCommandExecutionJobEveryTenSeconds</name>
+ <job-name>BackgroundCommandExecutionJob</job-name>
+ <job-group>Isis</job-group>
+ <cron-expression>0/10 * * * * ?</cron-expression>
+ </cron>
+ </trigger>
+ </schedule>
+</job-scheduling-data>
+----
+
+The remaining two pieces of configuration are the `quartz.properties` file:
+
+[source,ini]
+----
+org.quartz.scheduler.instanceName = SchedulerQuartzConfigXml
+org.quartz.threadPool.threadCount = 1
+org.quartz.jobStore.class = org.quartz.simpl.RAMJobStore
+org.quartz.plugin.jobInitializer.class =org.quartz.plugins.xml.XMLSchedulingDataProcessorPlugin
+org.quartz.plugin.jobInitializer.fileNames = webapp/scheduler/quartz-config.xml
+org.quartz.plugin.jobInitializer.failOnFileNotFound = true
+----
+
+and the entry in `web.xml` for the Quartz servlet:
+
+[source,xml]
+----
+<servlet>
+ <servlet-name>QuartzInitializer</servlet-name>
+ <servlet-class>org.quartz.ee.servlet.QuartzInitializerServlet</servlet-class>
+ <init-param>
+ <param-name>config-file</param-name>
+ <param-value>webapp/scheduler/quartz.properties</param-value>
+ </init-param>
+ <init-param>
+ <param-name>shutdown-on-unload</param-name>
+ <param-value>true</param-value>
+ </init-param>
+ <init-param>
+ <param-name>start-scheduler-on-load</param-name>
+ <param-value>true</param-value>
+ </init-param>
+ <load-on-startup>1</load-on-startup>
+ </servlet>
+----
+
[42/45] isis git commit: ISIS-1133: breaking out reference guide and
devenv guide;
moving appendices' release notes and migration notes to other docs;
improving the documentation page.
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_cssClass.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_cssClass.adoc
new file mode 100644
index 0000000..fdef77e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_cssClass.adoc
@@ -0,0 +1,36 @@
+[[_rg_annotations_manpage-CollectionLayout_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()` attribute can be used to render additional CSS classes in the HTML (a wrapping `<div>`) that represents the collection. xref:ug.adoc#_ug_runtime_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:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_cssClass[domain objects], xref:rg.adoc#_rg_annotations_manpage-ViewModelLayout_cssClass[view models], xref:rg.adoc#_rg_annotations_manpage-ActionLayout_cssClass[actions], xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_cssClass[properties] and xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_cssClass[parameters].
+
+
+For example:
+
+[source,java]
+----
+public class ToDoItem {
+ @CollectionLayout(
+ cssClass="x-important"
+ )
+ public SortedSet<ToDoItem> getDependencies() { ... }
+ ...
+}
+----
+
+
+As an alternative to using the annotation, the dynamic xref:rg.adoc#_rg_object-layout_dynamic[`.layout.json`]
+can be used instead, eg:
+
+[source,javascript]
+----
+"dependencies": {
+ "collectionLayout": { "cssClass": "x-important" }
+}
+----
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_describedAs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_describedAs.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_describedAs.adoc
new file mode 100644
index 0000000..68cafeb
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_describedAs.adoc
@@ -0,0 +1,37 @@
+[[_rg_annotations_manpage-CollectionLayout_describedAs]]
+= `describedAs()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `describedAs()` attribute is used to provide a short description of the collection to the user. In the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] it is displayed as a 'tool tip'.
+
+The `describedAs()` attribute can also be specified for xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_describedAs[properties], xref:rg.adoc#_rg_annotations_manpage-ActionLayout_describedAs[actions], xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_describedAs[parameters], xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_describedAs[domain objects] and xref:rg.adoc#_rg_annotations_manpage-ViewModelLayout_describedAs[view models].
+
+
+For example:
+
+[source,java]
+----
+public class ToDoItem {
+ @CollectionLayout(
+ describedAs="Other todo items that must be completed before this one")
+ public SortedSet<ToDoItem getDependencies() { ... }
+ ...
+}
+----
+
+
+As an alternative to using the annotation, the dynamic xref:rg.adoc#_rg_object-layout_dynamic[`.layout.json`]
+can be used instead, eg:
+
+[source,javascript]
+----
+"dependencies": {
+ "collectionLayout": {
+ "describedAs": "Other todo items that must be completed before this one"
+ }
+}
+----
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_hidden.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_hidden.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_hidden.adoc
new file mode 100644
index 0000000..654f6d7
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_hidden.adoc
@@ -0,0 +1,58 @@
+[[_rg_annotations_manpage-CollectionLayout_hidden]]
+= `hidden()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `hidden()` attribute indicates where (in the UI) the collection should be hidden from the user. This attribute can also be applied to xref:rg.adoc#_rg_annotations_manpage-ActionLayout_hidden[actions] and xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_hidden[properties].
+
+
+[TIP]
+====
+It is also possible to use xref:rg.adoc#_rg_annotations_manpage-Collection_hidden[`@Collection#hidden()`] to hide an action at the domain 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:
+
+[source,java]
+----
+public class ToDoItem {
+ @CollectionLayout(
+ hidden=Where.EVERYWHERE
+ public SortedSet<ToDoItem> getDependencies() { ... }
+ ...
+}
+----
+
+
+The acceptable values for the `where` parameter are:
+
+* `Where.EVERYWHERE` or `Where.ANYWHERE` +
++
+The collection should be hidden everywhere.
+
+* `Where.ANYWHERE` +
++
+Synonym for everywhere.
+
+* `Where.OBJECT_FORMS` +
++
+The collection should be hidden when displayed within an object form.
+
+* `Where.NOWHERE` +
++
+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:rg.adoc#_rg_object-layout_dynamic[`.layout.json`]
+can be used instead, eg:
+
+[source,javascript]
+----
+"dependencies": {
+ "collectionLayout": { "hidden": "EVERYWHERE" }
+}
+----
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_named.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_named.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_named.adoc
new file mode 100644
index 0000000..53be3e7
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_named.adoc
@@ -0,0 +1,53 @@
+[[_rg_annotations_manpage-CollectionLayout_named]]
+= `named()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `named()` attribute explicitly specifies the collection's name, overriding the name that would normally be inferred from the Java source code. This attribute can also be specified for xref:rg.adoc#_rg_annotations_manpage-ActionLayout_named[actions], xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_named[properties], xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_named[parameters], xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_named[domain objects], xref:rg.adoc#_rg_annotations_manpage-ViewModelLayout_named[view models] and xref:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_named[domain services].
+
+[TIP]
+====
+Following the link:http://en.wikipedia.org/wiki/Don%27t_repeat_yourself[don't repeat yourself] principle, we recommend that you only use this attribute when the desired name cannot be used in Java source code. Examples of that include a name that would be a reserved Java keyword (eg "package"), or a name that has punctuation, eg apostrophes.
+====
+
+
+By default the name is HTML escaped. To allow HTML markup, set the related `namedEscaped()` attribute to `false`.
+
+
+For example:
+
+[source,java]
+----
+public class ToDoItem {
+ @CollectionLayout(
+ named="Todo items that are <i>dependencies</i> of this item",
+ namedEscaped=false
+ )
+ public SortedSet<ToDoItem getDependencies() { ... }
+ ...
+}
+----
+
+
+
+As an alternative to using the annotation, the dynamic xref:rg.adoc#_rg_object-layout_dynamic[`.layout.json`]
+can be used instead, eg:
+
+[source,javascript]
+----
+"dependencies": {
+ "collectionLayout": {
+ "named": "Todo items that are <i>dependencies</i> of this item",
+ "namedEscaped": false,
+ }
+}
+----
+
+
+[TIP]
+====
+The framework also provides a separate, powerful mechanism for xref:ug.adoc#_ug_more-advanced_i18n[internationalization].
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_paged.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_paged.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_paged.adoc
new file mode 100644
index 0000000..0b71332
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_paged.adoc
@@ -0,0 +1,45 @@
+[[_rg_annotations_manpage-CollectionLayout_paged]]
+= `paged()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `paged()` attribute specifies the number of rows to display in a (parented) collection. This attribute can also be applied to xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_paged[domain objects] and xref:rg.adoc#_rg_annotations_manpage-ViewModelLayout_paged[view models].
+
+
+[WARNING]
+====
+The xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer] currently does not support paging. The xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] _does_ support paging, but note that the paging is performed client-side rather than server-side.
+
+We therefore recommend that large collections should instead be modelled as actions (to allow filtering to be applied to limit the number of rows).
+====
+
+
+For example:
+
+[source,java]
+----
+public class Order {
+ @CollectionLayout(paged=15)
+ public SortedSet<OrderLine> getDetails() {...}
+}
+----
+
+
+It is also possible to specify a global default for the page size of standalone collections, using the xref:ug.adoc#_ug_runtime_configuring-core[configuration property] `isis.viewer.paged.parented`.
+
+
+
+As an alternative to using the annotation, the dynamic xref:rg.adoc#_rg_object-layout_dynamic[`.layout.json`]
+can be used instead, eg:
+
+[source,javascript]
+----
+"details": {
+ "collectionLayout": {
+ "paged": 15
+ }
+}
+----
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_render.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_render.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_render.adoc
new file mode 100644
index 0000000..6d85f2c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_render.adoc
@@ -0,0 +1,40 @@
+[[_rg_annotations_manpage-CollectionLayout_render]]
+= `render()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `render()` attribute specifies that the collection be rendered either "eagerly" (shown open, displaying its contents) or "lazily" (shown closed, hiding its contents). The terminology here is based on the similar concept of lazy loading of collections in the domain/persistence layer boundary (except that the rendering relates to the presentation/domain layer boundary).
+
+
+For example:
+
+[source,java]
+----
+public class Order {
+ @CollectionLayout(render=RenderType.EAGERLY)
+ public SortedSet<LineItem> getDetails() { ... }
+ ...
+}
+----
+
+
+As an alternative to using the annotation, the dynamic xref:rg.adoc#_rg_object-layout_dynamic[`.layout.json`]
+can be used instead, eg:
+
+[source,javascript]
+----
+"details": {
+ "collectionLayout": {
+ "render": "EAGERLY"
+ }
+}
+----
+
+
+[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.
+====
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_sortedBy.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_sortedBy.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_sortedBy.adoc
new file mode 100644
index 0000000..d498c5f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-CollectionLayout_sortedBy.adoc
@@ -0,0 +1,59 @@
+[[_rg_annotations_manpage-CollectionLayout_sortedBy]]
+= `sortedBy()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `sortedBy()` attribute specifies that the collection be ordered using the specified comparator, rather than the natural ordering of the entity (as would usually be the case).
+
+For example:
+
+[source,java]
+----
+public class ToDoItem implements Comparable<ToDoItem> { // <1>
+ public static class DependenciesComparator // <2>
+ implements Comparator<ToDoItem> {
+ @Override
+ public int compare(ToDoItem p, ToDoItem q) {
+ return ORDERING_BY_DESCRIPTION // <3>
+ .compound(Ordering.<ToDoItem>natural())
+ .compare(p, q);
+ }
+ }
+ @CollectionLayout(sortedBy=DependenciesComparator.class) // <4>
+ public SortedSet<ToDoItem> getDependencies() { ... }
+ ...
+}
+----
+<1> the class has a natural ordering (implementation not shown)
+<2> declaration of the comparator class
+<3> ordering defined as being by the object's `description` property (not shown), and then by the natural ordering of the class
+<4> specify the comparator to use
+
+When the `dependencies` collection is rendered, the elements are sorted by the `description` property first:
+
+image::{_imagesdir}reference-annotations/CollectionLayout/sortedby-dependencies.png[width="720px",link="{_imagesdir}reference-annotations/CollectionLayout/sortedby-dependencies.png"]
+
+[NOTE]
+====
+Note that this screenshot shows an earlier version of the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] UI (specifically, pre 1.8.0).
+====
+
+
+Without this annotation, the order would have been inverted (because the natural ordering places items not completed before those items that have been completed.
+
+
+
+
+As an alternative to using the annotation, the dynamic xref:rg.adoc#_rg_object-layout_dynamic[`.layout.json`]
+can be used instead, eg:
+
+[source,javascript]
+----
+"dependencies": {
+ "collectionLayout": {
+ "sortedBy": "com.mycompany.myapp.dom.ToDoItem.DependenciesComparator"
+ }
+}
+----
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Collection_domainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Collection_domainEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Collection_domainEvent.adoc
new file mode 100644
index 0000000..76ceafa
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Collection_domainEvent.adoc
@@ -0,0 +1,158 @@
+[[_rg_annotations_manpage-Collection_domainEvent]]
+= `domainEvent()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+Whenever a domain object (or list of domain objects) is to be rendered, the framework fires off multiple domain events for every property, collection and action of the domain object. In the cases of the domain object's collections, the events that are fired are:
+
+* hide phase: to check that the collection is visible (has not been hidden)
+* disable phase: to check that the collection is usable (has not been disabled)
+* validate phase: to check that the collection's arguments are valid (to add or remove an element)
+* pre-execute phase: before the modification of the collection
+* post-execute: after the modification of the collection
+
+Subscribers subscribe through the xref:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`] using either link:https://github.com/google/guava[Guava] or link:http://www.axonframework.org/[Axon Framework] annotations and can influence each of these phases.
+
+
+[WARNING]
+====
+The xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] does _not_ currently support the modification of collections; they are rendered read-only. However, domain events are still relevant to determine if such collections should be hidden.
+
+The workaround is to create add/remove actions and use xref:rg.adoc#_rg_annotations_manpage-MemberOrder[UI hints] to render them close to the collection.
+====
+
+By default the event raised is `CollectionDomainEvent.Default`. For example:
+
+[source,java]
+----
+public class ToDoItem {
+ @Collection()
+ public SortedSet<ToDoItem> getDependencies() { ... }
+ ...
+}
+----
+
+The purpose of the `domainEvent()` attribute is to allows a custom subclass to be emitted instead. This attribute is also supported for xref:rg.adoc#_rg_annotations_manpage-Action_domainEvent[actions] and xref:rg.adoc#_rg_annotations_manpage-Property_domainEvent[properties].
+
+
+For example:
+
+[source,java]
+----
+public class ToDoItem {
+ public static class DependenciesChangedEvent
+ extends CollectionDomainEvent<ToDoItem, ToDoItem> { // <1>
+ private static final long serialVersionUID = 1L;
+ public DependenciesChangedEvent( // <2>
+ ToDoItem source, // <3>
+ Identifier identifier, // <4>
+ Of of, // <5>
+ ToDoItem value) { // <6>
+ super(source, identifier, of, value);
+ }
+ }
+ @Collection(
+ domainEvent=DependenciesChangedEvent.class
+ )
+ public SortedSet<ToDoItem> getDependencies() { ... }
+ ...
+}
+----
+<1> inherit from `CollectionDomainEvent<T,E>` where `T` is the type of the domain object being interacted with, and `E` is the type of the element in the collection (both `ToDoItem` in this example)
+<2> constructor called reflectively by the framework
+<3> populated with the object being interacted with (the source of the event)
+<4> identifier of the collection
+<5> indicates if the collection is being accessed, added to or removed from.
+<6> the element being added or removed from the collection
+
+
+The benefit is that subscribers can be more targetted as to the events that they subscribe to.
+
+
+
+== Subscribers
+
+Subscribers (which must be domain services) subscribe using either the link:https://github.com/google/guava[Guava] API or (if the xref:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`] has been appropriately configured) using the link:http://www.axonframework.org/[Axon Framework] API. The examples below use the Guava API.
+
+Subscribers can be either coarse-grained (if they subscribe to the top-level event type):
+
+[source,java]
+----
+@DomainService
+public class SomeSubscriber {
+ @Programmatic
+ @com.google.common.eventbus.Subscribe
+ public void on(CollectionInteractionEvent ev) {
+ ...
+ }
+}
+----
+
+or can be fine-grained (by subscribing to specific event subtypes):
+
+[source,java]
+----
+@DomainService
+public class SomeSubscriber {
+ @Programmatic
+ @com.google.common.eventbus.Subscribe
+ public void on(ToDoItem.DependenciesChangedEvent ev) {
+ ...
+ }
+}
+----
+
+[TIP]
+====
+If the AxonFramework is being used, replace `@com.google.common.eventbus.Subscribe` with `@org.axonframework.eventhandling.annotation.EventHandler`.
+====
+
+The subscriber's method is called (up to) 5 times:
+
+* whether to veto visibility (hide)
+* whether to veto usability (disable)
+* whether to veto execution (validate) the element being added to/removed from the collection
+* steps to perform prior to the collection being added to/removed from
+* steps to perform after the collection has been added to/removed from.
+
+The subscriber can distinguish these by calling `ev.getPhase()`. Thus the general form is:
+
+[source,java]
+----
+@Programmatic
+@com.google.common.eventbus.Subscribe
+public void on(CollectionDomainEvent ev) {
+ switch(ev.getPhase()) {
+ case HIDE:
+ // call ev.hide() or ev.veto("") to hide the collection
+ break;
+ case DISABLE:
+ // call ev.disable("...") or ev.veto("...") to disable the collection
+ break;
+ case VALIDATE:
+ // call ev.invalidate("...") or ev.veto("...")
+ // if object being added/removed to collection is invalid
+ break;
+ case EXECUTING:
+ break;
+ case EXECUTED:
+ break;
+ }
+}
+----
+
+It is also possible to abort the transaction during the executing or executed phases by throwing an exception. If the exception is a subtype of `RecoverableException` then the exception will be rendered as a user-friendly warning (eg Growl/toast) rather than an error.
+
+
+
+
+== Raising events programmatically
+
+Normally events are only raised for interactions through the UI. However, events can be raised programmatically either by calling the xref:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`] API directly, or by emulating the UI by
+wrapping the target object using the xref:rg.adoc#_rg_services-api_manpage-WrapperFactory[`WrapperFactory`] domain service.
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Collection_editing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Collection_editing.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Collection_editing.adoc
new file mode 100644
index 0000000..b7cbb42
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Collection_editing.adoc
@@ -0,0 +1,48 @@
+[[_rg_annotations_manpage-Collection_editing]]
+= `editing()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `editing()` annotation indicates whether a collection can be added to or removed from within the UI. This attribute can also be specified for xref:rg.adoc#_rg_annotations_manpage-Property_editing[properties], and can also be specified for the xref:rg.adoc#_rg_annotations_manpage-DomainObject_editing[domain object]
+
+The related `editingDisabledReason()` attribute specifies the a hard-coded reason why the collection cannot be modified directly.
+
+[WARNING]
+====
+The xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] does _not_ currently support the modification of collections; they are rendered read-only.
+
+The workaround is to create add/remove actions and use xref:rg.adoc#_rg_annotations_manpage-MemberOrder[UI hints] to render them close to the collection.
+====
+
+Whether a collection is enabled or disabled depends upon these factors:
+
+* whether the domain object has been configured as immutable through the xref:rg.adoc#_rg_annotations_manpage-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:ug.adoc#_ug_runtime_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.
+
+* else, the result of invoking any supporting xref:rg.adoc#_rg_methods_prefixes_manpage-disable[`disable...()`] supporting methods
+
+
+Thus, to make a collection read-only even if the object would otherwise be editable, use:
+
+
+[source,java]
+----
+public class ToDoItem {
+ @Collection(
+ editing=Editing.DISABLED,
+ editingDisabledReason="Use the add and remove actions to modify"
+ )
+ public SortedSet<ToDoItem> getDependencies() { ... }
+}
+----
+
+[NOTE]
+====
+To reiterate, it is _not_ possible to enable editing for a collection if editing has been disabled at the object-level.
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Collection_hidden.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Collection_hidden.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Collection_hidden.adoc
new file mode 100644
index 0000000..9dd2b27
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Collection_hidden.adoc
@@ -0,0 +1,54 @@
+[[_rg_annotations_manpage-Collection_hidden]]
+= `hidden()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+Collections can be hidden at the domain-level, indicating that they are not visible to the end-user. This attribute can also be applied to xref:rg.adoc#_rg_annotations_manpage-Action_hidden[actions] and xref:rg.adoc#_rg_annotations_manpage-Property_hidden[properties].
+
+[TIP]
+====
+It is also possible to use xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_hidden[`@CollectionLayout#hidden()`] or xref:rg.adoc#_rg_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:
+
+[source,java]
+----
+public class Customer {
+ @Collection(where=Where.EVERYWHERE)
+ public SortedSet<Address> getAddresses() { ... }
+}
+----
+
+
+The acceptable values for the `where` parameter are:
+
+* `Where.EVERYWHERE` or `Where.ANYWHERE` +
++
+The collection should be hidden everywhere.
+
+* `Where.ANYWHERE` +
++
+Synonym for everywhere.
+
+* `Where.OBJECT_FORMS` +
++
+The collection should be hidden when displayed within an object form.
+
+* `Where.NOWHERE` +
++
+The collection should not be hidden.
+
+The other values of the `Where` enum have no meaning for a collection.
+
+
+
+
+[NOTE]
+====
+The xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] suppresses collections when displaying lists of objects.
+
+The xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer] by default suppress collections when rendering a domain object.
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Collection_notPersisted.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Collection_notPersisted.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Collection_notPersisted.adoc
new file mode 100644
index 0000000..c2fa983
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Collection_notPersisted.adoc
@@ -0,0 +1,57 @@
+[[_rg_annotations_manpage-Collection_notPersisted]]
+= `notPersisted()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 (somewhat misnamed) `notPersisted()` attribute indicates that the collection should be excluded from any snapshots generated by the xref:rg.adoc#_rg_services-api_manpage-XmlSnapshotService[`XmlSnapshotService`]. This attribute is also supported for xref:rg.adoc#_rg_annotations_manpage-Property_notPersisted[properties].
+
+
+[WARNING]
+====
+This annotation does _not_ specify that a collection is not persisted in the JDO/DataNucleus objectstore. See below for details as to how to additionally annotate the collection for this.
+====
+
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ @Collection(notPersisted=true)
+ public SortedSet<Order> getPreviousOrders() {...}
+ public void setPreviousOrder(SortedSet<Order> previousOrders) {...}
+ ...
+}
+----
+
+Historically this annotation also hinted as to whether the collection's contents should be persisted in the object store. However, the JDO/DataNucleus objectstore does not recognize this annotation. Thus, to ensure that a collection is actually not persisted, it should *also* be annotated with `@javax.jdo.annotations.NotPersistent`.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ @Collection(notPersisted=true) // <1>
+ @javax.jdo.annotations.NotPersistent // <2>
+ public SortedSet<Order> getPreviousOrders() {...}
+ public void setPreviousOrder(SortedSet<Order> previousOrders) {...}
+ ...
+}
+----
+<1> ignored by Isis
+<2> ignored by JDO/DataNucleus
+
+
+
+Alternatively, if the collection is derived, then providing only a "getter" will also work:
+
+[source,java]
+----
+public class Customer {
+ public SortedSet<Order> getPreviousOrders() {...}
+ ...
+}
+----
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Collection_typeOf.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Collection_typeOf.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Collection_typeOf.adoc
new file mode 100644
index 0000000..6a50f5c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Collection_typeOf.adoc
@@ -0,0 +1,26 @@
+[[_rg_annotations_manpage-Collection_typeOf]]
+= `typeOf()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `typeOf()` attribute specifies the expected type of an element contained within a collection when for whatever reason the type cannot be inferred from the generic type, or to provide a hint about the actual run-time (as opposed to compile-time) type. This attribute can also be specified for xref:rg.adoc#_rg_annotations_manpage-Action_typeOf[actions].
+
+For example:
+
+[source,java]
+----
+public void Customer {
+ @TypeOf(Order.class)
+ public SortedSet getOutstandingOrders() { ... }
+ ...
+}
+----
+
+[TIP]
+====
+In general we recommend that you use generics instead, eg `SortedSet<Order>`.
+====
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Column.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Column.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Column.adoc
new file mode 100644
index 0000000..66984e1
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Column.adoc
@@ -0,0 +1,154 @@
+[[_rg_annotations_manpage-Column]]
+= `@Column` (`javax.jdo`)
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 JDO `@javax.jdo.annotation.Column` provides metadata describing how JDO/DataNucleus should persist the property to a database RDBMS table column (or equivalent concept for other persistence stores).
+
+Apache Isis also parses and interprets this annotation in order to build up aspects of its metamodel.
+
+[NOTE]
+====
+Isis parses the `@Column` annotation from the Java source code; it does not query the JDO metamodel. This means that it the `@Column` annotation must be used rather than the equivalent `<column>` link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/orm/schema_mapping.html[XML metadata].
+
+Moreover, while JDO/DataNucleus will recognize annotations on either the field or the getter method, Isis (currently) only inspects the getter method. Therefore ensure that the annotation is placed there.
+====
+
+This section identifies which attributes of `@Column` are recognized and used by Isis.
+
+
+
+== Nullability
+
+The `allowsNull()` attribute is used to specify if a property is mandatory or is optional.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ @javax.jdo.annotations.Column(allowNulls="true")
+ public String getMiddleInitial() { ... }
+ public void setMiddleInitial(String middleInitial) { ... }
+----
+
+Isis also provides xref:rg.adoc#_rg_annotations_manpage-Property_optionality[`@Property#optionality()`] attribute. If both are specified, Isis will check when it initializes for any contradictions, and will fail-fast with an appropriate error message in the log if there are.
+
+You should also be aware that in the lack of either the `@Column#allowsNull()` or the `@Property#optionality()` attributes, that the JDO and Isis defaults differ. Isis rule is straight-forward: properties are assumed to be required. JDO on the other hand specifies that only primitive types are mandatory; everything else is assumed to be optional. Therefore a lack of either annotation can also trigger the fail-fast validation check.
+
+In the vast majority of cases you should be fine just to add the `@Column#allowsNull()` attribute to the getter. But see the documentation for xref:rg.adoc#_rg_annotations_manpage-Property_optionality[`@Property#optionality()`] attribute for discussion on one or two minor edge cases.
+
+
+
+== Length for ``String``s
+
+The `length()` attribute is used to specify the length of `java.lang.String` property types as they map to `varchar(n)` columns.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ @javax.jdo.annotations.Column(length=20)
+ public String getFirstName() { ... }
+ public void setFirstName(String firstName) { ... }
+ @javax.jdo.annotations.Column(allowNulls="true", length=1)
+ public String getMiddleInitial() { ... }
+ public void setMiddleInitial(String middleInitial) { ... }
+ @javax.jdo.annotations.Column(length=30)
+ public String getLastName() { ... }
+ public void setLastName(String lastName) { ... }
+----
+
+Isis also provides xref:rg.adoc#_rg_annotations_manpage-Property_maxLength[`@Property#maxLength()`] attribute. If both are specified, Isis will check when it initializes for any contradictions, and will fail-fast with an appropriate error message in the log if there are.
+
+
+
+== Length/scale for ``BigDecimal``s
+
+
+The `length()` and `scale()` attributes are used to infer the precision/scale of `java.math.BigDecimal` property types as they map to `decimal(n,p)` columns.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ @javax.jdo.annotations.Column(length=10, scale=2)
+ public BigDecimal getTotalOrdersToDate() { ... }
+ public void setTotalOrdersToDate(BigDecimal totalOrdersToDate) { ... }
+----
+
+For ``BigDecimal``s it is also possible to specify the xref:rg.adoc#_rg_annotations_manpage-Digits[`@Digits`] annotation, whose form is `@Digits(integer, fraction)`. There is a subtle difference here: while `@Column#scale()` corresponds to `@Digits#fraction()`, the value of `@Column#length()` (ie the precision) is actually the _sum_ of the `@Digits`' `integer()` and `fraction()` parts.
+
+If both are specified, Isis will check when it initializes for any contradictions, and will fail-fast with an appropriate error message in the log if there are.
+
+
+
+
+== Hints and Tips
+
+This seems to be a good place to describe some additional common mappings that use `@Column`. Unlike the sections above, the attributes specified in these hints and tips aren't actually part of Isis metamodel.
+
+
+=== Mapping foreign keys
+
+The `name()` attribute can be used to override the name of the column. References to other objects are generally mapped as foreign key columns. If there are multiple references to a given type, then you will want to override the name that JDO/DataNucleus would otherwise default.
+
+For example (taken from link:http://github.com/estatio/estatio[estatio] app):
+
+[source,java]
+----
+public class PartyRelationship {
+ @Column(name = "fromPartyId", allowsNull = "false")
+ public Party getFrom() { ... }
+ public void setFrom(Party from) { ... }
+ @Column(name = "toPartyId", allowsNull = "false")
+ public Party getTo() { ... }
+ public void setTo(Party to) { ... }
+ ...
+}
+----
+
+
+
+== 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.
+
+For example, here's how to map a `Blob` (taken from (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp]):
+
+[source,java]
+----
+private Blob attachment;
+@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 = "BLOB")
+})
+@Property(
+ domainEvent = AttachmentDomainEvent.class,
+ optionality = Optionality.OPTIONAL
+)
+public Blob getAttachment() { ... }
+public void setAttachment(Blob attachment) { ... }
+----
+
+And here's how to map a `Clob` (also taken from the todoapp):
+
+[source,java]
+----
+private Clob doc;
+@javax.jdo.annotations.Persistent(defaultFetchGroup="false", columns = {
+ @javax.jdo.annotations.Column(name = "doc_name"),
+ @javax.jdo.annotations.Column(name = "doc_mimetype"),
+ @javax.jdo.annotations.Column(name = "doc_chars", jdbcType = "CLOB", sqlType = "CLOB")
+})
+@Property(
+ optionality = Optionality.OPTIONAL
+)
+public Clob getDoc() { ... }
+public void setDoc(final Clob doc) { ... }
+----
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Digits.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Digits.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Digits.adoc
new file mode 100644
index 0000000..a31516c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Digits.adoc
@@ -0,0 +1,35 @@
+[[_rg_annotations_manpage-Digits]]
+= `@Digits` (`javax`)
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@javax.validation.constraints.Digits` annotation is recognized by Apache Isis as a means to specify the precision for properties and action parameters of type `java.math.BigDecimal`.
+
+For example (taken from the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp]):
+
+[source,java]
+----
+@javax.jdo.annotations.Column(
+ scale=2 // <1>
+)
+@javax.validation.constraints.Digits(
+ integer=10,
+ fraction=2 // <2>
+)
+public BigDecimal getCost() {
+ return cost;
+}
+public void setCost(final BigDecimal cost) {
+ this.cost = cost!=null
+ ? cost.setScale(2, BigDecimal.ROUND_HALF_EVEN) // <3>
+ :null;
+}
+----
+<1> the xref:rg.adoc#_rg_annotations_manpage-Column[`@Column#scale()`] attribute must be ...
+<2> ... consistent with `@Digits#fraction()`
+<3> the correct idiom when setting a new value is to normalized to the correct scale
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Discriminator.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Discriminator.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Discriminator.adoc
new file mode 100644
index 0000000..93a1c4b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Discriminator.adoc
@@ -0,0 +1,59 @@
+[[_rg_annotations_manpage-Discriminator]]
+= `@Discriminator` (`javax.jdo`)
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@javax.jdo.annotation.Discriminator` is used by JDO/DataNucleus to specify how to discriminate between subclasses of an inheritance hierarchy.
+
+It is valid to add a `@Discriminator` for any class, even those not part of an explicitly mapped inheritance hierarchy. Apache Isis also checks for this annotation, and if present will use the `@Discriminator#value()` as the object type, a unique alias for the object's class name.
+
+[NOTE]
+====
+Isis parses the `@Discriminator` annotation from the Java source code; it does not query the JDO metamodel. This means that it the `@Discriminator` annotation must be used rather than the equivalent `<discriminator>` link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/orm/inheritance.html[XML metadata].
+
+Moreover, while JDO/DataNucleus will recognize annotations on either the field or the getter method, Isis (currently) only inspects the getter method. Therefore ensure that the annotation is placed there.
+====
+
+The object type is used internally by Isis to generate a string representation of an objects identity (the `Oid`). This can appear in several contexts, including:
+
+* as the value of `o.a.i.applib.services.bookmark.Bookmark#getObjectType()`
+* in the `toString()` value of `Bookmark`
+* in the URLs of the xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer]
+* in the URLs of the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] (in general and in particular if xref:ug.adoc#_ug_wicket-viewer_features_hints-and-copy-url[copying URLs])
+* in XML snapshots generated by the xref:rg.adoc#_rg_services-api_manpage-XmlSnapshotService[`XmlSnapshotService`]
+
+
+For example:
+
+[source,java]
+----
+@javax.jdo.annotations.Discriminator(value="custmgmt.Customer")
+public class Customer {
+ ...
+}
+----
+
+has an object type of `custmgmt.Customer`.
+
+If the object type has not been specified, then Isis will use the fully qualified class name of the entity.
+
+
+
+[TIP]
+====
+This might be obvious, but to make explicit: we recommend that you use namespaces of some form or other.
+
+If the object type has not been specified (by either this annotation, or by xref:rg.adoc#_rg_annotations_manpage-PersistenceCapable[`@PersistenceCapable`], or by Isis' own xref:rg.adoc#_rg_annotations_manpage-DomainObject_objectType[`@DomainObject#objectType()`] annotation/attribute), then (as noted above) Isis will use the fully qualified class name of the entity.
+
+However, chances are that the fully qualified class name is liable to change over time, for example if the code is refactored or (more fundamentally) if your company/organization reorganizes/renames itself/is acquired.
+
+We therefore strongly recommend that you specify an object type for all entities, one way or another. Specifying `@Discriminator` will override `@PersistenceCapable`, which overrides `@DomainObject#objectType()`. Using `@PersistenceCapable#schema()` is probably the best choice in most cases.
+====
+
+[NOTE]
+====
+If the object type is not unique across all domain classes then the framework will fail-fast and fail to boot. An error message will be printed in the log to help you determine which classes have duplicate object tyoes.
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject.adoc
new file mode 100644
index 0000000..3731056
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject.adoc
@@ -0,0 +1,105 @@
+[[_rg_annotations_manpage-DomainObject]]
+= `@DomainObject`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@DomainObject` annotation applies to domain objects, collecting together all domain semantics within a single annotation.
+
+The table below summarizes the annotation's attributes.
+
+.`@DomainObject` attributes
+[cols="2,2,4a", options="header"]
+|===
+
+| Attribute
+| Values (default)
+| Description
+
+
+|xref:rg.adoc#_rg_annotations_manpage-DomainObject_auditing[`auditing()`]
+|`AS_CONFIGURED`, `ENABLED`, `DISABLED` +
+(`AS_CONFIGURED`)
+|indicates whether each of the changed properties of an object should be submitted to the registered xref:rg.adoc#_rg_services-spi_manpage-AuditingService[`AuditingService`].
+
+
+|xref:rg.adoc#_rg_annotations_manpage-DomainObject_autoCompleteRepository[`autoCompleteRepository()`]
+|Domain service class
+|nominate a method on a domain service to be used for looking up instances of the domain object
+
+
+|`autoCompleteAction()`
+|Method name +
+(`autoComplete()`)
+|override the method name to use on the auto-complete repository
+
+
+|xref:rg.adoc#_rg_annotations_manpage-DomainObject_bounded[`bounded()`]
+|`true`, `false` +
+(`false`)
+|Whether the number of instances of this domain class is relatively small (a "bounded" set), such that instances could be selected from a drop-down list box or similar.
+
+
+|xref:rg.adoc#_rg_annotations_manpage-DomainObject_editing[`editing()`]
+|`AS_CONFIGURED`, `ENABLED`, `DISABLED` +
+(`AS_CONFIGURED`)
+|whether the object's properties and collections can be edited or not (ie whether the instance should be considered to be immutable)
+
+
+|xref:rg.adoc#_rg_annotations_manpage-DomainObject_nature[`nature()`]
+|`NOT_SPECIFIED`, `JDO_ENTITY`, `EXTERNAL_ENTITY`, `INMEMORY_ENTITY`, `VIEW_MODEL` (`NOT_SPECIFIED`)
+|whether the domain object logically is an entity (part of the domain layer) or is a view model (part of the application layer); and if an entity, how is its persistence managed
+
+
+|xref:rg.adoc#_rg_annotations_manpage-DomainObject_objectType[`objectType()`]
+|(none, which implies fully qualified class name)
+|specify an alias for the domain class used to uniquely identify the object both within the Isis runtime and externally
+
+
+|xref:rg.adoc#_rg_annotations_manpage-DomainObject_publishing[`publishing()`]
+|`AS_CONFIGURED`, `ENABLED`, `DISABLED` +
+(`AS_CONFIGURED`)
+|whether changes to the object should be published to the registered xref:rg.adoc#_rg_services-spi_manpage-PublishingService[`PublishingService`].
+
+
+|`publishing-` +
+`PayloadFactory()`
+|subtype of `PublishingPayloadFactory-` `ForObject` (none)
+|specifies that a custom implementation of `PublishingPayloadFactoryForObject` be used to create the (payload of the) published event representing the change to the object
+
+|===
+
+
+
+For example:
+
+[source,java]
+----
+@DomainObject(
+ auditing=Auditing.ENABLED,
+ autoCompleteRepository=CustomerRepository.class
+ editing=Editing.ENABLED, // <1>
+ publishing=Publishing.ENABLED
+)
+public class Customer {
+ ...
+}
+----
+<1> default value, so could be omitted
+
+
+
+include::_rg_annotations_manpage-DomainObject_auditing.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-DomainObject_autoCompleteRepository.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-DomainObject_bounded.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-DomainObject_editing.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-DomainObject_nature.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-DomainObject_objectType.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-DomainObject_publishing.adoc[leveloffset=+1]
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout.adoc
new file mode 100644
index 0000000..cf27ca8
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout.adoc
@@ -0,0 +1,115 @@
+[[_rg_annotations_manpage-DomainObjectLayout]]
+= `@DomainObjectLayout`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@DomainObjectLayout` annotation applies to domain classes, collecting together all UI hints within a single annotation.
+
+
+[NOTE]
+====
+For view models that have been annotated with `@ViewModel` the equivalent xref:rg.adoc#_rg_annotations_manpage-ViewModelLayout[`@ViewModelLayout`] can be used.
+====
+
+
+The table below summarizes the annotation's attributes.
+
+.`@DomainObjectLayout` attributes
+[cols="2,2,4a", options="header"]
+|===
+
+| Attribute
+| Values (default)
+| Description
+
+
+|xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_bookmarking[`bookmarking()`]
+|`AS_ROOT`, `AS_CHILD`, `NEVER` +
+(`NEVER`)
+|whether (and how) this domain object should be automatically bookmarked
+
+
+|xref:rg.adoc#_rg_annotations_manpage-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:ug.adoc#_ug_runtime_application-specific_application-css[`application.css`]
+
+
+|xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_cssClassFa[`cssClassFa()`]
+|Any valid link:http://fortawesome.github.io/Font-Awesome/[Font awesome] icon name
+|specify a font awesome icon for the action's menu link or icon. +
+
+
+|`cssClassFaPosition()`
+|`LEFT`, `RIGHT` +
+(`LEFT`)
+|Currently unused.
+
+
+|xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_describedAs[`describedAs()`]
+|String.
+|description of this class, eg to be rendered in a tooltip.
+
+
+
+|xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_named[`named()`]
+|String.
+|to override the name inferred from the action's name in code. +
+
+A typical use case is if the desired name is a reserved Java keyword, such as `default` or `package`.
+
+
+|xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_paged[`paged()`]
+|Positive integer
+|the page size for instances of this class when rendered within a table (as returned from an action invocation)
+
+
+|xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_plural[`plural()`]
+|String.
+|the plural name of the class
+
+|===
+
+
+
+For example:
+
+[source,java]
+----
+@DomainObjectLayout(
+ cssClass="x-key",
+ cssClassFa="fa-checklist",
+ describedAs="Capture a task that you need to do",
+ named="ToDo",
+ paged=30,
+ plural="ToDo List")
+)
+public class ToDoItem {
+ ...
+}
+----
+
+
+
+[NOTE]
+====
+Note that there is (currently) no support for specifying UI hints for domain objects through the dynamic xref:rg.adoc#_rg_object-layout_dynamic[`.layout.json`] file (only for properties, collections and actions are supported).
+====
+
+
+
+
+
+
+
+include::_rg_annotations_manpage-DomainObjectLayout_bookmarking.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-DomainObjectLayout_cssClass.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-DomainObjectLayout_cssClassFa.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-DomainObjectLayout_describedAs.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-DomainObjectLayout_named.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-DomainObjectLayout_paged.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-DomainObjectLayout_plural.adoc[leveloffset=+1]
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_bookmarking.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_bookmarking.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_bookmarking.adoc
new file mode 100644
index 0000000..32e52b5
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_bookmarking.adoc
@@ -0,0 +1,66 @@
+[[_rg_annotations_manpage-DomainObjectLayout_bookmarking]]
+= `bookmarking()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `bookmarking()` attribute indicates that an entity is automatically bookmarked. This attribute is also supported for xref:rg.adoc#_rg_annotations_manpage-Action_bookmarking[domain objects].
+
+(In the Wicket viewer), a link to a bookmarked object is shown in the bookmarks panel:
+
+image::{_imagesdir}reference-annotations/DomainObjectLayout/bookmarking.png[width="720px",link="{_imagesdir}reference-annotations/DomainObjectLayout/bookmarking.png"]
+
+[NOTE]
+====
+Note that this screenshot shows an earlier version of the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] UI (specifically, pre 1.8.0).
+====
+
+For example:
+
+[source,java]
+----
+@DomainObject(bookmarking=BookmarkPolicy.AS_ROOT)
+public class ToDoItem ... {
+ ...
+}
+----
+
+indicates that the `ToDoItem` class is bookmarkable:
+
+
+It is also possible to nest bookmarkable entities. For example, this screenshot is taken from http://github.com/estatio/estatio[Estatio]:
+
+image::{_imagesdir}reference-annotations/DomainObjectLayout/bookmarking-nested.png[width="720px",link="{_imagesdir}reference-annotations/DomainObjectLayout/bookmarking-nested.png"]
+
+
+[NOTE]
+====
+Note that this screenshot shows an earlier version of the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] UI (specifically, pre 1.8.0).
+====
+
+
+For example, the `Property` entity "[OXF] Oxford Super Mall" is a root bookmark, but the `Unit` child entity "[OXF-001] Unit 1" only appears as a bookmark _but only if_ its parent `Property` has already been bookmarked.
+
+This is accomplished with the following annotations:
+
+[source,java]
+----
+@DomainObject(bookmarking=BookmarkPolicy.AS_ROOT)
+public class Property { ... }
+----
+
+and
+
+[source,java]
+----
+@DomainObject(bookmarking=BookmarkPolicy.AS_CHILD)
+public abstract class Unit { ... }
+----
+
+The nesting can be done to any level; the Estatio screenshot also shows a bookmark nesting `Lease` > `LeaseItem` > `LeaseTerm` (3 levels deep).
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_cssClass.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_cssClass.adoc
new file mode 100644
index 0000000..ddd84c9
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_cssClass.adoc
@@ -0,0 +1,34 @@
+[[_rg_annotations_manpage-DomainObjectLayout_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()` attribute can be used to render additional CSS classes in the HTML (a wrapping `<div>`) that represents the domain object. xref:ug.adoc#_ug_runtime_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:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_cssClass[domain objects], xref:rg.adoc#_rg_annotations_manpage-ViewModelLayout_cssClass[view models], xref:rg.adoc#_rg_annotations_manpage-ActionLayout_cssClass[actions] xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_cssClass[properties], xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_cssClass[collections] and xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_cssClass[parameters].
+
+
+For example:
+
+[source,java]
+----
+@DomainObject(
+ cssClass="x-core-entity"
+)
+public class ToDoItem { ... }
+----
+
+
+
+
+[NOTE]
+====
+The similar xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_cssClassFa[`@DomainObjectLayout#cssClassFa()`] annotation attribute is also used as a hint to apply CSS, but in particular to allow http://fortawesome.github.io/Font-Awesome/icons/[Font Awesome icons]
+to be rendered as the icon for classes.
+====
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_cssClassFa.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_cssClassFa.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_cssClassFa.adoc
new file mode 100644
index 0000000..9dfcd7a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_cssClassFa.adoc
@@ -0,0 +1,40 @@
+[[_rg_annotations_manpage-DomainObjectLayout_cssClassFa]]
+= `cssClassFa()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `cssClassFa()` attribute is used to specify the name of a link:http://fortawesome.github.io/Font-Awesome/icons/[Font Awesome icon] name, to be rendered as the domain object's icon.
+
+These attributes can also be applied to xref:rg.adoc#_rg_annotations_manpage-ViewModelLayout_cssClassFa[view models] to specify the object's icon, and to xref:rg.adoc#_rg_annotations_manpage-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.
+
+
+
+For example:
+
+[source,java]
+----
+@DomainObjectLayout(
+ cssClassFa="fa-check-circle"
+)
+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.
+
+
+The related `cssClassFaPosition()` attribute is currently unused for domain objects; the icon is always rendered to the left.
+
+
+[TIP]
+====
+The similar xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_cssClass[`@DomainObjectLayout#cssClass()`] annotation attribute is also used as a hint
+to apply CSS, but for wrapping the representation of an object or object
+member so that it can be styled in an application-specific way.
+====
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_describedAs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_describedAs.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_describedAs.adoc
new file mode 100644
index 0000000..562f081
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_describedAs.adoc
@@ -0,0 +1,22 @@
+[[_rg_annotations_manpage-DomainObjectLayout_describedAs]]
+= `describedAs()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `describedAs()` attribute is used to provide a short description of the domain object to the user. In the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] it is displayed as a 'tool tip'. The attribute can also be specified for xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_describedAs[collections], xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_describedAs[properties], xref:rg.adoc#_rg_annotations_manpage-ActionLayout_describedAs[actions], xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_describedAs[parameters] and xref:rg.adoc#_rg_annotations_manpage-ViewModelLayout_describedAs[view models].
+
+For example:
+
+[source,java]
+----
+@DescribedAs("A customer who may have originally become known to us via " +
+ "the marketing system or who may have contacted us directly.")
+public class ProspectiveSale {
+ ...
+}
+----
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_named.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_named.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_named.adoc
new file mode 100644
index 0000000..c2cbea4
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_named.adoc
@@ -0,0 +1,37 @@
+[[_rg_annotations_manpage-DomainObjectLayout_named]]
+= `named()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `named()` attribute explicitly specifies the domain object's name, overriding the name that would normally be inferred from the Java source code. The attribute can also be specified for xref:rg.adoc#_rg_annotations_manpage-ActionLayout_named[actions], xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_named[collections], xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_named[properties], xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_named[parameters], xref:rg.adoc#_rg_annotations_manpage-ViewModelLayout_named[view models] and xref:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_named[domain services].
+
+
+[TIP]
+====
+Following the link:http://en.wikipedia.org/wiki/Don%27t_repeat_yourself[don't repeat yourself] principle, we recommend that you only use this attribute when the desired name cannot be used in Java source code. Examples of that include a name that would be a reserved Java keyword (eg "package"), or a name that has punctuation, eg apostrophes.
+====
+
+
+For example:
+
+[source,java]
+----
+@DomainObjectLayout(
+ named="Customer"
+)
+public class CustomerImpl implements Customer{
+ ...
+}
+----
+
+It's also possible to specify a xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_plural[plural form] of the name, used by the framework when rendering a standalone collection of the domain object.
+
+
+[TIP]
+====
+The framework also provides a separate, powerful mechanism for xref:ug.adoc#_ug_more-advanced_i18n[internationalization].
+====
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_paged.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_paged.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_paged.adoc
new file mode 100644
index 0000000..6963603
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_paged.adoc
@@ -0,0 +1,33 @@
+[[_rg_annotations_manpage-DomainObjectLayout_paged]]
+= `paged()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `paged()` attribute specifies the number of rows to display in a standalone collection, as returned from an action invocation. This attribute can also be applied to xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_paged[collections] and xref:rg.adoc#_rg_annotations_manpage-ViewModelLayout_paged[view models].
+
+
+[WARNING]
+====
+The xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer] currently does not support paging. The xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] _does_ support paging, but note that the paging is performed client-side rather than server-side.
+
+We therefore recommend that large collections should instead be modelled as actions (to allow filtering to be applied to limit the number of rows).
+====
+
+
+For example:
+
+[source,java]
+----
+@DomainObjectLayout(paged=15)
+public class Order {
+ ...
+}
+----
+
+
+It is also possible to specify a global default for the page size of standalone collections, using the xref:ug.adoc#_ug_runtime_configuring-core[configuration property] `isis.viewer.paged.standalone`.
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_plural.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_plural.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_plural.adoc
new file mode 100644
index 0000000..838d182
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_plural.adoc
@@ -0,0 +1,28 @@
+[[_rg_annotations_manpage-DomainObjectLayout_plural]]
+= `plural()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 Apache Isis displays a standalone collection of several objects, it will label the collection using the plural form of the object type.
+
+By default the plural name will be derived from the end of the singular name, with support for some basic English language defaults (eg using "ies" for names ending with a "y").
+
+The `plural()` attribute allows the plural form of the class name to be specified explicitly. This attribute is also supported for xref:rg.adoc#_rg_annotations_manpage-ViewModelLayout_plural[view models].
+
+For example:
+
+[source,java]
+----
+@DomainObjectLayout(plural="Children")
+public class Child {
+ ...
+}
+----
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_auditing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_auditing.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_auditing.adoc
new file mode 100644
index 0000000..29adddc
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObject_auditing.adoc
@@ -0,0 +1,38 @@
+[[_rg_annotations_manpage-DomainObject_auditing]]
+= `auditing()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `auditing()` attribute indicates that if the object is modified, then each of its changed properties should be submitted to the xref:rg.adoc#_rg_services-spi_manpage-AuditingService[`AuditingService`], if one has been configured.
+
+The default value for the attribute is `AS_CONFIGURED`, meaning that the xref:ug.adoc#_ug_runtime_configuring-core[configuration property] `isis.services.audit.objects` is used to determine the whether the action is published:
+
+* `all` +
++
+all changed objects are published
+
+* `none` +
++
+no changed objects are published
+
+If there is no configuration property in `isis.properties` then auditing is automatically enabled for domain objects.
+
+This default can be overridden on an object-by-object basis; if `auditing()` is set to `ENABLED` then changed properties of instances of the domain class are audited irrespective of the configured value; if set to `DISABLED` then the changed properties of instances are _not_ audited, again irrespective of the configured value.
+
+For example:
+
+[source,java]
+----
+@DomainObject(
+ auditing=Auditing.ENABLED // <1>
+)
+public class Customer {
+ ...
+}
+----
+<1> because set to enabled, will be audited irrespective of the configured value.
+
+
+
[44/45] isis git commit: ISIS-1133: breaking out reference guide and
devenv guide;
moving appendices' release notes and migration notes to other docs;
improving the documentation page.
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/_release-notes_migration-notes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/_release-notes_migration-notes.adoc b/adocs/documentation/src/main/asciidoc/_release-notes_migration-notes.adoc
new file mode 100644
index 0000000..cc0065c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/_release-notes_migration-notes.adoc
@@ -0,0 +1,563 @@
+[[_release-notes_migration-notes]]
+= Migration Notes
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+== Upgrading to DataNucleus 4 (in 1.9.0-SNAPSHOT)
+
+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 <<SimpleApp archetype>>; its Maven configuration has been updated.
+
+If you have an existing Isis app that you want to upgrade, then you'll need to make some changes.
+
+
+
+=== In the parent `pom.xml`
+
+under the `<project>/<properties>`, remove:
+
+[source,xml]
+----
+<!-- must be consistent with the versions defined by the JDO Objectstore -->
+<datanucleus-accessplatform-jdo-rdbms.version>3.3.6</datanucleus-accessplatform-jdo-rdbms.version>
+<datanucleus-maven-plugin.version>3.3.2</datanucleus-maven-plugin.version>
+----
+
+
+=== In `dom/pom.xml`,
+
+under `<build>/<plugins>`, remove:
+
+[source,xml]
+----
+<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>compile</phase>
+ <goals>
+ <goal>enhance</goal>
+ </goals>
+ </execution>
+ </executions>
+</plugin>
+----
+
+and (if you have it) under `<build>/<pluginManagement>/<plugins>`, remove:
+
+[source,xml]
+----
+<!--This plugin's configuration is used to store Eclipse m2e settings only. It has no influence on the Maven build itself.-->
+<plugin>
+ <groupId>org.eclipse.m2e</groupId>
+ <artifactId>lifecycle-mapping</artifactId>
+ <version>1.0.0</version>
+ <configuration>
+ <lifecycleMappingMetadata>
+ <pluginExecutions>
+ <pluginExecution>
+ <pluginExecutionFilter>
+ <groupId>
+ org.datanucleus
+ </groupId>
+ <artifactId>
+ datanucleus-maven-plugin
+ </artifactId>
+ <versionRange>
+ [3.2.0-release,)
+ </versionRange>
+ <goals>
+ <goal>enhance</goal>
+ </goals>
+ </pluginExecutionFilter>
+ <action>
+ <ignore></ignore>
+ </action>
+ </pluginExecution>
+ </pluginExecutions>
+ </lifecycleMappingMetadata>
+ </configuration>
+</plugin>
+----
+
+
+and instead in `<profiles>` add:
+
+
+[source,xml]
+----
+<profile>
+ <id>enhance</id>
+ <activation>
+ <activeByDefault>true</activeByDefault>
+ </activation>
+ <properties>
+ <datanucleus-maven-plugin.version>4.0.0-release</datanucleus-maven-plugin.version>
+ </properties>
+ <build>
+ <pluginManagement>
+ <plugins>
+ <plugin>
+ <!--This plugin's configuration is used to store Eclipse m2e settings only. It has no influence on the Maven build itself.-->
+ <groupId>org.eclipse.m2e</groupId>
+ <artifactId>lifecycle-mapping</artifactId>
+ <version>1.0.0</version>
+ <configuration>
+ <lifecycleMappingMetadata>
+ <pluginExecutions>
+ <pluginExecution>
+ <pluginExecutionFilter>
+ <groupId>org.datanucleus</groupId>
+ <artifactId>datanucleus-maven-plugin</artifactId>
+ <versionRange>[${datanucleus-maven-plugin.version},)</versionRange>
+ <goals>
+ <goal>enhance</goal>
+ </goals>
+ </pluginExecutionFilter>
+ <action>
+ <ignore></ignore>
+ </action>
+ </pluginExecution>
+ </pluginExecutions>
+ </lifecycleMappingMetadata>
+ </configuration>
+ </plugin>
+ </plugins>
+ </pluginManagement>
+ <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>
+----
+
+If you don't use Eclipse then you can omit the `org.eclipse.m2e` plugin in `<pluginManagement>`.
+
+
+
+
+=== In the webapp's `persistor_datanucleus.properties`
+
+in `src/main/webapp/WEB-INF/`,
+
+change:
+
+[source,ini]
+----
+isis.persistor.datanucleus.impl.datanucleus.autoCreateSchema=true
+isis.persistor.datanucleus.impl.datanucleus.validateTables=true
+isis.persistor.datanucleus.impl.datanucleus.validateConstraints=true
+----
+
+to:
+
+[source,ini]
+----
+isis.persistor.datanucleus.impl.datanucleus.schema.autoCreateAll=true
+isis.persistor.datanucleus.impl.datanucleus.schema.validateTables=true
+isis.persistor.datanucleus.impl.datanucleus.schema.validateConstraints=true
+----
+
+and change:
+
+[source,ini]
+----
+isis.persistor.datanucleus.impl.datanucleus.identifier.case=PreserveCase
+----
+
+to:
+
+[source,ini]
+----
+isis.persistor.datanucleus.impl.datanucleus.identifier.case=MixedCase
+----
+
+
+[WARNING]
+====
+Be careful to ensure that your classes are only enhanced by the DataNucleus 4 enhancer, and _not_ by the DataNucleus 3 enhancer. Or even, be careful that they are not doubly enhanced. One of our committers had this situation and it led to all sorts of bizarre issues. The solution, it turned out, was actually just to do a full `mvn clean`.
+
+If you are struggling and suspect you may have misconfigured the enhancer plugin, then you can decompile the bytecode (eg in IntelliJ) and take a look:
+
+* A class enhanced with DataNucleus 3 would implement `javax.jdo.spi.PersistenceCapable` interface
+* A class enhanced with DataNucleus 4 will implement `org.datanucleus.enhancer.Persistable`.
+====
+
+
+
+
+== Upgrading to Java 8 (1.9.0-SNAPSHOT and later)
+
+Apache Isis 1.9.0-SNAPSHOT is the first version to support Java 8. You can continue to use Java 7, but if you want to move to Java 8 then there are several small changes to be made.
+
+=== In the parent `pom.xml`
+
+under `<build>/<pluginManagement>/<plugins>`, add (or update) maven-enforcer-plugin:
+
+[source,xml]
+----
+<plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-compiler-plugin</artifactId>
+ <version>3.1</version>
+ <configuration>
+ <source>1.8</source>
+ <target>1.8</target>
+ <compilerArgument>-parameters</compilerArgument>
+ </configuration>
+ <executions>
+ <execution>
+ <id>source</id>
+ <phase>compile</phase>
+ </execution>
+ <execution>
+ <id>test</id>
+ <phase>test-compile</phase>
+ </execution>
+ </executions>
+</plugin>
+----
+
+[TIP]
+====
+The `-parameters` argument causes the Java compiler to capture the names of method parameters in the `.class` files. Isis can be configured to use this, thereby avoiding the requirement to annotate every parameter with `@ParameterLayout(named=...)` or `@Named()`. The necessary configuration is provided in an http://github.com/isisaddons/isis-metamodel-paraname8[Isis addons' paraname8] metamodel extension (non-ASF).
+====
+
+We also recommend that you add the `maven-enforcer-plugin` (if not used already). Again, this resides under `<build>/<pluginManagement>/<plugins>`:
+
+[source,xml]
+----
+<plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-enforcer-plugin</artifactId>
+ <version>1.3.1</version>
+ <configuration>
+ <rules>
+ <requireMavenVersion>
+ <version>[3.2.1,)</version>
+ </requireMavenVersion>
+ <requireJavaVersion>
+ <version>[1.8.0,)</version>
+ </requireJavaVersion>
+ <requirePluginVersions>
+ <message>All plugin versions must be defined!</message>
+ <banLatest>true</banLatest>
+ <banRelease>true</banRelease>
+ </requirePluginVersions>
+ <DependencyConvergence />
+ </rules>
+ </configuration>
+ <executions>
+ <execution>
+ <id>validate-enforce</id>
+ <phase>validate</phase>
+ <goals>
+ <goal>enforce</goal>
+ </goals>
+ </execution>
+ </executions>
+</plugin>
+----
+
+
+== Migrating from v1.7.0 to 1.8.0
+
+Existing projects written against v1.7.0 should run against v1.8.0 without any changes. In particular (unlike 1.6.0 and
+ 1.7.0) there should be no need to update `pom.xml` files of existing projects. If you *do* encounter any difficulties
+then let us know via the [users mailing list](../../support.html), so we can support you and document issues here.
+
+That said, many of the existing annotations have been deprecated in 1.8.0, replaced with a simplified and rationalized
+ set of annotations; see [here](../../reference/recognized-annotations/about.html). To help you migrate your application
+ over to the new annotations, there is a new configuration property that can be set in `isis.properties`:
+
+ isis.reflector.validator.allowDeprecated=false
+
+If this flag is present and set to false, then metamodel validation errors will be thrown on startup if any deprecated
+annotations are encountered. These can be viewed either in the console or by browsing to the app (an error page will
+be displayed).
+
+
+
+
+
+== Migrating from v1.6.0 to 1.7.0
+
+In v1.7.0 we've continued the work started in v1.6.0 in modularizing the framework. The most important change to note is that all Isis core modules (with the Maven `groupId` of `org.apache.isis.module` have now MOVED to [http://www.isisaddons.org](Isis Addons).
+
+In addition, we've retired some obsolete (and unused) functionality, specifically the `ProfileStore` component.
+
+To move up amounts to changing POM files and, where required, updating package names for any referenced modules.
+
+=== Reorganized 'modules'
+
+The following modules are no longer released as part of Isis core and have moved to Isis Addons (or in one case, back into Isis core).
+
+Minor changes are required to `pom.xml` files and (in some cases) to `isis.properties` config file.
+
+In one or two exceptional cases it may be necessary to fix up import statements if there are reference to changed package/class names in code (most likely any dependency on the `devutils` module or `settings` module).
+
+==== Audit module
+
+In `pom.xml`, replace:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.isis.module</groupId>
+ <artifactId>isis-module-audit-jdo</artifactId>
+</dependency>
+----
+
+with:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.isisaddons.module.audit</groupId>
+ <artifactId>isis-module-audit-dom</artifactId>
+</dependency>
+----
+
+If necessary, also update any services registered in `isis.properties` (package/class names may have changed slightly).
+
+==== Command module
+
+In `pom.xml`, replace:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.isis.module</groupId>
+ <artifactId>isis-module-command-jdo</artifactId>
+</dependency>
+----
+
+with:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.isisaddons.module.command</groupId>
+ <artifactId>isis-module-command-dom</artifactId>
+</dependency>
+----
+
+If necessary, also update any services registered in `isis.properties` (package/class names may have changed slightly).
+
+==== DevUtils module
+
+In `pom.xml`, replace:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.isis.module</groupId>
+ <artifactId>isis-module-devutils-applib</artifactId>
+</dependency>
+----
+
+with:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.isisaddons.module.devutils</groupId>
+ <artifactId>isis-module-devutils-dom</artifactId>
+</dependency>
+----
+
+Remove any references to:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.isis.module</groupId>
+ <artifactId>isis-module-devutils</artifactId>
+</dependency>
+----
+
+or to:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.isis.module</groupId>
+ <artifactId>isis-module-devutils-impl</artifactId>
+</dependency>
+----
+
+These modules are no longer required (the `org.apache.isis.module:isis-module-devutils-applib`
+and `org.apache.isis.module:isis-module-devutils-impl` submodules have been combined
+into the new `org.isisaddons.module.devutils:isis-module-devutils-dom` module).
+
+If necessary, also update any services registered in `isis.properties` (package/class names may have changed slightly).
+
+==== Publishing module
+
+In `pom.xml`, replace:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.isis.module</groupId>
+ <artifactId>isis-module-publishing-jdo</artifactId>
+</dependency>
+----
+
+with:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.isisaddons.module.publishing</groupId>
+ <artifactId>isis-module-publishing-dom</artifactId>
+</dependency>
+----
+
+If necessary, also update any services registered in `isis.properties` (package/class names may have changed slightly).
+
+==== Publishing Event Serializer RO module
+
+Remove any references to:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.isis.module</groupId>
+ <artifactId>isis-module-publishingeventserializer-ro</artifactId>
+</dependency>
+----
+
+This module has been merged with `org.isisaddons.module.publishing:isis-module-publishing-dom`, above.
+
+==== Settings module
+
+In `pom.xml`, replace:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.isis.module</groupId>
+ <artifactId>isis-module-settings-applib</artifactId>
+</dependency>
+----
+
+with:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.isisaddons.module.settings</groupId>
+ <artifactId>isis-module-settings-dom</artifactId>
+</dependency>
+----
+
+Remove any references to:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.isis.module</groupId>
+ <artifactId>isis-module-settings</artifactId>
+</dependency>
+----
+
+or to:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.isis.module</groupId>
+ <artifactId>isis-module-settings-impl</artifactId>
+</dependency>
+----
+
+These modules are no longer required (the `org.apache.isis.module:isis-module-settings-applib`
+and `org.apache.isis.module:isis-module-settings-impl` submodules have been combined
+into the new `org.isisaddons.module.settings:isis-module-settings-dom` module).
+
+If necessary, also update any services registered in `isis.properties` (package/class names may have changed slightly).
+
+==== Background module
+
+In `pom.xml`, remove:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.isis.module</groupId>
+ <artifactId>isis-module-background</artifactId>
+</dependency>
+----
+
+The service classes have been moved into existing `org.apache.isis.core:isis-core-runtime` Maven module (that is, already be referenced in the `pom.xml`).
+
+If necessary, also update any services registered in `isis.properties` (package/class names may have changed slightly).
+
+=== Retired `ProfileStore` component
+
+As per <a href='https://issues.apache.org/jira/browse/ISIS-802'>ISIS-802</a>, the ProfileStore component has been removed. This functionality was not surfaced or available in the Wicket or Restful Objects viewers, so there is no meaningful loss of functionality. However, Maven `pom.xml` files will require updating:
+
+Specifically, remove any dependencies on `org.apache.isis:isis-core-profilestore`:
+
+[source,xml]
+----
+<dependency>
+ <groupId>org.apache.isis.core</groupId>
+ <artifactId>isis-core-profilestore</artifactId>
+</dependency>
+----
+
+A number of corresponding classes/interfaces have also been removed from the Isis applib:
+
+* `org.apache.isis.applib.fixtures.userprofile.UserProfileService`
+* `org.apache.isis.applib.fixtures.userprofile.UserProfileServiceAware`
+* `org.apache.isis.applib.fixtures.UserProfileFixture`
+* `org.apache.isis.applib.profiles.Profile`
+* `org.apache.isis.applib.profiles.Perspective`
+
+It is highly unlikely that any existing production code references these classes.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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 7794ceb..a370601 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 Isis itself was to be able automatically generate a user interface for a domain object model.
-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:user-guide/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.
+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.
Deploying on 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 Isis means that the framework also manages object persistence. Agai
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. Isis' link:user-guide/ug.html#ug_restfulobjects_viewer[RestfulObjects viewer] is an implementation of that spec, making any 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. Isis' link:guides/ug.html#_ug_restfulobjects_viewer[RestfulObjects viewer] is an implementation of that spec, making any Isis domain object automatically available via REST.
There are two main use cases for deploying Isis as a RESTful web service are:
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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 af785da..b30d1e2 100644
--- a/adocs/documentation/src/main/asciidoc/documentation.adoc
+++ b/adocs/documentation/src/main/asciidoc/documentation.adoc
@@ -22,7 +22,7 @@ pass:[<br/>]
| *What is Isis?*
-* *link:./isis-in-pictures[What's Isis?] ... in pictures*
+* *link:./isis-in-pictures[What is Apache Isis?] ... in pictures*
* link:./powered-by.html[Powered by Isis]
* link:./how-isis-works.html[How Isis Works] image:{_imagesdir}tv_show-25.png[width="25px" link="how-isis-works.html"]
* link:./common-use-cases.html[Common Use Cases]
@@ -39,8 +39,9 @@ pass:[<br/>]
|*Development Environment:*
- * link:./user-guide/ug.html#_ug_appendices_dev-env_intellij[Setting up IntelliJ]
- * link:./user-guide/ug.html#_ug_appendices_dev-env_eclipse[Setting up Eclipse]
+* link:./guides/dg.html#_dg_intellij[Setting up IntelliJ]
+* link:./guides/dg.html#_dg_eclipse[Setting up Eclipse]
+* *link:./editor-templates.html[IDE templates]* (IntelliJ and Eclipse)
@@ -52,23 +53,24 @@ pass:[<br/>]
|*User Guide:*
-yada yada
+Core concepts, how tos, more advanced techniques, Wicket viewer, Restful Objects viewer, security, configuration, deployment, testing, extending
-pass:[<a class="button guide" href="./user-guide/ug.html" role="button">User Guide »</a>]
+pass:[<a class="button guide" href="./guides/ug.html" role="button">User Guide »</a>]
|*Reference Guide:*
-yada yada
+Annotations, reserved methods, method prefixes domain services (API and SPI), utility classes, object layout
-pass:[<a class="button guide" href="./ref-guide/rg.html" role="button">Reference Guide »</a>]
+pass:[<a class="button guide" href="./guides/rg.html" role="button">Reference Guide »</a>]
|*Resources:*
-* *link:./cheat-sheet.html[Cheat Sheet]*
+To save you time
-* link:./icons.html[Icons]
* *link:./editor-templates.html[IDE templates]* (IntelliJ and Eclipse)
+* *link:./cheat-sheet.html[Cheat Sheet]*
+* link:./icons.html[Icons]
|===
@@ -79,10 +81,13 @@ pass:[<a class="button guide" href="./ref-guide/rg.html" role="button">Reference
[cols="1a,1a,1a",frame="none"]
|===
-|*Further resorces:*
+|*Further resources:*
+
+For digging deeper
-* *link:./screencasts.html[Screencasts]* image:{_imagesdir}tv_show-25.png[width="25px",link="./screencasts.html]
+* link:./screencasts.html[Screencasts] image:{_imagesdir}tv_show-25.png[width="25px",link="./screencasts.html]
* link:./articles-and-presentations.html[Articles, Conferences, Podcasts]
+
* link:./books.html[Books]
* link:./resources/thesis/Pawson-Naked-Objects-thesis.pdf[Naked Objects PhD thesis] (Pawson)
//* link:./downloadable-presentations.html[Downloadable Presentations]
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/git-policy.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/git-policy.adoc b/adocs/documentation/src/main/asciidoc/git-policy.adoc
index f34147a..bdd314f 100644
--- a/adocs/documentation/src/main/asciidoc/git-policy.adoc
+++ b/adocs/documentation/src/main/asciidoc/git-policy.adoc
@@ -84,8 +84,6 @@ This way of working gives us the full history on the branch as to what the thoug
== Commit message
-==== Commit message format
-
The minimum we expect in a commit messages is:
[source,bash]
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_dg_cmd-line.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_dg_cmd-line.adoc b/adocs/documentation/src/main/asciidoc/guides/_dg_cmd-line.adoc
new file mode 100644
index 0000000..03147e5
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_dg_cmd-line.adoc
@@ -0,0 +1,9 @@
+[[_dg_cmd-line]]
+= Developing from the Command Line
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../../
+:_imagesdir: images/
+:toc: right
+
+IMPORTANT: TODO
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_dg_eclipse.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_dg_eclipse.adoc b/adocs/documentation/src/main/asciidoc/guides/_dg_eclipse.adoc
new file mode 100644
index 0000000..49fe925
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_dg_eclipse.adoc
@@ -0,0 +1,136 @@
+[[_dg_eclipse]]
+= Setting up Eclipse
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../../
+:_imagesdir: images/
+:toc: right
+
+
+We highly recommend that you develop your Isis application using an IDE. Isis is built with Maven, and all modern IDEs can import Maven projects.
+
+If you are an http://www.eclipse.org[Eclipse] user, then we recommend you download the "Eclipse JEE package" configuration.
+
+When running an Isis application, it's necessary to setup the development environment so that the Java bytecode can be enhanced by the link:http://www.datanucleus.org[DataNucleus] enhancer. If working in Eclipse, then JDO enhancement is most easily done by installing the http://www.datanucleus.org/products/datanucleus/jdo/guides/eclipse.html[DataNucleus' Eclipse plugin]. This hooks the bytecode enhancement of your domain objects into Eclipse's normal incremental compilation.
+
+This plugin needs to be configured for each of your domain modules (usually just one in any given app). The steps are therefore:
+
+* import the project into Eclipse
+* configure the DataNucleus enhancer
+* run the app from the `.launch` file
+
+
+
+
+== Screencast
+
+The following screencast shows how to import an Apache Isis maven-based application into Eclipse and configure to use with the JDO Objectstore
+
+video::RgcYfjQ8yJA[youtube,width="640px",height="480px"]
+
+
+
+
+== Importing the Project
+
+Use File > Import, then Maven > Existing Maven Projects.
+
+
+
+
+== Add DataNucleus support
+
+[TIP]
+====
+Make sure you are in the 'Java' Perspective, not the 'Java EE' Perspective.
+====
+
+
+In Eclipse, for the _domain object model_ project, first add DataNucleus support:
+
+image::{_imagesdir}appendices/dev-env/eclipse/eclipse-100-project-support.png[width="600px",link="{_imagesdir}appendices/dev-env/eclipse/eclipse-100-project-support.png"]
+
+
+Then turn on Auto-Enhancement:
+
+image::{_imagesdir}appendices/dev-env/eclipse/eclipse-110-project-support.png[width="600px",link="{_imagesdir}appendices/dev-env/eclipse/eclipse-110-project-support.png"]
+
+
+=== Update the classpath
+
+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].
+
+
+Then, tell DataNucleus to use the project classpath:
+
+
+image::{_imagesdir}/appendices/dev-env/eclipse/eclipse-010-windows-preferences.png[width="750px",link="{_imagesdir}/appendices/dev-env/eclipse/eclipse-010-windows-preferences.png"]
+
+When the enhancer runs, it will print out to the console:
+
+image::{_imagesdir}/appendices/dev-env/eclipse/eclipse-120-console.png[width="500px",link="{_imagesdir}/appendices/dev-env/eclipse/eclipse-120-console.png"]
+
+
+
+=== Workaround for path limits (the DN plugin to use the persistence.xml)
+
+If running on Windows then the DataNucleus plugin is very likely to hit the Windows path limit.
+
+To fix this, we configure the enhancer to read from the `persistence.xml` file.
+
+As a prerequisite, first make sure that your domain object model has a `persistence.xml` file. Then specify the `persistence-unit` in the project properties:
+
+image::{_imagesdir}/appendices/dev-env/eclipse/eclipse-025-project-properties.png[width="750px",link="{_imagesdir}/appendices/dev-env/eclipse/eclipse-025-project-properties.png"]
+
+
+=== Workaround: If the enhancer fails
+
+On occasion it appears that Eclipse can attempt to run two instances of the DataNucleus enhancer. This is probably due to multiple Eclipse builders being defined; we've noticed multiple entries in the Eclipse's `Debug` view:
+
+
+image::{_imagesdir}/appendices/dev-env/eclipse/eclipse-210-enhancer-fails-duplicates.png[width="600px",link="{_imagesdir}/appendices/dev-env/eclipse/eclipse-210-enhancer-fails-duplicates.png"]
+
+
+At any rate, you'll know you've encountered this error if you see the following in the console:
+
+
+image::{_imagesdir}/appendices/dev-env/eclipse/eclipse-200-enhancer-fails-duplicates.png[width="600px",link="{_imagesdir}/appendices/dev-env/eclipse/eclipse-200-enhancer-fails-duplicates.png"]
+
+
+
+The best solution is to remove DataNucleus support and then to re-add it:
+
+
+image::{_imagesdir}/appendices/dev-env/eclipse/eclipse-220-enhancer-fails-duplicates.png[width="600px",link="{_imagesdir}/appendices/dev-env/eclipse/eclipse-220-enhancer-fails-duplicates.png"]
+
+
+If you consistently hit problems, then the final recourse is to disable the automatic enhancement and to remember to manually enhance your domain object model before each run.
+
+Not ideal, we know. Please feel free to contribute a better solution :-)
+
+
+
+
+== Running the App
+
+The simpleapp archetype automatically provides a `.launch` configurations in the `webapp` module. You can therefore very simply run the application by right-clicking on one of these files, and choosing "Run As…" or "Debug As…".
+
+
+[NOTE]
+====
+The screencast above shows this in action.
+====
+
+
+
+
+
+== Other domain projects.
+
+There is nothing to prevent you having multiple domain projects. You might want to do such that each domain project corresponds to a http://www.methodsandtools.com/archive/archive.php?id=97p2[DDD module], thus guaranteeing that there are no cyclic dependencies between your modules.
+
+If you do this, make sure that each project has its own `persistence.xml` file.
+
+And, remember also to configure Eclipse's DataNucleus plugin for these other domain projects.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_dg_intellij.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_dg_intellij.adoc b/adocs/documentation/src/main/asciidoc/guides/_dg_intellij.adoc
new file mode 100644
index 0000000..c17cc4e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_dg_intellij.adoc
@@ -0,0 +1,374 @@
+[[_dg_intellij]]
+= Setting up IntelliJ IDEA
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../../
+:_imagesdir: images/
+:toc: right
+
+
+This appendix describes how to install and setup IntelliJ, then how to import an application into IntelliJ and run it.
+
+
+[NOTE]
+====
+This document relates to IntelliJ Community Edition 14.1.1, with screenshots taken for Windows.
+====
+
+== Installing and Setting up
+
+This section covers installation and setup.
+
+=== Download and Install
+
+https://www.jetbrains.com/idea/download/[Download] latest version of IntelliJ Community Edition, and install:
+
+Start the wizard, click through the welcome page:
+
+.IntelliJ Installation Wizard - Welcome page
+image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/010-welcome-page.png[width="400px"]
+
+Choose the location to install the IDE:
+
+.IntelliJ Installation Wizard - Choose Location
+image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/020-choose-location.png[width="400px"]
+
+Adjust any installation options as you prefer:
+
+.IntelliJ Installation Wizard - Installation Options
+image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/030-installation-options.png[width="400px"]
+
+and the start menu:
+
+.IntelliJ Installation Wizard - Start Menu Folder
+image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/040-start-menu-folder.png[width="400px"]
+
+and finish up the wizard:
+
+.IntelliJ Installation Wizard - Completing the Wizard
+image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/050-completing.png[width="400px"]
+
+Later on we'll specify the Apache Isis/ASF code style settings, so for now select `I do not want to import settings`:
+
+.IntelliJ Installation Wizard - Import Settings
+image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/060-import-settings-or-not.png[width="400px"]
+
+Finally, if you are young and trendy, set the UI theme to Darcula:
+
+.IntelliJ Installation Wizard Set UI Theme
+image::{_imagesdir}appendices/dev-env/intellij-idea/010-installing/070-set-ui-theme.png[width="600px"]
+
+
+
+
+=== New Project
+
+In IntelliJ a project can contain multiple modules; these need not be physically located together. (If you are previously an Eclipse user, you can think of it as similar to an Eclipse workspace).
+
+Start off by creating a new project:
+
+.IntelliJ Create New Project
+image::{_imagesdir}appendices/dev-env/intellij-idea/020-create-new-project/010-new-project-create.png[width="400px"]
+
+We want to create a new *Java* project:
+
+.IntelliJ Create New Project - Create a Java project
+image::{_imagesdir}appendices/dev-env/intellij-idea/020-create-new-project/020-java-project-setup-jdk.png[width="600px"]
+
+We therefore need to specify the JDK.
+
+NOTE: at the time of writing Isis supports only Java 7; Java 8 is scheduled for support in Isis v1.9.0
+
+
+.IntelliJ Create New Java Project - Select the JDK
+image::{_imagesdir}appendices/dev-env/intellij-idea/020-create-new-project/030-java-project-select-jdk.png[width="300px"]
+
+Specify the directory containing the JDK:
+
+.IntelliJ Create New Project - Select the JDK location
+image::{_imagesdir}appendices/dev-env/intellij-idea/020-create-new-project/050-name-and-location.png[width="400px"]
+
+Finally allow IntelliJ to create the directory for the new project:
+
+.IntelliJ Create New Project
+image::{_imagesdir}appendices/dev-env/intellij-idea/020-create-new-project/060-create-dir.png[width="200px"]
+
+
+
+=== Import Settings
+
+Next we need to configure IntelliJ with ASF/Apache Isis' standard templates and coding conventions. These are bundled as the `settings.jar` JAR file link:resources/appendices/dev-env/intellij/isis-settings.jar[download from the Isis website]).
+
+Import using: `File > Import Settings`, and specify the directory that you have downloaded the file to:
+
+.IntelliJ Import Settings - Specify JAR file
+image::{_imagesdir}appendices/dev-env/intellij-idea/030-import-settings/010-settings-import-jar.png[width="400px"]
+
+Select all the (two) categories of settings available in the JAR file:
+
+.IntelliJ Import Settings - Select all categories
+image::{_imagesdir}appendices/dev-env/intellij-idea/030-import-settings/020-select-all.png[width="300px"]
+
+And then restart:
+
+.IntelliJ Import Settings - Restart
+image::{_imagesdir}appendices/dev-env/intellij-idea/030-import-settings/030-restart.png[width="200px"]
+
+
+
+=== Other Settings
+
+There are also some other miscellaneous settings that we recommend that you adjust (though these are not critical).
+
+First, specify an up-to-date Maven installation, using `File > Settings` (or `IntelliJ > Preferences` if on MacOS):
+
+.IntelliJ Other Settings - Maven Installation
+image::{_imagesdir}appendices/dev-env/intellij-idea/040-other-settings/010-maven-installation.png[width="600px"]
+
+Still on the Maven settings page, configure as follows:
+
+.IntelliJ Other Settings - Maven Configuration
+image::{_imagesdir}appendices/dev-env/intellij-idea/040-other-settings/020-maven-configuration.png[width="600px"]
+
+On the compiler settings page, ensure that `build automatically` is enabled (and optionally `compile independent modules in parallel`):
+
+.IntelliJ Other Settings - Compiler Settings
+image::{_imagesdir}appendices/dev-env/intellij-idea/040-other-settings/030-build-automatically.png[width="600px"]
+
+On the auto import page, check the `optimize imports on the fly` and `add unambiguous imports on the fly`
+
+.IntelliJ Other Settings - Auto Import
+image::{_imagesdir}appendices/dev-env/intellij-idea/040-other-settings/040-auto-import.png[width="600px"]
+
+
+
+=== Plugins
+
+You might also want to set up some additional plugins, using `File > Settings > Plugins` (or equivalently `File > Other Settings > Configure Plugins`).
+
+Recommended are:
+* link:https://plugins.jetbrains.com/plugin/7179?pr=idea[Maven Helper] plugin
++
+Provides better visualization of dependency trees (similar to Eclipse)
+* link:https://github.com/asciidoctor/asciidoctor-intellij-plugin[AsciiDoctor] plugin
++
+Useful if you are doing any authoring of documents.
+
+Some others you might like to explore are:
+
+.IntelliJ Plugins
+image::{_imagesdir}appendices/dev-env/intellij-idea/050-some-plugins/020-some-plugins-confirmation.png[width="400px"]
+
+
+
+
+== Importing and Managing Maven Modules
+
+Let's load in some actual code! We do this by importing the Maven modules.
+
+First up, open up the Maven tool window (`View > Tool Windows > Maven Projects`). You can then use the 'plus' button to add Maven modules. In the screenshot you can see we've loaded in Isis core; the modules are listed in the _Maven Projects_ window and corresponding (IntelliJ) modules are shown in the _Projects_ window:
+
+.IntelliJ Maven Module Management - Importing Maven modules
+image::{_imagesdir}appendices/dev-env/intellij-idea/100-maven-module-mgmt/010-maven-modules-view.png[width="730px"]
+
+We can then import another module (from some other directory). For example, here we are importing the Isis Addons' todoapp example:
+
+.IntelliJ Maven Module Management - Importing another Module
+image::{_imagesdir}appendices/dev-env/intellij-idea/100-maven-module-mgmt/020-adding-another-module.png[width="400px"]
+
+You should then see the new Maven module loaded in the _Projects_ window and also the _Maven Projects_ window:
+
+.IntelliJ Maven Module Management -
+image::{_imagesdir}appendices/dev-env/intellij-idea/100-maven-module-mgmt/030-other-module-added.png[width="730px"]
+
+If any dependencies are already loaded in the project, then IntelliJ will automatically update the CLASSPATH to resolve to locally held modules (rather from `.m2/repository` folder). So, for example (assuming that the `<version>` is correct, of course), the Isis todoapp will have local dependencies on the Isis core.
+
+You can press F4 (or use `File > Project Structure`) to see the resolved classpath for any of the modules loaded into the project.
+
+If you want to focus on one set of code (eg the Isis todoapp but not Isis core) then you _could_ remove the module; but better is to ignore those modules. This will remove from the the _Projects_ window but keep them available in the _Maven Projects_ window for when you next want to work on them:
+
+.IntelliJ Maven Module Management - Ignoring Modules
+image::{_imagesdir}appendices/dev-env/intellij-idea/100-maven-module-mgmt/040-ignoring-modules.png[width="730px"]
+
+Confirm that it's ok to ignore these modules:
+
+.IntelliJ Maven Module Management - Ignoring Modules (ctd)
+image::{_imagesdir}appendices/dev-env/intellij-idea/100-maven-module-mgmt/050-ignoring-modules-2.png[width="300px"]
+
+All being well you should see that the _Projects_ window now only contains the code you are working on. Its classpath dependencies will be adjusted (eg to resolve to Isis core from `.m2/repository`):
+
+.IntelliJ Maven Module Management - Updated Projects Window
+image::{_imagesdir}appendices/dev-env/intellij-idea/100-maven-module-mgmt/060-ignored-modules.png[width="730px"]
+
+
+
+== Running
+
+Let's see how to run both the app and the tests.
+
+=== Running the App
+
+Once you've imported your Isis application, we should run it. We do this by creating a Run configuration, using `Run > Edit Configurations`.
+
+Set up the details as follows:
+
+.IntelliJ Running the App - Run Configuration
+image::{_imagesdir}appendices/dev-env/intellij-idea/110-running-the-app/010-run-configuration.png[width="600px"]
+
+We specify the `Main class` to be `org.apache.isis.WebServer`; this is a wrapper around Jetty. It's possible to pass program arguments to this (eg to automatically install fixtures), but for now leave this blank.
+
+Also note that `Use classpath of module` is the webapp module for your app, and that the `working directory` is `$MODULE_DIR$`.
+
+Next, and most importantly, configure the DataNucleus enhancer to run for your `dom` goal. This can be done by defining a Maven goal to run before the app:
+
+.IntelliJ Running the App - Datanucleus Enhancer Goal
+image::{_imagesdir}appendices/dev-env/intellij-idea/110-running-the-app/020-datanucleus-enhancer-goal.png[width="400px"]
+
+The `-o` flag in the goal means run off-line; this will run faster.
+
+WARNING: if you forget to set up the enhancer goal, or don't run it on the correct (dom) module, then you will get all sorts of errors when you startup. These usually manifest themselves as class cast exception in DataNucleus.
+
+You should now be able to run the app using `Run > Run Configuration`. The same configuration can also be used to debug the app if you so need.
+
+
+=== Running the Unit Tests
+
+The easiest way to run the unit tests is just to right click on the `dom` module in the _Project Window_, and choose run unit tests. Hopefully your tests will pass (!).
+
+.IntelliJ Running the App - Unit Tests Run Configuration
+image::{_imagesdir}appendices/dev-env/intellij-idea/110-running-the-app/030-running-unit-tests.png[width="600px"]
+
+As a side-effect, this will create a run configuration, very similar to the one we manually created for the main app:
+
+.IntelliJ Running the App - Unit Tests Run Configuration
+image::{_imagesdir}appendices/dev-env/intellij-idea/110-running-the-app/040-running-unit-tests-run-configuration.png[width="600px"]
+
+Thereafter, you should run units by selecting this configuration (if you use the right click approach you'll end up with lots of run configurations, all similar).
+
+=== Running the Integration Tests
+
+Integration tests can be run in the same way as unit tests, however the `dom` module must also have been enhanced.
+
+One approach is to initially run the tests use the right click on the `integtests` module; the tests will fail because the code won't have been enhanced, but we can then go and update the run configuration to run the datanucleus enhancer goal (same as when running the application):
+
+.IntelliJ Running the App - Integration Tests Run Configuration
+image::{_imagesdir}appendices/dev-env/intellij-idea/110-running-the-app/050-running-integration-tests-run-configuration.png[width="600px"]
+
+
+
+
+== Hints and Tips
+
+=== Keyboard Shortcuts Cheat Sheets
+
+You can download 1-page PDFs cheat sheets for IntelliJ's keyboard shortcuts:
+* for link:https://www.jetbrains.com/idea/docs/IntelliJIDEA_ReferenceCard.pdf[Windows]
+* for MacOS:https://www.jetbrains.com/idea/docs/IntelliJIDEA_ReferenceCard_Mac.pdf[MacOS]
+
+Probably the most important shortcut on them is for `Find Action`:
+- `ctrl-shift-A` on Windows
+- `cmd-shift-A` on MacOS.
+
+This will let you search for any action just by typing its name.
+
+### Switching between Tool Windows and Editors
+
+The Tool Windows are the views around the editor (to left, bottom and right). It's possible to move these around to your preferred locations.
+
+* Use `alt-1` through `alt-9` (or `cmd-1` through `alt-9`) to select the tool windows
+** Press it twice and the tool window will hide itself; so can use to toggle
+* If in the _Project Window_ (say) and hit enter on a file, then it will be shown in the editor, but (conveniently) the focus remains in the tool window. To switch to the editor, just press `Esc`.
+** If in the _Terminal Window_, you'll need to press `Shift-Esc`.
+* If on the editor and want to locate the file in (say) the _Project Window_, use `alt-F1`.
+* To change the size of any tool window, use `ctrl-shift-arrow`
+
+Using these shortcuts you can easily toggle between the tool windows and the editor, without using the mouse. Peachy!
+
+=== Navigating Around
+
+For all of the following, you don't need to type every letter, typing "ab" will actually search for ".*a.*b.*".
+
+* to open classes or files or methods that you know the name of:
+** `ctrl-N` to open class
+** `ctrl-shift-N` to open a file
+** (bit fiddly this) `ctrl-shift-alt-N` to search for any symbol.
+* open up dialog of recent files: `ctrl-E`
+* search for any file: `shift-shift`
+
+Navigating around:
+* find callers of a method (the call hierarchy): `ctrl-alt-H`
+* find subclasses or overrides: `ctrl-alt-B`
+* find superclasses/interface/declaration: `ctrl-B`
+
+Viewing the structure (ie outline) of a class
+* `ctrl-F12` will pop-up a dialog showing all members
+** hit `ctrl-F12` again to also see inherited members
+
+
+=== Editing
+
+* Extend selection using `ctrl-W`
+** and contract it down again using `ctrl-shift-W`
+* to duplicate a line, it's `ctrl-D`
+** if you have some text selected (or even some lines), it'll actually duplicate the entire selection
+* to delete a line, it's `ctrl-X`
+* to move a line up or down: `shift-alt-up` and `shift-alt-down`
+** if you have selected several lines, it'll move them all togethe
+* `ctrl-shift-J` can be handy for joining lines together
+** just hit enter to split them apart (even in string quotes; IntelliJ will "do the right thing")
+
+### Intentions and Code Completion
+
+Massively useful is the "Intentions" popup; IntelliJ tries to guess what you might want to do. You can activate this using`alt-enter`, whenever you see a lightbulb/tooltip in the margin of the current line.
+
+Code completion usually happens whenever you type '.'. You can also use `ctrl-space` to bring these up.
+
+In certain circumstances (eg in methods0) you can also type `ctrl-shift-space` to get a smart list of methods etc that you might want to call. Can be useful.
+
+Last, when invoking a method, use `ctrl-P` to see the parameter types.
+
+
+=== Refactoring
+
+Loads of good stuff on the `Refactor` menu; most used are:
+
+* Rename (`shift-F6`)
+* Extract
+** method: `ctrl-alt-M`
+** variable: `ctrl-alt-V`
+* Inline method/variable: `ctrl-alt-N`
+* Change signature
+
+If you can't remember all those shortcuts, just use `ctrl-shift-alt-T` (might want to rebind that to something else!) and get a context-sensitive list of refactorings available for the currently selected object
+
+
+=== Troubleshooting
+
+When a Maven module is imported, IntelliJ generates its own project files (suffix `.ipr`), and the application is actually built from that.
+
+Occasionally these don't keep in sync (even if auto-import of Maven modules has been enabled).
+
+To fix the issue, try:
+* reimport module
+* rebuild selected modules/entire project
+* remove and then re-add the project
+* restart, invalidating caches
+* hit StackOverflow (!)
+
+One thing worth knowing; IntelliJ actively scans the filesystem all the time. It's therefore (almost always) fine to build the app from the Maven command line; IntelliJ will detect the changes and keep in sync. If you want to force that, use `File > Synchronize`, `ctrl-alt-Y`.
+
+
+
+
+== Advanced
+
+In this section are a couple of options that will reduce the length of the change code/build/deploy/review feedback loop.
+
+
+=== Setting up Dynamic Reloading
+
+IMPORTANT: TODO - see link:http://blog.jetbrains.com/idea/2013/07/get-true-hot-swap-in-java-with-dcevm-and-intellij-idea/[IntelliJ blog].
+
+
+=== Setting up JRebel
+
+IMPORTANT: TODO
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations.adoc
new file mode 100644
index 0000000..10bbaf6
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations.adoc
@@ -0,0 +1,63 @@
+[[_rg-annotations]]
+= Annotations
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+Apache Isis uses annotations to provide additional metadata about the domain objects.
+
+To give just a few examples:
+
+* 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)`
+* if a class is a domain service and should be automatically instantiated as a singleton, then it can be annotated using `@DomainService`
+* if an action is idempotent, then it can be annotated using `@Action(semantics=SemanticsOf.IDEMPOTENT)`.
+* if an action parameter is optional, it can be annotated using `@Parameter(optionality=Optionality.OPTIONAL)`
+
+Some annotations act as UI hints, for example:
+
+* if a collection should be rendered "open" rather than collapsed, it can be annotated using `@CollectionLayout(render=RenderType.EAGERLY)`
+* 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 chapter documents all the annotations currently supported by Isis. It also identifies a number of annotations that are now deprecated, and indicates their replacement.
+
+
+include::_rg_annotations_aaa.adoc[leveloffset=+1]
+
+include::_rg_annotations_manpage-Action.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-ActionLayout.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-Collection.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-Collectionlayout.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-Column.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-Digits.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-Discriminator.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-DomainObject.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-DomainObjectLayout.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-DomainService.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-DomainServiceLayout.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-Facets.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-HomePage.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-Inject.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-MemberGroupLayout.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-MemberOrder.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-NotPersistent.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-MinLength.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-Parameter.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-ParameterLayout.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-PersistenceCapable.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-PostConstruct.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-PreDestroy.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-PrimaryKey.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-Programmatic.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-Property.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-PropertyLayout.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-RequestScoped.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-Title.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-Viewmodel.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-ViewmodelLayout.adoc[leveloffset=+1]
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa.adoc
new file mode 100644
index 0000000..42642bf
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa.adoc
@@ -0,0 +1,17 @@
+[[_rg_annotations_aaa]]
+= Summary
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 summarizes the various annotations supported by Isis. They break out into five categories.
+
+include::_rg_annotations_aaa_main.adoc[leveloffset=+1]
+include::_rg_annotations_aaa_other.adoc[leveloffset=+1]
+include::_rg_annotations_aaa_jdo.adoc[leveloffset=+1]
+include::_rg_annotations_aaa_jee.adoc[leveloffset=+1]
+include::_rg_annotations_aaa_deprecated.adoc[leveloffset=+1]
+include::_rg_annotations_aaa_partial.adoc[leveloffset=+1]
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa_deprecated.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa_deprecated.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa_deprecated.adoc
new file mode 100644
index 0000000..d2f14d1
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa_deprecated.adoc
@@ -0,0 +1,342 @@
+[[_rg_annotations_aaa_deprecated]]
+= Deprecated Annotations
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+As Apache Isis has evolved and grown, we found ourselves adding more and more annotations; but most of these related to either an object type (entity, view model, service) or an object member (property, collection, action). Over time it became harder and harder for end programmers to discover these new features.
+
+Accordingly, (in v1.8.0) we decided to unify the semantics into the main (core) annotations listed xref:rg.adoc#_rg_annotations_aaa_main[above].
+
+The annotations listed in the table below are still supported by Apache Isis, but will be retired in Isis v2.0.
+
+
+.Deprecated Annotations
+[cols="2,4a,3a,1,1", options="header"]
+|===
+|Annotation
+|Purpose
+|Use instead
+|Layer
+|xref:rg.adoc#_rg_object-layout_dynamic[Dynamic layout]?
+
+|`@ActionOrder`
+|Order of buttons and menu items representing actions.
+|xref:rg.adoc#_rg_annotations_manpage-MemberOrder[`@MemberOrder`]
+|UI
+|Yes
+
+|`@ActionInteraction`
+|Enable subscribers on the Event Bus Service to either veto, validate or take further steps before/after an action has been invoked.
+|xref:rg.adoc#_rg_annotations_manpage-Action_domainEvent[`@Action#domainEvent()`]
+|Domain
+|
+
+|`@ActionSemantics`
+|Query-only, idempotent or non-idempotent.
+|xref:rg.adoc#_rg_annotations_manpage-Action_semantics[`@Action#semantics()`]
+|Domain
+|
+
+|`@Audited`
+|Audit changes to an object.
+|xref:rg.adoc#_rg_annotations_manpage-DomainObject_auditing[`@DomainObject#` +
+`auditing()`]
+|Domain
+|
+
+|`@AutoComplete`
+|Repository method to search for entities
+|xref:rg.adoc#_rg_annotations_manpage-DomainObject_autoCompleteRepository[`@DomainObject` +
+`#autoCompleteRepository()`]
+|UI/Domain
+|
+
+|`@Bookmarkable`
+|Whether (and how) to create a bookmark for visited object.
+|xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_bookmarking[`@DomainObjectLayout` +
+`#bookmarking()`]
+|UI
+|
+
+|`@Bounded`
+|Bounded (and limited) number of instances of an entity type, translates into a drop-down for any property of that type.
+|xref:rg.adoc#_rg_annotations_manpage-DomainObject_bounded[`@DomainObject#bounded()`]
+|Domain
+|
+
+|`@Bulk`
+|Indicates an action is a bulk action, can be applied to multiple instances.
+|xref:rg.adoc#_rg_annotations_manpage-Action_invokeOn[`@Action#invokeOn()`]
+|UI, Domain
+|
+
+|`@CollectionInteraction`
+|Enable subscribers on the Event Bus Service to either veto, validate or take further steps before/after a collection has been added to or removed from.
+|xref:rg.adoc#_rg_annotations_manpage-Collection_domainEvent[`@Collection#domainEvent()`]
+|Domain
+|
+
+|`@Command`
+|Action invocation should be reified as a command object, optionally persistable for profiling and enhanced auditing, and background/async support.
+|xref:rg.adoc#_rg_annotations_manpage-Action_command[`@Action#command()`]
+|Domain
+|
+
+|`@CssClass`
+|Allow visual representation of individual objects or object members layout to be customized by application-specific CSS.
+|`#cssClass()` attribute for: xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_cssClass[`@DomainObjectLayout`], xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_cssClass[`@PropertyLayout`], xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_cssClass[`@CollectionLayout`], xref:rg.adoc#_rg_annotations_manpage-ActionLayout_cssClass[`@ActionLayout`] and xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_cssClass[`@ParameterLayout`]
+|UI
+|Yes
+
+|`@CssClassFa`
+|So that font awesome icons can be applied to action buttons/menu items and optionally as an object icon.
+|`cssClassFa()` attribute for: xref:rg.adoc#_rg_annotations_manpage-ActionLayout_cssClassFa[`@ActionLayout`], xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_cssClassFa[`DomainObjectLayout`] and xref:rg.adoc#_rg_annotations_manpage-ViewModelLayout_cssClassFa[`ViewModelLayout`]
+|UI
+|Yes
+
+|`@Debug`
+|Action only invokable in debug mode.
+|Not supported by either the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] or the xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer]; use prototype mode instead (xref:rg.adoc#_rg_annotations_manpage-Action_restrictTo[`@Action#restrictTo()`])
+|UI
+|
+
+|`@DescribedAs`
+|Provide a longer description/tool-tip of an object or object member.
+|`#describedAs()` attribute for xref:rg.adoc#_rg_annotations_manpage-DomainObject_describedAs[`@DomainObjectLayout`], xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_describedAs[`@PropertyLayout`], xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_describedAs[`@CollectionLayout`], xref:rg.adoc#_rg_annotations_manpage-ActionLayout_describedAs[`@ActionLayout`] and xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_describedAs[`@ParameterLayout`]
+|UI
+|Yes
+
+|`@Disabled`
+|Object property cannot be edited, an object collection cannot be added to/removed from, or an object action cannot be invoked.
+|`#editing()` attribute for xref:rg.adoc#_rg_annotations_manpage-Property_editing[`@Property`], xref:rg.adoc#_rg_annotations_manpage-Collection_editing[`@Collection`] and xref:rg.adoc#_rg_annotations_manpage-DomainObject_editing[`@DomainObject`]
+|UI, Domain
+|Yes
+
+|`@Exploration`
+|Action available in special 'exploration' mode.
+|Not supported by either the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] or the xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer]; use prototype mode instead (xref:rg.adoc#_rg_annotations_manpage-Action_restrictTo[`@Action#restrictTo()`])
+|UI
+|
+
+|`@FieldOrder`
+|Order of properties and collections.
+|xref:rg.adoc#_rg_annotations_manpage-MemberOrder[`@MemberOrder`]
+|UI
+|Yes
+
+|`@Hidden`
+|Object member is not visible, or on domain service (to indicate that none of its actions are visible).
+|For domain object members, use `#hidden()` attribute of xref:rg.adoc#_rg_annotations_manpage-Action_hidden[`Action`], xref:rg.adoc#_rg_annotations_manpage-Property_hidden[`Property`] or xref:rg.adoc#_rg_annotations_manpage-Collection_hidden[`Collection`]. +
+For domain service, use xref:rg.adoc#_rg_annotations_manpage-DomainService_nature[`@DomainService(` +
+`nature=DOMAIN)`]
+|UI, Domain
+|Yes
+
+|`@Idempotent`
+|Whether an action is idempotent (can be invoked multiple times with same post-condition).
+|xref:rg.adoc#_rg_annotations_manpage-Action_semantics[`@Action#semantics`]
+|Domain
+|
+
+|`@Ignore`
+|Exclude this method from the metamodel.
+|xref:rg.adoc#_rg_annotations_manpage-Programmatic[`@Programmatic`]. +
+
+`@Ignore` was deprecated because it can easily clash with `@org.junit.Ignore`.
+|Domain
+|
+
+|`@Immutable`
+|An object's state cannot be changed (properties cannot be edited, collections cannot be added to or removed from). Actions can still be invoked.
+|xref:rg.adoc#_rg_annotations_manpage-DomainObject_editing[`@DomainObject#editing()`]
+|Domain
+|
+
+|`@Mask`
+|How to parse/render values (never properly supported)
+|(None)
+|UI/domain
+|
+
+|`@MaxLength`
+|Maximum length of a property value (strings).
+|`#maxLength()` attribute for xref:rg.adoc#_rg_annotations_manpage-Property_maxLength[`@Property`] or xref:rg.adoc#_rg_annotations_manpage-Parameter_maxLength[`@Parameter`]
+|Domain
+|
+
+|`@MemberGroups`
+|Layout of properties and collections of a domain object or view model object.
+|xref:rg.adoc#_rg_annotations_manpage-MemberGroupLayout[`@MemberGroupLayout`]
+|UI
+|Yes
+
+|`@MultiLine`
+|Render string property over multiple lines (a textarea rather than a textbox).
+|`#multiLine()` attribute for xref:rg.adoc#_rg_annotations_manpage-Property_multiLine[`@Property`] or xref:rg.adoc#_rg_annotations_manpage-Parameter_multiLine[`@Parameter`]
+|UI
+|Yes
+
+|`@MustSatisfy`
+|Specify arbitrary specification constraints on a property or action parameter.
+|`#mustSatisfy()` attribute for xref:rg.adoc#_rg_annotations_manpage-Property_mustSatisfy[`@Property`] or xref:rg.adoc#_rg_annotations_manpage-Parameter_mustSatisfy[`@Parameter`]
+|Domain
+|
+
+|`@Named`
+|Override name inferred from class. Required for parameter names (prior to Java8).
+|`#named()` attribute for xref:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_named[`@DomainServiceLayout`], xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_named[`@DomainObjectLayout`], xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_named[`@PropertyLayout`], xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_named[`@CollectionLayout`], xref:rg.adoc#_rg_annotations_manpage-ActionLayout_named[`@ActionLayout`] and xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_named[`@ParameterLayout`]
+|UI
+|Yes
+
+|`@NotContributed`
+|Indicates that a domain service action is not rendered as an action on the (entity) types of its parameters. For 1-arg query-only actions, controls whether the domain service action is rendered as a property or collection on the entity type of its parameter.
+|Use xref:rg.adoc#_rg_annotations_manpage-DomainService_nature[`@DomainService#nature()`] to specify whether any of the actions in a domain service should appear in the menu bars (applies at type level, not action level).
+For individual actions, use xref:rg.adoc#_rg_annotations_manpage-ActionLayout_contributedAs[`@ActionLayout#` +
+`contributedAs()`] to specify whether any individual action should be contributed only as an action or as an association (property or collection).
+|UI
+|
+
+|`@NotInServiceMenu`
+|Indicates that a domain service should not be rendered in the application menu (at top of page in Wicket viewer).
+|xref:rg.adoc#_rg_annotations_manpage-DomainService_nature[`@DomainService#nature()`] to signify that none of the actions in a domain service should appear in the menu bars
+|UI
+|
+
+|`@NotPersisted`
+|Indicates that an object property is not persisted (meaning it is excluded from view model mementos, and should not be audited).
+|`#notPersisted()` attribute of xref:rg.adoc#_rg_annotations_manpage-Property_notPersisted[`@Property`] and xref:rg.adoc#_rg_annotations_manpage-Collection_notPersisted[`@Collection`]
+|Domain, Persistence
+|
+
+|`@ObjectType`
+|For constructing the external identifier (URI) of an entity instance (part of its URL in both Wicket viewer and Restful Objects viewer). Also part of the toString representation of bookmarks, if using the Bookmark Service
+|xref:rg.adoc#_rg_annotations_manpage-DomainObject_objectType[`@DomainObject#objectType()`]
+|Domain
+|
+
+|`@Optional`
+|Specifies that a property or action parameter is not mandatory.
+|`#optionality()` attribute for xref:rg.adoc#_rg_annotations_manpage-Property_optionality[`@Property`] or xref:rg.adoc#_rg_annotations_manpage-Parameter_optionality[`@Parameter`]
+|Domain
+|
+
+|`@Paged`
+|Number of instances to display in tables representing (standalone or parented) collections.
+|`#paged()` attribute for xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_paged[`@DomainObjectLayout`] or xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_paged[`@CollectionLayout`]
+|UI
+|Yes
+
+|`@Plural`
+|For the irregular plural form of an entity type.
+|xref:rg.adoc#_rg_annotations_manpage-DomainObject_plural[`@DomainObjectLayout` +
+`#plural()`]
+|UI
+|
+
+|`@PostsAction` +
+`InvokedEvent`
+|Post a domain event to the Event Bus Service indicating that an action has been invoked.
+|xref:rg.adoc#_rg_annotations_manpage-Action_domainEvent[`@Action#domainEvent()`]
+|Domain
+|
+
+|`@PostsCollection` +
+`AddedToEvent`
+|Post a domain event to the Event Bus Service indicating that an element has been added to a collection.
+|xref:rg.adoc#_rg_annotations_manpage-Collection_domainEvent[`@Collection#domainEvent()`]
+|Domain
+|
+
+|`@PostsCollection` +
+`RemovedFromEvent`
+|Post a domain event to the Event Bus Service indicating that an element has been removed from a collection.
+|xref:rg.adoc#_rg_annotations_manpage-Collection_domainEvent[`@Collection#domainEvent()`]
+|Domain
+|
+
+|`@PostsProperty` +
+`ChangedEvent`
+|Post a domain event to the Event Bus Service indicating that the value of a property has changed.
+|xref:rg.adoc#_rg_annotations_manpage-Property_domainEvent[`@Property#domainEvent()`]
+|Domain
+|
+
+|`@PropertyInteraction`
+|Enable subscribers on the Event Bus Service to either veto, validate or take further steps before/after a property has been modified or cleared.
+|xref:rg.adoc#_rg_annotations_manpage-Property_domainEvent[`@Property#domainEvent()`]
+|Domain
+|
+
+|`@Prototype`
+|Indicates that an action should only be visible in 'prototype' mode.
+|xref:rg.adoc#_rg_annotations_manpage-Action_restrictTo[`@Action#restrictTo()`]
+|UI
+|Yes
+
+|`@PublishedAction`
+|Action invocation should be serialized and published by configured PublishingService (if any), eg to other systems.
+|xref:rg.adoc#_rg_annotations_manpage-Action_publishing[`@Action#publishing()`]
+|Domain
+|
+
+|`@PublishedObject`
+|Change to object should be serialized and published by configured PublishingService (if any), eg to other systems.
+|xref:rg.adoc#_rg_annotations_manpage-DomainObject_publishing[`@DomainObject#publishing()`]
+|Domain
+|
+
+|`@QueryOnly`
+|Whether an action is query-only (has no side-effects).
+|xref:rg.adoc#_rg_annotations_manpage-Action_semantics[`@Action#semantics()`]
+|Domain
+|
+
+|`@RegEx`
+|Validate change to value of string property.
+|`#regexPattern()` for xref:rg.adoc#_rg_annotations_manpage-Property_regexPattern[`@Property`] or xref:rg.adoc#_rg_annotations_manpage-Property_regexPattern[`@Parameter`].
+|Domain
+|
+
+|`@Render`
+|Eagerly (or lazily) render the contents of a collection.
+|xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_render[`@CollectionLayout` +
+`#render()`]
+|UI
+|Yes
+
+|`@RenderedAsDayBefore`
+|Render dates as the day before; ie store [a,b) internally but render [a,b-1]) to end-user.
+|`#renderedAsDayBefore()` attribute for xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_renderedAsDayBefore[`@PropertyLayout`] and xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_renderedAsDayBefore[`@ParameterLayout`].
+|UI
+|
+
+|`@Resolve`
+|Eagerly (or lazily) render the contents of a collection (same as `@Render)`
+|xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_render[`@CollectionLayout` +
+`#render()`]
+|UI
+|Yes
+
+|`@SortedBy`
+|Display instances in collections in the order determined by the provided Comparator.
+|xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_sortedBy[`@CollectionLayout` +
+`#sortedBy()`]
+|UI
+|Yes
+
+|`@TypeOf`
+|The type of entity stored within a collection, or as the result of invoking an action, if cannot be otherwise inferred, eg from generics.
+|`#typeOf()` attribute for xref:rg.adoc#_rg_annotations_manpage-Collection_typeOf[`@Collection`] and xref:rg.adoc#_rg_annotations_manpage-Action_typeOf[`@Action`]
+|Domain
+|
+
+|`@TypicalLength`
+|The typical length of a string property, eg to determine a sensible length for a textbox.
+|`#typicalLength()` attribute for xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_typicalLength[`@PropertyLayout`] and xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_typicalLength[`@ParameterLayout`]
+|UI
+|Yes
+
+|===
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa_jdo.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa_jdo.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa_jdo.adoc
new file mode 100644
index 0000000..5a0606f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa_jdo.adoc
@@ -0,0 +1,113 @@
+[[_rg_annotations_aaa_jee]]
+= JDO Annotations
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+Apache Isis uses JDO/DataNucleus as its ORM, and infers some of its own metadata from the JDO annotations.
+
+[WARNING]
+====
+Isis (currently) builds up metadata by parsing the JDO annotations from source, _not_ by querying the JDO metamodel. The upshot is that, for the annotations documented here at least, your domain entities must use JDO annotations rather than XML.
+
+Furthermore, note that although JDO (the property-related) annotations to be placed on either the field or on the getter, Isis requires that annotations are placed on the getter.
+====
+
+The table below lists the JDO annotations currently recognized by Isis.
+
+
+.JDO Annotations
+[cols="2,4a,1,1", options="header"]
+|===
+|Annotation
+|Purpose
+|Layer
+|Applies to
+
+
+|xref:rg.adoc#_rg_annotations_manpage-Column[`@javax.jdo.annotations.` +
+`Column`]
+|Used to determine whether a property is mandatory or optional. For `String` and `BigDecimal` properties, used to determine length/precision/scale.
+
+|Domain / persistence
+|Property
+
+
+|xref:rg.adoc#_rg_annotations_manpage-Discriminator[`@javax.jdo.annotations.` +
+`Discriminator`]
+|Override for the object type, as used in `Bookmark`s, URLs for xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer] and elsewhere. +
+
+Note that the discriminator overrides the object type that may otherwise be inferred from the xref:rg.adoc#_rg_annotations_manpage-PersistenceCapable[`@PersistenceCapable`] annotation.
+|Domain / persistence
+|Class
+
+
+|xref:rg.adoc#_rg_annotations_manpage-NotPersistent[`@javax.jdo.annotations.` +
+`NotPersistent`]
+|Used to determine whether to enforce or skip some xref:ug.adoc#_ug_extending_programming-model_custom-validator[metamodel validation] for `@Column` versus equivalent Isis annotations.
+
+|Domain / persistence
+|Property
+
+
+
+|xref:rg.adoc#_rg_annotations_manpage-PersistenceCapable[`@javax.jdo.annotations.` +
+`PersistenceCapable`]
+|Used to build Isis' own internal identifier for objects. +
+
+If the `schema()` attribute is specified (and if xref:rg.adoc#_rg_annotations_manpage-Discriminator[`@Discriminator`] _hasn't_ been specified), is also used to derive the object type, as used in `Bookmark`s, URLs for xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer] and elsewhere.
+
+|Domain / persistence
+|Class
+
+
+|xref:rg.adoc#_rg_annotations_manpage-PrimaryKey[`@javax.jdo.annotations.` +
+`PrimaryKey`]
+|Used to ensure Isis does not overwrite application-defined primary keys, and to ensure is read-only in the UI.
+
+|Domain / persistence
+|Property
+
+
+
+|===
+
+
+
+Isis also parses the following JDO annotations, but the metadata is currently unused.
+
+.JDO Annotations (unused within Isis)
+[cols="2,4a,1,1", options="header"]
+|===
+|Annotation
+|Purpose
+|Layer
+|Applies to
+
+
+|`@javax.jdo.annotations.` +
+`DataStoreIdentity`
+|Unused
+|Persistence
+|Class
+
+
+|`@javax.jdo.annotations.` +
+`EmbeddedOnly`
+|Unused
+|Persistence
+|Class
+
+
+|`@javax.jdo.annotations.` +
+`Query`
+|Unused
+|Persistence
+|Class
+
+
+|===
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa_jee.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa_jee.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa_jee.adoc
new file mode 100644
index 0000000..2d7c608
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa_jee.adoc
@@ -0,0 +1,59 @@
+[[_rg_annotations_aaa_jee]]
+= Java EE Annotations
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+While Apache Isis does, as of today, define a good number of its own annotations, the policy is to reuse standard Java/JEE annotations wherever they exist or are added to the Java platform.
+
+The table below lists the JEE annotations currently recognized. Expect to see more added in future releases of Isis.
+
+
+.Java EE Annotations
+[cols="2,4a,1,1", options="header"]
+|===
+|Annotation
+|Purpose
+|Layer
+|xref:rg.adoc#_rg_object-layout_dynamic[Dynamic layout]?
+
+|xref:rg.adoc#_rg_annotations_manpage-Digits[`@javax.validation.` +
+`constraints.` +
+`Digits`]
+|Precision/scale for BigDecimal values.
+|Domain
+|
+
+|xref:rg.adoc#_rg_annotations_manpage-Inject[`@javax.inject.` +
+`Inject`]
+|Inject domain service into a domain object (entity or view model) or another domain service.
+|Domain
+|
+
+|xref:rg.adoc#_rg_annotations_manpage-PostConstruct[`@javax.annotations.` +
+`PostConstruct`]
+|Callback for domain services (either singleton or xref:rg.adoc#_rg_annotations_manpage-RequestScoped[request-scoped]) to initialize themselves once instantiated.
+
+|Domain
+|
+
+|xref:rg.adoc#_rg_annotations_manpage-PreDestroy[`@javax.annotations.` +
+`PreDestroy`]
+|Callback for domain services (either singleton or xref:rg.adoc#_rg_annotations_manpage-RequestScoped[request-scoped]) to clean up resources prior to destruction.
+
+|Domain
+|
+
+|xref:rg.adoc#_rg_annotations_manpage-RequestScoped[`@javax.enterprise.` +
+`context.` +
+`RequestScoped`]
+|Specify that a domain service has request-scope (rather than a singleton).
+|Domain
+|
+
+
+|===
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa_main.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa_main.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa_main.adoc
new file mode 100644
index 0000000..55197ec
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa_main.adoc
@@ -0,0 +1,103 @@
+[[_rg_annotations_aaa_main]]
+= Core annotations
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+In Apache Isis every domain object is either a domain entity, a view model or a domain service. And each of these are made up of properties, collections and actions (domain services only have actions).
+
+For each of these domain types and members there are two annotations. One covers the semantics intrinsic to the domain (eg whether an action parameter is optional or not), then other (suffix `...Layout`) captures semantics relating to the UI/presentation layer.
+
+[TIP]
+====
+Most UI semantics can also be specified using xref:rg.adoc#_rg_object-layout_dynamic[dynamic object layout].
+====
+
+
+The table below summarizes these most commonly used annotations in Isis.
+
+
+.Core annotations for domain objects, services and members (as of 1.8.0)
+[cols="2,4a,1,1", options="header"]
+|===
+|Annotation
+|Purpose
+|Layer
+|xref:rg.adoc#_rg_object-layout_dynamic[Dynamic layout]?
+
+|xref:rg.adoc#_rg_annotations_manpage-Action[`@Action`]
+|Domain semantics for actions
+|Domain
+|
+
+|xref:rg.adoc#_rg_annotations_manpage-ActionLayout[`@ActionLayout`]
+|User interface hints for actions
+|UI
+|Yes
+
+|xref:rg.adoc#_rg_annotations_manpage-Collection[`@Collection`]
+|Domain semantics for collections
+|Domain
+|
+
+|xref:rg.adoc#_rg_annotations_manpage-CollectionLayout[`@CollectionLayout`]
+|User interface hints for collections
+|UI
+|Yes
+
+|xref:rg.adoc#_rg_annotations_manpage-DomainObject[`@DomainObject`]
+|Domain semantics for domain object (entities and optionally view models, see also `@ViewModel)`
+|Domain
+|
+
+|xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout[`@DomainObjectLayout`]
+|User interface hints for domain object (entities and optionally view models, see also `@ViewModelLayout)`
+|UI
+|Yes
+
+|xref:rg.adoc#_rg_annotations_manpage-DomainService[`@DomainService`]
+|Class is a domain service (rather than an entity or view model)
+|Domain
+|
+
+|xref:rg.adoc#_rg_annotations_manpage-DomainServiceLayout[`@DomainServiceLayout`]
+|User interface hints for domain services
+|UI
+|
+
+|xref:rg.adoc#_rg_annotations_manpage-Parameter[`@Parameter`]
+|Domain semantics for action parameters
+|Domain
+|
+
+|xref:rg.adoc#_rg_annotations_manpage-ParameterLayout[`@ParameterLayout`]
+|Layout hints for an action parameter (currently: its label position either to top or the left).
+|UI
+|Yes
+
+|xref:rg.adoc#_rg_annotations_manpage-Property[`@Property`]
+|Domain semantics for properties
+|Domain
+|
+
+|xref:rg.adoc#_rg_annotations_manpage-PropertyLayout[`@PropertyLayout`]
+|Layout hints for a property
+|UI
+|Yes
+
+|xref:rg.adoc#_rg_annotations_manpage-ViewModel[`@ViewModel`]
+|Specify that a class is a view model (as opposed to an entity or domain service); equivalent to `@DomainObject(nature`=VIEW_MODEL).
+|Domain, Persistence
+|
+
+|xref:rg.adoc#_rg_annotations_manpage-ViewModelLayout[`@ViewModelLayout`]
+|User interface hints for view models.
+For use with `@ViewModel`. If specifying view models using `@DomainObject(nature=VIEW_MODEL)` then use `@DomainObjectLayout`)
+|UI
+|Yes
+
+|===
+
+
+
[40/45] isis git commit: ISIS-1133: breaking out reference guide and
devenv guide;
moving appendices' release notes and migration notes to other docs;
improving the documentation page.
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout_renderedAsDayBefore.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout_renderedAsDayBefore.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout_renderedAsDayBefore.adoc
new file mode 100644
index 0000000..0214505
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout_renderedAsDayBefore.adoc
@@ -0,0 +1,35 @@
+[[_rg_annotations_manpage-ParameterLayout_renderedAsDayBefore]]
+= `renderedAsDayBefore()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `renderedAsDayBefore()` attribute applies only to date parameters whereby the date will be rendered as the day before the value actually held in the domain object. It is ignored for parameters of other types. This attribute is also supported for xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_renderedAsDayBefore[properties].
+
+This behaviour might at first glance appear odd, but the rationale is to support the use case of a sequence of instances that represent adjacent intervals of time. In such cases there would typically be `startDate` and `endDate` properties, eg for all of Q2. Storing this as a half-closed interval -- eg `[1-Apr-2015, 1-July-2015)` -- can substantially simplify internal algorithms; the `endDate` of one interval will correspond to the `startDate` of the next.
+
+However, from an end-user perspective the requirement may be to render the interval as a fully closed interval; eg the end date should be shown as `30-Jun-2015`.
+
+This attribute therefore bridges the gap; it presents the information in a way that makes sense to an end-user, but also stores the domain object in a way that is easy work with internally.
+
+For example:
+
+[source,java]
+----
+public class Tenancy {
+ public void changeDates(
+ @ParameterLayout(named="Start Date")
+ LocalDate startDate,
+ @ParameterLayout(
+ named="End Date",
+ renderedAsDayBefore=true
+ )
+ LocalDate endDate) {
+ ...
+ }
+}
+----
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout_typicalLength.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout_typicalLength.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout_typicalLength.adoc
new file mode 100644
index 0000000..819723b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ParameterLayout_typicalLength.adoc
@@ -0,0 +1,36 @@
+[[_rg_annotations_manpage-ParameterLayout_typicalLength]]
+= `typicalLength()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `typicalLength()` attribute indicates the typical length of a string parameter. It is ignored for parameters of other types. The attribute is also supported for xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_typicalLength[properties].
+
+The information is intended as a hint to the UI to determine the space that should be given to render a particular string parameter. That said, note that the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] uses the maximum space available for all fields, so in effect ignores this attribute.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ public Customer updateName(
+ @Parameter(maxLength=30)
+ @ParameterLayout(
+ named="First name",
+ typicalLength=20
+ )
+ final String firstName,
+ @Parameter(maxLength=30)
+ @ParameterLayout(
+ named="Last name",
+ typicalLength=20
+ )
+ final String lastName) {
+ ...
+ }
+ ...
+}
+----
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Parameter_maxLength.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Parameter_maxLength.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Parameter_maxLength.adoc
new file mode 100644
index 0000000..ebd6a3f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Parameter_maxLength.adoc
@@ -0,0 +1,35 @@
+[[_rg_annotations_manpage-Parameter_maxLength]]
+= `maxLength()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `maxLength()` attribute applies only to `String` parameters, indicating the maximum number of characters that the user may enter (for example in a text field in the UI). It is ignored if applied to parameters of any other type. This attribute can also be applied to xref:rg.adoc#_rg_annotations_manpage-Property_maxLength[properties].
+
+For example:
+
+[source,java]
+----
+public class CustomerRepository {
+ public Customer newCustomer(
+ @Parameter(maxLength=30)
+ @ParameterLayout(named="First Name") // <1>
+ final String firstName,
+ @Parameter(maxLength=50)
+ @ParameterLayout(named="Last Name")
+ final String lastName) {
+ ...
+ }
+}
+----
+<1> the `@ParameterLayout(named=...)` attribute is required for Java 7; for Java 8 it can be omitted if the (non-ASF) http://github.com/isisaddons/isis-metamodel-paraname8[Isis addons' paraname8] metamodel extension is used.
+
+
+
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Parameter_mustSatisfy.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Parameter_mustSatisfy.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Parameter_mustSatisfy.adoc
new file mode 100644
index 0000000..d3d6c5e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Parameter_mustSatisfy.adoc
@@ -0,0 +1,50 @@
+[[_rg_annotations_manpage-Parameter_mustSatisfy]]
+= `mustSatisfy()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `mustSatisfy()` attribute allows arbitrary validation to be applied to parameters using an (implementation of a) `org.apache.isis.applib.spec.Specification` object. The attribute is also supported on xref:rg.adoc#_rg_annotations_manpage-Property_mustSatisfy[properties].
+
+[TIP]
+====
+The specification implementations can (of course) be reused between parameters and xref:rg.adoc#_rg_annotations_manpage-Property_mustSatisfy[properties].
+====
+
+The `Specification` is consulted during validation, being passed the proposed value. If the proposed value fails, then the value returned is the used as the invalidity reason.
+
+For example:
+
+[source,java]
+----
+public class StartWithCapitalLetterSpecification
+ extends AbstractSpecification<String> { // <1>
+ 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 CustomerRepository {
+ public Customer newCustomer(
+ @Parameter(
+ mustSatisfy=StartWithCapitalLetterSpecification.class
+ )
+ @ParameterLayout(named="First Name")
+ final String firstName,
+ @Parameter(
+ mustSatisfy=StartWithCapitalLetterSpecification.class
+ )
+ @ParameterLayout(named="Last Name")
+ final String lastName) {
+ ...
+ }
+ ...
+}
+----
+<1> the `AbstractSpecification` class conveniently handles type-safety and dealing with null values. The applib also provides `SpecificationAnd` and `SpecificationOr` to allow specifications to be combined "algebraically".
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Parameter_optionality.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Parameter_optionality.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Parameter_optionality.adoc
new file mode 100644
index 0000000..7031c00
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Parameter_optionality.adoc
@@ -0,0 +1,36 @@
+[[_rg_annotations_manpage-Parameter_optionality]]
+= `optionality()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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, Apache Isis assumes that all parameters of an action are required (mandatory). The `optionality()` attribute allows this to be relaxed. The attribute is also supported for xref:rg.adoc#_rg_annotations_manpage-Property_optionality[properties].
+
+
+[TIP]
+====
+The attribute has no meaning for a primitive type such as `int`: primitives will always have a default value (e.g. zero). If optionality is required, then use the corresponding wrapper class (e.g. `java.lang.Integer`) and annotate with `Parameter#optionality()` as required.
+====
+
+The values for the attribute are simply `OPTIONAL` or `MANDATORY`.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ public Order placeOrder(
+ final Product product,
+ @ParameterLayout(named = "Quantity")
+ final int quantity,
+ @Parameter(optionality = Optionality.OPTIONAL)
+ @ParameterLayout(named = "Special Instructions")
+ final String instr) {
+ ...
+ }
+ ...
+}
+----
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Parameter_regexPattern.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Parameter_regexPattern.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Parameter_regexPattern.adoc
new file mode 100644
index 0000000..ecd7043
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Parameter_regexPattern.adoc
@@ -0,0 +1,31 @@
+[[_rg_annotations_manpage-Parameter_regexPattern]]
+= `regexPattern()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `regexPattern()` attribute validates the contents of any string parameter with respect to a regular expression pattern. It is ignored if applied to parameters of any other type. This attribute can also be specified for xref:rg.adoc#_rg_annotations_manpage-Property_regexPattern[properties].
+
+The related `regexPatternFlags()` attribute specifies flags that modify the handling of the pattern. The values are those that would normally be passed to `java.util.regex.Pattern#compile(String,int)`.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ public void updateEmail(
+ @Parameter(
+ regexPattern = "(\\w+\\.)*\\w+@(\\w+\\.)+[A-Za-z]+",
+ regexPatternFlags=Pattern.CASE_INSENSITIVE
+ )
+ @ParameterLayout(named = "Email")
+ final String email) {
+ ...
+ }
+)
+----
+
+The related `regexPatternReplacement()` attribute is currently unused.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-PersistenceCapable.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-PersistenceCapable.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-PersistenceCapable.adoc
new file mode 100644
index 0000000..4e65f88
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-PersistenceCapable.adoc
@@ -0,0 +1,90 @@
+[[_rg_annotations_manpage-PersistenceCapable]]
+= `@PersistenceCapable` (`javax.jdo`)
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@javax.jdo.annotation.PersistenceCapable` is used by JDO/DataNucleus to indicate that a class is a domain entity to be persisted to the database.
+
+Apache Isis also checks for this annotation, and if the `@PersistenceCapable#schema()` attribute is present will use it to form the object type.
+
+[NOTE]
+====
+Isis parses the `@PersistenceCapable` annotation from the Java source code; it does not query the JDO metamodel. This means that it the `@PersistenceCapable` annotation must be used rather than the equivalent `<class>` link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/class_mapping.html[XML metadata].
+
+Moreover, while JDO/DataNucleus will recognize annotations on either the field or the getter method, Isis (currently) only inspects the getter method. Therefore ensure that the annotation is placed there.
+====
+
+
+The object type is used internally by Isis to generate a string representation of an objects identity (the `Oid`). This can appear in several contexts, including:
+
+* as the value of `o.a.i.applib.services.bookmark.Bookmark#getObjectType()`
+* in the `toString()` value of `Bookmark`
+* in the URLs of the xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer]
+* in the URLs of the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] (in general and in particular if xref:ug.adoc#_ug_wicket-viewer_features_hints-and-copy-url[copying URLs])
+* in XML snapshots generated by the xref:rg.adoc#_rg_services-api_manpage-XmlSnapshotService[`XmlSnapshotService`]
+
+
+The actual format of the object type used by Isis for the concatenation of `schema()` and `@PersistenceCapable#table()`. If the `table()` is not present, then the class' simple name is used instead.
+
+For example:
+
+[source,java]
+----
+@javax.jdo.annotations.PersistenceCapable(schema="custmgmt")
+public class Customer {
+ ...
+}
+----
+
+has an object type of `custmgmt.Customer`, while:
+
+[source,java]
+----
+@javax.jdo.annotations.PersistenceCapable(schema="custmgmt", table="Address")
+public class AddressImpl {
+ ...
+}
+----
+
+has an object type of `custmgmt.Address`.
+
+
+On the other hand:
+
+[source,java]
+----
+@javax.jdo.annotations.PersistenceCapable(table="Address")
+public class AddressImpl {
+ ...
+}
+----
+
+does _not_ correspond to an object type, because the `schema()` attribute is missing.
+
+If the object type has not been specified, then Isis will use the fully qualified class name of the entity.
+
+
+
+[TIP]
+====
+This might be obvious, but to make explicit: we recommend that you use namespaces of some form or other.
+
+If the object type has not been specified (by either this annotation, or by xref:rg.adoc#_rg_annotations_manpage-Discriminator[`@Discriminator`], or by Isis' own xref:rg.adoc#_rg_annotations_manpage-ObjectType[`@DomainObject#objectType()`] annotation/attribute), then (as noted above) Isis will use the fully qualified class name of the entity.
+
+
+However, chances are that the fully qualified class name is liable to change over time, for example if the code is refactored or (more fundamentally) if your company/organization reorganizes/renames itself/is acquired.
+
+Isis' recognition of `@PersistenceCapable#schema()` makes namespacing of object types comparatively trivial, and moreover aligns the namespacing with the way in which the tables in the database are namespaced by the database schema.
+
+We therefore strongly recommend that you specify an object type for all entities, one way or another. Using `@PersistenceCapable#schema()` is probably the best choice in most cases.
+====
+
+
+
+[NOTE]
+====
+If the object type is not unique across all domain classes then the framework will fail-fast and fail to boot. An error message will be printed in the log to help you determine which classes have duplicate object tyoes.
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-PostConstruct.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-PostConstruct.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-PostConstruct.adoc
new file mode 100644
index 0000000..1edf941
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-PostConstruct.adoc
@@ -0,0 +1,66 @@
+[[_rg_annotations_manpage-PostConstruct]]
+= `@PostConstruct` (`javax`)
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@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.
+
+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:rg.adoc#_rg_annotations_manpage-RequestScoped[`@RequestScoped`] domain services, the method is called at the beginning of the request.
+
+The signature of the method is:
+
+[source,java]
+----
+@PostConstruct
+@Programmatic <1>
+public void postConstruct() { ... } <2>
+----
+<1> The method should be annotated using xref:rg.adoc#_rg_annotations_manpage-Programmatic[`@Programmatic`] so that it is not interpreted as an action.
+<2> the method can have any name, but must have `public` visibility.
+
+In the form shown above the method can either accept no arguments. Alternatively, the method can accept a parameter of type `Map<String,String>`:
+
+[source,java]
+----
+@PostConstruct
+@Programmatic
+public void postConstruct(Map<String,String> properties) { ... }
+----
+Isis uses argument to pass in the configuration properties read from all xref:ug.adoc#_ug_runtime_configuration-files[configuration files]:
+
+[TIP]
+====
+Alternatively, you could inject xref:rg.adoc#_rg_services-api_manpage-DomainObjectContainer[`DomainObjectContainer`] into the service and read configuration properties using `DomainObjectContainer#getProperty(...)` and related methods.
+====
+
+A common use case is for domain services that interact with the xref:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`]. For example:
+
+[source,java]
+----
+@DomainService(nature=NatureOfService.DOMAIN)
+public class MySubscribingService {
+ @Programmatic
+ @PostConstruct
+ public void postConstruct() {
+ eventBusService.register(this);
+ }
+ @Programmatic
+ @PreDestroy
+ public void preDestroy() {
+ eventBusService.unregister(this);
+ }
+ ...
+ @javax.inject.Inject
+ EventBusService eventBusService;
+}
+----
+
+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.
+
+
+
+
+
+See also xref:rg.adoc#_rg_annotations_manpage-PreDestroy[`@PreDestroy`]
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-PreDestroy.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-PreDestroy.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-PreDestroy.adoc
new file mode 100644
index 0000000..f66c019
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-PreDestroy.adoc
@@ -0,0 +1,50 @@
+[[_rg_annotations_manpage-PreDestroy]]
+= `@PreDestroy` (`javax`)
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@javax.annotation.PreDestroy` annotation, as defined in link:https://jcp.org/en/jsr/detail?id=250[JSR-250], recognized by Apache Isis as a callback method on domain services to be called just as they go out of scope.
+
+For the default application-scoped (singleton) domain services, this means that the method, if present, is called just prior to the termination of the application. For xref:rg.adoc#_rg_annotations_manpage-RequestScoped[`@RequestScoped`] domain services, the method is called at the end of the request.
+
+The signature of the method is:
+
+[source,java]
+----
+@PreDestroy
+@Programmatic <1>
+public void preDestroy() { ... } <2>
+----
+<1> The method should be annotated using xref:rg.adoc#_rg_annotations_manpage-Programmatic[`@Programmatic`] so that it is not interpreted as an action.
+<2> the method can have any name, but must have `public` visibility, and accept no arguments.
+
+A common use case is for domain services that interact with the xref:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`]. For example:
+
+[source,java]
+----
+@DomainService(nature=NatureOfService.DOMAIN)
+public class MySubscribingService {
+ @Programmatic
+ @PostConstruct
+ public void postConstruct() {
+ eventBusService.register(this);
+ }
+ @Programmatic
+ @PreDestroy
+ public void preDestroy() {
+ eventBusService.unregister(this);
+ }
+ ...
+ @javax.inject.Inject
+ EventBusService eventBusService;
+}
+----
+
+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.
+
+
+
+See also xref:rg.adoc#_rg_annotations_manpage-PostConstruct[`@PostConstruct`]
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-PrimaryKey.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-PrimaryKey.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-PrimaryKey.adoc
new file mode 100644
index 0000000..853d1aa
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-PrimaryKey.adoc
@@ -0,0 +1,19 @@
+[[_rg_annotations_manpage-PrimaryKey]]
+= `@PrimaryKey` (`javax.jdo`)
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@javax.jdo.annotation.PrimaryKey` annotation is used by JDO/DataNucleus to indicate that a property is used as the primary key for an entity with application-managed identity.
+
+Apache Isis also uses this annotation in a very minimal way: to ensure that the framework's own logic to initialize newly instantiated objects (eg using xref:rg.adoc#_rg_services-api_manpage-DomainObjectContainer[`DomainObjectContainer#newTransientInstance(...)`] does not touch the primary key, and also to ensure that the primary key property is always disabled (read-only).
+
+[NOTE]
+====
+Isis parses the `@NotPersistent` annotation from the Java source code; it does not query the JDO metamodel. This means that it the `@NotPersistent` annotation must be used rather than the equivalent `<field>` link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/application_identity.html[XML metadata].
+
+Moreover, while JDO/DataNucleus will recognize annotations on either the field or the getter method, Isis (currently) only inspects the getter method. Therefore ensure that the annotation is placed there.
+====
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Programmatic.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Programmatic.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Programmatic.adoc
new file mode 100644
index 0000000..803e7ac
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Programmatic.adoc
@@ -0,0 +1,27 @@
+[[_rg_annotations_manpage-Programmatic]]
+= `@Programmatic`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@Programmatic` annotation causes the method to be excluded completely from the Apache Isis metamodel. This means it won't appear in any UI, and it won't appear in any xref:rg.adoc#_rg_services-api_manpage-MementoService[memento]s or xref:rg.adoc#_rg_services-api_manpage-XmlSnapshotService[snapshot]s.
+
+A common use-case is to ignore implementation-level artifacts. For example:
+
+[source,java]
+----
+public class Customer implements Comparable<Customer> {
+ ...
+ @Programmatic
+ public int compareTo(Customer c) {
+ return getSalary() - c.getSalary();
+ }
+ ...
+}
+----
+
+
+Note that `@Programmatic` does not simply imply `@Hidden`; it actually means that the class member will not be part of the Isis metamodel.
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Property.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Property.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Property.adoc
new file mode 100644
index 0000000..eeb4547
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Property.adoc
@@ -0,0 +1,125 @@
+[[_rg_annotations_manpage-Property]]
+= `@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/
+
+
+The `@Property` annotation applies to properties collecting together all domain semantics within a single annotation.
+
+It is also possible to apply the annotation to actions of domain services that are acting as link:../../more-advanced-topics/how-to-01-062-How-to-decouple-dependencies-using-contributions.html[contributed properties].
+
+
+
+.`@Property` attributes
+[cols="2,2,4a", options="header"]
+|===
+
+| Attribute
+| Values (default)
+| Description
+
+
+|xref:rg.adoc#_rg_annotations_manpage-Property_domainEvent[`domainEvent()`]
+|subtype of `PropertyDomainEvent` +
+(`PropertyDomainEvent.Default`)
+|the event type to be posted to the xref:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`] to broadcast the property's business rule checking (hide, disable, validate) and its modification (before and after).
+
+
+|xref:rg.adoc#_rg_annotations_manpage-Property_editing[`editing()`]
+|`ENABLED`, `DISABLED`, `AS_CONFIGURED` +
+(`AS_CONFIGURED`)
+|whether a property can be modified or cleared from within the UI
+
+
+|xref:rg.adoc#_rg_annotations_manpage-Property_hidden[`hidden()`]
+|`EVERYWHERE`, `OBJECT_FORMS`, `PARENTED_TABLES`, `STANDALONE_TABLES`, `ALL_TABLES`, `NOWHERE` +
+(`NOWHERE`)
+|indicates where (in the UI) the property should be hidden from the user.
+
+
+|xref:rg.adoc#_rg_annotations_manpage-Property_maxLength[`maxLength()`]
+|
+|maximum number of characters for string parameters; ignored otherwise +
+
+In many/most cases you should however use xref:rg.adoc#_rg_annotations_manpage-Column[`@Column#length()`]
+
+
+|xref:rg.adoc#_rg_annotations_manpage-Property_mustSatisfy[`mustSatisfy()`]
+|implementation of `o.a.i.applib.spec.Specification`
+|allows arbitrary validation to be applied
+
+
+|xref:rg.adoc#_rg_annotations_manpage-Property_notPersisted[`notPersisted()`]
+|`true`, `false` +
+(`false`)
+|whether to exclude from snapshots. +
+
+[WARNING]
+====
+Property must also be annotated with `@javax.jdo.annotations.NotPersistent` in order to not be persisted.
+====
+
+
+|xref:rg.adoc#_rg_annotations_manpage-Property_optionality[`optionality()`]
+|
+|specifies a property is optional rather than mandatory +
+
+In many/most cases you should however use xref:rg.adoc#_rg_annotations_manpage-Column[`@Column#allowNulls()`]
+
+
+
+|xref:rg.adoc#_rg_annotations_manpage-Property_regexPattern[`regexPattern()`]
+|regular expression
+|validates the contents of a string parameter against the regular expression pattern
+
+
+|`regexPatternFlags()`
+|value of flags as normally passed to `java.util.regex.` +
+`Pattern#compile(...)`
+|modifies the compilation of the regular expression
+
+
+|===
+
+
+For example:
+
+[source,java]
+----
+@DomainObject
+public class Customer {
+ public static class EmailSpecification extends AbstractSpecification<String> {
+ public String satisfiesSafely(String proposed) {
+ return EmailUtil.ensureValidEmail(proposed); // <1>
+ }
+ }
+ @javax.jdo.annotations.Column(allowNulls="true") // <2>
+ @Property(
+ maxLength=30,
+ minLength=5,
+ mustSatisfy=EmailSpecification.class,
+ regexPattern = "(\\w+\\.)*\\w+@(\\w+\\.)+[A-Za-z]+",
+ regexPatternFlags=Pattern.CASE_INSENSITIVE
+ )
+ public String getEmailAddress() { ... }
+ public void setEmailAddress(String emailAddress) { ... }
+ ...
+}
+----
+<1> the (fictitious) `EmailUtil.ensureValid(...)` (omitted for brevity) returns a string explaining if an email is invalid
+<2> generally use instead of the `@Property#optionality()` attribute
+
+
+
+include::_rg_annotations_manpage-Property_domainEvent.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-Property_editing.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-Property_hidden.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-Property_maxLength.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-Property_mustSatisfy.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-Property_notPersisted.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-Property_optionality.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-Property_regexPattern.adoc[leveloffset=+1]
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-PropertyLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-PropertyLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-PropertyLayout.adoc
new file mode 100644
index 0000000..66080ff
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-PropertyLayout.adoc
@@ -0,0 +1,135 @@
+[[_rg_annotations_manpage-PropertyLayout]]
+= `@PropertyLayout`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@PropertyLayout` annotation applies to properties collecting together all UI hints within a single annotation.
+
+
+The table below summarizes the annotation's attributes.
+
+.`@PropertyLayout` attributes
+[cols="2,2,4a", options="header"]
+|===
+
+| Attribute
+| Values (default)
+| Description
+
+
+|xref:rg.adoc#_rg_annotations_manpage-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:ug.adoc#_ug_runtime_application-specific_application-css[`application.css`]
+
+
+|xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_describedAs[`describedAs()`]
+|String
+|description of this property, eg to be rendered in a tooltip.
+
+
+|xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_hidden[`hidden()`]
+|`EVERYWHERE`, `OBJECT_FORMS`, `PARENTED_TABLES`, `STANDALONE_TABLES`, `ALL_TABLES`, `NOWHERE` +
+(`NOWHERE`)
+|indicates where (in the UI) the property should be hidden from the user.
+
+
+|xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_labelPosition[`labelPosition()`]
+|`LEFT`, `TOP`, `RIGHT`, `NONE` +
+(`LEFT`)
+|in forms, the positioning of the label relative to the property value. +
+
+Defaults is `LEFT`, unless xref:rg.adoc#_rg_annotations_manpage-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:ug.adoc#_ug_runtime_configuring-core_isis-viewers-propertyLayout-labelPosition[configuration property]
+
+
+|xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_multiLine[`multiLine()`]
+|Positive integer
+|for string properties, render as a text area over multiple lines. +
+
+If set > 1, then xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_labelPosition[`labelPosition`] defaults to TOP.
+
+
+|xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_named[`named()`]
+|String
+|to override the name inferred from the collection's name in code. +
+
+A typical use case is if the desired name is a reserved Java keyword, such as `default` or `package`.
+
+
+|`namedEscaped()`
+|`true`, `false` +
+(`true`)
+|whether to HTML escape the name of this property.
+
+
+|xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_renderedAsDayBefore[`renderedAsDayBefore()`]
+|`true`, `false` +
+(`false`)
+|for date properties only, render the date as one day prior to the actually stored date.
+
+
+|xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_typicalLength[`typicalLength()`]
+|Positive integer.
+|the typical entry length of a field, use to determine the optimum width for display
+
+|===
+
+
+
+
+For example:
+
+[source,java]
+----
+public class ToDoItem {
+ @PropertyLayout(
+ cssClass="x-key",
+ named="Description of this <i>item</i>",
+ namedEscaped=false,
+ describedAs="What needs to be done",
+ labelPosition=LabelPosition.LEFT,
+ typicalLength=80
+ )
+ public String getDescription() { ... }
+ ...
+}
+----
+
+It is also possible to apply the annotation to actions of domain services that are acting as link:../../more-advanced-topics/how-to-01-062-How-to-decouple-dependencies-using-contributions.html[contributed properties].
+
+
+
+As an alternative to using the `@PropertyLayout` annotation, a dynamic layout using xref:rg.adoc#_rg_object-layout_dynamic[`.layout.json`] file can be specified; for example:
+
+[source,javascript]
+----
+"description": {
+ "propertyLayout": {
+ "cssClass": "x-key",
+ "describedAs": "What needs to be done",
+ "labelPosition": "LEFT",
+ "typicalLength": 80
+ }
+}
+----
+
+
+
+
+
+include::_rg_annotations_manpage-PropertyLayout_cssClass.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-PropertyLayout_describedAs.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-PropertyLayout_labelPosition.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-PropertyLayout_multiLine.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-PropertyLayout_named.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-PropertyLayout_renderedAsDayBefore.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-PropertyLayout_typicalLength.adoc[leveloffset=+1]
+
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-PropertyLayout_cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-PropertyLayout_cssClass.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-PropertyLayout_cssClass.adoc
new file mode 100644
index 0000000..0b8181d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-PropertyLayout_cssClass.adoc
@@ -0,0 +1,36 @@
+[[_rg_annotations_manpage-PropertyLayout_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()` attribute can be used to render additional CSS classes in the HTML (a wrapping `<div>`) that represents the property. xref:ug.adoc#_ug_runtime_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:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_cssClass[domain objects], xref:rg.adoc#_rg_annotations_manpage-ViewModelLayout_cssClass[view models], xref:rg.adoc#_rg_annotations_manpage-ActionLayout_cssClass[actions] xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_cssClass[collections] and xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_cssClass[parameters].
+
+
+For example:
+
+[source,java]
+----
+public class ToDoItem {
+ @PropertyLayout(cssClass="x-key")
+ public LocalDate getDueBy() { ... }
+}
+----
+
+
+
+
+As an alternative to using the annotation, the dynamic xref:rg.adoc#_rg_object-layout_dynamic[`.layout.json`]
+can be used instead, eg:
+
+[source,javascript]
+----
+"dueBy": {
+ "propertyLayout": { "cssClass": "x-key" }
+}
+----
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-PropertyLayout_describedAs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-PropertyLayout_describedAs.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-PropertyLayout_describedAs.adoc
new file mode 100644
index 0000000..8d46b17
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-PropertyLayout_describedAs.adoc
@@ -0,0 +1,33 @@
+[[_rg_annotations_manpage-PropertyLayout_describedAs]]
+= `describedAs()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `describedAs()` attribute is used to provide a short description of the property to the user. In the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] it is displayed as a 'tool tip'. The attribute can also be specified for xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_describedAs[collections], xref:rg.adoc#_rg_annotations_manpage-ActionLayout_describedAs[actions], xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_describedAs[parameters], xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_describedAs[domain objects] and xref:rg.adoc#_rg_annotations_manpage-ViewModelLayout_describedAs[view models].
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ @DescribedAs("The name that the customer has indicated that they wish to be " +
+ "addressed as (e.g. Johnny rather than Jonathan)")
+ public String getFirstName() { ... }
+}
+----
+
+
+As an alternative to using the annotation, the dynamic xref:rg.adoc#_rg_object-layout_dynamic[`.layout.json`]
+can be used instead, eg:
+
+[source,javascript]
+----
+"firstName:" {
+ "propertyLayout": {
+ "describedAs": "The name that the customer has indicated that they wish to be addressed as (e.g. Johnny rather than Jonathan)"
+ }
+}
+----
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-PropertyLayout_hidden.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-PropertyLayout_hidden.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-PropertyLayout_hidden.adoc
new file mode 100644
index 0000000..54b91d4
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-PropertyLayout_hidden.adoc
@@ -0,0 +1,78 @@
+[[_rg_annotations_manpage-PropertyLayout_hidden]]
+= `hidden()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `hidden()` attribute indicates where (in the UI) the property should be hidden from the user. This attribute can also be applied to xref:rg.adoc#_rg_annotations_manpage-Action_hidden[actions] and xref:rg.adoc#_rg_annotations_manpage-Collection_hidden[collections].
+
+[TIP]
+====
+It is also possible to use xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_hidden[`@PropertyLayout#hidden()`] or xref:rg.adoc#_rg_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.
+====
+
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ @PropertyLayout(
+ hidden=Where.ALL_TABLES
+ )
+ public int getInternalId() { ... }
+ ...
+}
+----
+
+The acceptable values for the `where` parameter are:
+
+* `Where.EVERYWHERE` or `Where.ANYWHERE` +
++
+The property should be hidden everywhere.
+
+* `Where.ANYWHERE` +
++
+Synonym for everywhere.
+
+* `Where.OBJECT_FORMS` +
++
+The property should be hidden when displayed within an object form.
+
+* `Where.PARENTED_TABLES` +
++
+The property should be hidden when displayed as a column of a table within a parent object's collection.
+
+* `Where.STANDALONE_TABLES` +
++
+The property should be hidden when displayed as a column of a table showing a standalone list of objects, for example as returned by a repository query.
+
+* `Where.ALL_TABLES` +
++
+The property should be hidden when displayed as a column of a table, either an object's * collection or a standalone list. This combines `PARENTED_TABLES` and `STANDALONE_TABLES`.
+
+* `Where.NOWHERE` +
++
+The property should not be hidden, overriding any other metadata/conventions that would normally cause the property to be hidden. +
+
+For example, if a property is annotated with xref:rg.adoc#_rg_annotations_manpage-Title[`@Title`], then normally this should be hidden from all
+tables. Annotating with `@Property(where=Where.NOWHERE)` overrides this.
+
+
+[NOTE]
+====
+The xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer] has only partial support for these `Where` enums.
+====
+
+
+As an alternative to using the annotation, the dynamic xref:rg.adoc#_rg_object-layout_dynamic[`.layout.json`]
+can be used instead, eg:
+
+[source,javascript]
+----
+"internalId": {
+ "propertyLayout": { "hidden": "ALL_TABLES" }
+}
+----
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-PropertyLayout_labelPosition.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-PropertyLayout_labelPosition.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-PropertyLayout_labelPosition.adoc
new file mode 100644
index 0000000..cf0aea9
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-PropertyLayout_labelPosition.adoc
@@ -0,0 +1,96 @@
+[[_rg_annotations_manpage-PropertyLayout_labelPosition]]
+= `labelPosition()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `labelPosition()` attribute determines the positioning of labels for properties. This attribute can also be specified for xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_labelPosition[parameters].
+
+The positioning of labels is typically `LEFT`, but can be positioned to the `TOP`. The one exception is xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_multiLine[`multiLine()`] string properties, where the label defaults to `TOP` automatically (to provide as much real-estate for the multiline text field as possible).
+
+For boolean properties a positioning of `RIGHT` is also allowed; this is ignored for all other types.
+
+It is also possible to suppress the label altogether, using `NONE`.
+
+For example:
+
+[source,java]
+----
+public class ToDoItem {
+ @PropertyLayout(
+ labelPosition=LabelPosition.TOP
+ )
+ public String getDescription() { ... }
+ public void setDescription(String description) { ... }
+ ...
+}
+----
+
+
+To get an idea of how these are rendered (in the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer]), we can look at the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] that happens to have examples of most of these various label positions.
+
+The default `LEFT` label positioning is used by the `cost` property:
+
+image::{_imagesdir}reference-annotations/PropertyLayout/labelPosition-LEFT.png[width="720px",link="{_imagesdir}reference-annotations/PropertyLayout/labelPosition-LEFT.png"]
+
+
+The `TOP` label positioning is used by the `category` property:
+
+image::{_imagesdir}reference-annotations/PropertyLayout/labelPosition-TOP.png[width="720px",link="{_imagesdir}reference-annotations/PropertyLayout/labelPosition-TOP.png"]
+
+
+Labels are suppressed, using `NONE`, for the `subcategory` property:
+
+image::{_imagesdir}reference-annotations/PropertyLayout/labelPosition-NONE.png[width="720px",link="{_imagesdir}reference-annotations/PropertyLayout/labelPosition-NONE.png"]
+
+
+The todoapp's `complete` (boolean) property renders the label to the LEFT (the default):
+
+image::{_imagesdir}reference-annotations/PropertyLayout/labelPosition-boolean-LEFT.png[width="720px",link="{_imagesdir}reference-annotations/PropertyLayout/labelPosition-boolean-LEFT.png"]
+
+Moving the label to the `RIGHT` looks like:
+
+image::{_imagesdir}reference-annotations/PropertyLayout/labelPosition-boolean-RIGHT.png[width="720px",link="{_imagesdir}reference-annotations/PropertyLayout/labelPosition-boolean-RIGHT.png"]
+
+
+
+
+As an alternative to using the annotation, the dynamic xref:rg.adoc#_rg_object-layout_dynamic[`.layout.json`]
+can be used instead, eg:
+
+[source,javascript]
+----
+"description": {
+ "propertyLayout": {
+ "labelPosition": "TOP"
+ }
+}
+----
+
+
+
+[TIP]
+.Specifying a default setting for label positions
+====
+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:ug.adoc#_ug_runtime_configuring-core[configuration property] in `isis.properties`:
+
+[source,ini]
+----
+isis.viewers.propertyLayout.labelPosition=TOP
+----
+
+or
+
+[source,ini]
+----
+isis.viewers.propertyLayout.labelPosition=LEFT
+----
+
+If these are not present then 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/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-PropertyLayout_multiLine.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-PropertyLayout_multiLine.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-PropertyLayout_multiLine.adoc
new file mode 100644
index 0000000..1ade1ae
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-PropertyLayout_multiLine.adoc
@@ -0,0 +1,44 @@
+[[_rg_annotations_manpage-PropertyLayout_multiLine]]
+= `multiLine()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `multiLine()` attribute specifies that the text field for a string property should span multiple lines. It is ignored for other property types. The attribute is also supported for xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_multiLine[parameters].
+
+For example:
+
+[source,java]
+----
+public class BugReport {
+ @PropertyLayout(
+ numberOfLines=10
+ )
+ public String getStepsToReproduce() { ... }
+ public void setStepsToReproduce(String stepsToReproduce) { ... }
+ ...
+}
+----
+
+Here the `stepsToReproduce` will be displayed in a text area of 10 rows.
+
+
+
+As an alternative to using the annotation, the dynamic xref:rg.adoc#_rg_object-layout_dynamic[`.layout.json`]
+can be used instead, eg:
+
+[source,javascript]
+----
+"stepsToReproduce": {
+ "propertyLayout": {
+ "numberOfLines": 10
+ }
+}
+----
+
+
+[NOTE]
+====
+If set > 1 (as would normally be the case), then the default xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_labelPosition[`labelPosition`] defaults to `TOP` (rather than `LEFT`, as would normally be the case).
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-PropertyLayout_named.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-PropertyLayout_named.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-PropertyLayout_named.adoc
new file mode 100644
index 0000000..df524fa
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-PropertyLayout_named.adoc
@@ -0,0 +1,51 @@
+[[_rg_annotations_manpage-PropertyLayout_named]]
+= named()
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `named()` attribute explicitly specifies the property's name, overriding the name that would normally be inferred from the Java source code. This attribute can also be specified for xref:rg.adoc#_rg_annotations_manpage-ActionLayout_named[actions], xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_named[collections], xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_named[parameters], xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_named[domain objects], xref:rg.adoc#_rg_annotations_manpage-ViewModelLayout_named[view models] and xref:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_named[domain services].
+
+[TIP]
+====
+Following the link:http://en.wikipedia.org/wiki/Don%27t_repeat_yourself[don't repeat yourself] principle, we recommend that you only use this attribute when the desired name cannot be used in Java source code. Examples of that include a name that would be a reserved Java keyword (eg "package"), or a name that has punctuation, eg apostrophes.
+====
+
+
+By default the name is HTML escaped. To allow HTML markup, set the related `namedEscaped()` attribute to `false`.
+
+For example:
+
+[source,java]
+----
+public class ToDoItem {
+ @PropertyLayout(
+ named="Description of this <i>item</i>",
+ namedEscaped=false
+ )
+ public String getDescription() { ... }
+ ...
+}
+----
+
+
+
+As an alternative to using the annotation, the dynamic xref:rg.adoc#_rg_object-layout_dynamic[`.layout.json`]
+can be used instead, eg:
+
+[source,javascript]
+----
+"description": {
+ "propertyLayout": {
+ "named": "Description of this <i>item</i>",
+ "namedEscaped": false
+ }
+}
+----
+
+
+[TIP]
+====
+The framework also provides a separate, powerful mechanism for xref:ug.adoc#_ug_more-advanced_i18n[internationalization].
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-PropertyLayout_renderedAsDayBefore.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-PropertyLayout_renderedAsDayBefore.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-PropertyLayout_renderedAsDayBefore.adoc
new file mode 100644
index 0000000..1a2bcf2
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-PropertyLayout_renderedAsDayBefore.adoc
@@ -0,0 +1,45 @@
+[[_rg_annotations_manpage-PropertyLayout_renderedAsDayBefore]]
+= `renderedAsDayBefore()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `renderedAsDayBefore()` attribute applies only to date properties whereby the date will be rendered as the day before the value actually held in the domain object. It is ignored for properties of other types. This attribute is also supported for xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_renderedAsDayBefore[parameters].
+
+This behaviour might at first glance appear odd, but the rationale is to support the use case of a sequence of instances that represent adjacent intervals of time. In such cases there would typically be `startDate` and `endDate` properties, eg for all of Q2. Storing this as a half-closed interval -- eg `[1-Apr-2015, 1-July-2015)` -- can substantially simplify internal algorithms; the `endDate` of one interval will correspond to the `startDate` of the next.
+
+However, from an end-user perspective the requirement may be to render the interval as a fully closed interval; eg the end date should be shown as `30-Jun-2015`.
+
+This attribute therefore bridges the gap; it presents the information in a way that makes sense to an end-user, but also stores the domain object in a way that is easy work with internally.
+
+For example:
+
+[source,java]
+----
+public class Tenancy {
+ public LocalDate getStartDate() { ... }
+ public void setStartDate(LocalDate startDate) { ... }
+ @PropertyLayout(
+ renderedAsDayBefore=true
+ )
+ public LocalDate getEndDate() { ... }
+ public void setEndDate(LocalDate EndDate) { ... }
+ ...
+}
+----
+
+
+
+As an alternative to using the annotation, the dynamic xref:rg.adoc#_rg_object-layout_dynamic[`.layout.json`]
+can be used instead, eg:
+
+[source,javascript]
+----
+"endDate": {
+ "propertyLayout": {
+ "renderedAsDayBefore": true
+ }
+}
+----
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-PropertyLayout_typicalLength.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-PropertyLayout_typicalLength.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-PropertyLayout_typicalLength.adoc
new file mode 100644
index 0000000..62f5b02
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-PropertyLayout_typicalLength.adoc
@@ -0,0 +1,25 @@
+[[_rg_annotations_manpage-PropertyLayout_typicalLength]]
+= `typicalLength()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `typicalLength()` attribute indicates the typical length of a string property. It is ignored for properties of other types. The attribute is also supported for xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_typicalLength[parameters].
+
+The information is intended as a hint to the UI to determine the space that should be given to render a particular string property. That said, note that the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] uses the maximum space available for all fields, so in effect ignores this attribute.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ @javax.jdo.annotations.Column(length=30)
+ @ParameterLayout(typicalLength=20)
+ public String getFirstName() { ... }
+ public void setFirstName(String firstName) { ... }
+ ...
+}
+----
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Property_domainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Property_domainEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Property_domainEvent.adoc
new file mode 100644
index 0000000..9e89bf9
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Property_domainEvent.adoc
@@ -0,0 +1,150 @@
+[[_rg_annotations_manpage-Property_domainEvent]]
+= `domainEvent()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+Whenever a domain object (or list of domain objects) is to be rendered, the framework fires off multiple domain events for every property, collection and action of the domain object. In the cases of the domain object's properties, the events that are fired are:
+
+* hide phase: to check that the property is visible (has not been hidden)
+* disable phase: to check that the property is usable (has not been disabled)
+* validate phase: to check that the property's arguments are valid (to modify/clear its value)
+* pre-execute phase: before the modification of the property
+* post-execute: after the modification of the property
+
+Subscribers subscribe through the xref:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`] using either link:https://github.com/google/guava[Guava] or link:http://www.axonframework.org/[Axon Framework] annotations and can influence each of these phases.
+
+By default the event raised is `PropertyDomainEvent.Default`. For example:
+
+[source,java]
+----
+public class ToDoItem {
+ @Property()
+ public LocalDate getDueBy() { ... }
+ ...
+}
+----
+
+The purpose of the `domainEvent()` attribute is to allows a custom subclass to be emitted instead. This attribute is also supported for xref:rg.adoc#_rg_annotations_manpage-Action_domainEvent[actions] and xref:rg.adoc#_rg_annotations_manpage-Property_domainEvent[properties].
+
+
+For example:
+
+[source,java]
+----
+public class ToDoItem {
+ public static class DueByChangedEvent extends PropertyDomainEvent<ToDoItem, LocalDate> { // <1>
+ private static final long serialVersionUID = 1L;
+ public DueByChangedEvent( // <2>
+ ToDoItem source, // <3>
+ Identifier identifier, // <4>
+ LocalDate oldValue, // <5>
+ LocalDate newValue) { // <6>
+ super(source, identifier, oldValue, newValue);
+ }
+ }
+ @Property(domainEvent=ToDoItem.DueByChangedEvent)
+ public LocalDate getDueBy() { ... }
+ ...
+}
+----
+<1> inherit from `PropertyDomainEvent<T,P>` where `T` is the type of the domain object being interacted with, and `P` is the type of the property (`LocalDate` in this example)
+<2> constructor called reflectively by the framework
+<3> populated with the object being interacted with (the source of the event)
+<4> identifier of the property
+<5> current value of the property
+<6> proposed new value for the property; if being cleared then will be `null`.
+
+The benefit is that subscribers can be more targetted as to the events that they subscribe to.
+
+
+
+
+== Subscribers
+
+Subscribers (which must be domain services) subscribe using either the link:https://github.com/google/guava[Guava] API or (if the xref:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`] has been appropriately configured) using the link:http://www.axonframework.org/[Axon Framework] API. The examples below use the Guava API.
+
+Subscribers can be either coarse-grained (if they subscribe to the top-level event type):
+
+[source,java]
+----
+@DomainService
+public class SomeSubscriber {
+
+ @Programmatic
+ @com.google.common.eventbus.Subscribe
+ public void on(PropertyInteractionEvent ev) {
+
+ ...
+ }
+
+}
+----
+
+or can be fine-grained (by subscribing to specific event subtypes):
+
+[source,java]
+----
+@DomainService
+public class SomeSubscriber {
+
+ @Programmatic
+ @com.google.common.eventbus.Subscribe
+ public void on(ToDoItem.DueByChangedEvent ev) {
+
+ ...
+ }
+
+}
+----
+
+[TIP]
+====
+If the AxonFramework is being used, replace `@com.google.common.eventbus.Subscribe` with `@org.axonframework.eventhandling.annotation.EventHandler`.
+====
+
+The subscriber's method is called (up to) 5 times:
+
+* whether to veto visibility (hide)
+* whether to veto usability (disable)
+* whether to veto execution (validate)
+* steps to perform prior to the property being modified
+* steps to perform after the property has been modified.
+
+The subscriber can distinguish these by calling `ev.getPhase()`. Thus the general form is:
+
+[source,java]
+----
+@Programmatic
+@com.google.common.eventbus.Subscribe
+public void on(PropertyDomainEvent ev) {
+ switch(ev.getPhase()) {
+ case HIDE:
+ // call ev.hide() or ev.veto("") to hide the property
+ break;
+ case DISABLE:
+ // call ev.disable("...") or ev.veto("...") to disable the property
+ break;
+ case VALIDATE:
+ // call ev.invalidate("...") or ev.veto("...")
+ // if proposed property value is invalid
+ break;
+ case EXECUTING:
+ break;
+ case EXECUTED:
+ break;
+ }
+}
+----
+
+It is also possible to abort the transaction during the executing or executed phases by throwing an exception. If the exception is a subtype of `RecoverableException` then the exception will be rendered as a user-friendly warning (eg Growl/toast) rather than an error.
+
+
+
+
+== Raising events programmatically
+
+Normally events are only raised for interactions through the UI. However, events can be raised programmatically by
+wrapping the target object using the xref:rg.adoc#_rg_services-api_manpage-WrapperFactory[`WrapperFactory`] service.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Property_editing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Property_editing.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Property_editing.adoc
new file mode 100644
index 0000000..41367a7
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Property_editing.adoc
@@ -0,0 +1,43 @@
+[[_rg_annotations_manpage-Property_editing]]
+= `editing()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `editing()` attribute can be used to prevent a property from being modified or cleared, ie to make it read-only. This attribute can also be specified for xref:rg.adoc#_rg_annotations_manpage-Collection_editing[collections], and can also be specified for the xref:rg.adoc#_rg_annotations_manpage-DomainObject_editing[domain object].
+
+The related `editingDisabledReason()` attribute specifies the a hard-coded reason why the property cannot be modified directly.
+
+Whether a property is enabled or disabled depends upon these factors:
+
+* whether the domain object has been configured as immutable through the xref:rg.adoc#_rg_annotations_manpage-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:ug.adoc#_ug_runtime_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
+
+* else, the result of invoking any supporting xref:rg.adoc#_rg_methods_prefixes_manpage-disable[`disable...()`] supporting methods
+
+
+Thus, to make a property read-only even if the object would otherwise be editable, use:
+
+[source,java]
+----
+public class Customer {
+ @Property(
+ editing=Editing.DISABLED,
+ editingDisabledReason="The credit rating is derived from multiple factors"
+ )
+ public int getInitialCreditRating(){ ... }
+ public void setInitialCreditRating(int initialCreditRating) { ... }
+}
+----
+
+[NOTE]
+====
+To reiterate, it is _not_ possible to enable editing for a property if editing has been disabled at the object-level.
+====
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Property_hidden.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Property_hidden.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Property_hidden.adoc
new file mode 100644
index 0000000..20529b4
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Property_hidden.adoc
@@ -0,0 +1,66 @@
+[[_rg_annotations_manpage-Property_hidden]]
+= `hidden()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+Properties can be hidden at the domain-level, indicating that they are not visible to the end-user. This attribute can also be applied to xref:rg.adoc#_rg_annotations_manpage-ActionLayout_hidden[actions] and xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_hidden[collections].
+
+[TIP]
+====
+It is also possible to use xref:rg.adoc#_rg_annotations_manpage-Property_hidden[`@Property#hidden()`] to hide an action at the domain 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:
+
+[source,java]
+----
+public class Customer {
+ @Property(hidden=Where.EVERYWHERE)
+ public int getInternalId() { ... }
+ @Property(hidden=Where.ALL_TABLES)
+ public void updateStatus() { ... }
+ ...
+}
+----
+
+The acceptable values for the `where` parameter are:
+
+* `Where.EVERYWHERE` or `Where.ANYWHERE` +
++
+The property should be hidden everywhere.
+
+* `Where.ANYWHERE` +
++
+Synonym for everywhere.
+
+* `Where.OBJECT_FORMS` +
++
+The property should be hidden when displayed within an object form.
+
+* `Where.PARENTED_TABLES` +
++
+The property should be hidden when displayed as a column of a table within a parent object's collection.
+
+* `Where.STANDALONE_TABLES` +
++
+The property should be hidden when displayed as a column of a table showing a standalone list of objects, for example as returned by a repository query.
+
+* `Where.ALL_TABLES` +
++
+The property should be hidden when displayed as a column of a table, either an object's * collection or a standalone list. This combines `PARENTED_TABLES` and `STANDALONE_TABLES`.
+
+* `Where.NOWHERE` +
++
+The property should not be hidden, overriding any other metadata/conventions that would normally cause the property to be hidden. +
+
+For example, if a property is annotated with xref:rg.adoc#_rg_annotations_manpage-Title[`@Title`], then normally this should be hidden from all
+tables. Annotating with `@Property(where=Where.NOWHERE)` overrides this.
+
+
+[NOTE]
+====
+The xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer] has only partial support for these `Where` enums.
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Property_maxLength.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Property_maxLength.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Property_maxLength.adoc
new file mode 100644
index 0000000..e4485d1
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Property_maxLength.adoc
@@ -0,0 +1,49 @@
+[[_rg_annotations_manpage-Property_maxLength]]
+= `maxLength()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `maxLength()` attribute applies only to `String` properties, indicating the maximum number of characters that the user may enter (for example in a text field in the UI). The attribute It is ignored if applied to properties of any other type. This attribute can also be applied to xref:rg.adoc#_rg_annotations_manpage-Parameter_maxLength[parameters].
+
+
+That said, properties are most commonly defined on persistent domain objects (entities), in which case the JDO xref:rg.adoc#_rg_annotations_manpage-Column[`@Column`] will in any case need to be specified. Isis can infer the `maxLength` semantic directly from the equivalent `@Column#length()` annotation/attribute.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ @javax.jdo.annotations.Column(length=30)
+ public String getFirstName() { ... }
+ public void setFirstName(String firstName) { ... }
+ ...
+}
+----
+
+In this case there is therefore no need for the `@Property#maxLength()` attribute.
+
+
+
+== Non-persistent properties
+
+Of course, not every property is persistent (it could instead be derived), and neither is every domain object an entity (it could be a view model). For these non persistable properties the `maxLength()` attribute is still required.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ @javax.jdo.annotation.NotPersistent // <1>
+ @Property(maxLength=100)
+ public String getFullName() { ... } // <2>
+ public void setFullName(String fullName) { ... } // <3>
+ ...
+}
+----
+<1> a non persisted (derived) property
+<2> implementation would most likely derive full name from constituent parts (eg first name, middle initial, last name)
+<3> implementation would most likely parse the input and update the constituent parts
+
[15/45] isis git commit: ISIS-1133: breaking out reference guide and
devenv guide;
moving appendices' release notes and migration notes to other docs;
improving the documentation page.
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_autoCompleteRepository.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_autoCompleteRepository.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_autoCompleteRepository.adoc
deleted file mode 100644
index 2dbd0e8..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_autoCompleteRepository.adoc
+++ /dev/null
@@ -1,76 +0,0 @@
-[[_ug_reference-annotations_manpage-DomainObject_autoCompleteRepository]]
-= `autoCompleteRepository()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `autoCompleteRepository()` attribute nominates a single method on a domain service as the fallback means for lookuping up instances of the domain object using a simple string.
-
-For example, this might search for a customer by their name or number. Or it could search for a country based on its ISO-3 code or user-friendly name.
-
-
-[TIP]
-====
-If you require additional control - for example restricting the returned results based on the object being interacted with - then use the xref:_ug_reference-methods_prefixes_manpage-autoComplete[`autoComplete...()`] supporting method instead.
-====
-
-
-For example:
-
-[source,java]
-----
-@AutoComplete(
- autoCompleteRepository=Customers.class
-)
-public class Customer extends AbstractDomainObject {
- ....
-}
-----
-
-where:
-
-[source,java]
-----
-public interface Customers {
- @Programmatic // <1>
- List<Customer> autoComplete(String search); // <2>
- ...
-}
-----
-<1> do not expose in the UI
-<2> is assumed to be called "autoComplete", and accepts a single string
-
-
-
-== `autoCompleteAction()`
-
-As noted above, by default the method invoked on the repository is assumed to be called "autoComplete". The optional `autoCompleteAction()` attribute allows the method on the repository to be overridden.
-
-
-For example:
-
-[source,java]
-----
-@AutoComplete(
- autoCompleteRepository=Customers.class,
- autoCompleteAction="findByCustomerName"
-)
-public class Customer extends AbstractDomainObject {
- ....
-}
-----
-
-where in this case `findByCustomerName` might be an existing method already defined:
-
-[source,java]
-----
-public interface Customers {
- @Action(semantics=SemanticsOf.SAFE)
- List<Customer> findByCustomerName(@ParameterLayout(named="name") String name);
- ...
-}
-----
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_bounded.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_bounded.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_bounded.adoc
deleted file mode 100644
index 7146029..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_bounded.adoc
+++ /dev/null
@@ -1,36 +0,0 @@
-[[_ug_reference-annotations_manpage-DomainObject_bounded]]
-= `bounded()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 domain classes are immutable to the user, and moreover have only a fixed number of instances. Often these are "reference" ("standing") data, or lookup data/pick lists. Typical examples could include categories, countries, states, and tax or interest rate tables.
-
-Where the number of instances is relatively small, ie bounded, then the `bounded()` attribute can be used as a hint. For such domain objects the framework will automatically allow instances to be selected; xref:_ug_wicket-viewer[Wicket viewer] displays these as a drop-down list.
-
-
-For example:
-
-[source,java]
-----
-@DomainObject(
- bounded=true,
- editing=Editing.DISABLED // <1>
-)
-public class Currency {
- ...
-}
-----
-<1> This attribute is commonly combined with `editing=DISABLED` to enforce the fact that reference data is immutable
-
-
-[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:_ug_reference-methods_prefixes_manpage-autoComplete[`autoComplete...()`] supporting method or the xref:_ug_reference-annotations_manpage-DomainObject_autoComplete[`@DomainObject#autoComplete()`] attribute instead.
-====
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_editing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_editing.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_editing.adoc
deleted file mode 100644
index c86d68a..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_editing.adoc
+++ /dev/null
@@ -1,61 +0,0 @@
-[[_ug_reference-annotations_manpage-DomainObject_editing]]
-= `editing()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `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:_ug_runtime_configuring-core[configuration property] `isis.objects.editing` is used to determine the whether the object is modifiable:
-
-* `true` +
-+
-the object's properties and collections are modifiable.
-
-* `false` +
-+
-the object's properties and collections are read-only, ie _not_ modifiable.
-
-If there is no configuration property in `isis.properties` then object are assumed to be modifiable.
-
-[TIP]
-====
-In other words, editing can be disabled globally for an application by setting:
-
-[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.
-====
-
-The related `editingDisabledReason()` attribute specifies the a hard-coded reason why the object's properties and collections cannot be modified directly.
-
-
-
-This default can be overridden on an object-by-object basis; if `editing()` is set to `ENABLED` then the object's properties and collections are editable irrespective of the configured value; if set to `DISABLED` then the object's properties and collections are not editable irrespective of the configured value.
-
-For example:
-
-[source,java]
-----
-@DomainObject(
- editing=Editing.DISABLED,
- editingDisabledReason="Reference data, so cannot be modified"
-)
-public class Country {
- ...
-}
-----
-
-[TIP]
-====
-Another interesting example of immutable reference data is to define an entity to represent individual dates; after all, for a system with an expected lifetime of 20 years that equates to only 7,300 days, a comparatively tiny number of rows to hold in a database.
-====
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_nature.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_nature.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_nature.adoc
deleted file mode 100644
index 6098032..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_nature.adoc
+++ /dev/null
@@ -1,59 +0,0 @@
-[[_ug_reference-annotations_manpage-DomainObject_nature]]
-= `nature()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `nature()` attribute is used to characterize the domain object as either an entity (part of the domain layer) or as a view model (part of the application layer). If the domain object should be thought of as an entity, it also captures how the persistence of that entity is managed.
-
-For example:
-
-[source,java]
-----
-@DomainObject(nature=Nature.VIEW_MODEL)
-public class PieChartAnalysis {
- ...
-}
-----
-
-Specifically, the nature must be one of:
-
-* `NOT_SPECIFIED,` +
-+
-(the default); specifies no paricular semantics for the domain class.
-
-* `JDO_ENTITY` +
-+
-indicates that the domain object is an entity whose persistence is managed internally by Isis, using the JDO/DataNucleus objectstore.
-
-* `EXTERNAL_ENTITY` +
-+
-indicates that the domain objecct is a wrapper/proxy/stub (choose your term) to an entity that is managed by some related external system. For example, the domain object may hold just the URI to a RESTful resource of some third party REST service, or the id of some system accessible over SOAP. +
-+
-The identity of an external 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.
-
-* `INMEMORY_ENTITY` +
-+
-indicates that the domain object is a wrapper/proxy/stub to a "synthetic" entity, for example one that is constructed from some sort of internal memory data structure. +
-+
-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.
-
-* `VIEW_MODEL` +
-+
-indicates that the domain object is conceptually part of the application layer, and exists to surfaces behaviour and/or state that is aggregate of one or more domain entities.
-
-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:_ug_reference-annotations_manpage-ViewModel[`@ViewModel`] or implement the xref:_ug_reference-classes_super_manpage-ViewModel[`ViewModel`] interface.
-
-
-[NOTE]
-====
-Under the covers Isis' support for `VIEW_MODEL`, `EXTERNAL_ENTITY` and `INMEMORY_ENTITY` domain objects is identical; the state of the object is encoded into its internal OID (represented ultimately as its URL), and is recreated directly from that URL.
-
-Because this particular implementation was originally added to Isis in support of view models, the term was also used for the logically different external entities and inmemory entities.
-
-The benefit of `nature()` is that it allows the developer to properly characterize the layer (domain vs application) that an entity lives, thus avoiding confusion as "view model" (the implementation technique) and "view model" (the application layer concept).
-====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_objectType.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_objectType.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_objectType.adoc
deleted file mode 100644
index 6cdf621..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_objectType.adoc
+++ /dev/null
@@ -1,46 +0,0 @@
-[[_ug_reference-annotations_manpage-DomainObject_objectType]]
-= `objectType()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `objectType()` attribute is used to provide a unique alias for the object's class name.
-
-This value is used internally to generate a string representation of an objects identity (the `Oid`). This can appear in several contexts, including:
-
-* as the value of `o.a.i.applib.services.bookmark.Bookmark#getObjectType()`
-* in the `toString()` value of `Bookmark`
-* in the URLs of the xref:_ug_restfulobjects-viewer[RestfulObjects viewer]
-* in the URLs of the xref:_ug_wicket-viewer[Wicket viewer] (in general and in particular if xref:_ug_wicket-viewer_features_hints-and-copy-url[copying URLs])
-* in XML snapshots generated by the xref:_ug_reference-services-api_manpage-XmlSnapshotService[`XmlSnapshotService`]
-
-
-For example:
-
-[source,java]
-----
-@DomainObject(
- objectType="ORD"
-)
-public class Order {
- ...
-}
-----
-
-If the object type has not been specified, then Isis will use the fully qualified class name of the entity.
-
-
-[TIP]
-====
-This might be obvious, but to make explicit: we recommend that you use namespaces of some form or other for object types.
-
-As noted above, if the object type has not been specified, then Isis will use the fully qualified class name of the entity. However, this is liable to change over time, for example if the code is refactored or (more fundamentally) if your company/organization reorganizes/renames itself/is acquired.
-
-We therefore strongly recommend that you specify an object type for all entities, either using `objectType()` or using the JDO xref:_ug_reference-annotations_manpage-PersistenceCapable[`@PersistenceCapable`] (with a `schema()` attribute) or xref:_ug_reference-annotations_manpage-Discriminator[`@Discriminator`] annotations. Specifying `@Discriminator` will override `@PersistenceCapable`, which in turn overrides `objectType()`. Using `@PersistenceCapable#schema()` is probably the best choice in most cases.
-====
-
-[NOTE]
-====
-If the object type is not unique across all domain classes then the framework will fail-fast and fail to boot. An error message will be printed in the log to help you determine which classes have duplicate object tyoes.
-====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_publishing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_publishing.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_publishing.adoc
deleted file mode 100644
index e26440e..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainObject_publishing.adoc
+++ /dev/null
@@ -1,49 +0,0 @@
-[[_ug_reference-annotations_manpage-DomainObject_publishing]]
-= `publishing()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `publishing()` attribute determines whether and how a modified object instance is published via the registered implementation of a xref:_ug_reference-services-spi_manpage-PublishingService[`PublishingService`]). This attribute is also supported for xref:_ug_reference-annotations_manpage-Action_publishing[actions], where it controls whether action invocations 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:_ug_runtime_configuring-core[configuration property] `isis.services.publish.objects` is used to determine the whether the action is published:
-
-* `all` +
-+
-all changed objects are published
-
-* `none` +
-+
-no changed objects are published
-
-If there is no configuration property in `isis.properties` then publishing is automatically enabled for domain objects.
-
-This default can be overridden on an object-by-object basis; if `publishing()` is set to `ENABLED` then changed instances of the domain class are published irrespective of the configured value; if set to `DISABLED` then the changed instances are _not_ published, again irrespective of the configured value.
-
-For example:
-
-[source,java]
-----
-@DomainObject(
- publishing=Publishing.ENABLED // <1>
-)
-public class InterestRate {
- ...
-}
-----
-<1> because set to enabled, will be published irrespective of the configured value.
-
-
-
-
-== `publishingPayloadFactory()`
-
-The (optional) related `publishingPayloadFactory()` specifies the class to use to create the (payload of the) event to be published by the publishing factory.
-
-Rather than simply broadcast that the object was changed, the payload factory allows a "fatter" payload to be instantiated that can eagerly push commonly-required information to all subscribers. For at least some subscribers this should avoid the necessity to query back for additional information.
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainService.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainService.adoc
deleted file mode 100644
index 741bc5a..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainService.adoc
+++ /dev/null
@@ -1,64 +0,0 @@
-[[_ug_reference-annotations_manpage-DomainService]]
-= `@DomainService`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@DomainService` annotation indicates that the (concrete) class should be automatically instantiated as a domain service.
-
-Domain services with this annotation do NOT need to be registered explicitly in `isis.properties`; they will be
-discovered automatically on the CLASSPATH.
-
-The table below summarizes the annotation's attributes.
-
-.`@DomainService` attributes
-[cols="2,2,4a", options="header"]
-|===
-
-| Attribute
-| Values (default)
-| Description
-
-
-|xref:_ug_reference-annotations_manpage-DomainService_nature[`nature()`]
-|`VIEW`, `VIEW_MENU_ONLY`, `VIEW_CONTRIBUTIONS_ONLY`, `VIEW_REST_ONLY`, `DOMAIN` (`VIEW`)
-|the nature of this service: providing actions for menus, or as contributed actions, or for the xref:_ug_restfulobjects-viewer[RestfulObjects REST API], or neither
-
-
-|xref:_ug_reference-annotations_manpage-DomainService_repositoryFor[`repositoryFor()`]
-|
-|if this domain service acts as a repository for an entity type, specify that entity type. (This is currently informational only)
-
-
-|`menuOrder()`
-|
-|Deprecated in 1.8.0; use instead xref:_ug_reference-annotations_manpage-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`]
-
-|===
-
-
-
-For example:
-
-[source,java]
-----
-@DomainService(
- nature=NatureOfService.DOMAIN,
- repositoryFor=Loan.class
-)
-public class LoanRepository {
- @Programmatic
- public List<Loan> findLoansFor(Borrower borrower) { ... }
-}
-----
-
-
-
-include::_ug_reference-annotations_manpage-DomainService_nature.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-DomainService_repositoryFor.adoc[leveloffset=+1]
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainServiceLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainServiceLayout.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainServiceLayout.adoc
deleted file mode 100644
index 3176cce..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainServiceLayout.adoc
+++ /dev/null
@@ -1,78 +0,0 @@
-[[_ug_reference-annotations_manpage-DomainServiceLayout]]
-= `@DomainServiceLayout`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@DomainServiceLayout` annotation applies to domain services, collecting together all view layout semantics within a single annotation.
-
-[TIP]
-====
-You will also find some additional material in the xref:_ug_reference-object-layout_application-menu[object layout] chapter.
-====
-
-
-The table below summarizes the annotation's attributes.
-
-.`@DomainServiceLayout` attributes
-[cols="2,2,4a", options="header"]
-|===
-
-| Attribute
-| Values (default)
-| Description
-
-
-|xref:_ug_reference-annotations_manpage-DomainServiceLayout_menuBar[`menuBar()`]
-|`PRIMARY`, `SECONDARY`, `TERTIARY` (`PRIMARY`).
-|the menubar in which the menu that holds this service's actions should reside.
-
-
-|xref:_ug_reference-annotations_manpage-DomainServiceLayout_menuOrder[`menuOrder()`]
-|
-|the order of the service's menu with respect to other service's.
-
-
-|xref:_ug_reference-annotations_manpage-DomainServiceLayout_named[`named()`]
-|string, eg "Customers"
-|name of this class (overriding the name derived from its name in code)
-
-
-
-|===
-
-
-
-For example:
-
-[source,java]
-----
-@DomainService
-@DomainServiceLayout(
- menuBar=MenuBar.PRIMARY,
- menuOrder="100",
- named="ToDos"
-)
-public class ToDoItems {
- ...
-}
-----
-
-
-
-[NOTE]
-====
-Note that there is (currently) no support for specifying UI hints for domain services through the dynamic xref:_ug_reference-object-layout_dynamic[`.layout.json`] file (only for properties, collections and actions are supported).
-====
-
-
-
-include::_ug_reference-annotations_manpage-DomainServiceLayout_menuBar.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-DomainServiceLayout_menuOrder.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-DomainServiceLayout_named.adoc[leveloffset=+1]
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainServiceLayout_menuBar.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainServiceLayout_menuBar.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainServiceLayout_menuBar.adoc
deleted file mode 100644
index 5ad9d99..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainServiceLayout_menuBar.adoc
+++ /dev/null
@@ -1,43 +0,0 @@
-[[_ug_reference-annotations_manpage-DomainServiceLayout_menuBar]]
-= `menuBar()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `menuBar()` attribute is a hint to specify where on the application menu a domain service's actions should be rendered.
-
-For example:
-
-[source,java]
-----
-@DomainService
-@DomainServiceLayout(menuBar=MenuBar.PRIMARY)
-public class ToDoItems {
- ...
-}
-----
-
-In the xref:_ug_wicket-viewer[Wicket viewer], domain services placed on the `PRIMARY` menu bar appears to the left:
-
-image::{_imagesdir}reference-annotations/DomainServiceLayout/menuBar-primary.png[width="720px",link="{_imagesdir}reference-annotations/DomainServiceLayout/menuBar-primary.png"]
-
-Domain services placed on the `SECONDARY` menu bar appear to the right:
-
-image::{_imagesdir}reference-annotations/DomainServiceLayout/menuBar-secondary.png[width="720px",link="{_imagesdir}reference-annotations/DomainServiceLayout/menuBar-secondary.png"]
-
-
-Domain services placed on the `TERTIARY` appear in the menu bar associated with the user's name (far top-right)
-
-image::{_imagesdir}reference-annotations/DomainServiceLayout/menuBar-tertiary.png[width="720px",link="{_imagesdir}reference-annotations/DomainServiceLayout/menuBar-tertiary.png"]
-
-
-The grouping of multiple domain services actions within a single drop-down is managed by the xref:_ug_reference-annotations_manpage-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] attribute.
-
-
-[NOTE]
-====
-The xref:_ug_restfulobjects-viewer[RestfulObjects viewer] does not support this attribute.
-====
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainServiceLayout_menuOrder.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainServiceLayout_menuOrder.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainServiceLayout_menuOrder.adoc
deleted file mode 100644
index 019d48b..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainServiceLayout_menuOrder.adoc
+++ /dev/null
@@ -1,74 +0,0 @@
-[[_ug_reference-annotations_manpage-DomainServiceLayout_menuOrder]]
-= `menuOrder()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `menuOrder()` attribute determines the ordering of a domain service's actions as menu items within a specified menu bar and top-level menu.
-
-
-The algorithm works as follows:
-
-* first, the xref:_ug_reference-annotations_manpage-DomainServiceLayout_menuBar[`menuBar()`] determines which of the three menu bars the service's actions should be rendered
-* then, the domain service's top-level name (typically explicitly specified using xref:_ug_reference-annotations_manpage-DomainServiceLayout_named[`named()`]) is used to determine the top-level menu item to be rendered on the menu bar
-* finally, if there is more than domain service that has the same name, then the `menuOrder` attribute is used to order those actions on the menu item drop-down.
-
-For example, the screenshot below shows the "prototyping" menu from the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp]:
-
-image::{_imagesdir}reference-annotations/DomainServiceLayout/menuOrder.png[width="500px",link="{_imagesdir}reference-annotations/DomainServiceLayout/menuOrder.png"]
-
-
-The xref:_ug_wicket-viewer[Wicket viewer] automatically places separators between actions from different domain services. From this we can infer that there are actually five different domain services that are all rendered on the "prototyping" top-level menu.
-
-One of these is the todoapp's `DemoDomainEventSubscriptions` service:
-
-[source,java]
-----
-@DomainService(
- nature = NatureOfService.VIEW_MENU_ONLY
-)
-@DomainServiceLayout(
- menuBar = MenuBar.SECONDARY,
- named = "Prototyping", // <1>
- menuOrder = "500.20") // <2>
-public class DemoDomainEventSubscriptions {
- @ActionLayout(named="Set subscriber behaviour")
- @MemberOrder(sequence = "500.20.1") // <3>
- public void subscriberBehaviour(...) { ... }
- ...
-}
-----
-<1> render on the "Prototyping" menu
-<2> positioning relative to other service's on the "Prototyping" menu
-<3> by convention (nothing more) the `@MemberOrder#sequence()` attribute continues the same Dewey decimal sequence format (a simple string "1" could in fact have been used instead)
-
-
-while another comes from the (non-ASF) http://github.com/isisaddons/isis-module-devutils[Isis addons' devutils] module:
-
-[source,java]
-----
-@DomainServiceLayout(
- menuBar = MenuBar.SECONDARY,
- named = "Prototyping", // <1>
- menuOrder = "500.600" // <2>
-)
-public class DeveloperUtilitiesServiceMenu {
- @MemberOrder( sequence = "500.600.1" ) // <3>
- public Clob downloadMetaModel() { ... }
- @MemberOrder( sequence = "500.600.2" )
- public Blob downloadLayouts() { ... }
- @ActionLayout(named = "Rebuild Services Meta Model")
- @MemberOrder( sequence = "500.600.3")
- public void refreshServices() { ... }
- ...
-}
-----
-<1> render on the "Prototyping" menu
-<2> positioning relative to other service's on the "Prototyping" menu; this appears after the `DemoDomainEventSubscriptions` service shown above
-<3> by convention (nothing more) the `@MemberOrder#sequence()` attribute continues the same Dewey decimal sequence format (a simple string "1", "2", "3", ... could in fact have been used instead)
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainServiceLayout_named.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainServiceLayout_named.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainServiceLayout_named.adoc
deleted file mode 100644
index 485d12b..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainServiceLayout_named.adoc
+++ /dev/null
@@ -1,29 +0,0 @@
-[[_ug_reference-annotations_manpage-DomainServiceLayout_named]]
-= `named()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `named()` attribute explicitly specifies the domain service's name, overriding the name that would normally be inferred from the Java source code. This attribute can also be specified for xref:_ug_reference-annotations_manpage-ActionLayout_named[actions], xref:_ug_reference-annotations_manpage-CollectionLayout_named[collections], xref:_ug_reference-annotations_manpage-PropertyLayout_named[properties], xref:_ug_reference-annotations_manpage-ParameterLayout_named[parameters], xref:_ug_reference-annotations_manpage-DomainObjectLayout_named[domain objects] and xref:_ug_reference-annotations_manpage-ViewModelLayout_named[view models].
-
-
-[TIP]
-====
-The value of this attribute also has an important role to play in the positioning of the domain service's actions relative to the actions of other domain services. See xref:_ug_reference-annotations_manpage-DomainServiceLayout_menuOrder[`menuOrder()`] for a full discussion with examples.
-====
-
-For example:
-
-[source,java]
-----
-@DomainService
-@DomainServiceLayout(
- named="Customers"
-)
-public class CustomerRepository {
- ...
-}
-----
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainService_nature.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainService_nature.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainService_nature.adoc
deleted file mode 100644
index 14c40fe..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainService_nature.adoc
+++ /dev/null
@@ -1,89 +0,0 @@
-[[_ug_reference-annotations_manpage-DomainService_nature]]
-= `nature()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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, a domain service's actions will be rendered in the application menu bar _and_ be contributed _and_ appear in the REST API _and_ (of course) be available to invoke programmatically wherever that domain service is injected. This is great for initial prototyping, but later on you may prefer to add a little more structure. This is the purpose of the `nature()` attribute: to indicates the intent of (all of) the actions defined within the domain service.
-
-The values of the enum are:
-
-* `VIEW` +
-+
-The default; the service's actions appear on menu bars, can be contributed, appear in the REST API
-
-* `VIEW_MENU_ONLY` +
-+
-The service's actions appear on menus and in the REST API, but are not contributed to domain objects or view models
-
-* `VIEW_CONTRIBUTIONS_ONLY` +
-+
-The service's actions are intended only to be used as contributed actions/associations to domain objects and view models. +
-+
-The related xref:_ug_reference-annotations_manpage-ActionLayout_contributedAs[`@ActionLayout#contributedAs()`] determines whether any given (1-arg) action is contributed as an association rather than an action.
-
-* `VIEW_REST_ONLY` +
-+
-The service's actions are intended only to be listed in the REST API exposed by the xref:_ug_restfulobjects-viewer[RestfulObjects viewer].
-
-* `DOMAIN` +
-+
-The service and its actions are only intended to be invoked programmatically; they are a domain layer responsibility.
-
-
-The actual class name of the domain service is only rendered for the `VIEW`, `VIEW_MENU_ONLY` and `VIEW_REST_ONLY` natures. Thus, you might also want to adopt naming conventions for your domain classes so you can infer the nature from the class. For example, the naming convention adopted (by and large) by the (non-ASF) link:http://isisaddons.org[Isis Addons] is `ProgrammaticServices` or `Repository` as a suffix for `DOMAIN` services, and `Contributions` as a suffix for `VIEW_CONTRIBUTIONS_ONLY` services.
-
-For example:
-
-[source,java]
-----
-@DomainService(
- nature=NatureOfService.VIEW_CONTRIBUTIONS_ONLY
-)
-public class LoanContributions { // <1>
- @Action(semantics=SemanticsOf.SAFE) // <2>
- @ActionLayout(contributed=Contributed.AS_ASSOCIATION )
- public List<Loan> currentLoans(Borrower borrower) { ... }
- public Borrower newLoan(Borrower borrower, Book book) { ... }
-}
-----
-<1> `Contributions` as a suffix for a domain service that contributes a number of actions to ``Borrower``s. Note that `Borrower` could be a (marker) interface, so this functionality is "mixed in" merely by the class (eg `LibraryMember`) implementing this interface
-<2> actions contibuted as associations (a collection in this case) must have safe semantics
-
-
-Another example:
-
-[source,java]
-----
-@DomainService(
- nature=NatureOfService.DOMAIN
-)
-public class LoanRepository { // <1>
- @Programmatic // <2>
- public List<Loan> findLoansFor(Borrower borrower) { ... }
-}
-----
-<1> `Repository` as a suffix for a domain-layer service
-<2> methods on `DOMAIN` services are often xref:_ug_reference-annotations_manpage-Programmatic[`@Programmatic`]; they will never be exposed in the UI, so there's little point in including them in Isis' metamodel
-
-
-
-A final example:
-
-[source,java]
-----
-@DomainService(
- nature=NatureOfService.VIEW_MENU_ONLY
-)
-public class Loans { // <1>
- @Action(semantics=SemanticsOf.SAFE)
- public List<Loan> findOverdueLoans() { ... }
- @Inject
- LoanRepository loanRepository; // <2>
-}
-----
-<1> name is intended to be rendered in the UI
-<2> it's common for domain-layer domain services to be injected into presentation layer services (such as `VIEW_MENU_ONLY` and `VIEW_CONTRIBUTIONS_ONLY`).
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainService_repositoryFor.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainService_repositoryFor.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainService_repositoryFor.adoc
deleted file mode 100644
index 7eaf487..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-DomainService_repositoryFor.adoc
+++ /dev/null
@@ -1,26 +0,0 @@
-[[_ug_reference-annotations_manpage-DomainService_repositoryFor]]
-= `repositoryFor()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `repositoryFor()` attribute is intended for domain services (probably with a xref:_ug_reference-annotations_manpage-DomainService_nature[`nature=DOMAIN`]) that are intended to act as repositories for domain entities.
-
-For example:
-
-[source,java]
-----
-@DomainService(
- nature=NatureOfService.DOMAIN,
- repositoryFor=Loan.class
-)
-public class LoanRepository {
- @Programmatic
- public List<Loan> findLoansFor(Borrower borrower) { ... }
-}
-----
-
-
-Currently the metadata is unused; one planned use is to infer the icon for the domain service from the icon of the nominated entity.
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Facets.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Facets.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Facets.adoc
deleted file mode 100644
index 7c8513b..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Facets.adoc
+++ /dev/null
@@ -1,15 +0,0 @@
-[[_ug_reference-annotations_manpage-Facets]]
-= `@Facets`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@Facets` annotation allows `FacetFactory` implementations and so can be used to run install arbitrary `Facet`s for a type. Generally this is not needed, but can be useful for overriding a custom programming model where a `FacetFactory` is not typically included.
-
-
-[NOTE]
-====
-`FacetFactory` is an important internal API that is used by Isis to
-====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-HomePage.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-HomePage.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-HomePage.adoc
deleted file mode 100644
index e6ddd52..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-HomePage.adoc
+++ /dev/null
@@ -1,52 +0,0 @@
-[[_ug_reference-annotations_manpage-HomePage]]
-= `@HomePage`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@HomePage` annotation allows a _single_ (no-arg, query-only) action on a _single_ domain service to be nominated as the action to invoke for the default home page. This often returns a view model that acts as some sort of dashboard, presenting key information and makeing the most commonly used actions easy to invoke.
-
-For example, the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] uses `@HomePage` to return a dashboard of todo items to complete:
-
-image::{_imagesdir}reference-annotations/HomePage/HomePage.png[width="800px",link="{_imagesdir}reference-annotations/HomePage/HomePage.png"]
-
-
-The corresponding code is:
-
-[source,java]
-----
-@DomainService(nature = NatureOfService.DOMAIN)
-public class ToDoAppDashboardService {
- @Action(
- semantics = SemanticsOf.SAFE
- )
- @HomePage
- public ToDoAppDashboard lookup() {
- return container.injectServicesInto(new ToDoAppDashboard());
- }
- @Inject
- private DomainObjectContainer container;
-}
-----
-
-where `ToDoAppDashboard` is:
-
-[source,java]
-----
-@DomainObject(nature = Nature.VIEW_MODEL)
-public class ToDoAppDashboard {
- public String title() { return "Dashboard"; }
-
- public List<ToDoItem> getNotYetComplete() { ... }
- public List<ToDoItem> getComplete() { ... }
-
- public Blob exportToWordDoc() { ... } // <1>
-}
-----
-<1> associated using xref:_ug_reference-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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Inject.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Inject.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Inject.adoc
deleted file mode 100644
index 4b5c70a..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Inject.adoc
+++ /dev/null
@@ -1,110 +0,0 @@
-[[_ug_reference-annotations_manpage-Inject]]
-= `@Inject` (`javax`)
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 automatically injects domain services into other domain services and also into domain objects and view models. In fact, it also injects domain services into xref:_ug_testing_integ-test-support[integration tests] and xref:_ug_testing_fixture-scripts[fixture scripts].
-
-[NOTE]
-====
-One omission: Isis (currently) does not inject services into `o.a.i.applib.spec.Specification` instances (as used by xref:_ug_reference-annotations_manpage-Property_mustSatisfy[`@Property#mustSatisfy()`] and xref:_ug_reference-annotations_manpage-Parameter_mustSatisfy[`@Parameter#mustSatisfy()`] annotations.
-====
-
-Isis supports several syntaxes for injecting domain services. The simplest uses the `@javax.inject.Inject` annotation on the field, as defined in link:https://jcp.org/en/jsr/detail?id=330[JSR-330].
-
-For example:
-
-[source,java]
-----
-public class Customer {
- public List<Order> findRecentOrders() { // <1>
- return orders.recentOrdersFor(this);
- }
- @javax.inject.Inject
- OrderRepository orders; // <2>
-}
-----
-<1> an alternative implementation would be to implement `findRecentOrders()` as a xref:_ug_how-tos_contributed-members[contributed action].
-<2> we recommend default (rather than `private`) visibility so that unit tests can easily mock out the service
-
-
-
-== Alternative syntaxes
-
-Isis also supports setter-based injection:
-
-[source,java]
-----
-public class Customer {
- ...
- public void setOrderRepository(OrderRepository orderRepository) { ... }
-}
-----
-
-and also supports an additional syntax of using `inject...` as the prefix:
-
-[source,java]
-----
-public class Customer {
- ...
- public void injectOrderRepository(OrderRepository orderRepository) { ... }
-}
-----
-
-Generally we recommend using `@javax.inject.Inject`; it involves less code, and is more immediately familiar to most Java developers.
-
-
-
-== Manually injecting services
-
-Isis performs dependency injection when domain entities are recreated. It will also perform dependency injection if an object is created through the `DomainObjectContainer`.
-
-For example, to create a new (transient) domain object, the idiom is:
-
-[source,java]
-----
-Customer cust = container.newTransientInstance(Customer.class); <1>
-// initialize state of "cust"
-container.persist(cust);
-----
-<1> where `container` is an instance of xref:_ug_reference-services-api_manpage-DomainObjectContainer[`DomainObjectContainer`].
-
-View models are created similarly:
-
-[source,java]
-----
-ToDoAppDashboard dashboard = container.newViewModelInstance(ToDoAppDashboard.class);
-----
-
-
-If you prefer, though, you can simply instantiate domain objects using "new" and then inject domain services manually:
-
-
-[source,java]
-----
-Customer cust = new Customer();
-container.injectServicesInto(cust);
-// initialize state of "cust"
-container.persist(cust);
-----
-
-
-or if you prefer:
-
-[source,java]
-----
-Customer cust = container.injectServicesInto(new Customer());
-// initialize state of "cust"
-container.persist(cust);
-----
-
-
-[NOTE]
-====
-There is one subtle difference between using `DomainObjectContainer#newTransientInstance(...)` and `DomainObjectContainer#injectServicesInto(...)`, in that with the former Isis will automatically initialize all fields to their default values.
-
-This isn't a particular useful feature (and indeed can sometimes be rather confusing) so you may well wish to standardize on using `injectServicesInto(...)` throughout.
-====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-MemberGroupLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-MemberGroupLayout.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-MemberGroupLayout.adoc
deleted file mode 100644
index 3e8a513..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-MemberGroupLayout.adoc
+++ /dev/null
@@ -1,20 +0,0 @@
-[[_ug_reference-annotations_manpage-MemberGroupLayout]]
-= `@MemberGroupLayout`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@MemberGroupLayout` annotation specifies how an object's properties and collections are grouped together into columns, also specifying the relative positioning of those columns. It works in conjunction with the xref:_ug_reference-annotations_manpage-MemberOrder[`@MemberOrder`] annotation.
-
-
-The `@MemberOrder` annotation is used to specify the relative order of domain object members, that is: properties, collections and actions. It works in conjunction with the xref:_ug_reference-annotations_manpage-MemberGroupLayout[`@MemberGroupLayout`] annotation.
-
-The annotation defines two attributes, `name()` and `sequence()`. Broadly speaking the `name()` attribute is used to group or associate members together, while the `sequence()` attribute orders members once they have been grouped.
-
-
-[IMPORTANT]
-====
-As this is an important topic, there is a xref:_ug_reference-object-layout[separate chapter] that discussed object layout in full.
-====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-MemberOrder.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-MemberOrder.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-MemberOrder.adoc
deleted file mode 100644
index 3ab277f..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-MemberOrder.adoc
+++ /dev/null
@@ -1,25 +0,0 @@
-[[_ug_reference-annotations_manpage-MemberOrder]]
-= `@MemberOrder`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@MemberOrder` annotation is used to specify the relative order of domain object members, that is: properties, collections and actions. It works in conjunction with the xref:_ug_reference-annotations_manpage-MemberGroupLayout[`@MemberGroupLayout`] annotation.
-
-The annotation defines four attributes:
-
-* `columnSpans()` -- of type `int[]` -- which specifies the relative column sizes of the three columns that render properties as well as a fourth column that renders only collections
-
-* `left()` -- of type `String[]` - that specifies the order of the property groups (inferred from `@MemberOrder#name()`) as applied to properties) in the left-most column
-
-* `middle()` -- of type `String[]` - that specifies the order of the property groups (if any) as applied to properties) in the middle column
-
-* `right()` -- of type `String[]` - that specifies the order of the property groups (if any) as applied to properties) in the right-most column
-
-Collections are always rendered in the "last" column. This can appear either below the columns holding properties (if their column spans = 12), or can be rendered to the right of the property columns (if the spans of the property columns come to <12 leaving enough room for the span of the collection column).
-
-[IMPORTANT]
-====
-As this is an important topic, there is a xref:_ug_reference-object-layout[separate chapter] that discussed object layout in full.
-====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-MinLength.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-MinLength.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-MinLength.adoc
deleted file mode 100644
index fdbc9a5..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-MinLength.adoc
+++ /dev/null
@@ -1,32 +0,0 @@
-[[_ug_reference-annotations_manpage-MinLength]]
-= `@MinLength`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@MinLength` annotation is used to specify the minimum number of characters in a search of an xref:_ug_reference-methods_prefixes_manpage-autoComplete[`autoComplete...()`] supporting method.
-
-
-For example:
-
-[source,java]
-----
-public ToDoItem add(
- @TypicalLength(20)
- final ToDoItem toDoItem) {
- getDependencies().add(toDoItem);
- return this;
-}
-public List<ToDoItem> autoComplete0Add(
- final @MinLength(2)
- String search) {
- final List<ToDoItem> list = toDoItems.autoComplete(search);
- list.removeAll(getDependencies());
- list.remove(this);
- return list;
-}
-----
-
-
-The `@Parameter(minLength=...)`e can also be used (even though strictly speaking the search argument is not a parameter of the action).
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-NotPersistent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-NotPersistent.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-NotPersistent.adoc
deleted file mode 100644
index 7cc2efd..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-NotPersistent.adoc
+++ /dev/null
@@ -1,18 +0,0 @@
-[[_ug_reference-annotations_manpage-NotPersistent]]
-= `@NotPersistent` (`javax.jdo`)
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@javax.jdo.annotation.NotPersistent` annotation is used by JDO/DataNucleus to indicate that a property should not be persisted to the database.
-
-Apache Isis also uses this annotation, though (currently) only in the very minimal way to suppress checking of inconsistent metadata between JDO and Isis annotations (eg `@Column#allowsNull()` vs `@Property#optionality()`, or `@Column#length()` and `@Property#maxLength()`).
-
-[NOTE]
-====
-Isis parses the `@NotPersistent` annotation from the Java source code; it does not query the JDO metamodel. This means that it the `@NotPersistent` annotation must be used rather than the equivalent `<field>` link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/fields_properties.html[XML metadata].
-
-Moreover, while JDO/DataNucleus will recognize annotations on either the field or the getter method, Isis (currently) only inspects the getter method. Therefore ensure that the annotation is placed there.
-====
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter.adoc
deleted file mode 100644
index bd231e2..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Parameter.adoc
+++ /dev/null
@@ -1,96 +0,0 @@
-[[_ug_reference-annotations_manpage-Parameter]]
-= `@Parameter`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@Parameter` annotation applies to action parameters collecting together all domain semantics within a single annotation.
-
-The table below summarizes the annotation's attributes.
-
-.`@Paramter` attributes
-[cols="2,2,4a", options="header"]
-|===
-
-| Attribute
-| Values (default)
-| Description
-
-
-|xref:_ug_reference-annotations_manpage-Parameter_maxLength[`maxLength()`]
-|Positive integer
-|maximum number of characters for string parameters; ignored otherwise
-
-
-|`minLength()`
-|Positive integer
-|Deprecated; use xref:_ug_reference-annotations_manpage-MinLength[`@MinLength`] instead. +
-
-Can be used to specify the minimum length for xref:_ug_reference-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:_ug_reference-annotations_manpage-Parameter_mustSatisfy[`mustSatisfy()`]
-|implementation of `o.a.i.applib.spec.Specification`
-|allows arbitrary validation to be applied
-
-
-|xref:_ug_reference-annotations_manpage-Parameter_optionality[`optionality()`]
-|`MANDATORY`, `OPTIONAL` (`MANDATORY`)
-|specifies a parameter is optional rather than mandatory
-
-
-|xref:_ug_reference-annotations_manpage-Parameter_regexPattern[regexPattern()]
-|regular expression
-|validates the contents of a string parameter against the regular expression pattern
-
-
-|`regexPatternFlags()`
-|value of flags as normally passed to `java.util.regex.` +
-`Pattern#compile(...)`
-|modifies the compilation of the regular expression
-
-
-|`regexPatternReplacement()`
-|
-|Unused.
-
-
-|===
-
-
-
-
-For example:
-
-[source,java]
-----
-public class Customer {
- public static class EmailSpecification extends AbstractSpecification<String> {
- public String satisfiesSafely(String proposed) {
- return EmailUtil.ensureValidEmail(proposed); // <1>
- }
- }
- @Action(semantics=SemanticsOf.IDEMPOTENT)
- public Customer updateEmail(
- @Parameter(
- maxLength=30,
- mustSatisfy=EmailSpecification.class,
- optionality=Optionality.OPTIONAL,
- regexPattern = "(\\w+\\.)*\\w+@(\\w+\\.)+[A-Za-z]+",
- regexPatternFlags=Pattern.CASE_INSENSITIVE
- )
- @ParameterLayout(named="New Email Address")
- final String newEmailAddress
- ...
- }
-}
-----
-<1> the (fictitious) `EmailUtil.ensureValid(...)` (omitted for brevity) returns a string explaining if an email is invalid
-
-include::_ug_reference-annotations_manpage-Parameter_maxLength.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-Parameter_mustSatisfy.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-Parameter_optionality.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-Parameter_regexPattern.adoc[leveloffset=+1]
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout.adoc
deleted file mode 100644
index 420e04a..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout.adoc
+++ /dev/null
@@ -1,112 +0,0 @@
-[[_ug_reference-annotations_manpage-ParameterLayout]]
-= `@ParameterLayout`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@ParameterLayout` annotation applies to action parameters, collecting together all UI hints within a single annotation.
-
-The table below summarizes the annotation's attributes.
-
-.`@ParameterLayout` attributes
-[cols="2,2,4a", options="header"]
-|===
-
-| Attribute
-| Values (default)
-| Description
-
-
-|xref:_ug_reference-annotations_manpage-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:_ug_runtime_application-specific_application-css[`application.css`]
-
-
-|xref:_ug_reference-annotations_manpage-ParameterLayout_describedAs[`describedAs()`]
-|String
-|description of this parameter, eg to be rendered in a tooltip.
-
-
-|xref:_ug_reference-annotations_manpage-ParameterLayout_labelPosition[`labelPosition()`]
-|`LEFT`, `TOP`, `RIGHT`, `NONE` +
-(`LEFT`)
-|in forms, the positioning of the label relative to the property value. +
-
-Default is `LEFT`, unless xref:_ug_reference-annotations_manpage-ParameterLayout_multiLine[`multiLine`] in which case `TOP`. The value `RIGHT` is only supported for boolean parameters.
-
-
-|xref:_ug_reference-annotations_manpage-ParameterLayout_multiLine[`multiLine()`]
-|Positive integer
-|for string parameters, render as a text area over multiple lines. +
-
-If set > 1, then then xref:_ug_reference-annotations_manpage-ParameterLayout_labelPosition[`labelPosition`] defaults to `TOP`.
-
-
-|xref:_ug_reference-annotations_manpage-ParameterLayout_named[`named()`]
-|String
-|the name of this parameter. +
-
-For Java 7 this is generally required. For Java 8, the name can often be inferred from the code so this attribute allows the name to be overridden. A typical use case is if the desired name is a reserved Java keyword, such as `default` or `package`.
-
-
-|`namedEscaped()`
-|`true`, `false` (`true`)
-|whether to HTML escape the name of this parameter.
-
-
-|xref:_ug_reference-annotations_manpage-ParameterLayout_renderedAsDayBefore[`renderedAsDayBefore()`]
-|
-|for date parameters only, render the date as one day prior to the actually stored date (eg the end date of an open interval into a closed interval)
-
-
-|xref:_ug_reference-annotations_manpage-ParameterLayout_typicalLength[`typicalLength()`]
-|
-|the typical entry length of a field, use to determine the optimum width for display
-
-|===
-
-
-
-
-
-For example:
-
-[source,java]
-----
-public class ToDoItem {
- public ToDoItem updateDescription(
- @ParameterLayout(
- cssClass="x-key",
- describedAs="What needs to be done",
- labelPosition=LabelPosition.LEFT,
- named="Description of this <i>item</i>",
- namedEscaped=false,
- typicalLength=80)
- final String description) {
- setDescription(description);
- return this;
- }
- ...
-}
-----
-
-
-
-[NOTE]
-====
-Note that there is (currently) no support for specifying UI hints for domain services through the dynamic xref:_ug_reference-object-layout_dynamic[`.layout.json`] file (only for properties, collections and actions are supported).
-====
-
-
-
-include::_ug_reference-annotations_manpage-ParameterLayout_cssClass.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-ParameterLayout_describedAs.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-ParameterLayout_labelPosition.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-ParameterLayout_multiLine.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-ParameterLayout_named.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-ParameterLayout_renderedAsDayBefore.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-ParameterLayout_typicalLength.adoc[leveloffset=+1]
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout_cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout_cssClass.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout_cssClass.adoc
deleted file mode 100644
index 4404db4..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout_cssClass.adoc
+++ /dev/null
@@ -1,29 +0,0 @@
-[[_ug_reference-annotations_manpage-ParameterLayout_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()` attribute can be used to render additional CSS classes in the HTML (a wrapping `<div>`) that represents the action parameter. xref:_ug_runtime_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:_ug_reference-annotations_manpage-DomainObjectLayout_cssClass[domain objects], xref:_ug_reference-annotations_manpage-ViewModelLayout_cssClass[view models], xref:_ug_reference-annotations_manpage-ActionLayout_cssClass[actions] xref:_ug_reference-annotations_manpage-PropertyLayout_cssClass[properties], xref:_ug_reference-annotations_manpage-CollectionLayout_cssClass[collections] and xref:_ug_reference-annotations_manpage-ParameterLayout_cssClass[parameters].
-
-For example:
-
-[source,java]
-----
-public class ToDoItem {
- public ToDoItem postpone(
- @ParameterLayout(
- named="until",
- cssClass="x-key"
- )
- LocalDate until
- ) { ... }
- ...
-}
-----
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout_describedAs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout_describedAs.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout_describedAs.adoc
deleted file mode 100644
index e130350..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout_describedAs.adoc
+++ /dev/null
@@ -1,38 +0,0 @@
-[[_ug_reference-annotations_manpage-ParameterLayout_describedAs]]
-= `describedAs()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `describedAs()` attribute is used to provide a short description of the action parameter to the user. In the xref:_ug_wicket-viewer[Wicket viewer] it is displayed as a 'tool tip'. The `describedAs()` attribute can also be specified for xref:_ug_reference-annotations_manpage-CollectionLayout_describedAs[collections], xref:_ug_reference-annotations_manpage-PropertyLayout_describedAs[properties], xref:_ug_reference-annotations_manpage-ActionLayout_describedAs[actions], xref:_ug_reference-annotations_manpage-DomainObjectLayout_describedAs[domain objects] and xref:_ug_reference-annotations_manpage-ViewModelLayout_describedAs[view models].
-
-Descriptions may be provided for objects, members (properties,
-collections and actions), and for individual parameters within an action
-method. `@DescribedAs` therefore works in a very similar manner to
-`@Named` <!--(see ?)-->.
-
-
-To provide a description for an individual action parameter, use the
-`@DescribedAs` annotation in-line i.e. immediately before the parameter
-declaration.
-
-For example:
-
-[source,java]
-----
-public class Customer {
- public Order placeOrder(
- Product product,
- @ParameterLayout(
- named="Quantity",
- describedAs="The quantity of the product being ordered"
- )
- int quantity) {
- ...
- }
- ...
-}
-----
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout_labelPosition.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout_labelPosition.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout_labelPosition.adoc
deleted file mode 100644
index 72e1005..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout_labelPosition.adoc
+++ /dev/null
@@ -1,41 +0,0 @@
-[[_ug_reference-annotations_manpage-ParameterLayout_labelPosition]]
-= `labelPosition()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `labelPosition()` attribute determines the positioning of labels for parameters. This attribute can also be specified for xref:_ug_reference-annotations_manpage-PropertyLayout_labelPosition[properties].
-
-The positioning of labels is typically `LEFT`, but can be positioned to the `TOP`. The one exception is xref:_ug_reference-annotations_manpage-ParameterLayout_multiLine[`multiLine()`] string parameters, where the label defaults to `TOP` automatically (to provide as much real-estate for the multiline text field as possible).
-
-For boolean parameters a positioning of `RIGHT` is also allowed; this is ignored for all other types.
-
-It is also possible to suppress the label altogether, using `NONE`.
-
-For example:
-
-[source,java]
-----
-public class Order {
- public Order changeStatus(
- OrderStatus newStatus
- @Parameter(
- optionality=Optionality.OPTIONAL
- )
- @ParameterLayout(
- named="Reason",
- labelPosition=LabelPosition.TOP
- )
- String reason) {
- ...
- }
- ...
-}
-----
-
-
-To get an idea of how these are rendered (in the xref:_ug_wicket-viewer[Wicket viewer]), see xref:_ug_reference-annotations_manpage-PropertyLayout_labelPosition[PropertyLayout#labelPosition()].
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout_multiLine.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout_multiLine.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout_multiLine.adoc
deleted file mode 100644
index 535efc8..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ParameterLayout_multiLine.adoc
+++ /dev/null
@@ -1,32 +0,0 @@
-[[_ug_reference-annotations_manpage-ParameterLayout_multiLine]]
-= `multiLine()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `multiLine()` attribute specifies that the text field for a string parameter should span multiple lines. It is ignored for other parameter types. The attribute is also supported for xref:_ug_reference-annotations_manpage-PropertyLayout_multiLine[properties].
-
-For example:
-
-[source,java]
-----
-public class BugReport {
- public BugReport updateStepsToReproduce(
- @Parameter(named="Steps")
- @ParameterLayout(
- numberOfLines=10
- )
- final String steps) {
- ...
- }
- ...
-}
-----
-
-[NOTE]
-====
-If set > 1 (as would normally be the case), then the default xref:_ug_reference-annotations_manpage-ParameterLayout_labelPosition[`labelPosition`] defaults to `TOP` (rather than `LEFT`, as would normally be the case).
-====
-
[39/45] isis git commit: ISIS-1133: breaking out reference guide and
devenv guide;
moving appendices' release notes and migration notes to other docs;
improving the documentation page.
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Property_mustSatisfy.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Property_mustSatisfy.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Property_mustSatisfy.adoc
new file mode 100644
index 0000000..4d2ad97
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Property_mustSatisfy.adoc
@@ -0,0 +1,46 @@
+[[_rg_annotations_manpage-Property_mustSatisfy]]
+= `mustSatisfy()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `mustSatisfy()` attribute allows arbitrary validation to be applied to properties using an (implementation of a) `org.apache.isis.applib.spec.Specification` object.
+ The attribute is also supported on xref:rg.adoc#_rg_annotations_manpage-Parameter_mustSatisfy[parameters].
+
+[TIP]
+====
+The specification implementations can (of course) be reused between properties and xref:rg.adoc#_rg_annotations_manpage-Parameter_mustSatisfy[parameters].
+====
+
+The `Specification` is consulted during validation, being passed the proposed value. If the proposed value fails, then the value returned is the used as the invalidity reason.
+
+For example:
+
+[source,java]
+----
+public class StartWithCapitalLetterSpecification
+ extends AbstractSpecification<String> { // <1>
+ 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 {
+ @MustSatisfy(StartWithCapitalLetterSpecification.class)
+ public String getFirstName() { ... }
+ ...
+}
+----
+<1> the `AbstractSpecification` class conveniently handles type-safety and dealing with null values. The applib also provides `SpecificationAnd` and `SpecificationOr` to allow specifications to be combined "algebraically".
+
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Property_notPersisted.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Property_notPersisted.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Property_notPersisted.adoc
new file mode 100644
index 0000000..dde2cd7
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Property_notPersisted.adoc
@@ -0,0 +1,61 @@
+[[_rg_annotations_manpage-Property_notPersisted]]
+= `notPersisted()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 (somewhat misnamed) `notPersisted()` attribute indicates that the collection should be excluded from any snapshots generated by the xref:rg.adoc#_rg_services-api_manpage-XmlSnapshotService[`XmlSnapshotService`]. This attribute is also supported for xref:rg.adoc#_rg_annotations_manpage-Collection_notPersisted[collections].
+
+
+[WARNING]
+====
+This annotation does _not_ specify that a property is not persisted in the JDO/DataNucleus objectstore. See below for details as to how to additionally annotate the property for this.
+====
+
+
+For example:
+
+[source,java]
+----
+public class Order {
+ @Property(notPersisted=true)
+ public Order getPreviousOrder() {...}
+ public void setPreviousOrder(Order previousOrder) {...}
+ ...
+}
+----
+
+Historically this annotation also hinted as to whether the property's value contents should be persisted in the object store. However, the JDO/DataNucleus objectstore does not recognize this annotation. Thus, to ensure that a property is actually not persisted, it should *also* be annotated with `@javax.jdo.annotations.NotPersistent`.
+
+For example:
+
+[source,java]
+----
+public class Order {
+ @Property(notPersisted=true) // <1>
+ @javax.jdo.annotations.NotPersistent // <2>
+ public Order getPreviousOrder() {...}
+ public void setPreviousOrder(Order previousOrder) {...}
+ ...
+}
+----
+<1> ignored by Isis
+<2> ignored by JDO/DataNucleus
+
+
+
+
+
+Alternatively, if the property is derived, then providing only a "getter" will also work:
+
+[source,java]
+----
+public class Order {
+ public Order getPreviousOrder() {...}
+ ...
+}
+----
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Property_optionality.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Property_optionality.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Property_optionality.adoc
new file mode 100644
index 0000000..a0d371f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Property_optionality.adoc
@@ -0,0 +1,129 @@
+[[_rg_annotations_manpage-Property_optionality]]
+= `optionality()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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, Apache Isis assumes that all properties of an domain object or view model are required (mandatory). The `optionality()` attribute allows this to be relaxed. The attribute is also supported for xref:rg.adoc#_rg_annotations_manpage-Parameter_optionality[parameters].
+
+That said, properties are most commonly defined on persistent domain objects (entities), in which case the JDO xref:rg.adoc#_rg_annotations_manpage-Column[`@Column`] should be specified. Isis can infer the maxLength directly from the equivalent @Column#length() annotation.
+
+That said, properties are most commonly defined on persistent domain objects (entities), in which case the JDO xref:rg.adoc#_rg_annotations_manpage-Column[`@Column`] will in any case need to be specified. Isis can infer the `optionality` semantic directly from the equivalent `@Column#allowNulls()` annotation/attribute.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ @javax.jdo.annotations.Column(allowNulls="true")
+ public String getMiddleInitial() { ... }
+ public void setMiddleInitial(String middleInitial) { ... }
+ ...
+}
+----
+
+In this case there is no need for the `@Property#optionality()` attribute.
+
+
+== Mismatched defaults
+
+If the `@Column#allowNulls()` attribute is omitted and the `@Property#optionality() attribute is also omitted, then note that Isis' defaults and JDO's defaults differ. Specifically, Isis always assumes properties are mandatory, whereas JDO specifies that primitives are mandatory, but all reference types are optional.
+
+When Isis initializes it checks for these mismatches during its metamodel validation phase, and will fail to boot ("fail-fast") if there is a mismatch. The fix is usually to add the `@Column#allowsNulls()` annotation/attribute.
+
+
+== Superclass inheritance type
+
+There is one case (at least) it may be necessary to annotate the property with both `@Column#allowsNull` and also `@Property#optionality()`. If the property is logically mandatory and is in a subclass, but the mapping of the class hierarchy is to store both the superclass and subclass(es) into a single table (ie a "roll-up" mapping using `javax.jdo.annotations.InheritanceStrategy#SUPERCLASS_TABLE`), then JDO requires that the property is annotated as `@Column#allowsNull="true"`: its value will be not defined for other subclasses.
+
+In this case we therefore require both annotations.
+
+[source,java]
+----
+@javax.jdo.annotations.PersistenceCapable
+@javax.jdo.annotations.Inheritance(strategy = InheritanceStrategy.NEW_TABLE)
+public abstract class PaymentMethod {
+ ...
+}
+@javax.jdo.annotations.PersistenceCapable
+@javax.jdo.annotations.Inheritance(strategy = InheritanceStrategy.SUPERCLASS_TABLE)
+public class CreditCardPaymentMethod extends PaymentMethod {
+ private String cardNumber;
+ @javax.jdo.annotations.Column(allowNulls="true")
+ @Property(optionality=Optionality.MANDATORY)
+ public String getCardNumber() { return this.cardNumber; }
+ public void setCardNumber(String cardNumber) { this.cardNumber = cardNumber; }
+ ...
+}
+----
+
+Alternatively, you could rely on the fact that Isis never looks at fields (whereas JDO does) and move the JDO annotation to the field:
+
+[source,java]
+----
+@javax.jdo.annotations.PersistenceCapable
+@javax.jdo.annotations.Inheritance(strategy = InheritanceStrategy.SUPERCLASS_TABLE)
+public class CreditCardPaymentMethod extends PaymentMethod {
+ @javax.jdo.annotations.Column(allowNulls="true")
+ private String cardNumber;
+ public String getCardNumber() { return this.cardNumber; }
+ public void setCardNumber(String cardNumber) { this.cardNumber = cardNumber; }
+ ...
+}
+----
+
+However this at first glance this might be read as eing that the property is optional whereas Isis' default (required) applies. Also, in the future Isis may be extended to support reading annotations from fields.
+
+
+
+== Non-persistent properties
+
+Of course, not every property is persistent (it could instead be derived), and neither is every domain object an entity (it could be a view model). For these non persistable properties the `optionality()` attribute is still required.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ @javax.jdo.annotation.NotPersistent // <1>
+ @Property(optionality=Optionality.OPTIONAL)
+ public String getFullName() { ... } // <2>
+ public void setFullName(String fullName) { ... } // <3>
+ ...
+}
+----
+<1> a non persisted (derived) property
+<2> implementation would most likely derive full name from constituent parts (eg first name, middle initial, last name)
+<3> implementation would most likely parse the input and update the constituent parts
+
+
+[TIP]
+====
+The attribute has no meaning for a primitive type such as `int`: primitives will always have a default value (e.g. zero). If optionality is required, then use the corresponding wrapper class (e.g. `java.lang.Integer`) and annotate with `Parameter#optionality()` as required.
+====
+
+The values for the attribute are simply `OPTIONAL` or `MANDATORY`.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ public Order placeOrder(
+ final Product product,
+ @ParameterLayout(named = "Quantity")
+ final int quantity,
+ @Parameter(optionality = Optionality.OPTIONAL)
+ @ParameterLayout(named = "Special Instructions")
+ final String instr) {
+ ...
+ }
+ ...
+}
+----
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Property_regexPattern.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Property_regexPattern.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Property_regexPattern.adoc
new file mode 100644
index 0000000..a9cdb7b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Property_regexPattern.adoc
@@ -0,0 +1,28 @@
+[[_rg_annotations_manpage-Property_regexPattern]]
+= `regexPattern()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `regexPattern()` attribute validates the contents of any string property with respect to a regular expression pattern. It is ignored if applied to properties of any other type. This attribute can also be specified for xref:rg.adoc#_rg_annotations_manpage-Parameter_regexPattern[parameters].
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ @Property(
+ regexPattern = "(\\w+\\.)*\\w+@(\\w+\\.)+[A-Za-z]+",
+ regexPatternFlags=Pattern.CASE_INSENSITIVE
+ )
+ public String getEmail() { ... }
+}
+----
+
+
+
+The related `regexPatternFlags()` attribute specifies flags that modify the handling of the pattern. The values are those that would normally be passed to `java.util.regex.Pattern#compile(String,int)`.
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-RequestScoped.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-RequestScoped.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-RequestScoped.adoc
new file mode 100644
index 0000000..a8a503e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-RequestScoped.adoc
@@ -0,0 +1,50 @@
+[[_rg_annotations_manpage-RequestScoped]]
+= `@RequestScoped` (`javax`)
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@javax.enterprise.context.RequestScoped` link:https://jcp.org/en/jsr/detail?id=299[JSR-299] CDI annotation is used to specify that a xref:rg.adoc#_rg_annotations_manpage-DomainService[domain service] should be request-scoped rather than a singleton.
+
+Although Isis does not (currently) leverage CDI, the semantics are the same as request-scoped service; a new instance is created for each HTTP request, reserved for the exclusive use of all objects interacted with during that request.
+
+One of the built-in domain services that uses this annotation is xref:rg.adoc#_rg_services-api_manpage-Scratchpad[`Scratchpad`], intended to allow the arbitrary sharing of data between objects. Here is the full source code of this service is:
+
+
+[source,java]
+----
+@DomainService(
+ nature = NatureOfService.DOMAIN
+)
+@RequestScoped
+public class Scratchpad {
+ private final Map<Object, Object> userData = Maps.newHashMap(); // <1>
+ @Programmatic
+ public Object get(Object key) {
+ return userData.get(key); // <2>
+ }
+ @Programmatic
+ public void put(Object key, Object value) {
+ userData.put(key, value); // <3>
+ }
+ @Programmatic
+ public void clear() {
+ userData.clear(); // <4>
+ }
+}
+----
+<1> Provides a mechanism for each object being acted upon to pass data to the next object.
+<2> Obtain user-data, as set by a previous object being acted upon.
+<3> Set user-data, for the use of a subsequent object being acted upon.
+<4> Clear any user data.
+
+
+The vast majority of domain services in Isis tend to be singletons (which requires no special annotation); but as you can see setting up request-scoped services is very straightforward.
+
+[NOTE]
+====
+Behind the covers Isis creates a (singleton) wrapper for the domain service; the individual request-scoped instances are held in a thread-local of this wrapper. One consequence of this implementation is that request-scoped methods should not be marked as `final`.
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Title.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Title.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Title.adoc
new file mode 100644
index 0000000..253e9f3
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Title.adoc
@@ -0,0 +1,38 @@
+[[_rg_annotations_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/
+
+
+The `@Title` annotation is used to indicate which property or properties make up the object title. If more than one property is used, the order can be specified (using the same Dewey-decimal notation as used by `@MemberOrder`) and the string to use between the components can also be specified.
+
+For example:
+
+[source,java]
+----
+public void Customer {
+ @Title(sequence="1.0")
+ public String lastName() { ... }
+ ...
+ @Title(sequence="1.5", prepend=", ")
+ public String firstName() { ... }
+ ...
+ @Title(sequence="1.7", append=".")
+ public String midInitial() { ... }
+ ...
+}
+----
+
+could be used to create names of the style "Bloggs, Joe K."
+
+It is also possible to annotate reference properties; in this case the
+title will return the title of the referenced object (rather than, say,
+its string representation).
+
+An additional convention for `@Title` properties is that they are hidden
+in tables (in other words, it implies `@Hidden(where=Where.ALL_TABLES)`.
+For viewers that support this annotation (for example, the Wicket
+viewer), this convention excludes any properties whose value is already
+present in the title column. This convention can be overridden using
+`@Hidden(where=Where.NOWHERE)`.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ViewModel.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ViewModel.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ViewModel.adoc
new file mode 100644
index 0000000..a06df8a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ViewModel.adoc
@@ -0,0 +1,44 @@
+[[_rg_annotations_manpage-ViewModel]]
+= `@ViewModel`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@ViewModel` annotation, applied to a class, is the simplest way to indicate that the class is a view model.
+
+View models are not persisted to the database, instead their state is encoded within their identity (ultimately
+represented in the URL). As such, view models are immutable.
+
+For example:
+
+[source,java]
+----
+@ViewModel
+public class MyViewModel {
+ public MyViewModel() {} // <1>
+ ...
+}
+----
+<1> must have a no-arg constructor for subsequent "recreation" by the framework.
+
+
+To instantiate a view model, you can either instantiate directly using its constructor, or indirectly using `DomainObjectContainer#newTransientInstance()`. If you use the former, also programmatically call `DomainObjectContainer#injectServicesInto(...)` to ensure that any dependencies are injected into the service.
+
+
+[TIP]
+====
+Note that there is a `DomainObjectContainer#newViewModelInstance(.)`; this is for view models that implement `ViewModel` interface and can be safely ignored.
+====
+
+
+The view model's memento will be derived from the value of the view model object's properties. Any xref:rg.adoc#_rg_annotations_manpage-Property_notPersisted[`@Property#notPersisted()`] properties will be excluded from the memento, as will any http://isis.apache.org/reference/recognized-annotations/Programmatic.html[@Programmatic] properties. Properties that are merely http://isis.apache.org/reference/recognized-annotations/Hidden-deprecated.html[@Hidden] are included in the memento.
+
+Only properties supported by the configured xref:rg.adoc#_rg_services-api_manpage-MementoService[`MementoService`] can be used. The default implementation supports all the value types and persisted entities.
+
+(As of 1.8.0) there are some limitations:
+* view models cannot hold collections other view models (simple properties _are_ supported, though)
+* collections (of either view models or entities) are ignored.
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ViewModelLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ViewModelLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ViewModelLayout.adoc
new file mode 100644
index 0000000..33f8922
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ViewModelLayout.adoc
@@ -0,0 +1,102 @@
+[[_rg_annotations_manpage-ViewModelLayout]]
+= `@ViewModelLayout`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@ViewModelLayout` annotation is identical to the xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout[`@DomainObjectLayout`], but is provided
+for symmetry with domain objects that have been annotated using xref:rg.adoc#_rg_annotations_manpage-ViewModel[`@ViewModel`] (rather than xref:rg.adoc#_rg_annotations_manpage-DomainObject_nature[`@DomainObject(nature=VIEW_MODEL)`]).
+
+
+The table below summarizes the annotation's attributes.
+
+.`@ViewModel` attributes
+[cols="2,2,4a", options="header"]
+|===
+
+| Attribute
+| Values (default)
+| Description
+
+
+|xref:rg.adoc#_rg_annotations_manpage-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:ug.adoc#_ug_runtime_application-specific_application-css[`application.css`]
+
+
+|xref:rg.adoc#_rg_annotations_manpage-ViewModelLayout_cssClassFa[`cssClassFa()`]
+|Any valid link:http://fortawesome.github.io/Font-Awesome/[Font awesome] icon name
+|specify a font awesome icon for the action's menu link or icon. +
+
+
+|`cssClassFaPosition()`
+|`LEFT`, `RIGHT` +
+(`LEFT`)
+|Currently unused.
+
+
+|xref:rg.adoc#_rg_annotations_manpage-ViewModelLayout_describedAs[`describedAs()`]
+|String.
+|description of this class, eg to be rendered in a tooltip.
+
+
+
+|xref:rg.adoc#_rg_annotations_manpage-ViewModelLayout_named[`named()`]
+|String.
+|to override the name inferred from the action's name in code. +
+
+A typical use case is if the desired name is a reserved Java keyword, such as `default` or `package`.
+
+
+|xref:rg.adoc#_rg_annotations_manpage-ViewModelLayout_paged[`paged()`]
+|Positive integer
+|the page size for instances of this class when rendered within a table (as returned from an action invocation)
+
+
+|xref:rg.adoc#_rg_annotations_manpage-ViewModelLayout_plural[`plural()`]
+|String.
+|the plural name of the class
+
+
+|===
+
+
+
+
+
+For example:
+
+[source,java]
+----
+@ViewModel // <1>
+@ViewModelLayout(
+ cssClass="x-analysis",
+ cssClassFa="fa-piechart",
+ describedAs="Analysis of todo items by category"
+)
+public class CategoryPieChart { ... }
+----
+<1> this annotation is intended for use with `@ViewModel`. If a view model has been specified using the equivalent xref:rg.adoc#_rg_annotations_manpage-DomainObject_nature[`@DomainObject(nature=Nature.VIEW_MODEL)`], then we recommend you use xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout[`@DomainObjectLayout`] instead.
+
+
+[NOTE]
+====
+Note that there is (currently) no support for specifying UI hints for view models through the dynamic xref:rg.adoc#_rg_object-layout_dynamic[`.layout.json`] file (only for properties, collections and actions are supported).
+====
+
+
+
+include::_rg_annotations_manpage-ViewModelLayout_cssClass.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-ViewModelLayout_cssClassFa.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-ViewModelLayout_describedAs.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-ViewModelLayout_named.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-ViewModelLayout_paged.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-ViewModelLayout_plural.adoc[leveloffset=+1]
+
+
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ViewModelLayout_cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ViewModelLayout_cssClass.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ViewModelLayout_cssClass.adoc
new file mode 100644
index 0000000..c2f1173
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ViewModelLayout_cssClass.adoc
@@ -0,0 +1,30 @@
+[[_rg_annotations_manpage-ViewModelLayout_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()` attribute can be used to render additional CSS classes in the HTML (a wrapping `<div>`) that represents the view model. xref:ug.adoc#_ug_runtime_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:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_cssClass[domain objects], xref:rg.adoc#_rg_annotations_manpage-ActionLayout_cssClass[actions] xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_cssClass[properties], xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_cssClass[collections] and xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_cssClass[parameters].
+
+
+For example:
+
+[source,java]
+----
+@ViewModel
+@ViewModelLayout(cssClass="x-analysis")
+public class CategoryPieChart { ... }
+----
+
+
+
+
+[NOTE]
+====
+The similar xref:rg.adoc#_rg_annotations_manpage-ViewModelLayout_cssClassFa[`@ViewModelLayout#cssClassFa()`] annotation attribute is also used as a hint to apply CSS, but in particular to allow http://fortawesome.github.io/Font-Awesome/icons/[Font Awesome icons] to be rendered as the icon for classes.
+====
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ViewModelLayout_cssClassFa.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ViewModelLayout_cssClassFa.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ViewModelLayout_cssClassFa.adoc
new file mode 100644
index 0000000..1a13cd9
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ViewModelLayout_cssClassFa.adoc
@@ -0,0 +1,41 @@
+[[_rg_annotations_manpage-ViewModelLayout_cssClassFa]]
+= `cssClassFa()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `cssClassFa()` attribute is used to specify the name of a link:http://fortawesome.github.io/Font-Awesome/icons/[Font Awesome icon] name, to be rendered as the domain object's icon.
+
+These attribute can also be applied to xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_cssClassFa[domain objects] to specify the object's icon, and to xref:rg.adoc#_rg_annotations_manpage-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.
+
+
+
+
+For example:
+
+[source,java]
+----
+@ViewModel
+@ViewModelLayout(
+ cssClassFa="fa-piechart"
+)
+public class CategoryPieChart { ... }
+----
+
+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.
+
+
+The related `cssClassFaPosition()` attribute is currently unused for domain objects; the icon is always rendered to the left.
+
+
+[NOTE]
+====
+The similar xref:rg.adoc#_rg_annotations_manpage-ViewModelLayout_cssClass[`@ViewModelLayout#cssClass()`] annotation attribute is also used as a hint to apply CSS, but for wrapping the representation of an object or object member so that it can be styled in an application-specific way.
+====
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ViewModelLayout_describedAs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ViewModelLayout_describedAs.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ViewModelLayout_describedAs.adoc
new file mode 100644
index 0000000..351e8d1
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ViewModelLayout_describedAs.adoc
@@ -0,0 +1,23 @@
+[[_rg_annotations_manpage-ViewModelLayout_describedAs]]
+= `describedAs()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `describedAs()` attribute is used to provide a short description of the view model to the user. In the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] it is displayed as a 'tool tip'. The `describedAs()` attribute can also be specified for xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_describedAs[collections], xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_describedAs[properties], xref:rg.adoc#_rg_annotations_manpage-ActionLayout_describedAs[actions], xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_describedAs[parameters] and xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_describedAs[domain objects].
+
+For example:
+
+[source,java]
+----
+@ViewModel
+@ViewModelLayout(
+ cssClass="x-analysis",
+ cssClassFa="fa-piechart",
+ describedAs="Analysis of todo items by category"
+)
+public class CategoryPieChart { ... }
+----
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ViewModelLayout_named.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ViewModelLayout_named.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ViewModelLayout_named.adoc
new file mode 100644
index 0000000..25c6c9c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ViewModelLayout_named.adoc
@@ -0,0 +1,35 @@
+[[_rg_annotations_manpage-ViewModelLayout_named]]
+= `named()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `named()` attribute explicitly specifies the view model's name, overriding the name that would normally be inferred from the Java source code. This attribute can also be specified for xref:rg.adoc#_rg_annotations_manpage-ActionLayout_named[actions], xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_named[collections], xref:rg.adoc#_rg_annotations_manpage-PropertyLayout_named[properties], xref:rg.adoc#_rg_annotations_manpage-ParameterLayout_named[parameters], xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_named[domain objects] and xref:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_named[domain services].
+
+[TIP]
+====
+Following the link:http://en.wikipedia.org/wiki/Don%27t_repeat_yourself[don't repeat yourself] principle, we recommend that you only use this attribute when the desired name cannot be used in Java source code. Examples of that include a name that would be a reserved Java keyword (eg "package"), or a name that has punctuation, eg apostrophes.
+====
+
+
+
+For example:
+
+[source,java]
+----
+@ViewModel
+@ViewModelLayout(
+ named="PieChartAnalysis"
+)
+public class PieChartAnalysisViewModel {
+ ...
+}
+----
+
+
+
+[TIP]
+====
+The framework also provides a separate, powerful mechanism for xref:ug.adoc#_ug_more-advanced_i18n[internationalization].
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ViewModelLayout_paged.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ViewModelLayout_paged.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ViewModelLayout_paged.adoc
new file mode 100644
index 0000000..a04a100
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ViewModelLayout_paged.adoc
@@ -0,0 +1,34 @@
+[[_rg_annotations_manpage-ViewModelLayout_paged]]
+= `paged()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `paged()` attribute specifies the number of rows to display in a standalone collection, as returned from an action invocation. This attribute can also be applied to xref:rg.adoc#_rg_annotations_manpage-CollectionLayout_paged[collections] and xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_paged[domain objects].
+
+
+
+[WARNING]
+====
+The xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer] currently does not support paging. The xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] _does_ support paging, but note that the paging is performed client-side rather than server-side.
+
+We therefore recommend that large collections should instead be modelled as actions (to allow filtering to be applied to limit the number of rows).
+====
+
+
+For example:
+
+[source,java]
+----
+@ViewModel
+@ViewModelLayout(paged=15)
+public class OrderAnalysis {
+ ...
+}
+----
+
+
+It is also possible to specify a global default for the page size of standalone collections, using the xref:ug.adoc#_ug_runtime_configuring-core[configuration property] `isis.viewer.paged.standalone`.
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ViewModelLayout_plural.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ViewModelLayout_plural.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ViewModelLayout_plural.adoc
new file mode 100644
index 0000000..b5cb7ac
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-ViewModelLayout_plural.adoc
@@ -0,0 +1,24 @@
+[[_rg_annotations_manpage-ViewModelLayout_plural]]
+= `plural()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 Apache Isis displays a standalone collection of several objects, it will label the collection using the plural form of the object type.
+
+By default the plural name will be derived from the end of the singular name, with support for some basic English language defaults (eg using "ies" for names ending with a "y").
+
+The `plural()` attribute allows the plural form of the class name to be specified explicitly. This attribute is also supported for xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_plural[domain objects].
+
+For example:
+
+[source,java]
+----
+@ViewModel
+@ViewModelLayout(plural="Children")
+public class Child {
+ ...
+}
+----
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..c822899
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_classes.adoc
@@ -0,0 +1,14 @@
+[[_rg_classes]]
+= 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/
+
+IMPORTANT: TODO
+
+
+include::_rg_classes_super.adoc[leveloffset=+1]
+include::_rg_classes_value-types.adoc[leveloffset=+1]
+include::_rg_classes_utility.adoc[leveloffset=+1]
+include::_rg_classes_mixins.adoc[leveloffset=+1]
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_classes_mixins.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_mixins.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_mixins.adoc
new file mode 100644
index 0000000..bc7995e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_mixins.adoc
@@ -0,0 +1,56 @@
+[[_rg_classes_mixins]]
+= Mixins
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 like "mix-ins"; they allow domain services to contribute actions/properties/collections to any domain objects that implement these interfaces.
+
+
+
+== `HasTransactionId`
+
+The `HasTransactionId` interface is a mix-in for any domain objects that pertain
+
+[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`)
+
+
+== `HasUsername`
+
+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/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_classes_mixins_manpage-HasTransactionId.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_mixins_manpage-HasTransactionId.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_mixins_manpage-HasTransactionId.adoc
new file mode 100644
index 0000000..4f784fc
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_mixins_manpage-HasTransactionId.adoc
@@ -0,0 +1,9 @@
+[[_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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_classes_mixins_manpage-HasUserName.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_mixins_manpage-HasUserName.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_mixins_manpage-HasUserName.adoc
new file mode 100644
index 0000000..0a35aaa
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_mixins_manpage-HasUserName.adoc
@@ -0,0 +1,9 @@
+[[_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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..c22efa6
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super.adoc
@@ -0,0 +1,136 @@
+[[_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/
+
+IMPORTANT: TODO
+
+
+The table below summarizes all the convenience superclasses defined by Apache Isis.
+
+.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-AbstractDomainEvent[`o.a.i.applib.` +
+`AbstractDomainEvent`]
+|``o.a.i.core`` +
+``services.eventbus`` +
+``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-AbstractViewModel[`o.a.i.applib.` +
+`AbstractViewModel`]
+|``o.a.i.core`` +
+``isis-core-applib``
+|(abstract class)
+|
+
+
+|xref:rg.adoc#_rg_classes_super_manpage-ActionDomainEvent[`o.a.i.applib.` +
+`ActionDomainEvent`]
+|``o.a.i.core`` +
+``services.eventbus`` +
+``isis-core-applib``
+|(abstract class)
+|
+
+
+|xref:rg.adoc#_rg_classes_super_manpage-CollectionDomainEvent[`o.a.i.applib.` +
+`CollectionDomainEvent`]
+|``o.a.i.core`` +
+``services.eventbus`` +
+``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)
+|depends on: +
+`ClassDiscoveryService`
+
+
+|xref:rg.adoc#_rg_classes_super_manpage-PropertyDomainEvent[`o.a.i.applib.` +
+`PropertyDomainEvent`]
+|``o.a.i.core`` +
+``services.eventbus`` +
+``isis-core-applib``
+|(abstract class)
+|
+
+
+
+|===
+
+
+
+
+include::_rg_classes_super_manpage-AbstractContainedObject.adoc[leveloffset=+1]
+include::_rg_classes_super_manpage-AbstractDomainEvent.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-AbstractViewModel.adoc[leveloffset=+1]
+include::_rg_classes_super_manpage-ActionDomainEvent.adoc[leveloffset=+1]
+include::_rg_classes_super_manpage-CollectionDomainEvent.adoc[leveloffset=+1]
+include::_rg_classes_super_manpage-FixtureScript.adoc[leveloffset=+1]
+include::_rg_classes_super_manpage-FixtureScripts.adoc[leveloffset=+1]
+include::_rg_classes_super_manpage-PropertyDomainEvent.adoc[leveloffset=+1]
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..6b9e85f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractContainedObject.adoc
@@ -0,0 +1,9 @@
+[[_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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractDomainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractDomainEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractDomainEvent.adoc
new file mode 100644
index 0000000..7d6ef54
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractDomainEvent.adoc
@@ -0,0 +1,9 @@
+[[_rg_classes_super_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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..5a6a205
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractDomainObject.adoc
@@ -0,0 +1,9 @@
+[[_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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractDomainService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractDomainService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractDomainService.adoc
new file mode 100644
index 0000000..2b17a4e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractDomainService.adoc
@@ -0,0 +1,9 @@
+[[_rg_classes_super_manpage-AbstractDomainService]]
+= `AbstractDomainService`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..ea81a65
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractFactoryAndRepository.adoc
@@ -0,0 +1,9 @@
+[[_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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..a6242cb
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractService.adoc
@@ -0,0 +1,9 @@
+[[_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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..79d45c6
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractViewModel.adoc
@@ -0,0 +1,9 @@
+[[_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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-ActionDomainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-ActionDomainEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-ActionDomainEvent.adoc
new file mode 100644
index 0000000..14e15c8
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-ActionDomainEvent.adoc
@@ -0,0 +1,9 @@
+[[_rg_classes_super_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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-CollectionDomainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-CollectionDomainEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-CollectionDomainEvent.adoc
new file mode 100644
index 0000000..2848ef8
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-CollectionDomainEvent.adoc
@@ -0,0 +1,9 @@
+[[_rg_classes_super_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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..8ed412f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-FixtureScript.adoc
@@ -0,0 +1,9 @@
+[[_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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..2b4f150
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-FixtureScripts.adoc
@@ -0,0 +1,9 @@
+[[_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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-PropertyDomainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-PropertyDomainEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-PropertyDomainEvent.adoc
new file mode 100644
index 0000000..c6140ef
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-PropertyDomainEvent.adoc
@@ -0,0 +1,9 @@
+[[_rg_classes_super_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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..2f75c75
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_utility.adoc
@@ -0,0 +1,15 @@
+[[_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/9c5dafab/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
new file mode 100644
index 0000000..338e38b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_utility_manpage-Enums.adoc
@@ -0,0 +1,8 @@
+[[_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/
+
+
+IMPORTANT: TODO
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..241af3c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_utility_manpage-ObjectContracts.adoc
@@ -0,0 +1,107 @@
+[[_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 entities:
+
+ Party <->* AgreementRole <*-> Agreement
+
+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/9c5dafab/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
new file mode 100644
index 0000000..5b35b29
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_utility_manpage-Reasons.adoc
@@ -0,0 +1,31 @@
+[[_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/9c5dafab/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
new file mode 100644
index 0000000..fe0f05c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_utility_manpage-TitleBuffer.adoc
@@ -0,0 +1,13 @@
+[[_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()`.
+
+
+
[32/45] isis git commit: ISIS-1133: breaking out reference guide and
devenv guide;
moving appendices' release notes and migration notes to other docs;
improving the documentation page.
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..7e73413
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_your-apps.adoc
@@ -0,0 +1,37 @@
+[[_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/
+
+
+IMPORTANT: TODO
+
+== Decoupled
+
+IMPORTANT: TODO
+
+Long-term Cost of ownership
+
+Using:
+
+* 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
+
+IMPORTANT: TODO - behaviourally Complete vs Contributions
+
+
+== Testable
+
+IMPORTANT: WIP
+
+While Apache Isis can be used (very effectively) for simple CRUD-style applications, it is also intended to be used for complex business domains. Ensuring that the business logic in such applications is correct means that the framework must (and does) provide robust testing support, both for developer-level unit testing and business-level (end-to-end) integration testing.
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_deployment.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_deployment.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_deployment.adoc
new file mode 100644
index 0000000..97e9e8b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_deployment.adoc
@@ -0,0 +1,19 @@
+[[_ug_deployment]]
+= Deployment
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+This chapter provides guidance on some common deployment scenarios.
+
+include::_ug_deployment_cmd-line.adoc[leveloffset=+1]
+include::_ug_deployment_tomcat.adoc[leveloffset=+1]
+include::_ug_deployment_externalized-configuration.adoc[leveloffset=+1]
+include::_ug_deployment_gae.adoc[leveloffset=+1]
+include::_ug_deployment_neo4j.adoc[leveloffset=+1]
+include::_ug_deployment_jvm-flags.adoc[leveloffset=+1]
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_deployment_cmd-line.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_deployment_cmd-line.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_deployment_cmd-line.adoc
new file mode 100644
index 0000000..c55969f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_deployment_cmd-line.adoc
@@ -0,0 +1,30 @@
+[[_ug_deployment_cmd-line]]
+= Command Line
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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
+
+
+## `WebServer` class
+
+`org.apache.isis.WebServer`
+
+For example:
+* `--fixture`
+* `--services`
+
+etc...
+
+
+
+## `Dummy` class
+
+`org.apache.isis.Dummy`
+
+
+etc...
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_deployment_externalized-configuration.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_deployment_externalized-configuration.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_deployment_externalized-configuration.adoc
new file mode 100644
index 0000000..f710b30
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_deployment_externalized-configuration.adoc
@@ -0,0 +1,9 @@
+[[_ug_deployment_externalized-configuration]]
+= Externalized Configuration
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_deployment_gae.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_deployment_gae.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_deployment_gae.adoc
new file mode 100644
index 0000000..d06d75c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_deployment_gae.adoc
@@ -0,0 +1,48 @@
+[[_ug_deployment_gae]]
+= Deploying to Google App Engine
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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
+
+The Google App Engine (GAE) provides a JDO API, meaning that you can deploy Isis onto GAE using the JDO objectstore.
+
+However, GAE is not an RDBMS, and so there are some limitations that it imposes. This page gathers together various hints, tips and workarounds.
+
+
+== Primary Keys and Owned/Unowned Relationships
+
+All entities must have a `@PrimaryKey`. Within GAE, the type of this key matters.
+
+For an entity to be an aggregate root, (ie a root of an GAE entity group), its key must be a `Long`, eg:
+
+Any collection that holds this entity type (eg `ToDoItem#dependencies` holding a collection of `ToDoItem`s) should then be annotated with `@Unowned` (a GAE annotation).
+
+If on the other hand you want the object to be owned (through a 1:m relationship somewhere) by some other root, then use a String:
+
+Note: if you store a relationship with a String key it means that the parent object _owns_ the child, any attempt to change the relationship raise and exception.
+
+
+
+== Custom Types
+
+Currently Isis' `Blob` and `Clob` types and the JODA types (`LocalDate` et al) are _not_ supported in GAE.
+
+Instead, GAE defines a link:https://cloud.google.com/appengine/docs/java/datastore/entities#Properties_and_Value_Types[fixed set of value types], including `BlobKey`. Members of the Isis community have this working, though I haven't seen the code.
+
+The above notwithstanding, Andy Jefferson at DataNucleus tells us:
+
+pass:[<div class="extended-quote-first"><p>]GAE JDO/JPA does support _some_ type conversion, because looking at http://code.google.com/p/datanucleus-appengine/source/browse/trunk/src/com/google/appengine/datanucleus/StoreFieldManager.java#349[StoreFieldManager.java] for any field that is Object-based and not a relation nor Serialized it will call http://code.google.com/p/datanucleus-appengine/source/browse/trunk/src/com/google/appengine/datanucleus/TypeConversionUtils.java#736[TypeConverstionUtils.java] and that looks for a `TypeConverter` (specify `@Extension` with key of "type-converter-name" against a field and value as the `TypeConverter` class) and it should convert it. Similarly when getting the value from the datastore.
+pass:[</p></div>]
+
+On further investigation, it seems that the GAE implementation performs a type check on a `SUPPORTED_TYPES` Java set, in `com.google.appengine.api.datastore.DataTypeUtils`:
+
+[source,java]
+----
+if (!supportedTypes.contains(value.getClass())) {
+ throw new IllegalArgumentException(prefix + value.getClass().getName() + " is not a supported property type.");
+}
+----
+
+We still need to try out Andy's recipe, above.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_deployment_jvm-flags.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_deployment_jvm-flags.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_deployment_jvm-flags.adoc
new file mode 100644
index 0000000..d3edc30
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_deployment_jvm-flags.adoc
@@ -0,0 +1,9 @@
+[[_ug_deployment_jvm-flags]]
+= JVM Flags
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_deployment_neo4j.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_deployment_neo4j.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_deployment_neo4j.adoc
new file mode 100644
index 0000000..ea0b7b1
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_deployment_neo4j.adoc
@@ -0,0 +1,59 @@
+[[_ug_deployment_neo4j]]
+= Neo4J
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 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.
+
+[TIP]
+====
+In addition, the http://github.com/isisaddons/isis-app-neoapp[Isis addons' neoapp] (non-ASF) is configured to run with an embedded Neo4J server running alongside the Isis webapp.
+====
+
+The steps below describe the configuration steps required to update an existing app.
+
+== ConnectionURL
+
+In `persistor.properties`, update the JDO `ConnectionURL` property, eg:
+
+[source,ini]
+----
+isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionURL=neo4j:neo4j_DB
+----
+
+The other connection properties (`ConnectionDriverName`, `ConnectionUserName` and `ConnectionPassword`) should be commented out.
+
+== Update pom.xml
+
+Add the following dependency to the `webapp` project's `pom.xml`:
+
+[source,xml]
+----
+<dependencies>
+ ...
+ <dependency>
+ <groupId>org.datanucleus</groupId>
+ <artifactId>datanucleus-neo4j</artifactId>
+ <version>3.2.3</version> <!--1-->
+ </dependency>
+ ...
+</dependencies>
+----
+<1> for 1.8.0, use the value shown. for 1.9.0-SNAPSHOT, use 4.0.5.
+
+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`.
+
+== 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)
+
+* build the app:
+
+* run the app:
+
+If you visit the about page you should see the neo4j JAR files are linked in, and a `neo4j_DB` subdirectory within the `webapp` directory.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_deployment_tomcat.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_deployment_tomcat.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_deployment_tomcat.adoc
new file mode 100644
index 0000000..6dc82a7
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_deployment_tomcat.adoc
@@ -0,0 +1,35 @@
+[[_ug_deployment_tomcat]]
+= Deploying to Tomcat
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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
+
+
+== Externalized Configuration
+
+IMPORTANT: TODO
+
+
+== JVM Args
+
+IMPORTANT: TODO
+
+
+for the `WrapperFactory` (uses link:http://www.javassist.org[Javassist])
+
+using:
+
+[source,ini]
+----
+-XX:+CMSClassUnloadingEnabled -XX:+UseConcMarkSweepGC
+----
+
+You can hint the JVM to unload dynamically created classes which ClassLoaders are still around.
+
+
+== Using a JNDI Datasource
+
+See the guidance in the xref:ug.adoc#_ug_runtime_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/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_extending.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_extending.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_extending.adoc
new file mode 100644
index 0000000..47c6d81
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_extending.adoc
@@ -0,0 +1,14 @@
+[[_ug_extending]]
+= Extending
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+This chapter explains the main APIs for extending Apache Isis: the programming model conventions, the Wicket viewer, and the Restful Objects viewer.
+
+include::_ug_extending_programming-model.adoc[leveloffset=+1]
+
+include::_ug_extending_wicket-viewer.adoc[leveloffset=+1]
+
+include::_ug_extending_restfulobjects-viewer.adoc[leveloffset=+1]
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_extending_programming-model.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_extending_programming-model.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_extending_programming-model.adoc
new file mode 100644
index 0000000..aad09c6
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_extending_programming-model.adoc
@@ -0,0 +1,13 @@
+[[_ug_extending_programming-model]]
+= Programming Model
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+This section describes three mechanisms you can use to extend or alter the programming conventions that Isis understands to build up its metamodel.
+
+include::_ug_extending_programming-model_custom-validator.adoc[leveloffset=+1]
+include::_ug_extending_programming-model_finetuning.adoc[leveloffset=+1]
+include::_ug_extending_programming-model_layout-metadata-reader.adoc[leveloffset=+1]
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_extending_programming-model_custom-validator.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_extending_programming-model_custom-validator.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_extending_programming-model_custom-validator.adoc
new file mode 100644
index 0000000..ac1d4cd
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_extending_programming-model_custom-validator.adoc
@@ -0,0 +1,107 @@
+[[_ug_extending_programming-model_custom-validator]]
+= Custom validator
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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' programming model includes a validator component that detects and prevents (by failing fast) a number of situations where the domain model is logically inconsistent with itself.
+
+For example, the validator will detect any orphaned supporting methods (eg `hideXxx()`) if the corresponding property or action has been renamed or deleted but the supporting method was not also updated. Another example is that a class cannot have a title specified both using `title()` method and also using `@Title` annotation.
+
+[NOTE]
+====
+The support for xref:rg.adoc#_rg_annotations_aaa_deprecated[disallowing deprecated annotations] is also implemented using the metamodel validator.
+====
+
+You can also impose your own application-specific rules by installing your own metamodel validator. To give just one example, you could impose naming standards such as ensuring that a domain-specific abbreviation such as "ISBN" is always consistently capitalized wherever it appears in a class member.
+
+[TIP]
+====
+Isis' xref:ug.adoc#_ug_isis-maven-plugin[Maven plugin] will also validate the domain object model during build time.
+====
+
+
+== API and Implementation
+
+There are several ways to go about implementing a validator.
+
+=== `MetaModelValidator`
+
+Any custom validator must implement Isis' internal `MetaModelValidator` interface, so the simplest option is just to implement `MetaModelValidator` directly:
+
+
+[source,java]
+----
+public interface MetaModelValidator
+ implements SpecificationLoaderSpiAware { // <1>
+ public void validate(
+ ValidationFailures validationFailures); // <2>
+}
+----
+<1> the `SpecificationLoader` is the internal API providing access to the Isis metamodel.
+<2> add any metamodel violations to the `ValidationFailures` parameter (the link:http://c2.com/cgi/wiki?CollectingParameter[collecting parameter] pattern)
+
+
+=== `Visitor`
+
+More often than not, you'll want to visit every element in the metamodel, and so for this you can instead subclass from `MetaModelValidatorVisiting.Visitor`:
+
+[source,java]
+----
+public final class MetaModelValidatorVisiting ... {
+ public static interface Visitor {
+ public boolean visit( // <1>
+ ObjectSpecification objectSpec, // <2>
+ ValidationFailures validationFailures); // <3>
+ }
+ ...
+}
+----
+<1> return `true` continue visiting specs.
+<2> `ObjectSpecification` is the internal API representing a class
+<3> add any metamodel violations to the `ValidationFailures` parameter
+
+
+You can then create your custom validator by subclassing `MetaModelValidatorComposite` and adding the visiting validator:
+
+[source,java]
+----
+public class MyMetaModelValidator extends MetaModelValidatorComposite {
+ public MyMetaModelValidator() {
+ add(new MetaModelValidatorVisiting(new MyVisitor()));
+ }
+}
+----
+
+If you have more than one rule then each can live in its own visitor.
+
+=== `SummarizingVisitor`
+
+As a slight refinement, you can also subclass from `MetaModelValidatorVisiting.SummarizingVisitor`:
+
+[source,java]
+----
+public final class MetaModelValidatorVisiting ... {
+ public static interface SummarizingVisitor extends Visitor {
+ public void summarize(ValidationFailures validationFailures);
+ }
+ ...
+}
+----
+
+A `SummarizingVisitor` will be called once after every element in the metamodel has been visited. This is great for performing checks on the metamodel as a whole. For example, Isis uses this to check that there is at least one `@Persistable` domain entity defined.
+
+
+
+
+== Configuration
+
+Once you have implemented your validator, you must register it with the framework by defining the appropriate configuration property:
+
+[source,ini]
+----
+isis.reflector.validator=com.mycompany.myapp.MyMetaModelValidator
+----
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_extending_programming-model_finetuning.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_extending_programming-model_finetuning.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_extending_programming-model_finetuning.adoc
new file mode 100644
index 0000000..bc90189
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_extending_programming-model_finetuning.adoc
@@ -0,0 +1,80 @@
+[[_ug_extending_programming-model_finetuning]]
+= Finetuning
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 core metamodel defines APIs and implementations for building the Isis metamodel: a description of the set of entities, domain services and values that make up the domain model.
+
+
+The description of each domain class consists of a number of elements:
+
+https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/core/metamodel/spec/ObjectSpecification.java[ObjectSpecification]::
+Analogous to `java.lang.Class`; holds information about the class itself and holds collections of each of the three types of class' members (below);
+
+https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/core/metamodel/spec/feature/OneToOneAssociation.java[OneToOneAssociation]::
+Represents a class member that is a single-valued property of the class. The property's type is either a reference to another entity, or is a value type.
+
+https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/core/metamodel/spec/feature/OneToManyAssociation.java[OneToManyAssociation]::
+Represents a class member that is a collection of references to other entities. Note that Isis does not currently support collections of values.
+
+https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/core/metamodel/spec/feature/ObjectAction.java[ObjectAction]::
+Represents a class member that is an operation that can be performed on the action. Returns either a single value, a collection of entities, or is `void`.
+
+
+The metamodel is built up through the https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/core/metamodel/progmodel/ProgrammingModel.java[ProgrammingModel], which defines an API for registering a set of https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/core/metamodel/facets/FacetFactory.java[FacetFactory]s. Two special `FacetFactory` implementations - https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/core/metamodel/facets/properties/accessor/PropertyAccessorFacetViaAccessorFactory.java[PropertyAccessorFacetFactory] and https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/core/metamodel/facets/collections/accessor/CollectionAccessorFacetViaAccessorFactory.java[CollectionAccessorFacetFactory] - are used to identify the class members.
+Pretty much all the other ``FacetFactory``s are responsible for installing https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/core/metamodel/facetapi/Facet.java[Facet]s onto the metamodel elements.
+
+There are many many such ``Facet``s, and are used to do such things get values from properties or collections, modify properties or collections, invoke action, hide or disable class members, provide UI hints for class members, and so on. In short, the ``FacetFactory``s registered defines the Isis programming conventions.
+
+
+
+== Modifying the Prog. Model
+
+The default implementation of `ProgrammingModel` is https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/progmodels/dflt/ProgrammingModelFacetsJava5.java[ProgrammingModelFacetsJava5], which registers a large number of ``FacetFactory``s.
+
+By editing `isis.properties` you can modify the programming conventions either by (a) using the default programming model, but tweaking it to include new `FacetFactory`s or exclude existing, or (b) by specifying a completely different programming model implementation.
+
+Let's see how this is done.
+
+=== Including or excluding facets
+
+Suppose that you wanted to completely remove support for the (already deprecated) `@ActionOrder` annotation. This would be done using:
+
+[source,ini]
+----
+isis.reflector.facets.exclude=org.apache.isis.core.metamodel.facets.object.actionorder.annotation.ActionOrderFacetAnnotationFactory
+----
+
+Or, suppose you wanted to use the example https://github.com/apache/isis/blob/master/mothballed/misc/metamodel/namefile/src/main/java/org/apache/isis/example/metamodel/namefile/facets/NameFileFacetFactory.java["namefile"] `FacetFactory` as part of your programming conventions, use:
+
+[source,ini]
+----
+isis.reflector.facets.include=org.apache.isis.example.metamodel.namefile.facets.NameFileFacetFactory
+----
+
+To include/exclude more than one `FacetFactory`, specify as a comma-separated list. And if you want to dig into this in more detail, the code that implements this logic is https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/progmodels/dflt/JavaReflectorInstallerNoDecorators.java[JavaReflectorInstallerNoDecorators].
+
+[TIP]
+====
+This http://isis.markmail.org/thread/472c3mrvcgnripst[thread] from the users mailing list (in Apr 2014) shows a typical customization (to enable per-instance security) (though note that xref:ug.adoc#_ug_more-advanced_multi-tenancy[Multi-Tenancy] is now a better solution to that particular use-case.
+====
+
+
+
+
+== Replacing the Prog. Model
+
+If you want to make many changes to the programming model, then (rather than include/exclude lots of facet factories) you can specify a completely new programming model. For this you'll first need an implementation of `ProgrammingModel`.
+
+One option is to subclass from `ProgammingModelFacetsJava5`; in your subclass you could remove any ``FacetFactory``s that you wanted to exclude, as well as registering your own implementations.
+
+To tell Isis to use your new programming model, use:
+
+[source,ini]
+----
+isis.reflector.facets=com.mycompany.myapp.isis.IsisProgrammingModel
+----
+
+Again, the code that implements this logic is https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/progmodels/dflt/JavaReflectorInstallerNoDecorators.java[JavaReflectorInstallerNoDecorators].
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_extending_programming-model_layout-metadata-reader.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_extending_programming-model_layout-metadata-reader.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_extending_programming-model_layout-metadata-reader.adoc
new file mode 100644
index 0000000..dba6c6d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_extending_programming-model_layout-metadata-reader.adoc
@@ -0,0 +1,44 @@
+[[_ug_extending_programming-model_layout-metadata-reader]]
+= Layout Metadata Reader
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 metadata for domain objects is obtained both xref:rg.adoc#_rg_object-layout_static[statically] and xref:rg.adoc#_rg_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`).
+
+You can also implement your own metadata readers and plug them into Isis. These could read from a different file format, or they could, even, read data dynamically from a URL or database. (Indeed, one could imagine an implementation whereby users could share layouts, all stored in some central repository).
+
+
+
+== API and Implementation
+
+Any reader must implement Isis' internal `LayoutMetadataReader` interface:
+
+[source,java]
+----
+public interface LayoutMetadataReader {
+ public Properties asProperties(Class<?> domainClass) throws ReaderException;
+}
+----
+
+The implementation "simply" returns a set of properties where the property key is a unique identifier to both the class member and also the facet of the class member to which the metadata relates.
+
+See the implementation of the built-in `LayoutMetadataReaderFromJson` for more detail.
+
+
+
+== Configuration
+
+Once you have implemented your validator, you must register it with the framework by defining the appropriate configuration property:
+
+[source,ini]
+----
+isis.reflector.layoutMetadataReaders=\
+ com.mycompany.myapp.MyMetaModelValidator,\
+ org.apache.isis.core.metamodel.layoutmetadata.json.LayoutMetadataReaderFromJson # <1>
+----
+<1> the property replaces any existing metadata readers; if you want to preserve the ability to read from `Xxx.layout.json` then also register Isis' built-in implementation.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_extending_restfulobjects-viewer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_extending_restfulobjects-viewer.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_extending_restfulobjects-viewer.adoc
new file mode 100644
index 0000000..d9a841e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_extending_restfulobjects-viewer.adoc
@@ -0,0 +1,51 @@
+[[_ug_extending_restfulobjects-viewer]]
+= Restful Objects 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:ug.adoc#_ug_restfulobjects-viewer[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 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, 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:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer] to provide a simplified output, as described xref:ug.adoc#_ug_restfulobjects-viewer_configuration-properties_simplified-object-representation[here]. +
++
+If you simply want to suppress certain elements, as described xref:ug.adoc#_ug_restfulobjects-viewer_configuration-properties_suppressing-elements[here].
+
+* `RepresentationService` +
++
+The xref:rg.adoc#_rg_services-spi_manpage-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:rg.adoc#_rg_services-spi_manpage-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:rg.adoc#_rg_services-spi_manpage-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:ug.adoc#_ug_restfulobjects-viewer[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/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_extending_wicket-viewer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_extending_wicket-viewer.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_extending_wicket-viewer.adoc
new file mode 100644
index 0000000..0dda79e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_extending_wicket-viewer.adoc
@@ -0,0 +1,26 @@
+[[_ug_extending_wicket-viewer]]
+= 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/
+
+
+The Wicket viewer allows you to customize the GUI in several (progressively more sophisticated) ways:
+
+* by xref:ug.adoc#_ug_wicket-viewer_customisation_tweaking-css-classes[tweaking the UI using CSS]
+* by xref:ug.adoc#_ug_wicket-viewer_customisation_custom-javascript[tweaking the UI using Javascript]
+* by writing a xref:ug.adoc#_ug_extending_wicket-viewer_custom-bootstrap-theme[custom bootstrap theme]
+* by xref:ug.adoc#_ug_extending_wicket-viewer_replacing-page-elements[replacing elements of the page] using the `ComponentFactory` interface
+* by implementing xref:ug.adoc#_ug_extending_wicket-viewer_custom-pages[replacement page implementations] for the standard page types
+
+The first two of these options are discussed in the <<Wicket Viewer>> chapter. This chapter describes the remaining "heavier-weight/more powerful" options.
+
+
+include::_ug_extending_wicket-viewer_custom-bootstrap-theme.adoc[leveloffset=+1]
+
+include::_ug_extending_wicket-viewer_replacing-page-elements.adoc[leveloffset=+1]
+
+include::_ug_extending_wicket-viewer_custom-pages.adoc[leveloffset=+1]
+
+include::_ug_extending_wicket-viewer_isis-addons-extensions.adoc[leveloffset=+1]
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_extending_wicket-viewer_custom-bootstrap-theme.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_extending_wicket-viewer_custom-bootstrap-theme.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_extending_wicket-viewer_custom-bootstrap-theme.adoc
new file mode 100644
index 0000000..937138c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_extending_wicket-viewer_custom-bootstrap-theme.adoc
@@ -0,0 +1,34 @@
+[[_ug_extending_wicket-viewer_custom-bootstrap-theme]]
+= Custom Bootstrap theme
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 Isis Wicket viewer uses http://getbootstrap.com/[Bootstrap] styles and components (courtesy of the https://github.com/l0rdn1kk0n/wicket-bootstrap[Wicket Bootstrap] integration).
+
+By default the viewer uses the default bootstrap theme. It is possible to configure the Wicket viewer to allow the user to xref:ug.adoc#_ug_wicket-viewer_configuration-properties_showing-theme-chooser[select other themes] provided by http://bootswatch.com[bootswatch.com], and if required one of these can be xref:ug.adoc#_ug_wicket-viewer_customisation_default-theme[set as the default].
+
+However, you may instead want to write your own custom theme, for example to fit your company's look-n-feel/interface guidelines. This is done by implementing https://github.com/l0rdn1kk0n/wicket-bootstrap[Wicket Bootstrap]’s `de.agilecoders.wicket.core.settings.ITheme` class. This defines:
+
+* the name of the theme
+* the resources it needs (the CSS and optional JS and/or fonts), and
+* optional urls to load them from a Content Delivery Network (CDN).
+
+To make use of the custom `ITheme` the application should register it by adding the following snippet in
+(your application's subclass of) `IsisWicketApplication`:
+
+[source,java]
+----
+public void init() {
+ ...
+ IBootstrapSettings settings = new BootstrapSettings();
+ ThemeProvider themeProvider = new SingleThemeProvider(new MyTheme());
+ settings.setThemeProvider(themeProvider);
+ Bootstrap.install(getClass(), settings);
+}
+----
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_extending_wicket-viewer_custom-pages.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_extending_wicket-viewer_custom-pages.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_extending_wicket-viewer_custom-pages.adoc
new file mode 100644
index 0000000..40ba002
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_extending_wicket-viewer_custom-pages.adoc
@@ -0,0 +1,92 @@
+[[_ug_extending_wicket-viewer_custom-pages]]
+= Custom pages
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 the vast majority of cases customization should be sufficient by xref:ug.adoc#_ug_extending_wicket-viewer_replacing-page-elements[replacing elements of a page]. However, it is also possible to define an entirely new page for a given page type.
+
+Isis defines eight page types (see the `org.apache.isis.viewer.wicket.model.models.PageType` enum):
+
+.PageType enum
+[cols="1,4", options="header"]
+|===
+| Page type
+| Renders
+
+| SIGN_IN
+| The initial sign-in (aka login) page
+
+| SIGN_UP
+| The sign-up page (if xref:rg.adoc#_rg_services-spi_manpage-UserRegistrationService[user registration] is enabled).
+
+| SIGN_UP_VERIFY
+| The sign-up verification page (if xref:rg.adoc#_rg_services-spi_manpage-UserRegistrationService[user registration] is enabled; as accessed by link from verification email)
+
+| PASSWORD_RESET
+| The password reset page (if enabled).
+
+| HOME
+| The home page, displaying either the welcome message or dashboard
+
+| ABOUT
+| The about page, accessible from link top-right
+
+| ENTITY
+| Renders a single entity or view model
+
+| STANDALONE_COLLECTION
+| Page rendered after invoking an action that returns a collection of entites
+
+| VALUE
+| After invoking an action that returns a value type (though not URLs or Blob/Clobs, as these are handled appropriately automatically).
+
+| VOID_RETURN
+| After invoking an action that is `void`
+
+| ACTION_PROMPT
+| (No longer used).
+
+|===
+
+
+The `PageClassList` interface declares which class (subclass of `org.apache.wicket.Page` is used to render for each of these types. For example, Isis' `WicketSignInPage` renders the signin page.
+
+To specify a different page class, create a custom subclass of `PageClassList`:
+
+[source,java]
+----
+@Singleton
+public class MyPageClassList extends PageClassListDefault {
+ protected Class<? extends Page> getSignInPageClass() {
+ return MySignInPage.class;
+ }
+}
+----
+
+
+You then need to register your custom `PageClassList`. This is done by adjusting the Guice bindings (part of Isis' bootstrapping) in your custom subclass of `IsisWicketApplication`:
+
+[source,java]
+----
+public class MyAppApplication extends IsisWicketApplication {
+ @Override
+ protected Module newIsisWicketModule() {
+ final Module isisDefaults = super.newIsisWicketModule();
+ final Module myAppOverrides = new AbstractModule() {
+ @Override
+ protected void configure() {
+ ...
+ bind(PageClassList.class).to(MyPageClassList.class);
+ ...
+ }
+ };
+ return Modules.override(isisDefaults).with(myAppOverrides);
+ }
+}
+----
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_extending_wicket-viewer_isis-addons-extensions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_extending_wicket-viewer_isis-addons-extensions.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_extending_wicket-viewer_isis-addons-extensions.adoc
new file mode 100644
index 0000000..46ab3cc
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_extending_wicket-viewer_isis-addons-extensions.adoc
@@ -0,0 +1,17 @@
+[[_ug_extending_wicket-viewer_isis-addons-extensions]]
+= Isis Addons Extensions
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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
+
+[WARNING]
+====
+Note that Isis addons, while maintained by Isis committers, are not part of the ASF.
+====
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_ug_extending_wicket-viewer_replacing-page-elements.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_extending_wicket-viewer_replacing-page-elements.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_extending_wicket-viewer_replacing-page-elements.adoc
new file mode 100644
index 0000000..80f410f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_extending_wicket-viewer_replacing-page-elements.adoc
@@ -0,0 +1,167 @@
+[[_ug_extending_wicket-viewer_replacing-page-elements]]
+= Replacing page elements
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+Replacing elements of the page is the most powerful general-purpose way to customize the look-n-feel of the viewer. Examples at the (non-ASF) http://www.isisaddons.org[Isis Add-ons] include the http://github.com/isisaddons/isis-wicket-gmap3[gmap3] extension, the http://github.com/isisaddons/isis-wicket-fullcalendar2[calendar] extension, the http://github.com/isisaddons/isis-wicket-excel[excel download] and the http://github.com/isisaddons/isis-wicket-wickedcharts[wickedcharts] charting integration.
+
+The pages generated by Isis' Wicket viewer are built up of numerous elements, from fine-grained widgets for property/parameter fields, to much larger components that take responsibility for rendering an entire entity entity, or a collection of entities. Under the covers these are all implementations of the the Apache Wicket `Component` API. The larger components delegate to the smaller, of course.
+
+
+
+
+== How the viewer selects components
+
+Components are created using Isis' `ComponentFactory` interface, which are registered in turn through the `ComponentFactoryRegistrar` interface. Every component is categorizes by type (the `ComponentType` enum), and Isis uses this to determine which `ComponentFactory` to use. For example, the `ComponentType.BOOKMARKED_PAGES` is used to locate the `ComponentFactory` that will build the bookmarked pages panel.
+
+Each factory is also handed a model (an implementation of `org.apache.wicket.IModel`) appropriate to its `ComponentType`; this holds the data to be rendered. For example, `ComponentType.BOOKMARKED_PAGES` is given a `BookmarkedPagesModel`, while `ComponentType.SCALAR_NAME_AND_VALUE` factories are provided a model of type of type `ScalarModel` .
+
+In some cases there are several factories for a given `ComponentType`; this is most notably the case for `ComponentType.SCALAR_NAME_AND_VALUE`. After doing a first pass selection of candidate factories by `ComponentType`, each factory is then asked if it `appliesTo(Model)`. This is an opportunity for the factory to check the model itself to see if the data within it is of the appropriate type.
+
+Thus, the `BooleanPanelFactory` checks that the `ScalarModel` holds a boolean, while the `JodaLocalDatePanelFactory` checks to see if it holds `org.joda.time.LocalDate`.
+
+There will typically be only one `ComponentFactory` capable of rendering a particular `ComponentType`/`ScalarModel` combination; at any rate, the framework stops as soon as one is found.
+
+[NOTE]
+====
+There is one refinement to the above algorithm where multiple component factories might be used to render an object; this is discussed in <<Additional Views of Collections>>, below.
+====
+
+
+
+
+
+== How to replace a component
+
+This design (the http://en.wikipedia.org/wiki/Chain-of-responsibility_pattern[chain of responsibility] design pattern) makes it quite straightforward to change the rendering of any element of the page. For example, you might switch out Isis' sliding bookmark panel and replace it with one that presents the bookmarks in some different fashion.
+
+First, you need to write a `ComponentFactory` and corresponding `Component`. The recommended approach is to start with the source of the `Component` you want to switch out. For example:
+
+[source,java]
+----
+public class MyBookmarkedPagesPanelFactory extends ComponentFactoryAbstract {
+ public MyBookmarkedPagesPanelFactory() {
+ super(ComponentType.BOOKMARKED_PAGES);
+ }
+ @Override
+ public ApplicationAdvice appliesTo(final IModel<?> model) {
+ return appliesIf(model instanceof BookmarkedPagesModel);
+ }
+ @Override
+ public Component createComponent(final String id, final IModel<?> model) {
+ final BookmarkedPagesModel bookmarkedPagesModel = (BookmarkedPagesModel) model;
+ return new MyBookmarkedPagesPanel(id, bookmarkedPagesModel);
+ }
+}
+----
+
+and
+
+[source,java]
+----
+public class MyBookmarkedPagesPanel
+ extends PanelAbstract<BookmarkedPagesModel> {
+ ...
+}
+----
+
+Here `PanelAbstract` ultimately inherits from `org.apache.wicket.Component`.
+Your new `Component` uses the information in the provided model (eg `BookmarkedPagesModel`) to know what to render.
+
+Next, you will require a custom implementation of the `ComponentFactoryRegistrar` that registers your custom `ComponentFactory` as a replacement:
+
+[source,java]
+----
+@Singleton
+public class MyComponentFactoryRegistrar extends ComponentFactoryRegistrarDefault {
+ @Override
+ public void addComponentFactories(ComponentFactoryList componentFactories) {
+ super.addComponentFactories(componentFactories);
+ componentFactories.add(new MyBookmarkedPagesPanelFactory());
+ }
+}
+----
+
+This will result in the new component being used instead of (that is, discovered prior to) Isis' default implementation.
+
+[WARNING]
+====
+Previously we suggested using "replace" rather than "add"; however this has unclear semantics for some component types; see https://issues.apache.org/jira/browse/ISIS-996[ISIS-996].
+====
+
+
+Finally (as for other customizations), you need to adjust the Guice bindings in your custom subclass of `IsisWicketApplication`:
+
+[source,java]
+----
+public class MyAppApplication extends IsisWicketApplication {
+ @Override
+ protected Module newIsisWicketModule() {
+ final Module isisDefaults = super.newIsisWicketModule();
+ final Module myAppOverrides = new AbstractModule() {
+ @Override
+ protected void configure() {
+ ...
+ bind(ComponentFactoryRegistrar.class)
+ .to(MyComponentFactoryRegistrar.class);
+ ...
+ }
+ };
+
+ return Modules.override(isisDefaults).with(myAppOverrides);
+ }
+}
+----
+
+
+
+
+== Additional Views of Collections
+
+As explained above, in most cases Isis' Wicket viewer will search for the first `ComponentFactory` that can render an element, and use it. In the case of (either standalone or parented) collections, though, Isis will show all available views.
+
+For example, out-of-the-box Isis provides a table view, a summary view (totals/sums/averages of any data), and a collapsed view (for `@Render(LAZILY)` collections). These are selected by clicking on the toolbar by each collection.
+
+Additional views though could render the objects in the collection as a variety of ways. Indeed, some third-party implementations already exist:
+
+* https://github.com/isisaddons/isis-wicket-excel[excel integration] (collection as a downloadable excel spreadsheet)
+* https://github.com/isisaddons/isis-wicket-gmap3[google maps v3 integration] (render any objects with a location on a map)
+* https://github.com/isisaddons/isis-wicket-wickedcharts[wicked charts integration] (barchart of any data)
+* https://github.com/isisaddons/isis-wicket-fullcalendar2[full calendar integration] (render any objects with date properties on a calendar)
+
+Registering these custom views is just a matter of adding the appropriate Maven module to the classpath. Isis uses the JDK `ServiceLoader` API to automatically discover and register the `ComponentFactory` of each such component.
+
+If you want to write your own alternative component and auto-register, then include a file `META-INF/services/org.apache.isis.viewer.wicket.ui.ComponentFactory` whose contents is the fully-qualified class name of the custom `ComponentFactory` that you have written.
+
+Wicket itself has lots of components available at its http://wicketstuff.org[wicketstuff.org] companion website; you might find some of these useful for your own customizations.
+
+
+
+
+
+
+== Custom object view (eg dashboard)
+
+One further use case in particular is worth highlighting; the rendering of an entire entity. Normally entities this is done using `EntityCombinedPanelFactory`, this being the first `ComponentFactory` for the `ComponentType.ENTITY` that is registered in Isis default `ComponentFactoryRegistrarDefault`.
+
+You could, though, register your own `ComponentFactory` for entities that is targeted at a particular class of entity - some sort of object representing a dashboard, for example. It can use the `EntityModel` provided to it to determine the class of the entity, checking if it is of the appropriate type. Your custom factory should also be registered before the `EntityCombinedPanelFactory` so that it is checked prior to the default `EntityCombinedPanelFactory`:
+
+[source,java]
+----
+@Singleton
+public class MyComponentFactoryRegistrar extends ComponentFactoryRegistrarDefault {
+ @Override
+ public void addComponentFactories(ComponentFactoryList componentFactories) {
+ componentFactories.add(new DashboardEntityFactory());
+ ...
+ super.addComponentFactories(componentFactories);
+ ...
+ }
+}
+----
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..ae1b334
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_getting-started.adoc
@@ -0,0 +1,37 @@
+[[_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 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 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 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 Isis committers use either IntelliJ or Eclipse; in the xref:ug.adoc#_ug_appendices[appendices] 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/9c5dafab/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
new file mode 100644
index 0000000..54184a0
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_getting-started_datanucleus-enhancer.adoc
@@ -0,0 +1,107 @@
+[[_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 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-SNAPSHOT, 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.0-release</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:dg.adoc#_dg_eclipse[here].
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
new file mode 100644
index 0000000..95ebb1b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_getting-started_simpleapp-archetype.adoc
@@ -0,0 +1,300 @@
+[[_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 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.8.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 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.9.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 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:ug.adoc#_ug_wicket-viewer[Wicket viewer] and the xref:ug.adoc#_ug_restfulobjects-viewer[Restful Objects viewer]. The archetype also configures the [JDO Objectstore](../../components/objectstores/jdo/about.html) 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 appendices for details on xref:dg.adoc#_dg_eclipse[setting up Eclipse] or xref:dg.adoc#_dg_intellij[setting up 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:ug.adoc#_ug_testing_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:ug.adoc#_ug_wicket-viewer[Wicket viewer] or the xref:ug.adoc#_ug_restfulobjects-viewer[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:ug.adoc#_ug_security[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 [documentation](../../documentation.html) page first).
+
+If you use Eclipse or IntelliJ IDEA, do also install the [Eclipse templates](../resources/editor-templates.html); these will help you follow the 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 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.
+
+<table class="table table-striped table-bordered table-condensed">
+<tr><th>Module</th><th>Description</th></tr>
+<tr><td>myapp</td><td>The parent (aggregator) module</td></tr>
+<tr><td>myapp-dom</td><td>The domain object model, consisting of <tt>SimpleObject</tt> and <tt>SimpleObjects</tt> (repository) domain service.</td></tr>
+<tr><td>myapp-fixture</td><td>Domain object fixtures used for initializing the system when being demo'ed or for unit testing.</td></tr>
+<tr><td>myapp-integtests</td><td>End-to-end <a href="../../core/integtestsupport.html">integration tests</a>, that exercise from the UI through to the database</td></tr>
+<tr><td>myapp-webapp</td><td>Run as a webapp (from <tt>web.xml</tt>) using either the Wicket viewer or the Restful Objects viewer</td></tr>
+</table>
+
+If you run into issues, please don't hesitate to ask for help on the [users mailing list](../../support.html).
[17/45] isis git commit: ISIS-1133: breaking out reference guide and
devenv guide;
moving appendices' release notes and migration notes to other docs;
improving the documentation page.
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa_partial.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa_partial.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa_partial.adoc
deleted file mode 100644
index dd6ec50..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_aaa_partial.adoc
+++ /dev/null
@@ -1,92 +0,0 @@
-[[_ug_reference-annotations_aaa_partial]]
-= Incomplete/partial 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/
-
-
-These annotations have only incomplete/partial support, primarily relating to the management of value types. We recommend that you do not use them for now. Future versions of Isis may either formally deprecate/retire them, or we may go the other way and properly support them. This will depend in part on the interactions between the Isis runtime, its two viewer implementations, and DataNucleus persistence.
-
-
-.Annotations with incomplete/partial support
-[cols="2,4a,1", options="header"]
-|===
-|Annotation
-|Purpose
-|Layer
-
-|`@Aggregated`
-|Indicates that the object is aggregated, or wholly owned, by a root object. +
-
-This information could in theory provide useful semantics for some object store implementations, eg to store the aggregated objects "inline". +
-
-Currently neither the JDO ObjectStore nor any of the viewers exploit this metadata.
-|Domain, Persistence
-
-|`@Defaulted`
-|Indicates that a (value) class has a default value. +
-
-The concept of "defaulted" means being able to provide a default value for the type by way of the `o.a.i.applib.adapters.DefaultsProvider` interface. Generally this only applies to value types, where the `@Value` annotation implies encodability through the `ValueSemanticsProvider` interface. +
-
-For these reasons the `@Defaulted` annotation is generally never applied directly, but can be thought of as a placeholder for future enhancements whereby non-value types might also have a default value provided for them.|Domain
-
-|`@Encodable`
-|Indicates that a (value) class can be serialized/encoded. +
-
-Encodability means the ability to convert an object to-and-from a string, by way of the `o.a.i.applib.adapters.EncoderDecoder` interface. Generally this only applies to value types, where the `@Value` annotation implies encodability through the `ValueSemanticsProvider` interface.
-
-For these reasons the `@Encodable` annotation is generally never applied directly, but can be thought of as a placeholder for future enhancements whereby non-value types might also be directly encoded.
-
-Currently neither the Wicket viewer nor the RO viewer use this API. The Wicket viewer uses Wicket APIs, while RO viewer has its own mechanisms (parsing data from input JSON representations, etc.)
-|Persistence
-
-|`@NotPersistable`
-|Indicates that a domain object may not be programmatically persisted. +
-+
-This annotation indicates that transient instances of this class may be created but may not be persisted. The framework will not provide the user with an option to 'save' the object, and attempting to persist such an object programmatically would be an error.
-
-For example:
-
-[source,java]
-----
-@NotPersistable(By.USER)
-public class InputForm {
- ...
-}
-----
-
-By default the annotated object is effectively transient (ie default to `By.USER_OR_PROGRAM`).
-
-This annotation is not supported by: Wicket viewer (which does not support transient objects). See also link:https://issues.apache.org/jira/browse/ISIS-743[ISIS-743] contemplating the removal of this annotation.
-|Domain, Persistence
-
-|`@Parseable`
-|Indicates that a (value) class can be reconstructed from a string. +
-
-Parseability means being able to parse a string representation into an object by way of the `o.a.i.applib.adapters.Parser` interface. Generally this only applies to value types, where the `@Value` annotation implies encodability through the `ValueSemanticsProvider` interface. +
-
-For these reasons the `@Parser` annotation is generally never applied directly, but can be thought of as a placeholder for future enhancements whereby non-value types might also have be able to be parsed. +
-
-Note that the Wicket viewer uses Apache Wicket's Converter API instead.
-|UI, Domain
-
-|`@Value`
-|Specify that a class has value-semantics. +
-
-The `@Value` annotation indicates that a class should be treated as a value type rather than as a reference (or entity) type. It does this providing an implementation of a `o.a.i.applib.adapters.ValueSemanticsProvider`. +
-
-For example: +
-
-[source,java]
-----
-@Value(semanticsProviderClass=
- ComplexNumberValueSemanticsProvider.class)
-public class ComplexNumber {
- ...
-}
-----
-
-The `ValueSemanticsProvider` allows the framework to interact with the value, parsing strings and displaying as text, and encoding/decoding (for serialization).
-|Domain
-
-|===
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action.adoc
deleted file mode 100644
index 56f12cd..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action.adoc
+++ /dev/null
@@ -1,134 +0,0 @@
-[[_ug_reference-annotations_manpage-Action]]
-= `@Action`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@Action` annotation groups together all domain-specific metadata for an invokable action on a domain object or domain service.
-
-The table below summarizes the annotation's attributes.
-
-.`@Action` attributes
-[cols="2,2,4a", options="header"]
-|===
-
-| Attribute
-| Values (default)
-| Description
-
-
-|xref:_ug_reference-annotations_manpage-Action_command[`command()`]
-|`AS_CONFIGURED`, `ENABLED`, `DISABLED` +
-(`AS_CONFIGURED`)
-|whether the action invocation should be reified into a `o.a.i.applib.` +
-`services.command.Command` object through the xref:_ug_reference-services-api_manpage-CommandContext[`CommandContext`] service.
-
-
-|`commandExecuteIn()`
-|`FOREGROUND`,`BACKGROUND` +
-(`FOREGROUND`)
-|whether to execute the command immediately, or to persist it (assuming that an appropriate implementation of xref:_ug_reference-services-spi_manpage-CommandService[`CommandService`] has been configured) such that a background scheduler can execute the command asynchronously
-
-
-|`commandPersistence()`
-|`PERSISTED`, `NOT_PERSISTED`, `IF_HINTED` +
-(`PERSISTED`)
-|whether the reified `Command` (as provided by the `CommandContext` domain service) should actually be persisted (assuming an appropriate implementation of xref:_ug_reference-services-spi_manpage-CommandService[`CommandService`] has been configured).
-
-
-|xref:_ug_reference-annotations_manpage-Action_domainEvent[`domainEvent()`]
-|subtype of `ActionDomainEvent` +
-(`ActionDomainEvent.Default`)
-|the event type to be posted to the xref:_ug_reference-services-api_manpage-EventBusService[`EventBusService`] to broadcast the action's business rule checking (hide, disable, validate) and its invocation (pre-execute and post-execution).
-
-
-|xref:_ug_reference-annotations_manpage-Action_hidden[`hidden()`]
-|`EVERYWHERE`, `NOWHERE` +
-(`NOWHERE`)
-|indicates where (in the UI) the action should be hidden from the user.
-
-
-|xref:_ug_reference-annotations_manpage-Action_invokeOn[`invokeOn()`]
-|`OBJECT_ONLY`, `COLLECTION_ONLY`, `OBJECT_AND_COLLECTION` +
-(`OBJECT_ONLY`)
-|whether an action can be invoked on a single object and/or on many objects in a collection.
-
-Currently this is only supported for no-arg actions.
-
-
-|xref:_ug_reference-annotations_manpage-Action_publishing[`publishing()`]
-|`AS_CONFIGURED`, `ENABLED`, `DISABLED` +
-(`AS_CONFIGURED`)
-|whether the action invocation should be published to the registered xref:_ug_reference-services-spi_manpage-PublishingService[`PublishingService`].
-
-|`publishing-` +
-`PayloadFactory()`
-|subtype of `PublishingPayloadFactory-` `ForAction` (none)
-|specifies that a custom implementation of `PublishingPayloadFactoryForAction` be used to create the (payload of the) published event representing the action invocation
-
-|xref:_ug_reference-annotations_manpage-Action_restrictTo[`restrictTo()`]
-|`NO_RESTRICTIONS`,`PROTOTYPING` +
-(`NO_RESTRICTIONS`)
-|whether the action is only available in prototyping mode, or whether it is available also in production mode.
-
-|xref:_ug_reference-annotations_manpage-Action_semantics[`semantics()`]
-|`QUERY`, `IDEMPOTENT`, `NON_IDEMPOTENT` +
-(`NON_IDEMPOTENT`)
-|the action's semantics (ie whether objects are modified as the result of invoking this action, and if so whether reinvoking the action would result in no further change)
-
-|xref:_ug_reference-annotations_manpage-Action_typeOf[`typeOf()`]
-|(none)
-|if the action returns a collection, hints as to the run-time type of the objects within that collection (as a fallback)
-
-|===
-
-
-For example:
-
-[source,java]
-----
-public class ToDoItem {
- public static class CompletedEvent extends ActionDomainEvent<ToDoItem> {
- private static final long serialVersionUID = 1L;
- public CompletedEvent(
- final ToDoItem source,
- final Identifier identifier,
- final Object... arguments) {
- super("completed", source, identifier, arguments);
- }
- }
- @Action(
- command=CommandReification.ENABLED,
- commandExecuteIn=CommandExecuteIn.FOREGROUND, // <1>
- commandPersistence=CommandPersistence.NOT_PERSISTED, // <2>
- domainEvent=CompletedEvent.class,
- hidden = Where.NOWHERE, // <3>
- invokeOn = InvokeOn.OBJECT_ONLY, // <4>
- publishing = Publishing.ENABLED,
- semantics = SemanticsOf.IDEMPOTENT
- )
- public ToDoItem completed() { ... }
-}
-----
-<1> default value, so could be omitted
-<2> default value, so could be omitted
-<3> default value, so could be omitted
-<4> default value, so could be omitted
-
-
-
-
-
-include::_ug_reference-annotations_manpage-Action_command.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-Action_domainEvent.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-Action_hidden.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-Action_invokeOn.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-Action_publishing.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-Action_restrictTo.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-Action_semantics.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-Action_typeOf.adoc[leveloffset=+1]
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout.adoc
deleted file mode 100644
index 63ecf28..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout.adoc
+++ /dev/null
@@ -1,133 +0,0 @@
-[[_ug_reference-annotations_manpage-ActionLayout]]
-= `@ActionLayout`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@ActionLayout` annotation applies to actions, collecting together all UI hints within a single annotation.
-
-The table below summarizes the annotation's attributes.
-
-.`@ActionLayout` attributes
-[cols="2,2,4a", options="header"]
-|===
-
-| Attribute
-| Values (default)
-| Description
-
-
-|xref:_ug_reference-annotations_manpage-ActionLayout_bookmarking[`bookmarking()`]
-|`AS_ROOT`, `NEVER` +
-(`NEVER`)
-|indicates if an action (with safe xref:_ug_reference-annotations_manpage-Action_semantics[action semantics]) is automatically bookmarked.
-
-
-|xref:_ug_reference-annotations_manpage-ActionLayout_contributedAs[`contributedAs()`]
-|`AS_BOTH`, `AS_ACTION`, `AS_ASSOCIATION`, `AS_NEITHER` +
-(`AS_BOTH`)
-|for a domain service action that can be contributed, whether to contribute as an action or as an association (ie a property or collection). +
-
-For a domain service action to be contributed, the domain services must have a xref:_ug_reference-annotations_manpage-DomainService_nature[nature] nature of either `VIEW` or `VIEW_CONTRIBUTIONS_ONLY`, and the action must have xref:_ug_reference-annotations_manpage-Action_semantics[safe action semantics], and takes a single argument, namely the contributee domain object.
-
-
-|xref:_ug_reference-annotations_manpage-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:_ug_runtime_application-specific_application-css[`application.css`]. +
-
-Supported by the xref:_ug_wicket-viewer[Wicket viewer] but currently ignored by the xref:_ug_restfulobjects-viewer[RestfulObjects viewer].
-
-
-|xref:_ug_reference-annotations_manpage-ActionLayout_cssClassFa[`cssClassFa()`]
-|Any valid link:http://fortawesome.github.io/Font-Awesome/[Font awesome] icon name
-|specify a font awesome icon for the action's menu link or icon. +
-
-
-|`cssClassFaPosition()`
-|`LEFT`, `RIGHT` +
-(`LEFT`)
-|Positioning of the icon on the button/menu item.
-
-
-|xref:_ug_reference-annotations_manpage-ActionLayout_describedAs[`describedAs()`]
-|String.
-|provides a short description of the action, eg for rendering as a 'tool tip'.
-
-
-|xref:_ug_reference-annotations_manpage-ActionLayout_hidden[`hidden()`]
-|`EVERYWHERE`, `NOWHERE` +
-(`NOWHERE`)
-|indicates where (in the UI) the action should be hidden from the user.
-
-
-|xref:_ug_reference-annotations_manpage-ActionLayout_named[`named()`]
-|String.
-|to override the name inferred from the action's name in code. +
-
-A typical use case is if the desired name is a reserved Java keyword, such as `default` or `package`.
-
-|xref:_ug_reference-annotations_manpage-ActionLayout_position[`position()`]
-|`BELOW`, `RIGHT`, `PANEL`, `PANEL_DROPDOWN` (`BELOW`)
-|for actions associated (using xref:_ug_reference-annotations_manpage-MemberOrder[`@MemberOrder#named()`]) with properties, the positioning of the action's button with respect to the property
-
-
-|===
-
-
-For example:
-
-[source,java]
-----
-public class ToDoItems {
- @Action(semantics=SemanticsOf.SAFE) // <1>
- @ActionLayout(
- bookmarking=BookmarkPolicy.AS_ROOT,
- cssClass="x-key",
- cssClassFa="fa-checkbox",
- describedAs="Mark the todo item as not complete after all",
- hidden=Where.NOWHERE // <2>
- )
- @MemberOrder(sequence = "1")
- public List<ToDoItem> notYetComplete() {
- ...
- }
-}
-----
-<1> required for bookmarkable actions
-<2> default value, so could be omitted
-
-
-
-
-As an alternative to using the `@ActionLayout` annotation, a dynamic layout using xref:_ug_reference-object-layout_dynamic[`.layout.json`] file can be specified; for example:
-
-[source,javascript]
-----
-"notYetComplete": {
- "actionLayout": {
- "bookmarking": "AS_ROOT",
- "cssClass": "x-key",
- "cssClassFa": "fa-checkbox",
- "describedAs": "Mark the todo item as not complete after all",
- "hidden": "NOWHERE"
- }
-}
-----
-
-
-
-include::_ug_reference-annotations_manpage-ActionLayout_bookmarking.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-ActionLayout_contributedAs.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-ActionLayout_cssClass.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-ActionLayout_cssClassFa.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-ActionLayout_describedAs.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-ActionLayout_hidden.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-ActionLayout_named.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-ActionLayout_position.adoc[leveloffset=+1]
-
-
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout_bookmarking.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout_bookmarking.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout_bookmarking.adoc
deleted file mode 100644
index 49e437d..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout_bookmarking.adoc
+++ /dev/null
@@ -1,64 +0,0 @@
-[[_ug_reference-annotations_manpage-ActionLayout_bookmarking]]
-= `bookmarking()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `bookmarking()` attribute indicates if an action (with safe xref:_ug_reference-annotations_manpage-Action_semantics[action semantics]) is automatically bookmarked. This attribute is also supported for xref:_ug_reference-annotations_manpage-DomainObjectLayout_bookmarking[domain objects].
-
-
-
-In the xref:_ug_wicket-viewer[Wicket viewer], a link to a bookmarked object is shown in the bookmarks panel:
-
-image::{_imagesdir}reference-annotations/ActionLayout/bookmarking.png[width="720px",link="{_imagesdir}reference-annotations/ActionLayout/bookmarking.png"]
-
-[NOTE]
-====
-Note that this screenshot shows an earlier version of the xref:_ug_wicket-viewer[Wicket viewer] UI (specifically, pre 1.8.0).
-====
-
-[TIP]
-====
-The xref:_ug_wicket-viewer[Wicket viewer] supports `alt-[` as a shortcut for opening the bookmark panel. `Esc` will close.
-====
-
-
-For example:
-
-[source,java]
-----
-public class ToDoItems {
- @Action(semantics=SemanticsOf.SAFE)
- @ActionLayout(bookmarking=BookmarkPolicy.AS_ROOT)
- @MemberOrder(sequence = "1")
- public List<ToDoItem> notYetComplete() {
- ...
- }
-}
-----
-
-indicates that the `notYetComplete()` action is bookmarkable.
-
-
-
-[NOTE]
-====
-The enum value `AS_CHILD` has no meaning for actions; it relates only to bookmarked xref:_ug_reference-annotations_manpage-DomainObject_bookmarking[domain object]s.
-====
-
-
-
-As an alternative to using the annotation, the dynamic xref:_ug_reference-object-layout_dynamic[`.layout.json`]
-can be used instead, eg:
-
-[source,javascript]
-----
-"notYetComplete": {
- "actionLayout": { "bookmarking": "AS_ROOT" }
-}
-----
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout_contributedAs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout_contributedAs.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout_contributedAs.adoc
deleted file mode 100644
index d18de53..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout_contributedAs.adoc
+++ /dev/null
@@ -1,54 +0,0 @@
-[[_ug_reference-annotations_manpage-ActionLayout_contributedAs]]
-= `contributedAs()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-For a domain service action that _can_ be contributed, the `contributedAs()` attribute determines how it is contributed: as an action or as an association (ie a property or collection).
-
-The distinction between property or collection is automatic: if the action returns a `java.util.Collection` (or subtype) then the action is contributed as a collection; otherwise it is contributed as a property.
-
-For a domain service action to be contributed, the domain services must have a xref:_ug_reference-annotations_manpage-DomainService_nature[nature] nature of either `VIEW` or `VIEW_CONTRIBUTIONS_ONLY`, and the action must have xref:_ug_reference-annotations_manpage-Action_semantics[safe action semantics], and takes a single argument, namely the contributee domain object.
-
-For example:
-
-[source,java]
-----
-@DomainService(nature=NatureOfService.VIEW_CONTRIBUTIONS_ONLY)
-public class CustomerContributions {
- @Action(semantics=SemanticsOf.SAFE)
- @ActionLayout(contributedAs=Contributed.AS_ASSOCIATION)
- public List<Order> mostRecentOrders(Customer customer) { ... }
- ...
-}
-----
-
-[TIP]
-====
-The `@ActionLayout` is not required if the action does not have safe semantics, or if the action takes more than one argument; in these cases the action can only be contributed _as_ an action.
-====
-
-
-It's also possible to use the attribute to suppress the action completely:
-
-[source,java]
-----
-@DomainService(nature=NatureOfService.VIEW)
-public class OrderContributions {
- @ActionLayout(contributedAs=Contributed.AS_NEITHER)
- public void cancel(Order order);
- ...
-}
-----
-
-In such cases, though, it would probably make more sense to annotate the action as either xref:_ug_reference-annotations_manpage-Action_hidden[hidden] or indeed xref:_ug_reference-annotations_manpage-Programmatic[`@Programmatic`].
-
-
-
-[NOTE]
-====
-Unlike other `@ActionLayout` attributes, this attribute _cannot_ be specified dynamically in the `.layout.json` xref:_ug_reference-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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout_cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout_cssClass.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout_cssClass.adoc
deleted file mode 100644
index d12d66a..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout_cssClass.adoc
+++ /dev/null
@@ -1,41 +0,0 @@
-[[_ug_reference-annotations_manpage-ActionLayout_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()` attribute can be used to render additional CSS classes in the HTML (a wrapping `<div>`) that represents the action. xref:_ug_runtime_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:_ug_reference-annotations_manpage-DomainObjectLayout_cssClass[domain objects], xref:_ug_reference-annotations_manpage-ViewModelLayout_cssClass[view models], xref:_ug_reference-annotations_manpage-PropertyLayout_cssClass[properties], xref:_ug_reference-annotations_manpage-CollectionLayout_cssClass[collections] and xref:_ug_reference-annotations_manpage-ParameterLayout_cssClass[parameters].
-
-
-For example:
-
-[source,java]
-----
-public class ToDoItem {
- @ActionLayout(cssClass="x-key")
- public ToDoItem postpone(LocalDate until) { ... }
- ...
-}
-----
-
-[NOTE]
-====
-The similar xref:_ug_reference-annotations_manpage-ActionLayout_cssClassFa[`@ActionLayout#cssClassFa()`] annotation attribute is also used as a hint
-to apply CSS, specifically to add http://fortawesome.github.io/Font-Awesome/icons/[Font Awesome icons] on action menu items or buttons.
-====
-
-
-
-As an alternative to using the annotation, the dynamic xref:_ug_reference-object-layout_dynamic[`.layout.json`]
-can be used instead, eg:
-
-[source,javascript]
-----
-"postpone": {
- "actionLayout": { "cssClass": "x-key" }
-}
-----
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout_cssClassFa.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout_cssClassFa.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout_cssClassFa.adoc
deleted file mode 100644
index e6cc521..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout_cssClassFa.adoc
+++ /dev/null
@@ -1,59 +0,0 @@
-[[_ug_reference-annotations_manpage-ActionLayout_cssClassFa]]
-= `cssClassFa()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `cssClassFa()` attribute is used to specify the name of a link:http://fortawesome.github.io/Font-Awesome/icons/[Font Awesome icon] name, to be rendered on the action's representation as a button or menu item. The related `cssClassFaPosition()` attribute specifies the positioning of the icon, to the left or the right of the text.
-
-These attributes can also be applied to xref:_ug_reference-annotations_manpage-DomainObjectLayout_cssClassFa[domain objects] and to xref:_ug_reference-annotations_manpage-ViewModelLayout_cssClassFa[view models] to specify the object's icon.
-
-
-For example:
-
-[source,java]
-----
-public class ToDoItem {
- @ActionLayout(
- cssClassFa="fa-step-backward"
- )
- public ToDoItem previous() { ... }
-
- @ActionLayout(
- cssClassFa="fa-step-forward",
- cssClassFaPosition=ActionLayout.CssClassFaPosition.RIGHT
- )
- public ToDoItem next() { ... }
-}
-----
-
-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_reference-object-layout_dynamic[`.layout.json`]
-can be used instead, eg:
-
-[source,javascript]
-----
-"previous": {
- "actionLayout": {
- "cssClassFa": "fa-step-backward",
- "cssClassFaPosition": "LEFT"
- }
-},
-"next": {
- "actionLayout": {
- "cssClassFa": "fa-step-forward",
- "cssClassFaPosition": "RIGHT"
- }
-}
-----
-
-
-
-[NOTE]
-====
-The similar xref:_ug_reference-annotations_manpage-ActionLayout_cssClass[`@ActionLayout#cssClass()`] annotation attribute is also used as a hint to apply CSS, but for wrapping the representation of an object or object member so that it can be styled in an application-specific way.
-====
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout_describedAs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout_describedAs.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout_describedAs.adoc
deleted file mode 100644
index daf8265..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout_describedAs.adoc
+++ /dev/null
@@ -1,37 +0,0 @@
-[[_ug_reference-annotations_manpage-ActionLayout_describedAs]]
-= `describedAs()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `describedAs()` attribute is used to provide a short description of the action to the user. In the xref:_ug_wicket-viewer[Wicket viewer] it is displayed as a 'tool tip'.
-
-This attribute can also be specified for xref:_ug_reference-annotations_manpage-CollectionLayout_describedAs[collections], xref:_ug_reference-annotations_manpage-PropertyLayout_describedAs[properties], xref:_ug_reference-annotations_manpage-ParameterLayout_describedAs[parameters], xref:_ug_reference-annotations_manpage-DomainObjectLayout_describedAs[domain objects] and xref:_ug_reference-annotations_manpage-ViewModelLayout_describedAs[view models].
-
-
-For example:
-
-[source,java]
-----
-public class Customer {
- @ActionLayout(describedAs="Place a repeat order of the last (most recently placed) order")
- public Order placeRepeatOrder(...) { ... }
-}
-----
-
-
-
-
-As an alternative to using the annotation, the dynamic xref:_ug_reference-object-layout_dynamic[`.layout.json`]
-can be used instead, eg:
-
-[source,javascript]
-----
-"postpone": {
- "actionLayout": { "describedAs": "Place a repeat order of the last (most recently placed) order" }
-}
-----
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout_hidden.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout_hidden.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout_hidden.adoc
deleted file mode 100644
index 70de69d..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout_hidden.adoc
+++ /dev/null
@@ -1,57 +0,0 @@
-[[_ug_reference-annotations_manpage-ActionLayout_hidden]]
-= `hidden()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `hidden()` attribute indicates where (in the UI) the action should be hidden from the user. This attribute can also be applied to xref:_ug_reference-annotations_manpage-PropertyLayout_hidden[properties] and xref:_ug_reference-annotations_manpage-CollectionLayout_hidden[collections].
-
-[TIP]
-====
-It is also possible to use xref:_ug_reference-annotations_manpage-Action_hidden[`@Action#hidden()`] to hide an action at the domain 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:
-
-[source,java]
-----
-public class Customer {
- @ActionLayout(hidden=Where.EVERYWHERE)
- public void updateStatus() { ... }
- ...
-}
-----
-
-The acceptable values for the `where` parameter are:
-
-* `Where.EVERYWHERE` or `Where.ANYWHERE` +
-+
-The action should be hidden at all times.
-
-* `Where.NOWHERE` +
-+
-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_reference-object-layout_dynamic[`.layout.json`]
-can be used instead, eg:
-
-[source,javascript]
-----
-"updateStatus": {
- "actionLayout": { "hidden": "EVERYWHERE" }
-}
-----
-
-
-[NOTE]
-====
-For actions of domain services the visibility is dependent upon its xref:_ug_reference-annotations_manpage-DomainService_nature[`@DomainService#nature()`] and also on whether it is contributed (as per xref:_ug_reference-annotations_manpage-ActionLayout_contributedAs[`@ActionLayout#contributedAs()`]).
-====
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout_named.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout_named.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout_named.adoc
deleted file mode 100644
index d634676..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout_named.adoc
+++ /dev/null
@@ -1,45 +0,0 @@
-[[_ug_reference-annotations_manpage-ActionLayout_named]]
-= `named()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `named()` attribute explicitly specifies the action's name, overriding the name that would normally be inferred from the Java source code. This attribute can also be specified for xref:_ug_reference-annotations_manpage-CollectionLayout_named[collections], xref:_ug_reference-annotations_manpage-PropertyLayout_named[properties], xref:_ug_reference-annotations_manpage-ParameterLayout_named[parameters], xref:_ug_reference-annotations_manpage-DomainObjectLayout_named[domain objects], xref:_ug_reference-annotations_manpage-ViewModelLayout_named[view models] and xref:_ug_reference-annotations_manpage-DomainServiceLayout_named[domain services].
-
-[TIP]
-====
-Following the link:http://en.wikipedia.org/wiki/Don%27t_repeat_yourself[don't repeat yourself] principle, we recommend that you only use this attribute when the desired name cannot be used in Java source code. Examples of that include a name that would be a reserved Java keyword (eg "package"), or a name that has punctuation, eg apostrophes.
-====
-
-
-
-For example:
-
-[source,java]
-----
-public class Customer {
- @ActionLayout(named="Get credit rating")
- public CreditRating obtainCreditRating() { ... }
-}
-----
-
-
-As an alternative to using the annotation, the dynamic xref:_ug_reference-object-layout_dynamic[`.layout.json`]
-can be used instead, eg:
-
-[source,javascript]
-----
-"obtainCreditRating": {
- "actionLayout": { "named": "Get credit rating" }
-}
-----
-
-
-[TIP]
-====
-The framework also provides a separate, powerful mechanism for xref:_ug_more-advanced_i18n[internationalization].
-====
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout_position.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout_position.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout_position.adoc
deleted file mode 100644
index f333418..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-ActionLayout_position.adoc
+++ /dev/null
@@ -1,80 +0,0 @@
-[[_ug_reference-annotations_manpage-ActionLayout_position]]
-= `position()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `position()` attribute pertains only to actions that have been associated with properties using xref:_ug_reference-annotations_manpage-MemberOrder[`@MemberOrder#named()`]. For these actions, it specifies the positioning of the action's button with respect to the field representing the object property.
-
-The attribute can take one of four values: `BELOW`, `RIGHT`, `PANEL` or `PANEL_DROPDOWN`.
-
-For example:
-
-[source,java]
-----
-public class Customer {
-
- @Property(
- editing=Editing.DISABLED // <1>
- )
- public CustomerStatus getStatus() { ... }
- public void setStatus(CustomerStatus customerStatus) { ... }
-
- @MemberOrder(
- named="status", // <2>
- sequence="1"
- )
- @ActionLayout(
- named="Update", // <3>
- position=Position.BELOW
- )
- public CreditRating updateStatus(Customer ) { ... }
-}
-----
-<1> indicate the property as read-only, such that it can only be updated using an action
-<2> associate the "updateStatus" action with the "status" property
-<3> give the action an abbreviated name, because the fact that the "status" property is to be updated is implied by its positioning
-
-
-The default is `BELOW`, which is rendered (by the xref:_ug_wicket-viewer[Wicket viewer]) as shown below:
-
-image::{_imagesdir}reference-annotations/ActionLayout/position-BELOW.png[width="720px",link="{_imagesdir}reference-annotations/ActionLayout/position-BELOW.png.png"]
-
-
-If the action is positioned as `RIGHT`, then the action's button is rendered to the right of the property's field, in a compact drop-down. This is ideal if there are many actions associated with a property:
-
-image::{_imagesdir}reference-annotations/ActionLayout/position-RIGHT.png[width="720px",link="{_imagesdir}reference-annotations/ActionLayout/position-RIGHT.png.png"]
-
-
-
-If the action is positioned as `PANEL`, then the action's button is rendered on the header of the panel that contains the property:
-
-image::{_imagesdir}reference-annotations/ActionLayout/position-PANEL.png[width="720px",link="{_imagesdir}reference-annotations/ActionLayout/position-PANEL.png.png"]
-
-
-
-And finally, if the action is positioned as `PANEL_DROPDOWN`, then the action's button is again rendered on the panel header, but as a drop-down:
-
-
-image::{_imagesdir}reference-annotations/ActionLayout/position-PANEL_DROPDOWN.png[width="720px",link="{_imagesdir}reference-annotations/ActionLayout/position-PANEL_DROPDOWN.png.png"]
-
-
-
-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_reference-object-layout_dynamic[`.layout.json`]
-can be used instead, eg:
-
-[source,javascript]
-----
-"obtainCreditRating": {
- "actionLayout": { "named": "Get credit rating" }
-}
-----
-
-The fact that the layout is dynamic (does not require a rebuild/restart) is particularly useful in that the look-n-feel can be easily experimented with and adjusted.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action_command.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action_command.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action_command.adoc
deleted file mode 100644
index f48ad39..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action_command.adoc
+++ /dev/null
@@ -1,134 +0,0 @@
-[[_ug_reference-annotations_manpage-Action_command]]
-= `command()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@Action(command=...)` attribute (and the related `@Action(commandPersistence=...)` and `@Action(commandExecuteIn=...)` attributes) allows an action invocation to be made into a concrete object such that it can be inspected and persisted. The primary use case for this is enhanced profiling/auditing, and it also supports the deferring the execution of the action such that it can be invoked in the background.
-
-The annotation works with (and is influenced by the behaviour of) a number of domain services:
-
-* xref:_ug_reference-services-api_manpage-CommandContext[`CommandContext`]
-* xref:_ug_reference-services-spi_manpage-CommandService[`CommandService`]
-* xref:_ug_reference-services-spi_manpage-BackgroundService[`BackgroundService`] and
-* xref:_ug_reference-services-spi_manpage-BackgroundCommandService[`BackgroundCommandService`]
-
-
-Each action invocation is reified by the xref:_ug_reference-services-api_manpage-CommandContext[`CommandContext`] service into a `Command` object, capturing details of the target object, the action, the parameter arguments, the user, a timestamp and so on.
-
-If an appropriate `CommandService` is configured (for example using (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module), then the `Command` itself is persisted.
-
-By default, actions are invoked in directly in the thread of the invocation. If there is an implementation of `BackgroundCommandService` (as the http://github.com/isisaddons/isis-module-command[Isis addons' command] module does provide), then this means in turn that the `BackgroundService` can be used by the domain object code to programmatically create background ``Command``s.
-
-[NOTE]
-====
-If background ``Command``s are used, then an external scheduler, using xref:_ug_headless-access_BackgroundCommandExecution[headless access], must also be configured.
-====
-
-
-
-The `command()` attribute determines whether the action invocation should be reified into a `Command` object (by the xref:_ug_reference-services-api_manpage-CommandContext[`CommandContext`] service).
-
-The default is `AS_CONFIGURED`, meaning that the xref:_ug_runtime_configuring-core[configuration property] `isis.services.command.actions` is used to determine the whether the action is reified:
-
-* `all` +
-+
-all actions are reified
-
-* `ignoreSafe` (or `ignoreQueryOnly`) +
-+
-actions with safe (read-only) semantics are ignored, but actions which may modify data are not ignored
-
-* `none` +
-+
-no actions are reified.
-
-If there is no configuration property in `isis.properties` then all actions are reified into ``Command``s.
-
-[NOTE]
-====
-Note: `Command` reification does not necessarily imply that `Command` objects will be persisted; that depends on whether there is a xref:_ug_reference-services-spi_manpage-CommandService[`CommandService`] configured that will persist said ``Command``s.
-====
-
-This default can be overridden on an action-by-action basis; if `command()` is set to `ENABLED` then the action is reified irrespective of the configured value; if set to `DISABLED` then the action is NOT reified irrespective of the configured value.
-
-For example:
-
-[source,java]
-----
-public class Order {
- @Action(command=CommandReification.ENABLED)
- public Invoice generateInvoice(...) { ... }
-}
-----
-
-corresponds to the behaviour described above; the `Command` object is persisted (assuming an appropriate `CommandService` is defined, and executed immediately in the foreground).
-
-
-
-
-== `commandPersistence()`
-
-If the action has been reified, then the `commandPersistence()` attribute determines whether that `Command` object
-should then also be persisted (the default), or not persisted, or only if hinted.
-
-To explain this last alternative:
-
-[source,java]
-----
-public class Order {
- @Action(
- command=CommandReification.ENABLED,
- commandPersistence=CommandPersistence.IF_HINTED
- )
- public Invoice generateInvoice(...) { ... }
-}
-----
-
-will suppress the persistence of the `Command` object _unless_ a child background `Command` has been created in the body of the action by way of the xref:_ug_reference-services-api_manpage-BackgroundService[`BackgroundService`].
-
-On the other hand:
-
-[source,java]
-----
-public class Order {
- @Action(
- command=CommandReification.ENABLED,
- commandExecuteIn=CommandExecuteIn.FOREGROUND,
- commandPersistence=CommandPersistence.NOT_PERSISTED
- )
- public Invoice generateInvoice(...) { ... }
-}
-----
-
-will prevent the parent `Command` object from being persisted, _even if_ a child background `Command` is created.
-
-
-
-
-
-== `commandExecuteIn()`
-
-For persisted commands, the `commandExecuteIn()` attribute determines whether the `Command` should be executed in the foreground (the default) or executed in the background.
-
-Background execution means that the command is not executed immediately, but is available for a configured xref:_ug_reference-services-spi_manpage-BackgroundCommandService[`BackgroundCommandService`] to execute, eg by way of an in-memory scheduler such as Quartz. See xref:_ug_headless-access_BackgroundCommandExecution[here] for further information on this topic.
-
-For example:
-
-[source,java]
-----
-public class Order {
- @Action(
- command=CommandReification.ENABLED,
- commandExecuteIn=CommandExecuteIn.BACKGROUND)
- public Invoice generateInvoice(...) { ... }
-}
-----
-
-will result in the `Command` being persisted but its execution deferred to a background execution mechanism. The
-returned object from this action is the persisted `Command` itself.
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action_domainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action_domainEvent.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action_domainEvent.adoc
deleted file mode 100644
index d473db5..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action_domainEvent.adoc
+++ /dev/null
@@ -1,146 +0,0 @@
-[[_ug_reference-annotations_manpage-Action_domainEvent]]
-= domainEvent()
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-Whenever a domain object (or list of domain objects) is to be rendered, the framework fires off multiple domain events for every property, collection and action of the domain object. In the cases of the domain object's actions, the events that are fired are:
-
-* hide phase: to check that the action is visible (has not been hidden)
-* disable phase: to check that the action is usable (has not been disabled)
-* validate phase: to check that the action's arguments are valid
-* pre-execute phase: before the invocation of the action
-* post-execute: after the invocation of the action
-
-Subscribers subscribe through the xref:_ug_reference-services-api_manpage-EventBusService[`EventBusService`] using either link:https://github.com/google/guava[Guava] or link:http://www.axonframework.org/[Axon Framework] annotations and can influence each of these phases.
-
-By default the event raised is `ActionDomainEvent.Default`. For example:
-
-[source,java]
-----
-public class ToDoItem {
- @Action()
- public ToDoItem completed() { ... }
- ...
-}
-----
-
-The purpose of the `domainEvent()` attribute is to allows a custom subclass to be emitted instead. This attribute is also supported for xref:_ug_reference-annotations_manpage-Collection_domainEvent[collections] and xref:_ug_reference-annotations_manpage-Property_domainEvent[properties].
-
-For example:
-
-[source,java]
-----
-public class ToDoItem {
- public static class CompletedEvent extends ActionDomainEvent<ToDoItem> { // <1>
- private static final long serialVersionUID = 1L;
- public CompletedEvent( // <2>
- final ToDoItem source, // <3>
- final Identifier identifier, // <4>
- final Object... arguments) { // <5>
- super("completed", source, identifier, arguments);
- }
- }
- @Action(domainEvent=CompletedEvent.class)
- public ToDoItem completed() { ... }
-}
-----
-<1> inherit from `ActionDomainEvent<T>` where `T` is the type of the domain object being interacted with
-<2> constructor called reflectively by the framework
-<3> populated with the object being interacted with (the source of the event)
-<4> identifier of the collection
-<5> action argument(s)
-
-
-The benefit is that subscribers can be more targetted as to the events that they subscribe to.
-
-
-
-
-== Subscribers
-
-Subscribers (which must be domain services) subscribe using either the link:https://github.com/google/guava[Guava] API or (if the xref:_ug_reference-services-api_manpage-EventBusService[`EventBusService`] has been appropriately configured) using the link:http://www.axonframework.org/[Axon Framework] API. The examples below use the Guava API.
-
-Subscribers can be either coarse-grained (if they subscribe to the top-level event type):
-
-[source,java]
-----
-@DomainService
-public class SomeSubscriber {
- @Programmatic
- @com.google.common.eventbus.Subscribe
- public void on(ActionInteractionEvent ev) {
- ...
- }
-}
-----
-
-or can be fine-grained (by subscribing to specific event subtypes):
-
-[source,java]
-----
-@DomainService
-public class SomeSubscriber {
- @Programmatic
- @com.google.common.eventbus.Subscribe
- public void on(ToDoItem.CompletedEvent ev) {
- ...
- }
-}
-----
-
-[TIP]
-====
-If the AxonFramework is being used, replace `@com.google.common.eventbus.Subscribe` with `@org.axonframework.eventhandling.annotation.EventHandler`.
-====
-
-
-The subscriber's method is called (up to) 5 times:
-
-* whether to veto visibility (hide)
-* whether to veto usability (disable)
-* whether to veto execution (validate)
-* steps to perform prior to the action being invoked.
-* steps to perform after the action has been invoked.
-
-The subscriber can distinguish these by calling `ev.getEventPhase()`. Thus the general form is:
-
-[source,java]
-----
-@Programmatic
-@com.google.common.eventbus.Subscribe
-public void on(ActionDomainEvent ev) {
- switch(ev.getPhase()) {
- case HIDE:
- // call ev.hide() or ev.veto("") to hide the action
- break;
- case DISABLE:
- // call ev.disable("...") or ev.veto("...") to disable the action
- break;
- case VALIDATE:
- // call ev.invalidate("...") or ev.veto("...")
- // if action arguments are invalid
- break;
- case EXECUTING:
- break;
- case EXECUTED:
- break;
- }
-}
-----
-
-It is also possible to abort the transaction during the executing or executed phases by throwing an exception. If the exception is a subtype of `RecoverableException` then the exception will be rendered as a user-friendly warning (eg Growl/toast) rather than an error.
-
-
-
-
-== Raising events programmatically
-
-Normally events are only raised for interactions through the UI. However, events can be raised programmatically either by calling the xref:_ug_reference-services-api_manpage-EventBusService[`EventBusService`] API directly, or by emulating the UI by
-wrapping the target object using the xref:_ug_reference-services-api_manpage-WrapperFactory[`WrapperFactory`] domain service.
-
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action_hidden.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action_hidden.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action_hidden.adoc
deleted file mode 100644
index bc6c987..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action_hidden.adoc
+++ /dev/null
@@ -1,49 +0,0 @@
-[[_ug_reference-annotations_manpage-Action_hidden]]
-= `hidden()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-
-Actions can be hidden at the domain-level, indicating that they are not visible to the end-user. This attribute can also be applied to xref:_ug_reference-annotations_manpage-Property_hidden[properties] and xref:_ug_reference-annotations_manpage-Collection_hidden[collections].
-
-[TIP]
-====
-It is also possible to use xref:_ug_reference-annotations_manpage-ActionLayout_hidden[`@ActionLayout#hidden()`] or xref:_ug_reference-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:
-
-[source,java]
-----
-public class Customer {
- @Action(hidden=Where.EVERYWHERE)
- public void updateStatus() { ... }
- ...
-}
-----
-
-The acceptable values for the `where` parameter are:
-
-* `Where.EVERYWHERE` or `Where.ANYWHERE` +
-+
-The action should be hidden at all times.
-
-* `Where.NOWHERE` +
-+
-The action should not be hidden.
-
-
-The other values of the `Where` enum have no meaning for a collection.
-
-
-
-[NOTE]
-====
-For actions of domain services the visibility is dependent upon its xref:_ug_reference-annotations_manpage-DomainService_nature[`@DomainService#nature()`] and also on whether it is contributed (as per xref:_ug_reference-annotations_manpage-ActionLayout_contributedAs[`@ActionLayout#contributedAs()`]).
-====
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action_invokeOn.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action_invokeOn.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action_invokeOn.adoc
deleted file mode 100644
index 48411e7..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action_invokeOn.adoc
+++ /dev/null
@@ -1,64 +0,0 @@
-[[_ug_reference-annotations_manpage-Action_invokeOn]]
-= `invokeOn()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `invokeOn()` attribute indicates whether the an action can be invoked on a single object (the default) and/or on many objects in a collection.
-
-For example:
-
-[source,java]
-----
-public class ToDoItem {
- @Action(invokeOn=InvokeOn.OBJECT_AND_COLLECTION)
- public void markAsCompleted() {
- setCompleted(true);
- }
- ...
-}
-----
-
-
-Actions to be invoked on collection (currently) have a number of constraints. It:
-
-* must take no arguments
-* cannot be hidden (any annotations or supporting methods to that effect will be ignored)
-* cannot be disabled (any annotations or supporting methods to that effect will be ignored).
-
-The example given above is probably ok, because `setCompleted()` is most likely idempotent. However, if the action also called some other method, then we should add a guard.
-
-For example, for this non-idempotent action:
-
-[source,java]
-----
-@Action(invokeOn=InvokeOn.OBJECT_AND_COLLECTION)
-public void markAsCompleted() {
- setCompleted(true);
- todoTotalizer.incrementNumberCompleted();
-}
-----
-
-we should instead write it as:
-
-[source,java]
-----
-@Action(invokeOn=InvokeOn.OBJECT_AND_COLLECTION)
-public void markAsCompleted() {
- if(isCompleted()) {
- return;
- }
- setCompleted(true);
- todoTotalizer.incrementNumberCompleted();
-}
-----
-
-[NOTE]
-====
-This attribute has no meaning if annotated on an action of a domain service.
-====
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action_publishing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action_publishing.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action_publishing.adoc
deleted file mode 100644
index 61d3d0d..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action_publishing.adoc
+++ /dev/null
@@ -1,53 +0,0 @@
-[[_ug_reference-annotations_manpage-Action_publishing]]
-= `publishing()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `publishing()` attribute determines whether and how an action invocation is published via the registered implementation of a xref:_ug_reference-services-spi_manpage-PublishingService[`PublishingService`]). This attribute is also supported for xref:_ug_reference-annotations_manpage-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:_ug_runtime_configuring-core[configuration property] `isis.services.publish.actions` is used to determine the whether the action is published:
-
-* `all` +
-+
-all actions are published
-
-* `ignoreSafe` (or `ignoreQueryOnly`) +
-+
-actions with safe (read-only) semantics are ignored, but actions which may modify data are not ignored
-
-* `none` +
-+
-no actions are published
-
-If there is no configuration property in `isis.properties` then publishing is automatically enabled.
-
-This default can be overridden on an action-by-action basis; if `publishing()` is set to `ENABLED` then the action invocation is published irrespective of the configured value; if set to `DISABLED` then the action invocation is _not_ published, again irrespective of the configured value.
-
-For example:
-
-[source,java]
-----
-public class Order {
- @Action(publishing=Publishing.ENABLED) // <1>
- public Invoice generateInvoice(...) { ... }
-}
-----
-<1> because set to enabled, will be published irrespective of the configured value.
-
-
-
-
-== `publishingPayloadFactory()`
-
-The (optional) related `publishingPayloadFactory()` specifies the class to use to create the (payload of the) event to be published by the publishing factory.
-
-Rather than simply broadcast that the action was invoked, the payload factory allows a "fatter" payload to be instantiated that can eagerly push commonly-required information to all subscribers. For at least some subscribers this should avoid the necessity to query back for additional information.
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action_restrictTo.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action_restrictTo.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action_restrictTo.adoc
deleted file mode 100644
index 57a34d8..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action_restrictTo.adoc
+++ /dev/null
@@ -1,30 +0,0 @@
-[[_ug_reference-annotations_manpage-Action_restrictTo]]
-= `restrictTo()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 actions are available irrespective of the xref:_ug_runtime_deployment-types[deployment mode]. The `restrictTo()` attribute specifies whether the action should instead be restricted to only available in prototyping mode.
-
-For example:
-
-[source,java]
-----
-public class Customer {
- public Order placeNewOrder() { ... }
- public List<Order> listRecentOrders() { ... }
-
- @Action(restrictTo=RestrictTo.PROTOTYPING)
- public List<Order> listAllOrders() { ... }
- ...
-}
-----
-
-In this case the listing of all orders (in the `listAllOrders()` action) probably doesn't make sense for production; there could be thousands or millions. However, it would be useful to disaply how for a test or demo system where there are only a handful of orders.
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action_semantics.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action_semantics.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action_semantics.adoc
deleted file mode 100644
index 15b3d2d..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action_semantics.adoc
+++ /dev/null
@@ -1,36 +0,0 @@
-[[_ug_reference-annotations_manpage-Action_semantics]]
-= `semantics()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `semantics()` attribute describes whether the invocation is safe (as no side-effects), is idempotent (may have side-effects but always has the same post-conditions), or is neither safe nor idempotent. If the annotation is missing then the framework assumes non-idempotent.
-
-[TIP]
-====
-The attribute was originally introduced for the xref:_ug_restfulobjects-viewer[RestfulObjects viewer] in order that action invocations could be made available using either HTTP GET, PUT or POST (respectively).
-
-Since then its use has been extended into the core runtime. For example, it is now aso used for the in-built concurrency checking; the invocation of a safe action does not perform a concurrency check, whereas non-safe actions do perform a concurrency check.
-====
-
-For example:
-
-[source,java]
-----
-public class Customer {
- @Action(semantics=SemanticsOf.SAFE)
- public CreditRating checkCredit() { ... }
-
- @Action(semantics=SemanticsOf.IDEMPOTENT)
- public void changeOfAddress(Address address) { ... }
-
- @Action(semantics=SemanticsOf.NON_IDEMPOTENT)
- public Order placeNewOrder() { ... }
- ...
-}
-----
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action_typeOf.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action_typeOf.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action_typeOf.adoc
deleted file mode 100644
index ea7aa71..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Action_typeOf.adoc
+++ /dev/null
@@ -1,31 +0,0 @@
-[[_ug_reference-annotations_manpage-Action_typeOf]]
-= `typeOf()`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `typeOf()` attribute specifies the expected type of an element returned by the action (returning a collection), when for whatever reason the type cannot be inferred from the generic type, or to provide a hint about the actual run-time (as opposed to compile-time) type. This attribute can also be specified for xref:_ug_reference-annotations_manpage-Collection_typeOf[collections].
-
-
-For example:
-
-[source,java]
-----
-public void AccountService {
- @Action(typeOf=Customer.class)
- public List errantAccounts() {
- return customers.allNewCustomers();
- }
- ...
-
- @Inject
- CustomerRepository customers;
-}
-----
-
-[TIP]
-====
-In general we recommend that you use generics instead, eg `List<Customer>`.
-====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Collection.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Collection.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Collection.adoc
deleted file mode 100644
index 49961a1..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-Collection.adoc
+++ /dev/null
@@ -1,106 +0,0 @@
-[[_ug_reference-annotations_manpage-Collection]]
-= `@Collection`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@Collection` annotation applies to collections collecting together all domain semantics within a single annotation.
-
-The table below summarizes the annotation's attributes.
-
-.`@Collection` attributes
-[cols="2,2,4a", options="header"]
-|===
-
-| Attribute
-| Values (default)
-| Description
-
-
-|xref:_ug_reference-annotations_manpage-Collection_domainEvent[`domainEvent()`]
-|subtype of `CollectionDomainEvent` +
-(`CollectionDomainEvent.Default`)
-|the event type to be posted to the xref:_ug_reference-services-api_manpage-EventBusService[`EventBusService`] to broadcast the collection's business rule checking (hide, disable, validate) and its modification (before and after).
-
-
-|xref:_ug_reference-annotations_manpage-Collection_editing[`editing()`]
-|`ENABLED`, `DISABLED`, `AS_CONFIGURED` +
-(`AS_CONFIGURED`)
-|whether a collection can be added to or removed from within the UI
-
-
-|`editingDisabledReason()`
-|String value
-|if `editing()` is `DISABLED`, provides a reason as to why.
-
-
-|xref:_ug_reference-annotations_manpage-Collection_hidden[`hidden()`]
-|`EVERYWHERE`, `OBJECT_FORMS`, `NOWHERE` +
-(`NOWHERE`)
-|indicates where (in the UI) the collection should be hidden from the user.
-
-
-|xref:_ug_reference-annotations_manpage-Collection_notPersisted[`notPersisted()`]
-|`true`, `false` +
-(`false`)
-|whether to exclude from snapshots. +
-
-[WARNING]
-====
-Collection must also be annotated with `@javax.jdo.annotations.NotPersistent` in order to not be persisted.
-====
-
-
-
-|xref:_ug_reference-annotations_manpage-Collection_typeOf[`typeOf()`]
-|
-|hints as to the run-time type of the objects within that collection (as a fallback)
-
-|===
-
-
-For example:
-
-[source,java]
-----
-public class ToDoItem {
- public static class DependenciesChangedEvent
- extends CollectionDomainEvent<ToDoItem, ToDoItem> {
- private static final long serialVersionUID = 1L;
- public DependenciesChangedEvent(
- ToDoItem source,
- Identifier identifier,
- Of of,
- ToDoItem value) {
- super(source, identifier, of, value);
- }
- }
- @Collection(
- domainEvent=DependenciesChangedEvent.class,
- editing = Editing.ENABLED,
- hidden = Where.NOWHERE, // <1>
- notPersisted = false, // <2>
- typeOf = ToDoItem.class // <3>
- )
- public SortedSet<ToDoItem> getDependencies() { ... }
- ...
-}
-----
-<1> default value, so could be omitted
-<2> default value, so could be omitted
-<3> default value, so could be omitted
-
-
-
-
-
-include::_ug_reference-annotations_manpage-Collection_domainEvent.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-Collection_editing.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-Collection_hidden.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-Collection_notPersisted.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-Collection_typeOf.adoc[leveloffset=+1]
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-CollectionLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-CollectionLayout.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-CollectionLayout.adoc
deleted file mode 100644
index 91e18ee..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-annotations_manpage-CollectionLayout.adoc
+++ /dev/null
@@ -1,121 +0,0 @@
-[[_ug_reference-annotations_manpage-CollectionLayout]]
-= `@CollectionLayout`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `@CollectionLayout` annotation applies to collections, collecting together all UI hints within a single
-annotation. It is also possible to apply the annotation to actions of domain services that are acting as contributed collections.
-
-The table below summarizes the annotation's attributes.
-
-.`@CollectionLayout` attributes
-[cols="2,2,4a", options="header"]
-|===
-
-| Attribute
-| Values (default)
-| Description
-
-
-|xref:_ug_reference-annotations_manpage-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:_ug_runtime_application-specific_application-css[`application.css`]
-
-
-|xref:_ug_reference-annotations_manpage-CollectionLayout_describedAs[`describedAs()`]
-|String.
-|description of this collection, eg to be rendered in a tooltip.
-
-
-|xref:_ug_reference-annotations_manpage-CollectionLayout_hidden[`hidden()`]
-|`EVERYWHERE`, `OBJECT_FORMS`, `NOWHERE` +
-(`NOWHERE`)
-|indicates where (in the UI) the collection should be hidden from the user.
-
-
-|xref:_ug_reference-annotations_manpage-CollectionLayout_named[named()]
-|String.
-|to override the name inferred from the collection's name in code. +
-
-A typical use case is if the desired name is a reserved Java keyword, such as `default` or `package`.
-
-
-|namedEscaped()
-|`true`,`false` (`true`)
-|whether to HTML escape the name of this property.
-
-
-|xref:_ug_reference-annotations_manpage-CollectionLayout_paged[`paged()`]
-|Positive integer
-|the page size for instances of this class when rendered within a table.
-
-
-|xref:_ug_reference-annotations_manpage-CollectionLayout_render[`render()`]
-|`EAGERLY`, `LAZILY` +
-(`LAZILY`)
-|whether the collection should be (eagerly) rendered open or (lazily) rendered closed
-
-
-|xref:_ug_reference-annotations_manpage-CollectionLayout_sortedBy[`sortedBy()`]
-|Subclass of `java.util.Comparator` for element type
-|indicates that the elements in the `java.util.SortedSet` collection should be sorted according to a specified `Comparator` rather than their natural sort order.
-
-|===
-
-
-
-
-For example:
-
-[source,java]
-----
-public class ToDoItem {
- @CollectionLayout(
- cssClass="x-key",
- named="Todo items that are <i>dependencies</i> of this item.",
- namedEscaped=false,
- describedAs="Other todo items that must be completed before this one",
- labelPosition=LabelPosition.LEFT,
- render=EAGERLY)
- public SortedSet<ToDoItem> getDependencies() { ... }
- ...
-}
-----
-
-
-
-As an alternative to using the `@CollectionLayout` annotation, a dynamic layout using xref:_ug_reference-object-layout_dynamic[`.layout.json`] file can be specified; for example:
-
-[source,javascript]
-----
-"dependencies": {
- "collectionLayout": {
- "cssClass": "x-key",
- "named": "Todo items that are <i>dependencies</i> of this item.",
- "namedEscaped": false,
- "describedAs": "Other todo items that must be completed before this one",
- "labelPosition": "LEFT",
- "render": "EAGERLY"
- }
-}
-----
-
-
-
-
-
-include::_ug_reference-annotations_manpage-CollectionLayout_cssClass.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-CollectionLayout_describedAs.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-CollectionLayout_hidden.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-CollectionLayout_named.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-CollectionLayout_paged.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-CollectionLayout_render.adoc[leveloffset=+1]
-include::_ug_reference-annotations_manpage-CollectionLayout_sortedBy.adoc[leveloffset=+1]
-
-
-
-
-
-
[34/45] isis git commit: ISIS-1133: breaking out reference guide and
devenv guide;
moving appendices' release notes and migration notes to other docs;
improving the documentation page.
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-AuditingService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-AuditingService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-AuditingService.adoc
new file mode 100644
index 0000000..8109929
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-AuditingService.adoc
@@ -0,0 +1,84 @@
+[[_rg_services-spi_manpage-AuditingService]]
+= `AuditingService3`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `AuditingService3` auditing service provides a simple mechanism to capture changes to data. It is called for each property that has changed on any domain object, as a set of pre- and post-values.
+
+[NOTE]
+====
+In case you are wondering what happened to `AuditingService` and `AuditingService2`, these were earlier versions of the SPI that have since been deprecated and removed.
+====
+
+
+== SPI
+
+The SPI for the service is:
+
+[source,java]
+----
+public interface AuditingService3 {
+
+ @Programmatic
+ public void audit(
+ final UUID transactionId, String targetClassName, final Bookmark target,
+ String memberIdentifier, final String propertyName,
+ final String preValue, final String postValue,
+ final String user, final java.sql.Timestamp timestamp);
+ }
+----
+
+The framework will call this for each and every domain object property that is modified within a transaction.
+
+
+
+== Implementation
+
+The most full-featured available implementation is the (non-ASF) http://github.com/isisaddons/isis-module-audit[Isis addons' Audit module]. This creates an audit records for each changed property (ie every time that `AuditingService3#audit(...)` is called. The implementation is `org.isisaddons.module.audit.dom.AuditingService`.
+
+The module also provides:
+
+* `AuditingServiceMenu` service which provides actions to search for ``AuditEntry``s, underneath an 'Activity' menu on the secondary menu bar.
+
+* `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.
+
+
+
+If you just want to debug (writing to stderr), you can instead configure `o.a.i.applib.services.audit.AuditingService3$Stderr`
+
+
+
+== Usage
+
+The typical way to indicate that an object should be audited is to annotate it with the xref:rg.adoc#_rg_annotations_manpage-DomainObject_auditing[`@DomainObject#auditing()`] annotation.
+
+
+
+
+== Registering the Services
+
+Assuming that the `configuration-and-annotation` services installer is configured:
+
+[source,ini]
+----
+isis.services-installer=configuration-and-annotation
+----
+
+then adding the (non-ASF) http://github.com/isisaddons/isis-module-audit[Isis addons' audit] module to the classpath will automatically register the `AuditingService`, `AuditingServiceMenu`, `AuditingServiceRepository` and `AuditingServiceContributions` services. If menu items or contributions are not required in the UI, these can be suppressed either using security or by implementing a xref:ug.adoc#_ug_more-advanced_decoupling_vetoing-visibility[vetoing subscriber].
+
+
+
+== Related Services
+
+The auditing service works very well with the xref:rg.adoc#_rg_services-spi_manpage-CommandService[`CommandService`]. The `CommandService` captures the _cause_ of an interaction (an action was invoked, a property was edited), while the `AuditingService3` captures the _effect_ of that interaction in terms of changed state.
+
+You may also want to configure the xref:rg.adoc#_rg_services-spi_manpage-PublishingService[`PublishingService`].
+
+All three of these services collaborate implicitly by way of the xref:rg.adoc#_rg_classes_mixins_manpage-HasTransactionId[`HasTransactionId`] interface.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-BackgroundCommandService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-BackgroundCommandService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-BackgroundCommandService.adoc
new file mode 100644
index 0000000..2e1ea60
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-BackgroundCommandService.adoc
@@ -0,0 +1,129 @@
+[[_rg_services-spi_manpage-BackgroundCommandService]]
+= `BackgroundCommandService`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `BackgroundCommandService` (SPI) service supports the xref:rg.adoc#_rg_services-api_manpage-BackgroundService[`BackgroundService`] (API) service, persisting action invocations as commands such that they can subsequently be invoked in the background.
+
+The `BackgroundService` is responsible for capturing a memento representing the action invocation, and then hands off to the xref:rg.adoc#_rg_services-spi_manpage-BackgroundCommandService[`BackgroundCommandService`] `BackgroundCommandService` to actually persist it.
+
+The persisting of commands is only half the story; there needs to be a separate process to read the commands and execute them. The abstract xref:rg.adoc#_rg_services-api_manpage-BackgroundService_BackgroundCommandExecution[`BackgroundCommandExecution`] provides a mechanism to execute such commands. This can be considered an API, albeit "internal" because the implementation relies on internals of the framework.
+
+
+
+== SPI
+
+The SPI of the `BackgroundCommandService` is:
+
+[source,java]
+----
+public interface BackgroundCommandService {
+ void schedule(
+ ActionInvocationMemento aim, // <1>
+ Command parentCommand, // <2>
+ String targetClassName,
+ String targetActionName,
+ String targetArgs);
+
+}
+----
+<1> is a wrapper around a xref:rg.adoc#_rg_services-api_manpage-MementoService[`MementoService`]'s `Memento`, capturing the details of the action invocation to be retained (eg persisted to a database) so that it can be executed at a later time
+<2> reference to the parent `Command` requesting the action be performed as a background command. This allows information such as the initiating user to be obtained.
+
+The API of `ActionInvocationMemento` in turn is:
+
+[source,java]
+----
+public class ActionInvocationMemento {
+ public String getActionId() { ... }
+ public String getTargetClassName() { ... }
+ public String getTargetActionName() { ... }
+ public Bookmark getTarget() { ... }
+ public int getNumArgs() { ... }
+ public Class<?> getArgType(int num) throws ClassNotFoundException { ... }
+ public <T> T getArg(int num, Class<T> type) { ... }
+
+ public String asMementoString() { ... } // <1>
+}
+----
+<1> lets the `BackgroundCommandService` implementation convert the action invocation into a simple string.
+
+
+
+== "Internal" SPI
+
+The `BackgroundCommandExecution` (in isis-core) is an abstract template class for xref:ug.adoc#_ug_headless-access_AbstractIsisSessionTemplate[headless access], that defines an abstract hook method to obtain background `Command`s to be executed:
+
+[source,java]
+----
+public abstract class BackgroundCommandExecution
+ extends AbstractIsisSessionTemplate {
+ ...
+ protected abstract List<? extends Command> findBackgroundCommandsToExecute();
+ ...
+}
+----
+
+The developer is required to implement this hook method in a subclass.
+
+
+
+
+== Implementation
+
+The (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module provides an implementation (`org.isisaddons.module.command.dom.BackgroundCommandServiceJdo`) that persists ``Command``s using the JDO/DataNucleus object store. It further provides a number of supporting services:
+
+* `org.isisaddons.module.command.dom.BackgroundCommandServiceJdoRepository` is a repository to search for persisted background ``Command``s
+
+* `org.isisaddons.module.command.dom.BackgroundCommandServiceJdoContributions` contributes actions for searching for persisted child and sibling ``Command``s.
+
+The module also provides a concrete subclass of `BackgroundCommandExecution` that knows how to query for persisted (background) `Command`s such that they can be executed by a scheduler.
+
+[TIP]
+====
+Details of setting up the Quartz scheduler to actually execute these persisted commands can be found on the xref:rg.adoc#_rg_services-api_manpage-BackgroundService[`BackgroundService`] page.
+====
+
+
+
+
+== Usage
+
+Background commands can be created either declaratively or imperatively.
+
+The declarative approach involves annotating an action using xref:rg.adoc#_rg_annotations_manpage-Action_command[`@Action#command()`] with `@Action#commandExecuteIn=CommandExecuteIn.BACKGROUND`.
+
+The imperative approach involves explicitly calling the xref:rg.adoc#_rg_services-api_manpage-BackgroundService[`BackgroundService`] from within domain object's action.
+
+
+
+
+== Registering the Services
+
+Assuming that the `configuration-and-annotation` services installer is configured:
+
+[source,ini]
+----
+isis.services-installer=configuration-and-annotation
+----
+
+then adding the (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module to the classpath will automatically register the `BackgroundCommandServiceJdo`, `BackgroundCommandJdoRepository` and `BackgroundCommandServiceJdoContributions` services. If contributions are not required in the UI, these can be suppressed either using security or by implementing a xref:ug.adoc#_ug_more-advanced_decoupling_vetoing-visibility[vetoing subscriber].
+
+Note that this module also provides service implementations of the xref:rg.adoc#_rg_services-spi_manpage-CommandService[`CommandService`].
+
+
+
+
+== Related Services
+
+As discussed above, this service supports the xref:rg.adoc#_rg_services-api_manpage-BackgroundService[`BackgroundService`] , persisting `Command`s such that they can be executed in the background.
+
+There is also a tie-up with the xref:rg.adoc#_rg_services-api_manpage-CommandContext[`CommandContext`] and its supporting xref:rg.adoc#_rg_services-spi_manpage-CommandService[`CommandService`] domain service. The `CommandContext` service is responsible for providing a parent `Command` with which the background `Command`s can then be associated as children, while the `CommandService` is responsible for persisting those parent `Command`s (analogous to the way in which the `BackgroundCommandService` persists the child background `Command`s). The `BackgroundCommandService` ensures that these background `Command`s are associated with the parent "foreground" `Command`.
+
+What that means is that the implementations of `CommandService` and `BackgroundCommandService` go together, hence both implemented in the (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module.).
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-ClassDiscoveryService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-ClassDiscoveryService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-ClassDiscoveryService.adoc
new file mode 100644
index 0000000..db75edd
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-ClassDiscoveryService.adoc
@@ -0,0 +1,81 @@
+[[_rg_services-spi_manpage-ClassDiscoveryService]]
+= `ClassDiscoveryService`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `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.
+
+
+
+== SPI
+
+The SPI defined by the service is:
+
+[source,java]
+----
+public interface ClassDiscoveryService2 {
+ @Programmatic
+ <T> Set<Class<? extends T>> findSubTypesOfClasses(Class<T> type, String packagePrefix);
+ @Deprecated
+ @Programmatic
+ <T> Set<Class<? extends T>> findSubTypesOfClasses(Class<T> type); // <1>
+}
+----
+<1> no longer used
+
+
+
+== Implementation
+
+Isis provides an implementation of this service, namely `o.a.i.applib.services.classdiscovery.ClassDiscoveryServiceUsingReflections`.
+
+[NOTE]
+====
+This implementation is also used to discover domain services annotated with xref:rg.adoc#_rg_annotations_manpage-DomainService[`@DomainService`]. Currently this logic uses the implementation directly, so is not pluggable. However, the entire `ServicesInstaller`
+====
+
+
+
+== Usage
+
+The usage will vary depending upon the conventions of the design. In the case of fixture scripts, the convention is to implement scripts by subclassing xref:rg.adoc#_rg_classes_super_manpage-FixtureScript[`FixtureScript`], and to specify the package prefix in the constructor for xref:rg.adoc#_rg_classes_super_manpage-FixtureScripts[`FixtureScripts`].
+
+For example, the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] has its fixture scripts in the `todoapp.fixture` package. the `ToDoAppFixturesService` (its subclass of xref:rg.adoc#_rg_classes_super_manpage-FixtureScripts[`FixtureScripts`] is in the same package, so its constructor is:
+
+[source,java]
+----
+package todoapp.fixture;
+...
+@DomainService(nature = NatureOfService.VIEW_MENU_ONLY)
+public class ToDoAppFixturesService extends FixtureScripts {
+ public ToDoAppFixturesService() {
+ super(
+ ToDoAppFixturesService.class.getPackage().getName(), // <1>
+ MultipleExecutionStrategy.EXECUTE);
+ }
+ ...
+}
+----
+<1> specify the package prefix to search under for fixture scripts
+
+Other designs using this service are likely to work in a similar way, requiring some sort of scope to be specified.
+
+
+== Registering the Services
+
+Assuming that the `configuration-and-annotation` services installer is configured:
+
+[source,ini]
+----
+isis.services-installer=configuration-and-annotation
+----
+
+then 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/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-CommandService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-CommandService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-CommandService.adoc
new file mode 100644
index 0000000..5f3026d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-CommandService.adoc
@@ -0,0 +1,99 @@
+[[_rg_services-spi_manpage-CommandService]]
+= `CommandService`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `CommandService` service supports the xref:rg.adoc#_rg_services-api_manpage-CommandContext[`CommandContext`] service such that `Command` objects (that reify the invocation of an action on a domain object into an object) can be persisted.
+
+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:rg.adoc#_rg_services-api_manpage-BackgroundService[`BackgroundService`]
+* if xref:rg.adoc#_rg_services-spi_manpage-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:rg.adoc#_rg_services-spi_manpage-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`]
+* the associated xref:rg.adoc#_rg_annotations_manpage-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.
+
+
+
+The screencast below provides a run-through of the command (profiling) service, auditing service, publishing service. It also shows how commands can be run in the background either explicitly by scheduling through the background service or implicitly by way of a framework annotation.
+
+
+
+video::tqXUZkPB3EI[youtube,width="560px",height="315px"]
+
+[NOTE]
+====
+Note that this screencast shows an earlier version of the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] UI (specifically, pre 1.8.0).
+====
+
+
+== SPI
+
+The `CommandService` service defines the following very simple API:
+
+[source,java]
+----
+public interface CommandService {
+ @Programmatic
+ Command create();
+ @Programmatic
+ void startTransaction(Command command, final UUID transactionId);
+ @Programmatic
+ void complete(Command command);
+ @Programmatic
+ boolean persistIfPossible(Command command);
+}
+----
+
+where `Command` is defined as defined by the xref:rg.adoc#_rg_services-api_manpage-CommandContext[`CommandContext`] service.
+
+
+== Implementation
+
+The (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module provides an implementation (`org.isisaddons.module.command.dom.CommandServiceJdo`) that persists ``Command``s using the JDO/DataNucleus object store. It further provides a number of supporting services:
+
+* `org.isisaddons.module.command.dom.CommandServiceJdoRepository` is a repository to search for persisted ``Command``s
+
+* `org.isisaddons.module.command.dom.CommandServiceJdoContributions` contributes actions for searching for persisted child and sibling ``Command``s.
+
+
+
+== Usage
+
+The typical way to indicate that an action should be reified into a `Command` is by annotating the action using xref:rg.adoc#_rg_annotations_manpage-Action_command[`@Action#command()`].
+
+
+
+
+== Registering the Services
+
+Assuming that the `configuration-and-annotation` services installer is configured:
+
+[source,ini]
+----
+isis.services-installer=configuration-and-annotation
+----
+
+
+then adding the (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module to the classpath will automatically register the `CommandServiceJdo`, `CommandJdoRepository` and `CommandServiceJdoContributions` services. If contributions are not required in the UI, these can be suppressed either using security or by implementing a xref:ug.adoc#_ug_more-advanced_decoupling_vetoing-visibility[vetoing subscriber].
+
+Note that this module also provides service implementations of the xref:rg.adoc#_rg_services-spi_manpage-BackgroundCommandService[`BackgroundCommandService`].
+
+
+
+== Related Services
+
+As discussed above, this service supports the xref:rg.adoc#_rg_services-api_manpage-CommandContext[`CommandContext`], providing the ability for `Command` objects to be
+persisted. This is closely related to the xref:rg.adoc#_rg_services-spi_manpage-BackgroundCommandService[`BackgroundCommandService`]that allows the xref:rg.adoc#_rg_services-api_manpage-BackgroundService[`BackgroundService`] to schedule commands for background/asynchronous execution.
+
+The implementations of `CommandService` and `BackgroundCommandService` are intended to go together, so that persistent parent `Command`s can be associated with their child background `Command`s.
+
+The services provided by this module combines very well with the xref:rg.adoc#_rg_services-spi_manpage-AuditingService[`AuditingService`]. The `CommandService` captures the _cause_ of an interaction (an action was invoked, a property was edited), while the `AuditingService3` captures the _effect_ of that interaction in terms of changed state.
+
+You may also want to configure the xref:rg.adoc#_rg_services-spi_manpage-PublishingService[`PublishingService`].
+
+All three of these services collaborate implicitly by way of the xref:rg.adoc#_rg_classes_mixins_manpage-HasTransactionId[`HasTransactionId`] interface.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-ContentMappingService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-ContentMappingService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-ContentMappingService.adoc
new file mode 100644
index 0000000..f55aa82
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-ContentMappingService.adoc
@@ -0,0 +1,106 @@
+[[_rg_services-spi_manpage-ContentMappingService]]
+= `ContentMappingService`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `ContentMappingService` supports the (default implementation of the) xref:rg.adoc#_rg_services-spi_manpage-ContentNegotiationService[`ContentNegotiationService`] allowing the xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer] to allow domain objects to be transformed into some other format as specified by the HTTP `Accept` header.
+
+See xref:rg.adoc#_rg_services-spi_manpage-ContentNegotiationService[`ContentNegotiationService`] for further discussion.
+
+
+
+
+== SPI
+
+The SPI defined by this service is:
+
+[source,java]
+----
+public interface ContentMappingService {
+ @Programmatic
+ Object map(Object object, // <1>
+ List<MediaType> acceptableMediaTypes, // <2>
+ RepresentationType representationType); // <3>
+
+}
+
+----
+<1> typically the input is a domain object (whose structure might change over time), and the output is a DTO (whose structure is guaranteed to be preserved over time)
+<2> as per the caller's HTTP `Accept` header
+<3> the representation type required (as per the link:http://restfulobjects.org[Restful Objects spec]).
+
+
+[WARNING]
+====
+This is an "internal" SPI, meaning that it uses types that are not part of the Isis applib. We do not guarantee that link:http://semver.org[semantic versioning] will be honoured for these APIs.
+====
+
+
+== Implementations
+
+No default implementations are provided by Isis framework itself. However, the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] includes a sample implementation to convert its `ToDoItem` entity into a `ToDoItemDto` (JAXB annotated and derived from an XSD). This uses the link:http://orika-mapper.github.io/orika-docs/intro.html[Orika] mapping library.
+
+The source code is:
+
+[source,java]
+----
+@DomainService(nature = NatureOfService.DOMAIN)
+public class CustomContentMappingService implements ContentMappingService {
+ private MapperFactory mapperFactory; // <1>
+ @Programmatic
+ @PostConstruct
+ public void init() {
+ mapperFactory = new DefaultMapperFactory.Builder().build();
+ mapperFactory.registerClassMap(
+ mapperFactory.classMap(ToDoItem.class, ToDoItemDto.class) // <2>
+ .byDefault() // <3>
+ .toClassMap());
+ mapperFactory.registerClassMap(
+ mapperFactory.classMap(Bookmark.class, OidDto.class) // <4>
+ .field("identifier", "objectIdentifier") // <5>
+ .byDefault() // all other fields are compatible // <6>
+ .toClassMap());
+ }
+ @Programmatic
+ @Override // <7>
+ public Object map(
+ final Object object,
+ final List<MediaType> acceptableMediaTypes,
+ final RepresentationType representationType) {
+ if(object instanceof ToDoItem) {
+ final Bookmark bookmark = bookmarkService.bookmarkFor(object);
+ final ToDoItemDto dto =
+ mapperFactory.getMapperFacade().map(object, ToDoItemDto.class); // <8>
+ final OidDto oidDto =
+ mapperFactory.getMapperFacade().map(bookmark, OidDto.class); // <9>
+ dto.setOid(oidDto); // <10>
+ return dto;
+ }
+ return null;
+ }
+
+ @javax.inject.Inject
+ private BookmarkService bookmarkService;
+}
+----
+<1> registry of known mappings
+<2> how to map `ToDoItem` to `ToDoItemDto` ...
+<3> ... all properties have same name in both source and destination types
+<4> how to map `Bookmark` to `OidDto` ...
+<5> ... this property has a different name
+<6> ... all other properties have same name
+<7> the main API to implement. This implementation ignores the `acceptableMediaTypes` and `representationType`
+<8> map the domain object to the DTO
+<9> and map its oid (by way of the xref:rg.adoc#_rg_services-api_manpage-BookmarkService[`BookmarkService`]
+<10> and perform some additional manual wiring (because domain objects don't _know_ their Oids).
+
+You'll notice that the implementation doesn't actually use the `acceptableMediaTypes` and `representationType` parameters. That's because the calling `ContentNegotiationServiceXRoDomainType` will double check that the returned object is of the correct type (as defined by the `x-ro-domain-type` parameter of the HTTP `Accept` header). Since this (example) todoapp only offers a single mapping, there's therefore no need to for the mapping service to check further.
+
+
+
+== Related Services
+
+This service is a companion to the default implementation of the xref:rg.adoc#_rg_services-spi_manpage-ContentNegotiationService[`ContentNegotiationService`].
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-ContentNegotiationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-ContentNegotiationService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-ContentNegotiationService.adoc
new file mode 100644
index 0000000..eac2dc7
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-ContentNegotiationService.adoc
@@ -0,0 +1,189 @@
+[[_rg_services-spi_manpage-ContentNegotiationService]]
+= `ContentNegotiationService`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `ContentNegotiationService` is a plug-in point for the xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer] so that it can generate representations according to HTTP `Accept` header of the request. This idea is discussed in section 34.1 of the link:http://restfulobjects.org[Restful Objects spec] v1.0.
+
+The principal motivation is to allow more flexible representations to be generated for REST clients that (perhaps through their use of a certain Javascript library, say) expect, or at least works best with, a certain style of representation.
+
+Another use case is to support "third party" REST clients over which you have no control. In this scenario you _must not_ naively expose entities through the RO viewer, because over time those entities will inevitably evolve and change their structure. If the entities were exposed directly then those REST clients will break.
+
+Instead you need to create some sort of stable facade over your domain entities, one which you will preserve even if the domain entities change. There are three ways in which you can do this:
+
+* first is to solve the problem at the domain layer by defining a regular Isis xref:ug.adoc#_ug_more-advanced_view-models[view model]. This is then surfaced over the RO viewer. +
++
+If the underlying entities change, then care must be taken to ensure that structure of the view model nevertheless is unchanged.
+
+* a second option is to solve the problem at the persistence layer, but defining a (SQL) view in the database and then xref:ug.adoc#_ug_more-advanced_mapping-rdbms-views[mapping this] to a (read-only) entity. Again this is surfaced by the RO viewer. +
++
+If the underlying tables change (as the result of a change in their corresponding domain entities) then once more the view must be refactored so that it still presents the same structure.
+
+* our third option is to solve the problem at the presentation layer, using the `ContentNegotiationService` described in this section. +
++
+The `ContentNegotiationService` is responsible for inspecting the HTTP `Accept` header, and use this to select the correct representation to render. +
++
+The Isis framework provides a default implementation of `ContentNegotiationService` which inspects the "x-ro-domaintype" component of the HTTP `Accept` header. If present, this implementation will delegate to the companion xref:rg.adoc#_rg_services-spi_manpage-ContentMappingService[`ContentMappingService`] service, if configured. +
++
+A typical implementation of `ContentMappingService` will convert the domain object into some sort of DTO (data transfer object) as specified by the "x-ro-domaintype". If this DTO is annotated with JAXB or Jackson mappings, then the RO viewer (courtesy of the underlying link:http://resteasy.jboss.org/[RestEasy] framework) can serialize these directly +
++
+What all that means is that, if the underlying entities change, we are required to update the mappings in the `ContentMappingService` to map to the same DTOs.
+
+This diagram illustrates the three options available:
+
+image::{_imagesdir}reference-services-spi/ContentNegotiationService/facade-choices.png[width="700px",link="{_imagesdir}reference-services-spi/ContentNegotiationService/facade-choices.png"]
+
+
+
+
+== SPI
+
+The SPI defined by this service is:
+
+[source,java]
+----
+public interface ContentNegotiationService {
+ @Programmatic
+ Response.ResponseBuilder buildResponse( // <1>
+ RepresentationService.Context2 renderContext2,
+ ObjectAdapter objectAdapter);
+ @Programmatic
+ Response.ResponseBuilder buildResponse( // <2>
+ RepresentationService.Context2 renderContext2,
+ ObjectAndProperty objectAndProperty);
+ @Programmatic
+ Response.ResponseBuilder buildResponse( // <3>
+ RepresentationService.Context2 renderContext2,
+ ObjectAndCollection objectAndCollection);
+ @Programmatic
+ Response.ResponseBuilder buildResponse( // <4>
+ RepresentationService.Context2 renderContext2,
+ ObjectAndAction objectAndAction);
+ @Programmatic
+ Response.ResponseBuilder buildResponse( // <5>
+ RepresentationService.Context2 renderContext2,
+ ObjectAndActionInvocation objectAndActionInvocation);
+}
+----
+<1> representation of a single object, as per section 14.4 of the RO spec, v1.0
+<2> representation of a single property of an object, as per section 16.4 of the RO spec v1.0
+<3> representation of a single collection of an object, as per section 17.5 of the RO spec v1.0
+<4> representation of a single action (prompt) of an object, as per section 18.2 of the RO spec v1.0
+<5> representation of the results of a single action invocation, as per section 19.5 of the RO spec v1.0
+
+These methods provide:
+
+* a `RepresentationService.Context2` which provides access to request-specific context (eg HTTP headers), session-specific context (eg authentication) and global context (eg configuration settings)
+
+* an object representing the information to be rendered +
++
+eg `ObjectAdapter`, `ObjectAndProperty`, `ObjectAndCollection` etc
+
+In all cases, returning `null` will result in the regular RO spec representation being returned.
+
+
+[WARNING]
+====
+This is an "internal" SPI, meaning that it uses types that are not part of the Isis applib. We do not guarantee that link:http://semver.org[semantic versioning] will be honoured for these APIs.
+====
+
+
+
+== Implementation
+
+`ContentNegotiationServiceAbstract` (in `o.a.i.v.ro.rendering.service.conneg`) provides a no-op implementation of the SPI, along with supporting methods:
+
+[source,java]
+----
+public abstract class ContentNegotiationServiceAbstract implements ContentNegotiationService {
+ ...
+ protected Object objectOf(final ObjectAdapter objectAdapter) { ... }
+ protected Object returnedObjectOf(ObjectAndActionInvocation objectAndActionInvocation) { ... }
+
+ protected Class<?> loadClass(String cls) { ... }
+
+ protected void ensureJaxbAnnotated(Class<?> domainType) { ... }
+ protected void ensureDomainObjectAssignable(
+ String xRoDomainType, Class<?> domainType, Object domainObject) { ... }
+}
+----
+
+As discussed in the introduction, the framework also provides a default implementation, `o.a.i.v.ro.rendering.service.conneg.ContentNegotiationServiceXRoDomainType`. This handles content negotiation for two of the possible representations, object representations and for action result representations:
+
+* For object representations it will handle requests with HTTP `Accept` headers of the form:
+** `application/json;profile=urn:org.restfulobjects:repr-types/object;x-ro-domain-type=...`
+** `application/xml;profile=urn:org.restfulobjects:repr-types/object;x-ro-domain-type=...`
+
+* for action result representations it will similarly handle requests with HTTP `Accept` headers of the form:
+** `application/json;profile=urn:org.restfulobjects:repr-types/action-result;x-ro-domain-type=...` +
+** `application/xml;profile=urn:org.restfulobjects:repr-types/action-result;x-ro-domain-type=...`
+
+
+The value of the `x-ro-domain-type` parameter corresponds to the DTO to be mapped into by the xref:rg.adoc#_rg_services-spi_manpage-ContentMappingService[`ContentMappingService`].
+
+If the DTO is annotated with JAXB, then also note that the runtime type must be annotated with the JAXB `javax.xml.bind.annotation.XmlRootElement` so that RestEasy is able to unambiguously serialize it.
+
+
+
+
+== Usage
+
+You can find an example of all these services in the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp]. This defines a `ToDoItemDto` class that is JAXB annotated (it is in fact generated from an XSD).
+
+The example app also includes an implementation of `ContentMappingService` that maps `todoapp.dom.module.todoitem.ToDoItem` entities to `todoapp.dto.module.todoitem.ToDoItemDto` classes.
+
+A REST client can therefore request a DTO representation of an entity by invoking
+
+[source]
+----
+http://localhost:8080/restful/objects/TODO/0
+----
+
+with an `Accept` header of:
+
+[source]
+----
+application/xml;profile=urn:org.restfulobjects:repr-types/object;x-ro-domain-type=todoapp.dto.module.todoitem.ToDoItemDto
+----
+
+will result in an XML serialization of that class:
+
+image::{_imagesdir}reference-services-spi/ContentNegotiationService/accept-xml.png[width="700px",link="{_imagesdir}reference-services-spi/ContentNegotiationService/accept-xml.png"]
+
+
+while similarly hitting the same URL with an `Accept` header of:
+
+[source]
+----
+application/json;profile=urn:org.restfulobjects:repr-types/object;x-ro-domain-type=todoapp.dto.module.todoitem.ToDoItemDto
+----
+
+will result in the JSON serialization of that class:
+
+image::{_imagesdir}reference-services-spi/ContentNegotiationService/accept-json.png[width="700px",link="{_imagesdir}reference-services-spi/ContentNegotiationService/accept-json.png"]
+
+
+
+
+== Registering the Services
+
+Assuming that the `configuration-and-annotation` services installer is configured:
+
+[source,ini]
+----
+isis.services-installer=configuration-and-annotation
+----
+
+then Isis' default implementation of `ContentNegotiationService` service is automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
+
+
+
+
+== Related Services
+
+The default implementation of `ContentNegotiationService` delegates to xref:rg.adoc#_rg_services-spi_manpage-ContentMappingService[`ContentMappingService`] (if present) to convert domain entities into a stable form (eg DTO).
+
+The `ContentNegotiationService` is itself called by the (default implementation of) xref:rg.adoc#_rg_services-spi_manpage-RepresentationService[`RepresentationService`].
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-EmailNotificationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-EmailNotificationService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-EmailNotificationService.adoc
new file mode 100644
index 0000000..97ce2a2
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-EmailNotificationService.adoc
@@ -0,0 +1,80 @@
+[[_rg_services-spi_manpage-EmailNotificationService]]
+= `EmailNotificationService`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `EmailNotificationService` supports the xref:ug.adoc#_ug_wicket-viewer_features_user-registration[user registration] (self sign-up) features of the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] whereby a user can sign-up to access an application by providing a valid email address.
+
+The Wicket viewer will check whether an implementation of this service (and also the xref:rg.adoc#_rg_services-spi_manpage-UserRegistrationService[`UserRegistrationService`]) is available, and if so will (unless configured not to) expose a sign-up page where the user enters their email address. A verification email is sent using this service; the email includes a link back to the running application. The user then completes the registration process (choosing a user name, password and so on) and the Wicket viewer creates an account for them (using the aforementioned `UserRegistrationService`).
+
+The role of this service in all of this is to format and send out emails for the initial registration, or for password resets.
+
+The default implementation of this service uses the xref:rg.adoc#_rg_services-api_manpage-EmailService[`EmailService`], which must be configured in order for user registration to be enabled.
+
+
+== SPI
+
+The SPI defined by this service is:
+
+[source,java]
+----
+public interface EmailNotificationService extends Serializable {
+ @Programmatic
+ boolean send(EmailRegistrationEvent ev); // <1>
+ @Programmatic
+ boolean send(PasswordResetEvent ev); // <2>
+ @Programmatic
+ boolean isConfigured(); // <3>
+}
+----
+<1> sends an email to verify an email address as part of the initial user registration
+<2> sends an email to reset a password for an already-registered user
+<3> determines whether the implementation was configured and initialized correctly
+
+If `isConfigured()` returns false then it is _not_ valid to call `send(...)` (and doing so will result in an `IllegalStateException` being thrown.
+
+
+== Implementation
+
+The framework provides a default implementation, `o.a.i.core.runtime.services.userreg.EmailNotificationServiceDefault` that constructs the emails to send.
+
+
+
+=== Alternative Implementations
+
+The text of these email templates is hard-coded as resources, in other words baked into the core jar files. If you need to use different text then you can of course always write and register your own implementation to be used instead of Isis' default.
+
+If you have configured an alternative email service implementation, it should process the message body as HTML.
+
+If you wish to write an alternative implementation of this service, note that (unlike most Isis domain services) the implementation is also instantiated and injected by Google Guice. This is because `EmailNotificationService` is used as part of the xref:ug.adoc#_ug_wicket-viewer_features_user-registration[user registration] functionality and is used by Wicket pages that are accessed outside of the usual Isis runtime.
+
+This implies a couple of additional constraints:
+
+* first, implementation class should also be annotated with `@com.google.inject.Singleton`
+* second, there may not be any Isis session running. (If necessary, one can be created on the fly using `IsisContext.doInSession(...)`)
+
+To ensure that your alternative implementation takes the place of the default implementation, register it explicitly in `isis.properties`.
+
+
+
+== Registering the Service
+
+Assuming that the `configuration-and-annotation` services installer is configured:
+
+[source,ini]
+----
+isis.services-installer=configuration-and-annotation
+----
+
+then Isis' default implementation of `EmailNotificationService` service is automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
+
+
+== Related Services
+
+As noted elsewhere, the default implementation of this service uses xref:rg.adoc#_rg_services-api_manpage-EmailService[`EmailService`]. This service has no specific configuration properties but does require that the `EmailService` has been configured.
+
+Conversely, this service is used by (Isis' default implementation of) xref:rg.adoc#_rg_services-spi_manpage-UserRegistrationService[`UserRegistrationService`].
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-EventSerializer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-EventSerializer.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-EventSerializer.adoc
new file mode 100644
index 0000000..72c584e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-EventSerializer.adoc
@@ -0,0 +1,72 @@
+[[_rg_services-spi_manpage-EventSerializer]]
+= `EventSerializer`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `EmailSerializer` service is a supporting service intended for use by (any implementation of) xref:rg.adoc#_rg_services-spi_manpage-PublishingService[`PublishingService`]. Its responsibility is to combine the `EventMetadata` and the `EventPayload` into some serialized form (such as JSON, XML or a string) that can then be published.
+
+See xref:rg.adoc#_rg_services-spi_manpage-PublishingService[`PublishingService`] for further discussion.
+
+
+
+
+== SPI
+
+The SPI defined by this service is:
+
+[source,java]
+----
+public interface EventSerializer {
+ Object serialize( // <1>
+ EventMetadata metadata, // <2>
+ EventPayload payload); // <3>
+}
+----
+<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
+<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.
+
+
+
+
+
+== Implementation
+
+The (non-ASF) http://github.com/isisaddons/isis-module-publishing[Isis addons' publishing] module provides an implementation (`org.isisaddons.module.publishing.dom.eventserializer.RestfulObjectsSpecEventSerializer`) that represents the event payload using the representation defined by the link:http://restfulobjects.org[Restful Objects spec] of (transient) objects, grafting on the metadata as additional JSON nodes.
+
+For example, this is the JSON generated on an action invocation:
+
+.JSON representation of a published action invocation
+image::{_imagesdir}reference-services-spi/EventSerializer/action-invocation-published-to-stderr.png[width="750px",link="{_imagesdir}reference-services-spi/EventSerializer/action-invocation-published-to-stderr.png"]
+
+while this is the object change JSON:
+
+.JSON representation of a published changed object
+image::{_imagesdir}reference-services-spi/EventSerializer/changed-object-published-to-stderr.png[width="750px",link="{_imagesdir}reference-services-spi/EventSerializer/changed-object-published-to-stderr.png"]
+
+You could if you wish change the representation by registering your own implementation of this API in `isis.properties`:
+
+
+
+
+
+== Registering the Services
+
+Assuming that the `configuration-and-annotation` services installer is configured:
+
+[source,ini]
+----
+isis.services-installer=configuration-and-annotation
+----
+
+then adding the (non-ASF) http://github.com/isisaddons/isis-module-publishing[Isis addons' publishing] module to the classpath will automatically register the `RestfulObjectsSpecEventSerializer` implementation (and also the module's `PublishingService` implementation).
+
+
+
+== Related Services
+
+This service is intended (though not mandated) to be used by implementations of xref:rg.adoc#_rg_services-spi_manpage-PublishingService[`PublishingService`].
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-ExceptionRecognizer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-ExceptionRecognizer.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-ExceptionRecognizer.adoc
new file mode 100644
index 0000000..84e6c65
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-ExceptionRecognizer.adoc
@@ -0,0 +1,123 @@
+[[_rg_services-spi_manpage-ExceptionRecognizer]]
+= `ExceptionRecognizer`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `ExceptionRecognizer` service provides the mechanism for both the domain programmer and also for components to be able to recognize and handle certain exceptions that may be thrown by the system. Rather than display an obscure error to the end-user, the application can instead display a user-friendly message.
+
+For example, the JDO/DataNucleus Objectstore provides a set of recognizers to recognize and handle SQL constraint exceptions such as uniqueness violations. These can then be rendered back to the user as expected errors, rather than fatal stacktraces.
+
+It is also possible to provide additional implementations, registered in `isis.properties`. Unlike other services, where any service registered in `isis.properties` replaces any default implementations, in the case of this service all implementations registered are "consulted" to see if they recognize an exception (the chain-of-responsibility pattern).
+
+
+
+
+== SPI
+
+The SPI defined by this service is:
+
+[source,java]
+----
+public interface ExceptionRecognizer2 ... {
+ public enum Category { // <1>
+ ...
+ }
+ public static class Recognition { // <2>
+ private Category category;
+ private String reason;
+ ...
+ }
+ @Programmatic
+ public Recognition recognize2(Throwable ex); // <3>
+
+ @Deprecated
+ @Programmatic
+ public String recognize(Throwable ex); // <4>
+
+}
+----
+<1> an enumeration of varies categories of exceptions that are recognised
+<2> represents the fact that an exception has been recognized as has been converted into a user-friendy message, and has been categorized
+<3> the main API, to attempt to recognize an exception
+<4> deprecated API which converted exceptions into strings (reasons), ie without any categorization. This is no longer called.
+
+
+The categories are:
+
+[source,java]
+----
+public interface ExceptionRecognizer2 ... {
+ public enum Category {
+ CONSTRAINT_VIOLATION, // <1>
+ NOT_FOUND, // <2>
+ CONCURRENCY, // <3>
+ CLIENT_ERROR, // <4>
+ SERVER_ERROR, // <5>
+ OTHER // <6>
+ }
+ ...
+}
+
+----
+<1> a violation of some declarative constraint (eg uniqueness or referential integrity) was detected.
+<2> the object to be acted upon cannot be found (404)
+<3> a concurrency exception, in other words some other user has changed this object.
+<4> recognized, but for some other reason... 40x error
+<5> 50x error
+<6> recognized, but uncategorized (typically: a recognizer of the original `ExceptionRecognizer` API).
+
+
+In essence, if an exception is recognized then it is also categorized. This lets the viewer act accordingly. For example, if an exception is raised from the loading of an individual object, then this is passed by the registered ``ExceptionRecognizer``s. If any of these recognize the exception as representing a not-found exception, then an Isis `ObjectNotFoundException` is raised. Both the viewers interprets this correctly (the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] as a suitable error page, the xref:ug.adoc#_ug_restfulobjects-viewer[Restful Objects viewer] as a 404 status return code).
+
+
+If the implementation recognizes the exception then it returns a user-friendly message to be rendered (by the viewer) back to the user; otherwise it returns `null`. There is no need for the implementation to check for exception causes; the casual chain is unwrapped by Isis core and each exception in the chain will also be passed through to the recognizer (from most specific to least). The recognizer implementation can therefore be as fine-grained or as coarse-grained as it wishes.
+
+
+
+
+== Implementation
+
+The framework provides two default implementations:
+
+* `o.a.i.core.metamodel.services.container.DomainObjectContainerDefault` provided by Isis core is itself an `ExceptionRecognizer`, and will handle ``ConcurrencyException``s. It will also handle any application exceptions raised by the system (subclasses of `o.a.i.applib.RecoverableException`).
+
+* `o.a.i.objectstore.jdo.applib.service.exceprecog.ExceptionRecognizerCompositeForJdoObjectStore` bundles up a number of more fine-grained implementations:
+** `ExceptionRecognizerForSQLIntegrityConstraintViolationUniqueOrIndexException`
+** `ExceptionRecognizerForJDOObjectNotFoundException`
+** `ExceptionRecognizerForJDODataStoreException`
+
+
+If you want to recognize and handle additional exceptions (for example to capture error messages specific to the JDBC driver you might be using), then create a fine-grained implementation of `ExceptionRecognizer2` for the particular error message (there are some convenience implementations of the interface that you can subclass from if required) and register in `isis.properties`.
+
+
+
+
+== Registering the Services
+
+
+Assuming that the `configuration-and-annotation` services installer is configured:
+
+[source,ini]
+----
+isis.services-installer=configuration-and-annotation
+----
+
+then the default implementations provided by the framework (`DomainObjectContainerDefault` and `ExceptionRecognizerCompositeForJdoObjectStore`) will be registered.
+
+In addition, you can register any further exception recognizers in `isis.properties`:
+
+[source,ini]
+----
+isis.services=...,\
+ com.mycompany.myapp.MyExceptionRecognizer,\
+ ...
+----
+
+[NOTE]
+====
+Prior to 1.9.0, the `ExceptionRecognizerCompositeForJdoObjectStore` also required manual registration:
+
+====
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-LocaleProvider.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-LocaleProvider.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-LocaleProvider.adoc
new file mode 100644
index 0000000..eb4085e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-LocaleProvider.adoc
@@ -0,0 +1,71 @@
+[[_rg_services-spi_manpage-LocaleProvider]]
+= `LocaleProvider`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `LocaleProvider` service is one of the services that work together to implement Isis' support for i18n, being used by Isis' default implementation of xref:rg.adoc#_rg_services-spi_manpage-TranslationService[`TranslationService`].
+
+The role of the service itself is simply to return the `Locale` of the current user.
+
+
+[NOTE]
+====
+For the "big picture" and further details on Isis' i18n support, see xref:ug.adoc#_ug_more-advanced_i18n[here].
+====
+
+
+
+== SPI
+
+The SPI defined by this service is:
+
+[source,java]
+----
+public interface LocaleProvider {
+ @Programmatic
+ Locale getLocale();
+}
+----
+
+This is notionally request-scoped, returning the `Locale` of the current user; _not_ that of the server. (Note that the implementation is not required to actually be xref:rg.adoc#_rg_annotations_manpage-RequestScoped[`@RequestScoped`], however).
+
+
+
+
+== Implementation
+
+Isis' xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] provides an implementation of this service (`LocaleProviderWicket`) which leverages Apache Wicket APIs.
+
+[NOTE]
+====
+Currently there is no equivalent implementation for the xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer].
+====
+
+
+
+
+== Registering the Services
+
+Assuming that the `configuration-and-annotation` services installer is configured:
+
+[source,ini]
+----
+isis.services-installer=configuration-and-annotation
+----
+
+and that the xref:ug.adoc#_ug_wicket-viewer[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.
+
+
+
+
+
+== Related Services
+
+This service works in conjunction with xref:rg.adoc#_rg_services-spi_manpage-TranslationService[`TranslationService`] and xref:rg.adoc#_rg_services-spi_manpage-TranslationsResolver[`TranslationsResolver`] in order to provide i18n support.
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-PublishingService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-PublishingService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-PublishingService.adoc
new file mode 100644
index 0000000..cb35e8f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-PublishingService.adoc
@@ -0,0 +1,163 @@
+[[_rg_services-spi_manpage-PublishingService]]
+= `PublishingService`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `PublishingService` is intended for coarse-grained publish/subscribe for system-to-system interactions, from Isis to some other system. Here the only events published are those that action invocations and of changed objects. A typical use case is to publish onto a pub/sub bus such as link:http://activemq.apache.org/[ActiveMQ] with link:http://camel.apache.org[Camel] to keep other systems up to date.
+
+
+
+== SPI
+
+The SPI defined by the service is:
+
+[source,java]
+----
+public interface PublishingService {
+ public void publish(
+ EventMetadata metadata, // <1>
+ EventPayload payload); // <2>
+ @Deprecated
+ @Programmatic
+ 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
+<2> for published actions, an `EventPayloadForActionInvocation` (or subclass thereof); for published objects, an `EventPayloadForObjectChanged` (or subclass thereof)
+<3> injects in the xref:rg.adoc#_rg_services-spi_manpage-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.
+
+
+Typically implementations will use the injected `EventSerializer` to convert the metadata and payload into a form to be published:
+
+[source,java]
+----
+public interface EventSerializer {
+ public Object serialize(EventMetadata metadata, EventPayload payload);
+}
+----
+
+The serialized form returned by `EventSerializer` must be in a form that the `PublishingService` implementation is able to handle. Strings are a good lowest common denominator, but (if custom implementations of both `EventSerializer` and `PublishingService` were in use) then it might also be some other type, for example an `org.w3c.dom.Document` or an `org.json.JSONObject` might be returned instead.
+
+
+
+== Implementation
+
+The (non-ASF) http://github.com/isisaddons/isis-module-publishing[Isis addons' publishing] module provides an implementation (`org.isisaddons.module.publishing.dom.org.apache.isis.applib.services.publish`) that persists each event as a `PublishedEvent` entity. This holds the serialized form of the event metadata and payload as translated into a string by the injected `EventSerializer`. The module also provides its own implementation of `EventSerializer`, namely `RestfulObjectsSpecEventSerializer`, which represents the event payload using the representation defined by the link:http://restfulobjects.org[Restful Objects spec] of (transient) objects, grafting on the metadata as additional JSON nodes.
+
+The `PublishedEvent` entity also has a `state` field taking the values either "QUEUED" or "PROCESSED". The intention here is that an event bus can poll this table to grab pending events and dispatch them to downstream systems. When ``PublishedEvent``s are persisted initially they always take the value "QUEUED".
+
+
+
+
+== Usage
+
+To indicate that an action invocation should be published, annotate it with the xref:rg.adoc#_rg_annotations_manpage-Action_publishing[`@Action#publishing()`] annotation.
+
+To indicate that a changed object should be published is to annotate it with the xref:rg.adoc#_rg_annotations_manpage-DomainObject_publishing[`@DomainObject#publishing()`] annotation.
+
+
+It is also possible to "fine-tune" the `EventPayload` using the `#publishingFactory()` attribute (for both annotations). By default the `EventPayload` that is serialized identifies the object(s) being interacted with or changed, and in the case of the action invocation provides details of the action arguments and result (if any) of that action. However, the payload does not (by default) include any information about the new state of these objects. It is therefore the responsibility of the subscriber to call back to Isis to determine any information that has not been published.
+
+Although the representations (if using the Restful Object serializer and Restful Objects viewer) does include hrefs for the objects, this nevertheless requires an additional network call to obtain this information).
+
+In some circumstances, then, it may make more sense to eagerly "push" information about the change to the subscriber by including that state within the payload.
+
+To accomplish this, an implementation of a "`PayloadFactory`" must be specified in the annotation.
+
+For actions, we implement the `PublishingPayloadFactoryForAction` (in `o.a.i.applib.annotation`):
+
+[source,java]
+----
+public interface PublishingPayloadFactoryForAction {
+ @Programmatic
+ public EventPayload payloadFor(
+ Identifier actionIdentifier,
+ Object target,
+ List<Object> arguments,
+ Object result);
+}
+}
+----
+The `EventPayloadForActionInvocation` abstract class (in the Isis applib) should be used as the base class for the object instance returned from `payLoadFor(...)`.
+
+For objects, the interface to implement is `PublishingPayloadFactoryForObject`:
+
+[source,java]
+----
+public interface PublishingPayloadFactoryForObject {
+
+ @Programmatic
+ public EventPayload payloadFor(
+ Object changedObject,
+ PublishingChangeKind publishingChangeKind); // <1>
+}
+----
+<1> an enum taking the values `CREATE`, `UPDATE`, `DELETE`
+
+Similarly, the `EventPayloadForObjectChanged` abstract class should be used as the base class for the object returned from `payLoadFor(...)`.
+
+For example, the following will eagerly include a `ToDoItem`'s `description` property whenever it is changed:
+
+[source,java]
+----
+@DomainObject(publishingPayloadFactory=ToDoItemPayloadFactory.class)
+public class ToDoItem {
+ ...
+}
+----
+
+where `ToDoItemPayloadFactory` is defined as:
+
+[source,java]
+----
+public class ToDoItemChangedPayloadFactory implements PublishingPayloadFactoryForObject {
+ public static class ToDoItemPayload
+ extends EventPayloadForObjectChanged<ToDoItem> {
+ public ToDoItemPayload(ToDoItem changed) { super(changed); }
+ public String getDescription() { return getChanged().getDescription(); }
+ }
+ @Override
+ public EventPayload payloadFor(Object changedObject, PublishingChangeKind kind) {
+ return new ToDoItemPayload((ToDoItem) changedObject);
+ }
+}
+----
+
+
+
+
+== Registering the Services
+
+Assuming that the `configuration-and-annotation` services installer is configured:
+
+[source,ini]
+----
+isis.services-installer=configuration-and-annotation
+----
+
+then adding the (non-ASF) http://github.com/isisaddons/isis-module-publishing[Isis addons' publishing] module to the classpath will automatically register the `PublishingService` implementation (and also the module's `RestfulObjectsSpecEventSerializer` implementation).
+
+
+
+
+== Related Services
+
+The `PublishingService` is intended for coarse-grained publish/subscribe for system-to-system interactions, from Isis to some other system. Here the only events published are those that action invocations (for actions annotated with xref:rg.adoc#_rg_annotations_manpage-Action_publishing[`@Action#publishing()`]) and of changed objects (for objects annotated with xref:rg.adoc#_rg_annotations_manpage-DomainObject_publishing[`@DomainObject#publishing()`].
+
+The xref:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`] meanwhile is intended for fine-grained publish/subscribe for object-to-object interactions within an 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.
+
+
+
+
+== Design Notes
+
+The following class diagram shows how the above components fit together:
+
+image::{_imagesdir}reference-services-spi/PublishingService/yuml.me-23db58a4.png[width="800px",link="{_imagesdir}reference-services-spi/PublishingService/yuml.me-23db58a4.png"]
+
+This yuml.me diagram was generated at http://yuml.me/edit/23db58a4[yuml.me].
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-RepresentationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-RepresentationService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-RepresentationService.adoc
new file mode 100644
index 0000000..109269f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-RepresentationService.adoc
@@ -0,0 +1,106 @@
+[[_rg_services-spi_manpage-RepresentationService]]
+= `RepresentationService`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `RepresentationService` is the main plug-in point for the xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer] to generate representations.
+
+The default implementation generates representations according to the link:http://restfulobjects.org[Restful Objects spec] v1.0. However, it also delegates to the xref:rg.adoc#_rg_services-spi_manpage-ContentNegotiationService[`ContentNegotiationService`] which provides a mechanism for altering representations according to the HTTP `Accept` header.
+
+The principal motivation is to allow more flexible representations to be generated for REST clients that (perhaps through their use of a certain Javascript library, say) expect, or at least works best with, a certain style of representation.
+
+In all there are three domain services that can influence the representations generated: this service, xref:rg.adoc#_rg_services-spi_manpage-ContentNegotiationService[`ContentNegotiationService`]and the xref:rg.adoc#_rg_services-spi_manpage-ContentMappingService[`ContentMappingService`]. The diagram below shows how these collaborate:
+
+image::{_imagesdir}reference-services-spi/RepresentationService/service-collaborations.png[width="700px",link="{_imagesdir}reference-services-spi/RepresentationService/service-collaborations.png"]
+
+The `RepresentationServiceForRestfulObjects` is the default implementation of this service; likewise `ContentNegotiationServiceXRoDomainType` is the default implementation of the `ContentNegotiationService`. If you inspect the source code you'll see that the default implementation of this service's primary responsibility is to generate the default Restful Objects representations. Therefore, if you what you want to do is to generate a _different _representation then in many cases replacing either this service _or_ the `ContentNegotiationService` will be equivalent (you'll notice that their SPIs are very similar).
+
+
+== SPI
+
+The SPI defined by this service is:
+
+[source,java]
+----
+public interface RepresentationService {
+ @Programmatic
+ Response objectRepresentation( // <1>
+ Context rendererContext,
+ ObjectAdapter objectAdapter);
+ @Programmatic
+ Response propertyDetails( // <2>
+ Context rendererContext,
+ ObjectAndProperty objectAndProperty,
+ MemberReprMode memberReprMode);
+ @Programmatic
+ Response collectionDetails( // <3>
+ Context rendererContext,
+ ObjectAndCollection objectAndCollection,
+ MemberReprMode memberReprMode);
+ @Programmatic
+ Response actionPrompt( // <4>
+ Context rendererContext,
+ ObjectAndAction objectAndAction);
+ @Programmatic
+ Response actionResult( // <5>
+ Context rendererContext,
+ ObjectAndActionInvocation objectAndActionInvocation,
+ ActionResultReprRenderer.SelfLink selfLink);
+ public static interface Context extends RendererContext {
+ ObjectAdapterLinkTo getAdapterLinkTo();
+ }
+}
+----
+<1> representation of a single object, as per section 14.4 of the RO spec, v1.0
+<2> representation of a single property of an object, as per section 16.4 of the RO spec v1.0
+<3> representation of a single collection of an object, as per section 17.5 of the RO spec v1.0
+<4> representation of a single action (prompt) of an object, as per section 18.2 of the RO spec v1.0
+<5> representation of the results of a single action invocation, as per section 19.5 of the RO spec v1.0
+
+These methods provide:
+
+* a `RendererContext` which provides access to request-specific context (eg HTTP headers), session-specific context (eg authentication) and global context (eg configuration settings)
+
+* an object representing the information to be rendered +
++
+eg `ObjectAdapter`, `ObjectAndProperty`, `ObjectAndCollection` etc
+
+* for members, whether the representation is in read/write mode +
++
+ie `MemberReprMode`
+
+
+
+[WARNING]
+====
+This is an "internal" SPI, meaning that it uses types that are not part of the Isis applib. We do not guarantee that link:http://semver.org[semantic versioning] will be honoured for these APIs.
+====
+
+
+
+== Implementation
+
+As discussed in the introduction, the framework provides a default implementation, `o.a.i.v.ro.rendering.service.RepresentationServiceForRestfulObjects`. This delegates to xref:rg.adoc#_rg_services-spi_manpage-ContentNegotiationService[`ContentNegotiationService`] to generate an alternative representation; but if none is provided then it falls back on generating the representations as defined in the link:http://restfulobjects.org[Restful Objects spec] v1.0.
+
+
+
+== Registering the Services
+
+Assuming that the `configuration-and-annotation` services installer is configured:
+
+[source,ini]
+----
+isis.services-installer=configuration-and-annotation
+----
+
+then Isis' default implementation of `RepresentationService` service is automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
+
+
+
+
+== Related Services
+
+The default implementation delegates to xref:rg.adoc#_rg_services-spi_manpage-ContentNegotiationService[`ContentNegotiationService`], whose default implementation may delegate in turn to xref:rg.adoc#_rg_services-spi_manpage-ContentMappingService[`ContentMappingService`] (if present).
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-TranslationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-TranslationService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-TranslationService.adoc
new file mode 100644
index 0000000..21fa92e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-TranslationService.adoc
@@ -0,0 +1,79 @@
+[[_rg_services-spi_manpage-TranslationService]]
+= `TranslationService`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `TranslationService` is the cornerstone of Isis' i18n support. Its role is to be able to provide translated versions of the various elements within the Isis metamodel (service and object classes, properties, collections, actions, action parameters) and also to translate business rule (disable/valid) messages, and exceptions. These translations provide for both singular and plural forms.
+
+
+[NOTE]
+====
+For the "big picture" and further details on Isis' i18n support, see xref:ug.adoc#_ug_more-advanced_i18n[here].
+====
+
+
+
+== SPI
+
+The SPI defined by this service is:
+
+[source,java]
+----
+public interface TranslationService {
+ @Programmatic
+ String translate(String context, String text); // <1>
+ @Programmatic
+ String translate(String context, // <2>
+ String singularText,
+ String pluralText, int num);
+
+ enum Mode { READ, WRITE;}
+ @Programmatic
+ Mode getMode(); // <3>
+}
+
+----
+<1> translate the text, in the locale of the "current user".
+<2> return a translation of either the singular or the plural text, dependent on the `num` parameter, in the locale of the "current user"
+<3> whether this implementation is operating in read or in write mode.
+
+If in read mode, then the translations are expected to be present.
+
+If in write mode, then the implementation is saving translation keys, and will always return the untranslated translation.
+
+
+
+
+== Implementation
+
+The Isis framework provides a default implementation (`TranslationServicePo`) that uses the GNU `.pot` and `.po` files for translations. It relies on the `LocaleProvider` service (to return the `Locale` of the current user) and also the `TranslationsResolver` service (to read existing translations).
+
+The framework also provides a supporting `TranslationServicePoMenu` provides menu items under the "Prototyping" secondary menu for controlling this service and downloading `.pot` files for translation.
+
+For more details on the implementation, see xref:ug.adoc#_ug_more-advanced_i18n[i18n support].
+
+
+
+
+== Registering the Services
+
+Assuming that the `configuration-and-annotation` services installer is configured:
+
+[source,ini]
+----
+isis.services-installer=configuration-and-annotation
+----
+
+then 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:ug.adoc#_ug_more-advanced_decoupling_vetoing-visibility[vetoing subscriber].
+
+
+
+
+
+== Related Services
+
+This service works in conjunction with xref:rg.adoc#_rg_services-spi_manpage-LocaleProvider[`LocaleProvider`] and xref:rg.adoc#_rg_services-spi_manpage-TranslationsResolver[`TranslationsResolver`] in order to provide i18n support.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-TranslationsResolver.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-TranslationsResolver.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-TranslationsResolver.adoc
new file mode 100644
index 0000000..039de22
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-TranslationsResolver.adoc
@@ -0,0 +1,67 @@
+[[_rg_services-spi_manpage-TranslationsResolver]]
+= `TranslationsResolver`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `TranslationsResolver` service is one of the services that work together to implement Isis' support for i18n, being used by Isis' default implementation of xref:rg.adoc#_rg_services-spi_manpage-TranslationService[`TranslationService`].
+
+The role of the service itself is locate and return translations.
+
+
+[NOTE]
+====
+For the "big picture" and further details on Isis' i18n support, see xref:ug.adoc#_ug_more-advanced_i18n[here].
+====
+
+
+
+== SPI
+
+The SPI defined by this service is:
+
+[source,java]
+----
+public interface TranslationsResolver {
+ @Programmatic
+ List<String> readLines(final String file);
+}
+----
+
+
+== Implementation
+
+Isis' xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] provides an implementation of this service (`TranslationsResolverWicket`) which leverages Apache Wicket APIs. This searches for translation files in the standard `WEB-INF/` directory.
+
+[NOTE]
+====
+Currently there is no equivalent implementation for the xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer].
+====
+
+
+
+
+
+== Registering the Service
+
+Assuming that the `configuration-and-annotation` services installer is configured:
+
+[source,ini]
+----
+isis.services-installer=configuration-and-annotation
+----
+
+and that the xref:ug.adoc#_ug_wicket-viewer[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.
+
+
+
+
+
+== Related Services
+
+
+This service works in conjunction with xref:rg.adoc#_rg_services-spi_manpage-LocaleProvider[`LocaleProvider`] and xref:rg.adoc#_rg_services-spi_manpage-TranslationService[`TranslationService`] in order to provide i18n support.
+
+
[21/45] isis git commit: ISIS-1133: breaking out reference guide and
devenv guide;
moving appendices' release notes and migration notes to other docs;
improving the documentation page.
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_philosophy_domain-driven-design.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_philosophy_domain-driven-design.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_philosophy_domain-driven-design.adoc
deleted file mode 100644
index 764df57..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_philosophy_domain-driven-design.adoc
+++ /dev/null
@@ -1,80 +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/
-
-This section describes some of the core ideas and architectural patterns upon which Apache Isis builds.
-
-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.
-
-== 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 again be thinking of design documents and design diagrams. 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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_philosophy_hexagonal-architecture.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_philosophy_hexagonal-architecture.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_philosophy_hexagonal-architecture.adoc
deleted file mode 100644
index 7e33166..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_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*. Isis' viewers act as user-side adapters and use the 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 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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_philosophy_how-eases-ddd.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_philosophy_how-eases-ddd.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_philosophy_how-eases-ddd.adoc
deleted file mode 100644
index 1e6f601..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_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 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.
-
-
-
-== Abstract models are difficult to represent
-
-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_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.
-
-
-
-
-== Layered architectures are easily compromised
-
-_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. 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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_philosophy_naked-objects-pattern.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_philosophy_naked-objects-pattern.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_philosophy_naked-objects-pattern.adoc
deleted file mode 100644
index e870754..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_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 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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping.adoc
deleted file mode 100644
index eb49565..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_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_core-concepts_principles_apache-isis-vs_metawidget[here].
-====
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_principles.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_principles.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_principles.adoc
deleted file mode 100644
index da52685..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_principles_apache-isis-vs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_principles_apache-isis-vs.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_principles_apache-isis-vs.adoc
deleted file mode 100644
index cb4bcda..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_principles_apache-isis-vs.adoc
+++ /dev/null
@@ -1,36 +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]
-
-
-
-== vs CQRS
-
-IMPORTANT: TODO
-
-== vs Event Sourcing
-
-IMPORTANT: TODO
-
-
-== vs Angular
-
-IMPORTANT: TODO
-
-
-
-include::_ug_core-concepts_principles_apache-isis-vs_metawidget.adoc[leveloffset=+1]
-
-
-
-== vs OpenXava
-
-IMPORTANT: TODO
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_principles_apache-isis-vs_metawidget.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_principles_apache-isis-vs_metawidget.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_principles_apache-isis-vs_metawidget.adoc
deleted file mode 100644
index 11e851f..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_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_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:_ug_restfulobjects-viewer[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 Isis' own metamodel as an implementation of the MetaWidget API. This would allow MetaWidget to be able to render an Isis domain application.
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_principles_apache-isis-vs_mvc-server-side-frameworks.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_principles_apache-isis-vs_mvc-server-side-frameworks.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_principles_apache-isis-vs_mvc-server-side-frameworks.adoc
deleted file mode 100644
index e527e6d..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_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:_ug_extending_wicket-viewer[extending Isis' Wicket viewer] or by writing a bespoke UI leveraging the REST (hypermedia) API automatically exposed by xref:_ug_restfulobjects-viewer[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 Isis' REST API.
-
-Although these frameworks all provide their own ecosystems of extensions, 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. Isis' support is similar. Where Isis differs though is that it enables end-to-end testing without the need for slow and fragile Selenium tests. Instead, Isis provides a "xref:_ug_testing_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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_principles_isis-itself.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_principles_isis-itself.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_principles_isis-itself.adoc
deleted file mode 100644
index 8997d46..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_principles_isis-itself.adoc
+++ /dev/null
@@ -1,47 +0,0 @@
-[[_ug_core-concepts_principles_isis-itself]]
-= 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
-
-IMPORTANT: TODO
-
-
-== Focuses on its USP
-
-IMPORTANT: TODO
-
-
-add-ons
-
-* 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 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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_principles_your-apps.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_principles_your-apps.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_principles_your-apps.adoc
deleted file mode 100644
index 7e73413..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_principles_your-apps.adoc
+++ /dev/null
@@ -1,37 +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/
-
-
-IMPORTANT: TODO
-
-== Decoupled
-
-IMPORTANT: TODO
-
-Long-term Cost of ownership
-
-Using:
-
-* 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
-
-IMPORTANT: TODO - behaviourally Complete vs Contributions
-
-
-== Testable
-
-IMPORTANT: WIP
-
-While Apache Isis can be used (very effectively) for simple CRUD-style applications, it is also intended to be used for complex business domains. Ensuring that the business logic in such applications is correct means that the framework must (and does) provide robust testing support, both for developer-level unit testing and business-level (end-to-end) integration testing.
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment.adoc
deleted file mode 100644
index 97e9e8b..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment.adoc
+++ /dev/null
@@ -1,19 +0,0 @@
-[[_ug_deployment]]
-= Deployment
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-This chapter provides guidance on some common deployment scenarios.
-
-include::_ug_deployment_cmd-line.adoc[leveloffset=+1]
-include::_ug_deployment_tomcat.adoc[leveloffset=+1]
-include::_ug_deployment_externalized-configuration.adoc[leveloffset=+1]
-include::_ug_deployment_gae.adoc[leveloffset=+1]
-include::_ug_deployment_neo4j.adoc[leveloffset=+1]
-include::_ug_deployment_jvm-flags.adoc[leveloffset=+1]
-
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment_cmd-line.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment_cmd-line.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment_cmd-line.adoc
deleted file mode 100644
index c55969f..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment_cmd-line.adoc
+++ /dev/null
@@ -1,30 +0,0 @@
-[[_ug_deployment_cmd-line]]
-= Command Line
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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
-
-
-## `WebServer` class
-
-`org.apache.isis.WebServer`
-
-For example:
-* `--fixture`
-* `--services`
-
-etc...
-
-
-
-## `Dummy` class
-
-`org.apache.isis.Dummy`
-
-
-etc...
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment_externalized-configuration.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment_externalized-configuration.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment_externalized-configuration.adoc
deleted file mode 100644
index f710b30..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment_externalized-configuration.adoc
+++ /dev/null
@@ -1,9 +0,0 @@
-[[_ug_deployment_externalized-configuration]]
-= Externalized Configuration
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment_gae.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment_gae.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment_gae.adoc
deleted file mode 100644
index d06d75c..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment_gae.adoc
+++ /dev/null
@@ -1,48 +0,0 @@
-[[_ug_deployment_gae]]
-= Deploying to Google App Engine
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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
-
-The Google App Engine (GAE) provides a JDO API, meaning that you can deploy Isis onto GAE using the JDO objectstore.
-
-However, GAE is not an RDBMS, and so there are some limitations that it imposes. This page gathers together various hints, tips and workarounds.
-
-
-== Primary Keys and Owned/Unowned Relationships
-
-All entities must have a `@PrimaryKey`. Within GAE, the type of this key matters.
-
-For an entity to be an aggregate root, (ie a root of an GAE entity group), its key must be a `Long`, eg:
-
-Any collection that holds this entity type (eg `ToDoItem#dependencies` holding a collection of `ToDoItem`s) should then be annotated with `@Unowned` (a GAE annotation).
-
-If on the other hand you want the object to be owned (through a 1:m relationship somewhere) by some other root, then use a String:
-
-Note: if you store a relationship with a String key it means that the parent object _owns_ the child, any attempt to change the relationship raise and exception.
-
-
-
-== Custom Types
-
-Currently Isis' `Blob` and `Clob` types and the JODA types (`LocalDate` et al) are _not_ supported in GAE.
-
-Instead, GAE defines a link:https://cloud.google.com/appengine/docs/java/datastore/entities#Properties_and_Value_Types[fixed set of value types], including `BlobKey`. Members of the Isis community have this working, though I haven't seen the code.
-
-The above notwithstanding, Andy Jefferson at DataNucleus tells us:
-
-pass:[<div class="extended-quote-first"><p>]GAE JDO/JPA does support _some_ type conversion, because looking at http://code.google.com/p/datanucleus-appengine/source/browse/trunk/src/com/google/appengine/datanucleus/StoreFieldManager.java#349[StoreFieldManager.java] for any field that is Object-based and not a relation nor Serialized it will call http://code.google.com/p/datanucleus-appengine/source/browse/trunk/src/com/google/appengine/datanucleus/TypeConversionUtils.java#736[TypeConverstionUtils.java] and that looks for a `TypeConverter` (specify `@Extension` with key of "type-converter-name" against a field and value as the `TypeConverter` class) and it should convert it. Similarly when getting the value from the datastore.
-pass:[</p></div>]
-
-On further investigation, it seems that the GAE implementation performs a type check on a `SUPPORTED_TYPES` Java set, in `com.google.appengine.api.datastore.DataTypeUtils`:
-
-[source,java]
-----
-if (!supportedTypes.contains(value.getClass())) {
- throw new IllegalArgumentException(prefix + value.getClass().getName() + " is not a supported property type.");
-}
-----
-
-We still need to try out Andy's recipe, above.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment_jvm-flags.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment_jvm-flags.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment_jvm-flags.adoc
deleted file mode 100644
index d3edc30..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment_jvm-flags.adoc
+++ /dev/null
@@ -1,9 +0,0 @@
-[[_ug_deployment_jvm-flags]]
-= JVM Flags
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment_neo4j.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment_neo4j.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment_neo4j.adoc
deleted file mode 100644
index 4ffd2aa..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment_neo4j.adoc
+++ /dev/null
@@ -1,59 +0,0 @@
-[[_ug_deployment_neo4j]]
-= Neo4J
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 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_getting-started_simpleapp-archetype[SimpleApp archetype] has been updated so that they can be optionally run under Neo4J.
-
-[TIP]
-====
-In addition, the http://github.com/isisaddons/isis-app-neoapp[Isis addons' neoapp] (non-ASF) is configured to run with an embedded Neo4J server running alongside the Isis webapp.
-====
-
-The steps below describe the configuration steps required to update an existing app.
-
-== ConnectionURL
-
-In `persistor.properties`, update the JDO `ConnectionURL` property, eg:
-
-[source,ini]
-----
-isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionURL=neo4j:neo4j_DB
-----
-
-The other connection properties (`ConnectionDriverName`, `ConnectionUserName` and `ConnectionPassword`) should be commented out.
-
-== Update pom.xml
-
-Add the following dependency to the `webapp` project's `pom.xml`:
-
-[source,xml]
-----
-<dependencies>
- ...
- <dependency>
- <groupId>org.datanucleus</groupId>
- <artifactId>datanucleus-neo4j</artifactId>
- <version>3.2.3</version> <!--1-->
- </dependency>
- ...
-</dependencies>
-----
-<1> for 1.8.0, use the value shown. for 1.9.0-SNAPSHOT, use 4.0.5.
-
-In the xref:_ug_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_getting-started_simpleapp-archetype[SimpleApp archetype] (v1.8.0)
-
-* build the app:
-
-* run the app:
-
-If you visit the about page you should see the neo4j JAR files are linked in, and a `neo4j_DB` subdirectory within the `webapp` directory.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment_tomcat.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment_tomcat.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment_tomcat.adoc
deleted file mode 100644
index d29ca1a..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment_tomcat.adoc
+++ /dev/null
@@ -1,35 +0,0 @@
-[[_ug_deployment_tomcat]]
-= Deploying to Tomcat
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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
-
-
-== Externalized Configuration
-
-IMPORTANT: TODO
-
-
-== JVM Args
-
-IMPORTANT: TODO
-
-
-for the `WrapperFactory` (uses link:http://www.javassist.org[Javassist])
-
-using:
-
-[source,ini]
-----
--XX:+CMSClassUnloadingEnabled -XX:+UseConcMarkSweepGC
-----
-
-You can hint the JVM to unload dynamically created classes which ClassLoaders are still around.
-
-
-== Using a JNDI Datasource
-
-See the guidance in the xref:_ug_runtime_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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending.adoc
deleted file mode 100644
index 47c6d81..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending.adoc
+++ /dev/null
@@ -1,14 +0,0 @@
-[[_ug_extending]]
-= Extending
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-This chapter explains the main APIs for extending Apache Isis: the programming model conventions, the Wicket viewer, and the Restful Objects viewer.
-
-include::_ug_extending_programming-model.adoc[leveloffset=+1]
-
-include::_ug_extending_wicket-viewer.adoc[leveloffset=+1]
-
-include::_ug_extending_restfulobjects-viewer.adoc[leveloffset=+1]
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_programming-model.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_programming-model.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_programming-model.adoc
deleted file mode 100644
index aad09c6..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_programming-model.adoc
+++ /dev/null
@@ -1,13 +0,0 @@
-[[_ug_extending_programming-model]]
-= Programming Model
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-This section describes three mechanisms you can use to extend or alter the programming conventions that Isis understands to build up its metamodel.
-
-include::_ug_extending_programming-model_custom-validator.adoc[leveloffset=+1]
-include::_ug_extending_programming-model_finetuning.adoc[leveloffset=+1]
-include::_ug_extending_programming-model_layout-metadata-reader.adoc[leveloffset=+1]
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_programming-model_custom-validator.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_programming-model_custom-validator.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_programming-model_custom-validator.adoc
deleted file mode 100644
index 82eb1ba..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_programming-model_custom-validator.adoc
+++ /dev/null
@@ -1,107 +0,0 @@
-[[_ug_extending_programming-model_custom-validator]]
-= Custom validator
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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' programming model includes a validator component that detects and prevents (by failing fast) a number of situations where the domain model is logically inconsistent with itself.
-
-For example, the validator will detect any orphaned supporting methods (eg `hideXxx()`) if the corresponding property or action has been renamed or deleted but the supporting method was not also updated. Another example is that a class cannot have a title specified both using `title()` method and also using `@Title` annotation.
-
-[NOTE]
-====
-The support for xref:_ug_reference-annotations_aaa_deprecated[disallowing deprecated annotations] is also implemented using the metamodel validator.
-====
-
-You can also impose your own application-specific rules by installing your own metamodel validator. To give just one example, you could impose naming standards such as ensuring that a domain-specific abbreviation such as "ISBN" is always consistently capitalized wherever it appears in a class member.
-
-[TIP]
-====
-Isis' xref:_ug_isis-maven-plugin[Maven plugin] will also validate the domain object model during build time.
-====
-
-
-== API and Implementation
-
-There are several ways to go about implementing a validator.
-
-=== `MetaModelValidator`
-
-Any custom validator must implement Isis' internal `MetaModelValidator` interface, so the simplest option is just to implement `MetaModelValidator` directly:
-
-
-[source,java]
-----
-public interface MetaModelValidator
- implements SpecificationLoaderSpiAware { // <1>
- public void validate(
- ValidationFailures validationFailures); // <2>
-}
-----
-<1> the `SpecificationLoader` is the internal API providing access to the Isis metamodel.
-<2> add any metamodel violations to the `ValidationFailures` parameter (the link:http://c2.com/cgi/wiki?CollectingParameter[collecting parameter] pattern)
-
-
-=== `Visitor`
-
-More often than not, you'll want to visit every element in the metamodel, and so for this you can instead subclass from `MetaModelValidatorVisiting.Visitor`:
-
-[source,java]
-----
-public final class MetaModelValidatorVisiting ... {
- public static interface Visitor {
- public boolean visit( // <1>
- ObjectSpecification objectSpec, // <2>
- ValidationFailures validationFailures); // <3>
- }
- ...
-}
-----
-<1> return `true` continue visiting specs.
-<2> `ObjectSpecification` is the internal API representing a class
-<3> add any metamodel violations to the `ValidationFailures` parameter
-
-
-You can then create your custom validator by subclassing `MetaModelValidatorComposite` and adding the visiting validator:
-
-[source,java]
-----
-public class MyMetaModelValidator extends MetaModelValidatorComposite {
- public MyMetaModelValidator() {
- add(new MetaModelValidatorVisiting(new MyVisitor()));
- }
-}
-----
-
-If you have more than one rule then each can live in its own visitor.
-
-=== `SummarizingVisitor`
-
-As a slight refinement, you can also subclass from `MetaModelValidatorVisiting.SummarizingVisitor`:
-
-[source,java]
-----
-public final class MetaModelValidatorVisiting ... {
- public static interface SummarizingVisitor extends Visitor {
- public void summarize(ValidationFailures validationFailures);
- }
- ...
-}
-----
-
-A `SummarizingVisitor` will be called once after every element in the metamodel has been visited. This is great for performing checks on the metamodel as a whole. For example, Isis uses this to check that there is at least one `@Persistable` domain entity defined.
-
-
-
-
-== Configuration
-
-Once you have implemented your validator, you must register it with the framework by defining the appropriate configuration property:
-
-[source,ini]
-----
-isis.reflector.validator=com.mycompany.myapp.MyMetaModelValidator
-----
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_programming-model_finetuning.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_programming-model_finetuning.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_programming-model_finetuning.adoc
deleted file mode 100644
index 45d4c6b..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_programming-model_finetuning.adoc
+++ /dev/null
@@ -1,80 +0,0 @@
-[[_ug_extending_programming-model_finetuning]]
-= Finetuning
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 core metamodel defines APIs and implementations for building the Isis metamodel: a description of the set of entities, domain services and values that make up the domain model.
-
-
-The description of each domain class consists of a number of elements:
-
-https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/core/metamodel/spec/ObjectSpecification.java[ObjectSpecification]::
-Analogous to `java.lang.Class`; holds information about the class itself and holds collections of each of the three types of class' members (below);
-
-https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/core/metamodel/spec/feature/OneToOneAssociation.java[OneToOneAssociation]::
-Represents a class member that is a single-valued property of the class. The property's type is either a reference to another entity, or is a value type.
-
-https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/core/metamodel/spec/feature/OneToManyAssociation.java[OneToManyAssociation]::
-Represents a class member that is a collection of references to other entities. Note that Isis does not currently support collections of values.
-
-https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/core/metamodel/spec/feature/ObjectAction.java[ObjectAction]::
-Represents a class member that is an operation that can be performed on the action. Returns either a single value, a collection of entities, or is `void`.
-
-
-The metamodel is built up through the https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/core/metamodel/progmodel/ProgrammingModel.java[ProgrammingModel], which defines an API for registering a set of https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/core/metamodel/facets/FacetFactory.java[FacetFactory]s. Two special `FacetFactory` implementations - https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/core/metamodel/facets/properties/accessor/PropertyAccessorFacetViaAccessorFactory.java[PropertyAccessorFacetFactory] and https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/core/metamodel/facets/collections/accessor/CollectionAccessorFacetViaAccessorFactory.java[CollectionAccessorFacetFactory] - are used to identify the class members.
-Pretty much all the other ``FacetFactory``s are responsible for installing https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/core/metamodel/facetapi/Facet.java[Facet]s onto the metamodel elements.
-
-There are many many such ``Facet``s, and are used to do such things get values from properties or collections, modify properties or collections, invoke action, hide or disable class members, provide UI hints for class members, and so on. In short, the ``FacetFactory``s registered defines the Isis programming conventions.
-
-
-
-== Modifying the Prog. Model
-
-The default implementation of `ProgrammingModel` is https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/progmodels/dflt/ProgrammingModelFacetsJava5.java[ProgrammingModelFacetsJava5], which registers a large number of ``FacetFactory``s.
-
-By editing `isis.properties` you can modify the programming conventions either by (a) using the default programming model, but tweaking it to include new `FacetFactory`s or exclude existing, or (b) by specifying a completely different programming model implementation.
-
-Let's see how this is done.
-
-=== Including or excluding facets
-
-Suppose that you wanted to completely remove support for the (already deprecated) `@ActionOrder` annotation. This would be done using:
-
-[source,ini]
-----
-isis.reflector.facets.exclude=org.apache.isis.core.metamodel.facets.object.actionorder.annotation.ActionOrderFacetAnnotationFactory
-----
-
-Or, suppose you wanted to use the example https://github.com/apache/isis/blob/master/mothballed/misc/metamodel/namefile/src/main/java/org/apache/isis/example/metamodel/namefile/facets/NameFileFacetFactory.java["namefile"] `FacetFactory` as part of your programming conventions, use:
-
-[source,ini]
-----
-isis.reflector.facets.include=org.apache.isis.example.metamodel.namefile.facets.NameFileFacetFactory
-----
-
-To include/exclude more than one `FacetFactory`, specify as a comma-separated list. And if you want to dig into this in more detail, the code that implements this logic is https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/progmodels/dflt/JavaReflectorInstallerNoDecorators.java[JavaReflectorInstallerNoDecorators].
-
-[TIP]
-====
-This http://isis.markmail.org/thread/472c3mrvcgnripst[thread] from the users mailing list (in Apr 2014) shows a typical customization (to enable per-instance security) (though note that xref:_ug_more-advanced_multi-tenancy[Multi-Tenancy] is now a better solution to that particular use-case.
-====
-
-
-
-
-== Replacing the Prog. Model
-
-If you want to make many changes to the programming model, then (rather than include/exclude lots of facet factories) you can specify a completely new programming model. For this you'll first need an implementation of `ProgrammingModel`.
-
-One option is to subclass from `ProgammingModelFacetsJava5`; in your subclass you could remove any ``FacetFactory``s that you wanted to exclude, as well as registering your own implementations.
-
-To tell Isis to use your new programming model, use:
-
-[source,ini]
-----
-isis.reflector.facets=com.mycompany.myapp.isis.IsisProgrammingModel
-----
-
-Again, the code that implements this logic is https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/progmodels/dflt/JavaReflectorInstallerNoDecorators.java[JavaReflectorInstallerNoDecorators].
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_programming-model_layout-metadata-reader.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_programming-model_layout-metadata-reader.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_programming-model_layout-metadata-reader.adoc
deleted file mode 100644
index 7e2992a..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_programming-model_layout-metadata-reader.adoc
+++ /dev/null
@@ -1,44 +0,0 @@
-[[_ug_extending_programming-model_layout-metadata-reader]]
-= Layout Metadata Reader
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 metadata for domain objects is obtained both xref:_ug_reference-object-layout_static[statically] and xref:_ug_reference-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`).
-
-You can also implement your own metadata readers and plug them into Isis. These could read from a different file format, or they could, even, read data dynamically from a URL or database. (Indeed, one could imagine an implementation whereby users could share layouts, all stored in some central repository).
-
-
-
-== API and Implementation
-
-Any reader must implement Isis' internal `LayoutMetadataReader` interface:
-
-[source,java]
-----
-public interface LayoutMetadataReader {
- public Properties asProperties(Class<?> domainClass) throws ReaderException;
-}
-----
-
-The implementation "simply" returns a set of properties where the property key is a unique identifier to both the class member and also the facet of the class member to which the metadata relates.
-
-See the implementation of the built-in `LayoutMetadataReaderFromJson` for more detail.
-
-
-
-== Configuration
-
-Once you have implemented your validator, you must register it with the framework by defining the appropriate configuration property:
-
-[source,ini]
-----
-isis.reflector.layoutMetadataReaders=\
- com.mycompany.myapp.MyMetaModelValidator,\
- org.apache.isis.core.metamodel.layoutmetadata.json.LayoutMetadataReaderFromJson # <1>
-----
-<1> the property replaces any existing metadata readers; if you want to preserve the ability to read from `Xxx.layout.json` then also register Isis' built-in implementation.
-
[07/45] isis git commit: ISIS-1133: breaking out reference guide and
devenv guide;
moving appendices' release notes and migration notes to other docs;
improving the documentation page.
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-RepresentationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-RepresentationService.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-RepresentationService.adoc
deleted file mode 100644
index 28f4852..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-RepresentationService.adoc
+++ /dev/null
@@ -1,106 +0,0 @@
-[[_ug_reference-services-spi_manpage-RepresentationService]]
-= `RepresentationService`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `RepresentationService` is the main plug-in point for the xref:_ug_restfulobjects-viewer[RestfulObjects viewer] to generate representations.
-
-The default implementation generates representations according to the link:http://restfulobjects.org[Restful Objects spec] v1.0. However, it also delegates to the xref:_ug_reference-services-spi_manpage-ContentNegotiationService[`ContentNegotiationService`] which provides a mechanism for altering representations according to the HTTP `Accept` header.
-
-The principal motivation is to allow more flexible representations to be generated for REST clients that (perhaps through their use of a certain Javascript library, say) expect, or at least works best with, a certain style of representation.
-
-In all there are three domain services that can influence the representations generated: this service, xref:_ug_reference-services-spi_manpage-ContentNegotiationService[`ContentNegotiationService`]and the xref:_ug_reference-services-spi_manpage-ContentMappingService[`ContentMappingService`]. The diagram below shows how these collaborate:
-
-image::{_imagesdir}reference-services-spi/RepresentationService/service-collaborations.png[width="700px",link="{_imagesdir}reference-services-spi/RepresentationService/service-collaborations.png"]
-
-The `RepresentationServiceForRestfulObjects` is the default implementation of this service; likewise `ContentNegotiationServiceXRoDomainType` is the default implementation of the `ContentNegotiationService`. If you inspect the source code you'll see that the default implementation of this service's primary responsibility is to generate the default Restful Objects representations. Therefore, if you what you want to do is to generate a _different _representation then in many cases replacing either this service _or_ the `ContentNegotiationService` will be equivalent (you'll notice that their SPIs are very similar).
-
-
-== SPI
-
-The SPI defined by this service is:
-
-[source,java]
-----
-public interface RepresentationService {
- @Programmatic
- Response objectRepresentation( // <1>
- Context rendererContext,
- ObjectAdapter objectAdapter);
- @Programmatic
- Response propertyDetails( // <2>
- Context rendererContext,
- ObjectAndProperty objectAndProperty,
- MemberReprMode memberReprMode);
- @Programmatic
- Response collectionDetails( // <3>
- Context rendererContext,
- ObjectAndCollection objectAndCollection,
- MemberReprMode memberReprMode);
- @Programmatic
- Response actionPrompt( // <4>
- Context rendererContext,
- ObjectAndAction objectAndAction);
- @Programmatic
- Response actionResult( // <5>
- Context rendererContext,
- ObjectAndActionInvocation objectAndActionInvocation,
- ActionResultReprRenderer.SelfLink selfLink);
- public static interface Context extends RendererContext {
- ObjectAdapterLinkTo getAdapterLinkTo();
- }
-}
-----
-<1> representation of a single object, as per section 14.4 of the RO spec, v1.0
-<2> representation of a single property of an object, as per section 16.4 of the RO spec v1.0
-<3> representation of a single collection of an object, as per section 17.5 of the RO spec v1.0
-<4> representation of a single action (prompt) of an object, as per section 18.2 of the RO spec v1.0
-<5> representation of the results of a single action invocation, as per section 19.5 of the RO spec v1.0
-
-These methods provide:
-
-* a `RendererContext` which provides access to request-specific context (eg HTTP headers), session-specific context (eg authentication) and global context (eg configuration settings)
-
-* an object representing the information to be rendered +
-+
-eg `ObjectAdapter`, `ObjectAndProperty`, `ObjectAndCollection` etc
-
-* for members, whether the representation is in read/write mode +
-+
-ie `MemberReprMode`
-
-
-
-[WARNING]
-====
-This is an "internal" SPI, meaning that it uses types that are not part of the Isis applib. We do not guarantee that link:http://semver.org[semantic versioning] will be honoured for these APIs.
-====
-
-
-
-== Implementation
-
-As discussed in the introduction, the framework provides a default implementation, `o.a.i.v.ro.rendering.service.RepresentationServiceForRestfulObjects`. This delegates to xref:_ug_reference-services-spi_manpage-ContentNegotiationService[`ContentNegotiationService`] to generate an alternative representation; but if none is provided then it falls back on generating the representations as defined in the link:http://restfulobjects.org[Restful Objects spec] v1.0.
-
-
-
-== Registering the Services
-
-Assuming that the `configuration-and-annotation` services installer is configured:
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then Isis' default implementation of `RepresentationService` service is automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
-
-
-
-
-== Related Services
-
-The default implementation delegates to xref:_ug_reference-services-spi_manpage-ContentNegotiationService[`ContentNegotiationService`], whose default implementation may delegate in turn to xref:_ug_reference-services-spi_manpage-ContentMappingService[`ContentMappingService`] (if present).
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-TranslationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-TranslationService.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-TranslationService.adoc
deleted file mode 100644
index 8218801..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-TranslationService.adoc
+++ /dev/null
@@ -1,79 +0,0 @@
-[[_ug_reference-services-spi_manpage-TranslationService]]
-= `TranslationService`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `TranslationService` is the cornerstone of Isis' i18n support. Its role is to be able to provide translated versions of the various elements within the Isis metamodel (service and object classes, properties, collections, actions, action parameters) and also to translate business rule (disable/valid) messages, and exceptions. These translations provide for both singular and plural forms.
-
-
-[NOTE]
-====
-For the "big picture" and further details on Isis' i18n support, see xref:_ug_more-advanced_i18n[here].
-====
-
-
-
-== SPI
-
-The SPI defined by this service is:
-
-[source,java]
-----
-public interface TranslationService {
- @Programmatic
- String translate(String context, String text); // <1>
- @Programmatic
- String translate(String context, // <2>
- String singularText,
- String pluralText, int num);
-
- enum Mode { READ, WRITE;}
- @Programmatic
- Mode getMode(); // <3>
-}
-
-----
-<1> translate the text, in the locale of the "current user".
-<2> return a translation of either the singular or the plural text, dependent on the `num` parameter, in the locale of the "current user"
-<3> whether this implementation is operating in read or in write mode.
-
-If in read mode, then the translations are expected to be present.
-
-If in write mode, then the implementation is saving translation keys, and will always return the untranslated translation.
-
-
-
-
-== Implementation
-
-The Isis framework provides a default implementation (`TranslationServicePo`) that uses the GNU `.pot` and `.po` files for translations. It relies on the `LocaleProvider` service (to return the `Locale` of the current user) and also the `TranslationsResolver` service (to read existing translations).
-
-The framework also provides a supporting `TranslationServicePoMenu` provides menu items under the "Prototyping" secondary menu for controlling this service and downloading `.pot` files for translation.
-
-For more details on the implementation, see xref:_ug_more-advanced_i18n[i18n support].
-
-
-
-
-== Registering the Services
-
-Assuming that the `configuration-and-annotation` services installer is configured:
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then 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:_ug_more-advanced_decoupling_vetoing-visibility[vetoing subscriber].
-
-
-
-
-
-== Related Services
-
-This service works in conjunction with xref:_ug_reference-services-spi_manpage-LocaleProvider[`LocaleProvider`] and xref:_ug_reference-services-spi_manpage-TranslationsResolver[`TranslationsResolver`] in order to provide i18n support.
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-TranslationsResolver.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-TranslationsResolver.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-TranslationsResolver.adoc
deleted file mode 100644
index e93f1f6..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-TranslationsResolver.adoc
+++ /dev/null
@@ -1,67 +0,0 @@
-[[_ug_reference-services-spi_manpage-TranslationsResolver]]
-= `TranslationsResolver`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `TranslationsResolver` service is one of the services that work together to implement Isis' support for i18n, being used by Isis' default implementation of xref:_ug_reference-services-spi_manpage-TranslationService[`TranslationService`].
-
-The role of the service itself is locate and return translations.
-
-
-[NOTE]
-====
-For the "big picture" and further details on Isis' i18n support, see xref:_ug_more-advanced_i18n[here].
-====
-
-
-
-== SPI
-
-The SPI defined by this service is:
-
-[source,java]
-----
-public interface TranslationsResolver {
- @Programmatic
- List<String> readLines(final String file);
-}
-----
-
-
-== Implementation
-
-Isis' xref:_ug_wicket-viewer[Wicket viewer] provides an implementation of this service (`TranslationsResolverWicket`) which leverages Apache Wicket APIs. This searches for translation files in the standard `WEB-INF/` directory.
-
-[NOTE]
-====
-Currently there is no equivalent implementation for the xref:_ug_restfulobjects-viewer[RestfulObjects viewer].
-====
-
-
-
-
-
-== Registering the Service
-
-Assuming that the `configuration-and-annotation` services installer is configured:
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-and that the xref:_ug_wicket-viewer[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.
-
-
-
-
-
-== Related Services
-
-
-This service works in conjunction with xref:_ug_reference-services-spi_manpage-LocaleProvider[`LocaleProvider`] and xref:_ug_reference-services-spi_manpage-TranslationService[`TranslationService`] in order to provide i18n support.
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-UserProfileService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-UserProfileService.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-UserProfileService.adoc
deleted file mode 100644
index a7134e6..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-UserProfileService.adoc
+++ /dev/null
@@ -1,44 +0,0 @@
-[[_ug_reference-services-spi_manpage-UserProfileService]]
-= `UserProfileService`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `UserProfileService` provides the ability for the domain application to return supplementary metadata about the current user. This information is used (by the xref:_ug_wicket-viewer[Wicket viewer]) to customize the appearance of the tertiary "Me" menu bar (top right). For example, rather than display the username, instead the user's first and last name could be displayed.
-
-Another use case is to allow the user to switch context in some fashion or other. This might be to emulate a sort of "sudo"-like function, or perhaps to focus on some particular set of data.
-
-
-
-== SPI
-
-The SPI defined by the service is:
-
-[source,java]
-----
-public interface UserProfileService {
- @Programmatic
- String userProfileName(); // <1>
-}
-----
-<1> is used (in the Wicket viewer) as the menu name of the tertiary "Me" menu bar.
-
-If the method returns `null` or throws an exception then the framework will default to using the current user name.
-
-In the future this API may be expanded; one obvious possibility is to return a profile photo or avatar URL.
-
-
-
-== Implementation
-
-The (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] has a simple implementation of this service:
-
-image::{_imagesdir}reference-services-spi/UserProfileService/todoapp.png[width="800px",link="{_imagesdir}reference-services-spi/UserProfileService/todoapp.png"]
-
-
-[NOTE]
-====
-Currently this feature is not integrated with Isis' authentication mechanisms; the information provided is purely metadata provided for presentation purposes only.
-====
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-UserRegistrationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-UserRegistrationService.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-UserRegistrationService.adoc
deleted file mode 100644
index a2d647a..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-UserRegistrationService.adoc
+++ /dev/null
@@ -1,81 +0,0 @@
-[[_ug_reference-services-spi_manpage-UserRegistrationService]]
-= `UserRegistrationService`
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 `UserRegistrationService` provides the ability for users to sign-up to access an application by providing a valid email address, and also provides the capability for users to reset their password if forgotten.
-
-For user sign-up, the xref:_ug_wicket-viewer[Wicket viewer] will check whether an implementation of this service (and also the xref:_ug_reference-services-spi_manpage-EmailNotificationService[`EmailNotificationService`]) is available, and if so will render a sign-up page where the user enters their email address. A verification email is sent (using the aforementioned `EmailNotificationService`) which includes a link back to the running application; this allows the user then to complete their registration process (choose user name, password and so on). When the user has provided the additional details, the Wicket viewer calls _this_ service in order to create an account for them, and then logs the user on.
-
-For the password reset feature, the Wicket viewer will render a password reset page, and use the `EmailNotificationService` to send a "password forgotten" email. This service provides the ability to reset a password based on the user's email address.
-
-It is of course possible for domain objects to use this service; it will be injected into domain object or other domain services in the usual way. That said, we expect that such use cases will be comparatively rare; the primary use case is for the Wicket viewer's sign-up page.
-
-[NOTE]
-====
-For further details on the user registration feature (as supported by the Wicket viewer), see xref:_ug_wicket-viewer_features_user-registration[here].
-====
-
-
-
-== SPI
-
-The SPI defined by the service is:
-
-[source,java]
-----
-public interface UserRegistrationService {
- @Programmatic
- boolean usernameExists(String username); // <1>
- @Programmatic
- boolean emailExists(String emailAddress); // <2>
- @Programmatic
- void registerUser(String username, String password, String emailAddress); // <3>
- @Programmatic
- boolean updatePasswordByEmail(String emailAddress, String password); // <4>
-}
-----
-<1> checks if there is already a user with the specified username
-<2> checks if there is already a user with the specified email address
-<3> creates the user, with specified password and email address. The username and email address must both be unique (not being used by an existing user)
-<4> allows the user to reset their password
-
-
-
-
-== Implementation
-
-The core Isis framework itself defines only an API; there is no default implementation. Rather, the implementation will depend on the security mechanism being used.
-
-That said, if you have configured your app to use the http://github.com/isisaddons/isis-module-security[Isis addons security module], then note that the security module does provide an abstract implementation (`SecurityModuleAppUserRegistrationServiceAbstract`) of the `UserRegistrationService`. You will need to extend that service and provide implementation for the two abstract methods: `getInitialRole()` and `getAdditionalInitialRoles()`.
-
-This is needed so that the self-registered users are assigned automatically to your application role(s) and be able to use the application. Without any role such user will be able only to see/use the logout link of the application.
-
-
-
-
-== Registering the Services
-
-Assuming that the `configuration-and-annotation` services installer is configured:
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then (if using the (non-ASF) http://github.com/isisaddons/isis-module-security[Isis addons' security] module) you will need to register your concrete implementation of `SecurityModuleAppUserRegistrationServiceAbstract`.
-
-
-
-
-== Related Services
-
-The most common use case is to allow users to sign-up through Isis' Wicket viewer. Because the process requires email to be sent, the following services must be configured:
-
-* xref:_ug_reference-services-api_manpage-EmailService[`EmailService`]
-* xref:_ug_reference-services-spi_manpage-EmailNotificationService[`EmailNotificationService`]
-* `UserRegistrationService` (this service)
-
-The `EmailService` in particular requires additional xref:_ug_runtime_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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer.adoc
deleted file mode 100644
index abeecf1..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer.adoc
+++ /dev/null
@@ -1,25 +0,0 @@
-[[_ug_restfulobjects-viewer]]
-= Restful Objects 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/
-
-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.
-
-The Restful Objects viewer also provides a number of proprietary extensions.
-
-
-
-include::_ug_restfulobjects-viewer_features.adoc[leveloffset=+1]
-
-include::_ug_restfulobjects-viewer_configuration-properties.adoc[leveloffset=+1]
-
-include::_ug_restfulobjects-viewer_hints-and-tips.adoc[leveloffset=+1]
-
-
-== Extending the viewer
-
-... is discussed in xref:_ug_extending_restfulobjects-viewer[Extending the Restful Objects viewer].
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties.adoc
deleted file mode 100644
index 81ff855..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties.adoc
+++ /dev/null
@@ -1,72 +0,0 @@
-[[_ug_restfulobjects-viewer_configuration-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/
-
-
-The Restful Objects viewer provides a number 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).
-
-[WARNING]
-====
-These configuration settings should be considered beta, and may change in the future in response to emerging requirements.
-
-Also, be aware enabling these settings makes the representations with respect to the http://restfulobjects.org[Restful Object spec]. (Based on experience in Isis, in the future the spec may be updated to allow such extensions).
-====
-
-
-.Restful Objects Viewer Configuration Properties
-[cols="2a,1,3", options="header"]
-|===
-|Property
-|Value +
-(_default value_)
-|Description
-
-|`isis.viewer.restfulobjects.` +
-`honorUiHints`
-| `true`,`false` (`_false_`)
-| See xref:_ug_restfulobjects-viewer_configuration-properties_honor-ui-hints[discussion], below.
-
-|`isis.viewer.restfulobjects.` +
-`suppressDescribedByLinks`
-| `true`,`false` (`_false_`)
-.6+| See xref:_ug_restfulobjects-viewer_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:_ug_restfulobjects-viewer_configuration-properties_simplified-object[discussion], below.
-
-|===
-
-
-
-
-include::_ug_restfulobjects-viewer_configuration-properties_honor-ui-hints.adoc[leveloffset=+1]
-include::_ug_restfulobjects-viewer_configuration-properties_suppressing-elements.adoc[leveloffset=+1]
-include::_ug_restfulobjects-viewer_configuration-properties_simplified-object-representation.adoc[leveloffset=+1]
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties_honor-ui-hints.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties_honor-ui-hints.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties_honor-ui-hints.adoc
deleted file mode 100644
index c9122cc..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties_honor-ui-hints.adoc
+++ /dev/null
@@ -1,27 +0,0 @@
-[[_ug_restfulobjects-viewer_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 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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties_simplified-object-representation.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties_simplified-object-representation.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties_simplified-object-representation.adoc
deleted file mode 100644
index e0b23d8..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties_simplified-object-representation.adoc
+++ /dev/null
@@ -1,68 +0,0 @@
-[[_ug_restfulobjects-viewer_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:_ug_restfulobjects-viewer_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:_ug_extending_restfulobjects-viewer[Extending the Restful Objects viewer].
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties_suppressing-elements.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties_suppressing-elements.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties_suppressing-elements.adoc
deleted file mode 100644
index ff35c6b..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties_suppressing-elements.adoc
+++ /dev/null
@@ -1,39 +0,0 @@
-[[_ug_restfulobjects-viewer_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:_ug_restfulobjects-viewer_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:_ug_extending_restfulobjects-viewer[Extending the Restful Objects viewer] in the <<Extending>> chapter.
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_features.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_features.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_features.adoc
deleted file mode 100644
index 5043db5..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_features.adoc
+++ /dev/null
@@ -1,23 +0,0 @@
-[[_ug_restfulobjects-viewer_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 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.
-
-== Restful Objects Specification
-
-IMPORTANT: TODO - a brief summary here
-
-The Restful Objects spec can be downloaded link:http://restfulobjects.org[here].
-
-== Pretty printing
-
-The JSON representations generated by the Restful Objects viewer are in compact form if the xref:_ug_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.
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_hints-and-tips.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_hints-and-tips.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_hints-and-tips.adoc
deleted file mode 100644
index b42c58a..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_hints-and-tips.adoc
+++ /dev/null
@@ -1,81 +0,0 @@
-[[_ug_restfulobjects-viewer_hints-and-tips]]
-= Hints and Tips
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-Since the Restful Objects viewer is designed for computer programs to interact with (rather than human beings), it can be a little difficult to explore and generally "grok" how it works.
-
-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.
-
-video::_-TOvVYWCHc[youtube,width="840px",height="472px"]
-
-
-
-
-== AngularJS Tips
-
-The hypermedia API exposed by Isis' Restful Objects viewer is intended be support both bespoke custom-written viewers as well as generic viewers. Indeed, we expect most clients consuming the API will be bespoke, not generic.
-
-This page captures one or two tips on using AngularJS to write such a bespoke client.
-
-
-=== Invoking a GET link (eg invoking a query action)
-
-Suppose you have a `CustomerService` providing a `findCustomer` action:
-
-[source,java]
-----
-public class CustomerService {
- public String id() { return "customers"; }
- @ActionSemantics(Of.SAFE)
- public Customer findCustomer(@Named("customerName") String customerName) { ... }
-}
-----
-
-Restful Objects will expose this as action with the following link that looks something like:
-
-[source,javascript]
-----
-{
- "rel" : "urn:org.restfulobjects:rels/invoke",
- "href" : "http://localhost:8080/restful/services/customers/actions/findCustomer/invoke",
- "method" : "GET",
- "type" : "application/json;profile=\"urn:org.restfulobjects:repr-types/action-result\"",
- "arguments" : {
- "customerName" : {
- "value" : null
- }
- }
-}
-----
-
-You can then invoke this using AngularJs' `$resource` service as follows.
-
-[source,javascript]
-----
-var findCustomer = $resource("http://localhost:8080/restful/services/customers/actions/findCustomer/invoke?:queryString");
-var findCustomerArgs = {
- "customerName": {
- "value": "Fred"
- }
-};
-findCustomer.get({queryString: JSON.stringify(findCustomerArgs)}, function(data) { ... } )
-----
-
-Here the `:queryString` placeholder in the initial `$resource` constructor is expanded with a stringified version of the JSON object representing the args. Note how the `findCustomerArgs` is the same as the `"arguments"` attribute in the original link (with a value provided instead of `null`).
-
-
-=== Invoking a PUT or POST link
-
-If the method is a PUT or a POST, then no `:queryString` placeholder is required in the URL, and the args are instead part of the body.
-
-Use `$resource.put(...)` or `$resource.post(...)` instead.
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime.adoc
deleted file mode 100644
index fb62b57..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime.adoc
+++ /dev/null
@@ -1,29 +0,0 @@
-[[_ug_runtime]]
-= Runtime
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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:_ug_wicket-viewer[Wicket Viewer] chapter and the <<Restful Objects Viewer>> chapter. Likewise[details of configuring security (Apache Shiro) can be found in the xref:_ug_security[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 <<Deployment>> chapter.
-====
-
-
-include::_ug_runtime_deployment-types.adoc[leveloffset=+1]
-include::_ug_runtime_configuration-files.adoc[leveloffset=+1]
-include::_ug_runtime_specifying-components.adoc[leveloffset=+1]
-include::_ug_runtime_configuring-core.adoc[leveloffset=+1]
-include::_ug_runtime_configuring-datanucleus.adoc[leveloffset=+1]
-include::_ug_runtime_web-xml.adoc[leveloffset=+1]
-include::_ug_runtime_application-specific.adoc[leveloffset=+1]
-
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_application-specific.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_application-specific.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_application-specific.adoc
deleted file mode 100644
index 156fad5..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_application-specific.adoc
+++ /dev/null
@@ -1,13 +0,0 @@
-[[_ug_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/
-
-IMPORTANT: TODO
-
-
-include::_ug_runtime_application-specific_application-css.adoc[leveloffset=+1]
-include::_ug_runtime_application-specific_application-js.adoc[leveloffset=+1]
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_application-specific_application-css.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_application-specific_application-css.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_application-specific_application-css.adoc
deleted file mode 100644
index 59fdc5a..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_application-specific_application-css.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-[[_ug_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/
-
-IMPORTANT: TODO - `WEB-INF/css/application.css`
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_application-specific_application-js.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_application-specific_application-js.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_application-specific_application-js.adoc
deleted file mode 100644
index 4b97f1b..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_application-specific_application-js.adoc
+++ /dev/null
@@ -1,9 +0,0 @@
-[[_ug_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/
-
-
-
-IMPORTANT: TODO - `WEB-INF/scripts/application.js`
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuration-files.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuration-files.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuration-files.adoc
deleted file mode 100644
index d3dcd6c..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuration-files.adoc
+++ /dev/null
@@ -1,36 +0,0 @@
-[[_ug_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 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:_ug_wicket-viewer[Wicket UI (viewer)] is in use
-
-* `viewer_restfulobjects.properties` - if the xref:_ug_restfulobjects-viewer[Restful Objects REST API (viewer)] is in use
-
-* `viewer.properties` - for any shared UI configuration
-
-* `persistor_datanucleus.properties` - assuming the JDO/DataNucleus objectstore is in use
-
-* `persistor.properties` - for any other objectstore configuration. This typically is used to hold `JDBC` ``URL``s
-
-* `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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-core.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-core.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-core.adoc
deleted file mode 100644
index cef424f..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-core.adoc
+++ /dev/null
@@ -1,239 +0,0 @@
-[[_ug_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:_ug_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:_ug_wicket-viewer_configuration-properties[here for Wicket viewer], and xref:_ug_restfulobjects-viewer_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:_ug_reference-annotations_manpage-DomainObject_editing[`@DomainObject#editing()`]); see xref:_ug_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 Isis itself. (Note that there is no "datanucleus" in the property).
-
-|`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:_user-guide_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:_user-guide_how-tos_ui-hints_action-icons-and-css[UI hints] for more details.
-
-|`isis.reflector.facets`
-|`FQCN`
-|Fully qualified class names of a custom implementation of `ProgrammingModel` interface. +
-
-See xref:_ug_extending_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:_ug_extending_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:_ug_extending_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_reference-object-layout_dynamic[dynamic layout]s. +
-
-See xref:_ug_extending_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:_ug_extending_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:_ug_reference-annotations_manpage-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`]).
-
-
-|`isis.services.` +
-`audit.objects`
-| `all`, `none` (`all`)
-|Whether the changed properties of objects should be automatically audited (for objects annotated with xref:_ug_reference-annotations_manpage-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:_ug_reference-annotations_manpage-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.service.` +
-`email.tls.enabled` +
-| `true`,`false` (`_true_`)
-|Whether to enable TLS for the email SMTP connection (used by xref:_ug_reference-services-api_manpage-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:_ug_reference-services-api_manpage-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:_ug_reference-services-api_manpage-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:_ug_reference-services-api_manpage-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:_ug_reference-services-api_manpage-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:_ug_reference-services-api_manpage-EventBusService[`EventBusService`] as the underlying event bus.
-
-| `isis.services.` +
-`eventbus.allowLateRegistration` +
-| `true`, `false`, (`_false_`)
-|whether a domain service can register with the xref:_ug_reference-services-api_manpage-EventBusService[`EventBusService`] after any events have posted. +
-
-Since this almost certainly constitutes a bug in application code, by default this is disallowed.
-
-
-|`isis.services.` +
-`publish.objects`
-| `all`, `none` (`all`)
-|Whether changed objects should be automatically published (for objects annotated with xref:_ug_reference-annotations_manpage-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:_ug_reference-annotations_manpage-Action_publishing[`@Action(publishing=Publishing.AS_CONFIGURED)`]. +
-
-|`isis.services.` +
-`translation.po.mode`
-| `read`,`write`
-|Whether to force the `TranslationService` into either read or write mode. +
-
-See xref:_ug_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:_ug_reference-annotations_manpage-PropertyLayout_labelPosition[`@PropertyLayout#labelPosition()`]
-
-|===
-
-
-
-
-[[_ug_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.
-
-
-
-[[_ug_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 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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus.adoc
deleted file mode 100644
index dd94c59..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus.adoc
+++ /dev/null
@@ -1,18 +0,0 @@
-[[_ug_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 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 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:_ug_more-advanced_overriding-jdo-annotations[Overriding JDO Annotatons] for further discussion.
-
-
-include::_ug_runtime_configuring-datanucleus_properties.adoc[leveloffset=+1]
-include::_ug_runtime_configuring-datanucleus_persistence-xml.adoc[leveloffset=+1]
-include::_ug_runtime_configuring-datanucleus_eagerly-registering-entities.adoc[leveloffset=+1]
-include::_ug_runtime_configuring-datanucleus_disabling-persistence-by-reachability.adoc[leveloffset=+1]
-include::_ug_runtime_configuring-datanucleus_using-jndi-data-source.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_disabling-persistence-by-reachability.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_disabling-persistence-by-reachability.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_disabling-persistence-by-reachability.adoc
deleted file mode 100644
index 25ad73a..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_disabling-persistence-by-reachability.adoc
+++ /dev/null
@@ -1,88 +0,0 @@
-[[_ug_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 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 Isis' xref:_ug_reference-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_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/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_eagerly-registering-entities.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_eagerly-registering-entities.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_eagerly-registering-entities.adoc
deleted file mode 100644
index 5d99d25..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_eagerly-registering-entities.adoc
+++ /dev/null
@@ -1,44 +0,0 @@
-[[_ug_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. Isis builds its metamodel by walking the graph of types from the services registered using `@DomainService` or explicitly registered in `isis.properties`. The JDO 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.
-
-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 `RegisterEntities` service can therefore be registered in order to do the eager registration. It searches for all `@PersistenceCapable` entities under specified package(s), and registers them all.
-
-[WARNING]
-====
-There's a chance that (from 1.6.0+) feature may be (partly?) broken; see https://issues.apache.org/jira/browse/ISIS-847[ISIS-847].
-====
-
-
-== Specify the Package Prefix(es)
-
-In the `persistor_datanucleus.properties`, specify the package prefix(es) of your application, to provide a hint for finding the `@PersistenceCapable` classes.
-
-The value of this property can be a comma-separated list (if there is more than one package or Maven module that holds persistable entities).
-
-
-== Integration Testing
-
-The `IsisConfigurationForJdoIntegTests`, recommended for use in xref:_ug_testing_integ-test-support[Integration Testing] provides the `#addRegisterEntitiesPackagePrefix()` method to set up this configuration property:
-
-[source,java]
-.Integration test bootstrapping
-----
-private static class SimpleAppSystemBuilder extends IsisSystemForTest.Builder {
- ...
- private static IsisConfiguration testConfiguration() {
- final IsisConfigurationForJdoIntegTests testConfiguration = new IsisConfigurationForJdoIntegTests();
- testConfiguration.addRegisterEntitiesPackagePrefix("domainapp.dom.modules"); // <1>
- return testConfiguration;
- }
-}
-----
-<1> specify the package prefix(es) for integration testing.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_persistence-xml.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_persistence-xml.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_persistence-xml.adoc
deleted file mode 100644
index cf8b777..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_persistence-xml.adoc
+++ /dev/null
@@ -1,10 +0,0 @@
-[[_ug_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/
-
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_properties.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_properties.adoc
deleted file mode 100644
index b740bab..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_properties.adoc
+++ /dev/null
@@ -1,64 +0,0 @@
-[[_ug_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)
-| of class names; specifies the entities early rather than allow DataNucleus to find the entities lazily. Strongly recommended (subtle issues can sometimes arise if lazy discovery is used).
-Further xref:_ug_runtime_configuring-datanucleus_eagerly-registering-entities[discussion below].
-
-|`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:_ug_runtime_configuring-datanucleus_disabling-persistence-by-reachability[discussion below].
-
-|===
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_using-jndi-data-source.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_using-jndi-data-source.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_using-jndi-data-source.adoc
deleted file mode 100644
index 25649c0..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_using-jndi-data-source.adoc
+++ /dev/null
@@ -1,75 +0,0 @@
-[[_ug_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 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.
-====
-
[02/45] isis git commit: ISIS-1133: breaking out reference guide and
devenv guide;
moving appendices' release notes and migration notes to other docs;
improving the documentation page.
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/110-running-the-app/020-datanucleus-enhancer-goal.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/110-running-the-app/020-datanucleus-enhancer-goal.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/110-running-the-app/020-datanucleus-enhancer-goal.png
deleted file mode 100644
index 2dae157..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/110-running-the-app/020-datanucleus-enhancer-goal.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/110-running-the-app/030-running-unit-tests.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/110-running-the-app/030-running-unit-tests.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/110-running-the-app/030-running-unit-tests.png
deleted file mode 100644
index b4e042a..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/110-running-the-app/030-running-unit-tests.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/110-running-the-app/040-running-unit-tests-run-configuration.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/110-running-the-app/040-running-unit-tests-run-configuration.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/110-running-the-app/040-running-unit-tests-run-configuration.png
deleted file mode 100644
index 83a4a70..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/110-running-the-app/040-running-unit-tests-run-configuration.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/110-running-the-app/050-running-integration-tests-run-configuration.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/110-running-the-app/050-running-integration-tests-run-configuration.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/110-running-the-app/050-running-integration-tests-run-configuration.png
deleted file mode 100644
index 6b0ad89..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/110-running-the-app/050-running-integration-tests-run-configuration.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/200-project-sdk/010-file-project-structure.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/200-project-sdk/010-file-project-structure.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/200-project-sdk/010-file-project-structure.png
deleted file mode 100644
index 544a185..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/200-project-sdk/010-file-project-structure.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/200-project-sdk/020-select-jdk.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/200-project-sdk/020-select-jdk.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/200-project-sdk/020-select-jdk.png
deleted file mode 100644
index 90865f1..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/200-project-sdk/020-select-jdk.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/200-project-sdk/030-select-jdk-directory.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/200-project-sdk/030-select-jdk-directory.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/200-project-sdk/030-select-jdk-directory.png
deleted file mode 100644
index f5675b2..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/200-project-sdk/030-select-jdk-directory.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/200-project-sdk/040-set-project-level.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/200-project-sdk/040-set-project-level.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/200-project-sdk/040-set-project-level.png
deleted file mode 100644
index 026a821..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/200-project-sdk/040-set-project-level.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/200-project-sdk/050-isis-language-level-7.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/200-project-sdk/050-isis-language-level-7.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/200-project-sdk/050-isis-language-level-7.png
deleted file mode 100644
index 62e220b..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/200-project-sdk/050-isis-language-level-7.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/200-project-sdk/060-app-language-level-8.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/200-project-sdk/060-app-language-level-8.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/200-project-sdk/060-app-language-level-8.png
deleted file mode 100644
index 5723524..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/200-project-sdk/060-app-language-level-8.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/250-new-project/010-new-project.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/250-new-project/010-new-project.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/250-new-project/010-new-project.png
deleted file mode 100644
index edc97cf..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/250-new-project/010-new-project.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/250-new-project/020-new-project-name.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/250-new-project/020-new-project-name.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/250-new-project/020-new-project-name.png
deleted file mode 100644
index 15b78a7..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/250-new-project/020-new-project-name.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/250-new-project/030-new-project-new-window.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/250-new-project/030-new-project-new-window.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/250-new-project/030-new-project-new-window.png
deleted file mode 100644
index b8d8e61..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/250-new-project/030-new-project-new-window.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/250-new-project/040-new-module-from-existing-sources.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/250-new-project/040-new-module-from-existing-sources.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/250-new-project/040-new-module-from-existing-sources.png
deleted file mode 100644
index 160b3b9..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/250-new-project/040-new-module-from-existing-sources.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/250-new-project/050-specify-source-folder.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/250-new-project/050-specify-source-folder.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/250-new-project/050-specify-source-folder.png
deleted file mode 100644
index 5eecb9c..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/250-new-project/050-specify-source-folder.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/250-new-project/060-import-using-maven.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/250-new-project/060-import-using-maven.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/250-new-project/060-import-using-maven.png
deleted file mode 100644
index 55a5db3..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/250-new-project/060-import-using-maven.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/250-new-project/070-import-module-settings.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/250-new-project/070-import-module-settings.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/250-new-project/070-import-module-settings.png
deleted file mode 100644
index 6828802..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/250-new-project/070-import-module-settings.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/250-new-project/080-maven-profiles.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/250-new-project/080-maven-profiles.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/250-new-project/080-maven-profiles.png
deleted file mode 100644
index fcc12aa..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/250-new-project/080-maven-profiles.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/250-new-project/090-maven-coordinates.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/250-new-project/090-maven-coordinates.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/250-new-project/090-maven-coordinates.png
deleted file mode 100644
index fc6691f..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/250-new-project/090-maven-coordinates.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/250-new-project/100-annotation-processing.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/250-new-project/100-annotation-processing.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/250-new-project/100-annotation-processing.png
deleted file mode 100644
index dbb7b6a..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/250-new-project/100-annotation-processing.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/250-new-project/110-parameter8.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/250-new-project/110-parameter8.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/250-new-project/110-parameter8.png
deleted file mode 100644
index a7c4d8d..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/250-new-project/110-parameter8.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/250-new-project/120-clean-generate-sources.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/250-new-project/120-clean-generate-sources.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/250-new-project/120-clean-generate-sources.png
deleted file mode 100644
index 5a9182b..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/250-new-project/120-clean-generate-sources.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/300-paraname8-support/010-configuring-the-compiler.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/300-paraname8-support/010-configuring-the-compiler.png b/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/300-paraname8-support/010-configuring-the-compiler.png
deleted file mode 100644
index 50a043f..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/appendices/dev-env/intellij-idea/300-paraname8-support/010-configuring-the-compiler.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/configuration/configuring-shiro/ldap/activeds-ldap-groups.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/configuration/configuring-shiro/ldap/activeds-ldap-groups.png b/adocs/documentation/src/main/asciidoc/user-guide/images/configuration/configuring-shiro/ldap/activeds-ldap-groups.png
deleted file mode 100644
index 0496a84..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/configuration/configuring-shiro/ldap/activeds-ldap-groups.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/configuration/configuring-shiro/ldap/activeds-ldap-mojo-partition.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/configuration/configuring-shiro/ldap/activeds-ldap-mojo-partition.png b/adocs/documentation/src/main/asciidoc/user-guide/images/configuration/configuring-shiro/ldap/activeds-ldap-mojo-partition.png
deleted file mode 100644
index 42d7480..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/configuration/configuring-shiro/ldap/activeds-ldap-mojo-partition.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/configuration/configuring-shiro/ldap/activeds-ldap-mojo-root-dse.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/configuration/configuring-shiro/ldap/activeds-ldap-mojo-root-dse.png b/adocs/documentation/src/main/asciidoc/user-guide/images/configuration/configuring-shiro/ldap/activeds-ldap-mojo-root-dse.png
deleted file mode 100644
index 9c4c480..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/configuration/configuring-shiro/ldap/activeds-ldap-mojo-root-dse.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/configuration/configuring-shiro/ldap/activeds-ldap-sasl-authentication.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/configuration/configuring-shiro/ldap/activeds-ldap-sasl-authentication.png b/adocs/documentation/src/main/asciidoc/user-guide/images/configuration/configuring-shiro/ldap/activeds-ldap-sasl-authentication.png
deleted file mode 100644
index 91d1a61..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/configuration/configuring-shiro/ldap/activeds-ldap-sasl-authentication.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/configuration/configuring-shiro/ldap/activeds-ldap-users.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/configuration/configuring-shiro/ldap/activeds-ldap-users.png b/adocs/documentation/src/main/asciidoc/user-guide/images/configuration/configuring-shiro/ldap/activeds-ldap-users.png
deleted file mode 100644
index 7ff133c..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/configuration/configuring-shiro/ldap/activeds-ldap-users.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/core-concepts/philosophy/hexagonal-architecture.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/core-concepts/philosophy/hexagonal-architecture.png b/adocs/documentation/src/main/asciidoc/user-guide/images/core-concepts/philosophy/hexagonal-architecture.png
deleted file mode 100644
index d8b28bd..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/core-concepts/philosophy/hexagonal-architecture.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/core-concepts/philosophy/hexagonal-architecture.pptx
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/core-concepts/philosophy/hexagonal-architecture.pptx b/adocs/documentation/src/main/asciidoc/user-guide/images/core-concepts/philosophy/hexagonal-architecture.pptx
deleted file mode 100644
index 3eb0aad..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/core-concepts/philosophy/hexagonal-architecture.pptx and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/simpleapp-webapp-with-fixtures.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/simpleapp-webapp-with-fixtures.png b/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/simpleapp-webapp-with-fixtures.png
deleted file mode 100644
index 1dd885a..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/simpleapp-webapp-with-fixtures.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/simpleapp-webapp.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/simpleapp-webapp.png b/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/simpleapp-webapp.png
deleted file mode 100644
index 771451b..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/simpleapp-webapp.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/010-root-page.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/010-root-page.png b/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/010-root-page.png
deleted file mode 100644
index 74e5ff9..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/010-root-page.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/020-login-to-wicket-viewer.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/020-login-to-wicket-viewer.png b/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/020-login-to-wicket-viewer.png
deleted file mode 100644
index fc0d919..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/020-login-to-wicket-viewer.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/030-home-page-run-fixture-scripts.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/030-home-page-run-fixture-scripts.png b/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/030-home-page-run-fixture-scripts.png
deleted file mode 100644
index 3a1bb54..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/030-home-page-run-fixture-scripts.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/040-first-object.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/040-first-object.png b/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/040-first-object.png
deleted file mode 100644
index bc999ee..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/040-first-object.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/050-update-name-prompt.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/050-update-name-prompt.png b/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/050-update-name-prompt.png
deleted file mode 100644
index 166e533..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/050-update-name-prompt.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/060-object-updated.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/060-object-updated.png b/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/060-object-updated.png
deleted file mode 100644
index d34888a..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/060-object-updated.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/070-list-all-prompt.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/070-list-all-prompt.png b/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/070-list-all-prompt.png
deleted file mode 100644
index 59cc275..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/070-list-all-prompt.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/080-list-all.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/080-list-all.png b/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/080-list-all.png
deleted file mode 100644
index e3e67cf..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/080-list-all.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/090-create.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/090-create.png b/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/090-create.png
deleted file mode 100644
index f5708ec..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/090-create.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/100-create-prompt.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/100-create-prompt.png b/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/100-create-prompt.png
deleted file mode 100644
index 9829512..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/100-create-prompt.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/110-object-created.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/110-object-created.png b/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/110-object-created.png
deleted file mode 100644
index 31696f3..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/110-object-created.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/120-list-all.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/120-list-all.png b/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/120-list-all.png
deleted file mode 100644
index 75a4e04..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/120-list-all.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/220-login-to-restful-viewer.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/220-login-to-restful-viewer.png b/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/220-login-to-restful-viewer.png
deleted file mode 100644
index 1b364b5..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/220-login-to-restful-viewer.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/230-home-page.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/230-home-page.png b/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/230-home-page.png
deleted file mode 100644
index d032e68..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/230-home-page.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/240-list-all-invoke.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/240-list-all-invoke.png b/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/240-list-all-invoke.png
deleted file mode 100644
index 57971ef..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/240-list-all-invoke.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/250-list-all-results.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/250-list-all-results.png b/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/250-list-all-results.png
deleted file mode 100644
index b8c8b8b..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/getting-started/using-simple-app/250-list-all-results.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/headless-access/BackgroundCommandExecution.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/headless-access/BackgroundCommandExecution.png b/adocs/documentation/src/main/asciidoc/user-guide/images/headless-access/BackgroundCommandExecution.png
deleted file mode 100644
index 5cefae3..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/headless-access/BackgroundCommandExecution.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/headless-access/BackgroundCommandExecutionFromBackgroundCommandServiceJdo.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/headless-access/BackgroundCommandExecutionFromBackgroundCommandServiceJdo.png b/adocs/documentation/src/main/asciidoc/user-guide/images/headless-access/BackgroundCommandExecutionFromBackgroundCommandServiceJdo.png
deleted file mode 100644
index 0c026fb..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/headless-access/BackgroundCommandExecutionFromBackgroundCommandServiceJdo.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/how-tos/domain-services/hexagonal-architecture-addons.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/how-tos/domain-services/hexagonal-architecture-addons.png b/adocs/documentation/src/main/asciidoc/user-guide/images/how-tos/domain-services/hexagonal-architecture-addons.png
deleted file mode 100644
index af32db1..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/how-tos/domain-services/hexagonal-architecture-addons.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/how-tos/tips-n-tricks/are-you-sure-happy-case.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/how-tos/tips-n-tricks/are-you-sure-happy-case.png b/adocs/documentation/src/main/asciidoc/user-guide/images/how-tos/tips-n-tricks/are-you-sure-happy-case.png
deleted file mode 100644
index 1981c09..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/how-tos/tips-n-tricks/are-you-sure-happy-case.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/how-tos/tips-n-tricks/are-you-sure-sad-case.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/how-tos/tips-n-tricks/are-you-sure-sad-case.png b/adocs/documentation/src/main/asciidoc/user-guide/images/how-tos/tips-n-tricks/are-you-sure-sad-case.png
deleted file mode 100644
index 6182447..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/how-tos/tips-n-tricks/are-you-sure-sad-case.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/how-tos/tips-n-tricks/are-you-sure.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/how-tos/tips-n-tricks/are-you-sure.png b/adocs/documentation/src/main/asciidoc/user-guide/images/how-tos/tips-n-tricks/are-you-sure.png
deleted file mode 100644
index e1a76fe..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/how-tos/tips-n-tricks/are-you-sure.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/how-tos/ui-hints/object-titles-and-icons/cust-order-product.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/how-tos/ui-hints/object-titles-and-icons/cust-order-product.png b/adocs/documentation/src/main/asciidoc/user-guide/images/how-tos/ui-hints/object-titles-and-icons/cust-order-product.png
deleted file mode 100644
index 3cec4bd..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/how-tos/ui-hints/object-titles-and-icons/cust-order-product.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/ActionLayout/bookmarking.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/ActionLayout/bookmarking.png b/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/ActionLayout/bookmarking.png
deleted file mode 100644
index 0100b63..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/ActionLayout/bookmarking.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/ActionLayout/position-BELOW.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/ActionLayout/position-BELOW.png b/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/ActionLayout/position-BELOW.png
deleted file mode 100644
index 944bb52..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/ActionLayout/position-BELOW.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/ActionLayout/position-PANEL.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/ActionLayout/position-PANEL.png b/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/ActionLayout/position-PANEL.png
deleted file mode 100644
index ef01a63..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/ActionLayout/position-PANEL.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/ActionLayout/position-PANEL_DROPDOWN.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/ActionLayout/position-PANEL_DROPDOWN.png b/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/ActionLayout/position-PANEL_DROPDOWN.png
deleted file mode 100644
index 2194ee8..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/ActionLayout/position-PANEL_DROPDOWN.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/ActionLayout/position-RIGHT.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/ActionLayout/position-RIGHT.png b/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/ActionLayout/position-RIGHT.png
deleted file mode 100644
index 0da5647..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/ActionLayout/position-RIGHT.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/CollectionLayout/sortedby-dependencies.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/CollectionLayout/sortedby-dependencies.png b/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/CollectionLayout/sortedby-dependencies.png
deleted file mode 100644
index e5936b5..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/CollectionLayout/sortedby-dependencies.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/DomainObjectLayout/bookmarking-nested.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/DomainObjectLayout/bookmarking-nested.png b/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/DomainObjectLayout/bookmarking-nested.png
deleted file mode 100644
index c48eb9c..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/DomainObjectLayout/bookmarking-nested.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/DomainObjectLayout/bookmarking.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/DomainObjectLayout/bookmarking.png b/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/DomainObjectLayout/bookmarking.png
deleted file mode 100644
index 0100b63..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/DomainObjectLayout/bookmarking.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/DomainServiceLayout/menuBar-primary.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/DomainServiceLayout/menuBar-primary.png b/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/DomainServiceLayout/menuBar-primary.png
deleted file mode 100644
index 6fe3947..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/DomainServiceLayout/menuBar-primary.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/DomainServiceLayout/menuBar-secondary.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/DomainServiceLayout/menuBar-secondary.png b/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/DomainServiceLayout/menuBar-secondary.png
deleted file mode 100644
index 46f8e62..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/DomainServiceLayout/menuBar-secondary.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/DomainServiceLayout/menuBar-tertiary.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/DomainServiceLayout/menuBar-tertiary.png b/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/DomainServiceLayout/menuBar-tertiary.png
deleted file mode 100644
index c87c8ad..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/DomainServiceLayout/menuBar-tertiary.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/DomainServiceLayout/menuOrder.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/DomainServiceLayout/menuOrder.png b/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/DomainServiceLayout/menuOrder.png
deleted file mode 100644
index b5029dd..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/DomainServiceLayout/menuOrder.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/HomePage/HomePage.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/HomePage/HomePage.png b/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/HomePage/HomePage.png
deleted file mode 100644
index 59880f4..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/HomePage/HomePage.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/PropertyLayout/labelPosition-LEFT.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/PropertyLayout/labelPosition-LEFT.png b/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/PropertyLayout/labelPosition-LEFT.png
deleted file mode 100644
index 3298ead..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/PropertyLayout/labelPosition-LEFT.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/PropertyLayout/labelPosition-NONE.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/PropertyLayout/labelPosition-NONE.png b/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/PropertyLayout/labelPosition-NONE.png
deleted file mode 100644
index e903f0c..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/PropertyLayout/labelPosition-NONE.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/PropertyLayout/labelPosition-TOP.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/PropertyLayout/labelPosition-TOP.png b/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/PropertyLayout/labelPosition-TOP.png
deleted file mode 100644
index 8cd2f37..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/PropertyLayout/labelPosition-TOP.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/PropertyLayout/labelPosition-boolean-LEFT.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/PropertyLayout/labelPosition-boolean-LEFT.png b/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/PropertyLayout/labelPosition-boolean-LEFT.png
deleted file mode 100644
index 9b4742b..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/PropertyLayout/labelPosition-boolean-LEFT.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/PropertyLayout/labelPosition-boolean-RIGHT.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/PropertyLayout/labelPosition-boolean-RIGHT.png b/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/PropertyLayout/labelPosition-boolean-RIGHT.png
deleted file mode 100644
index 6595267..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-annotations/PropertyLayout/labelPosition-boolean-RIGHT.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/reference-layout/4-0-8-0.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-layout/4-0-8-0.png b/adocs/documentation/src/main/asciidoc/user-guide/images/reference-layout/4-0-8-0.png
deleted file mode 100644
index 1ebb062..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-layout/4-0-8-0.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/reference-layout/4-4-4-12.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-layout/4-4-4-12.png b/adocs/documentation/src/main/asciidoc/user-guide/images/reference-layout/4-4-4-12.png
deleted file mode 100644
index fd946bf..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-layout/4-4-4-12.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/reference-layout/6-6-0-12.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-layout/6-6-0-12.png b/adocs/documentation/src/main/asciidoc/user-guide/images/reference-layout/6-6-0-12.png
deleted file mode 100644
index 369efb7..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-layout/6-6-0-12.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/reference-layout/isis-layout-show-facets.css
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-layout/isis-layout-show-facets.css b/adocs/documentation/src/main/asciidoc/user-guide/images/reference-layout/isis-layout-show-facets.css
deleted file mode 100644
index c6b6334..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-layout/isis-layout-show-facets.css
+++ /dev/null
@@ -1,3 +0,0 @@
-ul.isis-facets {
- display: initial;
-}
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/reference-layout/isis-layout.css
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-layout/isis-layout.css b/adocs/documentation/src/main/asciidoc/user-guide/images/reference-layout/isis-layout.css
deleted file mode 100644
index acd445d..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-layout/isis-layout.css
+++ /dev/null
@@ -1,253 +0,0 @@
-.primary-1 {
- background-color: #669900;
-}
-
-.primary-2 {
- background-color: #669900;
-}
-
-.primary-3 {
- background-color: #669900;
-}
-
-.primary-4 {
- background-color: #99FF66;
-}
-
-.primary-5 {
- background-color: #CCFF99;
-}
-
-.secondary-a-1 {
- background-color: #006666;
-}
-
-.secondary-a-2 {
- background-color: #006666;
-}
-
-.secondary-a-3 {
- background-color: #006666;
-}
-
-.secondary-a-4 {
- background-color: #66CCCC;
-}
-
-.secondary-a-5 {
- background-color: #99CCCC;
-}
-
-.secondary-b-1 {
- background-color: #999900;
-}
-
-.secondary-b-2 {
- background-color: #999900;
-}
-
-.secondary-b-3 {
- background-color: #999900;
-}
-
-.secondary-b-4 {
- background-color: #FFFF66;
-}
-
-.secondary-b-5 {
- background-color: #FFFFCC;
-}
-
-.complement-1 {
- background-color: #990033;
-}
-
-.complement-2 {
- background-color: #990033;
-}
-
-.complement-3 {
- background-color: #990033;
-}
-
-.complement-4 {
- background-color: #FF6699;
-}
-
-.complement-5 {
- background-color: #FF99CC;
-}
-
-
-
-legend {
- background-color: white;
-}
-
-fieldset {
- padding-bottom: 10px;
-}
-
-span,li {
- color: white;
-}
-span {
- font-weight: bold;
-}
-
-li {
- padding-bottom: 10px;
- margin-bottom: 10px;
-}
-
-
-
-.isis-header {
- padding: 20px 80px 20px 40px;
- margin-right: 100px;
- background-color: #99CCCC;
- display: block;
- width: 100%;
-}
-
-.isis-header span.isis-title {
- font-size: xx-large;
- padding: 5px 80px 5px 40px;
- margin-right: 50px;
- color: black;
- background-color: #99FF66;
- display: inline-table;
- vertical-align: bottom;
-}
-
-.isis-header div.isis-actions span {
- font-size: large;
- padding: 5px 5px 5px 5px;
- display: inline-table;
-}
-
-.isis-memberGroup, .isis-collection {
- margin-top: 10px;
- margin-bottom: 10px;
- min-height: 100px;
-}
-
-.isis-memberGroup {
- background-color: #669900;
-}
-
-.isis-collection {
- background-color: #999900;
-}
-
-
-div.isis-property > span {
- margin-left: 5%;
- padding-left: 10px;
- width: 90%;
- display: block;
-}
-
-fieldset div.isis-property > span {
- padding: 5px;
- margin: 10px;
- background-color: #006666;
-}
-
-.isis-header div.isis-actions,
-fieldset div.isis-actions {
- margin-left: 60px;
-}
-
-fieldset.isis-collection div.isis-actions {
- margin-left: 60px;
-}
-
-.isis-header .isis-actions {
- display: inline-block;
-}
-
-.isis-header div.isis-action,
-fieldset div.isis-action {
- display: inline-table;
- padding: 5px;
- margin-top: 5px;
- margin-bottom: 5px;
- background-color: #990033;
-}
-
-
-fieldset div.isis-action span {
- background-color: #990033;
-}
-
-.isis-memberGroups {}
-
-.isis-memberGroup.min-height-50,
-.isis-collection.min-height-50 {
- min-height: 50px;
-}
-
-.isis-memberGroup.min-height-100,
-.isis-collection.min-height-100 {
- min-height: 100px;
-}
-
-.isis-memberGroup.min-height-150,
-.isis-collection.min-height-150 {
- min-height: 150px;
-}
-
-.isis-memberGroup.min-height-200,
-.isis-collection.min-height-200 {
- min-height: 200px;
-}
-
-.isis-memberGroup.min-height-250,
-.isis-collection.min-height-250 {
- min-height: 250px;
-}
-
-.isis-memberGroup.min-height-300,
-.isis-collection.min-height-300 {
- min-height: 300px;
-}
-
-.isis-memberGroup.min-height-350,
-.isis-collection.min-height-350 {
- min-height: 350px;
-}
-
-.isis-memberGroup.min-height-400,
-.isis-collection.min-height-400 {
- min-height: 400px;
-}
-
-.isis-memberGroup .isis-hidden {
- display: none;
-}
-
-.isis-action ul.isis-facets li {
- margin-top: 30px;
-}
-ul.isis-facets li {
- margin-left: 40px;
- font-size: small;
-}
-.isis-action ul.isis-facets li {
- margin-top: 10px;
- margin-left: 20px;
-}
-.isis-action ul.isis-facets li {
- font-size: small;
-}
-ul.isis-facets {
- line-height: 0px;
-}
-ul.isis-facets {
- margin:0px;
-}
-
-.isis-facets {
- display: none;
-}
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/reference-layout/layout-4-0-8-0.html
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-layout/layout-4-0-8-0.html b/adocs/documentation/src/main/asciidoc/user-guide/images/reference-layout/layout-4-0-8-0.html
deleted file mode 100644
index eeeb185..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-layout/layout-4-0-8-0.html
+++ /dev/null
@@ -1,198 +0,0 @@
-f<!DOCTYPE html>
-<html lang="en">
-<head>
- <meta charset="utf-8">
- <meta http-equiv="X-UA-Compatible" content="IE=edge">
- <meta name="viewport" content="width=device-width, initial-scale=1">
- <title>colspans={4,0,8,0}</title>
-
- <!-- Bootstrap -->
- <!--
- <link rel="stylesheet" href="//netdna.bootstrapcdn.com/bootstrap/3.1.1/css/bootstrap.min.css">
- <link rel="stylesheet" href="//netdna.bootstrapcdn.com/bootstrap/3.1.1/css/bootstrap-theme.min.css">
- <script src="//netdna.bootstrapcdn.com/bootstrap/3.1.1/js/bootstrap.min.js"></script>
- -->
-
- <!-- Bootstrap -->
- <link href="css/bootstrap.min.css" rel="stylesheet">
-
- <!-- HTML5 Shim and Respond.js IE8 support of HTML5 elements and media queries -->
- <!-- WARNING: Respond.js doesn't work if you view the page via file:// -->
- <!--[if lt IE 9]>
- <script src="https://oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
- <script src="https://oss.maxcdn.com/libs/respond.js/1.4.2/respond.min.js"></script>
- <![endif]-->
- <link href="isis-layout.css" rel="stylesheet">
- <!--<link href="isis-layout-show-facets.css" rel="stylesheet">-->
-</head>
- <body>
- <div class="container">
- <h1>colspans={4,0,8,0}</h1>
- <div class="row">
- <div class="col-md-12">
- <div class="isis-header">
- <span class="isis-title">Buy bread</span>
- <div class="isis-actions">
- <div class="isis-action x-caution">
- <span>delete</span>
- </div>
- <div class="isis-action">
- <span data-isis-id="duplicate">clone</span>
- <ul class="isis-facets">
- <li>describedAs.value="Create a new todo item from this one"</li>
- </ul>
- </div>
- <div class="isis-action">
- <span>recentChanges</span>
- </div>
- <div class="isis-action">
- <span>recentChanges</span>
- </div>
- </div>
- </div>
- </div>
- </div>
- <div class="row">
- <div class="col-md-4 isis-memberGroups">
- <fieldset class="isis-memberGroup min-height-100">
- <legend>General</legend>
- <div class="isis-property">
- <span data-isis-typicallength="50">description</span>
- <ul class="isis-facets">
- <li>typicalLength.value=50</li>
- </ul>
- </div>
- <div class="isis-property">
- <span>category</span>
- <ul class="isis-facets">
- <li>disabled.reason="Use action to update both category and subcategory"</li>
- </ul>
- </div>
- <div class="isis-property">
- <span>subcategory</span>
- <ul class="isis-facets">
- <li>disabled.reason="Use action to update both category and subcategory"</li>
- </ul>
- <div class="isis-actions">
- <div class="isis-action">
- <span data-isis-id="updateCategory">update</span>
- </div>
- <div class="isis-action">
- <span>analyseCategory</span>
- </div>
- </div>
- </div>
- <div class="isis-property">
- <span class="isis-hidden">ownedBy</span>
- </div>
- <div class="isis-property x-highlight">
- <span data-isis-id="complete">done</span>
- <div class="isis-actions">
- <div class="isis-action">
- <span data-isis-id="completed">done</span>
- <ul class="isis-facets">
- <li>describedAs.value="Mark this todo item as having been completed"</li>
- </ul>
- </div>
- <div class="isis-action">
- <span>scheduleExplicitly</span>
- </div>
- <div class="isis-action">
- <span>scheduleImplicitly</span>
- </div>
- <div class="isis-action">
- <span data-isis-id="notYetCompleted">not done</span>
- </div>
- </div>
- </div>
- </fieldset>
- <fieldset class="isis-memberGroup">
- <legend>Priority</legend>
- <div class="isis-property">
- <span>relativePriority</span>
- <div class="isis-actions">
- <div class="isis-action">
- <span>previous</span>
- </div>
- <div class="isis-action">
- <span>next</span>
- </div>
- </div>
- </div>
- <div class="isis-property x-key">
- <span>dueBy</span>
- </div>
- <legend>Other</legend>
- <div class="isis-property">
- <span>cost</span>
- <div class="isis-actions">
- <div class="isis-action">
- <span data-isis-id="updateCost">update</span>
- </div>
- </div>
- </div>
- <div class="isis-property">
- <span>notes</span>
- <ul class="isis-facets">
- <li>multiLine.numberOfLines=5</li>
- <li>hidden.where=ALL_TABLES</li>
- </ul>
- </div>
- <div class="isis-property">
- <span>attachment</span>
- <ul class="isis-facets">
- <li>hidden.where=ALL_TABLES</li>
- </ul>
- </div>
- <div class="isis-property">
- <span data-isis-id="versionSequence">version</span>
- <ul class="isis-facets">
- <li>disabled</li>
- <li>hidden.where=STANDALONE_TABLES</li>
- </ul>
- </div>
- </fieldset>
- </div>
- <div class="col-md-8">
- <fieldset class="isis-collection min-height-100">
- <legend>dependencies</legend>
- <div class="isis-actions">
- <div class="isis-action">
- <span>add</span>
- </div>
- <div class="isis-action x-caution">
- <span>remove</span>
- </div>
- </div>
- <ul class="isis-facets">
- <li>disabled</li>
- <li>paged.value=5</li>
- <li>render.value=EAGERLY</li>
- </ul>
- </fieldset>
- <fieldset class="isis-collection min-height-200">
- <legend>similarTo</legend>
- <ul class="isis-facets">
- <li>disabled</li>
- <li>paged.value=3</li>
- <li>render.value=LAZILY</li>
- </ul>
- </fieldset>
- </div>
- </div>
- <div class="row">
- <div class="col-md-12">
- </div>
- </div>
- </div>
-
- <!-- jQuery (necessary for Bootstrap's JavaScript plugins) -->
- <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.0/jquery.min.js"></script>
- <!-- Include all compiled plugins (below), or include individual files as needed -->
- <script src="js/bootstrap.min.js"></script>
- <script>
- $(document).ready(function () {
- });
- </script>
- </body>
-</html>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/images/reference-layout/layout-4-4-4-12.html
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-layout/layout-4-4-4-12.html b/adocs/documentation/src/main/asciidoc/user-guide/images/reference-layout/layout-4-4-4-12.html
deleted file mode 100644
index cd508dc..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/images/reference-layout/layout-4-4-4-12.html
+++ /dev/null
@@ -1,205 +0,0 @@
-f<!DOCTYPE html>
-<html lang="en">
-<head>
- <meta charset="utf-8">
- <meta http-equiv="X-UA-Compatible" content="IE=edge">
- <meta name="viewport" content="width=device-width, initial-scale=1">
- <title>colspans={4,4,4,12}</title>
-
- <!-- Bootstrap -->
- <!--
- <link rel="stylesheet" href="//netdna.bootstrapcdn.com/bootstrap/3.1.1/css/bootstrap.min.css">
- <link rel="stylesheet" href="//netdna.bootstrapcdn.com/bootstrap/3.1.1/css/bootstrap-theme.min.css">
- <script src="//netdna.bootstrapcdn.com/bootstrap/3.1.1/js/bootstrap.min.js"></script>
- -->
-
- <!-- Bootstrap -->
- <link href="css/bootstrap.min.css" rel="stylesheet">
-
- <!-- HTML5 Shim and Respond.js IE8 support of HTML5 elements and media queries -->
- <!-- WARNING: Respond.js doesn't work if you view the page via file:// -->
- <!--[if lt IE 9]>
- <script src="https://oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
- <script src="https://oss.maxcdn.com/libs/respond.js/1.4.2/respond.min.js"></script>
- <![endif]-->
- <link href="isis-layout.css" rel="stylesheet">
- <!--<link href="isis-layout-show-facets.css" rel="stylesheet">-->
-</head>
- <body>
- <div class="container">
- <h1>colspans={4,4,4,12}</h1>
- <div class="row">
- <div class="col-md-12">
- <div class="isis-header">
- <span class="isis-title">Buy bread</span>
- <div class="isis-actions">
- <div class="isis-action x-caution">
- <span>delete</span>
- </div>
- <div class="isis-action">
- <span data-isis-id="duplicate">clone</span>
- <ul class="isis-facets">
- <li>describedAs.value="Create a new todo item from this one"</li>
- </ul>
- </div>
- <div class="isis-action">
- <span>recentChanges</span>
- </div>
- <div class="isis-action">
- <span>recentChanges</span>
- </div>
- </div>
- </div>
- </div>
- </div>
- <div class="row">
- <div class="col-md-4 isis-memberGroups">
- <fieldset class="isis-memberGroup min-height-100">
- <legend>General</legend>
- <div class="isis-property">
- <span data-isis-typicallength="50">description</span>
- <ul class="isis-facets">
- <li>typicalLength.value=50</li>
- </ul>
- </div>
- <div class="isis-property">
- <span>category</span>
- <ul class="isis-facets">
- <li>disabled.reason="Use action to update both category and subcategory"</li>
- </ul>
- </div>
- <div class="isis-property">
- <span>subcategory</span>
- <ul class="isis-facets">
- <li>disabled.reason="Use action to update both category and subcategory"</li>
- </ul>
- <div class="isis-actions">
- <div class="isis-action">
- <span data-isis-id="updateCategory">update</span>
- </div>
- <div class="isis-action">
- <span>analyseCategory</span>
- </div>
- </div>
- </div>
- <div class="isis-property">
- <span class="isis-hidden">ownedBy</span>
- </div>
- <div class="isis-property x-highlight">
- <span data-isis-id="complete">done</span>
- <div class="isis-actions">
- <div class="isis-action">
- <span data-isis-id="completed">done</span>
- <ul class="isis-facets">
- <li>describedAs.value="Mark this todo item as having been completed"</li>
- </ul>
- </div>
- <div class="isis-action">
- <span>scheduleExplicitly</span>
- </div>
- <div class="isis-action">
- <span>scheduleImplicitly</span>
- </div>
- <div class="isis-action">
- <span data-isis-id="notYetCompleted">not done</span>
- </div>
- </div>
- </div>
- </fieldset>
- </div>
- <div class="col-md-4 isis-memberGroups">
- <fieldset class="isis-memberGroup">
- <legend>Priority</legend>
- <div class="isis-property">
- <span>relativePriority</span>
- <div class="isis-actions">
- <div class="isis-action">
- <span>previous</span>
- </div>
- <div class="isis-action">
- <span>next</span>
- </div>
- </div>
- </div>
- <div class="isis-property x-key">
- <span>dueBy</span>
- </div>
- </fieldset>
- </div>
- <div class="col-md-4 isis-memberGroups">
- <fieldset class="isis-memberGroup">
- <legend>Other</legend>
- <div class="isis-property">
- <span>cost</span>
- <div class="isis-actions">
- <div class="isis-action">
- <span data-isis-id="updateCost">update</span>
- </div>
- </div>
- </div>
- <div class="isis-property">
- <span>notes</span>
- <ul class="isis-facets">
- <li>multiLine.numberOfLines=5</li>
- <li>hidden.where=ALL_TABLES</li>
- </ul>
- </div>
- <div class="isis-property">
- <span>attachment</span>
- <ul class="isis-facets">
- <li>hidden.where=ALL_TABLES</li>
- </ul>
- </div>
- </fieldset>
- <fieldset class="isis-memberGroup min-height-100">
- <legend>Misc</legend>
- <div class="isis-property">
- <span data-isis-id="versionSequence">version</span>
- <ul class="isis-facets">
- <li>disabled</li>
- <li>hidden.where=STANDALONE_TABLES</li>
- </ul>
- </div>
- </fieldset>
- </div>
- </div>
- <div class="row">
- <div class="col-md-12">
- <fieldset class="isis-collection min-height-100">
- <legend>dependencies</legend>
- <div class="isis-actions">
- <div class="isis-action">
- <span>add</span>
- </div>
- <div class="isis-action x-caution">
- <span>remove</span>
- </div>
- </div>
- <ul class="isis-facets">
- <li>disabled</li>
- <li>paged.value=5</li>
- <li>render.value=EAGERLY</li>
- </ul>
- </fieldset>
- <fieldset class="isis-collection min-height-200">
- <legend>similarTo</legend>
- <ul class="isis-facets">
- <li>disabled</li>
- <li>paged.value=3</li>
- <li>render.value=LAZILY</li>
- </ul>
- </fieldset>
- </div>
- </div>
- </div>
-
- <!-- jQuery (necessary for Bootstrap's JavaScript plugins) -->
- <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.0/jquery.min.js"></script>
- <!-- Include all compiled plugins (below), or include individual files as needed -->
- <script src="js/bootstrap.min.js"></script>
- <script>
- $(document).ready(function () {
- });
- </script>
- </body>
-</html>
\ No newline at end of file