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/05/18 08:26:43 UTC
[01/22] isis git commit: ISIS-1133: renamed _user-guide_ to _ug_
Repository: isis
Updated Branches:
refs/heads/master 332988f74 -> 840487684
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_features.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_features.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_features.adoc
deleted file mode 100644
index ca7c501..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_features.adoc
+++ /dev/null
@@ -1,458 +0,0 @@
-= 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.
-
-
-
-== Titles in Tables
-
-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 <<_abbreviating_suppressing_titles_in_tables, abbreviate titles or suppress them>> completely.
-====
-
-
-
-== File upload/download
-
-The Isis application library provides the <<_blob, Blob>> value type (binary large objects) and also the <<_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):
-
-[NOTE]
-====
-TODO: these screenshots need to be updated for the new look-n-feel introduced in 1.8.0
-====
-
-==== 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"]
-
-==== 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.
-
-
-
-
-== Bookmarked pages
-
-The Wicket viewer supports the bookmarking of both domain objects and query-only (<<_actionsemantics, @ActionSemantics>>) 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]
-====
-TODO: this screenshot need to be updated for the new look-n-feel introduced in 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"]
-
-[NOTE]
-====
-TODO: this screenshot need to be updated for the new look-n-feel introduced in 1.8.0
-====
-
-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 <<_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 <<_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 <<_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
-----
-
-
-
-== Recent pages (drop down)
-
-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]
-====
-TODO: this screenshot need to be updated for the new look-n-feel introduced in 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 <<_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.
-
-
-
-
-
-== Hints and copy URL
-
-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.
-
-[NOTE]
-====
-TODO: these screenshots need to be updated for the new look-n-feel introduced in 1.8.0
-====
-
-==== 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"]
-
-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.
-
-
-
-
-
-
-
-== User Registration
-
-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 <<_user_registration_service, user registration service>>, which provides an API to create the user account
-* the <<_email_notification_service, email notification service>>, which provides an API for to send the verification emails
-* the <<_email_service, 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 <<_user_registration_service, user registration service>> (eg by using the https://github.com/isisaddons/isis-module-security[Isis addons security module])
-
-* configure the <<_email_service, 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 <<_suppressing_sign_up, the sign-up page link>> and/or the <<_suppressing_password_reset, password reset page>>.
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_isis-addons.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_isis-addons.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_isis-addons.adoc
deleted file mode 100644
index 47eb472..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_isis-addons.adoc
+++ /dev/null
@@ -1,32 +0,0 @@
-= 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 http://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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_layout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_layout.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_layout.adoc
deleted file mode 100644
index a5b4c6c..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_layout.adoc
+++ /dev/null
@@ -1,31 +0,0 @@
-= 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 section describes how this is done both for domain objects -- statically or dynamically -- and for the application menu bar (containing domain service' actions).
-
-include::_user-guide_wicket-viewer_layout_static-object-layout.adoc[leveloffset=+1]
-
-include::_user-guide_wicket-viewer_layout_dynamic-object-layout.adoc[leveloffset=+1]
-
-include::_user-guide_wicket-viewer_layout_application-menu-layout.adoc[leveloffset=+1]
-
-
-
-== Static vs Dynamic Layouts
-
-Using <<_dynamic_object_layout, 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 <<_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 (third-party) http://github.com/isisaddons/isis-jrebel-plugin}[Isis addons' jrebel] plugin (non-ASF) 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.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_layout_application-menu-layout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_layout_application-menu-layout.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_layout_application-menu-layout.adoc
deleted file mode 100644
index 88ccc3a..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_layout_application-menu-layout.adoc
+++ /dev/null
@@ -1,170 +0,0 @@
-= 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 Isis add-ons 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 <<_vetoing_visibility, vetoing subscriber>>.
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_layout_dynamic-object-layout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_layout_dynamic-object-layout.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_layout_dynamic-object-layout.adoc
deleted file mode 100644
index 03148b8..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_layout_dynamic-object-layout.adoc
+++ /dev/null
@@ -1,160 +0,0 @@
-= 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/
-
-
-Because Isis implements the http://en.wikipedia.org/wiki/Naked_objects[naked objects pattern], the domain objects are rendered in the UI based only metadata gleaned from the domain classes themselves. Traditionally this metadata has been specified statically, using annotations such as <<_memberorder, `@MemberOrder`>> and <<_membergrouplayout, `@MemberGroupLayout`>>. However, it is also possible to specify the layout data using a JSON file. This brings the advantage that the layout can be refreshed dynamically, without recompiling/redeploying the app.
-
-== Screencast
-
-How to layout properties and collections dynamically, in the Wicket viewer.
-
-video::zmrg49WeEPc[youtube,width="530px",height="354px"]
-
-
-
-== 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 <<_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 http://github.com/isisaddons/isis-module-devutils}[Isis addons' devutils] module (non-ASF) to download the layout file (derived from any existing static metadata defined by annotations).
-
-
-
-== Picking up new metadata
-
-When running in <<_deployment_types, prototype (development) mode>>, the Wicket viewer automatically rebuilds the metamodel for each class as it is rendered.
-
-[NOTE]
-====
-Conversely, do note that the Wicket viewer will _not_ pick up new metadata if running in production/server mode.
-====
-
-
-
-== 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 link:../../../intro/getting-started/simple-archetype.html[archetype], then the POM is already correctly configured.
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_layout_static-object-layout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_layout_static-object-layout.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_layout_static-object-layout.adoc
deleted file mode 100644
index 7fbd783..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_layout_static-object-layout.adoc
+++ /dev/null
@@ -1,166 +0,0 @@
-= 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/
-
-
-Because Isis implements the http://en.wikipedia.org/wiki/Naked_objects[naked objects pattern], the domain objects are rendered in the UI based only metadata gleaned from the domain classes themselves. Traditionally this metadata has been specified statically using annotations.
-
-
-== `@MemberOrder`
-
-To specify the relative order of domain class properties and classes, the `@MemberOrder` annotation is used.
-
-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(sequence="1")
- public SortedSet<ToDoItem> getDependencies() { ... }
-
- // actions ...
- @MemberOrder(name="complete", sequence="1")
- public ToDoItem completed() { ...}
-
- @MemberOrder(name="complete", sequence="2")
- public ToDoItem notYetCompleted() { ...}
-
- // more actions ...
- @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.
-
-If the `name` attribute is omitted, then the action is rendered near the header. Note also that the `@MemberOrder`'s `name` attribute has no meaning for collections.
-
-== `@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. It also specifies the relative width.
-
-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 http://twitter.github.io/bootstrap/[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}wicket-viewer/layouts/6-6-0-12.png[width="720px",link="{_imagesdir}wicket-viewer/layouts/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}wicket-viewer/layouts/4-4-4-12.png[width="720px",link="{_imagesdir}wicket-viewer/layouts/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}wicket-viewer/layouts/4-0-8-0.png[width="720px",link="{_imagesdir}wicket-viewer/layouts/4-0-8-0.png"]
-
-
-== Other Annotations
-
-As of 1.8.0, all the layout annotations have been consolidated into the various `XxxLayout` annotations:
-
-* <<_domainservicelayout, `@DomainServiceLayout`>>
-* <<_domainobjectlayout, `@DomainObjectLayout`>>
-* <<_viewmodellayout, `@ViewModelLayout`>>
-* <<_propertylayout, `@PropertyLayout`>>
-* <<_collectionlayout, `@CollectionLayout`>>
-* <<_actionlayout, `@ActionLayout`>>
-* <<_parameterlayout, `@ParameterLayout`>>
-
-Prior to 1.8.0 a variety of annotations (now deprecated) are available, including:
-
-* <<_named, `@Named`>>
-* <<_describedas, `@DescribedAs`>>
-* <<_multiline, `@MultiLine`>>
-* <<_typicallength, `@TypicalLength`>>
-* <<_render, `@Render`>>
-* <<_cssclass, `@CssClass`>>
-* <<_cssclassfa, `@CssClassFa`>>
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_request-parameters.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_request-parameters.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_request-parameters.adoc
deleted file mode 100644
index 12f843c..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_request-parameters.adoc
+++ /dev/null
@@ -1,52 +0,0 @@
-= 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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_xxx.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_xxx.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_xxx.adoc
deleted file mode 100644
index e69de29..0000000
[12/22] isis git commit: ISIS-1133: renamed _user-guide_ to _ug_
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..b2d1ba2
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_fixture-scripts_api-and-usage.adoc
@@ -0,0 +1,285 @@
+= 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 <<_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 <<_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 <<_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 <<_wrapper_factory, `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 <<_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 <<_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 <<_fixturescripts, `FixtureScripts`>> 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 <<_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/97531ca0/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
new file mode 100644
index 0000000..dea52eb
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_fixture-scripts_sudo-service.adoc
@@ -0,0 +1,58 @@
+= SudoService (1.9.0-SNAPSHOT)
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+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/97531ca0/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
new file mode 100644
index 0000000..f4d4cab
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support.adoc
@@ -0,0 +1,23 @@
+= 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::_user-guide_testing_integ-test-support_typical-usage.adoc[leveloffset=+1]
+include::_user-guide_testing_integ-test-support_bootstrapping.adoc[leveloffset=+1]
+include::_user-guide_testing_integ-test-support_wrapper-factory.adoc[leveloffset=+1]
+include::_user-guide_testing_integ-test-support_maven-configuration.adoc[leveloffset=+1]
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..c987e58
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_bootstrapping.adoc
@@ -0,0 +1,230 @@
+= 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 <<_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 <<_isisconfigurationforjdointegtests, 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 <<_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 <<_i18n_support, 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/97531ca0/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
new file mode 100644
index 0000000..609c52b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_maven-configuration.adoc
@@ -0,0 +1,45 @@
+= 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 <<_simpleapp_archetype, SimpleApp archetype>>. To set it up manually, update the `pom.xml` of your domain object model module:
+
+[source]
+----
+<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/97531ca0/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
new file mode 100644
index 0000000..1f2dd0b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_typical-usage.adoc
@@ -0,0 +1,123 @@
+= 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 <<_fixture_scripts, `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:assertj.org[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/97531ca0/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
new file mode 100644
index 0000000..e1f0d74
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_wrapper-factory.adoc
@@ -0,0 +1,161 @@
+= 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 `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: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 <<_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 <<__code_EventBusService_code, `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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_overview.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_overview.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_overview.adoc
new file mode 100644
index 0000000..790c8bc
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_overview.adoc
@@ -0,0 +1,165 @@
+= 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://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 <<_wrapper_factory, `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 <<_fixture_scripts, 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/97531ca0/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
new file mode 100644
index 0000000..2f02863
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_unit-test-support.adoc
@@ -0,0 +1,12 @@
+= 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::_user-guide_testing_unit-test-support_contract-tests.adoc[leveloffset=+1]
+include::_user-guide_testing_unit-test-support_jmock-extensions.adoc[leveloffset=+1]
+include::_user-guide_testing_unit-test-support_maven-configuration.adoc[leveloffset=+1]
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..0de8cfd
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_unit-test-support_contract-tests.adoc
@@ -0,0 +1,169 @@
+= 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 link:../more-advanced-topics/how-to-04-060-How-to-set-up-and-maintain-bidirectional-relationships.html[mutual registration pattern]
+
+TIP: If using the link:../components/objectstores/jdo/about.html[JDO Object Store], then there is generally no need to programmatically maintain 1:m relationships (indeed it may introduce subtle errors). For more details, see link:../components/objectstores/jdo/managed-1-to-m-relationships.html[here]. Check out the link:../intro/resources/editor-templates.html[Eclipse 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 {
+ protected ClockService clockService;
+ public void injectClockService(ClockService clockService) {
+ this.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/97531ca0/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
new file mode 100644
index 0000000..c58dcc3
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_unit-test-support_jmock-extensions.adoc
@@ -0,0 +1,58 @@
+= 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://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.csg.ci.i.u-tokyo.ac.jp/~chiba/javassist/[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/97531ca0/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
new file mode 100644
index 0000000..26f00ed
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_unit-test-support_maven-configuration.adoc
@@ -0,0 +1,45 @@
+= 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 <<_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/97531ca0/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
new file mode 100644
index 0000000..fd42f26
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_troubleshooting.adoc
@@ -0,0 +1,13 @@
+= Trouble Shooting
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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::_user-guide_troubleshooting_enabling-logging.adoc[leveloffset=+1]
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..533273c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_troubleshooting_enabling-logging.adoc
@@ -0,0 +1,38 @@
+= 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 <<_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/97531ca0/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
new file mode 100644
index 0000000..3c5efb0
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer.adoc
@@ -0,0 +1,29 @@
+= 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::_user-guide_wicket-viewer_features.adoc[leveloffset=+1]
+
+include::_user-guide_wicket-viewer_configuration_properties.adoc[leveloffset=+1]
+
+include::_user-guide_wicket-viewer_request-parameters.adoc[leveloffset=+1]
+
+include::_user-guide_wicket-viewer_layout.adoc[leveloffset=+1]
+
+include::_user-guide_wicket-viewer_customisation.adoc[leveloffset=+1]
+
+
+
+== Extending the viewer
+
+APIs to extend the Wicket viewer are discussed in the <<_extending_the_wicket_viewer, Extending>> chapter.
+
+
+include::_user-guide_wicket-viewer_isis-addons.adoc[leveloffset=+1]
+
[17/22] isis git commit: ISIS-1133: renamed _user-guide_ to _ug_
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..54517f8
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_crud.adoc
@@ -0,0 +1,22 @@
+= Object Management (CRUD)
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+IMPORTANT: TODO
+
+## Injecting Services
+
+## Instantiating and Persisting Objects
+
+## Finding Objects
+
+### Using DataNucleus type-safe queries
+
+as per http://github.com/isisaddons/isis-app-todoapp}[Isis addons' todoapp] (non-ASF)
+
+## Deleting Objects
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..c0e8e8e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_derived-members.adoc
@@ -0,0 +1,33 @@
+= Derived Members
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+IMPORTANT: TODO
+
+## Derived Property
+
+## Derived Collection
+
+
+.Inlining query-only repository action
+****
+While derived properties and derived collections typically "walk the graph" to associated objects, there is nothing to prevent the returned value being the result of invoking a repository (domain service) action.
+
+For example:
+
+[source,java]
+----
+public class Customer {
+ ...
+ public List<Order> getMostRecentOrders() {
+ return orderRepo.findMostRecentOrders(this, 5);
+ }
+}
+----
+****
+
+## Trigger on property change
+
+## Trigger on collection change
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..ef7e4ad
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_domain-services.adoc
@@ -0,0 +1,23 @@
+= 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/
+
+IMPORTANT: TODO
+
+
+
+## Singleton & request-scoped services
+
+IMPORTANT: TODO
+
+
+It's worth extending the <<_hexagonal_architecture, Hexagonal Architecture> to show where domain services -- and in particular the domain services provided by http://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 a number of in-built domain services.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..643c705
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_drop-downs-and-defaults.adoc
@@ -0,0 +1,30 @@
+= Drop Downs and Defaults
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+IMPORTANT: TODO
+
+## For Properties
+
+### Choices for Property
+
+### Auto-complete for property
+
+### Default for property
+
+## For Action Parameters
+
+### Choices for action parameter
+
+### Dependent choices for action params
+
+### Auto-complete for action param
+
+### Default for action param
+
+## For both Properties and Action Parameters
+
+### Drop-down for limited number of instances
+
+### Auto-complete (repository-based)
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..b7f7d7f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_entity-relationships.adoc
@@ -0,0 +1,11 @@
+= Entity Relationships
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+IMPORTANT: TODO
+
+## Mapping Mandatory and Optional Properties
+
+## Managed 1-m bidirectional relationships
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..f8e6e1a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_ui-hints.adoc
@@ -0,0 +1,17 @@
+= 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/
+
+IMPORTANT: TODO
+
+include::_user-guide_how-tos_ui-hints_object-titles-and-icons.adoc[leveloffset=+1]
+
+include::_user-guide_how-tos_ui-hints_names-and-descriptions.adoc[leveloffset=+1]
+
+include::_user-guide_how-tos_ui-hints_layout.adoc[leveloffset=+1]
+
+include::_user-guide_how-tos_ui-hints_eager-rendering.adoc[leveloffset=+1]
+
+include::_user-guide_how-tos_ui-hints_action-icons-and-css.adoc[leveloffset=+1]
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..a2db15e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_ui-hints_action-icons-and-css.adoc
@@ -0,0 +1,60 @@
+= 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: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: TODO - more words here...
+
+* `@CssClassFa`
+* `@CssClass`
+
+Alternatively, you can specify these hints in the `Xxx.layout.json` for the entity:
+
+IMPORTANT: TODO
+
+
+== Per pattern matching
+
+Rather than annotating every action with `@CssClassFa` and `@CssClass`, you can instead specify the UI hint globally using regular expressions.
+
+The `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: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 `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 `@CssClassFa` or `@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/97531ca0/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
new file mode 100644
index 0000000..1636aac
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_ui-hints_eager-rendering.adoc
@@ -0,0 +1,57 @@
+= 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/97531ca0/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
new file mode 100644
index 0000000..8f8bdcf
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_ui-hints_layout.adoc
@@ -0,0 +1,14 @@
+= 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/
+
+IMPORTANT: TODO
+
+
+== Layout using annotations
+
+== Dynamic layouts
+
+== Application menu layout
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..04ab662
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_ui-hints_names-and-descriptions.adoc
@@ -0,0 +1,41 @@
+= 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 <<_i18n, Internationalization>>
+
+== Class (object)
+
+IMPORTANT: TODO
+
+== Property
+
+IMPORTANT: TODO
+
+== Collections
+
+IMPORTANT: TODO
+
+== Actions
+
+IMPORTANT: TODO
+
+== Action Parameters
+
+IMPORTANT: WIP
+
+Use `@ParameterLayout(named=...)` or `@Named(...)`
+
+[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 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 <<_upgrading_to_java_8_1_9_0_snapshot_and_later,upgrading to Java 8>>.
+====
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..7b3260f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_ui-hints_object-titles-and-icons.adoc
@@ -0,0 +1,94 @@
+= 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 <<_object_title, title>> (label) and an <<_object_icon, 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 return a <<_object_css_styling, CSS class>>. In conjunction with <<_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 `@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. See <<_titles_in_tables, here>> for further discussion.
+====
+
+
+=== Imperative style
+
+IMPORTANT: TODO
+
+
+
+
+== 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
+
+
+== Object CSS Styling
+
+
+It is also possible for an object to return a <<_object_css_styling, CSS class>>. In conjunction with <<_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
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_isis-addons-modules.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_isis-addons-modules.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_isis-addons-modules.adoc
new file mode 100644
index 0000000..7a90efe
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_isis-addons-modules.adoc
@@ -0,0 +1,115 @@
+= Isis Addons Modules (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 http://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-auditing}[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.
+
+== Command Service (persistence)
+
+IMPORTANT: TODO
+
+=== API
+=== Isis addons implementation
+
+
+
+== Background Command Service
+
+IMPORTANT: TODO
+
+=== API
+=== Background Execution
+=== Isis addons implementation
+
+
+
+== Auditing
+
+IMPORTANT: TODO
+
+=== Auditing API
+=== Isis addons implementation
+
+
+
+
+== Publishing Service
+
+IMPORTANT: TODO
+
+=== API
+=== Isis addons implementation
+
+
+=== Event Serializer
+
+Isis' PublishingService API also has a companion API, the `EventSerializer`. This provides a pluggable mechanism by which the event can be rendered into different formats.
+
+The http://github.com/isisaddons/isis-module-publishing}[Isis addons' publishing] module provides an implementation of this API -- `RestfulObjectsSpecEventSerializer` -- that reuses part of the implementation of the Restful Objects viewer to serialize the the provided `EventPayload` into the form specified by the http://restfulobjects.org[Restful Objects spec].
+
+For example, this is the JSON generated on an action invocation:
+
+.JSON generated by action invocation
+image::{_imagesdir}isis-addons-modules/action-invocation-published-to-stderr.png[width="750px"]
+
+while this is the object change JSON:
+
+.JSON generated by action invocation
+image::{_imagesdir}isis-addons-modules/changed-object-published-to-stderr.png[width="750px"]
+
+You could if you wish change the representation by registering your own implementation of this API in `isis.properties`:
+
+[source,ini]
+----
+isis.services=...\
+ com.mycompany.myapp.MyEventSerializer,\
+ ...
+----
+
+
+
+== Security
+
+IMPORTANT: TODO
+
+
+
+== Other Isis Addons
+
+IMPORTANT: TODO
+
+=== Developer Utilities
+=== Docx Mail merge
+=== Excel download/upload
+=== Fake Data
+=== Poly
+=== Session Logger
+=== Settings
+=== String interpolator
+=== Tags
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..dc62e39
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced.adoc
@@ -0,0 +1,32 @@
+= 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/
+
+IMPORTANT: TODO
+
+
+include::_user-guide_more-advanced_decoupling.adoc[leveloffset=+1]
+
+include::_user-guide_more-advanced_assembling.adoc[leveloffset=+1]
+
+include::_user-guide_more-advanced_bulk-actions.adoc[leveloffset=+1]
+
+include::_user-guide_more-advanced_view-models.adoc[leveloffset=+1]
+
+include::_user-guide_more-advanced_transactions-and-errors.adoc[leveloffset=+1]
+
+include::_user-guide_more-advanced_i18n.adoc[leveloffset=+1]
+
+include::_user-guide_more-advanced_multi-tenancy.adoc[leveloffset=+1]
+
+include::_user-guide_more-advanced_persistence-lifecycle.adoc[leveloffset=+1]
+
+include::_user-guide_more-advanced_neo4j.adoc[leveloffset=+1]
+
+include::_user-guide_more-advanced_tips-n-tricks.adoc[leveloffset=+1]
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_assembling.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_assembling.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_assembling.adoc
new file mode 100644
index 0000000..ce73737
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_assembling.adoc
@@ -0,0 +1,63 @@
+= Assembling
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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
+
+
+
+== Vetoing Visibility
+
+
+
+
+
+== Overriding JDO Annotations
+
+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 <<_using_modules, using modules>>.
+====
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..9b83333
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_bulk-actions.adoc
@@ -0,0 +1,8 @@
+= 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
+
+ie `@Action(invokeOn=...)`
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..cdcaf84
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_decoupling.adoc
@@ -0,0 +1,25 @@
+= 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 <<_assembling, following section>> describes 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::_user-guide_more-advanced_decoupling_db-schemas.adoc[leveloffset=+1]
+
+include::_user-guide_more-advanced_decoupling_contributions.adoc[leveloffset=+1]
+
+include::_user-guide_more-advanced_decoupling_event-bus.adoc[leveloffset=+1]
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..f91e759
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_decoupling_contributions.adoc
@@ -0,0 +1,7 @@
+= 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/97531ca0/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
new file mode 100644
index 0000000..d341854
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_decoupling_db-schemas.adoc
@@ -0,0 +1,152 @@
+= 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 http://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 <<_overriding_jdo_annotations, Overriding Annotations>> for a write-up of how to do this.
+====
+
+
+
+
+== Listener to create DB schema objects
+
+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]
+----
+package org.apache.isis.objectstore.jdo.datanucleus;
+
+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).
+
+
+
+== Registering an Alternative Implementation
+
+An alternative implementation can be registered and used through the following configuration property:
+
+[source,ini]
+----
+#
+# hook to perform additional initialization when JDO class metadata is loaded
+# default implementation will attempt to run 'create schema' for the specified schema.
+#
+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/97531ca0/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
new file mode 100644
index 0000000..5dda011
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_decoupling_event-bus.adoc
@@ -0,0 +1,136 @@
+= 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
+
+## Publishing and Subscribing to Events (Pulling Changes)
+
+
+
+## Pushing Changes
+
+NOTE: this technique is much less powerful than the event bus described in <<Publishing and Subscribing to Events (Pulling Changes)>>). 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 added to or removed from
+
+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; // <1>
+
+ 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) {
+ numMaleEmployees += countOneMale(employee); // <2>
+ numFemaleEmployees += countOneFemale(employee); // <2>
+ employees.add(employee);
+ }
+ public void removeFromEmployees(Employee employee) {
+ numMaleEmployees -= countOneMale(employee); // <3>
+ numFemaleEmployees -= countOneFemale(employee); // <3>
+ 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 and female employees (getters and setters omitted)
+<2> the `addTo...()` method increments the derived properties
+<3> the `removeTo...()` method similarly decrements the derived properties
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..a9c3292
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_i18n.adoc
@@ -0,0 +1,606 @@
+= 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/a/14327683/56880[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.
+
+
+
+
+== Service API and Implementation
+
+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` (implementation)
+
+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 <<_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 <<_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.
+
+== Translating validation and other (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 <<_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 <<_domain_object_container, `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 <<_exception_recognizer, `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 <<_integration_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 <<_exception_recognizer, ``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 link:../reference/externalized-configuration.html[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]
+----
+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.
+
+
+
+
+== Migrating from v1.6.0 to 1.7.0
+
+In v1.7.0 we've continued the work started in link:migrating-to-1.6.0.html[1.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]
+----
+<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/97531ca0/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
new file mode 100644
index 0000000..4f99008
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_multi-tenancy.adoc
@@ -0,0 +1,7 @@
+= Multi-tenancy
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+IMPORTANT: TODO
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_neo4j.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_neo4j.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_neo4j.adoc
new file mode 100644
index 0000000..95d27a7
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_neo4j.adoc
@@ -0,0 +1,58 @@
+= 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 <<_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 <<_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 <<_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/97531ca0/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
new file mode 100644
index 0000000..5226979
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_persistence-lifecycle.adoc
@@ -0,0 +1,7 @@
+= 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/97531ca0/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
new file mode 100644
index 0000000..c555440
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_tips-n-tricks.adoc
@@ -0,0 +1,20 @@
+= 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/
+
+IMPORTANT: TODO
+
+
+include::_user-guide_more-advanced_tips-n-tricks_are-you-sure.adoc[leveloffset=+1]
+
+include::_user-guide_more-advanced_tips-n-tricks_simulating-collections-of-values.adoc[leveloffset=+1]
+
+include::_user-guide_more-advanced_tips-n-tricks_render-all-properties-in-tables.adoc[leveloffset=+1]
+
+include::_user-guide_more-advanced_tips-n-tricks_per-user-themes.adoc[leveloffset=+1]
+
+include::_user-guide_more-advanced_tips-n-tricks_suppress-actions-from-the-ui.adoc[leveloffset=+1]
+
+include::_user-guide_more-advanced_tips-n-tricks_enhance-only.adoc[leveloffset=+1]
+
[18/22] isis git commit: ISIS-1133: renamed _user-guide_ to _ug_
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..3030665
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_programming-model_finetuning.adoc
@@ -0,0 +1,79 @@
+= 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 Programming 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.
+
+=== Fine-tuning the existing programming model
+
+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 <<_multi_tenancy, Multi-Tenancy>> is now a better solution to that particular use-case.
+====
+
+
+
+
+== Specifying a new programming 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/97531ca0/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
new file mode 100644
index 0000000..b431d78
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_programming-model_layout-metadata-reader.adoc
@@ -0,0 +1,43 @@
+= 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 <<_static_object_layout, statically>> and <<_dynamic_object_layout, 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/97531ca0/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
new file mode 100644
index 0000000..1cb2164
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_restfulobjects-viewer.adoc
@@ -0,0 +1,120 @@
+= Extending the Restful 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 Restful Objects viewer implements the http://restfulobjects.org[Restful Object spec], meaning that it:
+
+* defines a well-defined set of endpoint URLs as resources
+* generates a well-defined set of (JSON) representations when these resources are accessed.
+
+There are, however, a number of other "standards" for defining representations, among these:
+
+* 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)
+* 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].
+
+While Isis' Restful Objects viewer only has "out-of-the-box" support for the representations defined in the Restful Objects spec,
+it is possible to plugin a custom representation generator that can produce any arbitrary representation.
+
+[TIP]
+====
+If all that is required is a very simple representations (of objects), you can instead reconfigure RO viewer to provide a simplified output, as described <<_simplified_object_representation, here>>. Or, it is also possible to simply suppress certain elements, as described <<_suppressing_elements_of_the_representations, here>>.
+====
+
+
+== API
+
+The API to implement is the `RepresentationService` API:
+
+[WARNING]
+====
+This API should be considered beta, as it may change in the future in response to emerging requirements
+====
+
+[source,java]
+----
+import javax.ws.rs.core.Response;
+import org.apache.isis.applib.annotation.Programmatic;
+import org.apache.isis.core.metamodel.adapter.ObjectAdapter;
+import org.apache.isis.viewer.restfulobjects.rendering.RendererContext;
+import org.apache.isis.viewer.restfulobjects.rendering.domainobjects.*;
+
+public interface RepresentationService {
+
+ @Programmatic
+ Response objectRepresentation(
+ Context rendererContext,
+ ObjectAdapter objectAdapter);
+
+ @Programmatic
+ Response propertyDetails(
+ Context rendererContext,
+ ObjectAndProperty objectAndProperty,
+ MemberReprMode memberReprMode);
+
+ @Programmatic
+ Response collectionDetails(
+ Context rendererContext,
+ ObjectAndCollection objectAndCollection,
+ MemberReprMode memberReprMode);
+
+ @Programmatic
+ Response actionPrompt(
+ Context rendererContext,
+ ObjectAndAction objectAndAction);
+
+ @Programmatic
+ Response actionResult(
+ Context rendererContext,
+ ObjectAndActionInvocation objectAndActionInvocation,
+ ActionResultReprRenderer.SelfLink selfLink);
+
+ public static interface Context extends RendererContext {
+ ObjectAdapterLinkTo getAdapterLinkTo();
+ }
+}
+----
+
+
+== Default Implementation
+
+Restful Objects' out-of-the-box support for Restful Objects spec uses this same API, specifically `RepresentationServiceForRestfulObjects` (in the `org.apache.isis.viewer.restfulobjects.rendering.service` package).
+
+Each of these methods provides:
+
+* a `RendererContext` +
++
+providing 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`
+
+
+== Configuring your Implementation
+
+Implement the service and register in `WEB-INF/isis.properties`, eg:
+
+[source,ini]
+----
+isis.services=...,\
+ com.mycompany.myservice.RepresentationServiceForMyRestApi,
+ ...
+----
+
+This will replace the default implementatoin.
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..71f49e3
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_wicket-viewer.adoc
@@ -0,0 +1,25 @@
+= Extending the 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 <<_tweak_the_ui_with_css, tweaking the UI using CSS>>
+* by <<_tweak_the_ui_with_javascript, tweaking the UI using Javascript>>
+* by writing a <<_writing_a_custom_theme, custom bootstrap theme>>
+* by <<_replacing_page_elements, replacing elements of the page>> using the `ComponentFactory` interface
+* by implementing <<_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::_user-guide_extending_wicket-viewer_custom-bootstrap-theme.adoc[leveloffset=+1]
+
+include::_user-guide_extending_wicket-viewer_replacing-page-elements.adoc[leveloffset=+1]
+
+include::_user-guide_extending_wicket-viewer_custom-pages.adoc[leveloffset=+1]
+
+include::_user-guide_extending_wicket-viewer_isis-addons-extensions.adoc[leveloffset=+1]
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..72b13d7
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_wicket-viewer_custom-bootstrap-theme.adoc
@@ -0,0 +1,33 @@
+= 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 <<_showing_a_theme_chooser, select other themes>> provided by http://bootswatch.com[bootswatch.com], and if required one of these can be <<_specifying_a_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/97531ca0/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
new file mode 100644
index 0000000..de8aab4
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_wicket-viewer_custom-pages.adoc
@@ -0,0 +1,91 @@
+= 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 link:./customizing-the-viewer.html[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 <<_user_registration, user registration>> is enabled).
+
+| SIGN_UP_VERIFY
+| The sign-up verification page (if <<_user_registration, 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/97531ca0/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
new file mode 100644
index 0000000..6ef681b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_wicket-viewer_isis-addons-extensions.adoc
@@ -0,0 +1,16 @@
+= 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/97531ca0/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
new file mode 100644
index 0000000..4462152
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_wicket-viewer_replacing-page-elements.adoc
@@ -0,0 +1,159 @@
+= 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 http://www.isisaddons.org[Isis Add-ons] include the link:isisaddons/isis-wicket-gmap3.html[gmap3], link:isisaddons/isis-wicket-fullcalendar2.html[calendar], link:isisaddons/isis-wicket-excel.html[excel download] and link:isisaddons/isis-wicket-wickedcharts.html[charting] integrations.
+
+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 Wicket 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.
+
+
+
+
+== Adding a Custom Object View (eg a 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/97531ca0/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
new file mode 100644
index 0000000..c260365
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_getting-started.adoc
@@ -0,0 +1,11 @@
+= Getting Started
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+IMPORTANT: TODO
+
+include::_user-guide_getting-started_simpleapp-archetype.adoc[leveloffset=+1]
+
+include::_user-guide_getting-started_datanucleus-enhancer.adoc[leveloffset=+1]
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..a015a4e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_getting-started_datanucleus-enhancer.adoc
@@ -0,0 +1,87 @@
+= 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/
+
+
+By leveraging the JDO/Datanucleus ORM, Isis' JDO objectstore is very powerful. However, with such power comes a little bit of complexity to the development environment: all domain objects must be enhanced through the http://db.apache.org/jdo/enhancement.html[JDO enhancer]. So the enhancer must, in 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:
+
+[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 <<SimpleApp Archetype>> sets up the plugin correctly in the `dom` (domain object model) module. (It's actually a little bit more complext 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 <<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 <<Setting up Eclipse,here>>.
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..1decbc9
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_getting-started_simpleapp-archetype.adoc
@@ -0,0 +1,7 @@
+= SimpleApp Archetype
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+IMPORTANT: TODO
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..8ac1008
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_headless-access.adoc
@@ -0,0 +1,114 @@
+= 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 <<_wicket_viewer, Wicket>> or <<_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 <<_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.
+
+
+== AbstractIsisSessionTemplate
+
+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.
+====
+
+
+
+== BackgroundCommandExecution
+
+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 shows the dependencies between these various classes:
+
+.Inheritance Hierarchy for `BackgroundCommandExecution`
+image::{_imagesdir}headless-access/BackgroundCommandExecution.png[width="400px"]
+
+[TIP]
+====
+[source]
+.DSL (http://yuml.me/edit/363b335f[yuml.me/363b335f])
+----
+[AbstractIsisSessionTemplate|#doExecute()]^-[BackgroundCommandExecution|#findBackgroundCommandsToExecute()]
+[BackgroundCommandExecution]^-[BackgroundCommandExecutionFromBackgroundCommandServiceJdo]
+[BackgroundCommandExecutionFromBackgroundCommandServiceJdo]->injected[BackgroundCommandServiceJdoRepository|findBackgroundCommandsNotYetStarted()]
+----
+
+====
+
+
+
+=== Background Execution using Isis Addons Command Module (not ASF)
+
+The `BackgroundCommandExecutionFromBackgroundCommandServiceJdo` is a concrete subclass of <<BackgroundCommandExecution>>, 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 http://isisaddons.org/isis-module-command[Isis addons Command Module]'s implementations of <<CommandService>> and <<BackgroundCommandService>> using the `BackgroundCommandServiceJdoRepository`.
+
+The diagram below shows the inheritance hierarchy for this class:
+
+.Inheritance Hierarchy for `BackgroundCommandExecutionFromBackgroundCommandServiceJdo`
+image::{_imagesdir}headless-access/BackgroundCommandExecutionFromBackgroundCommandServiceJdo.png[width="500px"]
+
+
+[TIP]
+====
+[source]
+.DSL (http://yuml.me/edit/25343da1[yuml.me/25343da1]):
+----
+[AbstractIsisSessionTemplate|#doExecute()]^-[BackgroundCommandExecution|#findBackgroundCommandsToExecute()]
+[BackgroundCommandExecution]->injected[BookmarkService|lookup()]
+[BackgroundCommandExecution]->injected[CommandContext|setCommand()]
+----
+
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..58e85d6
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos.adoc
@@ -0,0 +1,25 @@
+= Basics
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+IMPORTANT: TODO
+
+include::_user-guide_how-tos_class-structure.adoc[leveloffset=+1]
+
+include::_user-guide_how-tos_ui-hints.adoc[leveloffset=+1]
+
+include::_user-guide_how-tos_domain-services.adoc[leveloffset=+1]
+
+include::_user-guide_how-tos_crud.adoc[leveloffset=+1]
+
+include::_user-guide_how-tos_entity-relationships.adoc[leveloffset=+1]
+
+include::_user-guide_how-tos_contributed-members.adoc[leveloffset=+1]
+
+include::_user-guide_how-tos_business-rules.adoc[leveloffset=+1]
+
+include::_user-guide_how-tos_derived-members.adoc[leveloffset=+1]
+
+include::_user-guide_how-tos_drop-downs-and-defaults.adoc[leveloffset=+1]
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..c78f198
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_business-rules.adoc
@@ -0,0 +1,57 @@
+= Business Rules
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+IMPORTANT: TODO
+
+## Visibility ("see it")
+
+### Hide a Property
+
+### Hide a Collection
+
+### Hide an Action
+
+### Hide a Contributed Property, Collection or Action
+
+### All Members Hidden
+
+## Usability ("use it")
+
+### Disable a Property
+
+### Disable a Collection
+
+### Disable an Action
+
+### Disable a Contributed Property, Collection or Action
+
+### All Members Unmodifiable (Disabling the Edit Button)
+
+Sometimes an object is unmodifiable.
+
+In the Wicket viewer this means disabling the edit button.
+
+#### Declarative
+
+`@DomainObject(editing=...)`
+
+#### Imperative
+
+
+
+## Validity ("do it")
+
+### Validate (change to) a Property
+
+### Validate (adding or removing from) a Collection
+
+### Validate (arguments to invoke) an Action
+
+### Validating a Contributed Property, Collection or Action
+
+### Declarative validation using `@MustSatisfy`
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..e775741
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_class-structure.adoc
@@ -0,0 +1,39 @@
+= 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 <<_extending_the_programming_model, here>>.
+====
+
+
+include::_user-guide_how-tos_class-structure_class-definition.adoc[leveloffset=+1]
+
+include::_user-guide_how-tos_class-structure_properties.adoc[leveloffset=+1]
+
+include::_user-guide_how-tos_class-structure_collections.adoc[leveloffset=+1]
+
+include::_user-guide_how-tos_class-structure_actions.adoc[leveloffset=+1]
+
+include::_user-guide_how-tos_class-structure_action-parameters.adoc[leveloffset=+1]
+
+include::_user-guide_how-tos_class-structure_properties-vs-parameters.adoc[leveloffset=+1]
+
+include::_user-guide_how-tos_class-structure_ignoring-methods.adoc[leveloffset=+1]
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..cccf0fe
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_class-structure_action-parameters.adoc
@@ -0,0 +1,17 @@
+= 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 Length Of Action Parameter
+
+== BigDecimal Precision Of Action Parameter
+
+== Optional Action Argument
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..aa58f5a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_class-structure_actions.adoc
@@ -0,0 +1,18 @@
+= 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 <<_ignoring_methods, Ignoring Methods>>. This ensures that the collection is ignored by Isis.
+====
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..6744e73
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_class-structure_class-definition.adoc
@@ -0,0 +1,23 @@
+= 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: TODO
+
+
+Classes are defined both to Isis and (if any entity) also to JDO/DataNucleus.
+
+
+We use Java packages as a way to group related domain objects together; the package name forms a namespace. We can then reason about all the classes in that package/namespace as a single unit.
+
+In the same way that Java packages act as a namespace for domain objects, it's good practice to map domain entities to their own (database) schemas.
+
+[TIP]
+====
+For more on this topic, see <<_using_modules,Using Modules>>.
+====
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..a7ef399
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_class-structure_collections.adoc
@@ -0,0 +1,78 @@
+= 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: TODO
+
+
+[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 `@Programmatic`, as described in <<_ignoring_methods, Ignoring Methods>>. This ensures that the collection is ignored by Isis.
+
+Another workaround is to wrap each value in a view model, as explained in this <<_simulating_collections_of_values, tip>>.
+====
+
+
+
+== Managed 1-m bidirectional relationships
+
+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.
+
+[TIP]
+====
+The `modifyXxx()` and `clearXxx()` supporting methods were introduced in the framework primarily to help support implement the mutual registration pattern. This dates from
+====
+
+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/97531ca0/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
new file mode 100644
index 0000000..ee47a7d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_class-structure_ignoring-methods.adoc
@@ -0,0 +1,15 @@
+= 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: TODO
+
+
+Sometimes you want to define a `public` method on a domain object that is not intended to be rendered in Isis' UI.
+
+To exclude such methods, use the `@Programmatic` annotation.
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..374093c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_class-structure_properties-vs-parameters.adoc
@@ -0,0 +1,45 @@
+= 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: TODO
+
+
+
+In many cases the value types of properties and of action parameters align. For example, a `Customer` entity might have a `surname` property, and there might also be corresponding `changeSurname`. Ideally we want the surname property and surname action parameter to use the same value type.
+
+Having first-class support for this is a goal of 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/97531ca0/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
new file mode 100644
index 0000000..29d051c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_class-structure_properties.adoc
@@ -0,0 +1,282 @@
+= 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 <<_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]
+----
+@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)`.
+
+
+
+
+
+== Mapping String (Length)
+
+IMPORTANT: TODO
+
+
+
+
+
+== 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:
+
+
+
+
+== Mapping BigDecimals
+
+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 link:mapping-joda-dates.html[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/97531ca0/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
new file mode 100644
index 0000000..394cdfb
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos_contributed-members.adoc
@@ -0,0 +1,15 @@
+= Contributed Members
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+IMPORTANT: TODO
+
+## Contributed Action
+
+## Contributed Property
+
+## Contributed Collection
+
+
+
[20/22] isis git commit: ISIS-1133: renamed _user-guide_ to _ug_
Posted by da...@apache.org.
ISIS-1133: renamed _user-guide_ to _ug_
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/97531ca0
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/97531ca0
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/97531ca0
Branch: refs/heads/master
Commit: 97531ca08506ff5404d284c20930f46cc20a82f1
Parents: 332988f
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Mon May 18 07:19:41 2015 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Mon May 18 07:19:41 2015 +0100
----------------------------------------------------------------------
.../asciidoc/user-guide/_ug_appendices.adoc | 12 +
.../user-guide/_ug_appendices_dev-env.adoc | 14 +
.../_ug_appendices_dev-env_cmd-line.adoc | 8 +
.../_ug_appendices_dev-env_eclipse.adoc | 8 +
.../_ug_appendices_dev-env_intellij.adoc | 363 +++++++++++
...ug_appendices_dev-env_isis-maven-plugin.adoc | 8 +
.../_ug_appendices_migration-notes.adoc | 322 ++++++++++
.../_ug_appendices_release-notes.adoc | 126 ++++
.../asciidoc/user-guide/_ug_core-concepts.adoc | 24 +
.../user-guide/_ug_core-concepts_add-ons.adoc | 7 +
.../_ug_core-concepts_building-blocks.adoc | 237 ++++++++
...re-concepts_framework-provided-services.adoc | 84 +++
.../_ug_core-concepts_philosophy.adoc | 20 +
.../_ug_core-concepts_philosophy_aop.adoc | 35 ++
.../_ug_core-concepts_philosophy_dci.adoc | 8 +
...oncepts_philosophy_domain-driven-design.adoc | 79 +++
...cepts_philosophy_hexagonal-architecture.adoc | 28 +
..._core-concepts_philosophy_how-eases-ddd.adoc | 73 +++
...ncepts_philosophy_naked-objects-pattern.adoc | 54 ++
.../_ug_core-concepts_principles.adoc | 17 +
...core-concepts_principles_apache-isis-vs.adoc | 36 ++
...ug_core-concepts_principles_isis-itself.adoc | 46 ++
.../_ug_core-concepts_principles_your-apps.adoc | 38 ++
.../asciidoc/user-guide/_ug_deployment.adoc | 19 +
.../user-guide/_ug_deployment_cmd-line.adoc | 29 +
.../asciidoc/user-guide/_ug_deployment_gae.adoc | 459 ++++++++++++++
.../user-guide/_ug_deployment_jvm-flags.adoc | 18 +
.../user-guide/_ug_deployment_tomcat.adoc | 14 +
.../main/asciidoc/user-guide/_ug_extending.adoc | 13 +
.../_ug_extending_programming-model.adoc | 12 +
...ding_programming-model_custom-validator.adoc | 106 ++++
..._extending_programming-model_finetuning.adoc | 79 +++
...rogramming-model_layout-metadata-reader.adoc | 43 ++
.../_ug_extending_restfulobjects-viewer.adoc | 120 ++++
.../user-guide/_ug_extending_wicket-viewer.adoc | 25 +
...ng_wicket-viewer_custom-bootstrap-theme.adoc | 33 +
...ug_extending_wicket-viewer_custom-pages.adoc | 91 +++
...ng_wicket-viewer_isis-addons-extensions.adoc | 16 +
...g_wicket-viewer_replacing-page-elements.adoc | 159 +++++
.../user-guide/_ug_getting-started.adoc | 11 +
...ug_getting-started_datanucleus-enhancer.adoc | 87 +++
..._ug_getting-started_simpleapp-archetype.adoc | 7 +
.../user-guide/_ug_headless-access.adoc | 114 ++++
.../main/asciidoc/user-guide/_ug_how-tos.adoc | 25 +
.../user-guide/_ug_how-tos_business-rules.adoc | 57 ++
.../user-guide/_ug_how-tos_class-structure.adoc | 39 ++
...w-tos_class-structure_action-parameters.adoc | 17 +
.../_ug_how-tos_class-structure_actions.adoc | 18 +
...ow-tos_class-structure_class-definition.adoc | 23 +
..._ug_how-tos_class-structure_collections.adoc | 78 +++
...ow-tos_class-structure_ignoring-methods.adoc | 15 +
...lass-structure_properties-vs-parameters.adoc | 45 ++
.../_ug_how-tos_class-structure_properties.adoc | 282 +++++++++
.../_ug_how-tos_contributed-members.adoc | 15 +
.../asciidoc/user-guide/_ug_how-tos_crud.adoc | 22 +
.../user-guide/_ug_how-tos_derived-members.adoc | 33 +
.../user-guide/_ug_how-tos_domain-services.adoc | 23 +
.../_ug_how-tos_drop-downs-and-defaults.adoc | 30 +
.../_ug_how-tos_entity-relationships.adoc | 11 +
.../user-guide/_ug_how-tos_ui-hints.adoc | 17 +
...g_how-tos_ui-hints_action-icons-and-css.adoc | 60 ++
.../_ug_how-tos_ui-hints_eager-rendering.adoc | 57 ++
.../user-guide/_ug_how-tos_ui-hints_layout.adoc | 14 +
...how-tos_ui-hints_names-and-descriptions.adoc | 41 ++
...ow-tos_ui-hints_object-titles-and-icons.adoc | 94 +++
.../user-guide/_ug_isis-addons-modules.adoc | 115 ++++
.../asciidoc/user-guide/_ug_more-advanced.adoc | 32 +
.../_ug_more-advanced_assembling.adoc | 63 ++
.../_ug_more-advanced_bulk-actions.adoc | 8 +
.../_ug_more-advanced_decoupling.adoc | 25 +
..._more-advanced_decoupling_contributions.adoc | 7 +
..._ug_more-advanced_decoupling_db-schemas.adoc | 152 +++++
.../_ug_more-advanced_decoupling_event-bus.adoc | 136 +++++
.../user-guide/_ug_more-advanced_i18n.adoc | 606 +++++++++++++++++++
.../_ug_more-advanced_multi-tenancy.adoc | 7 +
.../user-guide/_ug_more-advanced_neo4j.adoc | 58 ++
..._ug_more-advanced_persistence-lifecycle.adoc | 7 +
.../_ug_more-advanced_tips-n-tricks.adoc | 20 +
...ore-advanced_tips-n-tricks_are-you-sure.adoc | 47 ++
...ore-advanced_tips-n-tricks_enhance-only.adoc | 18 +
...-advanced_tips-n-tricks_per-user-themes.adoc | 85 +++
...-tricks_render-all-properties-in-tables.adoc | 51 ++
...tricks_simulating-collections-of-values.adoc | 20 +
...s-n-tricks_suppress-actions-from-the-ui.adoc | 13 +
...g_more-advanced_transactions-and-errors.adoc | 26 +
.../_ug_more-advanced_view-models.adoc | 10 +
.../main/asciidoc/user-guide/_ug_reference.adoc | 25 +
.../user-guide/_ug_reference_addons.adoc | 17 +
.../_ug_reference_addons_settings-module.adoc | 49 ++
.../user-guide/_ug_reference_annotations.adoc | 39 ++
.../_ug_reference_annotations_aaa.adoc | 14 +
...ug_reference_annotations_aaa_deprecated.adoc | 328 ++++++++++
.../_ug_reference_annotations_aaa_jee.adoc | 35 ++
.../_ug_reference_annotations_aaa_main.adoc | 91 +++
.../_ug_reference_annotations_aaa_other.adoc | 55 ++
.../_ug_reference_annotations_aaa_partial.adoc | 43 ++
...ug_reference_annotations_manpage_action.adoc | 8 +
...erence_annotations_manpage_actionlayout.adoc | 8 +
...eference_annotations_manpage_collection.adoc | 8 +
...ce_annotations_manpage_collectionlayout.adoc | 8 +
...ug_reference_annotations_manpage_digits.adoc | 8 +
...erence_annotations_manpage_domainobject.adoc | 8 +
..._annotations_manpage_domainobjectlayout.adoc | 8 +
...rence_annotations_manpage_domainservice.adoc | 8 +
...annotations_manpage_domainservicelayout.adoc | 8 +
...ug_reference_annotations_manpage_facets.adoc | 8 +
..._reference_annotations_manpage_homepage.adoc | 8 +
...ug_reference_annotations_manpage_inject.adoc | 8 +
...e_annotations_manpage_membergrouplayout.adoc | 8 +
...ference_annotations_manpage_memberorder.adoc | 8 +
...reference_annotations_manpage_minlength.adoc | 8 +
...reference_annotations_manpage_parameter.adoc | 8 +
...erence_annotations_manpage_programmatic.adoc | 8 +
..._reference_annotations_manpage_property.adoc | 8 +
...ence_annotations_manpage_propertylayout.adoc | 8 +
...rence_annotations_manpage_requestscoped.adoc | 8 +
..._ug_reference_annotations_manpage_title.adoc | 8 +
...reference_annotations_manpage_viewmodel.adoc | 8 +
...nce_annotations_manpage_viewmodellayout.adoc | 8 +
.../_ug_reference_applib-utility-classes.adoc | 144 +++++
.../user-guide/_ug_reference_methods.adoc | 14 +
.../user-guide/_ug_reference_methods_aaa.adoc | 117 ++++
.../_ug_reference_methods_manpage_cssClass.adoc | 8 +
.../_ug_reference_methods_manpage_getId.adoc | 8 +
.../_ug_reference_methods_manpage_iconName.adoc | 8 +
.../_ug_reference_methods_manpage_title.adoc | 8 +
.../user-guide/_ug_reference_mixins.adoc | 11 +
.../user-guide/_ug_reference_prefixes.adoc | 27 +
.../user-guide/_ug_reference_prefixes_aaa.adoc | 151 +++++
.../_ug_reference_prefixes_manpage_addTo.adoc | 8 +
...reference_prefixes_manpage_autoComplete.adoc | 8 +
.../_ug_reference_prefixes_manpage_choices.adoc | 8 +
.../_ug_reference_prefixes_manpage_clear.adoc | 8 +
.../_ug_reference_prefixes_manpage_default.adoc | 8 +
.../_ug_reference_prefixes_manpage_disable.adoc | 8 +
.../_ug_reference_prefixes_manpage_get.adoc | 8 +
.../_ug_reference_prefixes_manpage_hide.adoc | 8 +
.../_ug_reference_prefixes_manpage_modify.adoc | 8 +
...g_reference_prefixes_manpage_removeFrom.adoc | 8 +
.../_ug_reference_prefixes_manpage_set.adoc | 8 +
..._ug_reference_prefixes_manpage_validate.adoc | 8 +
...eference_prefixes_manpage_validateAddTo.adoc | 8 +
...nce_prefixes_manpage_validateRemoveFrom.adoc | 8 +
.../user-guide/_ug_reference_services-api.adoc | 30 +
.../_ug_reference_services-api_aaa.adoc | 215 +++++++
..._services-api_action-invocation-context.adoc | 8 +
...ference_services-api_background-service.adoc | 8 +
...reference_services-api_bookmark-service.adoc | 8 +
...ug_reference_services-api_clock-service.adoc | 8 +
..._reference_services-api_command-context.adoc | 8 +
...eference_services-api_deep-link-service.adoc | 8 +
...ce_services-api_domain-object-container.adoc | 8 +
...ug_reference_services-api_email-service.adoc | 8 +
...eference_services-api_event-bus-service.adoc | 15 +
...erence_services-api_guice-bean-provider.adoc | 8 +
...reference_services-api_isis-jdo-support.adoc | 129 ++++
..._reference_services-api_memento-service.adoc | 8 +
...eference_services-api_metamodel-service.adoc | 8 +
...erence_services-api_query-results-cache.adoc | 8 +
.../_ug_reference_services-api_scratch-pad.adoc | 8 +
..._ug_reference_services-api_sudo-service.adoc | 8 +
..._reference_services-api_wrapper-factory.adoc | 18 +
...rence_services-api_xml-snapshot-service.adoc | 8 +
.../user-guide/_ug_reference_services-spi.adoc | 25 +
.../_ug_reference_services-spi_aaa.adoc | 214 +++++++
...reference_services-spi_auditing-service.adoc | 13 +
...services-spi_background-command-service.adoc | 12 +
...ce_services-spi_class-discovery-service.adoc | 8 +
..._reference_services-spi_command-service.adoc | 11 +
...ce_services-spi_content-mapping-service.adoc | 8 +
...ervices-spi_content-negotiation-service.adoc | 8 +
...services-spi_email-notification-service.adoc | 8 +
...reference_services-spi_event-serializer.adoc | 8 +
...rence_services-spi_exception-recognizer.adoc | 8 +
..._reference_services-spi_locale-provider.adoc | 8 +
...ference_services-spi_publishing-service.adoc | 11 +
...erence_services-spi_translation-service.adoc | 8 +
...ence_services-spi_translations-resolver.adoc | 8 +
...rence_services-spi_user-profile-service.adoc | 8 +
..._services-spi_user-registration-service.adoc | 8 +
.../user-guide/_ug_reference_superclasses.adoc | 52 ++
..._reference_superclasses_fixture-scripts.adoc | 8 +
.../user-guide/_ug_reference_value-types.adoc | 14 +
.../user-guide/_ug_restfulobjects-viewer.adoc | 24 +
...objects-viewer_configuration_properties.adoc | 181 ++++++
.../_ug_restfulobjects-viewer_features.adoc | 22 +
...ug_restfulobjects-viewer_hints-and-tips.adoc | 75 +++
.../main/asciidoc/user-guide/_ug_runtime.adoc | 27 +
.../_ug_runtime_configuration-files.adoc | 87 +++
.../_ug_runtime_configuring-core.adoc | 88 +++
.../_ug_runtime_configuring-datanucleus.adoc | 21 +
...s_disabling-persistence-by-reachability.adoc | 93 +++
...atanucleus_eagerly-registering-entities.adoc | 43 ++
...configuring-datanucleus_persistence-xml.adoc | 9 +
...time_configuring-datanucleus_properties.adoc | 57 ++
...ring-datanucleus_using-jndi-data-source.adoc | 72 +++
.../user-guide/_ug_runtime_web-xml.adoc | 19 +
.../main/asciidoc/user-guide/_ug_security.adoc | 52 ++
.../_ug_security_api-for-applications.adoc | 61 ++
...security_configuring-isis-to-use-bypass.adoc | 24 +
..._security_configuring-isis-to-use-shiro.adoc | 75 +++
.../user-guide/_ug_security_shiro-caching.adoc | 40 ++
.../_ug_security_shiro-ini-realm.adoc | 132 ++++
...shiro-isis-enhanced-wildcard-permission.adoc | 62 ++
.../_ug_security_shiro-isis-ldap-realm.adoc | 145 +++++
..._shiro-isisaddons-security-module-realm.adoc | 35 ++
.../_ug_security_shiro-jdbc-realm.adoc | 114 ++++
.../_ug_security_usage-by-isis-viewers.adoc | 207 +++++++
.../main/asciidoc/user-guide/_ug_testing.adoc | 16 +
.../_ug_testing_bdd-spec-support.adoc | 21 +
...ug_testing_bdd-spec-support_bdd-tooling.adoc | 13 +
...g_testing_bdd-spec-support_how-it-works.adoc | 19 +
...ug_testing_bdd-spec-support_key-classes.adoc | 58 ++
...ng_bdd-spec-support_maven-configuration.adoc | 72 +++
...ing_bdd-spec-support_writing-a-bdd-spec.adoc | 140 +++++
.../user-guide/_ug_testing_fixture-scripts.adoc | 43 ++
...g_testing_fixture-scripts_api-and-usage.adoc | 285 +++++++++
...ug_testing_fixture-scripts_sudo-service.adoc | 58 ++
.../_ug_testing_integ-test-support.adoc | 23 +
...esting_integ-test-support_bootstrapping.adoc | 230 +++++++
..._integ-test-support_maven-configuration.adoc | 45 ++
...esting_integ-test-support_typical-usage.adoc | 123 ++++
...ting_integ-test-support_wrapper-factory.adoc | 161 +++++
.../user-guide/_ug_testing_overview.adoc | 165 +++++
.../_ug_testing_unit-test-support.adoc | 12 +
...esting_unit-test-support_contract-tests.adoc | 169 ++++++
...ting_unit-test-support_jmock-extensions.adoc | 58 ++
...g_unit-test-support_maven-configuration.adoc | 45 ++
.../user-guide/_ug_troubleshooting.adoc | 13 +
.../_ug_troubleshooting_enabling-logging.adoc | 38 ++
.../asciidoc/user-guide/_ug_wicket-viewer.adoc | 29 +
..._wicket-viewer_configuration_properties.adoc | 276 +++++++++
.../_ug_wicket-viewer_customisation.adoc | 458 ++++++++++++++
.../user-guide/_ug_wicket-viewer_features.adoc | 458 ++++++++++++++
.../_ug_wicket-viewer_isis-addons.adoc | 32 +
.../user-guide/_ug_wicket-viewer_layout.adoc | 31 +
...t-viewer_layout_application-menu-layout.adoc | 170 ++++++
...ket-viewer_layout_dynamic-object-layout.adoc | 160 +++++
...cket-viewer_layout_static-object-layout.adoc | 166 +++++
.../_ug_wicket-viewer_request-parameters.adoc | 52 ++
.../src/main/asciidoc/user-guide/_ug_xxx.adoc | 0
.../user-guide/_user-guide_appendices.adoc | 12 -
.../_user-guide_appendices_dev-env.adoc | 14 -
..._user-guide_appendices_dev-env_cmd-line.adoc | 8 -
.../_user-guide_appendices_dev-env_eclipse.adoc | 8 -
..._user-guide_appendices_dev-env_intellij.adoc | 363 -----------
...de_appendices_dev-env_isis-maven-plugin.adoc | 8 -
.../_user-guide_appendices_migration-notes.adoc | 322 ----------
.../_user-guide_appendices_release-notes.adoc | 126 ----
.../user-guide/_user-guide_core-concepts.adoc | 24 -
.../_user-guide_core-concepts_add-ons.adoc | 7 -
...ser-guide_core-concepts_building-blocks.adoc | 237 --------
...re-concepts_framework-provided-services.adoc | 84 ---
.../_user-guide_core-concepts_philosophy.adoc | 20 -
...user-guide_core-concepts_philosophy_aop.adoc | 35 --
...user-guide_core-concepts_philosophy_dci.adoc | 8 -
...oncepts_philosophy_domain-driven-design.adoc | 79 ---
...cepts_philosophy_hexagonal-architecture.adoc | 28 -
..._core-concepts_philosophy_how-eases-ddd.adoc | 73 ---
...ncepts_philosophy_naked-objects-pattern.adoc | 54 --
.../_user-guide_core-concepts_principles.adoc | 17 -
...core-concepts_principles_apache-isis-vs.adoc | 36 --
...de_core-concepts_principles_isis-itself.adoc | 46 --
...uide_core-concepts_principles_your-apps.adoc | 38 --
.../user-guide/_user-guide_deployment.adoc | 19 -
.../_user-guide_deployment_cmd-line.adoc | 29 -
.../user-guide/_user-guide_deployment_gae.adoc | 459 --------------
.../_user-guide_deployment_jvm-flags.adoc | 18 -
.../_user-guide_deployment_tomcat.adoc | 14 -
.../user-guide/_user-guide_extending.adoc | 13 -
..._user-guide_extending_programming-model.adoc | 12 -
...ding_programming-model_custom-validator.adoc | 106 ----
..._extending_programming-model_finetuning.adoc | 79 ---
...rogramming-model_layout-metadata-reader.adoc | 43 --
...r-guide_extending_restfulobjects-viewer.adoc | 120 ----
.../_user-guide_extending_wicket-viewer.adoc | 25 -
...ng_wicket-viewer_custom-bootstrap-theme.adoc | 33 -
...de_extending_wicket-viewer_custom-pages.adoc | 91 ---
...ng_wicket-viewer_isis-addons-extensions.adoc | 16 -
...g_wicket-viewer_replacing-page-elements.adoc | 159 -----
.../user-guide/_user-guide_getting-started.adoc | 11 -
...de_getting-started_datanucleus-enhancer.adoc | 87 ---
...ide_getting-started_simpleapp-archetype.adoc | 7 -
.../user-guide/_user-guide_headless-access.adoc | 114 ----
.../user-guide/_user-guide_how-tos.adoc | 25 -
.../_user-guide_how-tos_business-rules.adoc | 57 --
.../_user-guide_how-tos_class-structure.adoc | 39 --
...w-tos_class-structure_action-parameters.adoc | 17 -
...r-guide_how-tos_class-structure_actions.adoc | 18 -
...ow-tos_class-structure_class-definition.adoc | 23 -
...ide_how-tos_class-structure_collections.adoc | 78 ---
...ow-tos_class-structure_ignoring-methods.adoc | 15 -
...lass-structure_properties-vs-parameters.adoc | 45 --
...uide_how-tos_class-structure_properties.adoc | 282 ---------
..._user-guide_how-tos_contributed-members.adoc | 15 -
.../user-guide/_user-guide_how-tos_crud.adoc | 22 -
.../_user-guide_how-tos_derived-members.adoc | 33 -
.../_user-guide_how-tos_domain-services.adoc | 23 -
...r-guide_how-tos_drop-downs-and-defaults.adoc | 30 -
...user-guide_how-tos_entity-relationships.adoc | 11 -
.../_user-guide_how-tos_ui-hints.adoc | 17 -
...e_how-tos_ui-hints_action-icons-and-css.adoc | 60 --
...-guide_how-tos_ui-hints_eager-rendering.adoc | 57 --
.../_user-guide_how-tos_ui-hints_layout.adoc | 14 -
...how-tos_ui-hints_names-and-descriptions.adoc | 41 --
...ow-tos_ui-hints_object-titles-and-icons.adoc | 94 ---
.../_user-guide_isis-addons-modules.adoc | 115 ----
.../user-guide/_user-guide_more-advanced.adoc | 32 -
.../_user-guide_more-advanced_assembling.adoc | 63 --
.../_user-guide_more-advanced_bulk-actions.adoc | 8 -
.../_user-guide_more-advanced_decoupling.adoc | 25 -
..._more-advanced_decoupling_contributions.adoc | 7 -
...ide_more-advanced_decoupling_db-schemas.adoc | 152 -----
...uide_more-advanced_decoupling_event-bus.adoc | 136 -----
.../_user-guide_more-advanced_i18n.adoc | 606 -------------------
..._user-guide_more-advanced_multi-tenancy.adoc | 7 -
.../_user-guide_more-advanced_neo4j.adoc | 58 --
...ide_more-advanced_persistence-lifecycle.adoc | 7 -
..._user-guide_more-advanced_tips-n-tricks.adoc | 20 -
...ore-advanced_tips-n-tricks_are-you-sure.adoc | 47 --
...ore-advanced_tips-n-tricks_enhance-only.adoc | 18 -
...-advanced_tips-n-tricks_per-user-themes.adoc | 85 ---
...-tricks_render-all-properties-in-tables.adoc | 51 --
...tricks_simulating-collections-of-values.adoc | 20 -
...s-n-tricks_suppress-actions-from-the-ui.adoc | 13 -
...e_more-advanced_transactions-and-errors.adoc | 26 -
.../_user-guide_more-advanced_view-models.adoc | 10 -
.../user-guide/_user-guide_reference.adoc | 25 -
.../_user-guide_reference_addons.adoc | 17 -
...-guide_reference_addons_settings-module.adoc | 49 --
.../_user-guide_reference_annotations.adoc | 39 --
.../_user-guide_reference_annotations_aaa.adoc | 14 -
...de_reference_annotations_aaa_deprecated.adoc | 328 ----------
...ser-guide_reference_annotations_aaa_jee.adoc | 35 --
...er-guide_reference_annotations_aaa_main.adoc | 91 ---
...r-guide_reference_annotations_aaa_other.adoc | 55 --
...guide_reference_annotations_aaa_partial.adoc | 43 --
...de_reference_annotations_manpage_action.adoc | 8 -
...erence_annotations_manpage_actionlayout.adoc | 8 -
...eference_annotations_manpage_collection.adoc | 8 -
...ce_annotations_manpage_collectionlayout.adoc | 8 -
...de_reference_annotations_manpage_digits.adoc | 8 -
...erence_annotations_manpage_domainobject.adoc | 8 -
..._annotations_manpage_domainobjectlayout.adoc | 8 -
...rence_annotations_manpage_domainservice.adoc | 8 -
...annotations_manpage_domainservicelayout.adoc | 8 -
...de_reference_annotations_manpage_facets.adoc | 8 -
..._reference_annotations_manpage_homepage.adoc | 8 -
...de_reference_annotations_manpage_inject.adoc | 8 -
...e_annotations_manpage_membergrouplayout.adoc | 8 -
...ference_annotations_manpage_memberorder.adoc | 8 -
...reference_annotations_manpage_minlength.adoc | 8 -
...reference_annotations_manpage_parameter.adoc | 8 -
...erence_annotations_manpage_programmatic.adoc | 8 -
..._reference_annotations_manpage_property.adoc | 8 -
...ence_annotations_manpage_propertylayout.adoc | 8 -
...rence_annotations_manpage_requestscoped.adoc | 8 -
...ide_reference_annotations_manpage_title.adoc | 8 -
...reference_annotations_manpage_viewmodel.adoc | 8 -
...nce_annotations_manpage_viewmodellayout.adoc | 8 -
...-guide_reference_applib-utility-classes.adoc | 144 -----
.../_user-guide_reference_methods.adoc | 14 -
.../_user-guide_reference_methods_aaa.adoc | 117 ----
...uide_reference_methods_manpage_cssClass.adoc | 8 -
...r-guide_reference_methods_manpage_getId.adoc | 8 -
...uide_reference_methods_manpage_iconName.adoc | 8 -
...r-guide_reference_methods_manpage_title.adoc | 8 -
.../_user-guide_reference_mixins.adoc | 11 -
.../_user-guide_reference_prefixes.adoc | 27 -
.../_user-guide_reference_prefixes_aaa.adoc | 151 -----
...-guide_reference_prefixes_manpage_addTo.adoc | 8 -
...reference_prefixes_manpage_autoComplete.adoc | 8 -
...uide_reference_prefixes_manpage_choices.adoc | 8 -
...-guide_reference_prefixes_manpage_clear.adoc | 8 -
...uide_reference_prefixes_manpage_default.adoc | 8 -
...uide_reference_prefixes_manpage_disable.adoc | 8 -
...er-guide_reference_prefixes_manpage_get.adoc | 8 -
...r-guide_reference_prefixes_manpage_hide.adoc | 8 -
...guide_reference_prefixes_manpage_modify.adoc | 8 -
...e_reference_prefixes_manpage_removeFrom.adoc | 8 -
...er-guide_reference_prefixes_manpage_set.adoc | 8 -
...ide_reference_prefixes_manpage_validate.adoc | 8 -
...eference_prefixes_manpage_validateAddTo.adoc | 8 -
...nce_prefixes_manpage_validateRemoveFrom.adoc | 8 -
.../_user-guide_reference_services-api.adoc | 30 -
.../_user-guide_reference_services-api_aaa.adoc | 215 -------
..._services-api_action-invocation-context.adoc | 8 -
...ference_services-api_background-service.adoc | 8 -
...reference_services-api_bookmark-service.adoc | 8 -
...de_reference_services-api_clock-service.adoc | 8 -
..._reference_services-api_command-context.adoc | 8 -
...eference_services-api_deep-link-service.adoc | 8 -
...ce_services-api_domain-object-container.adoc | 8 -
...de_reference_services-api_email-service.adoc | 8 -
...eference_services-api_event-bus-service.adoc | 15 -
...erence_services-api_guice-bean-provider.adoc | 8 -
...reference_services-api_isis-jdo-support.adoc | 129 ----
..._reference_services-api_memento-service.adoc | 8 -
...eference_services-api_metamodel-service.adoc | 8 -
...erence_services-api_query-results-cache.adoc | 8 -
...uide_reference_services-api_scratch-pad.adoc | 8 -
...ide_reference_services-api_sudo-service.adoc | 8 -
..._reference_services-api_wrapper-factory.adoc | 18 -
...rence_services-api_xml-snapshot-service.adoc | 8 -
.../_user-guide_reference_services-spi.adoc | 25 -
.../_user-guide_reference_services-spi_aaa.adoc | 214 -------
...reference_services-spi_auditing-service.adoc | 13 -
...services-spi_background-command-service.adoc | 12 -
...ce_services-spi_class-discovery-service.adoc | 8 -
..._reference_services-spi_command-service.adoc | 11 -
...ce_services-spi_content-mapping-service.adoc | 8 -
...ervices-spi_content-negotiation-service.adoc | 8 -
...services-spi_email-notification-service.adoc | 8 -
...reference_services-spi_event-serializer.adoc | 8 -
...rence_services-spi_exception-recognizer.adoc | 8 -
..._reference_services-spi_locale-provider.adoc | 8 -
...ference_services-spi_publishing-service.adoc | 11 -
...erence_services-spi_translation-service.adoc | 8 -
...ence_services-spi_translations-resolver.adoc | 8 -
...rence_services-spi_user-profile-service.adoc | 8 -
..._services-spi_user-registration-service.adoc | 8 -
.../_user-guide_reference_superclasses.adoc | 52 --
..._reference_superclasses_fixture-scripts.adoc | 8 -
.../_user-guide_reference_value-types.adoc | 14 -
.../_user-guide_restfulobjects-viewer.adoc | 24 -
...objects-viewer_configuration_properties.adoc | 181 ------
...er-guide_restfulobjects-viewer_features.adoc | 22 -
...de_restfulobjects-viewer_hints-and-tips.adoc | 75 ---
.../user-guide/_user-guide_runtime.adoc | 27 -
..._user-guide_runtime_configuration-files.adoc | 87 ---
.../_user-guide_runtime_configuring-core.adoc | 88 ---
...r-guide_runtime_configuring-datanucleus.adoc | 21 -
...s_disabling-persistence-by-reachability.adoc | 93 ---
...atanucleus_eagerly-registering-entities.adoc | 43 --
...configuring-datanucleus_persistence-xml.adoc | 9 -
...time_configuring-datanucleus_properties.adoc | 57 --
...ring-datanucleus_using-jndi-data-source.adoc | 72 ---
.../user-guide/_user-guide_runtime_web-xml.adoc | 19 -
.../user-guide/_user-guide_security.adoc | 52 --
...ser-guide_security_api-for-applications.adoc | 61 --
...security_configuring-isis-to-use-bypass.adoc | 24 -
..._security_configuring-isis-to-use-shiro.adoc | 75 ---
.../_user-guide_security_shiro-caching.adoc | 40 --
.../_user-guide_security_shiro-ini-realm.adoc | 132 ----
...shiro-isis-enhanced-wildcard-permission.adoc | 62 --
...er-guide_security_shiro-isis-ldap-realm.adoc | 145 -----
..._shiro-isisaddons-security-module-realm.adoc | 35 --
.../_user-guide_security_shiro-jdbc-realm.adoc | 114 ----
...er-guide_security_usage-by-isis-viewers.adoc | 207 -------
.../user-guide/_user-guide_testing.adoc | 16 -
.../_user-guide_testing_bdd-spec-support.adoc | 21 -
...de_testing_bdd-spec-support_bdd-tooling.adoc | 13 -
...e_testing_bdd-spec-support_how-it-works.adoc | 19 -
...de_testing_bdd-spec-support_key-classes.adoc | 58 --
...ng_bdd-spec-support_maven-configuration.adoc | 72 ---
...ing_bdd-spec-support_writing-a-bdd-spec.adoc | 140 -----
.../_user-guide_testing_fixture-scripts.adoc | 43 --
...e_testing_fixture-scripts_api-and-usage.adoc | 285 ---------
...de_testing_fixture-scripts_sudo-service.adoc | 58 --
.../_user-guide_testing_integ-test-support.adoc | 23 -
...esting_integ-test-support_bootstrapping.adoc | 230 -------
..._integ-test-support_maven-configuration.adoc | 45 --
...esting_integ-test-support_typical-usage.adoc | 123 ----
...ting_integ-test-support_wrapper-factory.adoc | 161 -----
.../_user-guide_testing_overview.adoc | 165 -----
.../_user-guide_testing_unit-test-support.adoc | 12 -
...esting_unit-test-support_contract-tests.adoc | 169 ------
...ting_unit-test-support_jmock-extensions.adoc | 58 --
...g_unit-test-support_maven-configuration.adoc | 45 --
.../user-guide/_user-guide_troubleshooting.adoc | 13 -
...-guide_troubleshooting_enabling-logging.adoc | 38 --
.../user-guide/_user-guide_wicket-viewer.adoc | 29 -
..._wicket-viewer_configuration_properties.adoc | 276 ---------
..._user-guide_wicket-viewer_customisation.adoc | 458 --------------
.../_user-guide_wicket-viewer_features.adoc | 458 --------------
.../_user-guide_wicket-viewer_isis-addons.adoc | 32 -
.../_user-guide_wicket-viewer_layout.adoc | 31 -
...t-viewer_layout_application-menu-layout.adoc | 170 ------
...ket-viewer_layout_dynamic-object-layout.adoc | 160 -----
...cket-viewer_layout_static-object-layout.adoc | 166 -----
...-guide_wicket-viewer_request-parameters.adoc | 52 --
.../asciidoc/user-guide/_user-guide_xxx.adoc | 0
482 files changed, 13491 insertions(+), 13491 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..8656e00
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices.adoc
@@ -0,0 +1,12 @@
+= Appendices
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+IMPORTANT: TODO
+
+include::_user-guide_appendices_dev-env.adoc[leveloffset=+1]
+
+include::_user-guide_appendices_release-notes.adoc[leveloffset=+1]
+
+include::_user-guide_appendices_migration-notes.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..63dd9d9
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_dev-env.adoc
@@ -0,0 +1,14 @@
+= Setting up a Development Environment
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+IMPORTANT: TODO
+
+include::_user-guide_appendices_dev-env_cmd-line.adoc[leveloffset=+1]
+
+include::_user-guide_appendices_dev-env_intellij.adoc[leveloffset=+1]
+
+include::_user-guide_appendices_dev-env_eclipse.adoc[leveloffset=+1]
+
+include::_user-guide_appendices_dev-env_isis-maven-plugin.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..f1ece55
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_dev-env_cmd-line.adoc
@@ -0,0 +1,8 @@
+= 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/97531ca0/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
new file mode 100644
index 0000000..395719a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_dev-env_eclipse.adoc
@@ -0,0 +1,8 @@
+= 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
+
+IMPORTANT: TODO
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..3401805
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_dev-env_intellij.adoc
@@ -0,0 +1,363 @@
+= 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
+
+
+
+== Installing and Setting up
+
+=== Download and Install
+
+WARNING: This doc used IntelliJ Community Edition 14.1.1, with screenshots taken for Windows. If you're a MacOS user, I'm sure you can adapt :-)
+
+https://www.jetbrains.com/idea/download/[Download] latest version of IntelliJ Community Edition, and install:
+
+Start the wizard, click through the welcome page:
+
+.IntelliJ Installation Wizard - Welcome page
+image::{_imagesdir}appendices/dev-env/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
+
+=== Setting up JRebel
+
+IMPORTANT: TODO
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_dev-env_isis-maven-plugin.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_dev-env_isis-maven-plugin.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_dev-env_isis-maven-plugin.adoc
new file mode 100644
index 0000000..d56f37d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_dev-env_isis-maven-plugin.adoc
@@ -0,0 +1,8 @@
+= 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/97531ca0/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
new file mode 100644
index 0000000..10aa1d2
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_migration-notes.adoc
@@ -0,0 +1,322 @@
+= 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).
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..266879e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices_release-notes.adoc
@@ -0,0 +1,126 @@
+= 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 http://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]
+| RestfulObjects 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 http://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/97531ca0/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
new file mode 100644
index 0000000..b5a5833
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts.adoc
@@ -0,0 +1,24 @@
+= 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::_user-guide_core-concepts_philosophy.adoc[leveloffset=+1]
+
+include::_user-guide_core-concepts_principles.adoc[leveloffset=+1]
+
+include::_user-guide_core-concepts_building-blocks.adoc[leveloffset=+1]
+
+include::_user-guide_core-concepts_framework-provided-services.adoc[leveloffset=+1]
+
+include::_user-guide_core-concepts_add-ons.adoc[leveloffset=+1]
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..5b01d80
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_add-ons.adoc
@@ -0,0 +1,7 @@
+= 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/
+
+IMPORTANT: TODO
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..0c04071
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_building-blocks.adoc
@@ -0,0 +1,237 @@
+= Building Blocks
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+IMPORTANT: TODO
+
+## A MetaModel with Explicit and Inferred Semantics
+
+* use of annotations
+** reuse JEE annotations where possible
+* layout hints are overridable, to avoid restarting the app/speed up feedback
+
+
+## Domain Objects and Domain Services
+
+* domain model
+** domain objects
+*** domain entity
+*** view model
+** domain service
+** value type
+
+Anything else can be (should be) ignored by annotating with `@Programmatic`.
+
+
+
+## Properties, Collections and Actions
+
+
+
+## Domain Entities vs View Models
+
+`@DomainObject(nature=...)`
+
+
+
+## Domain Services
+
+Domain services consist of a set of logically grouped actions, and as such follow the same conventions as for entities. However, a service cannot have (persisted) properties, nor can it have (persisted) collections.
+
+Domain services are instantiated once and once only by the framework, and are used to centralize any domain logic that does not logically belong in a domain entity or value. Isis will automatically inject services into every domain entity that requests them, and into each other.
+
+For convenience you can inherit from AbstractService or one of its subclasses, but this is not mandatory.
+
+### Domain Services vs View Services
+
+`@DomainService(nature=...)`
+
+.Factories, Repositories and Services
+****
+A distinction is sometimes made between a factory (that creates object) and a repository (that is used to find existing objects). You will find them discussed separately in Evans' link:Domain Driven Design[http://books.google.com/books/about/Domain_Driven_Design.html?id=hHBf4YxMnWMC], for example.
+
+In Apache Isis these are all implemented as domain services. Indeed, it is quite common to have a domain service that acts as both a factory and a repository.
+****
+
+## Value Objects (Primitives)
+
+
+
+## Contributions
+
+
+
+## Event Bus
+
+
+
+
+
+
+=== Registering domain services
+
+As noted link:../../how-tos/how-to-09-010-How-to-register-domain-services,-repositories-and-factories.html[elsewhere], domain services (which includes repositories and factories) should be registered in the `isis.properties` configuration file, under `isis.services` key (a comma-separated list):
+
+For example:
+
+[source]
+----
+isis.services = com.mycompany.myapp.employee.Employees\,
+ com.mycompany.myapp.claim.Claims\,
+ ...
+----
+
+This will then result in the framework instantiating a single instance of each of the services listed.
+
+If all services reside under a common package, then the `isis.services.prefix` can specify this prefix:
+
+[source]
+----
+isis.services.prefix = com.mycompany.myapp
+isis.services = employee.Employees,\
+ claim.Claims,\
+ ...
+----
+
+This is quite rare, however; you will often want to use default implementations of domain services that are provided by the framework and so will not reside under this prefix.
+
+Examples of framework-provided services (as defined in the applib) can be found referenced from the main link:../../documentation.html[documentation] page. They include clock, auditing, publishing, exception handling, view model support, snapshots/mementos, and user/application settings management.
+
+=== Service scopes
+
+By default all domain services are considered to be singletons, and thread-safe.
+
+Sometimes though a service's lifetime is applicable only to a single request; in other words it is request-scoped.
+
+The CDI annotation `@javax.enterprise.context.RequestScoped` is used to indicate this fact:
+
+[source]
+----
+ @javax.enterprise.context.RequestScoped
+ public class MyService extends AbstractService {
+ ...
+ }
+----
+
+The framework provides a number of request-scoped services; these can be found referenced from the main link:../../documentation.html[documentation] page. They include scratchpad service, query results caching, and support for co-ordinating bulk actions.
+
+=== (Suppressing) contributed actions
+
+Any n-parameter action provided by a service will automatically be contributed to the list of actions for each of its (entity) parameters. From the viewpoint of the entity the action is called a contributed action.
+
+For example, given a service:
+
+[source]
+----
+public interface Library {
+ public Loan borrow(Loanable l, Borrower b);
+}
+----
+
+and the entities:
+
+[source]
+----
+public class Book implements Loanable { ... }y
+----
+
+and
+
+[source]
+----
+public class LibraryMember implements Borrower { ... }
+----
+
+then the `borrow(...)` action will be contributed to both `Book` and to `LibraryMember`.
+
+This is an important capability because it helps to decouple the concrete classes from the services.
+
+If necessary, though, this behaviour can be suppressed by annotating the service action with `@org.apache.isis.applib.annotations.NotContributed`.
+
+For example:
+
+[source]
+----
+public interface Library {
+ @NotContributed
+ public Loan borrow(Loanable l, Borrower b);
+}
+----
+
+If annotated at the interface level, then the annotation will be inherited by every concrete class. Alternatively the annotation can be applied at the implementation class level and only apply to that particular implementation.
+
+Note that an action annotated as being `@NotContributed` will still appear in the service menu for the service. If an action should neither be contributed nor appear in service menu items, then simply annotate it as `@Hidden`.
+
+=== (Suppressing) service menu items
+
+By default every action of a service (by which we also mean repositories and factories) will be rendered in the viewer, eg as a menu item for that service menu. This behaviour can be suppressed by annotating the action using `@org.apache.isis.applib.annotations.NotInServiceMenu`.
+
+For example:
+
+[source]
+----
+public interface Library {
+ @NotInServiceMenu
+ public Loan borrow(Loanable l, Borrower b);
+}
+----
+
+Note that an action annotated as being `@NotInServiceMenu` will still be contributed. If an action should neither be contributed nor appear in service menu items, then simply annotate it as `@Hidden`.
+
+Alternatively, this can be performed using a supporting method:
+
+[source]
+----
+public class LibraryImpl implements Library {
+ public Loan borrow(Loanable l, Borrower b) { ... }
+ public boolean notInServiceMenuBorrow() { ... }
+}
+----
+
+=== (Suppressing) service menus
+
+If none of the service menu items should appear, then the service itself should be annotated as `@Hidden`.
+
+For example:
+
+[source]
+----
+@Hidden
+public interface EmailService {
+ public void sendEmail(String to, String from, String subject, String body);
+ public void forwardEmail(String to, String from, String subject, String body);
+}
+----
+
+=== Initializing Services
+
+Services can optionally declare lifecycle callbacks to initialize them (when the app is deployed) and to shut them down (when the app is undeployed).
+
+An Isis session _is_ available when initialization occurs (so services can interact with the object store, for example).
+
+==== Initialization
+
+The framework will call any `public` method annotated with `@javax.annotation.PostConstruct` and with either no arguments of an argument of type `Map<String,String>`:
+
+or
+
+In the latter case, the framework passes in the configuration (`isis.properties` and any other component-specific configuration files).
+
+==== Shutdown
+
+Shutdown is similar; the framework will call any method annotated with `@javax.annotation.PreDestroy`:
+
+=== The getId() method
+
+Optionally, a service may provide a `getId()` method:
+
+[source]
+----
+public String getId()
+----
+
+This method returns a logical identifier for a service, independent of its implementation. Currently it used only by perspectives, providing a label by which to record the services that are available for a current user's profile. <!--See ? for more about profiles and perspectives.-->
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..50519e1
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_framework-provided-services.adoc
@@ -0,0 +1,84 @@
+= Framework-provided Services
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+IMPORTANT: TODO
+
+## API vs SPI
+
+Most framework domain services are API: they exist to provide support functionality to the application's domain objects and services. In this case an implementation of the service will be available, either by Apache Isis itself or by Isis Addons (non ASF).
+
+Some framework domain services are SPI: they exist primarily so that the application can influence the framework's behaviour. In these cases there is (usually) no default implementation; it is up to the application to provide an implementation.
+
+## Autoregistration of Domain services
+
+Where a domain service has an implementation, it is (almost always) automatically registered just by virtue of being on the `CLASSPATH`.
+
+The one exception is <<ExceptionRecognizer>>.
+
+It is possible to replacing automatically-registered domain services.
+
+
+## Overview of Domain Services
+
+Unless indicated as SPI, each of the following has an implementation in Isis core.
+
+A full list of services (including those with implementations in http://isisaddons.org[Isis Addons] (non-ASF)) can be found in the <<_domain_services_2,Domain Services>> section.
+
+### `DomainObjectContainer`
+
+### `ClockService`
+
+### `IsisSupportJdo`
+
+### `ExceptionRecognizer`
+
+### `WrapperFactory`
+
+### `EventBusService`
+
+### Commands/Background
+
+#### `CommandContext`
+
+#### `BackgroundService`
+
+### Information Sharing
+
+#### `ScratchPad`
+
+#### `ActionInvocationContext`
+
+#### `QueryResultsCache`
+
+### `EmailService`
+
+### UserManagement
+
+#### `UserProfileService` (SPI)
+
+#### `UserRegistrationService` (SPI)
+
+#### `EmailNotificationService`
+
+
+### Bookmarks and Mementos
+
+#### `BookmarkService`
+
+#### `MementoService`
+
+#### `DeepLinkService`
+
+#### `XmlSnapshotService`
+
+
+
+
+
+
+
+
+
+
[04/22] isis git commit: ISIS-1133: renamed _user-guide_ to _ug_
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_superclasses.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_superclasses.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_superclasses.adoc
deleted file mode 100644
index d9aaee1..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_superclasses.adoc
+++ /dev/null
@@ -1,52 +0,0 @@
-= 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
-
-
-|<<__code_fixturescripts_code, `o.a.i.applib.` +
-`fixturescripts` +
-`FixtureScripts`>>
-|``o.a.i.core`` +
-``isis-core-applib``
-|(abstract class)
-|depends on: +
-`ClassDiscoveryService`
-
-
-
-|===
-
-
-
-
-include::_user-guide_reference_superclasses_fixture-scripts.adoc[leveloffset=+1]
-
-
-
-== `AbstractDomainObject`
-
-IMPORTANT: TODO
-
-== `AbstractDomainService`
-
-IMPORTANT: TODO
-
-== `AbstractFactoryAndRepository`
-
-IMPORTANT: TODO
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_superclasses_fixture-scripts.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_superclasses_fixture-scripts.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_superclasses_fixture-scripts.adoc
deleted file mode 100644
index f7cd2e2..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_superclasses_fixture-scripts.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_value-types.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_value-types.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_value-types.adoc
deleted file mode 100644
index 0808f72..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_value-types.adoc
+++ /dev/null
@@ -1,14 +0,0 @@
-= 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
-
-## JodaTime
-
-## Isis Applib
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_restfulobjects-viewer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_restfulobjects-viewer.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_restfulobjects-viewer.adoc
deleted file mode 100644
index be399da..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_restfulobjects-viewer.adoc
+++ /dev/null
@@ -1,24 +0,0 @@
-= 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::_user-guide_restfulobjects-viewer_features.adoc[leveloffset=+1]
-
-include::_user-guide_restfulobjects-viewer_configuration_properties.adoc[leveloffset=+1]
-
-include::_user-guide_restfulobjects-viewer_hints-and-tips.adoc[leveloffset=+1]
-
-
-== Extending the viewer
-
-Discussed in <<_extending_the_restful_viewer, Extending the Restful viewer>>.
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_restfulobjects-viewer_configuration_properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_restfulobjects-viewer_configuration_properties.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_restfulobjects-viewer_configuration_properties.adoc
deleted file mode 100644
index 546a4fa..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_restfulobjects-viewer_configuration_properties.adoc
+++ /dev/null
@@ -1,181 +0,0 @@
-= 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/
-
-IMPORTANT: WIP...
-
-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).
-====
-
-
-.RestfulObjects Viewer Configuration Properties
-[cols="2a,1,3", options="header"]
-|===
-|Property
-|Value +
-(_default value_)
-|Description
-
-|`isis.viewer.restfulobjects.` +
-`honorUiHints`
-| `true`,`false` (`_false_`)
-| See <<_honor_ui_hints, discussion>>, below.
-
-|`isis.viewer.restfulobjects.` +
-`suppressDescribedByLinks`
-| `true`,`false` (`_false_`)
-.6+| See <<_suppressing_elements_of_the_representation, 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 <<_simplified_object_representation, discussion>>, below.
-
-|===
-
-
-
-== Honor UI hints
-
-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.
-====
-
-
-
-== Suppressing elements of the representation
-
-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 <<_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 <<_extending_the_restful_viewer, Extending the Restful viewer>> in the <<Extending>> chapter.
-
-
-
-== Simplified object representation
-
-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 <<_suppressing_elements_of_the_representations, 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 <<_extending_the_restful_viewer, Extending the Restful viewer>>.
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_restfulobjects-viewer_features.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_restfulobjects-viewer_features.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_restfulobjects-viewer_features.adoc
deleted file mode 100644
index 2f8f591..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_restfulobjects-viewer_features.adoc
+++ /dev/null
@@ -1,22 +0,0 @@
-= 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 <<_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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_restfulobjects-viewer_hints-and-tips.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_restfulobjects-viewer_hints-and-tips.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_restfulobjects-viewer_hints-and-tips.adoc
deleted file mode 100644
index f37da44..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_restfulobjects-viewer_hints-and-tips.adoc
+++ /dev/null
@@ -1,75 +0,0 @@
-= 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/
-
-
-
-== 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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime.adoc
deleted file mode 100644
index 8bc64e6..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime.adoc
+++ /dev/null
@@ -1,27 +0,0 @@
-= 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 <<Wicket Viewer>> chapter and the <<Restful Objects Viewer>> chapter. Likewise, details of configuring security (Apache Shiro) can be found in the <<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::_user-guide_runtime_configuration-files.adoc[leveloffset=+1]
-
-include::_user-guide_runtime_configuring-core.adoc[leveloffset=+1]
-
-include::_user-guide_runtime_web-xml.adoc[leveloffset=+1]
-
-include::_user-guide_runtime_configuring-datanucleus.adoc[leveloffset=+1]
-
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime_configuration-files.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime_configuration-files.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime_configuration-files.adoc
deleted file mode 100644
index c5ddffe..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime_configuration-files.adoc
+++ /dev/null
@@ -1,87 +0,0 @@
-= 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 <<_wicket_viewer_2, Wicket UI (viewer)>> is in use
-
-* `viewer_restfulobjects.properties` - if the <<_restful_objects_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.
-
-
-== Specifying other components
-
-The `isis.properties` file has three 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.persistor`
-|`_datanucleus_`
-|`org.apache.isis.core.runtime.installerregistry.installerapi.` `PersistenceMechanismInstaller`
-
-|`isis.authentication`
-|`_shiro_` +
-`bypass`
-|`org.apache.isis.core.runtime.authentication.` `AuthenticationManagerInstaller`
-
-|`isis.authorization`
-|`_shiro_` +
-`bypass`
-|`org.apache.isis.core.runtime.authorization.` `AuthorizationManagerInstaller`
-
-|===
-
-[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. In practice only the two security APIs are actually simple enough for this to be viable.
-====
-
-As for the viewers, these are specified indirectly by way of the filters and servlets in the `web.xml` file (discussed <<_configuring_the_webapp, 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.
-
-
-
-== Deployment Types
-
-IMPORTANT: TODO
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime_configuring-core.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime_configuring-core.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime_configuring-core.adoc
deleted file mode 100644
index 99c5618..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime_configuring-core.adoc
+++ /dev/null
@@ -1,88 +0,0 @@
-= 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.
-
-Configuration properties for the JDO/DataNucleus objectstore can be found in the <<_configuring_datanucleus, Configuring DataNucleus>> section elsewhere in this chapter.
-
-Configuration properties for the viewers can be found in the <<Wicket Viewer>> chapter and the <<Restful Objects Viewer>> chapter.
-
-
-.Core Configuration Properties
-[cols="2a,1,3a", options="header"]
-|===
-|Property
-|Value +
-(_default value_)
-|Description
-
-|`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 `@DomainServiceLayout#menuOrder()`).
-
-|`isis.services.` +
-`container.disableAutoFlush`
-| `true`,`false` (`_false_`)
-|Whether the `DomainObjectContainer` should automatically flush pending changes prior to querying (via `allMatches()`, `firstMatch()` and so on).
-
-|`isis.services.` +
-`translation.po.mode`
-| `read`,`write`
-|Whether to force the `TranslationService` into either read or write mode. +
-See <<_i18n, i18n support>> to learn more about the translation service.
-
-|`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.` +
-`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: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 <<_user-guide_how-tos_ui-hints_action-icons-and-css, UI hints>> for more details.
-
-|`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 <<_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 <<_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 <<_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 <<_finetuning, finetuning the programming model>> for more details.
-
-|`isis.reflector.validator`
-|`FQCN`
-|Custom implementation of `MetaModelValidator` (in the `org.apache.isis.core.metamodel.specloader.validator` package) +
-See <<_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.reflector.` +
-`layoutMetadataReaders`
-|`FQCN`,`FQCN2`,...
-|Fully qualified class names of classes to be instantiated to read layout metadata, as used in for <<_dynamic_object_layout, dynamic layout>>s. +
-See <<_layout_metadata_reader, Layout Metadata Reader>> for more information.
-
-|===
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime_configuring-datanucleus.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime_configuring-datanucleus.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime_configuring-datanucleus.adoc
deleted file mode 100644
index 1e10db1..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime_configuring-datanucleus.adoc
+++ /dev/null
@@ -1,21 +0,0 @@
-= 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 <<_overriding_jdo_annotations, Overriding JDO Annotatons>> for further discussion.
-
-
-include::_user-guide_runtime_configuring-datanucleus_properties.adoc[leveloffset=+1]
-
-include::_user-guide_runtime_configuring-datanucleus_persistence-xml.adoc[leveloffset=+1]
-
-include::_user-guide_runtime_configuring-datanucleus_eagerly-registering-entities.adoc[leveloffset=+1]
-
-include::_user-guide_runtime_configuring-datanucleus_disabling-persistence-by-reachability.adoc[leveloffset=+1]
-
-include::_user-guide_runtime_configuring-datanucleus_using-jndi-data-source.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime_configuring-datanucleus_disabling-persistence-by-reachability.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime_configuring-datanucleus_disabling-persistence-by-reachability.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime_configuring-datanucleus_disabling-persistence-by-reachability.adoc
deleted file mode 100644
index 5c0b109..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime_configuring-datanucleus_disabling-persistence-by-reachability.adoc
+++ /dev/null
@@ -1,93 +0,0 @@
-= Disabling 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' link:../../../reference/Utility.html[ObjectContracts] utility. 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 <<_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.
-
-== Explanation of the issue in more detail
-
-Consider the entities:
-
-image::{_imagesdir}reference/configuration-properties/datanucleus-objectstore/party-agreementrole-agreement.png[width="750px"]
-
-
-[TIP]
-====
-[source]
-.DSL (http://yuml.me/edit/b8681268[yuml.me/b8681268])
-----
-[Party|reference]<--->*[AgreementRole|startDate]
-[AgreementRole]*<-->[Agreement|reference]
-----
-====
-
-
-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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime_configuring-datanucleus_eagerly-registering-entities.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime_configuring-datanucleus_eagerly-registering-entities.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime_configuring-datanucleus_eagerly-registering-entities.adoc
deleted file mode 100644
index 3748ac3..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime_configuring-datanucleus_eagerly-registering-entities.adoc
+++ /dev/null
@@ -1,43 +0,0 @@
-= Eagerly Registering Entity 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/
-
-[WARNING]
-====
-From 1.6.0+ this feature may be (partly?) broken; see https://issues.apache.org/jira/browse/ISIS-847[ISIS-847].
-====
-
-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.
-
-
-== 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 <<_integration_testing, 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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime_configuring-datanucleus_persistence-xml.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime_configuring-datanucleus_persistence-xml.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime_configuring-datanucleus_persistence-xml.adoc
deleted file mode 100644
index 7933b17..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime_configuring-datanucleus_persistence-xml.adoc
+++ /dev/null
@@ -1,9 +0,0 @@
-= `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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime_configuring-datanucleus_properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime_configuring-datanucleus_properties.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime_configuring-datanucleus_properties.adoc
deleted file mode 100644
index a76fa6a..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime_configuring-datanucleus_properties.adoc
+++ /dev/null
@@ -1,57 +0,0 @@
-= 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/
-
-IMPORTANT: WIP...
-
-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.` +
-`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 <<_registering_entity_types, 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 <<_disabling_persistence_by_reachability, discussion below>>.
-
-|===
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime_configuring-datanucleus_using-jndi-data-source.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime_configuring-datanucleus_using-jndi-data-source.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime_configuring-datanucleus_using-jndi-data-source.adoc
deleted file mode 100644
index 9888750..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime_configuring-datanucleus_using-jndi-data-source.adoc
+++ /dev/null
@@ -1,72 +0,0 @@
-= 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 connections
-
-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) datasource
-
-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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime_web-xml.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime_web-xml.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime_web-xml.adoc
deleted file mode 100644
index 8be8f26..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_runtime_web-xml.adoc
+++ /dev/null
@@ -1,19 +0,0 @@
-= `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
-
-
-== Servlets
-
-
-== Running Restful Objects Viewer only
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_security.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_security.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_security.adoc
deleted file mode 100644
index acba897..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_security.adoc
+++ /dev/null
@@ -1,52 +0,0 @@
-= 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 <<_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 http://isisaddons.org[Isis Addons] (non-ASF) 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 -- <<_command_service, `CommandService`>> and <<_auditing_service, `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 http://isisaddons.org[Isis Addons] (non-ASF), namely the http://github.com/isisaddons/isis-module-command}[Isis addons' command] module and the http://github.com/isisaddons/isis-module-auditing}[Isis addons' auditing] module.
-====
-
-
-
-include::_user-guide_security_configuring-isis-to-use-shiro.adoc[leveloffset=+1]
-
-include::_user-guide_security_shiro-ini-realm.adoc[leveloffset=+1]
-
-include::_user-guide_security_shiro-isis-ldap-realm.adoc[leveloffset=+1]
-
-include::_user-guide_security_shiro-isisaddons-security-module-realm.adoc[leveloffset=+1]
-
-include::_user-guide_security_shiro-jdbc-realm.adoc[leveloffset=+1]
-
-include::_user-guide_security_shiro-isis-enhanced-wildcard-permission.adoc[leveloffset=+1]
-
-include::_user-guide_security_configuring-isis-to-use-bypass.adoc[leveloffset=+1]
-
-include::_user-guide_security_api-for-applications.adoc[leveloffset=+1]
-
-include::_user-guide_security_usage-by-isis-viewers.adoc[leveloffset=+1]
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_security_api-for-applications.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_security_api-for-applications.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_security_api-for-applications.adoc
deleted file mode 100644
index 5655fe2..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_security_api-for-applications.adoc
+++ /dev/null
@@ -1,61 +0,0 @@
-= 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.
-
-
-== Using Isis` `DomainObjectContainer`
-
-The <<_domain_object_container, `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").
-
-
-
-== Accessing user/roles from the 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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_security_configuring-isis-to-use-bypass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_security_configuring-isis-to-use-bypass.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_security_configuring-isis-to-use-bypass.adoc
deleted file mode 100644
index f80fb37..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_security_configuring-isis-to-use-bypass.adoc
+++ /dev/null
@@ -1,24 +0,0 @@
-= Bypass 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).
-
-
-== Specifying bypass as the security mechanism
-
-To tell Apache Isis to bypass security, 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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_security_configuring-isis-to-use-shiro.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_security_configuring-isis-to-use-shiro.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_security_configuring-isis-to-use-shiro.adoc
deleted file mode 100644
index 1515608..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_security_configuring-isis-to-use-shiro.adoc
+++ /dev/null
@@ -1,75 +0,0 @@
-= 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 <<_simpleapp_archetype, SimpleApp archetype>> is pre-configured to use Apache Shiro, so much of what follows is set up already.
-====
-
-== Specifying Shiro as the security mechanism
-
-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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_security_shiro-caching.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_security_shiro-caching.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_security_shiro-caching.adoc
deleted file mode 100644
index deb94b9..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_security_shiro-caching.adoc
+++ /dev/null
@@ -1,40 +0,0 @@
-= 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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_security_shiro-ini-realm.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_security_shiro-ini-realm.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_security_shiro-ini-realm.adoc
deleted file mode 100644
index a1bad63..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_security_shiro-ini-realm.adoc
+++ /dev/null
@@ -1,132 +0,0 @@
-= 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 <<_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]
-----
-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 <<_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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_security_shiro-isis-enhanced-wildcard-permission.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_security_shiro-isis-enhanced-wildcard-permission.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_security_shiro-isis-enhanced-wildcard-permission.adoc
deleted file mode 100644
index d94372d..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_security_shiro-isis-enhanced-wildcard-permission.adoc
+++ /dev/null
@@ -1,62 +0,0 @@
-= 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 <<_shiro_ini_realm, `IniRealm`>> or <<_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`.
-
-
-
-== Shiro Configuration
-
-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.
-
-
[11/22] isis git commit: ISIS-1133: renamed _user-guide_ to _ug_
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..420a0fc
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_configuration_properties.adoc
@@ -0,0 +1,276 @@
+= 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 <<_abbreviating_suppressing_titles_in_tables, below>>.
+
+|`isis.viewer.wicket.` +
+`maxTitleLengthInStandaloneTables`
+| +ve integer, (`_12_`)
+| See discussion <<_abbreviating_suppressing_titles_in_tables, below>>.
+
+|`isis.viewer.wicket.` +
+`maxTitleLengthInTables`
+| +ve integer, (`_12_`)
+| See discussion <<_abbreviating_suppressing_titles_in_tables, 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 <<_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 <<_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 <<_suppressing_sign_up, below>>.
+
+|`isis.viewer.wicket.` +
+`themes.enabled`
+| comma separated list ...
+| ... of bootswatch themes. Only applies if `themes.showChooser`==`true`. See discussion <<_showing_a_theme_chooser, below>>.
+
+|`isis.viewer.wicket.` +
+`themes.showChooser`
+| `true`,`false` (`_false_`)
+| Whether to show chooser for Bootstrap themes. See discussion <<_showing_a_theme_chooser, below>>
+
+|===
+
+
+
+== Abbreviating/suppressing titles in tables
+
+Objects whose title is overly long can be cumbersome in titles. The Wicket viewer has a <<_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`.
+
+
+
+
+== Suppressing 'remember me'
+
+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
+----
+
+
+
+== Suppressing 'sign up'
+
+If <<_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 <<_suppressing_password_reset, password reset link>> can be suppressed in a similar manner.
+
+
+
+== Suppressing 'password reset'
+
+If <<_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 <<_suppressing_sign-up, sign up link>> can be suppressed in a similar manner.
+
+
+
+
+== Stripped Wicket tags
+
+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.
+====
+
+
+
+== Showing a theme chooser
+
+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 <<_specifying_a_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 <<_custom_bootstrap_theme, Extending>> chapter for further details.
+====
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..ed3d089
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_customisation.adoc
@@ -0,0 +1,458 @@
+= 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/
+
+
+== Brand logo
+
+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 `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;
+}
+----
+
+
+
+
+== Specifying a default theme
+
+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 <<_custom_bootstrap_theme, here>>) then this can also be specified using the https://github.com/l0rdn1kk0n/wicket-bootstrap/wiki/Themes[Wicket Bootstrap API].
+
+
+
+
+
+== Welcome page
+
+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`.
+
+
+
+
+== About page
+
+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]
+====
+TODO: this screenshot need to be updated for the new look-n-feel introduced in 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 <<_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!
+
+
+
+
+== Tweaking CSS classes
+
+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 `src/main/webapp/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 `src/main/webapp/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 <<_dynamic_layouts, dynamic layout>> JSON file:
+
+[source,javascript]
+----
+"dueBy": {
+ "propertyLayout": {
+ "cssClass": "x-myapp-important"
+ }
+},
+----
+
+
+
+== Cheap-n-cheerful "theme"
+
+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 <<_custom_bootstrap_theme, own Bootstrap theme>>, as described in the <<Extending>> chapter.
+====
+
+
+
+== Using a different CSS file
+
+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]
+----
+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`.
+
+
+
+== Custom Javascript
+
+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 <<_extending_the_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.
+
+
+
+
+== Auto-refresh page
+
+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/97531ca0/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
new file mode 100644
index 0000000..ca7c501
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_features.adoc
@@ -0,0 +1,458 @@
+= 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.
+
+
+
+== Titles in Tables
+
+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 <<_abbreviating_suppressing_titles_in_tables, abbreviate titles or suppress them>> completely.
+====
+
+
+
+== File upload/download
+
+The Isis application library provides the <<_blob, Blob>> value type (binary large objects) and also the <<_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):
+
+[NOTE]
+====
+TODO: these screenshots need to be updated for the new look-n-feel introduced in 1.8.0
+====
+
+==== 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"]
+
+==== 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.
+
+
+
+
+== Bookmarked pages
+
+The Wicket viewer supports the bookmarking of both domain objects and query-only (<<_actionsemantics, @ActionSemantics>>) 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]
+====
+TODO: this screenshot need to be updated for the new look-n-feel introduced in 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"]
+
+[NOTE]
+====
+TODO: this screenshot need to be updated for the new look-n-feel introduced in 1.8.0
+====
+
+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 <<_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 <<_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 <<_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
+----
+
+
+
+== Recent pages (drop down)
+
+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]
+====
+TODO: this screenshot need to be updated for the new look-n-feel introduced in 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 <<_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.
+
+
+
+
+
+== Hints and copy URL
+
+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.
+
+[NOTE]
+====
+TODO: these screenshots need to be updated for the new look-n-feel introduced in 1.8.0
+====
+
+==== 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"]
+
+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.
+
+
+
+
+
+
+
+== User Registration
+
+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 <<_user_registration_service, user registration service>>, which provides an API to create the user account
+* the <<_email_notification_service, email notification service>>, which provides an API for to send the verification emails
+* the <<_email_service, 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 <<_user_registration_service, user registration service>> (eg by using the https://github.com/isisaddons/isis-module-security[Isis addons security module])
+
+* configure the <<_email_service, 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 <<_suppressing_sign_up, the sign-up page link>> and/or the <<_suppressing_password_reset, password reset page>>.
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..47eb472
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_isis-addons.adoc
@@ -0,0 +1,32 @@
+= 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 http://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/97531ca0/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
new file mode 100644
index 0000000..a5b4c6c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_layout.adoc
@@ -0,0 +1,31 @@
+= 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 section describes how this is done both for domain objects -- statically or dynamically -- and for the application menu bar (containing domain service' actions).
+
+include::_user-guide_wicket-viewer_layout_static-object-layout.adoc[leveloffset=+1]
+
+include::_user-guide_wicket-viewer_layout_dynamic-object-layout.adoc[leveloffset=+1]
+
+include::_user-guide_wicket-viewer_layout_application-menu-layout.adoc[leveloffset=+1]
+
+
+
+== Static vs Dynamic Layouts
+
+Using <<_dynamic_object_layout, 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 <<_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 (third-party) http://github.com/isisaddons/isis-jrebel-plugin}[Isis addons' jrebel] plugin (non-ASF) 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.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_layout_application-menu-layout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_layout_application-menu-layout.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_layout_application-menu-layout.adoc
new file mode 100644
index 0000000..88ccc3a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_layout_application-menu-layout.adoc
@@ -0,0 +1,170 @@
+= 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 Isis add-ons 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 <<_vetoing_visibility, vetoing subscriber>>.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_layout_dynamic-object-layout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_layout_dynamic-object-layout.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_layout_dynamic-object-layout.adoc
new file mode 100644
index 0000000..03148b8
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_layout_dynamic-object-layout.adoc
@@ -0,0 +1,160 @@
+= 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/
+
+
+Because Isis implements the http://en.wikipedia.org/wiki/Naked_objects[naked objects pattern], the domain objects are rendered in the UI based only metadata gleaned from the domain classes themselves. Traditionally this metadata has been specified statically, using annotations such as <<_memberorder, `@MemberOrder`>> and <<_membergrouplayout, `@MemberGroupLayout`>>. However, it is also possible to specify the layout data using a JSON file. This brings the advantage that the layout can be refreshed dynamically, without recompiling/redeploying the app.
+
+== Screencast
+
+How to layout properties and collections dynamically, in the Wicket viewer.
+
+video::zmrg49WeEPc[youtube,width="530px",height="354px"]
+
+
+
+== 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 <<_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 http://github.com/isisaddons/isis-module-devutils}[Isis addons' devutils] module (non-ASF) to download the layout file (derived from any existing static metadata defined by annotations).
+
+
+
+== Picking up new metadata
+
+When running in <<_deployment_types, prototype (development) mode>>, the Wicket viewer automatically rebuilds the metamodel for each class as it is rendered.
+
+[NOTE]
+====
+Conversely, do note that the Wicket viewer will _not_ pick up new metadata if running in production/server mode.
+====
+
+
+
+== 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 link:../../../intro/getting-started/simple-archetype.html[archetype], then the POM is already correctly configured.
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_layout_static-object-layout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_layout_static-object-layout.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_layout_static-object-layout.adoc
new file mode 100644
index 0000000..7fbd783
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_layout_static-object-layout.adoc
@@ -0,0 +1,166 @@
+= 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/
+
+
+Because Isis implements the http://en.wikipedia.org/wiki/Naked_objects[naked objects pattern], the domain objects are rendered in the UI based only metadata gleaned from the domain classes themselves. Traditionally this metadata has been specified statically using annotations.
+
+
+== `@MemberOrder`
+
+To specify the relative order of domain class properties and classes, the `@MemberOrder` annotation is used.
+
+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(sequence="1")
+ public SortedSet<ToDoItem> getDependencies() { ... }
+
+ // actions ...
+ @MemberOrder(name="complete", sequence="1")
+ public ToDoItem completed() { ...}
+
+ @MemberOrder(name="complete", sequence="2")
+ public ToDoItem notYetCompleted() { ...}
+
+ // more actions ...
+ @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.
+
+If the `name` attribute is omitted, then the action is rendered near the header. Note also that the `@MemberOrder`'s `name` attribute has no meaning for collections.
+
+== `@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. It also specifies the relative width.
+
+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 http://twitter.github.io/bootstrap/[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}wicket-viewer/layouts/6-6-0-12.png[width="720px",link="{_imagesdir}wicket-viewer/layouts/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}wicket-viewer/layouts/4-4-4-12.png[width="720px",link="{_imagesdir}wicket-viewer/layouts/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}wicket-viewer/layouts/4-0-8-0.png[width="720px",link="{_imagesdir}wicket-viewer/layouts/4-0-8-0.png"]
+
+
+== Other Annotations
+
+As of 1.8.0, all the layout annotations have been consolidated into the various `XxxLayout` annotations:
+
+* <<_domainservicelayout, `@DomainServiceLayout`>>
+* <<_domainobjectlayout, `@DomainObjectLayout`>>
+* <<_viewmodellayout, `@ViewModelLayout`>>
+* <<_propertylayout, `@PropertyLayout`>>
+* <<_collectionlayout, `@CollectionLayout`>>
+* <<_actionlayout, `@ActionLayout`>>
+* <<_parameterlayout, `@ParameterLayout`>>
+
+Prior to 1.8.0 a variety of annotations (now deprecated) are available, including:
+
+* <<_named, `@Named`>>
+* <<_describedas, `@DescribedAs`>>
+* <<_multiline, `@MultiLine`>>
+* <<_typicallength, `@TypicalLength`>>
+* <<_render, `@Render`>>
+* <<_cssclass, `@CssClass`>>
+* <<_cssclassfa, `@CssClassFa`>>
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..12f843c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer_request-parameters.adoc
@@ -0,0 +1,52 @@
+= 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/97531ca0/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
new file mode 100644
index 0000000..e69de29
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices.adoc
deleted file mode 100644
index 8656e00..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices.adoc
+++ /dev/null
@@ -1,12 +0,0 @@
-= Appendices
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-IMPORTANT: TODO
-
-include::_user-guide_appendices_dev-env.adoc[leveloffset=+1]
-
-include::_user-guide_appendices_release-notes.adoc[leveloffset=+1]
-
-include::_user-guide_appendices_migration-notes.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_dev-env.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_dev-env.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_dev-env.adoc
deleted file mode 100644
index 63dd9d9..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_dev-env.adoc
+++ /dev/null
@@ -1,14 +0,0 @@
-= Setting up a Development Environment
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-IMPORTANT: TODO
-
-include::_user-guide_appendices_dev-env_cmd-line.adoc[leveloffset=+1]
-
-include::_user-guide_appendices_dev-env_intellij.adoc[leveloffset=+1]
-
-include::_user-guide_appendices_dev-env_eclipse.adoc[leveloffset=+1]
-
-include::_user-guide_appendices_dev-env_isis-maven-plugin.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_dev-env_cmd-line.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_dev-env_cmd-line.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_dev-env_cmd-line.adoc
deleted file mode 100644
index f1ece55..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_dev-env_cmd-line.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= 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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_dev-env_eclipse.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_dev-env_eclipse.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_dev-env_eclipse.adoc
deleted file mode 100644
index 395719a..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_dev-env_eclipse.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= 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
-
-IMPORTANT: TODO
-
[06/22] isis git commit: ISIS-1133: renamed _user-guide_ to _ug_
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_aaa.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_aaa.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_aaa.adoc
deleted file mode 100644
index c8ef404..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_aaa.adoc
+++ /dev/null
@@ -1,14 +0,0 @@
-= 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/
-
-
-
-include::_user-guide_reference_annotations_aaa_main.adoc[leveloffset=+1]
-include::_user-guide_reference_annotations_aaa_other.adoc[leveloffset=+1]
-include::_user-guide_reference_annotations_aaa_jee.adoc[leveloffset=+1]
-include::_user-guide_reference_annotations_aaa_deprecated.adoc[leveloffset=+1]
-include::_user-guide_reference_annotations_aaa_partial.adoc[leveloffset=+1]
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_aaa_deprecated.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_aaa_deprecated.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_aaa_deprecated.adoc
deleted file mode 100644
index 15f22d6..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_aaa_deprecated.adoc
+++ /dev/null
@@ -1,328 +0,0 @@
-= 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/
-
-
-
-
-.Deprecated Annotations
-[cols="2,4a,3a,1,1", options="header"]
-|===
-|Annotation
-|Purpose
-|Use instead
-|Layer
-|`.layout +
-.json`?
-
-|`@ActionOrder`
-|Order of buttons and menu items representing actions.
-|`@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.
-|`@Action#domainEvent()`
-|Domain
-|
-
-|`@ActionSemantics`
-|Query-only, idempotent or non-idempotent.
-|`@Action#semantics()`
-|Domain
-|
-
-|`@Audited`
-|Audit changes to an object.
-|`@DomainObject#` +
-`auditing()`
-|Domain
-|
-
-|`@AutoComplete`
-|Repository method to search for entities
-|`@DomainObject` +
-`#autoCompleteRepository()`
-|UI/Domain
-|
-
-|`@Bookmarkable`
-|Whether (and how) to create a bookmark for visited object.
-|`@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.
-|`@DomainObject#bounded()`
-|Domain
-|
-
-|`@Bulk`
-|Indicates an action is a bulk action, can be applied to multiple instances.
-|`@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.
-|`@Collection#domainEvent()`
-|Domain
-|
-
-|`@Command`
-|Action invocation should be reified as a command object, optionally persistable for profiling and enhanced auditing, and background/async support.
-|`@Action#command()`
-|Domain
-|
-
-|`@CssClass`
-|Allow visual representation of individual objects or object members layout to be customized by application-specific CSS.
-|`#cssClass()` attribute for: `@DomainObjectLayout`, `@PropertyLayout`, `@CollectionLayout`, `@ActionLayout` and `@ParameterLayout`
-|UI
-|Yes
-
-|`@CssClassFa`
-|So that font awesome icons can be applied to action buttons/menu items and optionally as an object icon.
-|`@ActionLayout#cssClassFa()`
-|UI
-|Yes
-
-|`@Debug`
-|Action only invokable in debug mode.
-|Use prototype mode instead (`@Action#restrictTo()`)
-|UI
-|
-
-|`@DescribedAs`
-|Provide a longer description/tool-tip of an object or object member.
-|`#describedAs()` attribute for `@DomainObjectLayout`, `@PropertyLayout`, `@CollectionLayout`, `@ActionLayout` and `@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 `@Property` and `@Collection#editing()`; see also `@DomainObject`
-|UI, Domain
-|Yes
-
-|`@Exploration`
-|Action available in special 'exploration' mode.
-|`@Action#restrictTo()` (combines exploration and prototyping modes).
-|UI
-|
-
-|`@FieldOrder`
-|Order of properties and collections.
-|`@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 `@Action#hidden()`, `@Property#hidden()` or `@Collection#hidden()`. +
-For domain service, use `@DomainService(nature=DOMAIN)`
-|UI, Domain
-|Yes
-
-|`@Idempotent`
-|Whether an action is idempotent (can be invoked multiple times with same post-condition).
-|`@Action#semantics`
-|Domain
-|
-
-|`@Ignore`
-|Exclude this method from the metamodel.
-|`@Programmatic`
-|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.
-|`@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 `@Property` or `@Parameter`
-|Domain
-|
-
-|`@MemberGroups`
-|Layout of properties and collections of a domain object or view model object.
-|`@MemberGroupLayout` or dynamic layout.
-|UI
-|Yes
-
-|`@MultiLine`
-|Render string property over multiple lines (a textarea rather than a textbox).
-|`#multiLine()` attribute for `@PropertyLayout` and`@ParameterLayout`
-|UI
-|Yes
-
-|`@MustSatisfy`
-|Specify arbitrary specification constraints on a property or action parameter.
-|`#mustSatisfy()` attribute for `@Property` and `@Parameter`
-|Domain
-|
-
-|`@Named`
-|Override name inferred from class. Required for parameter names (prior to Java8).
-|`#named()` attribute for `@DomainServiceLayout`, `@DomainObjectLayout`, `@PropertyLayout`, `@CollectionLayout`, `@ActionLayout` and `@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 `@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 `@ActionLayout` 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).
-|`@DomainService#nature()` to specify 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).
-|`@Property#notPersisted()`
-|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
-|`@DomainObject#objectType()`
-|Domain
-|
-
-|`@Optional`
-|Specifies that a property or action parameter is not mandatory.
-|`#optionality()` attribute for `@Property` or `@Parameter`
-|Domain
-|
-
-|`@Paged`
-|Number of instances to display in tables representing (standalone or parented) collections.
-|`#paged()` attribute for `@DomainObjectLayout` or `@CollectionLayout`
-|UI
-|Yes
-
-|`@Plural`
-|For the irregular plural form of an entity type.
-|`@DomainObjectLayout#plural()`
-|UI
-|
-
-|`@PostsAction` +
-`InvokedEvent`
-|Post a domain event to the Event Bus Service indicating that an action has been invoked.
-|`@Action#domainEvent()`
-|Domain
-|
-
-|`@PostsCollection` +
-`AddedToEvent`
-|Post a domain event to the Event Bus Service indicating that an element has been added to a collection.
-|`@Collection#domainEvent()`
-|Domain
-|
-
-|`@PostsCollection` +
-`RemovedFromEvent`
-|Post a domain event to the Event Bus Service indicating that an element has been removed from a collection.
-|`@Collection#domainEvent()`
-|Domain
-|
-
-|`@PostsProperty` +
-`ChangedEvent`
-|Post a domain event to the Event Bus Service indicating that the value of a property has changed.
-|`@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.
-|`@Property#domainEvent()`
-|Domain
-|
-
-|`@Prototype`
-|Indicates that an action should only be visible in 'prototype' mode.
-|`@Action#restrictTo()`
-|UI
-|Yes
-
-|`@PublishedAction`
-|Action invocation should be serialized and published by configured PublishingService (if any), eg to other systems.|`@Action#publishing()`
-|Domain
-|
-
-|`@PublishedObject`
-|Change to object should be serialized and published by configured PublishingService (if any), eg to other systems.
-|`@DomainObject#publishing()`
-|Domain
-|
-
-|`@QueryOnly`
-|Whether an action is query-only (has no side-effects).
-|`@Action#semantics()`
-|Domain
-|
-
-|`@RegEx`
-|Validate change to value of string property.
-|`#regexPattern()` for `@Property` or `@Parameter`.
-|Domain
-|
-
-|`@Render`
-|Eagerly (or lazily) render the contents of a collection.
-|`@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 `@PropertyLayout` and `@ParameterLayout`.
-|UI
-|
-
-|`@Resolve`
-|Eagerly (or lazily) render the contents of a collection (same as `@Render)`
-|`@CollectionLayout#render()`
-|UI
-|Yes
-
-|`@SortedBy`
-|Display instances in collections in the order determined by the provided Comparator.
-|`@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 `@Collection` and `@Action`
-|Domain
-|
-
-|`@TypicalLength`
-|The typical length of a string property, eg to determine a sensible length for a textbox.
-|`#typicalLength()` attribute for `@PropertyLayout` and `@ParameterLayout`
-|UI
-|Yes
-
-|===
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_aaa_jee.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_aaa_jee.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_aaa_jee.adoc
deleted file mode 100644
index 75015ff..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_aaa_jee.adoc
+++ /dev/null
@@ -1,35 +0,0 @@
-= 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/
-
-
-
-.Java EE Annotations
-[cols="2,4a,1,1", options="header"]
-|===
-|Annotation
-|Purpose
-|Layer
-|`.layout +
-.json`?
-
-|<<__code_requestscoped_code_javax, `@javax.enterprise.context.RequestScoped`>>
-|Specify that a domain service has request-scope (rather than a singleton).
-|Domain
-|
-
-|<<__code_inject_code_javax, `@javax.inject.Inject`>>
-|Inject domain service into a domain object (entity or view model) or another domain service.
-|Domain
-|
-
-|<<__code_digits_code_javax, `@javax.validation.constraints.Digits`>>
-|Precision/scale for BigDecimal values.
-|Domain
-|
-
-|===
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_aaa_main.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_aaa_main.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_aaa_main.adoc
deleted file mode 100644
index cc44f08..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_aaa_main.adoc
+++ /dev/null
@@ -1,91 +0,0 @@
-= 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/
-
-
-
-.Core annotations for domain objects, services and members (as of 1.8.0)
-[cols="2,4a,1,1", options="header"]
-|===
-|Annotation
-|Purpose
-|Layer
-|`.layout +
-.json`?
-
-|<<__code_action_code, `@Action`>>
-|Domain semantics for actions
-|Domain
-|
-
-|<<__code_actionlayout_code, `@ActionLayout`>>
-|User interface hints for actions
-|UI
-|Yes
-
-|<<__code_collection_code, `@Collection`>>
-|Domain semantics for collections
-|Domain
-|
-
-|<<__code_collectionlayout_code, `@CollectionLayout`>>
-|User interface hints for collections
-|UI
-|Yes
-
-|<<__code_domainobject_code, `@DomainObject`>>
-|Domain semantics for domain object (entities and optionally view models, see also `@ViewModel)`
-|Domain
-|
-
-|<<__code_domainobjectlayout_code, `@DomainObjectLayout`>>
-|User interface hints for domain object (entities and optionally view models, see also `@ViewModelLayout)`
-|UI
-|Yes
-
-|<<__code_domainservice_code, `@DomainService`>>
-|Class is a domain service (rather than an entity or view model)
-|Domain
-|
-
-|<<__code_domainservicelayout_code, `@DomainServiceLayout`>>
-|User interface hints for domain services
-|UI
-|
-
-|<<__code_parameter_code, `@Parameter`>>
-|Domain semantics for action parameters
-|Domain
-|
-
-|<<__code_propertylayout_code, `@PropertyLayout`>>
-|Layout hints for an action parameter (currently: its label position either to top or the left).
-|UI
-|Yes
-
-|<<__code_property_code, `@Property`>>
-|Domain semantics for properties
-|Domain
-|
-
-|<<__code_propertylayout_code, `@PropertyLayout`>>
-|Layout hints for a property
-|UI
-|Yes
-
-|<<__code_viewmodel_code, `@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
-|
-
-|<<__code_ViewModelLayout_code, `@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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_aaa_other.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_aaa_other.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_aaa_other.adoc
deleted file mode 100644
index b71247b..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_aaa_other.adoc
+++ /dev/null
@@ -1,55 +0,0 @@
-= 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/
-
-
-
-.Other Isis Annotations
-[cols="2,4a,1,1", options="header"]
-|===
-|Annotation
-|Purpose
-|Layer
-|`.layout +
-.json`?
-
-|<<__code_facets_code, `@Facets`>>
-|Install arbitrary facets within the Isis metamodel.
-|(any)
-|
-
-|<<__code_homepage_code, `@HomePage`>>
-|Query-only action (on domain service) to be invoked, result of which is rendered as the user's home page.
-|UI
-|
-
-|<<__code_membergrouplayout_code, `@MemberGroupLayout`>>
-|Grouping of properties into groups, and organizing of properties, collections into columns.
-|UI
-|Yes
-
-
-|<<__code_memberorder_code, `@MemberOrder`>>
-|Ordering of properties, collections and actions, and also associating actions with either a property or a collection.
-|UI
-|Yes
-
-
-|<<__code_programmatic_code, `@Programmatic`>>
-|Ignore a public method, excluded from the Isis metamodel.
-|Domain
-|
-
-|<<__code_minlength_code, `@MinLength`>>
-|Minimum number of characters required for an auto-complete search argument.
-|UI
-|
-
-|<<__code_title_code, `@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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_aaa_partial.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_aaa_partial.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_aaa_partial.adoc
deleted file mode 100644
index cbc33ad..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_aaa_partial.adoc
+++ /dev/null
@@ -1,43 +0,0 @@
-= 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/
-
-
-
-.Annotations with incomplete/partial support
-[cols="2,4a,1", options="header"]
-|===
-|Annotation
-|Purpose
-|Layer
-
-|`@Aggregated`
-|Part of an aggregate root
-|Domain, Persistence
-
-|`@Defaulted`
-|Indicates that a (value) class has a default value.
-|Domain
-
-|`@Encodable`
-|Indicates that a (value) class can be serialized/encoded.
-|Persistence
-
-|`@EqualByContent`
-|Indicates that a value class has equality semantics.
-|Domain
-
-|`@NotPersistable`
-|Indicates that a domain object may not be programmatically persisted (partly supported).
-|Domain, Persistence
-
-|`@Parseable`
-|Indicates that a (value) class can be reconstructed from a string.
-|UI, Domain
-
-|`@Value`
-|Specify that a class has value-semantics.
-|Domain
-
-|===
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_action.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_action.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_action.adoc
deleted file mode 100644
index a12816b..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_action.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `@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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_actionlayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_actionlayout.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_actionlayout.adoc
deleted file mode 100644
index 12e0e63..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_actionlayout.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `@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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_collection.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_collection.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_collection.adoc
deleted file mode 100644
index 7d4e2c2..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_collection.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `@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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_collectionlayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_collectionlayout.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_collectionlayout.adoc
deleted file mode 100644
index 37b1f55..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_collectionlayout.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `@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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_digits.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_digits.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_digits.adoc
deleted file mode 100644
index 57fac81..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_digits.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `@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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_domainobject.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_domainobject.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_domainobject.adoc
deleted file mode 100644
index 33bc0f1..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_domainobject.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `@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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_domainobjectlayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_domainobjectlayout.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_domainobjectlayout.adoc
deleted file mode 100644
index 87bf7a0..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_domainobjectlayout.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `@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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_domainservice.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_domainservice.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_domainservice.adoc
deleted file mode 100644
index b9c58dc..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_domainservice.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `@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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_domainservicelayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_domainservicelayout.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_domainservicelayout.adoc
deleted file mode 100644
index fd9e2b4..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_domainservicelayout.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `@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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_facets.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_facets.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_facets.adoc
deleted file mode 100644
index 0cf9a83..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_facets.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `@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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_homepage.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_homepage.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_homepage.adoc
deleted file mode 100644
index bb836b2..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_homepage.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `@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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_inject.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_inject.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_inject.adoc
deleted file mode 100644
index 887ca24..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_inject.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `@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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_membergrouplayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_membergrouplayout.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_membergrouplayout.adoc
deleted file mode 100644
index c452aa9..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_membergrouplayout.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `@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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_memberorder.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_memberorder.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_memberorder.adoc
deleted file mode 100644
index c452aa9..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_memberorder.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `@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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_minlength.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_minlength.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_minlength.adoc
deleted file mode 100644
index 4ae8092..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_minlength.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `@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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_parameter.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_parameter.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_parameter.adoc
deleted file mode 100644
index 6bcf579..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_parameter.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `@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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_programmatic.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_programmatic.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_programmatic.adoc
deleted file mode 100644
index 6872f5c..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_programmatic.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `@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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_property.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_property.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_property.adoc
deleted file mode 100644
index 6d800fe..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_property.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `@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
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_propertylayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_propertylayout.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_propertylayout.adoc
deleted file mode 100644
index bb22a8d..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_propertylayout.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `@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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_requestscoped.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_requestscoped.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_requestscoped.adoc
deleted file mode 100644
index 5f59691..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_requestscoped.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `@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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_title.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_title.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_title.adoc
deleted file mode 100644
index df89289..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_title.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `@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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_viewmodel.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_viewmodel.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_viewmodel.adoc
deleted file mode 100644
index 606ea84..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_viewmodel.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `@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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_viewmodellayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_viewmodellayout.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_viewmodellayout.adoc
deleted file mode 100644
index 95bc856..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations_manpage_viewmodellayout.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `@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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_applib-utility-classes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_applib-utility-classes.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_applib-utility-classes.adoc
deleted file mode 100644
index f684ebe..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_applib-utility-classes.adoc
+++ /dev/null
@@ -1,144 +0,0 @@
-= 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.
-
-== Title creation
-
-The `TitleBuffer` utility class is intended to make it easy to construct
-title strings (returned from the `title()` method). For example, it has
-overloaded versions of methods called `append()` and `concat()`.
-
-== Reason text creation (for disable and validate methods)
-
-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.
-
-== ObjectContracts
-
-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
-----
-#
-# Require explicit persistence (since entities are Comparable and using ObjectContracts#compareTo).
-#
-isis.persistor.datanucleus.impl.datanucleus.persistenceByReachabilityAtCommit=false
-----
-
-====
-
-### Explanation of 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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_methods.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_methods.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_methods.adoc
deleted file mode 100644
index 49106b3..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_methods.adoc
+++ /dev/null
@@ -1,14 +0,0 @@
-= 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/
-
-
-
-include::_user-guide_reference_methods_aaa.adoc[leveloffset=+1]
-
-
-include::_user-guide_reference_methods_manpage_cssClass.adoc[leveloffset=+1]
-include::_user-guide_reference_methods_manpage_iconName.adoc[leveloffset=+1]
-include::_user-guide_reference_methods_manpage_getId.adoc[leveloffset=+1]
-include::_user-guide_reference_methods_manpage_title.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_methods_aaa.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_methods_aaa.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_methods_aaa.adoc
deleted file mode 100644
index 7c83936..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_methods_aaa.adoc
+++ /dev/null
@@ -1,117 +0,0 @@
-= 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/
-
-
-
-
-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
-
-|<<__code_cssclass_code, `cssClass()`>>
-|Provides a CSS class for this object, which is added as a style in the containing when rendering the object within a table, or to a containing when rendering the object on a page. In conjunction with css/application.css, can therefore provide custom styling of an object instance wherever it is rendered.
-See also <<__code_title_code, `title()`>> and <<__code_iconName_code, `iconName()`>>.
-
-|<<__code_iconname_code, `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 <<__code_title_code, `title()`>> and <<__code_cssClass_code, `cssClass()`>>
-
-|<<__code_getid_code, `getId()`>>
-|Provides an optional unique identifier of a service. +
-If not provided, the services fully-qualified class name is used.
-
-|<<__code_title_code, `title()`>>
-|Provides a title for the object. +
-Alternatively, use the <<__code_title_code, `@Title`>> annotation. +
-See also `iconName()` and <<__code_cssClass_code, `cssClass()`>>
-
-|===
-
-
-
-
-
-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]
-====
-We believe there may some scenarios (not yet fully catalogued) where the lifecycle method is not called. As such we recommend that you don't rely on these methods and/or fully test they are called as required in your apps
-
-As an alternative, consider using Isis' event bus and domain events.
-====
-
-The lifecycle methods are:
-
-.Lifecycle methods (partial support)
-[cols="1,4a", options="header"]
-|===
-
-|Method
-|Description
-
-|<<__code_created_code, `created()`>>
-|called when an object has just been created using <<__code_newTransientInstance_code, `newTransientInstance()`>>
-
-|<<__code_loaded_code, `loaded()`>>
-|called when a (persistent) object has just been loaded from the object store.
-
-|<<__code_persisted_code, `persisted()`>>
-|called when object has just been persisted from the object store.
-
-|<<__code_persisting_code, `persisting()`>>
-|called when a (not-yet-persistent) object is just about to be persisted from the object store
-
-|<<__code_removed_code, `removed()`>>
-|called when a (persistent) object has just been persisted from the object store
-
-|<<__code_removing_code, `removing()`>>
-|called when a (persistent) object is just about to be deleted from the object store
-
-|<<__code_updated_code, `updated()`>>
-|called when a (persistent) object has just been updated in the object store
-
-|<<__code_updating_code, `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 <<__code_removed_code, `removed()`>>
-
-|`deleting()`
-|Replaced by 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 persisted()`
-
-|`saving()`
-|Replaced by <<__code_persisting_code, `persisting()`>>
-
-|===
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_methods_manpage_cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_methods_manpage_cssClass.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_methods_manpage_cssClass.adoc
deleted file mode 100644
index 1dc6a67..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_methods_manpage_cssClass.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_methods_manpage_getId.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_methods_manpage_getId.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_methods_manpage_getId.adoc
deleted file mode 100644
index 75586c0..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_methods_manpage_getId.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_methods_manpage_iconName.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_methods_manpage_iconName.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_methods_manpage_iconName.adoc
deleted file mode 100644
index 521649e..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_methods_manpage_iconName.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_methods_manpage_title.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_methods_manpage_title.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_methods_manpage_title.adoc
deleted file mode 100644
index 1533a74..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_methods_manpage_title.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_mixins.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_mixins.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_mixins.adoc
deleted file mode 100644
index 13634f8..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_mixins.adoc
+++ /dev/null
@@ -1,11 +0,0 @@
-= 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/
-
-
-IMPORTANT: TODO
-
-== `HasTransactionId`
-
-== `HasUsername`
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes.adoc
deleted file mode 100644
index 2cd4338..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes.adoc
+++ /dev/null
@@ -1,27 +0,0 @@
-= Recognized 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/
-
-
-
-include::_user-guide_reference_prefixes_aaa.adoc[leveloffset=+1]
-
-include::_user-guide_reference_prefixes_manpage_addTo.adoc[leveloffset=+1]
-include::_user-guide_reference_prefixes_manpage_autoComplete.adoc[leveloffset=+1]
-include::_user-guide_reference_prefixes_manpage_choices.adoc[leveloffset=+1]
-include::_user-guide_reference_prefixes_manpage_clear.adoc[leveloffset=+1]
-include::_user-guide_reference_prefixes_manpage_default.adoc[leveloffset=+1]
-include::_user-guide_reference_prefixes_manpage_disable.adoc[leveloffset=+1]
-include::_user-guide_reference_prefixes_manpage_get.adoc[leveloffset=+1]
-include::_user-guide_reference_prefixes_manpage_hide.adoc[leveloffset=+1]
-include::_user-guide_reference_prefixes_manpage_modify.adoc[leveloffset=+1]
-include::_user-guide_reference_prefixes_manpage_removeFrom.adoc[leveloffset=+1]
-include::_user-guide_reference_prefixes_manpage_set.adoc[leveloffset=+1]
-include::_user-guide_reference_prefixes_manpage_validate.adoc[leveloffset=+1]
-include::_user-guide_reference_prefixes_manpage_validateAddTo.adoc[leveloffset=+1]
-include::_user-guide_reference_prefixes_manpage_validateRemoveFrom.adoc[leveloffset=+1]
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_aaa.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_aaa.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_aaa.adoc
deleted file mode 100644
index ea45d56..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_aaa.adoc
+++ /dev/null
@@ -1,151 +0,0 @@
-= 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/
-
-
-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
-
-|<<__code_addto_code, `addTo...()`>>
-|
-|
-|Y
-|
-|
-|add object to a collection (nb: not currently supported by Wicket viewer) +
-See also <<__code_removefrom_code, `removeFrom...()`>>`
-
-|<<__code_autocomplete_code, `autoComplete...()`>>
-|
-|Y
-|
-|
-|Y
-|Return a list of matching elements for a property or an action parameter. +
-Alternatively, can specify for a class using <<__code_domainobject_code, `@DomainObject#autoComplete`>> +
-+
-See also choices
-
-|<<__code_choices_code, `choices...()`>>
-|
-|Y
-|
-|
-|Y
-|Provide list of choices for a property or action parameter
-See also <<__code_autocomplete_code, `autoComplete...()`>>.
-
-|<<__code_clear_code, `clear...()`>>
-|
-|Y
-|
-|
-|
-|Clear a property (set it to null). Allows business logic to be placed apart from the setter.
-See also <<__code_modify_code, `modify...()`>>
-
-
-|<<__code_default_code, `default...()`>>
-|
-|Y
-|
-|
-|Y
-|Default value for a property or an action parameter.
-
-|<<__code_disable_code, `disable...()`>>
-|Y
-|Y
-|Y
-|Y
-|
-|Disables (makes read-only) a property, a collection or an action.
-
-|<<__code_get_code, `get...()`>>
-|
-|Y
-|Y
-|
-|
-|Access the value of a property or collection. +
-See also <<__code_set_code, `set...()`>>.
-
-|<<__code_hide_code, `hide...()`>>
-|
-|Y
-|Y
-|Y
-|
-|Hides a property, a collection or an action.
-
-|<<__code_modify_code, `modify...()`>>
-|
-|Y
-|
-|
-|
-|Modify a property (set it to a non-null) value. Allows business logic to be placed apart from the setter. +
-See also <<__code_clear_code, `clear...()`>>`.
-
-|<<__code_removeFrom_code, `removeFrom...()`>>
-|
-|
-|Y
-|
-|
-|remove object from a collection (nb: not currently supported by Wicket viewer) +
-See also <<__code_addto_code, `addTo...()`>>`
-
-|<<__code_set_code, `set...()`>>
-|
-|Y
-|Y
-|
-|
-|Sets the value of a property or a collection.
-
-|<<__code_validate_code, `validate...()`>>
-|Y
-|
-|
-|Y
-|Y
-|Check that a proposed value of a property or an action parameter is valid. +
-See also <<__code_validateaddto_code, validateAddTo...()`>> and <<__code_validateremovefrom_code, `validateRemoveFrom...()`>> for collections.
-
-|<<__code_validateaddto_code, `validate +
-AddTo...()`>>
-|
-|Y
-|
-|
-|
-|Check that a proposed object to add to a collection is valid. +
-See also <<__code_validateremovefrom_code, `validateRemoveFrom...()`>>, and <<__code_validate_code, `validate...()`>> for properties and collections.
-
-|<<__code_validateremovefrom_code, `validate +
-RemoveFrom...()`>>
-|
-|Y
-|
-|
-|
-|Check that a proposed object to add to a collection is valid.
-See also <<__code_validateaddto_code, `validateAddTo...()`>>, and <<__code_validate_code, `validate...()`>> for properties and collections.
-
-|===
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_addTo.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_addTo.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_addTo.adoc
deleted file mode 100644
index 73a8ebb..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_addTo.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_autoComplete.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_autoComplete.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_autoComplete.adoc
deleted file mode 100644
index 1b4cfd1..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_autoComplete.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_choices.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_choices.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_choices.adoc
deleted file mode 100644
index 4406b14..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_choices.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `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/
-
-IMPORTANT: TODO
-
-
[22/22] isis git commit: ISIS-1133: updated user-guide to include all
content;
Posted by da...@apache.org.
ISIS-1133: updated user-guide to include all content;
also downgraded enforcer check for mvn to 3.0.5, for Cloudbees
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/84048768
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/84048768
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/84048768
Branch: refs/heads/master
Commit: 8404876848821b6f0cebc8af543e4b5553b06ebd
Parents: 6369716
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Mon May 18 07:26:01 2015 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Mon May 18 07:26:01 2015 +0100
----------------------------------------------------------------------
.../main/asciidoc/user-guide/user-guide.adoc | 29 ++++++++++----------
core/pom.xml | 2 +-
2 files changed, 16 insertions(+), 15 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/84048768/adocs/documentation/src/main/asciidoc/user-guide/user-guide.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/user-guide.adoc b/adocs/documentation/src/main/asciidoc/user-guide/user-guide.adoc
index 300bc2f..54c9878 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/user-guide.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/user-guide.adoc
@@ -4,19 +4,20 @@
:_imagesdir: images/
:numbered:
-//include::_ug_core-concepts.adoc[leveloffset=+1]
-//include::_ug_getting-started.adoc[leveloffset=+1]
-//include::_ug_how-tos.adoc[leveloffset=+1]
-//include::_ug_more-advanced.adoc[leveloffset=+1]
-//include::_ug_reference.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_core-concepts.adoc[leveloffset=+1]
+include::_ug_getting-started.adoc[leveloffset=+1]
+include::_ug_how-tos.adoc[leveloffset=+1]
+include::_ug_more-advanced.adoc[leveloffset=+1]
+include::_ug_reference.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_deployment.adoc[leveloffset=+1]
+include::_ug_deployment.adoc[leveloffset=+1]
include::_ug_testing.adoc[leveloffset=+1]
-//include::_ug_headless-access.adoc[leveloffset=+1]
-//include::_ug_isis-addons-modules.adoc[leveloffset=+1]
-//include::_ug_extending.adoc[leveloffset=+1]
-//include::_ug_troubleshooting.adoc[leveloffset=+1]
-//include::_ug_appendices.adoc[leveloffset=+1]
+include::_ug_headless-access.adoc[leveloffset=+1]
+include::_ug_isis-addons-modules.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/84048768/core/pom.xml
----------------------------------------------------------------------
diff --git a/core/pom.xml b/core/pom.xml
index 327ae36..9851d1c 100644
--- a/core/pom.xml
+++ b/core/pom.xml
@@ -920,7 +920,7 @@
<configuration>
<rules>
<requireMavenVersion>
- <version>[3.1.1,)</version>
+ <version>[3.0.5,)</version>
</requireMavenVersion>
<requireJavaVersion>
<version>[1.8.0,)</version>
[19/22] isis git commit: ISIS-1133: renamed _user-guide_ to _ug_
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..5825c02
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_philosophy.adoc
@@ -0,0 +1,20 @@
+= 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::_user-guide_core-concepts_philosophy_domain-driven-design.adoc[leveloffset=+1]
+
+include::_user-guide_core-concepts_philosophy_naked-objects-pattern.adoc[leveloffset=+1]
+
+include::_user-guide_core-concepts_philosophy_hexagonal-architecture.adoc[leveloffset=+1]
+
+include::_user-guide_core-concepts_philosophy_aop.adoc[leveloffset=+1]
+
+// include::_user-guide_core-concepts_philosophy_dci.adoc[leveloffset=+1]
+
+include::_user-guide_core-concepts_philosophy_how-eases-ddd.adoc[leveloffset=+1]
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..0ea9a10
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_philosophy_aop.adoc
@@ -0,0 +1,35 @@
+= 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 <<_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 <<_decoupling, Decoupling>> chapter. 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 <<_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 bein
g 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 (<<_contributed_members, contributions>>) and interceptors (the <<_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/97531ca0/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
new file mode 100644
index 0000000..eb54833
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_philosophy_dci.adoc
@@ -0,0 +1,8 @@
+= 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/97531ca0/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
new file mode 100644
index 0000000..0eb7be6
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_philosophy_domain-driven-design.adoc
@@ -0,0 +1,79 @@
+= 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/97531ca0/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
new file mode 100644
index 0000000..47a05a1
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_philosophy_hexagonal-architecture.adoc
@@ -0,0 +1,28 @@
+= 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/97531ca0/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
new file mode 100644
index 0000000..275c4fb
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_philosophy_how-eases-ddd.adoc
@@ -0,0 +1,73 @@
+= 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 <<_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/97531ca0/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
new file mode 100644
index 0000000..ec6d671
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_philosophy_naked-objects-pattern.adoc
@@ -0,0 +1,54 @@
+= 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: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 http://isisaddons.org[Isis Addons] (non-ASF) the http://github.com/isisaddons/isis-wicket-gmap3}[Isis addons' gmap3 modue] 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.
+====
+
+== Object Interface Mapping
+
+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 <<_vs_metawidget,here>>.
+====
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..543ec76
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_principles.adoc
@@ -0,0 +1,17 @@
+= 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::_user-guide_core-concepts_principles_your-apps.adoc[leveloffset=+1]
+
+include::_user-guide_core-concepts_principles_isis-itself.adoc[leveloffset=+1]
+
+include::_user-guide_core-concepts_principles_apache-isis-vs.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..6290e10
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_principles_apache-isis-vs.adoc
@@ -0,0 +1,36 @@
+= 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?
+
+## vs MVC server-side frameworks
+
+Some of most commonly used frameworks today are link:http://www.springframework.org/[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 <<_extending_the_viewer, extending Isis' Wicket viewer>> or by writing a bespoke UI leveraging the REST (hypermedia) API automatically exposed by <<_restful_objects_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 http://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 "<<_using_the_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.
+
+
+## vs Angular
+
+## vs MetaWidget
+
+MetaWidget (mentioned <<_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 http://isisaddons.org[Isis Addons] (non-ASF), and we also provide a full <<_restful_objects_viewer,Restful API>>
+
+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.
+
+
+## vs OpenXava
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..b48230c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_principles_isis-itself.adoc
@@ -0,0 +1,46 @@
+= 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/97531ca0/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
new file mode 100644
index 0000000..fcfb767
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts_principles_your-apps.adoc
@@ -0,0 +1,38 @@
+= 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: TODO
+
+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/97531ca0/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
new file mode 100644
index 0000000..26fdede
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment.adoc
@@ -0,0 +1,19 @@
+= 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::_user-guide_deployment_cmd-line.adoc[leveloffset=+1]
+
+include::_user-guide_deployment_tomcat.adoc[leveloffset=+1]
+
+include::_user-guide_deployment_gae.adoc[leveloffset=+1]
+
+include::_user-guide_deployment_jvm-flags.adoc[leveloffset=+1]
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..5c936d6
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment_cmd-line.adoc
@@ -0,0 +1,29 @@
+= 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/97531ca0/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
new file mode 100644
index 0000000..938a247
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment_gae.adoc
@@ -0,0 +1,459 @@
+= 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 https://developers.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:
+
+____
+
+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.
+
+____
+
+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.
+
+=== A GAE compatible version of `ToDoItem.java`
+
+... as per the http://github.com/isisaddons/isis-app-todoapp}[Isis addons' todoapp] (non-ASF), is as follows:
+
+[source,java]
+----
+@javax.jdo.annotations.Queries( {
+ @javax.jdo.annotations.Query(
+ name="todo_all", language="JDOQL",
+ value="SELECT FROM dom.todo.ToDoItem WHERE ownedBy == :ownedBy"),
+ @javax.jdo.annotations.Query(
+ name="todo_notYetComplete", language="JDOQL",
+ value="SELECT FROM dom.todo.ToDoItem WHERE ownedBy == :ownedBy && complete == false"),
+ @javax.jdo.annotations.Query(
+ name="todo_complete", language="JDOQL",
+ value="SELECT FROM dom.todo.ToDoItem WHERE ownedBy == :ownedBy && complete == true"),
+ @javax.jdo.annotations.Query(
+ name="todo_similarTo", language="JDOQL",
+ value="SELECT FROM dom.todo.ToDoItem WHERE ownedBy == :ownedBy && category == :category"),
+ @javax.jdo.annotations.Query(
+ name="todo_autoComplete", language="JDOQL",
+ value="SELECT FROM dom.todo.ToDoItem WHERE ownedBy == :ownedBy && description.startsWith(:description)")
+})
+@javax.jdo.annotations.Version(strategy= VersionStrategy.VERSION_NUMBER, column="VERSION")
+@ObjectType("TODO")
+@Auditable
+@AutoComplete(repository=ToDoItems.class, action="autoComplete")
+@MemberGroups({"General", "Detail"})
+@javax.jdo.annotations.PersistenceCapable
+public class ToDoItem implements Comparable<ToDoItem> {
+// @PrimaryKey
+// @Persistent(valueStrategy = javax.jdo.annotations.IdGeneratorStrategy.IDENTITY)
+// @Extension(vendorName="datanucleus", key="gae.encoded-pk", value="true")
+// private String key;
+ @Persistent(valueStrategy=IdGeneratorStrategy.IDENTITY)
+ @PrimaryKey
+ private Long id;
+
+ private static final long ONE_WEEK_IN_MILLIS = 7 * 24 * 60 * 60 * 1000L;
+
+ public static enum Category {
+ Professional, Domestic, Other;
+ }
+
+ // {{ Identification on the UI
+ public String title() {
+ final TitleBuffer buf = new TitleBuffer();
+ buf.append(getDescription());
+ if (isComplete()) {
+ buf.append(" - Completed!");
+ } else {
+ if (getDueBy() != null) {
+ SimpleDateFormat sdf = new SimpleDateFormat("dd-MM-yyyy");
+ buf.append(" due by ", sdf.format(getDueBy()));
+ }
+ }
+ return buf.toString();
+ }
+
+ // }}
+
+ // {{ Description
+ private String description;
+
+ @RegEx(validation = "\\w[@&:\\-\\,\\.\\+ \\w]*")
+ // words, spaces and selected punctuation
+ @MemberOrder(sequence = "1")
+ @DescribedAs("Enter the description")
+ public String getDescription() {
+ return description;
+ }
+
+ public void setDescription(final String description) {
+ this.description = description;
+ }
+ // }}
+
+ // {{ DueBy (property)
+ private Date dueBy;
+
+ @javax.jdo.annotations.Persistent
+ @MemberOrder(name="Detail", sequence = "3")
+ @Optional
+ @DescribedAs("Enter the date")
+ public Date getDueBy() {
+ return dueBy;
+ }
+
+ public void setDueBy(final Date dueBy) {
+ this.dueBy = dueBy;
+ }
+ public void clearDueBy() {
+ setDueBy(null);
+ }
+ // proposed new value is validated before setting
+ public String validateDueBy(final Date dueBy) {
+ if (dueBy == null) {
+ return null;
+ }
+ return isMoreThanOneWeekInPast(dueBy) ? "Due by date cannot be more than one week old" : null;
+ }
+ // }}
+
+ // {{ Category
+ private Category category;
+
+ @MemberOrder(sequence = "2")
+ @DescribedAs("Enter the category")
+ public Category getCategory() {
+ return category;
+ }
+
+ public void setCategory(final Category category) {
+ this.category = category;
+ }
+ // }}
+
+ // {{ OwnedBy (property)
+ private String ownedBy;
+
+ @Hidden
+ // not shown in the UI
+ public String getOwnedBy() {
+ return ownedBy;
+ }
+
+ public void setOwnedBy(final String ownedBy) {
+ this.ownedBy = ownedBy;
+ }
+
+ // }}
+
+ // {{ Complete (property)
+ private boolean complete;
+
+ @Disabled
+ // cannot be edited as a property
+ @MemberOrder(sequence = "4")
+ public boolean isComplete() {
+ return complete;
+ }
+
+ public void setComplete(final boolean complete) {
+ this.complete = complete;
+ }
+
+ // {{ Notes (property)
+ private String notes;
+
+ @Hidden(where=Where.ALL_TABLES)
+ @Optional
+ @MultiLine(numberOfLines=4)
+ @MemberOrder(name="Detail", sequence = "6")
+ public String getNotes() {
+ return notes;
+ }
+
+ public void setNotes(final String notes) {
+ this.notes = notes;
+ }
+ // }}
+
+ // {{ Attachment (property)
+ private BlobKey attachment;
+
+ @Persistent
+ @Optional
+ @MemberOrder(name="Detail", sequence = "7")
+ public BlobKey getAttachment() {
+ return attachment;
+ }
+
+ public void setAttachment(final BlobKey attachment) {
+ this.attachment = attachment;
+ }
+ // }}
+
+ // {{ Version (derived property)
+ @Hidden(where=Where.ALL_TABLES)
+ @Disabled
+ @MemberOrder(name="Detail", sequence = "99")
+ @Named("Version")
+ public Long getVersionSequence() {
+ if(!(this instanceof PersistenceCapable)) {
+ return null;
+ }
+ PersistenceCapable persistenceCapable = (PersistenceCapable) this;
+ final Long version = (Long) JDOHelper.getVersion(persistenceCapable);
+ return version;
+ }
+ public boolean hideVersionSequence() {
+ return !(this instanceof PersistenceCapable);
+ }
+ // }}
+
+ // {{ completed (action)
+ @Bulk
+ @MemberOrder(sequence = "1")
+ public ToDoItem completed() {
+ setComplete(true);
+ return this;
+ }
+
+ // disable action dependent on state of object
+ public String disableCompleted() {
+ return complete ? "Already completed" : null;
+ }
+ // }}
+
+ // {{ notYetCompleted (action)
+ @MemberOrder(sequence = "2")
+ public ToDoItem notYetCompleted() {
+ setComplete(false);
+ return this;
+ }
+
+ // disable action dependent on state of object
+ public String disableNotYetCompleted() {
+ return !complete ? "Not yet completed" : null;
+ }
+ // }}
+
+ // {{ dependencies (Collection)
+ @Unowned
+ private List<ToDoItem> dependencies = new ArrayList<ToDoItem>();
+
+ @Disabled
+ @MemberOrder(sequence = "1")
+ @Resolve(Type.EAGERLY)
+ public List<ToDoItem> getDependencies() {
+ return dependencies;
+ }
+
+ public void setDependencies(final List<ToDoItem> dependencies) {
+ this.dependencies = dependencies;
+ }
+ // }}
+
+ // {{ add (action)
+ @MemberOrder(name="dependencies", sequence = "3")
+ public ToDoItem add(final ToDoItem toDoItem) {
+ getDependencies().add(toDoItem);
+ return this;
+ }
+ public String validateAdd(final ToDoItem toDoItem) {
+ if(getDependencies().contains(toDoItem)) {
+ return "Already a dependency";
+ }
+ if(toDoItem == this) {
+ return "Can't set up a dependency to self";
+ }
+ return null;
+ }
+ public List<ToDoItem> choices0Add() {
+ return toDoItems.allToDos();
+ }
+
+ // }}
+
+ // {{ remove (action)
+ @MemberOrder(name="dependencies", sequence = "4")
+ public ToDoItem remove(final ToDoItem toDoItem) {
+ getDependencies().remove(toDoItem);
+ return this;
+ }
+ public String disableRemove(final ToDoItem toDoItem) {
+ return getDependencies().isEmpty()? "No dependencies to remove": null;
+ }
+ public String validateRemove(final ToDoItem toDoItem) {
+ if(!getDependencies().contains(toDoItem)) {
+ return "Not a dependency";
+ }
+ return null;
+ }
+ public List<ToDoItem> choices0Remove() {
+ return getDependencies();
+ }
+ // }}
+
+ // {{ clone (action)
+ @Named("Clone")
+ // the name of the action in the UI
+ @MemberOrder(sequence = "3")
+ // nb: method is not called "clone()" is inherited by java.lang.Object and
+ // (a) has different semantics and (b) is in any case automatically ignored
+ // by the framework
+ public ToDoItem duplicate() {
+ return toDoItems.newToDo(getDescription() + " - Copy", getCategory(), getDueBy());
+ }
+ // }}
+
+ // {{ isDue (programmatic)
+ @Programmatic
+ // excluded from the framework's metamodel
+ public boolean isDue() {
+ if (getDueBy() == null) {
+ return false;
+ }
+ return !isMoreThanOneWeekInPast(getDueBy());
+ }
+
+ // }}
+
+ // {{ SimilarItems (derived collection)
+ @MemberOrder(sequence = "5")
+ @NotPersisted
+ @Resolve(Type.EAGERLY)
+ public List<ToDoItem> getSimilarItems() {
+ return toDoItems.similarTo(this);
+ }
+
+ // }}
+
+ // {{ compareTo (programmatic)
+ /**
+ * by complete flag, then due by date, then description
+ */
+ // exclude from the framework's metamodel
+ @Override
+ public int compareTo(final ToDoItem other) {
+ if (isComplete() && !other.isComplete()) {
+ return +1;
+ }
+ if (!isComplete() && other.isComplete()) {
+ return -1;
+ }
+ if (getDueBy() == null && other.getDueBy() != null) {
+ return +1;
+ }
+ if (getDueBy() != null && other.getDueBy() == null) {
+ return -1;
+ }
+ if (getDueBy() == null && other.getDueBy() == null || getDueBy().equals(this.getDueBy())) {
+ return getDescription().compareTo(other.getDescription());
+ }
+ return getDueBy().compareTo(getDueBy());
+ }
+ // }}
+
+ // {{ helpers
+ private static boolean isMoreThanOneWeekInPast(final Date dueBy) {
+ return dueBy.getTime() < Clock.getTime() - ONE_WEEK_IN_MILLIS;
+ }
+
+ // }}
+
+ // {{ filters (programmatic)
+ @SuppressWarnings("unchecked")
+ public static Filter<ToDoItem> thoseDue() {
+ return Filters.and(Filters.not(thoseComplete()), new Filter<ToDoItem>() {
+ @Override
+ public boolean accept(final ToDoItem t) {
+ return t.isDue();
+ }
+ });
+ }
+
+ public static Filter<ToDoItem> thoseComplete() {
+ return new Filter<ToDoItem>() {
+ @Override
+ public boolean accept(final ToDoItem t) {
+ return t.isComplete();
+ }
+ };
+ }
+
+ public static Filter<ToDoItem> thoseOwnedBy(final String currentUser) {
+ return new Filter<ToDoItem>() {
+ @Override
+ public boolean accept(final ToDoItem toDoItem) {
+ return Objects.equal(toDoItem.getOwnedBy(), currentUser);
+ }
+
+ };
+ }
+
+ public static Filter<ToDoItem> thoseSimilarTo(final ToDoItem toDoItem) {
+ return new Filter<ToDoItem>() {
+ @Override
+ public boolean accept(final ToDoItem eachToDoItem) {
+ return Objects.equal(toDoItem.getCategory(), eachToDoItem.getCategory()) &&
+ Objects.equal(toDoItem.getOwnedBy(), eachToDoItem.getOwnedBy()) &&
+ eachToDoItem != toDoItem;
+ }
+
+ };
+ }
+ // }}
+
+ // {{ injected: DomainObjectContainer
+ @SuppressWarnings("unused")
+ private DomainObjectContainer container;
+
+ public void setDomainObjectContainer(final DomainObjectContainer container) {
+ this.container = container;
+ }
+ // }}
+
+ // {{ injected: ToDoItems
+ private ToDoItems toDoItems;
+
+ public void setToDoItems(final ToDoItems toDoItems) {
+ this.toDoItems = toDoItems;
+ }
+ // }}
+
+}
+----
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..d359f52
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment_jvm-flags.adoc
@@ -0,0 +1,18 @@
+= 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
+
+
+for the `WrapperFactory` (uses link:http://www.csg.ci.i.u-tokyo.ac.jp/~chiba/javassist/[Javassist])
+
+using:
+
+[source]
+----
+-XX:+CMSClassUnloadingEnabled -XX:+UseConcMarkSweepGC
+----
+
+You can hint the JVM to unload dynamically created classes which ClassLoaders are still around.
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..d25dba6
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment_tomcat.adoc
@@ -0,0 +1,14 @@
+= 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
+
+eg Tomcat
+
+== Externalized Configuration
+
+== JVM Args
+
+== Using a JNDI Datasource
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..8f80ea4
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending.adoc
@@ -0,0 +1,13 @@
+= 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::_user-guide_extending_programming-model.adoc[leveloffset=+1]
+
+include::_user-guide_extending_wicket-viewer.adoc[leveloffset=+1]
+
+include::_user-guide_extending_restfulobjects-viewer.adoc[leveloffset=+1]
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..bd1e959
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_programming-model.adoc
@@ -0,0 +1,12 @@
+= Extending the Programming Model
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+include::_user-guide_extending_programming-model_custom-validator.adoc[leveloffset=+1]
+
+include::_user-guide_extending_programming-model_finetuning.adoc[leveloffset=+1]
+
+include::_user-guide_extending_programming-model_layout-metadata-reader.adoc[leveloffset=+1]
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..3ee496d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending_programming-model_custom-validator.adoc
@@ -0,0 +1,106 @@
+= 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 <<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' <<_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
+----
+
+
+
[13/22] isis git commit: ISIS-1133: renamed _user-guide_ to _ug_
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..5655fe2
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_api-for-applications.adoc
@@ -0,0 +1,61 @@
+= 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.
+
+
+== Using Isis` `DomainObjectContainer`
+
+The <<_domain_object_container, `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").
+
+
+
+== Accessing user/roles from the 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/97531ca0/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
new file mode 100644
index 0000000..f80fb37
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_configuring-isis-to-use-bypass.adoc
@@ -0,0 +1,24 @@
+= Bypass 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).
+
+
+== Specifying bypass as the security mechanism
+
+To tell Apache Isis to bypass security, 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/97531ca0/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
new file mode 100644
index 0000000..1515608
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_configuring-isis-to-use-shiro.adoc
@@ -0,0 +1,75 @@
+= 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 <<_simpleapp_archetype, SimpleApp archetype>> is pre-configured to use Apache Shiro, so much of what follows is set up already.
+====
+
+== Specifying Shiro as the security mechanism
+
+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/97531ca0/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
new file mode 100644
index 0000000..deb94b9
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-caching.adoc
@@ -0,0 +1,40 @@
+= 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/97531ca0/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
new file mode 100644
index 0000000..a1bad63
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-ini-realm.adoc
@@ -0,0 +1,132 @@
+= 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 <<_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]
+----
+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 <<_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/97531ca0/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
new file mode 100644
index 0000000..d94372d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-isis-enhanced-wildcard-permission.adoc
@@ -0,0 +1,62 @@
+= 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 <<_shiro_ini_realm, `IniRealm`>> or <<_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`.
+
+
+
+== Shiro Configuration
+
+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/97531ca0/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
new file mode 100644
index 0000000..59c0192
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-isis-ldap-realm.adoc
@@ -0,0 +1,145 @@
+= 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.
+====
+
+
+
+
+
+
+== Using a shared role/perms path
+
+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 Mini-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/97531ca0/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
new file mode 100644
index 0000000..7f99cb0
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-isisaddons-security-module-realm.adoc
@@ -0,0 +1,35 @@
+= 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/97531ca0/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
new file mode 100644
index 0000000..c90957d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-jdbc-realm.adoc
@@ -0,0 +1,114 @@
+= 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"]
+
+
+
+
+== Shiro Configuration
+
+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/a/23784702/56880[this StackOverflow answer].
+====
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..667adde
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_usage-by-isis-viewers.adoc
@@ -0,0 +1,207 @@
+= 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 <<_wicket_viewer, Wicket Viewer>> and <<_restful_objects_viewer, Restful viewer>>, and the overall <<_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 <<_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 <<_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 <<_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 <<_custom_pages, extensions chapter>> for details.
+====
+
+User registration is only available if the <<_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 <<_restful_objects_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/97531ca0/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
new file mode 100644
index 0000000..7acc994
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing.adoc
@@ -0,0 +1,16 @@
+= 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::_user-guide_testing_overview.adoc[leveloffset=+1]
+include::_user-guide_testing_unit-test-support.adoc[leveloffset=+1]
+include::_user-guide_testing_integ-test-support.adoc[leveloffset=+1]
+include::_user-guide_testing_bdd-spec-support.adoc[leveloffset=+1]
+include::_user-guide_testing_fixture-scripts.adoc[leveloffset=+1]
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..68569c1
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support.adoc
@@ -0,0 +1,21 @@
+= 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::_user-guide_testing_bdd-spec-support_how-it-works.adoc[leveloffset=+1]
+include::_user-guide_testing_bdd-spec-support_key-classes.adoc[leveloffset=+1]
+include::_user-guide_testing_bdd-spec-support_writing-a-bdd-spec.adoc[leveloffset=+1]
+include::_user-guide_testing_bdd-spec-support_bdd-tooling.adoc[leveloffset=+1]
+include::_user-guide_testing_bdd-spec-support_maven-configuration.adoc[leveloffset=+1]
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..ede2b2a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_bdd-tooling.adoc
@@ -0,0 +1,13 @@
+= 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/97531ca0/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
new file mode 100644
index 0000000..27d0e49
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_how-it-works.adoc
@@ -0,0 +1,19 @@
+= 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 http://cukes.info/step-definitions.html[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/97531ca0/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
new file mode 100644
index 0000000..9244f6e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_key-classes.adoc
@@ -0,0 +1,58 @@
+= 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' <<_integration_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/97531ca0/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
new file mode 100644
index 0000000..88bbc7f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_maven-configuration.adoc
@@ -0,0 +1,72 @@
+= 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 <<_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]
+----
+<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/97531ca0/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
new file mode 100644
index 0000000..5cdc050
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_writing-a-bdd-spec.adoc
@@ -0,0 +1,140 @@
+= 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 <<_integration_test_support, Integration Test Support>>, bootstrapping section).
+
+
+Here's an example of a feature from the <<_simpleapp_archetype, SimpleApp archetype>>:
+
+[source]
+----
+@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 <<_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 <<_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/97531ca0/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
new file mode 100644
index 0000000..adba36a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_fixture-scripts.adoc
@@ -0,0 +1,43 @@
+= 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::_user-guide_testing_fixture-scripts_api-and-usage.adoc[leveloffset=+1]
+include::_user-guide_testing_fixture-scripts_sudo-service.adoc[leveloffset=+1]
+
[05/22] isis git commit: ISIS-1133: renamed _user-guide_ to _ug_
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_clear.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_clear.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_clear.adoc
deleted file mode 100644
index a84aafc..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_clear.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_default.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_default.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_default.adoc
deleted file mode 100644
index 92f1658..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_default.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_disable.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_disable.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_disable.adoc
deleted file mode 100644
index b511df5..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_disable.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_get.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_get.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_get.adoc
deleted file mode 100644
index a2f9f87..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_get.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_hide.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_hide.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_hide.adoc
deleted file mode 100644
index 8918811..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_hide.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_modify.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_modify.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_modify.adoc
deleted file mode 100644
index acd087d..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_modify.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_removeFrom.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_removeFrom.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_removeFrom.adoc
deleted file mode 100644
index 14411ba..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_removeFrom.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_set.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_set.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_set.adoc
deleted file mode 100644
index add8f0e..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_set.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_validate.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_validate.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_validate.adoc
deleted file mode 100644
index 3135322..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_validate.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_validateAddTo.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_validateAddTo.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_validateAddTo.adoc
deleted file mode 100644
index fa98e27..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_validateAddTo.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_validateRemoveFrom.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_validateRemoveFrom.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_validateRemoveFrom.adoc
deleted file mode 100644
index 0cb8353..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_prefixes_manpage_validateRemoveFrom.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api.adoc
deleted file mode 100644
index f613063..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api.adoc
+++ /dev/null
@@ -1,30 +0,0 @@
-= 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/
-
-
-IMPORTANT: TODO
-
-include::_user-guide_reference_services-api_aaa.adoc[leveloffset=+1]
-
-include::_user-guide_reference_services-api_action-invocation-context.adoc[leveloffset=+1]
-include::_user-guide_reference_services-api_background-service.adoc[leveloffset=+1]
-include::_user-guide_reference_services-api_bookmark-service.adoc[leveloffset=+1]
-include::_user-guide_reference_services-api_clock-service.adoc[leveloffset=+1]
-include::_user-guide_reference_services-api_command-context.adoc[leveloffset=+1]
-include::_user-guide_reference_services-api_deep-link-service.adoc[leveloffset=+1]
-include::_user-guide_reference_services-api_domain-object-container.adoc[leveloffset=+1]
-include::_user-guide_reference_services-api_email-service.adoc[leveloffset=+1]
-include::_user-guide_reference_services-api_event-bus-service.adoc[leveloffset=+1]
-include::_user-guide_reference_services-api_guice-bean-provider.adoc[leveloffset=+1]
-include::_user-guide_reference_services-api_isis-jdo-support.adoc[leveloffset=+1]
-include::_user-guide_reference_services-api_memento-service.adoc[leveloffset=+1]
-include::_user-guide_reference_services-api_metamodel-service.adoc[leveloffset=+1]
-include::_user-guide_reference_services-api_query-results-cache.adoc[leveloffset=+1]
-include::_user-guide_reference_services-api_scratch-pad.adoc[leveloffset=+1]
-include::_user-guide_reference_services-api_sudo-service.adoc[leveloffset=+1]
-include::_user-guide_reference_services-api_wrapper-factory.adoc[leveloffset=+1]
-include::_user-guide_reference_services-api_xml-snapshot-service.adoc[leveloffset=+1]
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_aaa.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_aaa.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_aaa.adoc
deleted file mode 100644
index 4bb02a9..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_aaa.adoc
+++ /dev/null
@@ -1,215 +0,0 @@
-= 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/
-
-
-
-IMPORTANT: TODO
-
-
-== Applib Services
-
-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 http://isisaddons.org[Isis Addons] (non-ASF)modules.
-
-.Domain Services
-[cols="2,4a,1,1", options="header"]
-|===
-
-|API
-|Maven Module +
-Impl'n (g: a:)
-|Implementation
-|Notes
-
-|<<__code_actioninvocationcontext_code, `o.a.i.applib.` +
-`services.actinv` +
-`ActionInvocation-` +
-`Context`>>
-|``o.a.i.core`` +
-``isis-core-applib``
-|`ActionInvocationContext`
-|API is also concrete class
-
-|<<__code_backgroundservice_code, `o.a.i.applib.` +
-`services.background` +
-`BackgroundService`>>
-|``o.a.i.core`` +
-``isis-core-runtime``
-|`BackgroundServiceDefault`
-|depends on: +
-`BackgroundCommandService`
-
-|<<__code_bookmarkservice_code, `o.a.i.applib.` +
-`services.bookmark` +
-`BookmarkService`>>
-|``o.a.i.core`` +
-``isis-core-metamodel``
-|`BookmarkServiceDefault`
-|related services:
-`BookmarkHolder-` ++
-`ActionContributions`,
-`BookmarkHolder-` ++
-`AssociationContributions`
-
-|<<__code_clockservice_code, `o.a.i.applib.` +
-`services.clock` +
-`ClockService`>>
-|``o.a.i.core`` +
-``isis-core-applib``
-|`ClockService`
-|API is also a concrete class.
-
-|<<__code_commandcontext_code, `o.a.i.applib.` +
-`services.command` +
-`CommandContext`>>
-|``o.a.i.core`` +
-``isis-core-applib``
-|`CommandContext`
-|API is also a concrete class. +
-depends on: +
-`CommandService` for persistent `Command`, else in-memory impl. used
-
-|<<__code_deeplinkservice_code, `o.a.i.applib` +
-`services.deeplink` +
-`DeepLinkService`>>
-|``o.a.i.viewer`` +
-``isis-viewer-wicket-impl``
-|`DeepLinkServiceWicket`
-|Implementation only usable within Wicket viewer
-
-|<<__code_domainobjectcontainer_code, `o.a.i.applib` +
-`DomainObjectContainer`>>
-|``o.a.i.core`` +
-``isis-core-metamodel``
-|`DomainObjectContainerDefault`
-|
-
-|<<__code_emailservice_code, `o.a.i.applib.` +
-`services.email` +
-`EmailService`>>
-|``o.a.i.core`` +
-``isis-core-runtime``
-|`EmailServiceDefault`
-|
-
-|<<__code_eventbusservice_code, `o.a.i.applib.` +
-`services.eventbus` +
-`EventBusService`>>
-|``o.a.i.core`` +
-``isis-core-objectstore-jdo-datanucleus``
-|`EventBusServiceJdo`
-|
-
-|<<__code_guicebeanprovider_code, `o.a.i.applib.` +
-`services.guice` +
-`GuiceBeanProvider`>>
-|``o.a.i.core`` +
-``isis-viewer-wicket-impl``
-|`GuiceBeanProviderWicket`
-|
-
-|<<__code_isisjdosupport_code, `o.a.i.applib.` +
-`services.jdosupport` +
-`IsisJdoSupport`>>
-|``o.a.i.core`` +
-``isis-core-objectstore-jdo-datanucleus``
-|`IsisJdoSupportImpl`
-|
-
-|<<__code_mementoservice_code, `o.a.i.applib.` +
-`services.memento` +
-`MementoService`>>
-|``o.a.i.core`` +
-``isis-core-runtime``
-|`MementoServiceDefault`
-|
-
-|<<__code_metamodelservice_code, `o.a.i.applib.` +
-`services.metamodel` +
-`MetaModelService`>>
-|``o.a.i.core`` +
-``isis-core-metamodel``
-|`MetaModelServiceDefault`
-|
-
-|<<__code_queryresultscache_code, `o.a.i.applib.` +
-`services.` +
-`queryresultscache` +
-`QueryResultsCache`>>
-|``o.a.i.core`` +
-``isis-core-applib``
-|`QueryResultsCache`
-|API is also a concrete class
-
-|<<__code_scratchpad_code, `o.a.i.applib.` +
-`services.scratchpad` +
-`Scratchpad`>>
-|``o.a.i.core`` +
-``isis-core-applib``
-|`Scratchpad`
-|API is also a concrete class
-
-|<<__code_scratchpad_code, `o.a.i.applib.` +
-`services.sudo` +
-`SudoService`>>
-|``o.a.i.core`` +
-``isis-core-runtime``
-|`SudoServiceDefault`
-|API is also a concrete class
-
-|<<__code_wrapperfactory_code, `o.a.i.applib.` +
-`services.wrapper` +
-`WrapperFactory`>>
-|``o.a.i.core`` +
-``isis-core-wrapper``
-|`WrapperFactoryDefault`
-|
-
-|<<__code_xmlsnapshotservice_code, `o.a.i.applib.` +
-`services.xmlsnapshot` +
-`XmlSnapshotService`>>
-|``o.a.i.core`` +
-``isis-core-runtime``
-|`XmlSnapshotServiceDefault`
-|
-
-|===
-
-Key:
-
-* `o.a.i` is an abbreviation for `org.apache.isis`
-* `o.ia.m` is an abbreviation for `org.isisaddons.module`
-
-
-
-
-== Deprecated Services
-
-There is also a number of deprecated domain services.
-
-.Deprecated Domain Services
-[cols="2,4a,1,1", options="header"]
-|===
-
-|API
-|Maven Module +
-Impl'n (g: a:)
-|Implementation
-|Notes
-
-|`o.a.i.applib.` +
-`annotation`
-`Bulk.InteractionContext`
-|``o.a.i.core`` +
-``isis-core-applib``
-|`Bulk.InteractionContext`
-|Replaced by `ActionInvocationContext`
-
-
-|===
-
-Key:
-
-* `o.a.i` is an abbreviation for `org.apache.isis`
-* `o.ia.m` is an abbreviation for `org.isisaddons.module`
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_action-invocation-context.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_action-invocation-context.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_action-invocation-context.adoc
deleted file mode 100644
index 989d131..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_action-invocation-context.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_background-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_background-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_background-service.adoc
deleted file mode 100644
index 74c69e5..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_background-service.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_bookmark-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_bookmark-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_bookmark-service.adoc
deleted file mode 100644
index 5d0024a..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_bookmark-service.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_clock-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_clock-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_clock-service.adoc
deleted file mode 100644
index 1b4675d..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_clock-service.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_command-context.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_command-context.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_command-context.adoc
deleted file mode 100644
index 15c250c..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_command-context.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_deep-link-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_deep-link-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_deep-link-service.adoc
deleted file mode 100644
index 7135b31..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_deep-link-service.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_domain-object-container.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_domain-object-container.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_domain-object-container.adoc
deleted file mode 100644
index 53d253f..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_domain-object-container.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_email-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_email-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_email-service.adoc
deleted file mode 100644
index 6f78302..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_email-service.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_event-bus-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_event-bus-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_event-bus-service.adoc
deleted file mode 100644
index 43275fe..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_event-bus-service.adoc
+++ /dev/null
@@ -1,15 +0,0 @@
-= `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/
-
-IMPORTANT: TODO
-
-## Implementation
-
-IMPORTANT: TODO
-
-## Registration
-
-The `EventBusServiceJdo` class provides the default implementation and (as of 1.6.0+) is automatically registered using `@DomainService`. No further configuration is necessary.
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_guice-bean-provider.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_guice-bean-provider.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_guice-bean-provider.adoc
deleted file mode 100644
index 99f4f36..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_guice-bean-provider.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_isis-jdo-support.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_isis-jdo-support.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_isis-jdo-support.adoc
deleted file mode 100644
index 3c1873a..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_isis-jdo-support.adoc
+++ /dev/null
@@ -1,129 +0,0 @@
-= `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.
-
-
-== API
-
-The API provided by `IsisJdoSupport` is:
-
-[source,java]
-----
-public interface IsisJdoSupport {
- List<Map<String, Object>> executeSql(String sql);
- Integer executeUpdate(String sql);
- void deleteAll(Class<?>... pcClasses);
- <T> T refresh(T domainObject);
- void ensureLoaded(Collection<?> collectionOfDomainObjects);
- PersistenceManager getJdoPersistenceManager();
-}
-----
-
-Each of these methods are discussed in more details below.
-
-
-== Executing arbitrary SQL
-
-The `executeSql(...)` method allows arbitrary 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 updates to be performed.
-
-[source,java]
-----
-int count = isisJdoSupport.executeUpdate("select count(*) from custMgmt.customers);
-----
-
-The returned value is the number of rows updated.
-
-
-
-== Fixture support
-
-The `deleteAll(...)` method is provided pretty much exclusively for tearing down fixture data:
-
-[source,java]
-----
-deleteAll(Order.class);
-deleteAll(CustomerAddress.class);
-deleteAll(Customer.class);
-----
-
-[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 <i>force</i> the deletion of all instances), concurrency checking
-is temporarily disabled while this method is performed.
-====
-
-
-
-== Reloading entities
-
-A http://www.datanucleus.org/products/datanucleus/jdo/orm/relationships.html[known limitation] of DataNucleus' implementation of JDO is that persisting a child entity (in a 1:n bidirectional relationship) does not cause the parent's collection to be updated.
-
-The `refresh(T domainObject)` method can be used to reload the parent object (or indeed any object).
-
-For example:
-
-[source,java]
-----
-public Order newOrder(final Customer customer) {
- Order order = newTransientInstance(Order.class);
- order.setCustomer(customer);
- persist(customer);
- getContainer().flush(); // <1>
- isisJdoSupport.refresh(customer); // <2>
- return order;
-}
-----
-<1> flush to database
-<2> reload parent from database
-
-
-[NOTE]
-====
-The particular example that led to this method being added was a 1:m bidirectional relationship,
-analogous to `Customer <-> * 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.
-
-====
-
-
-
-
-== Using JDO `PersistenceManager` directly
-
-Apache Isis provides a simplified API on top of only supports JDO, and so does not support all of JDO's features. For example, Isis (currently) only supports named queries. If you require more flexibility than this, eg for dynamically constructed queries, then the service provides access to the underlying JDO `PersistenceManager` API:
-
-[source,java]
-----
-public List<Order> findOrders(...) {
- javax.jdo.PersistenceManager pm = isisJdoSupport.getPersistenceManager();
-
- // knock yourself out...
-
- return someListOfOrders;
-}
-----
-
-
-
-== Registering the Service
-
-The `IsisJdoSupportImpl` class provides the default implementation and (as of 1.6.0+) is automatically registered using `@DomainService`. No further configuration is necessary.
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_memento-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_memento-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_memento-service.adoc
deleted file mode 100644
index f06a824..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_memento-service.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_metamodel-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_metamodel-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_metamodel-service.adoc
deleted file mode 100644
index cb298dc..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_metamodel-service.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_query-results-cache.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_query-results-cache.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_query-results-cache.adoc
deleted file mode 100644
index 0b22d23..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_query-results-cache.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_scratch-pad.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_scratch-pad.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_scratch-pad.adoc
deleted file mode 100644
index 0a11596..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_scratch-pad.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_sudo-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_sudo-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_sudo-service.adoc
deleted file mode 100644
index bb33642..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_sudo-service.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_wrapper-factory.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_wrapper-factory.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_wrapper-factory.adoc
deleted file mode 100644
index e2949b1..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_wrapper-factory.adoc
+++ /dev/null
@@ -1,18 +0,0 @@
-= `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/
-
-IMPORTANT: TODO
-
-
-
-
-
-
-
-== `wrapNoExecute()`
-
-
-== `wrapSkipRules()`
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_xml-snapshot-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_xml-snapshot-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_xml-snapshot-service.adoc
deleted file mode 100644
index f82a24a..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-api_xml-snapshot-service.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi.adoc
deleted file mode 100644
index ddf79f6..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi.adoc
+++ /dev/null
@@ -1,25 +0,0 @@
-= 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/
-
-
-IMPORTANT: TODO
-
-include::_user-guide_reference_services-spi_aaa.adoc[leveloffset=+1]
-
-include::_user-guide_reference_services-spi_auditing-service.adoc[leveloffset=+1]
-include::_user-guide_reference_services-spi_background-command-service.adoc[leveloffset=+1]
-include::_user-guide_reference_services-spi_class-discovery-service.adoc[leveloffset=+1]
-include::_user-guide_reference_services-spi_command-service.adoc[leveloffset=+1]
-include::_user-guide_reference_services-spi_content-mapping-service.adoc[leveloffset=+1]
-include::_user-guide_reference_services-spi_content-negotiation-service.adoc[leveloffset=+1]
-include::_user-guide_reference_services-spi_email-notification-service.adoc[leveloffset=+1]
-include::_user-guide_reference_services-spi_event-serializer.adoc[leveloffset=+1]
-include::_user-guide_reference_services-spi_exception-recognizer.adoc[leveloffset=+1]
-include::_user-guide_reference_services-spi_locale-provider.adoc[leveloffset=+1]
-include::_user-guide_reference_services-spi_publishing-service.adoc[leveloffset=+1]
-include::_user-guide_reference_services-spi_translation-service.adoc[leveloffset=+1]
-include::_user-guide_reference_services-spi_translations-resolver.adoc[leveloffset=+1]
-include::_user-guide_reference_services-spi_user-profile-service.adoc[leveloffset=+1]
-include::_user-guide_reference_services-spi_user-registration-service.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_aaa.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_aaa.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_aaa.adoc
deleted file mode 100644
index fa3baef..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_aaa.adoc
+++ /dev/null
@@ -1,214 +0,0 @@
-= 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/
-
-
-
-IMPORTANT: TODO
-
-== Applib SPIs
-
-IMPORTANT: TODO
-
-.Domain Services
-[cols="2,4a,1,1", options="header"]
-|===
-
-|API
-|Maven Module +
-Impl'n (g: a:)
-|Implementation
-|Notes
-
-|<<__code_auditingservice3_code, `o.a.i.applib.` +
-`services.audit` +
-`AuditingService3`>>
-|``o.ia.m.audit`` +
-``isis-module-audit``
-|`AuditingService`
-|related services:
-`AuditingService-` +
-`Contributions`,
-`AuditingService-` +
-`Repository`
-
-|<<__code_backgroundcommandservice_code, `o.a.i.applib.` +
-`services.background` +
-`BackgroundCommandService`>>
-|``o.ia.m.command`` +
-``isis-module-command``
-|`BackgroundCommandServiceJdo`
-|related services:
-`BackgroundCommandService-` +
-`JdoContributions`,
-`BackgroundCommandService-` +
-`JdoRepository`
-
-|<<__code_classdiscoveryservice_code, `o.a.i.applib.` +
-`services.classdiscovery` +
-`ClassDiscoveryService`>>
-|``o.a.i.core`` +
-``isis-core-applib``
-|`ClassDiscoveryService-` +
-`UsingReflections`
-|requires `org.reflections:reflections` as Maven dependency
-
-|<<__code_commandservice_code, `o.a.i.applib.` +
-`services.command.spi` +
-`CommandService`>>
-|``o.ia.m.command`` +
-``isis-module-command``
-|`CommandServiceJdo`
-|related services: +
-`CommandService-` ++
-`JdoContributions`,
-`CommandService-` ++
-`JdoRepository`
-
-|<<__code_emailnotificationservice_code, `o.a.i.applib.` +
-`services.userreg` +
-`EmailNotificationService`>>
-|``o.a.i.core`` +
-``isis-core-runtime``
-|`EmailNotificationService-` ++
-`Default`
-|depends on: +
-a configured `EmailService`
-
-|<<__code_eventserializer_code, `o.a.i.applib.` +
-`services.publish` +
-`EventSerializer`>>
-|``o.ia.m.publishing`` +
-``isis-module-publishing``
-|`RestfulObjects-` +
-`SpecEventSerializer`
-|
-
-|<<__code_exceptionrecognizer_code, `o.a.i.applib.` +
-`services.exceprecog` +
-`ExceptionRecognizer`>>
-|``o.a.i.core`` +
-``isis-core-applib``
-|`ExceptionRecognizer-` +
-`CompositeFor-` +
-`JdoObjectStore`
-|Extensible using composite pattern if required
-
-|<<__code_localeprovider_code, `o.a.i.applib.` +
-`services.i18n` +
-`LocaleProvider`>>
-|``o.a.i.viewer`` +
-``isis-viewer-wicket-impl``
-|`LocaleProviderWicket`
-|
-
-|<<__code_publishingservice_code, `o.a.i.applib.` +
-`services.publish` +
-`PublishingService`>>
-|``o.ia.m.publishing`` +
-``isis-module-publishing``
-|`PublishingService`
-|related services:
-`PublishingService-` ++
-`Contributions`,
-`PublishingService-` ++
-`Repository`. +
-depends on: +
-`EventSerializer`
-
-|<<__code_translationservice_code, `o.a.i.applib.` +
-`services.i18n` +
-`TranslationService`>>
-|``o.a.i.core`` +
-``isis-core-runtime``
-|`TranslationServicePo`
-|related services: `TranslationServicePoMenu` +
-depends on: +
-`TranslationsResolver`, `LocaleProvider`
-
-|<<__code_translationsresolver_code, `o.a.i.applib.` +
-`services.i18n` +
-`TranslationsResolver`>>
-|``o.a.i.viewer`` +
-``isis-viewer-wicket-impl``
-|`TranslationsResolverWicket`
-|
-
-|<<__code_userprofileservice_code, `o.a.i.applib.` +
-`services.userprof` +
-`UserProfileService`>>
-|
-|
-|SPI only
-
-|<<__code_userregistrationservice_code, `o.a.i.applib.` +
-`services.userreg` +
-`UserRegistrationService`>>
-|``o.ia.m.security`` +
-``isis-module-security``
-|`SecurityModule-` +
-`AppUserRegistrationService`
-|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`
-
-
-All domain services are automatically registered (annotated with <<__code_domainservice_code, `@DomainService`>>) except:
-
-
-
-* `ExceptionRecognizer` +
-+
-Register explicitly in isis.properties (so is extensible)
-
-
-
-
-
-== "Internal" SPIs
-
-These services definitions depend on the internals of the framework; we do not guarantee that link:semver.org[semantic versioning] will be honoured for these APIs.
-
-
-.Semi-public SPI
-[cols="3,3,2,2a", options="header"]
-|===
-
-|SPI
-|Maven Module +
-Impl'n (g: a:)
-|Implementation
-|Notes
-
-
-|<<__code_contentmappingservice_code, `o.a.i.v.ro.` +
-`rendering.service.conneg.` +
-`ContentMappingService`>>
-|
-|
-|No default implementation.
-
-|<<__code_contentnegotiationservice_code, `o.a.i.v.ro.` +
-`rendering.service.conneg.` +
-`ContentNegotiationService`>>
-|``o.a.i.core`` +
-`isis-core-viewer-restfulobjects-rendering`
-|`ContentNegotiationService-` +
-`XRoDomainType`
-|
-
-
-|===
-
-Key:
-
-* `o.a.i.v.ro` is an abbreviation for `org.apache.isis.viewer.restfulobjects`
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_auditing-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_auditing-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_auditing-service.adoc
deleted file mode 100644
index e4626d2..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_auditing-service.adoc
+++ /dev/null
@@ -1,13 +0,0 @@
-= `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/
-
-IMPORTANT: TODO
-
-
-
-
-== Isis Addons Implementation
-
-For 1.7.0+, see the http://github.com/isisaddons/isis-module-audit[Isis addons' Audit module] (non-ASF).
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_background-command-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_background-command-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_background-command-service.adoc
deleted file mode 100644
index 3111628..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_background-command-service.adoc
+++ /dev/null
@@ -1,12 +0,0 @@
-= `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/
-
-IMPORTANT: TODO
-
-
-== Isis Addons Implementation
-
-For 1.7.0+, see the http://github.com/isisaddons/isis-module-command[Isis addons' Command module] (non-ASF).
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_class-discovery-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_class-discovery-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_class-discovery-service.adoc
deleted file mode 100644
index 075cf62..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_class-discovery-service.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_command-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_command-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_command-service.adoc
deleted file mode 100644
index ab86189..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_command-service.adoc
+++ /dev/null
@@ -1,11 +0,0 @@
-= `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/
-
-IMPORTANT: TODO
-
-
-== Isis Addons Implementation
-
-For 1.7.0+, see the http://github.com/isisaddons/isis-module-command[Isis addons' Command module] (non-ASF).
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_content-mapping-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_content-mapping-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_content-mapping-service.adoc
deleted file mode 100644
index 09d20f9..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_content-mapping-service.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_content-negotiation-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_content-negotiation-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_content-negotiation-service.adoc
deleted file mode 100644
index 89933f9..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_content-negotiation-service.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_email-notification-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_email-notification-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_email-notification-service.adoc
deleted file mode 100644
index 2a99016..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_email-notification-service.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_event-serializer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_event-serializer.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_event-serializer.adoc
deleted file mode 100644
index 2c20560..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_event-serializer.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_exception-recognizer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_exception-recognizer.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_exception-recognizer.adoc
deleted file mode 100644
index 04e7561..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_exception-recognizer.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_locale-provider.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_locale-provider.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_locale-provider.adoc
deleted file mode 100644
index 4956f49..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_locale-provider.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_publishing-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_publishing-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_publishing-service.adoc
deleted file mode 100644
index 93b17c1..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_publishing-service.adoc
+++ /dev/null
@@ -1,11 +0,0 @@
-= `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/
-
-IMPORTANT: TODO
-
-
-== Isis Addons Implementation
-
-For 1.7.0+, see the http://github.com/isisaddons/isis-module-publishing[Isis addons' Publishing module] (non-ASF).
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_translation-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_translation-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_translation-service.adoc
deleted file mode 100644
index 0c1b16e..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_translation-service.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_translations-resolver.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_translations-resolver.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_translations-resolver.adoc
deleted file mode 100644
index 7148bc7..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_translations-resolver.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_user-profile-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_user-profile-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_user-profile-service.adoc
deleted file mode 100644
index 6b56835..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_user-profile-service.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `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/
-
-IMPORTANT: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_user-registration-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_user-registration-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_user-registration-service.adoc
deleted file mode 100644
index ab1a666..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_services-spi_user-registration-service.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= `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/
-
-IMPORTANT: TODO
-
-
[09/22] isis git commit: ISIS-1133: renamed _user-guide_ to _ug_
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy_naked-objects-pattern.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy_naked-objects-pattern.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy_naked-objects-pattern.adoc
deleted file mode 100644
index ec6d671..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy_naked-objects-pattern.adoc
+++ /dev/null
@@ -1,54 +0,0 @@
-= 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: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 http://isisaddons.org[Isis Addons] (non-ASF) the http://github.com/isisaddons/isis-wicket-gmap3}[Isis addons' gmap3 modue] 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.
-====
-
-== Object Interface Mapping
-
-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 <<_vs_metawidget,here>>.
-====
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_principles.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_principles.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_principles.adoc
deleted file mode 100644
index 543ec76..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_principles.adoc
+++ /dev/null
@@ -1,17 +0,0 @@
-= 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::_user-guide_core-concepts_principles_your-apps.adoc[leveloffset=+1]
-
-include::_user-guide_core-concepts_principles_isis-itself.adoc[leveloffset=+1]
-
-include::_user-guide_core-concepts_principles_apache-isis-vs.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_principles_apache-isis-vs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_principles_apache-isis-vs.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_principles_apache-isis-vs.adoc
deleted file mode 100644
index 6290e10..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_principles_apache-isis-vs.adoc
+++ /dev/null
@@ -1,36 +0,0 @@
-= 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?
-
-## vs MVC server-side frameworks
-
-Some of most commonly used frameworks today are link:http://www.springframework.org/[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 <<_extending_the_viewer, extending Isis' Wicket viewer>> or by writing a bespoke UI leveraging the REST (hypermedia) API automatically exposed by <<_restful_objects_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 http://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 "<<_using_the_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.
-
-
-## vs Angular
-
-## vs MetaWidget
-
-MetaWidget (mentioned <<_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 http://isisaddons.org[Isis Addons] (non-ASF), and we also provide a full <<_restful_objects_viewer,Restful API>>
-
-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.
-
-
-## vs OpenXava
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_principles_isis-itself.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_principles_isis-itself.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_principles_isis-itself.adoc
deleted file mode 100644
index b48230c..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_principles_isis-itself.adoc
+++ /dev/null
@@ -1,46 +0,0 @@
-= 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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_principles_your-apps.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_principles_your-apps.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_principles_your-apps.adoc
deleted file mode 100644
index fcfb767..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_principles_your-apps.adoc
+++ /dev/null
@@ -1,38 +0,0 @@
-= 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: TODO
-
-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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_deployment.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_deployment.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_deployment.adoc
deleted file mode 100644
index 26fdede..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_deployment.adoc
+++ /dev/null
@@ -1,19 +0,0 @@
-= 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::_user-guide_deployment_cmd-line.adoc[leveloffset=+1]
-
-include::_user-guide_deployment_tomcat.adoc[leveloffset=+1]
-
-include::_user-guide_deployment_gae.adoc[leveloffset=+1]
-
-include::_user-guide_deployment_jvm-flags.adoc[leveloffset=+1]
-
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_deployment_cmd-line.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_deployment_cmd-line.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_deployment_cmd-line.adoc
deleted file mode 100644
index 5c936d6..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_deployment_cmd-line.adoc
+++ /dev/null
@@ -1,29 +0,0 @@
-= 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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_deployment_gae.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_deployment_gae.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_deployment_gae.adoc
deleted file mode 100644
index 938a247..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_deployment_gae.adoc
+++ /dev/null
@@ -1,459 +0,0 @@
-= 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 https://developers.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:
-
-____
-
-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.
-
-____
-
-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.
-
-=== A GAE compatible version of `ToDoItem.java`
-
-... as per the http://github.com/isisaddons/isis-app-todoapp}[Isis addons' todoapp] (non-ASF), is as follows:
-
-[source,java]
-----
-@javax.jdo.annotations.Queries( {
- @javax.jdo.annotations.Query(
- name="todo_all", language="JDOQL",
- value="SELECT FROM dom.todo.ToDoItem WHERE ownedBy == :ownedBy"),
- @javax.jdo.annotations.Query(
- name="todo_notYetComplete", language="JDOQL",
- value="SELECT FROM dom.todo.ToDoItem WHERE ownedBy == :ownedBy && complete == false"),
- @javax.jdo.annotations.Query(
- name="todo_complete", language="JDOQL",
- value="SELECT FROM dom.todo.ToDoItem WHERE ownedBy == :ownedBy && complete == true"),
- @javax.jdo.annotations.Query(
- name="todo_similarTo", language="JDOQL",
- value="SELECT FROM dom.todo.ToDoItem WHERE ownedBy == :ownedBy && category == :category"),
- @javax.jdo.annotations.Query(
- name="todo_autoComplete", language="JDOQL",
- value="SELECT FROM dom.todo.ToDoItem WHERE ownedBy == :ownedBy && description.startsWith(:description)")
-})
-@javax.jdo.annotations.Version(strategy= VersionStrategy.VERSION_NUMBER, column="VERSION")
-@ObjectType("TODO")
-@Auditable
-@AutoComplete(repository=ToDoItems.class, action="autoComplete")
-@MemberGroups({"General", "Detail"})
-@javax.jdo.annotations.PersistenceCapable
-public class ToDoItem implements Comparable<ToDoItem> {
-// @PrimaryKey
-// @Persistent(valueStrategy = javax.jdo.annotations.IdGeneratorStrategy.IDENTITY)
-// @Extension(vendorName="datanucleus", key="gae.encoded-pk", value="true")
-// private String key;
- @Persistent(valueStrategy=IdGeneratorStrategy.IDENTITY)
- @PrimaryKey
- private Long id;
-
- private static final long ONE_WEEK_IN_MILLIS = 7 * 24 * 60 * 60 * 1000L;
-
- public static enum Category {
- Professional, Domestic, Other;
- }
-
- // {{ Identification on the UI
- public String title() {
- final TitleBuffer buf = new TitleBuffer();
- buf.append(getDescription());
- if (isComplete()) {
- buf.append(" - Completed!");
- } else {
- if (getDueBy() != null) {
- SimpleDateFormat sdf = new SimpleDateFormat("dd-MM-yyyy");
- buf.append(" due by ", sdf.format(getDueBy()));
- }
- }
- return buf.toString();
- }
-
- // }}
-
- // {{ Description
- private String description;
-
- @RegEx(validation = "\\w[@&:\\-\\,\\.\\+ \\w]*")
- // words, spaces and selected punctuation
- @MemberOrder(sequence = "1")
- @DescribedAs("Enter the description")
- public String getDescription() {
- return description;
- }
-
- public void setDescription(final String description) {
- this.description = description;
- }
- // }}
-
- // {{ DueBy (property)
- private Date dueBy;
-
- @javax.jdo.annotations.Persistent
- @MemberOrder(name="Detail", sequence = "3")
- @Optional
- @DescribedAs("Enter the date")
- public Date getDueBy() {
- return dueBy;
- }
-
- public void setDueBy(final Date dueBy) {
- this.dueBy = dueBy;
- }
- public void clearDueBy() {
- setDueBy(null);
- }
- // proposed new value is validated before setting
- public String validateDueBy(final Date dueBy) {
- if (dueBy == null) {
- return null;
- }
- return isMoreThanOneWeekInPast(dueBy) ? "Due by date cannot be more than one week old" : null;
- }
- // }}
-
- // {{ Category
- private Category category;
-
- @MemberOrder(sequence = "2")
- @DescribedAs("Enter the category")
- public Category getCategory() {
- return category;
- }
-
- public void setCategory(final Category category) {
- this.category = category;
- }
- // }}
-
- // {{ OwnedBy (property)
- private String ownedBy;
-
- @Hidden
- // not shown in the UI
- public String getOwnedBy() {
- return ownedBy;
- }
-
- public void setOwnedBy(final String ownedBy) {
- this.ownedBy = ownedBy;
- }
-
- // }}
-
- // {{ Complete (property)
- private boolean complete;
-
- @Disabled
- // cannot be edited as a property
- @MemberOrder(sequence = "4")
- public boolean isComplete() {
- return complete;
- }
-
- public void setComplete(final boolean complete) {
- this.complete = complete;
- }
-
- // {{ Notes (property)
- private String notes;
-
- @Hidden(where=Where.ALL_TABLES)
- @Optional
- @MultiLine(numberOfLines=4)
- @MemberOrder(name="Detail", sequence = "6")
- public String getNotes() {
- return notes;
- }
-
- public void setNotes(final String notes) {
- this.notes = notes;
- }
- // }}
-
- // {{ Attachment (property)
- private BlobKey attachment;
-
- @Persistent
- @Optional
- @MemberOrder(name="Detail", sequence = "7")
- public BlobKey getAttachment() {
- return attachment;
- }
-
- public void setAttachment(final BlobKey attachment) {
- this.attachment = attachment;
- }
- // }}
-
- // {{ Version (derived property)
- @Hidden(where=Where.ALL_TABLES)
- @Disabled
- @MemberOrder(name="Detail", sequence = "99")
- @Named("Version")
- public Long getVersionSequence() {
- if(!(this instanceof PersistenceCapable)) {
- return null;
- }
- PersistenceCapable persistenceCapable = (PersistenceCapable) this;
- final Long version = (Long) JDOHelper.getVersion(persistenceCapable);
- return version;
- }
- public boolean hideVersionSequence() {
- return !(this instanceof PersistenceCapable);
- }
- // }}
-
- // {{ completed (action)
- @Bulk
- @MemberOrder(sequence = "1")
- public ToDoItem completed() {
- setComplete(true);
- return this;
- }
-
- // disable action dependent on state of object
- public String disableCompleted() {
- return complete ? "Already completed" : null;
- }
- // }}
-
- // {{ notYetCompleted (action)
- @MemberOrder(sequence = "2")
- public ToDoItem notYetCompleted() {
- setComplete(false);
- return this;
- }
-
- // disable action dependent on state of object
- public String disableNotYetCompleted() {
- return !complete ? "Not yet completed" : null;
- }
- // }}
-
- // {{ dependencies (Collection)
- @Unowned
- private List<ToDoItem> dependencies = new ArrayList<ToDoItem>();
-
- @Disabled
- @MemberOrder(sequence = "1")
- @Resolve(Type.EAGERLY)
- public List<ToDoItem> getDependencies() {
- return dependencies;
- }
-
- public void setDependencies(final List<ToDoItem> dependencies) {
- this.dependencies = dependencies;
- }
- // }}
-
- // {{ add (action)
- @MemberOrder(name="dependencies", sequence = "3")
- public ToDoItem add(final ToDoItem toDoItem) {
- getDependencies().add(toDoItem);
- return this;
- }
- public String validateAdd(final ToDoItem toDoItem) {
- if(getDependencies().contains(toDoItem)) {
- return "Already a dependency";
- }
- if(toDoItem == this) {
- return "Can't set up a dependency to self";
- }
- return null;
- }
- public List<ToDoItem> choices0Add() {
- return toDoItems.allToDos();
- }
-
- // }}
-
- // {{ remove (action)
- @MemberOrder(name="dependencies", sequence = "4")
- public ToDoItem remove(final ToDoItem toDoItem) {
- getDependencies().remove(toDoItem);
- return this;
- }
- public String disableRemove(final ToDoItem toDoItem) {
- return getDependencies().isEmpty()? "No dependencies to remove": null;
- }
- public String validateRemove(final ToDoItem toDoItem) {
- if(!getDependencies().contains(toDoItem)) {
- return "Not a dependency";
- }
- return null;
- }
- public List<ToDoItem> choices0Remove() {
- return getDependencies();
- }
- // }}
-
- // {{ clone (action)
- @Named("Clone")
- // the name of the action in the UI
- @MemberOrder(sequence = "3")
- // nb: method is not called "clone()" is inherited by java.lang.Object and
- // (a) has different semantics and (b) is in any case automatically ignored
- // by the framework
- public ToDoItem duplicate() {
- return toDoItems.newToDo(getDescription() + " - Copy", getCategory(), getDueBy());
- }
- // }}
-
- // {{ isDue (programmatic)
- @Programmatic
- // excluded from the framework's metamodel
- public boolean isDue() {
- if (getDueBy() == null) {
- return false;
- }
- return !isMoreThanOneWeekInPast(getDueBy());
- }
-
- // }}
-
- // {{ SimilarItems (derived collection)
- @MemberOrder(sequence = "5")
- @NotPersisted
- @Resolve(Type.EAGERLY)
- public List<ToDoItem> getSimilarItems() {
- return toDoItems.similarTo(this);
- }
-
- // }}
-
- // {{ compareTo (programmatic)
- /**
- * by complete flag, then due by date, then description
- */
- // exclude from the framework's metamodel
- @Override
- public int compareTo(final ToDoItem other) {
- if (isComplete() && !other.isComplete()) {
- return +1;
- }
- if (!isComplete() && other.isComplete()) {
- return -1;
- }
- if (getDueBy() == null && other.getDueBy() != null) {
- return +1;
- }
- if (getDueBy() != null && other.getDueBy() == null) {
- return -1;
- }
- if (getDueBy() == null && other.getDueBy() == null || getDueBy().equals(this.getDueBy())) {
- return getDescription().compareTo(other.getDescription());
- }
- return getDueBy().compareTo(getDueBy());
- }
- // }}
-
- // {{ helpers
- private static boolean isMoreThanOneWeekInPast(final Date dueBy) {
- return dueBy.getTime() < Clock.getTime() - ONE_WEEK_IN_MILLIS;
- }
-
- // }}
-
- // {{ filters (programmatic)
- @SuppressWarnings("unchecked")
- public static Filter<ToDoItem> thoseDue() {
- return Filters.and(Filters.not(thoseComplete()), new Filter<ToDoItem>() {
- @Override
- public boolean accept(final ToDoItem t) {
- return t.isDue();
- }
- });
- }
-
- public static Filter<ToDoItem> thoseComplete() {
- return new Filter<ToDoItem>() {
- @Override
- public boolean accept(final ToDoItem t) {
- return t.isComplete();
- }
- };
- }
-
- public static Filter<ToDoItem> thoseOwnedBy(final String currentUser) {
- return new Filter<ToDoItem>() {
- @Override
- public boolean accept(final ToDoItem toDoItem) {
- return Objects.equal(toDoItem.getOwnedBy(), currentUser);
- }
-
- };
- }
-
- public static Filter<ToDoItem> thoseSimilarTo(final ToDoItem toDoItem) {
- return new Filter<ToDoItem>() {
- @Override
- public boolean accept(final ToDoItem eachToDoItem) {
- return Objects.equal(toDoItem.getCategory(), eachToDoItem.getCategory()) &&
- Objects.equal(toDoItem.getOwnedBy(), eachToDoItem.getOwnedBy()) &&
- eachToDoItem != toDoItem;
- }
-
- };
- }
- // }}
-
- // {{ injected: DomainObjectContainer
- @SuppressWarnings("unused")
- private DomainObjectContainer container;
-
- public void setDomainObjectContainer(final DomainObjectContainer container) {
- this.container = container;
- }
- // }}
-
- // {{ injected: ToDoItems
- private ToDoItems toDoItems;
-
- public void setToDoItems(final ToDoItems toDoItems) {
- this.toDoItems = toDoItems;
- }
- // }}
-
-}
-----
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_deployment_jvm-flags.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_deployment_jvm-flags.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_deployment_jvm-flags.adoc
deleted file mode 100644
index d359f52..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_deployment_jvm-flags.adoc
+++ /dev/null
@@ -1,18 +0,0 @@
-= 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
-
-
-for the `WrapperFactory` (uses link:http://www.csg.ci.i.u-tokyo.ac.jp/~chiba/javassist/[Javassist])
-
-using:
-
-[source]
-----
--XX:+CMSClassUnloadingEnabled -XX:+UseConcMarkSweepGC
-----
-
-You can hint the JVM to unload dynamically created classes which ClassLoaders are still around.
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_deployment_tomcat.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_deployment_tomcat.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_deployment_tomcat.adoc
deleted file mode 100644
index d25dba6..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_deployment_tomcat.adoc
+++ /dev/null
@@ -1,14 +0,0 @@
-= 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
-
-eg Tomcat
-
-== Externalized Configuration
-
-== JVM Args
-
-== Using a JNDI Datasource
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending.adoc
deleted file mode 100644
index 8f80ea4..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending.adoc
+++ /dev/null
@@ -1,13 +0,0 @@
-= 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::_user-guide_extending_programming-model.adoc[leveloffset=+1]
-
-include::_user-guide_extending_wicket-viewer.adoc[leveloffset=+1]
-
-include::_user-guide_extending_restfulobjects-viewer.adoc[leveloffset=+1]
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_programming-model.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_programming-model.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_programming-model.adoc
deleted file mode 100644
index bd1e959..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_programming-model.adoc
+++ /dev/null
@@ -1,12 +0,0 @@
-= Extending the Programming Model
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-include::_user-guide_extending_programming-model_custom-validator.adoc[leveloffset=+1]
-
-include::_user-guide_extending_programming-model_finetuning.adoc[leveloffset=+1]
-
-include::_user-guide_extending_programming-model_layout-metadata-reader.adoc[leveloffset=+1]
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_programming-model_custom-validator.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_programming-model_custom-validator.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_programming-model_custom-validator.adoc
deleted file mode 100644
index 3ee496d..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_programming-model_custom-validator.adoc
+++ /dev/null
@@ -1,106 +0,0 @@
-= 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 <<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' <<_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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_programming-model_finetuning.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_programming-model_finetuning.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_programming-model_finetuning.adoc
deleted file mode 100644
index 3030665..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_programming-model_finetuning.adoc
+++ /dev/null
@@ -1,79 +0,0 @@
-= 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 Programming 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.
-
-=== Fine-tuning the existing programming model
-
-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 <<_multi_tenancy, Multi-Tenancy>> is now a better solution to that particular use-case.
-====
-
-
-
-
-== Specifying a new programming 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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_programming-model_layout-metadata-reader.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_programming-model_layout-metadata-reader.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_programming-model_layout-metadata-reader.adoc
deleted file mode 100644
index b431d78..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_programming-model_layout-metadata-reader.adoc
+++ /dev/null
@@ -1,43 +0,0 @@
-= 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 <<_static_object_layout, statically>> and <<_dynamic_object_layout, 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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_restfulobjects-viewer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_restfulobjects-viewer.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_restfulobjects-viewer.adoc
deleted file mode 100644
index 1cb2164..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_restfulobjects-viewer.adoc
+++ /dev/null
@@ -1,120 +0,0 @@
-= Extending the Restful 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 Restful Objects viewer implements the http://restfulobjects.org[Restful Object spec], meaning that it:
-
-* defines a well-defined set of endpoint URLs as resources
-* generates a well-defined set of (JSON) representations when these resources are accessed.
-
-There are, however, a number of other "standards" for defining representations, among these:
-
-* 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)
-* 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].
-
-While Isis' Restful Objects viewer only has "out-of-the-box" support for the representations defined in the Restful Objects spec,
-it is possible to plugin a custom representation generator that can produce any arbitrary representation.
-
-[TIP]
-====
-If all that is required is a very simple representations (of objects), you can instead reconfigure RO viewer to provide a simplified output, as described <<_simplified_object_representation, here>>. Or, it is also possible to simply suppress certain elements, as described <<_suppressing_elements_of_the_representations, here>>.
-====
-
-
-== API
-
-The API to implement is the `RepresentationService` API:
-
-[WARNING]
-====
-This API should be considered beta, as it may change in the future in response to emerging requirements
-====
-
-[source,java]
-----
-import javax.ws.rs.core.Response;
-import org.apache.isis.applib.annotation.Programmatic;
-import org.apache.isis.core.metamodel.adapter.ObjectAdapter;
-import org.apache.isis.viewer.restfulobjects.rendering.RendererContext;
-import org.apache.isis.viewer.restfulobjects.rendering.domainobjects.*;
-
-public interface RepresentationService {
-
- @Programmatic
- Response objectRepresentation(
- Context rendererContext,
- ObjectAdapter objectAdapter);
-
- @Programmatic
- Response propertyDetails(
- Context rendererContext,
- ObjectAndProperty objectAndProperty,
- MemberReprMode memberReprMode);
-
- @Programmatic
- Response collectionDetails(
- Context rendererContext,
- ObjectAndCollection objectAndCollection,
- MemberReprMode memberReprMode);
-
- @Programmatic
- Response actionPrompt(
- Context rendererContext,
- ObjectAndAction objectAndAction);
-
- @Programmatic
- Response actionResult(
- Context rendererContext,
- ObjectAndActionInvocation objectAndActionInvocation,
- ActionResultReprRenderer.SelfLink selfLink);
-
- public static interface Context extends RendererContext {
- ObjectAdapterLinkTo getAdapterLinkTo();
- }
-}
-----
-
-
-== Default Implementation
-
-Restful Objects' out-of-the-box support for Restful Objects spec uses this same API, specifically `RepresentationServiceForRestfulObjects` (in the `org.apache.isis.viewer.restfulobjects.rendering.service` package).
-
-Each of these methods provides:
-
-* a `RendererContext` +
-+
-providing 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`
-
-
-== Configuring your Implementation
-
-Implement the service and register in `WEB-INF/isis.properties`, eg:
-
-[source,ini]
-----
-isis.services=...,\
- com.mycompany.myservice.RepresentationServiceForMyRestApi,
- ...
-----
-
-This will replace the default implementatoin.
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_wicket-viewer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_wicket-viewer.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_wicket-viewer.adoc
deleted file mode 100644
index 71f49e3..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_wicket-viewer.adoc
+++ /dev/null
@@ -1,25 +0,0 @@
-= Extending the 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 <<_tweak_the_ui_with_css, tweaking the UI using CSS>>
-* by <<_tweak_the_ui_with_javascript, tweaking the UI using Javascript>>
-* by writing a <<_writing_a_custom_theme, custom bootstrap theme>>
-* by <<_replacing_page_elements, replacing elements of the page>> using the `ComponentFactory` interface
-* by implementing <<_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::_user-guide_extending_wicket-viewer_custom-bootstrap-theme.adoc[leveloffset=+1]
-
-include::_user-guide_extending_wicket-viewer_replacing-page-elements.adoc[leveloffset=+1]
-
-include::_user-guide_extending_wicket-viewer_custom-pages.adoc[leveloffset=+1]
-
-include::_user-guide_extending_wicket-viewer_isis-addons-extensions.adoc[leveloffset=+1]
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_wicket-viewer_custom-bootstrap-theme.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_wicket-viewer_custom-bootstrap-theme.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_wicket-viewer_custom-bootstrap-theme.adoc
deleted file mode 100644
index 72b13d7..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_wicket-viewer_custom-bootstrap-theme.adoc
+++ /dev/null
@@ -1,33 +0,0 @@
-= 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 <<_showing_a_theme_chooser, select other themes>> provided by http://bootswatch.com[bootswatch.com], and if required one of these can be <<_specifying_a_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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_wicket-viewer_custom-pages.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_wicket-viewer_custom-pages.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_wicket-viewer_custom-pages.adoc
deleted file mode 100644
index de8aab4..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_wicket-viewer_custom-pages.adoc
+++ /dev/null
@@ -1,91 +0,0 @@
-= 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 link:./customizing-the-viewer.html[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 <<_user_registration, user registration>> is enabled).
-
-| SIGN_UP_VERIFY
-| The sign-up verification page (if <<_user_registration, 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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_wicket-viewer_isis-addons-extensions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_wicket-viewer_isis-addons-extensions.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_wicket-viewer_isis-addons-extensions.adoc
deleted file mode 100644
index 6ef681b..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_wicket-viewer_isis-addons-extensions.adoc
+++ /dev/null
@@ -1,16 +0,0 @@
-= 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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_wicket-viewer_replacing-page-elements.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_wicket-viewer_replacing-page-elements.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_wicket-viewer_replacing-page-elements.adoc
deleted file mode 100644
index 4462152..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_extending_wicket-viewer_replacing-page-elements.adoc
+++ /dev/null
@@ -1,159 +0,0 @@
-= 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 http://www.isisaddons.org[Isis Add-ons] include the link:isisaddons/isis-wicket-gmap3.html[gmap3], link:isisaddons/isis-wicket-fullcalendar2.html[calendar], link:isisaddons/isis-wicket-excel.html[excel download] and link:isisaddons/isis-wicket-wickedcharts.html[charting] integrations.
-
-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 Wicket 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.
-
-
-
-
-== Adding a Custom Object View (eg a 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);
- ...
- }
-}
-----
-
-
-
[07/22] isis git commit: ISIS-1133: renamed _user-guide_ to _ug_
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_assembling.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_assembling.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_assembling.adoc
deleted file mode 100644
index ce73737..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_assembling.adoc
+++ /dev/null
@@ -1,63 +0,0 @@
-= Assembling
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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
-
-
-
-== Vetoing Visibility
-
-
-
-
-
-== Overriding JDO Annotations
-
-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 <<_using_modules, using modules>>.
-====
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_bulk-actions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_bulk-actions.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_bulk-actions.adoc
deleted file mode 100644
index 9b83333..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_bulk-actions.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= 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
-
-ie `@Action(invokeOn=...)`
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_decoupling.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_decoupling.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_decoupling.adoc
deleted file mode 100644
index cdcaf84..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_decoupling.adoc
+++ /dev/null
@@ -1,25 +0,0 @@
-= 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 <<_assembling, following section>> describes 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::_user-guide_more-advanced_decoupling_db-schemas.adoc[leveloffset=+1]
-
-include::_user-guide_more-advanced_decoupling_contributions.adoc[leveloffset=+1]
-
-include::_user-guide_more-advanced_decoupling_event-bus.adoc[leveloffset=+1]
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_decoupling_contributions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_decoupling_contributions.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_decoupling_contributions.adoc
deleted file mode 100644
index f91e759..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_decoupling_contributions.adoc
+++ /dev/null
@@ -1,7 +0,0 @@
-= 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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_decoupling_db-schemas.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_decoupling_db-schemas.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_decoupling_db-schemas.adoc
deleted file mode 100644
index d341854..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_decoupling_db-schemas.adoc
+++ /dev/null
@@ -1,152 +0,0 @@
-= 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 http://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 <<_overriding_jdo_annotations, Overriding Annotations>> for a write-up of how to do this.
-====
-
-
-
-
-== Listener to create DB schema objects
-
-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]
-----
-package org.apache.isis.objectstore.jdo.datanucleus;
-
-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).
-
-
-
-== Registering an Alternative Implementation
-
-An alternative implementation can be registered and used through the following configuration property:
-
-[source,ini]
-----
-#
-# hook to perform additional initialization when JDO class metadata is loaded
-# default implementation will attempt to run 'create schema' for the specified schema.
-#
-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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_decoupling_event-bus.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_decoupling_event-bus.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_decoupling_event-bus.adoc
deleted file mode 100644
index 5dda011..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_decoupling_event-bus.adoc
+++ /dev/null
@@ -1,136 +0,0 @@
-= 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
-
-## Publishing and Subscribing to Events (Pulling Changes)
-
-
-
-## Pushing Changes
-
-NOTE: this technique is much less powerful than the event bus described in <<Publishing and Subscribing to Events (Pulling Changes)>>). 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 added to or removed from
-
-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; // <1>
-
- 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) {
- numMaleEmployees += countOneMale(employee); // <2>
- numFemaleEmployees += countOneFemale(employee); // <2>
- employees.add(employee);
- }
- public void removeFromEmployees(Employee employee) {
- numMaleEmployees -= countOneMale(employee); // <3>
- numFemaleEmployees -= countOneFemale(employee); // <3>
- 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 and female employees (getters and setters omitted)
-<2> the `addTo...()` method increments the derived properties
-<3> the `removeTo...()` method similarly decrements the derived properties
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_i18n.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_i18n.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_i18n.adoc
deleted file mode 100644
index a9c3292..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_i18n.adoc
+++ /dev/null
@@ -1,606 +0,0 @@
-= 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/a/14327683/56880[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.
-
-
-
-
-== Service API and Implementation
-
-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` (implementation)
-
-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 <<_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 <<_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.
-
-== Translating validation and other (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 <<_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 <<_domain_object_container, `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 <<_exception_recognizer, `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 <<_integration_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 <<_exception_recognizer, ``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 link:../reference/externalized-configuration.html[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]
-----
-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.
-
-
-
-
-== Migrating from v1.6.0 to 1.7.0
-
-In v1.7.0 we've continued the work started in link:migrating-to-1.6.0.html[1.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]
-----
-<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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_multi-tenancy.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_multi-tenancy.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_multi-tenancy.adoc
deleted file mode 100644
index 4f99008..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_multi-tenancy.adoc
+++ /dev/null
@@ -1,7 +0,0 @@
-= 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
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_neo4j.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_neo4j.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_neo4j.adoc
deleted file mode 100644
index 95d27a7..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_neo4j.adoc
+++ /dev/null
@@ -1,58 +0,0 @@
-= 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 <<_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 <<_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 <<_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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_persistence-lifecycle.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_persistence-lifecycle.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_persistence-lifecycle.adoc
deleted file mode 100644
index 5226979..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_persistence-lifecycle.adoc
+++ /dev/null
@@ -1,7 +0,0 @@
-= 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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_tips-n-tricks.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_tips-n-tricks.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_tips-n-tricks.adoc
deleted file mode 100644
index c555440..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_tips-n-tricks.adoc
+++ /dev/null
@@ -1,20 +0,0 @@
-= 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/
-
-IMPORTANT: TODO
-
-
-include::_user-guide_more-advanced_tips-n-tricks_are-you-sure.adoc[leveloffset=+1]
-
-include::_user-guide_more-advanced_tips-n-tricks_simulating-collections-of-values.adoc[leveloffset=+1]
-
-include::_user-guide_more-advanced_tips-n-tricks_render-all-properties-in-tables.adoc[leveloffset=+1]
-
-include::_user-guide_more-advanced_tips-n-tricks_per-user-themes.adoc[leveloffset=+1]
-
-include::_user-guide_more-advanced_tips-n-tricks_suppress-actions-from-the-ui.adoc[leveloffset=+1]
-
-include::_user-guide_more-advanced_tips-n-tricks_enhance-only.adoc[leveloffset=+1]
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_tips-n-tricks_are-you-sure.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_tips-n-tricks_are-you-sure.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_tips-n-tricks_are-you-sure.adoc
deleted file mode 100644
index b5b1522..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_tips-n-tricks_are-you-sure.adoc
+++ /dev/null
@@ -1,47 +0,0 @@
-= '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[]
-
-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));
-
- // invalid to return 'this' (cannot render a deleted object)
- return toDoItems.notYetComplete();
-}
-public String validateDelete(boolean areYouSure) {
- return areYouSure? null: "Please confirm you are sure";
-}
-----
-
-Note that the action itself does not use the boolean parameter, it is only
-used by the supporting `validateXxx()` method.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_tips-n-tricks_enhance-only.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_tips-n-tricks_enhance-only.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_tips-n-tricks_enhance-only.adoc
deleted file mode 100644
index a490b68..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_tips-n-tricks_enhance-only.adoc
+++ /dev/null
@@ -1,18 +0,0 @@
-= 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/
-
-IMPORTANT: TODO
-
-
-== Question:
-
-Is there a simple way to make a run configuration in IntelliJ for running the datanucleus enhancer before running integration test?
-
-== Answer:
-
-* 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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_tips-n-tricks_per-user-themes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_tips-n-tricks_per-user-themes.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_tips-n-tricks_per-user-themes.adoc
deleted file mode 100644
index a8ee6b0..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_tips-n-tricks_per-user-themes.adoc
+++ /dev/null
@@ -1,85 +0,0 @@
-= 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/
-
-== Question:
-
-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?
-
-== Answer:
-
-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/blob/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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_tips-n-tricks_render-all-properties-in-tables.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_tips-n-tricks_render-all-properties-in-tables.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_tips-n-tricks_render-all-properties-in-tables.adoc
deleted file mode 100644
index 04976fd..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_tips-n-tricks_render-all-properties-in-tables.adoc
+++ /dev/null
@@ -1,51 +0,0 @@
-= Render all 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() {
- // workaround for ISIS-582
- return null;
- }
- ...
-}
-----
-
-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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_tips-n-tricks_simulating-collections-of-values.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_tips-n-tricks_simulating-collections-of-values.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_tips-n-tricks_simulating-collections-of-values.adoc
deleted file mode 100644
index d0fa519..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_tips-n-tricks_simulating-collections-of-values.adoc
+++ /dev/null
@@ -1,20 +0,0 @@
-= Simulating 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/
-
-
-IMPORTANT: TODO
-
-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
-
-
-== Persistence Concerns
-
-* easiest to simply store using DataNucleus' support for collections, marked as @Ignore. 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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_tips-n-tricks_suppress-actions-from-the-ui.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_tips-n-tricks_suppress-actions-from-the-ui.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_tips-n-tricks_suppress-actions-from-the-ui.adoc
deleted file mode 100644
index d074e71..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_tips-n-tricks_suppress-actions-from-the-ui.adoc
+++ /dev/null
@@ -1,13 +0,0 @@
-= Suppressing actions from the UI
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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
-
-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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_transactions-and-errors.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_transactions-and-errors.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_transactions-and-errors.adoc
deleted file mode 100644
index d666d0a..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_transactions-and-errors.adoc
+++ /dev/null
@@ -1,26 +0,0 @@
-= 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 <<_isis_jdo_support, 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
-
-
-
-== Exception Recognizers
-
-IMPORTANT: TODO
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_view-models.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_view-models.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_view-models.adoc
deleted file mode 100644
index 2d23d59..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced_view-models.adoc
+++ /dev/null
@@ -1,10 +0,0 @@
-= 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: TODO
-
-== `@ViewModel`
-
-== `ViewModel` interface
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference.adoc
deleted file mode 100644
index 62324ed..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference.adoc
+++ /dev/null
@@ -1,25 +0,0 @@
-= Reference
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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
-
-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.
-
-Some of the services defined in the applib are intended to be used (primarily) not by your domain objects but instead by Isis itself. A good example of this is the <<__code_auditingservice3_code, `AuditingService3`>> 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 `EmailService` that is of direct use for domain objects wishing to send out emails, but is also used by the framework to support the user registration functionality supported by the <<_wicket_viewer, Wicket viewer>>. The same is true of the <<__code_eventbusservice_code, `EventBusService`>>; this can be used by domain objects to broadcast arbitrary events, but is also used by the framework to automatically emit events eg for `@Action(domainEvent=...)`. For these hybrid services we we have categorized the service as an "API" service.
-
-
-include::_user-guide_reference_annotations.adoc[leveloffset=+1]
-include::_user-guide_reference_prefixes.adoc[leveloffset=+1]
-include::_user-guide_reference_methods.adoc[leveloffset=+1]
-include::_user-guide_reference_services-api.adoc[leveloffset=+1]
-include::_user-guide_reference_services-spi.adoc[leveloffset=+1]
-include::_user-guide_reference_superclasses.adoc[leveloffset=+1]
-include::_user-guide_reference_value-types.adoc[leveloffset=+1]
-include::_user-guide_reference_applib-utility-classes.adoc[leveloffset=+1]
-include::_user-guide_reference_mixins.adoc[leveloffset=+1]
-include::_user-guide_reference_addons.adoc[leveloffset=+1]
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_addons.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_addons.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_addons.adoc
deleted file mode 100644
index caa04de..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_addons.adoc
+++ /dev/null
@@ -1,17 +0,0 @@
-= Isis Addons
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 highlights a number of the addons available at http://isisaddons.org[Isis Addons] website. Note that it is _not_ intended to be comprehensive.
-
-[NOTE]
-====
-The http://isisaddons.org[Isis Addons], while maintained by Isis committers, are entirely independent of the Apache Software Foundation.
-====
-
-
-include::_user-guide_reference_addons_settings-module.adoc[leveloffset=+1]
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_addons_settings-module.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_addons_settings-module.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_addons_settings-module.adoc
deleted file mode 100644
index 8355192..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_addons_settings-module.adoc
+++ /dev/null
@@ -1,49 +0,0 @@
-= Settings 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/
-
-
-The http://github.com/isisaddons/isis-module-settings}[Isis addons' settings] module provides a simple way to store both global (application-level) settings as well as per-user settings.
-
-The settings service is documented here for your convenience; the full README can be found on the http://github.com/isisaddons/isis-module-settings}[github site].
-
-
-== Application Settings
-
-=== API
-
-IMPORTANT: TODO
-
-=== Implementation
-
-In the case of `ApplicationSettingsService`, the service is implemented by `ApplicationSettingsServiceJdo`, with the `ApplicationSetting` interface implemented by a `ApplicationSettingsJdo` entity.
-
-The service also provides the ability to create list all existing settings, create new settings (of whichever datatype), update settings, and to delete settings.
-
-These actions can be hidden using security if need be.
-
-== User Settings
-
-=== API
-
-IMPORTANT: TODO
-
-=== Implementation
-
-In the case of `UserSettingsService`, the service is implemented by `UserSettingsServiceJdo`, with the `UserSetting` interface implemented by a `UserSettingsJdo` entity.
-
-As for application settings, the user settings service also provides the ability to create list all existing settings, create new settings (of whichever datatype), update settings, and to delete settings.
-
-These actions can be hidden using security if need be.
-
-
-== Registration and Configuration
-
-The `ApplicationSettingsServiceJdo` class and `UserSettingsServiceJdo` are annotated with `@DomainService` and so are automatically registered with the framework, with actions appearing on the secondary menu bar.
-
-IMPORTANT: TODO - screenshot of settings menu
-
-All actions from the services emit domain events. If you wish to hide/disable these default actions in your application, we recommend using up a subscriber on the actions' domain events to veto their visibility/usability.
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations.adoc
deleted file mode 100644
index d8f34bc..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_annotations.adoc
+++ /dev/null
@@ -1,39 +0,0 @@
-= 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/
-
-IMPORTANT: TODO
-
-
-include::_user-guide_reference_annotations_aaa.adoc[leveloffset=+1]
-
-include::_user-guide_reference_annotations_manpage_action.adoc[leveloffset=+1]
-include::_user-guide_reference_annotations_manpage_actionlayout.adoc[leveloffset=+1]
-include::_user-guide_reference_annotations_manpage_collection.adoc[leveloffset=+1]
-include::_user-guide_reference_annotations_manpage_collectionlayout.adoc[leveloffset=+1]
-include::_user-guide_reference_annotations_manpage_domainobject.adoc[leveloffset=+1]
-include::_user-guide_reference_annotations_manpage_domainobjectlayout.adoc[leveloffset=+1]
-include::_user-guide_reference_annotations_manpage_domainservice.adoc[leveloffset=+1]
-include::_user-guide_reference_annotations_manpage_domainservicelayout.adoc[leveloffset=+1]
-include::_user-guide_reference_annotations_manpage_parameter.adoc[leveloffset=+1]
-include::_user-guide_reference_annotations_manpage_property.adoc[leveloffset=+1]
-include::_user-guide_reference_annotations_manpage_propertylayout.adoc[leveloffset=+1]
-include::_user-guide_reference_annotations_manpage_viewmodel.adoc[leveloffset=+1]
-include::_user-guide_reference_annotations_manpage_viewmodellayout.adoc[leveloffset=+1]
-
-
-include::_user-guide_reference_annotations_manpage_facets.adoc[leveloffset=+1]
-include::_user-guide_reference_annotations_manpage_homepage.adoc[leveloffset=+1]
-include::_user-guide_reference_annotations_manpage_membergrouplayout.adoc[leveloffset=+1]
-include::_user-guide_reference_annotations_manpage_memberorder.adoc[leveloffset=+1]
-include::_user-guide_reference_annotations_manpage_programmatic.adoc[leveloffset=+1]
-include::_user-guide_reference_annotations_manpage_minlength.adoc[leveloffset=+1]
-include::_user-guide_reference_annotations_manpage_title.adoc[leveloffset=+1]
-
-
-include::_user-guide_reference_annotations_manpage_requestscoped.adoc[leveloffset=+1]
-include::_user-guide_reference_annotations_manpage_inject.adoc[leveloffset=+1]
-include::_user-guide_reference_annotations_manpage_digits.adoc[leveloffset=+1]
-
-
[10/22] isis git commit: ISIS-1133: renamed _user-guide_ to _ug_
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_dev-env_intellij.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_dev-env_intellij.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_dev-env_intellij.adoc
deleted file mode 100644
index 3401805..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_dev-env_intellij.adoc
+++ /dev/null
@@ -1,363 +0,0 @@
-= 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
-
-
-
-== Installing and Setting up
-
-=== Download and Install
-
-WARNING: This doc used IntelliJ Community Edition 14.1.1, with screenshots taken for Windows. If you're a MacOS user, I'm sure you can adapt :-)
-
-https://www.jetbrains.com/idea/download/[Download] latest version of IntelliJ Community Edition, and install:
-
-Start the wizard, click through the welcome page:
-
-.IntelliJ Installation Wizard - Welcome page
-image::{_imagesdir}appendices/dev-env/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
-
-=== Setting up JRebel
-
-IMPORTANT: TODO
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_dev-env_isis-maven-plugin.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_dev-env_isis-maven-plugin.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_dev-env_isis-maven-plugin.adoc
deleted file mode 100644
index d56f37d..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_dev-env_isis-maven-plugin.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= 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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_migration-notes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_migration-notes.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_migration-notes.adoc
deleted file mode 100644
index 10aa1d2..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_migration-notes.adoc
+++ /dev/null
@@ -1,322 +0,0 @@
-= 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).
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_release-notes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_release-notes.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_release-notes.adoc
deleted file mode 100644
index 266879e..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_appendices_release-notes.adoc
+++ /dev/null
@@ -1,126 +0,0 @@
-= 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 http://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]
-| RestfulObjects 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 http://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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts.adoc
deleted file mode 100644
index b5a5833..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts.adoc
+++ /dev/null
@@ -1,24 +0,0 @@
-= 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::_user-guide_core-concepts_philosophy.adoc[leveloffset=+1]
-
-include::_user-guide_core-concepts_principles.adoc[leveloffset=+1]
-
-include::_user-guide_core-concepts_building-blocks.adoc[leveloffset=+1]
-
-include::_user-guide_core-concepts_framework-provided-services.adoc[leveloffset=+1]
-
-include::_user-guide_core-concepts_add-ons.adoc[leveloffset=+1]
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_add-ons.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_add-ons.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_add-ons.adoc
deleted file mode 100644
index 5b01d80..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_add-ons.adoc
+++ /dev/null
@@ -1,7 +0,0 @@
-= 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/
-
-IMPORTANT: TODO
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_building-blocks.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_building-blocks.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_building-blocks.adoc
deleted file mode 100644
index 0c04071..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_building-blocks.adoc
+++ /dev/null
@@ -1,237 +0,0 @@
-= Building Blocks
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-IMPORTANT: TODO
-
-## A MetaModel with Explicit and Inferred Semantics
-
-* use of annotations
-** reuse JEE annotations where possible
-* layout hints are overridable, to avoid restarting the app/speed up feedback
-
-
-## Domain Objects and Domain Services
-
-* domain model
-** domain objects
-*** domain entity
-*** view model
-** domain service
-** value type
-
-Anything else can be (should be) ignored by annotating with `@Programmatic`.
-
-
-
-## Properties, Collections and Actions
-
-
-
-## Domain Entities vs View Models
-
-`@DomainObject(nature=...)`
-
-
-
-## Domain Services
-
-Domain services consist of a set of logically grouped actions, and as such follow the same conventions as for entities. However, a service cannot have (persisted) properties, nor can it have (persisted) collections.
-
-Domain services are instantiated once and once only by the framework, and are used to centralize any domain logic that does not logically belong in a domain entity or value. Isis will automatically inject services into every domain entity that requests them, and into each other.
-
-For convenience you can inherit from AbstractService or one of its subclasses, but this is not mandatory.
-
-### Domain Services vs View Services
-
-`@DomainService(nature=...)`
-
-.Factories, Repositories and Services
-****
-A distinction is sometimes made between a factory (that creates object) and a repository (that is used to find existing objects). You will find them discussed separately in Evans' link:Domain Driven Design[http://books.google.com/books/about/Domain_Driven_Design.html?id=hHBf4YxMnWMC], for example.
-
-In Apache Isis these are all implemented as domain services. Indeed, it is quite common to have a domain service that acts as both a factory and a repository.
-****
-
-## Value Objects (Primitives)
-
-
-
-## Contributions
-
-
-
-## Event Bus
-
-
-
-
-
-
-=== Registering domain services
-
-As noted link:../../how-tos/how-to-09-010-How-to-register-domain-services,-repositories-and-factories.html[elsewhere], domain services (which includes repositories and factories) should be registered in the `isis.properties` configuration file, under `isis.services` key (a comma-separated list):
-
-For example:
-
-[source]
-----
-isis.services = com.mycompany.myapp.employee.Employees\,
- com.mycompany.myapp.claim.Claims\,
- ...
-----
-
-This will then result in the framework instantiating a single instance of each of the services listed.
-
-If all services reside under a common package, then the `isis.services.prefix` can specify this prefix:
-
-[source]
-----
-isis.services.prefix = com.mycompany.myapp
-isis.services = employee.Employees,\
- claim.Claims,\
- ...
-----
-
-This is quite rare, however; you will often want to use default implementations of domain services that are provided by the framework and so will not reside under this prefix.
-
-Examples of framework-provided services (as defined in the applib) can be found referenced from the main link:../../documentation.html[documentation] page. They include clock, auditing, publishing, exception handling, view model support, snapshots/mementos, and user/application settings management.
-
-=== Service scopes
-
-By default all domain services are considered to be singletons, and thread-safe.
-
-Sometimes though a service's lifetime is applicable only to a single request; in other words it is request-scoped.
-
-The CDI annotation `@javax.enterprise.context.RequestScoped` is used to indicate this fact:
-
-[source]
-----
- @javax.enterprise.context.RequestScoped
- public class MyService extends AbstractService {
- ...
- }
-----
-
-The framework provides a number of request-scoped services; these can be found referenced from the main link:../../documentation.html[documentation] page. They include scratchpad service, query results caching, and support for co-ordinating bulk actions.
-
-=== (Suppressing) contributed actions
-
-Any n-parameter action provided by a service will automatically be contributed to the list of actions for each of its (entity) parameters. From the viewpoint of the entity the action is called a contributed action.
-
-For example, given a service:
-
-[source]
-----
-public interface Library {
- public Loan borrow(Loanable l, Borrower b);
-}
-----
-
-and the entities:
-
-[source]
-----
-public class Book implements Loanable { ... }y
-----
-
-and
-
-[source]
-----
-public class LibraryMember implements Borrower { ... }
-----
-
-then the `borrow(...)` action will be contributed to both `Book` and to `LibraryMember`.
-
-This is an important capability because it helps to decouple the concrete classes from the services.
-
-If necessary, though, this behaviour can be suppressed by annotating the service action with `@org.apache.isis.applib.annotations.NotContributed`.
-
-For example:
-
-[source]
-----
-public interface Library {
- @NotContributed
- public Loan borrow(Loanable l, Borrower b);
-}
-----
-
-If annotated at the interface level, then the annotation will be inherited by every concrete class. Alternatively the annotation can be applied at the implementation class level and only apply to that particular implementation.
-
-Note that an action annotated as being `@NotContributed` will still appear in the service menu for the service. If an action should neither be contributed nor appear in service menu items, then simply annotate it as `@Hidden`.
-
-=== (Suppressing) service menu items
-
-By default every action of a service (by which we also mean repositories and factories) will be rendered in the viewer, eg as a menu item for that service menu. This behaviour can be suppressed by annotating the action using `@org.apache.isis.applib.annotations.NotInServiceMenu`.
-
-For example:
-
-[source]
-----
-public interface Library {
- @NotInServiceMenu
- public Loan borrow(Loanable l, Borrower b);
-}
-----
-
-Note that an action annotated as being `@NotInServiceMenu` will still be contributed. If an action should neither be contributed nor appear in service menu items, then simply annotate it as `@Hidden`.
-
-Alternatively, this can be performed using a supporting method:
-
-[source]
-----
-public class LibraryImpl implements Library {
- public Loan borrow(Loanable l, Borrower b) { ... }
- public boolean notInServiceMenuBorrow() { ... }
-}
-----
-
-=== (Suppressing) service menus
-
-If none of the service menu items should appear, then the service itself should be annotated as `@Hidden`.
-
-For example:
-
-[source]
-----
-@Hidden
-public interface EmailService {
- public void sendEmail(String to, String from, String subject, String body);
- public void forwardEmail(String to, String from, String subject, String body);
-}
-----
-
-=== Initializing Services
-
-Services can optionally declare lifecycle callbacks to initialize them (when the app is deployed) and to shut them down (when the app is undeployed).
-
-An Isis session _is_ available when initialization occurs (so services can interact with the object store, for example).
-
-==== Initialization
-
-The framework will call any `public` method annotated with `@javax.annotation.PostConstruct` and with either no arguments of an argument of type `Map<String,String>`:
-
-or
-
-In the latter case, the framework passes in the configuration (`isis.properties` and any other component-specific configuration files).
-
-==== Shutdown
-
-Shutdown is similar; the framework will call any method annotated with `@javax.annotation.PreDestroy`:
-
-=== The getId() method
-
-Optionally, a service may provide a `getId()` method:
-
-[source]
-----
-public String getId()
-----
-
-This method returns a logical identifier for a service, independent of its implementation. Currently it used only by perspectives, providing a label by which to record the services that are available for a current user's profile. <!--See ? for more about profiles and perspectives.-->
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_framework-provided-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_framework-provided-services.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_framework-provided-services.adoc
deleted file mode 100644
index 50519e1..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_framework-provided-services.adoc
+++ /dev/null
@@ -1,84 +0,0 @@
-= Framework-provided Services
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-IMPORTANT: TODO
-
-## API vs SPI
-
-Most framework domain services are API: they exist to provide support functionality to the application's domain objects and services. In this case an implementation of the service will be available, either by Apache Isis itself or by Isis Addons (non ASF).
-
-Some framework domain services are SPI: they exist primarily so that the application can influence the framework's behaviour. In these cases there is (usually) no default implementation; it is up to the application to provide an implementation.
-
-## Autoregistration of Domain services
-
-Where a domain service has an implementation, it is (almost always) automatically registered just by virtue of being on the `CLASSPATH`.
-
-The one exception is <<ExceptionRecognizer>>.
-
-It is possible to replacing automatically-registered domain services.
-
-
-## Overview of Domain Services
-
-Unless indicated as SPI, each of the following has an implementation in Isis core.
-
-A full list of services (including those with implementations in http://isisaddons.org[Isis Addons] (non-ASF)) can be found in the <<_domain_services_2,Domain Services>> section.
-
-### `DomainObjectContainer`
-
-### `ClockService`
-
-### `IsisSupportJdo`
-
-### `ExceptionRecognizer`
-
-### `WrapperFactory`
-
-### `EventBusService`
-
-### Commands/Background
-
-#### `CommandContext`
-
-#### `BackgroundService`
-
-### Information Sharing
-
-#### `ScratchPad`
-
-#### `ActionInvocationContext`
-
-#### `QueryResultsCache`
-
-### `EmailService`
-
-### UserManagement
-
-#### `UserProfileService` (SPI)
-
-#### `UserRegistrationService` (SPI)
-
-#### `EmailNotificationService`
-
-
-### Bookmarks and Mementos
-
-#### `BookmarkService`
-
-#### `MementoService`
-
-#### `DeepLinkService`
-
-#### `XmlSnapshotService`
-
-
-
-
-
-
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy.adoc
deleted file mode 100644
index 5825c02..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy.adoc
+++ /dev/null
@@ -1,20 +0,0 @@
-= 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::_user-guide_core-concepts_philosophy_domain-driven-design.adoc[leveloffset=+1]
-
-include::_user-guide_core-concepts_philosophy_naked-objects-pattern.adoc[leveloffset=+1]
-
-include::_user-guide_core-concepts_philosophy_hexagonal-architecture.adoc[leveloffset=+1]
-
-include::_user-guide_core-concepts_philosophy_aop.adoc[leveloffset=+1]
-
-// include::_user-guide_core-concepts_philosophy_dci.adoc[leveloffset=+1]
-
-include::_user-guide_core-concepts_philosophy_how-eases-ddd.adoc[leveloffset=+1]
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy_aop.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy_aop.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy_aop.adoc
deleted file mode 100644
index 0ea9a10..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy_aop.adoc
+++ /dev/null
@@ -1,35 +0,0 @@
-= 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 <<_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 <<_decoupling, Decoupling>> chapter. 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 <<_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 bein
g 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 (<<_contributed_members, contributions>>) and interceptors (the <<_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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy_dci.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy_dci.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy_dci.adoc
deleted file mode 100644
index eb54833..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy_dci.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-= 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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy_domain-driven-design.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy_domain-driven-design.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy_domain-driven-design.adoc
deleted file mode 100644
index 0eb7be6..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy_domain-driven-design.adoc
+++ /dev/null
@@ -1,79 +0,0 @@
-= 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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy_hexagonal-architecture.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy_hexagonal-architecture.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy_hexagonal-architecture.adoc
deleted file mode 100644
index 47a05a1..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy_hexagonal-architecture.adoc
+++ /dev/null
@@ -1,28 +0,0 @@
-= 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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy_how-eases-ddd.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy_how-eases-ddd.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy_how-eases-ddd.adoc
deleted file mode 100644
index 275c4fb..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy_how-eases-ddd.adoc
+++ /dev/null
@@ -1,73 +0,0 @@
-= 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 <<_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.
-
[08/22] isis git commit: ISIS-1133: renamed _user-guide_ to _ug_
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_getting-started.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_getting-started.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_getting-started.adoc
deleted file mode 100644
index c260365..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_getting-started.adoc
+++ /dev/null
@@ -1,11 +0,0 @@
-= Getting Started
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-IMPORTANT: TODO
-
-include::_user-guide_getting-started_simpleapp-archetype.adoc[leveloffset=+1]
-
-include::_user-guide_getting-started_datanucleus-enhancer.adoc[leveloffset=+1]
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_getting-started_datanucleus-enhancer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_getting-started_datanucleus-enhancer.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_getting-started_datanucleus-enhancer.adoc
deleted file mode 100644
index a015a4e..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_getting-started_datanucleus-enhancer.adoc
+++ /dev/null
@@ -1,87 +0,0 @@
-= 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/
-
-
-By leveraging the JDO/Datanucleus ORM, Isis' JDO objectstore is very powerful. However, with such power comes a little bit of complexity to the development environment: all domain objects must be enhanced through the http://db.apache.org/jdo/enhancement.html[JDO enhancer]. So the enhancer must, in 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:
-
-[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 <<SimpleApp Archetype>> sets up the plugin correctly in the `dom` (domain object model) module. (It's actually a little bit more complext 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 <<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 <<Setting up Eclipse,here>>.
-====
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_getting-started_simpleapp-archetype.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_getting-started_simpleapp-archetype.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_getting-started_simpleapp-archetype.adoc
deleted file mode 100644
index 1decbc9..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_getting-started_simpleapp-archetype.adoc
+++ /dev/null
@@ -1,7 +0,0 @@
-= SimpleApp Archetype
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../../
-:_imagesdir: images/
-
-IMPORTANT: TODO
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_headless-access.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_headless-access.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_headless-access.adoc
deleted file mode 100644
index 8ac1008..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_headless-access.adoc
+++ /dev/null
@@ -1,114 +0,0 @@
-= 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 <<_wicket_viewer, Wicket>> or <<_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 <<_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.
-
-
-== AbstractIsisSessionTemplate
-
-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.
-====
-
-
-
-== BackgroundCommandExecution
-
-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 shows the dependencies between these various classes:
-
-.Inheritance Hierarchy for `BackgroundCommandExecution`
-image::{_imagesdir}headless-access/BackgroundCommandExecution.png[width="400px"]
-
-[TIP]
-====
-[source]
-.DSL (http://yuml.me/edit/363b335f[yuml.me/363b335f])
-----
-[AbstractIsisSessionTemplate|#doExecute()]^-[BackgroundCommandExecution|#findBackgroundCommandsToExecute()]
-[BackgroundCommandExecution]^-[BackgroundCommandExecutionFromBackgroundCommandServiceJdo]
-[BackgroundCommandExecutionFromBackgroundCommandServiceJdo]->injected[BackgroundCommandServiceJdoRepository|findBackgroundCommandsNotYetStarted()]
-----
-
-====
-
-
-
-=== Background Execution using Isis Addons Command Module (not ASF)
-
-The `BackgroundCommandExecutionFromBackgroundCommandServiceJdo` is a concrete subclass of <<BackgroundCommandExecution>>, 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 http://isisaddons.org/isis-module-command[Isis addons Command Module]'s implementations of <<CommandService>> and <<BackgroundCommandService>> using the `BackgroundCommandServiceJdoRepository`.
-
-The diagram below shows the inheritance hierarchy for this class:
-
-.Inheritance Hierarchy for `BackgroundCommandExecutionFromBackgroundCommandServiceJdo`
-image::{_imagesdir}headless-access/BackgroundCommandExecutionFromBackgroundCommandServiceJdo.png[width="500px"]
-
-
-[TIP]
-====
-[source]
-.DSL (http://yuml.me/edit/25343da1[yuml.me/25343da1]):
-----
-[AbstractIsisSessionTemplate|#doExecute()]^-[BackgroundCommandExecution|#findBackgroundCommandsToExecute()]
-[BackgroundCommandExecution]->injected[BookmarkService|lookup()]
-[BackgroundCommandExecution]->injected[CommandContext|setCommand()]
-----
-
-====
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos.adoc
deleted file mode 100644
index 58e85d6..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos.adoc
+++ /dev/null
@@ -1,25 +0,0 @@
-= Basics
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-IMPORTANT: TODO
-
-include::_user-guide_how-tos_class-structure.adoc[leveloffset=+1]
-
-include::_user-guide_how-tos_ui-hints.adoc[leveloffset=+1]
-
-include::_user-guide_how-tos_domain-services.adoc[leveloffset=+1]
-
-include::_user-guide_how-tos_crud.adoc[leveloffset=+1]
-
-include::_user-guide_how-tos_entity-relationships.adoc[leveloffset=+1]
-
-include::_user-guide_how-tos_contributed-members.adoc[leveloffset=+1]
-
-include::_user-guide_how-tos_business-rules.adoc[leveloffset=+1]
-
-include::_user-guide_how-tos_derived-members.adoc[leveloffset=+1]
-
-include::_user-guide_how-tos_drop-downs-and-defaults.adoc[leveloffset=+1]
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_business-rules.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_business-rules.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_business-rules.adoc
deleted file mode 100644
index c78f198..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_business-rules.adoc
+++ /dev/null
@@ -1,57 +0,0 @@
-= Business Rules
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-IMPORTANT: TODO
-
-## Visibility ("see it")
-
-### Hide a Property
-
-### Hide a Collection
-
-### Hide an Action
-
-### Hide a Contributed Property, Collection or Action
-
-### All Members Hidden
-
-## Usability ("use it")
-
-### Disable a Property
-
-### Disable a Collection
-
-### Disable an Action
-
-### Disable a Contributed Property, Collection or Action
-
-### All Members Unmodifiable (Disabling the Edit Button)
-
-Sometimes an object is unmodifiable.
-
-In the Wicket viewer this means disabling the edit button.
-
-#### Declarative
-
-`@DomainObject(editing=...)`
-
-#### Imperative
-
-
-
-## Validity ("do it")
-
-### Validate (change to) a Property
-
-### Validate (adding or removing from) a Collection
-
-### Validate (arguments to invoke) an Action
-
-### Validating a Contributed Property, Collection or Action
-
-### Declarative validation using `@MustSatisfy`
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_class-structure.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_class-structure.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_class-structure.adoc
deleted file mode 100644
index e775741..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_class-structure.adoc
+++ /dev/null
@@ -1,39 +0,0 @@
-= 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 <<_extending_the_programming_model, here>>.
-====
-
-
-include::_user-guide_how-tos_class-structure_class-definition.adoc[leveloffset=+1]
-
-include::_user-guide_how-tos_class-structure_properties.adoc[leveloffset=+1]
-
-include::_user-guide_how-tos_class-structure_collections.adoc[leveloffset=+1]
-
-include::_user-guide_how-tos_class-structure_actions.adoc[leveloffset=+1]
-
-include::_user-guide_how-tos_class-structure_action-parameters.adoc[leveloffset=+1]
-
-include::_user-guide_how-tos_class-structure_properties-vs-parameters.adoc[leveloffset=+1]
-
-include::_user-guide_how-tos_class-structure_ignoring-methods.adoc[leveloffset=+1]
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_class-structure_action-parameters.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_class-structure_action-parameters.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_class-structure_action-parameters.adoc
deleted file mode 100644
index cccf0fe..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_class-structure_action-parameters.adoc
+++ /dev/null
@@ -1,17 +0,0 @@
-= 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 Length Of Action Parameter
-
-== BigDecimal Precision Of Action Parameter
-
-== Optional Action Argument
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_class-structure_actions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_class-structure_actions.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_class-structure_actions.adoc
deleted file mode 100644
index aa58f5a..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_class-structure_actions.adoc
+++ /dev/null
@@ -1,18 +0,0 @@
-= 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 <<_ignoring_methods, Ignoring Methods>>. This ensures that the collection is ignored by Isis.
-====
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_class-structure_class-definition.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_class-structure_class-definition.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_class-structure_class-definition.adoc
deleted file mode 100644
index 6744e73..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_class-structure_class-definition.adoc
+++ /dev/null
@@ -1,23 +0,0 @@
-= 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: TODO
-
-
-Classes are defined both to Isis and (if any entity) also to JDO/DataNucleus.
-
-
-We use Java packages as a way to group related domain objects together; the package name forms a namespace. We can then reason about all the classes in that package/namespace as a single unit.
-
-In the same way that Java packages act as a namespace for domain objects, it's good practice to map domain entities to their own (database) schemas.
-
-[TIP]
-====
-For more on this topic, see <<_using_modules,Using Modules>>.
-====
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_class-structure_collections.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_class-structure_collections.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_class-structure_collections.adoc
deleted file mode 100644
index a7ef399..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_class-structure_collections.adoc
+++ /dev/null
@@ -1,78 +0,0 @@
-= 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: TODO
-
-
-[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 `@Programmatic`, as described in <<_ignoring_methods, Ignoring Methods>>. This ensures that the collection is ignored by Isis.
-
-Another workaround is to wrap each value in a view model, as explained in this <<_simulating_collections_of_values, tip>>.
-====
-
-
-
-== Managed 1-m bidirectional relationships
-
-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.
-
-[TIP]
-====
-The `modifyXxx()` and `clearXxx()` supporting methods were introduced in the framework primarily to help support implement the mutual registration pattern. This dates from
-====
-
-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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_class-structure_ignoring-methods.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_class-structure_ignoring-methods.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_class-structure_ignoring-methods.adoc
deleted file mode 100644
index ee47a7d..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_class-structure_ignoring-methods.adoc
+++ /dev/null
@@ -1,15 +0,0 @@
-= 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: TODO
-
-
-Sometimes you want to define a `public` method on a domain object that is not intended to be rendered in Isis' UI.
-
-To exclude such methods, use the `@Programmatic` annotation.
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_class-structure_properties-vs-parameters.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_class-structure_properties-vs-parameters.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_class-structure_properties-vs-parameters.adoc
deleted file mode 100644
index 374093c..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_class-structure_properties-vs-parameters.adoc
+++ /dev/null
@@ -1,45 +0,0 @@
-= 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: TODO
-
-
-
-In many cases the value types of properties and of action parameters align. For example, a `Customer` entity might have a `surname` property, and there might also be corresponding `changeSurname`. Ideally we want the surname property and surname action parameter to use the same value type.
-
-Having first-class support for this is a goal of 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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_class-structure_properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_class-structure_properties.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_class-structure_properties.adoc
deleted file mode 100644
index 29d051c..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_class-structure_properties.adoc
+++ /dev/null
@@ -1,282 +0,0 @@
-= 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 <<_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]
-----
-@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)`.
-
-
-
-
-
-== Mapping String (Length)
-
-IMPORTANT: TODO
-
-
-
-
-
-== 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:
-
-
-
-
-== Mapping BigDecimals
-
-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 link:mapping-joda-dates.html[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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_contributed-members.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_contributed-members.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_contributed-members.adoc
deleted file mode 100644
index 394cdfb..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_contributed-members.adoc
+++ /dev/null
@@ -1,15 +0,0 @@
-= Contributed Members
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-IMPORTANT: TODO
-
-## Contributed Action
-
-## Contributed Property
-
-## Contributed Collection
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_crud.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_crud.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_crud.adoc
deleted file mode 100644
index 54517f8..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_crud.adoc
+++ /dev/null
@@ -1,22 +0,0 @@
-= Object Management (CRUD)
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-IMPORTANT: TODO
-
-## Injecting Services
-
-## Instantiating and Persisting Objects
-
-## Finding Objects
-
-### Using DataNucleus type-safe queries
-
-as per http://github.com/isisaddons/isis-app-todoapp}[Isis addons' todoapp] (non-ASF)
-
-## Deleting Objects
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_derived-members.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_derived-members.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_derived-members.adoc
deleted file mode 100644
index c0e8e8e..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_derived-members.adoc
+++ /dev/null
@@ -1,33 +0,0 @@
-= Derived Members
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-IMPORTANT: TODO
-
-## Derived Property
-
-## Derived Collection
-
-
-.Inlining query-only repository action
-****
-While derived properties and derived collections typically "walk the graph" to associated objects, there is nothing to prevent the returned value being the result of invoking a repository (domain service) action.
-
-For example:
-
-[source,java]
-----
-public class Customer {
- ...
- public List<Order> getMostRecentOrders() {
- return orderRepo.findMostRecentOrders(this, 5);
- }
-}
-----
-****
-
-## Trigger on property change
-
-## Trigger on collection change
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_domain-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_domain-services.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_domain-services.adoc
deleted file mode 100644
index ef7e4ad..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_domain-services.adoc
+++ /dev/null
@@ -1,23 +0,0 @@
-= 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/
-
-IMPORTANT: TODO
-
-
-
-## Singleton & request-scoped services
-
-IMPORTANT: TODO
-
-
-It's worth extending the <<_hexagonal_architecture, Hexagonal Architecture> to show where domain services -- and in particular the domain services provided by http://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 a number of in-built domain services.
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_drop-downs-and-defaults.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_drop-downs-and-defaults.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_drop-downs-and-defaults.adoc
deleted file mode 100644
index 643c705..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_drop-downs-and-defaults.adoc
+++ /dev/null
@@ -1,30 +0,0 @@
-= Drop Downs and Defaults
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-IMPORTANT: TODO
-
-## For Properties
-
-### Choices for Property
-
-### Auto-complete for property
-
-### Default for property
-
-## For Action Parameters
-
-### Choices for action parameter
-
-### Dependent choices for action params
-
-### Auto-complete for action param
-
-### Default for action param
-
-## For both Properties and Action Parameters
-
-### Drop-down for limited number of instances
-
-### Auto-complete (repository-based)
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_entity-relationships.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_entity-relationships.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_entity-relationships.adoc
deleted file mode 100644
index b7f7d7f..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_entity-relationships.adoc
+++ /dev/null
@@ -1,11 +0,0 @@
-= Entity Relationships
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-IMPORTANT: TODO
-
-## Mapping Mandatory and Optional Properties
-
-## Managed 1-m bidirectional relationships
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_ui-hints.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_ui-hints.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_ui-hints.adoc
deleted file mode 100644
index f8e6e1a..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_ui-hints.adoc
+++ /dev/null
@@ -1,17 +0,0 @@
-= 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/
-
-IMPORTANT: TODO
-
-include::_user-guide_how-tos_ui-hints_object-titles-and-icons.adoc[leveloffset=+1]
-
-include::_user-guide_how-tos_ui-hints_names-and-descriptions.adoc[leveloffset=+1]
-
-include::_user-guide_how-tos_ui-hints_layout.adoc[leveloffset=+1]
-
-include::_user-guide_how-tos_ui-hints_eager-rendering.adoc[leveloffset=+1]
-
-include::_user-guide_how-tos_ui-hints_action-icons-and-css.adoc[leveloffset=+1]
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_ui-hints_action-icons-and-css.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_ui-hints_action-icons-and-css.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_ui-hints_action-icons-and-css.adoc
deleted file mode 100644
index a2db15e..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_ui-hints_action-icons-and-css.adoc
+++ /dev/null
@@ -1,60 +0,0 @@
-= 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: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: TODO - more words here...
-
-* `@CssClassFa`
-* `@CssClass`
-
-Alternatively, you can specify these hints in the `Xxx.layout.json` for the entity:
-
-IMPORTANT: TODO
-
-
-== Per pattern matching
-
-Rather than annotating every action with `@CssClassFa` and `@CssClass`, you can instead specify the UI hint globally using regular expressions.
-
-The `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: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 `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 `@CssClassFa` or `@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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_ui-hints_eager-rendering.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_ui-hints_eager-rendering.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_ui-hints_eager-rendering.adoc
deleted file mode 100644
index 1636aac..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_ui-hints_eager-rendering.adoc
+++ /dev/null
@@ -1,57 +0,0 @@
-= 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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_ui-hints_layout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_ui-hints_layout.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_ui-hints_layout.adoc
deleted file mode 100644
index 8f8bdcf..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_ui-hints_layout.adoc
+++ /dev/null
@@ -1,14 +0,0 @@
-= 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/
-
-IMPORTANT: TODO
-
-
-== Layout using annotations
-
-== Dynamic layouts
-
-== Application menu layout
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_ui-hints_names-and-descriptions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_ui-hints_names-and-descriptions.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_ui-hints_names-and-descriptions.adoc
deleted file mode 100644
index 04ab662..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_ui-hints_names-and-descriptions.adoc
+++ /dev/null
@@ -1,41 +0,0 @@
-= 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 <<_i18n, Internationalization>>
-
-== Class (object)
-
-IMPORTANT: TODO
-
-== Property
-
-IMPORTANT: TODO
-
-== Collections
-
-IMPORTANT: TODO
-
-== Actions
-
-IMPORTANT: TODO
-
-== Action Parameters
-
-IMPORTANT: WIP
-
-Use `@ParameterLayout(named=...)` or `@Named(...)`
-
-[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 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 <<_upgrading_to_java_8_1_9_0_snapshot_and_later,upgrading to Java 8>>.
-====
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_ui-hints_object-titles-and-icons.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_ui-hints_object-titles-and-icons.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_ui-hints_object-titles-and-icons.adoc
deleted file mode 100644
index 7b3260f..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_ui-hints_object-titles-and-icons.adoc
+++ /dev/null
@@ -1,94 +0,0 @@
-= 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 <<_object_title, title>> (label) and an <<_object_icon, 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 return a <<_object_css_styling, CSS class>>. In conjunction with <<_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 `@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. See <<_titles_in_tables, here>> for further discussion.
-====
-
-
-=== Imperative style
-
-IMPORTANT: TODO
-
-
-
-
-== 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
-
-
-== Object CSS Styling
-
-
-It is also possible for an object to return a <<_object_css_styling, CSS class>>. In conjunction with <<_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
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_isis-addons-modules.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_isis-addons-modules.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_isis-addons-modules.adoc
deleted file mode 100644
index 7a90efe..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_isis-addons-modules.adoc
+++ /dev/null
@@ -1,115 +0,0 @@
-= Isis Addons Modules (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 http://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-auditing}[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.
-
-== Command Service (persistence)
-
-IMPORTANT: TODO
-
-=== API
-=== Isis addons implementation
-
-
-
-== Background Command Service
-
-IMPORTANT: TODO
-
-=== API
-=== Background Execution
-=== Isis addons implementation
-
-
-
-== Auditing
-
-IMPORTANT: TODO
-
-=== Auditing API
-=== Isis addons implementation
-
-
-
-
-== Publishing Service
-
-IMPORTANT: TODO
-
-=== API
-=== Isis addons implementation
-
-
-=== Event Serializer
-
-Isis' PublishingService API also has a companion API, the `EventSerializer`. This provides a pluggable mechanism by which the event can be rendered into different formats.
-
-The http://github.com/isisaddons/isis-module-publishing}[Isis addons' publishing] module provides an implementation of this API -- `RestfulObjectsSpecEventSerializer` -- that reuses part of the implementation of the Restful Objects viewer to serialize the the provided `EventPayload` into the form specified by the http://restfulobjects.org[Restful Objects spec].
-
-For example, this is the JSON generated on an action invocation:
-
-.JSON generated by action invocation
-image::{_imagesdir}isis-addons-modules/action-invocation-published-to-stderr.png[width="750px"]
-
-while this is the object change JSON:
-
-.JSON generated by action invocation
-image::{_imagesdir}isis-addons-modules/changed-object-published-to-stderr.png[width="750px"]
-
-You could if you wish change the representation by registering your own implementation of this API in `isis.properties`:
-
-[source,ini]
-----
-isis.services=...\
- com.mycompany.myapp.MyEventSerializer,\
- ...
-----
-
-
-
-== Security
-
-IMPORTANT: TODO
-
-
-
-== Other Isis Addons
-
-IMPORTANT: TODO
-
-=== Developer Utilities
-=== Docx Mail merge
-=== Excel download/upload
-=== Fake Data
-=== Poly
-=== Session Logger
-=== Settings
-=== String interpolator
-=== Tags
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced.adoc
deleted file mode 100644
index dc62e39..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_more-advanced.adoc
+++ /dev/null
@@ -1,32 +0,0 @@
-= 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/
-
-IMPORTANT: TODO
-
-
-include::_user-guide_more-advanced_decoupling.adoc[leveloffset=+1]
-
-include::_user-guide_more-advanced_assembling.adoc[leveloffset=+1]
-
-include::_user-guide_more-advanced_bulk-actions.adoc[leveloffset=+1]
-
-include::_user-guide_more-advanced_view-models.adoc[leveloffset=+1]
-
-include::_user-guide_more-advanced_transactions-and-errors.adoc[leveloffset=+1]
-
-include::_user-guide_more-advanced_i18n.adoc[leveloffset=+1]
-
-include::_user-guide_more-advanced_multi-tenancy.adoc[leveloffset=+1]
-
-include::_user-guide_more-advanced_persistence-lifecycle.adoc[leveloffset=+1]
-
-include::_user-guide_more-advanced_neo4j.adoc[leveloffset=+1]
-
-include::_user-guide_more-advanced_tips-n-tricks.adoc[leveloffset=+1]
-
-
-
-
-
[02/22] isis git commit: ISIS-1133: renamed _user-guide_ to _ug_
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_integ-test-support_maven-configuration.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_integ-test-support_maven-configuration.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_integ-test-support_maven-configuration.adoc
deleted file mode 100644
index 609c52b..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_integ-test-support_maven-configuration.adoc
+++ /dev/null
@@ -1,45 +0,0 @@
-= 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 <<_simpleapp_archetype, SimpleApp archetype>>. To set it up manually, update the `pom.xml` of your domain object model module:
-
-[source]
-----
-<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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_integ-test-support_typical-usage.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_integ-test-support_typical-usage.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_integ-test-support_typical-usage.adoc
deleted file mode 100644
index 1f2dd0b..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_integ-test-support_typical-usage.adoc
+++ /dev/null
@@ -1,123 +0,0 @@
-= 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 <<_fixture_scripts, `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:assertj.org[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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_integ-test-support_wrapper-factory.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_integ-test-support_wrapper-factory.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_integ-test-support_wrapper-factory.adoc
deleted file mode 100644
index e1f0d74..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_integ-test-support_wrapper-factory.adoc
+++ /dev/null
@@ -1,161 +0,0 @@
-= 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 `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: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 <<_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 <<__code_EventBusService_code, `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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_overview.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_overview.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_overview.adoc
deleted file mode 100644
index 790c8bc..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_overview.adoc
+++ /dev/null
@@ -1,165 +0,0 @@
-= 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://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 <<_wrapper_factory, `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 <<_fixture_scripts, 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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_unit-test-support.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_unit-test-support.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_unit-test-support.adoc
deleted file mode 100644
index 2f02863..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_unit-test-support.adoc
+++ /dev/null
@@ -1,12 +0,0 @@
-= 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::_user-guide_testing_unit-test-support_contract-tests.adoc[leveloffset=+1]
-include::_user-guide_testing_unit-test-support_jmock-extensions.adoc[leveloffset=+1]
-include::_user-guide_testing_unit-test-support_maven-configuration.adoc[leveloffset=+1]
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_unit-test-support_contract-tests.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_unit-test-support_contract-tests.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_unit-test-support_contract-tests.adoc
deleted file mode 100644
index 0de8cfd..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_unit-test-support_contract-tests.adoc
+++ /dev/null
@@ -1,169 +0,0 @@
-= 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 link:../more-advanced-topics/how-to-04-060-How-to-set-up-and-maintain-bidirectional-relationships.html[mutual registration pattern]
-
-TIP: If using the link:../components/objectstores/jdo/about.html[JDO Object Store], then there is generally no need to programmatically maintain 1:m relationships (indeed it may introduce subtle errors). For more details, see link:../components/objectstores/jdo/managed-1-to-m-relationships.html[here]. Check out the link:../intro/resources/editor-templates.html[Eclipse 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 {
- protected ClockService clockService;
- public void injectClockService(ClockService clockService) {
- this.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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_unit-test-support_jmock-extensions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_unit-test-support_jmock-extensions.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_unit-test-support_jmock-extensions.adoc
deleted file mode 100644
index c58dcc3..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_unit-test-support_jmock-extensions.adoc
+++ /dev/null
@@ -1,58 +0,0 @@
-= 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://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.csg.ci.i.u-tokyo.ac.jp/~chiba/javassist/[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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_unit-test-support_maven-configuration.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_unit-test-support_maven-configuration.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_unit-test-support_maven-configuration.adoc
deleted file mode 100644
index 26f00ed..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_unit-test-support_maven-configuration.adoc
+++ /dev/null
@@ -1,45 +0,0 @@
-= 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 <<_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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_troubleshooting.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_troubleshooting.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_troubleshooting.adoc
deleted file mode 100644
index fd42f26..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_troubleshooting.adoc
+++ /dev/null
@@ -1,13 +0,0 @@
-= Trouble Shooting
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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::_user-guide_troubleshooting_enabling-logging.adoc[leveloffset=+1]
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_troubleshooting_enabling-logging.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_troubleshooting_enabling-logging.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_troubleshooting_enabling-logging.adoc
deleted file mode 100644
index 533273c..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_troubleshooting_enabling-logging.adoc
+++ /dev/null
@@ -1,38 +0,0 @@
-= 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 <<_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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer.adoc
deleted file mode 100644
index 3c5efb0..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer.adoc
+++ /dev/null
@@ -1,29 +0,0 @@
-= 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::_user-guide_wicket-viewer_features.adoc[leveloffset=+1]
-
-include::_user-guide_wicket-viewer_configuration_properties.adoc[leveloffset=+1]
-
-include::_user-guide_wicket-viewer_request-parameters.adoc[leveloffset=+1]
-
-include::_user-guide_wicket-viewer_layout.adoc[leveloffset=+1]
-
-include::_user-guide_wicket-viewer_customisation.adoc[leveloffset=+1]
-
-
-
-== Extending the viewer
-
-APIs to extend the Wicket viewer are discussed in the <<_extending_the_wicket_viewer, Extending>> chapter.
-
-
-include::_user-guide_wicket-viewer_isis-addons.adoc[leveloffset=+1]
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_configuration_properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_configuration_properties.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_configuration_properties.adoc
deleted file mode 100644
index 420a0fc..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_configuration_properties.adoc
+++ /dev/null
@@ -1,276 +0,0 @@
-= 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 <<_abbreviating_suppressing_titles_in_tables, below>>.
-
-|`isis.viewer.wicket.` +
-`maxTitleLengthInStandaloneTables`
-| +ve integer, (`_12_`)
-| See discussion <<_abbreviating_suppressing_titles_in_tables, below>>.
-
-|`isis.viewer.wicket.` +
-`maxTitleLengthInTables`
-| +ve integer, (`_12_`)
-| See discussion <<_abbreviating_suppressing_titles_in_tables, 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 <<_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 <<_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 <<_suppressing_sign_up, below>>.
-
-|`isis.viewer.wicket.` +
-`themes.enabled`
-| comma separated list ...
-| ... of bootswatch themes. Only applies if `themes.showChooser`==`true`. See discussion <<_showing_a_theme_chooser, below>>.
-
-|`isis.viewer.wicket.` +
-`themes.showChooser`
-| `true`,`false` (`_false_`)
-| Whether to show chooser for Bootstrap themes. See discussion <<_showing_a_theme_chooser, below>>
-
-|===
-
-
-
-== Abbreviating/suppressing titles in tables
-
-Objects whose title is overly long can be cumbersome in titles. The Wicket viewer has a <<_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`.
-
-
-
-
-== Suppressing 'remember me'
-
-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
-----
-
-
-
-== Suppressing 'sign up'
-
-If <<_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 <<_suppressing_password_reset, password reset link>> can be suppressed in a similar manner.
-
-
-
-== Suppressing 'password reset'
-
-If <<_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 <<_suppressing_sign-up, sign up link>> can be suppressed in a similar manner.
-
-
-
-
-== Stripped Wicket tags
-
-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.
-====
-
-
-
-== Showing a theme chooser
-
-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 <<_specifying_a_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 <<_custom_bootstrap_theme, Extending>> chapter for further details.
-====
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_customisation.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_customisation.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_customisation.adoc
deleted file mode 100644
index ed3d089..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_wicket-viewer_customisation.adoc
+++ /dev/null
@@ -1,458 +0,0 @@
-= 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/
-
-
-== Brand logo
-
-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 `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;
-}
-----
-
-
-
-
-== Specifying a default theme
-
-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 <<_custom_bootstrap_theme, here>>) then this can also be specified using the https://github.com/l0rdn1kk0n/wicket-bootstrap/wiki/Themes[Wicket Bootstrap API].
-
-
-
-
-
-== Welcome page
-
-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`.
-
-
-
-
-== About page
-
-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]
-====
-TODO: this screenshot need to be updated for the new look-n-feel introduced in 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 <<_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!
-
-
-
-
-== Tweaking CSS classes
-
-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 `src/main/webapp/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 `src/main/webapp/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 <<_dynamic_layouts, dynamic layout>> JSON file:
-
-[source,javascript]
-----
-"dueBy": {
- "propertyLayout": {
- "cssClass": "x-myapp-important"
- }
-},
-----
-
-
-
-== Cheap-n-cheerful "theme"
-
-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 <<_custom_bootstrap_theme, own Bootstrap theme>>, as described in the <<Extending>> chapter.
-====
-
-
-
-== Using a different CSS file
-
-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]
-----
-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`.
-
-
-
-== Custom Javascript
-
-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 <<_extending_the_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.
-
-
-
-
-== Auto-refresh page
-
-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
- }
-});
-----
[03/22] isis git commit: ISIS-1133: renamed _user-guide_ to _ug_
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_security_shiro-isis-ldap-realm.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_security_shiro-isis-ldap-realm.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_security_shiro-isis-ldap-realm.adoc
deleted file mode 100644
index 59c0192..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_security_shiro-isis-ldap-realm.adoc
+++ /dev/null
@@ -1,145 +0,0 @@
-= 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.
-====
-
-
-
-
-
-
-== Using a shared role/perms path
-
-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 Mini-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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_security_shiro-isisaddons-security-module-realm.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_security_shiro-isisaddons-security-module-realm.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_security_shiro-isisaddons-security-module-realm.adoc
deleted file mode 100644
index 7f99cb0..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_security_shiro-isisaddons-security-module-realm.adoc
+++ /dev/null
@@ -1,35 +0,0 @@
-= 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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_security_shiro-jdbc-realm.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_security_shiro-jdbc-realm.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_security_shiro-jdbc-realm.adoc
deleted file mode 100644
index c90957d..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_security_shiro-jdbc-realm.adoc
+++ /dev/null
@@ -1,114 +0,0 @@
-= 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"]
-
-
-
-
-== Shiro Configuration
-
-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/a/23784702/56880[this StackOverflow answer].
-====
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_security_usage-by-isis-viewers.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_security_usage-by-isis-viewers.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_security_usage-by-isis-viewers.adoc
deleted file mode 100644
index 667adde..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_security_usage-by-isis-viewers.adoc
+++ /dev/null
@@ -1,207 +0,0 @@
-= 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 <<_wicket_viewer, Wicket Viewer>> and <<_restful_objects_viewer, Restful viewer>>, and the overall <<_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 <<_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 <<_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 <<_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 <<_custom_pages, extensions chapter>> for details.
-====
-
-User registration is only available if the <<_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 <<_restful_objects_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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing.adoc
deleted file mode 100644
index 7acc994..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing.adoc
+++ /dev/null
@@ -1,16 +0,0 @@
-= 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::_user-guide_testing_overview.adoc[leveloffset=+1]
-include::_user-guide_testing_unit-test-support.adoc[leveloffset=+1]
-include::_user-guide_testing_integ-test-support.adoc[leveloffset=+1]
-include::_user-guide_testing_bdd-spec-support.adoc[leveloffset=+1]
-include::_user-guide_testing_fixture-scripts.adoc[leveloffset=+1]
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_bdd-spec-support.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_bdd-spec-support.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_bdd-spec-support.adoc
deleted file mode 100644
index 68569c1..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_bdd-spec-support.adoc
+++ /dev/null
@@ -1,21 +0,0 @@
-= 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::_user-guide_testing_bdd-spec-support_how-it-works.adoc[leveloffset=+1]
-include::_user-guide_testing_bdd-spec-support_key-classes.adoc[leveloffset=+1]
-include::_user-guide_testing_bdd-spec-support_writing-a-bdd-spec.adoc[leveloffset=+1]
-include::_user-guide_testing_bdd-spec-support_bdd-tooling.adoc[leveloffset=+1]
-include::_user-guide_testing_bdd-spec-support_maven-configuration.adoc[leveloffset=+1]
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_bdd-spec-support_bdd-tooling.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_bdd-spec-support_bdd-tooling.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_bdd-spec-support_bdd-tooling.adoc
deleted file mode 100644
index ede2b2a..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_bdd-spec-support_bdd-tooling.adoc
+++ /dev/null
@@ -1,13 +0,0 @@
-= 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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_bdd-spec-support_how-it-works.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_bdd-spec-support_how-it-works.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_bdd-spec-support_how-it-works.adoc
deleted file mode 100644
index 27d0e49..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_bdd-spec-support_how-it-works.adoc
+++ /dev/null
@@ -1,19 +0,0 @@
-= 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 http://cukes.info/step-definitions.html[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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_bdd-spec-support_key-classes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_bdd-spec-support_key-classes.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_bdd-spec-support_key-classes.adoc
deleted file mode 100644
index 9244f6e..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_bdd-spec-support_key-classes.adoc
+++ /dev/null
@@ -1,58 +0,0 @@
-= 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' <<_integration_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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_bdd-spec-support_maven-configuration.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_bdd-spec-support_maven-configuration.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_bdd-spec-support_maven-configuration.adoc
deleted file mode 100644
index 88bbc7f..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_bdd-spec-support_maven-configuration.adoc
+++ /dev/null
@@ -1,72 +0,0 @@
-= 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 <<_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]
-----
-<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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_bdd-spec-support_writing-a-bdd-spec.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_bdd-spec-support_writing-a-bdd-spec.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_bdd-spec-support_writing-a-bdd-spec.adoc
deleted file mode 100644
index 5cdc050..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_bdd-spec-support_writing-a-bdd-spec.adoc
+++ /dev/null
@@ -1,140 +0,0 @@
-= 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 <<_integration_test_support, Integration Test Support>>, bootstrapping section).
-
-
-Here's an example of a feature from the <<_simpleapp_archetype, SimpleApp archetype>>:
-
-[source]
-----
-@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 <<_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 <<_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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_fixture-scripts.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_fixture-scripts.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_fixture-scripts.adoc
deleted file mode 100644
index adba36a..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_fixture-scripts.adoc
+++ /dev/null
@@ -1,43 +0,0 @@
-= 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::_user-guide_testing_fixture-scripts_api-and-usage.adoc[leveloffset=+1]
-include::_user-guide_testing_fixture-scripts_sudo-service.adoc[leveloffset=+1]
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_fixture-scripts_api-and-usage.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_fixture-scripts_api-and-usage.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_fixture-scripts_api-and-usage.adoc
deleted file mode 100644
index b2d1ba2..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_fixture-scripts_api-and-usage.adoc
+++ /dev/null
@@ -1,285 +0,0 @@
-= 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 <<_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 <<_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 <<_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 <<_wrapper_factory, `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 <<_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 <<_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 <<_fixturescripts, `FixtureScripts`>> 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 <<_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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_fixture-scripts_sudo-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_fixture-scripts_sudo-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_fixture-scripts_sudo-service.adoc
deleted file mode 100644
index dea52eb..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_fixture-scripts_sudo-service.adoc
+++ /dev/null
@@ -1,58 +0,0 @@
-= SudoService (1.9.0-SNAPSHOT)
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-
-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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_integ-test-support.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_integ-test-support.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_integ-test-support.adoc
deleted file mode 100644
index f4d4cab..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_integ-test-support.adoc
+++ /dev/null
@@ -1,23 +0,0 @@
-= 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::_user-guide_testing_integ-test-support_typical-usage.adoc[leveloffset=+1]
-include::_user-guide_testing_integ-test-support_bootstrapping.adoc[leveloffset=+1]
-include::_user-guide_testing_integ-test-support_wrapper-factory.adoc[leveloffset=+1]
-include::_user-guide_testing_integ-test-support_maven-configuration.adoc[leveloffset=+1]
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_integ-test-support_bootstrapping.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_integ-test-support_bootstrapping.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_integ-test-support_bootstrapping.adoc
deleted file mode 100644
index c987e58..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_testing_integ-test-support_bootstrapping.adoc
+++ /dev/null
@@ -1,230 +0,0 @@
-= 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 <<_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 <<_isisconfigurationforjdointegtests, 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 <<_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 <<_i18n_support, 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
-
[16/22] isis git commit: ISIS-1133: renamed _user-guide_ to _ug_
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..b5b1522
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_tips-n-tricks_are-you-sure.adoc
@@ -0,0 +1,47 @@
+= '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[]
+
+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));
+
+ // invalid to return 'this' (cannot render a deleted object)
+ return toDoItems.notYetComplete();
+}
+public String validateDelete(boolean areYouSure) {
+ return areYouSure? null: "Please confirm you are sure";
+}
+----
+
+Note that the action itself does not use the boolean parameter, it is only
+used by the supporting `validateXxx()` method.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..a490b68
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_tips-n-tricks_enhance-only.adoc
@@ -0,0 +1,18 @@
+= 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/
+
+IMPORTANT: TODO
+
+
+== Question:
+
+Is there a simple way to make a run configuration in IntelliJ for running the datanucleus enhancer before running integration test?
+
+== Answer:
+
+* 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/97531ca0/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
new file mode 100644
index 0000000..a8ee6b0
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_tips-n-tricks_per-user-themes.adoc
@@ -0,0 +1,85 @@
+= 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/
+
+== Question:
+
+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?
+
+== Answer:
+
+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/blob/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/97531ca0/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
new file mode 100644
index 0000000..04976fd
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_tips-n-tricks_render-all-properties-in-tables.adoc
@@ -0,0 +1,51 @@
+= Render all 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() {
+ // workaround for ISIS-582
+ return null;
+ }
+ ...
+}
+----
+
+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/97531ca0/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
new file mode 100644
index 0000000..d0fa519
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_tips-n-tricks_simulating-collections-of-values.adoc
@@ -0,0 +1,20 @@
+= Simulating 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/
+
+
+IMPORTANT: TODO
+
+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
+
+
+== Persistence Concerns
+
+* easiest to simply store using DataNucleus' support for collections, marked as @Ignore. 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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_tips-n-tricks_suppress-actions-from-the-ui.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_tips-n-tricks_suppress-actions-from-the-ui.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_tips-n-tricks_suppress-actions-from-the-ui.adoc
new file mode 100644
index 0000000..d074e71
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_tips-n-tricks_suppress-actions-from-the-ui.adoc
@@ -0,0 +1,13 @@
+= Suppressing actions from the UI
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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
+
+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/97531ca0/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
new file mode 100644
index 0000000..d666d0a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_transactions-and-errors.adoc
@@ -0,0 +1,26 @@
+= 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 <<_isis_jdo_support, 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
+
+
+
+== Exception Recognizers
+
+IMPORTANT: TODO
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..2d23d59
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced_view-models.adoc
@@ -0,0 +1,10 @@
+= 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: TODO
+
+== `@ViewModel`
+
+== `ViewModel` interface
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference.adoc
new file mode 100644
index 0000000..62324ed
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference.adoc
@@ -0,0 +1,25 @@
+= Reference
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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
+
+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.
+
+Some of the services defined in the applib are intended to be used (primarily) not by your domain objects but instead by Isis itself. A good example of this is the <<__code_auditingservice3_code, `AuditingService3`>> 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 `EmailService` that is of direct use for domain objects wishing to send out emails, but is also used by the framework to support the user registration functionality supported by the <<_wicket_viewer, Wicket viewer>>. The same is true of the <<__code_eventbusservice_code, `EventBusService`>>; this can be used by domain objects to broadcast arbitrary events, but is also used by the framework to automatically emit events eg for `@Action(domainEvent=...)`. For these hybrid services we we have categorized the service as an "API" service.
+
+
+include::_user-guide_reference_annotations.adoc[leveloffset=+1]
+include::_user-guide_reference_prefixes.adoc[leveloffset=+1]
+include::_user-guide_reference_methods.adoc[leveloffset=+1]
+include::_user-guide_reference_services-api.adoc[leveloffset=+1]
+include::_user-guide_reference_services-spi.adoc[leveloffset=+1]
+include::_user-guide_reference_superclasses.adoc[leveloffset=+1]
+include::_user-guide_reference_value-types.adoc[leveloffset=+1]
+include::_user-guide_reference_applib-utility-classes.adoc[leveloffset=+1]
+include::_user-guide_reference_mixins.adoc[leveloffset=+1]
+include::_user-guide_reference_addons.adoc[leveloffset=+1]
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_addons.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_addons.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_addons.adoc
new file mode 100644
index 0000000..caa04de
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_addons.adoc
@@ -0,0 +1,17 @@
+= Isis Addons
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 highlights a number of the addons available at http://isisaddons.org[Isis Addons] website. Note that it is _not_ intended to be comprehensive.
+
+[NOTE]
+====
+The http://isisaddons.org[Isis Addons], while maintained by Isis committers, are entirely independent of the Apache Software Foundation.
+====
+
+
+include::_user-guide_reference_addons_settings-module.adoc[leveloffset=+1]
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_addons_settings-module.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_addons_settings-module.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_addons_settings-module.adoc
new file mode 100644
index 0000000..8355192
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_addons_settings-module.adoc
@@ -0,0 +1,49 @@
+= Settings 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/
+
+
+The http://github.com/isisaddons/isis-module-settings}[Isis addons' settings] module provides a simple way to store both global (application-level) settings as well as per-user settings.
+
+The settings service is documented here for your convenience; the full README can be found on the http://github.com/isisaddons/isis-module-settings}[github site].
+
+
+== Application Settings
+
+=== API
+
+IMPORTANT: TODO
+
+=== Implementation
+
+In the case of `ApplicationSettingsService`, the service is implemented by `ApplicationSettingsServiceJdo`, with the `ApplicationSetting` interface implemented by a `ApplicationSettingsJdo` entity.
+
+The service also provides the ability to create list all existing settings, create new settings (of whichever datatype), update settings, and to delete settings.
+
+These actions can be hidden using security if need be.
+
+== User Settings
+
+=== API
+
+IMPORTANT: TODO
+
+=== Implementation
+
+In the case of `UserSettingsService`, the service is implemented by `UserSettingsServiceJdo`, with the `UserSetting` interface implemented by a `UserSettingsJdo` entity.
+
+As for application settings, the user settings service also provides the ability to create list all existing settings, create new settings (of whichever datatype), update settings, and to delete settings.
+
+These actions can be hidden using security if need be.
+
+
+== Registration and Configuration
+
+The `ApplicationSettingsServiceJdo` class and `UserSettingsServiceJdo` are annotated with `@DomainService` and so are automatically registered with the framework, with actions appearing on the secondary menu bar.
+
+IMPORTANT: TODO - screenshot of settings menu
+
+All actions from the services emit domain events. If you wish to hide/disable these default actions in your application, we recommend using up a subscriber on the actions' domain events to veto their visibility/usability.
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..d8f34bc
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_annotations.adoc
@@ -0,0 +1,39 @@
+= 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/
+
+IMPORTANT: TODO
+
+
+include::_user-guide_reference_annotations_aaa.adoc[leveloffset=+1]
+
+include::_user-guide_reference_annotations_manpage_action.adoc[leveloffset=+1]
+include::_user-guide_reference_annotations_manpage_actionlayout.adoc[leveloffset=+1]
+include::_user-guide_reference_annotations_manpage_collection.adoc[leveloffset=+1]
+include::_user-guide_reference_annotations_manpage_collectionlayout.adoc[leveloffset=+1]
+include::_user-guide_reference_annotations_manpage_domainobject.adoc[leveloffset=+1]
+include::_user-guide_reference_annotations_manpage_domainobjectlayout.adoc[leveloffset=+1]
+include::_user-guide_reference_annotations_manpage_domainservice.adoc[leveloffset=+1]
+include::_user-guide_reference_annotations_manpage_domainservicelayout.adoc[leveloffset=+1]
+include::_user-guide_reference_annotations_manpage_parameter.adoc[leveloffset=+1]
+include::_user-guide_reference_annotations_manpage_property.adoc[leveloffset=+1]
+include::_user-guide_reference_annotations_manpage_propertylayout.adoc[leveloffset=+1]
+include::_user-guide_reference_annotations_manpage_viewmodel.adoc[leveloffset=+1]
+include::_user-guide_reference_annotations_manpage_viewmodellayout.adoc[leveloffset=+1]
+
+
+include::_user-guide_reference_annotations_manpage_facets.adoc[leveloffset=+1]
+include::_user-guide_reference_annotations_manpage_homepage.adoc[leveloffset=+1]
+include::_user-guide_reference_annotations_manpage_membergrouplayout.adoc[leveloffset=+1]
+include::_user-guide_reference_annotations_manpage_memberorder.adoc[leveloffset=+1]
+include::_user-guide_reference_annotations_manpage_programmatic.adoc[leveloffset=+1]
+include::_user-guide_reference_annotations_manpage_minlength.adoc[leveloffset=+1]
+include::_user-guide_reference_annotations_manpage_title.adoc[leveloffset=+1]
+
+
+include::_user-guide_reference_annotations_manpage_requestscoped.adoc[leveloffset=+1]
+include::_user-guide_reference_annotations_manpage_inject.adoc[leveloffset=+1]
+include::_user-guide_reference_annotations_manpage_digits.adoc[leveloffset=+1]
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..c8ef404
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_annotations_aaa.adoc
@@ -0,0 +1,14 @@
+= 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/
+
+
+
+include::_user-guide_reference_annotations_aaa_main.adoc[leveloffset=+1]
+include::_user-guide_reference_annotations_aaa_other.adoc[leveloffset=+1]
+include::_user-guide_reference_annotations_aaa_jee.adoc[leveloffset=+1]
+include::_user-guide_reference_annotations_aaa_deprecated.adoc[leveloffset=+1]
+include::_user-guide_reference_annotations_aaa_partial.adoc[leveloffset=+1]
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..15f22d6
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_annotations_aaa_deprecated.adoc
@@ -0,0 +1,328 @@
+= 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/
+
+
+
+
+.Deprecated Annotations
+[cols="2,4a,3a,1,1", options="header"]
+|===
+|Annotation
+|Purpose
+|Use instead
+|Layer
+|`.layout +
+.json`?
+
+|`@ActionOrder`
+|Order of buttons and menu items representing actions.
+|`@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.
+|`@Action#domainEvent()`
+|Domain
+|
+
+|`@ActionSemantics`
+|Query-only, idempotent or non-idempotent.
+|`@Action#semantics()`
+|Domain
+|
+
+|`@Audited`
+|Audit changes to an object.
+|`@DomainObject#` +
+`auditing()`
+|Domain
+|
+
+|`@AutoComplete`
+|Repository method to search for entities
+|`@DomainObject` +
+`#autoCompleteRepository()`
+|UI/Domain
+|
+
+|`@Bookmarkable`
+|Whether (and how) to create a bookmark for visited object.
+|`@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.
+|`@DomainObject#bounded()`
+|Domain
+|
+
+|`@Bulk`
+|Indicates an action is a bulk action, can be applied to multiple instances.
+|`@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.
+|`@Collection#domainEvent()`
+|Domain
+|
+
+|`@Command`
+|Action invocation should be reified as a command object, optionally persistable for profiling and enhanced auditing, and background/async support.
+|`@Action#command()`
+|Domain
+|
+
+|`@CssClass`
+|Allow visual representation of individual objects or object members layout to be customized by application-specific CSS.
+|`#cssClass()` attribute for: `@DomainObjectLayout`, `@PropertyLayout`, `@CollectionLayout`, `@ActionLayout` and `@ParameterLayout`
+|UI
+|Yes
+
+|`@CssClassFa`
+|So that font awesome icons can be applied to action buttons/menu items and optionally as an object icon.
+|`@ActionLayout#cssClassFa()`
+|UI
+|Yes
+
+|`@Debug`
+|Action only invokable in debug mode.
+|Use prototype mode instead (`@Action#restrictTo()`)
+|UI
+|
+
+|`@DescribedAs`
+|Provide a longer description/tool-tip of an object or object member.
+|`#describedAs()` attribute for `@DomainObjectLayout`, `@PropertyLayout`, `@CollectionLayout`, `@ActionLayout` and `@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 `@Property` and `@Collection#editing()`; see also `@DomainObject`
+|UI, Domain
+|Yes
+
+|`@Exploration`
+|Action available in special 'exploration' mode.
+|`@Action#restrictTo()` (combines exploration and prototyping modes).
+|UI
+|
+
+|`@FieldOrder`
+|Order of properties and collections.
+|`@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 `@Action#hidden()`, `@Property#hidden()` or `@Collection#hidden()`. +
+For domain service, use `@DomainService(nature=DOMAIN)`
+|UI, Domain
+|Yes
+
+|`@Idempotent`
+|Whether an action is idempotent (can be invoked multiple times with same post-condition).
+|`@Action#semantics`
+|Domain
+|
+
+|`@Ignore`
+|Exclude this method from the metamodel.
+|`@Programmatic`
+|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.
+|`@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 `@Property` or `@Parameter`
+|Domain
+|
+
+|`@MemberGroups`
+|Layout of properties and collections of a domain object or view model object.
+|`@MemberGroupLayout` or dynamic layout.
+|UI
+|Yes
+
+|`@MultiLine`
+|Render string property over multiple lines (a textarea rather than a textbox).
+|`#multiLine()` attribute for `@PropertyLayout` and`@ParameterLayout`
+|UI
+|Yes
+
+|`@MustSatisfy`
+|Specify arbitrary specification constraints on a property or action parameter.
+|`#mustSatisfy()` attribute for `@Property` and `@Parameter`
+|Domain
+|
+
+|`@Named`
+|Override name inferred from class. Required for parameter names (prior to Java8).
+|`#named()` attribute for `@DomainServiceLayout`, `@DomainObjectLayout`, `@PropertyLayout`, `@CollectionLayout`, `@ActionLayout` and `@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 `@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 `@ActionLayout` 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).
+|`@DomainService#nature()` to specify 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).
+|`@Property#notPersisted()`
+|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
+|`@DomainObject#objectType()`
+|Domain
+|
+
+|`@Optional`
+|Specifies that a property or action parameter is not mandatory.
+|`#optionality()` attribute for `@Property` or `@Parameter`
+|Domain
+|
+
+|`@Paged`
+|Number of instances to display in tables representing (standalone or parented) collections.
+|`#paged()` attribute for `@DomainObjectLayout` or `@CollectionLayout`
+|UI
+|Yes
+
+|`@Plural`
+|For the irregular plural form of an entity type.
+|`@DomainObjectLayout#plural()`
+|UI
+|
+
+|`@PostsAction` +
+`InvokedEvent`
+|Post a domain event to the Event Bus Service indicating that an action has been invoked.
+|`@Action#domainEvent()`
+|Domain
+|
+
+|`@PostsCollection` +
+`AddedToEvent`
+|Post a domain event to the Event Bus Service indicating that an element has been added to a collection.
+|`@Collection#domainEvent()`
+|Domain
+|
+
+|`@PostsCollection` +
+`RemovedFromEvent`
+|Post a domain event to the Event Bus Service indicating that an element has been removed from a collection.
+|`@Collection#domainEvent()`
+|Domain
+|
+
+|`@PostsProperty` +
+`ChangedEvent`
+|Post a domain event to the Event Bus Service indicating that the value of a property has changed.
+|`@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.
+|`@Property#domainEvent()`
+|Domain
+|
+
+|`@Prototype`
+|Indicates that an action should only be visible in 'prototype' mode.
+|`@Action#restrictTo()`
+|UI
+|Yes
+
+|`@PublishedAction`
+|Action invocation should be serialized and published by configured PublishingService (if any), eg to other systems.|`@Action#publishing()`
+|Domain
+|
+
+|`@PublishedObject`
+|Change to object should be serialized and published by configured PublishingService (if any), eg to other systems.
+|`@DomainObject#publishing()`
+|Domain
+|
+
+|`@QueryOnly`
+|Whether an action is query-only (has no side-effects).
+|`@Action#semantics()`
+|Domain
+|
+
+|`@RegEx`
+|Validate change to value of string property.
+|`#regexPattern()` for `@Property` or `@Parameter`.
+|Domain
+|
+
+|`@Render`
+|Eagerly (or lazily) render the contents of a collection.
+|`@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 `@PropertyLayout` and `@ParameterLayout`.
+|UI
+|
+
+|`@Resolve`
+|Eagerly (or lazily) render the contents of a collection (same as `@Render)`
+|`@CollectionLayout#render()`
+|UI
+|Yes
+
+|`@SortedBy`
+|Display instances in collections in the order determined by the provided Comparator.
+|`@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 `@Collection` and `@Action`
+|Domain
+|
+
+|`@TypicalLength`
+|The typical length of a string property, eg to determine a sensible length for a textbox.
+|`#typicalLength()` attribute for `@PropertyLayout` and `@ParameterLayout`
+|UI
+|Yes
+
+|===
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..75015ff
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_annotations_aaa_jee.adoc
@@ -0,0 +1,35 @@
+= 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/
+
+
+
+.Java EE Annotations
+[cols="2,4a,1,1", options="header"]
+|===
+|Annotation
+|Purpose
+|Layer
+|`.layout +
+.json`?
+
+|<<__code_requestscoped_code_javax, `@javax.enterprise.context.RequestScoped`>>
+|Specify that a domain service has request-scope (rather than a singleton).
+|Domain
+|
+
+|<<__code_inject_code_javax, `@javax.inject.Inject`>>
+|Inject domain service into a domain object (entity or view model) or another domain service.
+|Domain
+|
+
+|<<__code_digits_code_javax, `@javax.validation.constraints.Digits`>>
+|Precision/scale for BigDecimal values.
+|Domain
+|
+
+|===
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..cc44f08
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_annotations_aaa_main.adoc
@@ -0,0 +1,91 @@
+= 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/
+
+
+
+.Core annotations for domain objects, services and members (as of 1.8.0)
+[cols="2,4a,1,1", options="header"]
+|===
+|Annotation
+|Purpose
+|Layer
+|`.layout +
+.json`?
+
+|<<__code_action_code, `@Action`>>
+|Domain semantics for actions
+|Domain
+|
+
+|<<__code_actionlayout_code, `@ActionLayout`>>
+|User interface hints for actions
+|UI
+|Yes
+
+|<<__code_collection_code, `@Collection`>>
+|Domain semantics for collections
+|Domain
+|
+
+|<<__code_collectionlayout_code, `@CollectionLayout`>>
+|User interface hints for collections
+|UI
+|Yes
+
+|<<__code_domainobject_code, `@DomainObject`>>
+|Domain semantics for domain object (entities and optionally view models, see also `@ViewModel)`
+|Domain
+|
+
+|<<__code_domainobjectlayout_code, `@DomainObjectLayout`>>
+|User interface hints for domain object (entities and optionally view models, see also `@ViewModelLayout)`
+|UI
+|Yes
+
+|<<__code_domainservice_code, `@DomainService`>>
+|Class is a domain service (rather than an entity or view model)
+|Domain
+|
+
+|<<__code_domainservicelayout_code, `@DomainServiceLayout`>>
+|User interface hints for domain services
+|UI
+|
+
+|<<__code_parameter_code, `@Parameter`>>
+|Domain semantics for action parameters
+|Domain
+|
+
+|<<__code_propertylayout_code, `@PropertyLayout`>>
+|Layout hints for an action parameter (currently: its label position either to top or the left).
+|UI
+|Yes
+
+|<<__code_property_code, `@Property`>>
+|Domain semantics for properties
+|Domain
+|
+
+|<<__code_propertylayout_code, `@PropertyLayout`>>
+|Layout hints for a property
+|UI
+|Yes
+
+|<<__code_viewmodel_code, `@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
+|
+
+|<<__code_ViewModelLayout_code, `@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/97531ca0/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
new file mode 100644
index 0000000..b71247b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_annotations_aaa_other.adoc
@@ -0,0 +1,55 @@
+= 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/
+
+
+
+.Other Isis Annotations
+[cols="2,4a,1,1", options="header"]
+|===
+|Annotation
+|Purpose
+|Layer
+|`.layout +
+.json`?
+
+|<<__code_facets_code, `@Facets`>>
+|Install arbitrary facets within the Isis metamodel.
+|(any)
+|
+
+|<<__code_homepage_code, `@HomePage`>>
+|Query-only action (on domain service) to be invoked, result of which is rendered as the user's home page.
+|UI
+|
+
+|<<__code_membergrouplayout_code, `@MemberGroupLayout`>>
+|Grouping of properties into groups, and organizing of properties, collections into columns.
+|UI
+|Yes
+
+
+|<<__code_memberorder_code, `@MemberOrder`>>
+|Ordering of properties, collections and actions, and also associating actions with either a property or a collection.
+|UI
+|Yes
+
+
+|<<__code_programmatic_code, `@Programmatic`>>
+|Ignore a public method, excluded from the Isis metamodel.
+|Domain
+|
+
+|<<__code_minlength_code, `@MinLength`>>
+|Minimum number of characters required for an auto-complete search argument.
+|UI
+|
+
+|<<__code_title_code, `@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/97531ca0/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
new file mode 100644
index 0000000..cbc33ad
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_annotations_aaa_partial.adoc
@@ -0,0 +1,43 @@
+= 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/
+
+
+
+.Annotations with incomplete/partial support
+[cols="2,4a,1", options="header"]
+|===
+|Annotation
+|Purpose
+|Layer
+
+|`@Aggregated`
+|Part of an aggregate root
+|Domain, Persistence
+
+|`@Defaulted`
+|Indicates that a (value) class has a default value.
+|Domain
+
+|`@Encodable`
+|Indicates that a (value) class can be serialized/encoded.
+|Persistence
+
+|`@EqualByContent`
+|Indicates that a value class has equality semantics.
+|Domain
+
+|`@NotPersistable`
+|Indicates that a domain object may not be programmatically persisted (partly supported).
+|Domain, Persistence
+
+|`@Parseable`
+|Indicates that a (value) class can be reconstructed from a string.
+|UI, Domain
+
+|`@Value`
+|Specify that a class has value-semantics.
+|Domain
+
+|===
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..a12816b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_annotations_manpage_action.adoc
@@ -0,0 +1,8 @@
+= `@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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..12e0e63
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_annotations_manpage_actionlayout.adoc
@@ -0,0 +1,8 @@
+= `@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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..7d4e2c2
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_annotations_manpage_collection.adoc
@@ -0,0 +1,8 @@
+= `@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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..37b1f55
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_annotations_manpage_collectionlayout.adoc
@@ -0,0 +1,8 @@
+= `@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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..57fac81
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_annotations_manpage_digits.adoc
@@ -0,0 +1,8 @@
+= `@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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..33bc0f1
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_annotations_manpage_domainobject.adoc
@@ -0,0 +1,8 @@
+= `@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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..87bf7a0
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_annotations_manpage_domainobjectlayout.adoc
@@ -0,0 +1,8 @@
+= `@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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..b9c58dc
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_annotations_manpage_domainservice.adoc
@@ -0,0 +1,8 @@
+= `@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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..fd9e2b4
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_annotations_manpage_domainservicelayout.adoc
@@ -0,0 +1,8 @@
+= `@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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..0cf9a83
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_annotations_manpage_facets.adoc
@@ -0,0 +1,8 @@
+= `@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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..bb836b2
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_annotations_manpage_homepage.adoc
@@ -0,0 +1,8 @@
+= `@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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..887ca24
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_annotations_manpage_inject.adoc
@@ -0,0 +1,8 @@
+= `@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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..c452aa9
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_annotations_manpage_membergrouplayout.adoc
@@ -0,0 +1,8 @@
+= `@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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..c452aa9
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_annotations_manpage_memberorder.adoc
@@ -0,0 +1,8 @@
+= `@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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..4ae8092
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_annotations_manpage_minlength.adoc
@@ -0,0 +1,8 @@
+= `@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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..6bcf579
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_annotations_manpage_parameter.adoc
@@ -0,0 +1,8 @@
+= `@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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..6872f5c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_annotations_manpage_programmatic.adoc
@@ -0,0 +1,8 @@
+= `@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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..6d800fe
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_annotations_manpage_property.adoc
@@ -0,0 +1,8 @@
+= `@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
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..bb22a8d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_annotations_manpage_propertylayout.adoc
@@ -0,0 +1,8 @@
+= `@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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..5f59691
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_annotations_manpage_requestscoped.adoc
@@ -0,0 +1,8 @@
+= `@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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..df89289
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_annotations_manpage_title.adoc
@@ -0,0 +1,8 @@
+= `@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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..606ea84
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_annotations_manpage_viewmodel.adoc
@@ -0,0 +1,8 @@
+= `@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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..95bc856
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_annotations_manpage_viewmodellayout.adoc
@@ -0,0 +1,8 @@
+= `@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/
+
+IMPORTANT: TODO
+
+
[14/22] isis git commit: ISIS-1133: renamed _user-guide_ to _ug_
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_aaa.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_aaa.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_aaa.adoc
new file mode 100644
index 0000000..fa3baef
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_aaa.adoc
@@ -0,0 +1,214 @@
+= 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/
+
+
+
+IMPORTANT: TODO
+
+== Applib SPIs
+
+IMPORTANT: TODO
+
+.Domain Services
+[cols="2,4a,1,1", options="header"]
+|===
+
+|API
+|Maven Module +
+Impl'n (g: a:)
+|Implementation
+|Notes
+
+|<<__code_auditingservice3_code, `o.a.i.applib.` +
+`services.audit` +
+`AuditingService3`>>
+|``o.ia.m.audit`` +
+``isis-module-audit``
+|`AuditingService`
+|related services:
+`AuditingService-` +
+`Contributions`,
+`AuditingService-` +
+`Repository`
+
+|<<__code_backgroundcommandservice_code, `o.a.i.applib.` +
+`services.background` +
+`BackgroundCommandService`>>
+|``o.ia.m.command`` +
+``isis-module-command``
+|`BackgroundCommandServiceJdo`
+|related services:
+`BackgroundCommandService-` +
+`JdoContributions`,
+`BackgroundCommandService-` +
+`JdoRepository`
+
+|<<__code_classdiscoveryservice_code, `o.a.i.applib.` +
+`services.classdiscovery` +
+`ClassDiscoveryService`>>
+|``o.a.i.core`` +
+``isis-core-applib``
+|`ClassDiscoveryService-` +
+`UsingReflections`
+|requires `org.reflections:reflections` as Maven dependency
+
+|<<__code_commandservice_code, `o.a.i.applib.` +
+`services.command.spi` +
+`CommandService`>>
+|``o.ia.m.command`` +
+``isis-module-command``
+|`CommandServiceJdo`
+|related services: +
+`CommandService-` ++
+`JdoContributions`,
+`CommandService-` ++
+`JdoRepository`
+
+|<<__code_emailnotificationservice_code, `o.a.i.applib.` +
+`services.userreg` +
+`EmailNotificationService`>>
+|``o.a.i.core`` +
+``isis-core-runtime``
+|`EmailNotificationService-` ++
+`Default`
+|depends on: +
+a configured `EmailService`
+
+|<<__code_eventserializer_code, `o.a.i.applib.` +
+`services.publish` +
+`EventSerializer`>>
+|``o.ia.m.publishing`` +
+``isis-module-publishing``
+|`RestfulObjects-` +
+`SpecEventSerializer`
+|
+
+|<<__code_exceptionrecognizer_code, `o.a.i.applib.` +
+`services.exceprecog` +
+`ExceptionRecognizer`>>
+|``o.a.i.core`` +
+``isis-core-applib``
+|`ExceptionRecognizer-` +
+`CompositeFor-` +
+`JdoObjectStore`
+|Extensible using composite pattern if required
+
+|<<__code_localeprovider_code, `o.a.i.applib.` +
+`services.i18n` +
+`LocaleProvider`>>
+|``o.a.i.viewer`` +
+``isis-viewer-wicket-impl``
+|`LocaleProviderWicket`
+|
+
+|<<__code_publishingservice_code, `o.a.i.applib.` +
+`services.publish` +
+`PublishingService`>>
+|``o.ia.m.publishing`` +
+``isis-module-publishing``
+|`PublishingService`
+|related services:
+`PublishingService-` ++
+`Contributions`,
+`PublishingService-` ++
+`Repository`. +
+depends on: +
+`EventSerializer`
+
+|<<__code_translationservice_code, `o.a.i.applib.` +
+`services.i18n` +
+`TranslationService`>>
+|``o.a.i.core`` +
+``isis-core-runtime``
+|`TranslationServicePo`
+|related services: `TranslationServicePoMenu` +
+depends on: +
+`TranslationsResolver`, `LocaleProvider`
+
+|<<__code_translationsresolver_code, `o.a.i.applib.` +
+`services.i18n` +
+`TranslationsResolver`>>
+|``o.a.i.viewer`` +
+``isis-viewer-wicket-impl``
+|`TranslationsResolverWicket`
+|
+
+|<<__code_userprofileservice_code, `o.a.i.applib.` +
+`services.userprof` +
+`UserProfileService`>>
+|
+|
+|SPI only
+
+|<<__code_userregistrationservice_code, `o.a.i.applib.` +
+`services.userreg` +
+`UserRegistrationService`>>
+|``o.ia.m.security`` +
+``isis-module-security``
+|`SecurityModule-` +
+`AppUserRegistrationService`
+|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`
+
+
+All domain services are automatically registered (annotated with <<__code_domainservice_code, `@DomainService`>>) except:
+
+
+
+* `ExceptionRecognizer` +
++
+Register explicitly in isis.properties (so is extensible)
+
+
+
+
+
+== "Internal" SPIs
+
+These services definitions depend on the internals of the framework; we do not guarantee that link:semver.org[semantic versioning] will be honoured for these APIs.
+
+
+.Semi-public SPI
+[cols="3,3,2,2a", options="header"]
+|===
+
+|SPI
+|Maven Module +
+Impl'n (g: a:)
+|Implementation
+|Notes
+
+
+|<<__code_contentmappingservice_code, `o.a.i.v.ro.` +
+`rendering.service.conneg.` +
+`ContentMappingService`>>
+|
+|
+|No default implementation.
+
+|<<__code_contentnegotiationservice_code, `o.a.i.v.ro.` +
+`rendering.service.conneg.` +
+`ContentNegotiationService`>>
+|``o.a.i.core`` +
+`isis-core-viewer-restfulobjects-rendering`
+|`ContentNegotiationService-` +
+`XRoDomainType`
+|
+
+
+|===
+
+Key:
+
+* `o.a.i.v.ro` is an abbreviation for `org.apache.isis.viewer.restfulobjects`
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_auditing-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_auditing-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_auditing-service.adoc
new file mode 100644
index 0000000..e4626d2
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_auditing-service.adoc
@@ -0,0 +1,13 @@
+= `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/
+
+IMPORTANT: TODO
+
+
+
+
+== Isis Addons Implementation
+
+For 1.7.0+, see the http://github.com/isisaddons/isis-module-audit[Isis addons' Audit module] (non-ASF).
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_background-command-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_background-command-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_background-command-service.adoc
new file mode 100644
index 0000000..3111628
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_background-command-service.adoc
@@ -0,0 +1,12 @@
+= `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/
+
+IMPORTANT: TODO
+
+
+== Isis Addons Implementation
+
+For 1.7.0+, see the http://github.com/isisaddons/isis-module-command[Isis addons' Command module] (non-ASF).
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_class-discovery-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_class-discovery-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_class-discovery-service.adoc
new file mode 100644
index 0000000..075cf62
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_class-discovery-service.adoc
@@ -0,0 +1,8 @@
+= `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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_command-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_command-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_command-service.adoc
new file mode 100644
index 0000000..ab86189
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_command-service.adoc
@@ -0,0 +1,11 @@
+= `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/
+
+IMPORTANT: TODO
+
+
+== Isis Addons Implementation
+
+For 1.7.0+, see the http://github.com/isisaddons/isis-module-command[Isis addons' Command module] (non-ASF).
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_content-mapping-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_content-mapping-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_content-mapping-service.adoc
new file mode 100644
index 0000000..09d20f9
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_content-mapping-service.adoc
@@ -0,0 +1,8 @@
+= `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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_content-negotiation-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_content-negotiation-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_content-negotiation-service.adoc
new file mode 100644
index 0000000..89933f9
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_content-negotiation-service.adoc
@@ -0,0 +1,8 @@
+= `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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_email-notification-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_email-notification-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_email-notification-service.adoc
new file mode 100644
index 0000000..2a99016
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_email-notification-service.adoc
@@ -0,0 +1,8 @@
+= `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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_event-serializer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_event-serializer.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_event-serializer.adoc
new file mode 100644
index 0000000..2c20560
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_event-serializer.adoc
@@ -0,0 +1,8 @@
+= `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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_exception-recognizer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_exception-recognizer.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_exception-recognizer.adoc
new file mode 100644
index 0000000..04e7561
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_exception-recognizer.adoc
@@ -0,0 +1,8 @@
+= `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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_locale-provider.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_locale-provider.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_locale-provider.adoc
new file mode 100644
index 0000000..4956f49
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_locale-provider.adoc
@@ -0,0 +1,8 @@
+= `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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_publishing-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_publishing-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_publishing-service.adoc
new file mode 100644
index 0000000..93b17c1
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_publishing-service.adoc
@@ -0,0 +1,11 @@
+= `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/
+
+IMPORTANT: TODO
+
+
+== Isis Addons Implementation
+
+For 1.7.0+, see the http://github.com/isisaddons/isis-module-publishing[Isis addons' Publishing module] (non-ASF).
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_translation-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_translation-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_translation-service.adoc
new file mode 100644
index 0000000..0c1b16e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_translation-service.adoc
@@ -0,0 +1,8 @@
+= `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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_translations-resolver.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_translations-resolver.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_translations-resolver.adoc
new file mode 100644
index 0000000..7148bc7
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_translations-resolver.adoc
@@ -0,0 +1,8 @@
+= `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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_user-profile-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_user-profile-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_user-profile-service.adoc
new file mode 100644
index 0000000..6b56835
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_user-profile-service.adoc
@@ -0,0 +1,8 @@
+= `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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_user-registration-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_user-registration-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_user-registration-service.adoc
new file mode 100644
index 0000000..ab1a666
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi_user-registration-service.adoc
@@ -0,0 +1,8 @@
+= `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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_superclasses.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_superclasses.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_superclasses.adoc
new file mode 100644
index 0000000..d9aaee1
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_superclasses.adoc
@@ -0,0 +1,52 @@
+= 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
+
+
+|<<__code_fixturescripts_code, `o.a.i.applib.` +
+`fixturescripts` +
+`FixtureScripts`>>
+|``o.a.i.core`` +
+``isis-core-applib``
+|(abstract class)
+|depends on: +
+`ClassDiscoveryService`
+
+
+
+|===
+
+
+
+
+include::_user-guide_reference_superclasses_fixture-scripts.adoc[leveloffset=+1]
+
+
+
+== `AbstractDomainObject`
+
+IMPORTANT: TODO
+
+== `AbstractDomainService`
+
+IMPORTANT: TODO
+
+== `AbstractFactoryAndRepository`
+
+IMPORTANT: TODO
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_superclasses_fixture-scripts.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_superclasses_fixture-scripts.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_superclasses_fixture-scripts.adoc
new file mode 100644
index 0000000..f7cd2e2
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_superclasses_fixture-scripts.adoc
@@ -0,0 +1,8 @@
+= `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/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_value-types.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_value-types.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_value-types.adoc
new file mode 100644
index 0000000..0808f72
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_value-types.adoc
@@ -0,0 +1,14 @@
+= 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
+
+## JodaTime
+
+## Isis Applib
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..be399da
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer.adoc
@@ -0,0 +1,24 @@
+= 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::_user-guide_restfulobjects-viewer_features.adoc[leveloffset=+1]
+
+include::_user-guide_restfulobjects-viewer_configuration_properties.adoc[leveloffset=+1]
+
+include::_user-guide_restfulobjects-viewer_hints-and-tips.adoc[leveloffset=+1]
+
+
+== Extending the viewer
+
+Discussed in <<_extending_the_restful_viewer, Extending the Restful viewer>>.
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..546a4fa
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration_properties.adoc
@@ -0,0 +1,181 @@
+= 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/
+
+IMPORTANT: WIP...
+
+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).
+====
+
+
+.RestfulObjects Viewer Configuration Properties
+[cols="2a,1,3", options="header"]
+|===
+|Property
+|Value +
+(_default value_)
+|Description
+
+|`isis.viewer.restfulobjects.` +
+`honorUiHints`
+| `true`,`false` (`_false_`)
+| See <<_honor_ui_hints, discussion>>, below.
+
+|`isis.viewer.restfulobjects.` +
+`suppressDescribedByLinks`
+| `true`,`false` (`_false_`)
+.6+| See <<_suppressing_elements_of_the_representation, 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 <<_simplified_object_representation, discussion>>, below.
+
+|===
+
+
+
+== Honor UI hints
+
+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.
+====
+
+
+
+== Suppressing elements of the representation
+
+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 <<_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 <<_extending_the_restful_viewer, Extending the Restful viewer>> in the <<Extending>> chapter.
+
+
+
+== Simplified object representation
+
+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 <<_suppressing_elements_of_the_representations, 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 <<_extending_the_restful_viewer, Extending the Restful viewer>>.
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..2f8f591
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_features.adoc
@@ -0,0 +1,22 @@
+= 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 <<_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/97531ca0/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
new file mode 100644
index 0000000..f37da44
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_hints-and-tips.adoc
@@ -0,0 +1,75 @@
+= 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/
+
+
+
+== 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/97531ca0/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
new file mode 100644
index 0000000..8bc64e6
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime.adoc
@@ -0,0 +1,27 @@
+= 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 <<Wicket Viewer>> chapter and the <<Restful Objects Viewer>> chapter. Likewise, details of configuring security (Apache Shiro) can be found in the <<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::_user-guide_runtime_configuration-files.adoc[leveloffset=+1]
+
+include::_user-guide_runtime_configuring-core.adoc[leveloffset=+1]
+
+include::_user-guide_runtime_web-xml.adoc[leveloffset=+1]
+
+include::_user-guide_runtime_configuring-datanucleus.adoc[leveloffset=+1]
+
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..c5ddffe
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuration-files.adoc
@@ -0,0 +1,87 @@
+= 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 <<_wicket_viewer_2, Wicket UI (viewer)>> is in use
+
+* `viewer_restfulobjects.properties` - if the <<_restful_objects_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.
+
+
+== Specifying other components
+
+The `isis.properties` file has three 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.persistor`
+|`_datanucleus_`
+|`org.apache.isis.core.runtime.installerregistry.installerapi.` `PersistenceMechanismInstaller`
+
+|`isis.authentication`
+|`_shiro_` +
+`bypass`
+|`org.apache.isis.core.runtime.authentication.` `AuthenticationManagerInstaller`
+
+|`isis.authorization`
+|`_shiro_` +
+`bypass`
+|`org.apache.isis.core.runtime.authorization.` `AuthorizationManagerInstaller`
+
+|===
+
+[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. In practice only the two security APIs are actually simple enough for this to be viable.
+====
+
+As for the viewers, these are specified indirectly by way of the filters and servlets in the `web.xml` file (discussed <<_configuring_the_webapp, 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.
+
+
+
+== Deployment Types
+
+IMPORTANT: TODO
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..99c5618
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-core.adoc
@@ -0,0 +1,88 @@
+= 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.
+
+Configuration properties for the JDO/DataNucleus objectstore can be found in the <<_configuring_datanucleus, Configuring DataNucleus>> section elsewhere in this chapter.
+
+Configuration properties for the viewers can be found in the <<Wicket Viewer>> chapter and the <<Restful Objects Viewer>> chapter.
+
+
+.Core Configuration Properties
+[cols="2a,1,3a", options="header"]
+|===
+|Property
+|Value +
+(_default value_)
+|Description
+
+|`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 `@DomainServiceLayout#menuOrder()`).
+
+|`isis.services.` +
+`container.disableAutoFlush`
+| `true`,`false` (`_false_`)
+|Whether the `DomainObjectContainer` should automatically flush pending changes prior to querying (via `allMatches()`, `firstMatch()` and so on).
+
+|`isis.services.` +
+`translation.po.mode`
+| `read`,`write`
+|Whether to force the `TranslationService` into either read or write mode. +
+See <<_i18n, i18n support>> to learn more about the translation service.
+
+|`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.` +
+`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: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 <<_user-guide_how-tos_ui-hints_action-icons-and-css, UI hints>> for more details.
+
+|`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 <<_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 <<_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 <<_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 <<_finetuning, finetuning the programming model>> for more details.
+
+|`isis.reflector.validator`
+|`FQCN`
+|Custom implementation of `MetaModelValidator` (in the `org.apache.isis.core.metamodel.specloader.validator` package) +
+See <<_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.reflector.` +
+`layoutMetadataReaders`
+|`FQCN`,`FQCN2`,...
+|Fully qualified class names of classes to be instantiated to read layout metadata, as used in for <<_dynamic_object_layout, dynamic layout>>s. +
+See <<_layout_metadata_reader, Layout Metadata Reader>> for more information.
+
+|===
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..1e10db1
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus.adoc
@@ -0,0 +1,21 @@
+= 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 <<_overriding_jdo_annotations, Overriding JDO Annotatons>> for further discussion.
+
+
+include::_user-guide_runtime_configuring-datanucleus_properties.adoc[leveloffset=+1]
+
+include::_user-guide_runtime_configuring-datanucleus_persistence-xml.adoc[leveloffset=+1]
+
+include::_user-guide_runtime_configuring-datanucleus_eagerly-registering-entities.adoc[leveloffset=+1]
+
+include::_user-guide_runtime_configuring-datanucleus_disabling-persistence-by-reachability.adoc[leveloffset=+1]
+
+include::_user-guide_runtime_configuring-datanucleus_using-jndi-data-source.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..5c0b109
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_disabling-persistence-by-reachability.adoc
@@ -0,0 +1,93 @@
+= Disabling 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' link:../../../reference/Utility.html[ObjectContracts] utility. 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 <<_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.
+
+== Explanation of the issue in more detail
+
+Consider the entities:
+
+image::{_imagesdir}reference/configuration-properties/datanucleus-objectstore/party-agreementrole-agreement.png[width="750px"]
+
+
+[TIP]
+====
+[source]
+.DSL (http://yuml.me/edit/b8681268[yuml.me/b8681268])
+----
+[Party|reference]<--->*[AgreementRole|startDate]
+[AgreementRole]*<-->[Agreement|reference]
+----
+====
+
+
+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/97531ca0/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
new file mode 100644
index 0000000..3748ac3
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_eagerly-registering-entities.adoc
@@ -0,0 +1,43 @@
+= Eagerly Registering Entity 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/
+
+[WARNING]
+====
+From 1.6.0+ this feature may be (partly?) broken; see https://issues.apache.org/jira/browse/ISIS-847[ISIS-847].
+====
+
+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.
+
+
+== 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 <<_integration_testing, 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/97531ca0/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
new file mode 100644
index 0000000..7933b17
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_persistence-xml.adoc
@@ -0,0 +1,9 @@
+= `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/97531ca0/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
new file mode 100644
index 0000000..a76fa6a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_properties.adoc
@@ -0,0 +1,57 @@
+= 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/
+
+IMPORTANT: WIP...
+
+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.` +
+`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 <<_registering_entity_types, 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 <<_disabling_persistence_by_reachability, discussion below>>.
+
+|===
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..9888750
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_using-jndi-data-source.adoc
@@ -0,0 +1,72 @@
+= 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 connections
+
+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) datasource
+
+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/97531ca0/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
new file mode 100644
index 0000000..8be8f26
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_web-xml.adoc
@@ -0,0 +1,19 @@
+= `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
+
+
+== Servlets
+
+
+== Running Restful Objects Viewer only
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..acba897
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security.adoc
@@ -0,0 +1,52 @@
+= 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 <<_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 http://isisaddons.org[Isis Addons] (non-ASF) 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 -- <<_command_service, `CommandService`>> and <<_auditing_service, `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 http://isisaddons.org[Isis Addons] (non-ASF), namely the http://github.com/isisaddons/isis-module-command}[Isis addons' command] module and the http://github.com/isisaddons/isis-module-auditing}[Isis addons' auditing] module.
+====
+
+
+
+include::_user-guide_security_configuring-isis-to-use-shiro.adoc[leveloffset=+1]
+
+include::_user-guide_security_shiro-ini-realm.adoc[leveloffset=+1]
+
+include::_user-guide_security_shiro-isis-ldap-realm.adoc[leveloffset=+1]
+
+include::_user-guide_security_shiro-isisaddons-security-module-realm.adoc[leveloffset=+1]
+
+include::_user-guide_security_shiro-jdbc-realm.adoc[leveloffset=+1]
+
+include::_user-guide_security_shiro-isis-enhanced-wildcard-permission.adoc[leveloffset=+1]
+
+include::_user-guide_security_configuring-isis-to-use-bypass.adoc[leveloffset=+1]
+
+include::_user-guide_security_api-for-applications.adoc[leveloffset=+1]
+
+include::_user-guide_security_usage-by-isis-viewers.adoc[leveloffset=+1]
+
[15/22] isis git commit: ISIS-1133: renamed _user-guide_ to _ug_
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_applib-utility-classes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_applib-utility-classes.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_applib-utility-classes.adoc
new file mode 100644
index 0000000..f684ebe
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_applib-utility-classes.adoc
@@ -0,0 +1,144 @@
+= 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.
+
+== Title creation
+
+The `TitleBuffer` utility class is intended to make it easy to construct
+title strings (returned from the `title()` method). For example, it has
+overloaded versions of methods called `append()` and `concat()`.
+
+== Reason text creation (for disable and validate methods)
+
+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.
+
+== ObjectContracts
+
+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
+----
+#
+# Require explicit persistence (since entities are Comparable and using ObjectContracts#compareTo).
+#
+isis.persistor.datanucleus.impl.datanucleus.persistenceByReachabilityAtCommit=false
+----
+
+====
+
+### Explanation of 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/97531ca0/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
new file mode 100644
index 0000000..49106b3
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_methods.adoc
@@ -0,0 +1,14 @@
+= 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/
+
+
+
+include::_user-guide_reference_methods_aaa.adoc[leveloffset=+1]
+
+
+include::_user-guide_reference_methods_manpage_cssClass.adoc[leveloffset=+1]
+include::_user-guide_reference_methods_manpage_iconName.adoc[leveloffset=+1]
+include::_user-guide_reference_methods_manpage_getId.adoc[leveloffset=+1]
+include::_user-guide_reference_methods_manpage_title.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_methods_aaa.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_methods_aaa.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_methods_aaa.adoc
new file mode 100644
index 0000000..7c83936
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_methods_aaa.adoc
@@ -0,0 +1,117 @@
+= 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/
+
+
+
+
+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
+
+|<<__code_cssclass_code, `cssClass()`>>
+|Provides a CSS class for this object, which is added as a style in the containing when rendering the object within a table, or to a containing when rendering the object on a page. In conjunction with css/application.css, can therefore provide custom styling of an object instance wherever it is rendered.
+See also <<__code_title_code, `title()`>> and <<__code_iconName_code, `iconName()`>>.
+
+|<<__code_iconname_code, `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 <<__code_title_code, `title()`>> and <<__code_cssClass_code, `cssClass()`>>
+
+|<<__code_getid_code, `getId()`>>
+|Provides an optional unique identifier of a service. +
+If not provided, the services fully-qualified class name is used.
+
+|<<__code_title_code, `title()`>>
+|Provides a title for the object. +
+Alternatively, use the <<__code_title_code, `@Title`>> annotation. +
+See also `iconName()` and <<__code_cssClass_code, `cssClass()`>>
+
+|===
+
+
+
+
+
+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]
+====
+We believe there may some scenarios (not yet fully catalogued) where the lifecycle method is not called. As such we recommend that you don't rely on these methods and/or fully test they are called as required in your apps
+
+As an alternative, consider using Isis' event bus and domain events.
+====
+
+The lifecycle methods are:
+
+.Lifecycle methods (partial support)
+[cols="1,4a", options="header"]
+|===
+
+|Method
+|Description
+
+|<<__code_created_code, `created()`>>
+|called when an object has just been created using <<__code_newTransientInstance_code, `newTransientInstance()`>>
+
+|<<__code_loaded_code, `loaded()`>>
+|called when a (persistent) object has just been loaded from the object store.
+
+|<<__code_persisted_code, `persisted()`>>
+|called when object has just been persisted from the object store.
+
+|<<__code_persisting_code, `persisting()`>>
+|called when a (not-yet-persistent) object is just about to be persisted from the object store
+
+|<<__code_removed_code, `removed()`>>
+|called when a (persistent) object has just been persisted from the object store
+
+|<<__code_removing_code, `removing()`>>
+|called when a (persistent) object is just about to be deleted from the object store
+
+|<<__code_updated_code, `updated()`>>
+|called when a (persistent) object has just been updated in the object store
+
+|<<__code_updating_code, `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 <<__code_removed_code, `removed()`>>
+
+|`deleting()`
+|Replaced by 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 persisted()`
+
+|`saving()`
+|Replaced by <<__code_persisting_code, `persisting()`>>
+
+|===
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_methods_manpage_cssClass.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_methods_manpage_cssClass.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_methods_manpage_cssClass.adoc
new file mode 100644
index 0000000..1dc6a67
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_methods_manpage_cssClass.adoc
@@ -0,0 +1,8 @@
+= `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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_methods_manpage_getId.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_methods_manpage_getId.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_methods_manpage_getId.adoc
new file mode 100644
index 0000000..75586c0
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_methods_manpage_getId.adoc
@@ -0,0 +1,8 @@
+= `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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_methods_manpage_iconName.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_methods_manpage_iconName.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_methods_manpage_iconName.adoc
new file mode 100644
index 0000000..521649e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_methods_manpage_iconName.adoc
@@ -0,0 +1,8 @@
+= `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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_methods_manpage_title.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_methods_manpage_title.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_methods_manpage_title.adoc
new file mode 100644
index 0000000..1533a74
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_methods_manpage_title.adoc
@@ -0,0 +1,8 @@
+= `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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_mixins.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_mixins.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_mixins.adoc
new file mode 100644
index 0000000..13634f8
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_mixins.adoc
@@ -0,0 +1,11 @@
+= 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/
+
+
+IMPORTANT: TODO
+
+== `HasTransactionId`
+
+== `HasUsername`
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes.adoc
new file mode 100644
index 0000000..2cd4338
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes.adoc
@@ -0,0 +1,27 @@
+= Recognized 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/
+
+
+
+include::_user-guide_reference_prefixes_aaa.adoc[leveloffset=+1]
+
+include::_user-guide_reference_prefixes_manpage_addTo.adoc[leveloffset=+1]
+include::_user-guide_reference_prefixes_manpage_autoComplete.adoc[leveloffset=+1]
+include::_user-guide_reference_prefixes_manpage_choices.adoc[leveloffset=+1]
+include::_user-guide_reference_prefixes_manpage_clear.adoc[leveloffset=+1]
+include::_user-guide_reference_prefixes_manpage_default.adoc[leveloffset=+1]
+include::_user-guide_reference_prefixes_manpage_disable.adoc[leveloffset=+1]
+include::_user-guide_reference_prefixes_manpage_get.adoc[leveloffset=+1]
+include::_user-guide_reference_prefixes_manpage_hide.adoc[leveloffset=+1]
+include::_user-guide_reference_prefixes_manpage_modify.adoc[leveloffset=+1]
+include::_user-guide_reference_prefixes_manpage_removeFrom.adoc[leveloffset=+1]
+include::_user-guide_reference_prefixes_manpage_set.adoc[leveloffset=+1]
+include::_user-guide_reference_prefixes_manpage_validate.adoc[leveloffset=+1]
+include::_user-guide_reference_prefixes_manpage_validateAddTo.adoc[leveloffset=+1]
+include::_user-guide_reference_prefixes_manpage_validateRemoveFrom.adoc[leveloffset=+1]
+
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_aaa.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_aaa.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_aaa.adoc
new file mode 100644
index 0000000..ea45d56
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_aaa.adoc
@@ -0,0 +1,151 @@
+= 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/
+
+
+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
+
+|<<__code_addto_code, `addTo...()`>>
+|
+|
+|Y
+|
+|
+|add object to a collection (nb: not currently supported by Wicket viewer) +
+See also <<__code_removefrom_code, `removeFrom...()`>>`
+
+|<<__code_autocomplete_code, `autoComplete...()`>>
+|
+|Y
+|
+|
+|Y
+|Return a list of matching elements for a property or an action parameter. +
+Alternatively, can specify for a class using <<__code_domainobject_code, `@DomainObject#autoComplete`>> +
++
+See also choices
+
+|<<__code_choices_code, `choices...()`>>
+|
+|Y
+|
+|
+|Y
+|Provide list of choices for a property or action parameter
+See also <<__code_autocomplete_code, `autoComplete...()`>>.
+
+|<<__code_clear_code, `clear...()`>>
+|
+|Y
+|
+|
+|
+|Clear a property (set it to null). Allows business logic to be placed apart from the setter.
+See also <<__code_modify_code, `modify...()`>>
+
+
+|<<__code_default_code, `default...()`>>
+|
+|Y
+|
+|
+|Y
+|Default value for a property or an action parameter.
+
+|<<__code_disable_code, `disable...()`>>
+|Y
+|Y
+|Y
+|Y
+|
+|Disables (makes read-only) a property, a collection or an action.
+
+|<<__code_get_code, `get...()`>>
+|
+|Y
+|Y
+|
+|
+|Access the value of a property or collection. +
+See also <<__code_set_code, `set...()`>>.
+
+|<<__code_hide_code, `hide...()`>>
+|
+|Y
+|Y
+|Y
+|
+|Hides a property, a collection or an action.
+
+|<<__code_modify_code, `modify...()`>>
+|
+|Y
+|
+|
+|
+|Modify a property (set it to a non-null) value. Allows business logic to be placed apart from the setter. +
+See also <<__code_clear_code, `clear...()`>>`.
+
+|<<__code_removeFrom_code, `removeFrom...()`>>
+|
+|
+|Y
+|
+|
+|remove object from a collection (nb: not currently supported by Wicket viewer) +
+See also <<__code_addto_code, `addTo...()`>>`
+
+|<<__code_set_code, `set...()`>>
+|
+|Y
+|Y
+|
+|
+|Sets the value of a property or a collection.
+
+|<<__code_validate_code, `validate...()`>>
+|Y
+|
+|
+|Y
+|Y
+|Check that a proposed value of a property or an action parameter is valid. +
+See also <<__code_validateaddto_code, validateAddTo...()`>> and <<__code_validateremovefrom_code, `validateRemoveFrom...()`>> for collections.
+
+|<<__code_validateaddto_code, `validate +
+AddTo...()`>>
+|
+|Y
+|
+|
+|
+|Check that a proposed object to add to a collection is valid. +
+See also <<__code_validateremovefrom_code, `validateRemoveFrom...()`>>, and <<__code_validate_code, `validate...()`>> for properties and collections.
+
+|<<__code_validateremovefrom_code, `validate +
+RemoveFrom...()`>>
+|
+|Y
+|
+|
+|
+|Check that a proposed object to add to a collection is valid.
+See also <<__code_validateaddto_code, `validateAddTo...()`>>, and <<__code_validate_code, `validate...()`>> for properties and collections.
+
+|===
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_addTo.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_addTo.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_addTo.adoc
new file mode 100644
index 0000000..73a8ebb
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_addTo.adoc
@@ -0,0 +1,8 @@
+= `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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_autoComplete.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_autoComplete.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_autoComplete.adoc
new file mode 100644
index 0000000..1b4cfd1
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_autoComplete.adoc
@@ -0,0 +1,8 @@
+= `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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_choices.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_choices.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_choices.adoc
new file mode 100644
index 0000000..4406b14
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_choices.adoc
@@ -0,0 +1,8 @@
+= `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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_clear.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_clear.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_clear.adoc
new file mode 100644
index 0000000..a84aafc
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_clear.adoc
@@ -0,0 +1,8 @@
+= `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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_default.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_default.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_default.adoc
new file mode 100644
index 0000000..92f1658
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_default.adoc
@@ -0,0 +1,8 @@
+= `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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_disable.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_disable.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_disable.adoc
new file mode 100644
index 0000000..b511df5
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_disable.adoc
@@ -0,0 +1,8 @@
+= `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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_get.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_get.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_get.adoc
new file mode 100644
index 0000000..a2f9f87
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_get.adoc
@@ -0,0 +1,8 @@
+= `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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_hide.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_hide.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_hide.adoc
new file mode 100644
index 0000000..8918811
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_hide.adoc
@@ -0,0 +1,8 @@
+= `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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_modify.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_modify.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_modify.adoc
new file mode 100644
index 0000000..acd087d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_modify.adoc
@@ -0,0 +1,8 @@
+= `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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_removeFrom.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_removeFrom.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_removeFrom.adoc
new file mode 100644
index 0000000..14411ba
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_removeFrom.adoc
@@ -0,0 +1,8 @@
+= `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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_set.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_set.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_set.adoc
new file mode 100644
index 0000000..add8f0e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_set.adoc
@@ -0,0 +1,8 @@
+= `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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_validate.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_validate.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_validate.adoc
new file mode 100644
index 0000000..3135322
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_validate.adoc
@@ -0,0 +1,8 @@
+= `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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_validateAddTo.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_validateAddTo.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_validateAddTo.adoc
new file mode 100644
index 0000000..fa98e27
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_validateAddTo.adoc
@@ -0,0 +1,8 @@
+= `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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_validateRemoveFrom.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_validateRemoveFrom.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_validateRemoveFrom.adoc
new file mode 100644
index 0000000..0cb8353
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes_manpage_validateRemoveFrom.adoc
@@ -0,0 +1,8 @@
+= `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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..f613063
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api.adoc
@@ -0,0 +1,30 @@
+= 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/
+
+
+IMPORTANT: TODO
+
+include::_user-guide_reference_services-api_aaa.adoc[leveloffset=+1]
+
+include::_user-guide_reference_services-api_action-invocation-context.adoc[leveloffset=+1]
+include::_user-guide_reference_services-api_background-service.adoc[leveloffset=+1]
+include::_user-guide_reference_services-api_bookmark-service.adoc[leveloffset=+1]
+include::_user-guide_reference_services-api_clock-service.adoc[leveloffset=+1]
+include::_user-guide_reference_services-api_command-context.adoc[leveloffset=+1]
+include::_user-guide_reference_services-api_deep-link-service.adoc[leveloffset=+1]
+include::_user-guide_reference_services-api_domain-object-container.adoc[leveloffset=+1]
+include::_user-guide_reference_services-api_email-service.adoc[leveloffset=+1]
+include::_user-guide_reference_services-api_event-bus-service.adoc[leveloffset=+1]
+include::_user-guide_reference_services-api_guice-bean-provider.adoc[leveloffset=+1]
+include::_user-guide_reference_services-api_isis-jdo-support.adoc[leveloffset=+1]
+include::_user-guide_reference_services-api_memento-service.adoc[leveloffset=+1]
+include::_user-guide_reference_services-api_metamodel-service.adoc[leveloffset=+1]
+include::_user-guide_reference_services-api_query-results-cache.adoc[leveloffset=+1]
+include::_user-guide_reference_services-api_scratch-pad.adoc[leveloffset=+1]
+include::_user-guide_reference_services-api_sudo-service.adoc[leveloffset=+1]
+include::_user-guide_reference_services-api_wrapper-factory.adoc[leveloffset=+1]
+include::_user-guide_reference_services-api_xml-snapshot-service.adoc[leveloffset=+1]
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_aaa.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_aaa.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_aaa.adoc
new file mode 100644
index 0000000..4bb02a9
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_aaa.adoc
@@ -0,0 +1,215 @@
+= 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/
+
+
+
+IMPORTANT: TODO
+
+
+== Applib Services
+
+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 http://isisaddons.org[Isis Addons] (non-ASF)modules.
+
+.Domain Services
+[cols="2,4a,1,1", options="header"]
+|===
+
+|API
+|Maven Module +
+Impl'n (g: a:)
+|Implementation
+|Notes
+
+|<<__code_actioninvocationcontext_code, `o.a.i.applib.` +
+`services.actinv` +
+`ActionInvocation-` +
+`Context`>>
+|``o.a.i.core`` +
+``isis-core-applib``
+|`ActionInvocationContext`
+|API is also concrete class
+
+|<<__code_backgroundservice_code, `o.a.i.applib.` +
+`services.background` +
+`BackgroundService`>>
+|``o.a.i.core`` +
+``isis-core-runtime``
+|`BackgroundServiceDefault`
+|depends on: +
+`BackgroundCommandService`
+
+|<<__code_bookmarkservice_code, `o.a.i.applib.` +
+`services.bookmark` +
+`BookmarkService`>>
+|``o.a.i.core`` +
+``isis-core-metamodel``
+|`BookmarkServiceDefault`
+|related services:
+`BookmarkHolder-` ++
+`ActionContributions`,
+`BookmarkHolder-` ++
+`AssociationContributions`
+
+|<<__code_clockservice_code, `o.a.i.applib.` +
+`services.clock` +
+`ClockService`>>
+|``o.a.i.core`` +
+``isis-core-applib``
+|`ClockService`
+|API is also a concrete class.
+
+|<<__code_commandcontext_code, `o.a.i.applib.` +
+`services.command` +
+`CommandContext`>>
+|``o.a.i.core`` +
+``isis-core-applib``
+|`CommandContext`
+|API is also a concrete class. +
+depends on: +
+`CommandService` for persistent `Command`, else in-memory impl. used
+
+|<<__code_deeplinkservice_code, `o.a.i.applib` +
+`services.deeplink` +
+`DeepLinkService`>>
+|``o.a.i.viewer`` +
+``isis-viewer-wicket-impl``
+|`DeepLinkServiceWicket`
+|Implementation only usable within Wicket viewer
+
+|<<__code_domainobjectcontainer_code, `o.a.i.applib` +
+`DomainObjectContainer`>>
+|``o.a.i.core`` +
+``isis-core-metamodel``
+|`DomainObjectContainerDefault`
+|
+
+|<<__code_emailservice_code, `o.a.i.applib.` +
+`services.email` +
+`EmailService`>>
+|``o.a.i.core`` +
+``isis-core-runtime``
+|`EmailServiceDefault`
+|
+
+|<<__code_eventbusservice_code, `o.a.i.applib.` +
+`services.eventbus` +
+`EventBusService`>>
+|``o.a.i.core`` +
+``isis-core-objectstore-jdo-datanucleus``
+|`EventBusServiceJdo`
+|
+
+|<<__code_guicebeanprovider_code, `o.a.i.applib.` +
+`services.guice` +
+`GuiceBeanProvider`>>
+|``o.a.i.core`` +
+``isis-viewer-wicket-impl``
+|`GuiceBeanProviderWicket`
+|
+
+|<<__code_isisjdosupport_code, `o.a.i.applib.` +
+`services.jdosupport` +
+`IsisJdoSupport`>>
+|``o.a.i.core`` +
+``isis-core-objectstore-jdo-datanucleus``
+|`IsisJdoSupportImpl`
+|
+
+|<<__code_mementoservice_code, `o.a.i.applib.` +
+`services.memento` +
+`MementoService`>>
+|``o.a.i.core`` +
+``isis-core-runtime``
+|`MementoServiceDefault`
+|
+
+|<<__code_metamodelservice_code, `o.a.i.applib.` +
+`services.metamodel` +
+`MetaModelService`>>
+|``o.a.i.core`` +
+``isis-core-metamodel``
+|`MetaModelServiceDefault`
+|
+
+|<<__code_queryresultscache_code, `o.a.i.applib.` +
+`services.` +
+`queryresultscache` +
+`QueryResultsCache`>>
+|``o.a.i.core`` +
+``isis-core-applib``
+|`QueryResultsCache`
+|API is also a concrete class
+
+|<<__code_scratchpad_code, `o.a.i.applib.` +
+`services.scratchpad` +
+`Scratchpad`>>
+|``o.a.i.core`` +
+``isis-core-applib``
+|`Scratchpad`
+|API is also a concrete class
+
+|<<__code_scratchpad_code, `o.a.i.applib.` +
+`services.sudo` +
+`SudoService`>>
+|``o.a.i.core`` +
+``isis-core-runtime``
+|`SudoServiceDefault`
+|API is also a concrete class
+
+|<<__code_wrapperfactory_code, `o.a.i.applib.` +
+`services.wrapper` +
+`WrapperFactory`>>
+|``o.a.i.core`` +
+``isis-core-wrapper``
+|`WrapperFactoryDefault`
+|
+
+|<<__code_xmlsnapshotservice_code, `o.a.i.applib.` +
+`services.xmlsnapshot` +
+`XmlSnapshotService`>>
+|``o.a.i.core`` +
+``isis-core-runtime``
+|`XmlSnapshotServiceDefault`
+|
+
+|===
+
+Key:
+
+* `o.a.i` is an abbreviation for `org.apache.isis`
+* `o.ia.m` is an abbreviation for `org.isisaddons.module`
+
+
+
+
+== Deprecated Services
+
+There is also a number of deprecated domain services.
+
+.Deprecated Domain Services
+[cols="2,4a,1,1", options="header"]
+|===
+
+|API
+|Maven Module +
+Impl'n (g: a:)
+|Implementation
+|Notes
+
+|`o.a.i.applib.` +
+`annotation`
+`Bulk.InteractionContext`
+|``o.a.i.core`` +
+``isis-core-applib``
+|`Bulk.InteractionContext`
+|Replaced by `ActionInvocationContext`
+
+
+|===
+
+Key:
+
+* `o.a.i` is an abbreviation for `org.apache.isis`
+* `o.ia.m` is an abbreviation for `org.isisaddons.module`
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_action-invocation-context.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_action-invocation-context.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_action-invocation-context.adoc
new file mode 100644
index 0000000..989d131
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_action-invocation-context.adoc
@@ -0,0 +1,8 @@
+= `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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_background-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_background-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_background-service.adoc
new file mode 100644
index 0000000..74c69e5
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_background-service.adoc
@@ -0,0 +1,8 @@
+= `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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_bookmark-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_bookmark-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_bookmark-service.adoc
new file mode 100644
index 0000000..5d0024a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_bookmark-service.adoc
@@ -0,0 +1,8 @@
+= `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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_clock-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_clock-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_clock-service.adoc
new file mode 100644
index 0000000..1b4675d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_clock-service.adoc
@@ -0,0 +1,8 @@
+= `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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_command-context.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_command-context.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_command-context.adoc
new file mode 100644
index 0000000..15c250c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_command-context.adoc
@@ -0,0 +1,8 @@
+= `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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_deep-link-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_deep-link-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_deep-link-service.adoc
new file mode 100644
index 0000000..7135b31
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_deep-link-service.adoc
@@ -0,0 +1,8 @@
+= `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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_domain-object-container.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_domain-object-container.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_domain-object-container.adoc
new file mode 100644
index 0000000..53d253f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_domain-object-container.adoc
@@ -0,0 +1,8 @@
+= `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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_email-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_email-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_email-service.adoc
new file mode 100644
index 0000000..6f78302
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_email-service.adoc
@@ -0,0 +1,8 @@
+= `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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_event-bus-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_event-bus-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_event-bus-service.adoc
new file mode 100644
index 0000000..43275fe
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_event-bus-service.adoc
@@ -0,0 +1,15 @@
+= `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/
+
+IMPORTANT: TODO
+
+## Implementation
+
+IMPORTANT: TODO
+
+## Registration
+
+The `EventBusServiceJdo` class provides the default implementation and (as of 1.6.0+) is automatically registered using `@DomainService`. No further configuration is necessary.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_guice-bean-provider.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_guice-bean-provider.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_guice-bean-provider.adoc
new file mode 100644
index 0000000..99f4f36
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_guice-bean-provider.adoc
@@ -0,0 +1,8 @@
+= `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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_isis-jdo-support.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_isis-jdo-support.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_isis-jdo-support.adoc
new file mode 100644
index 0000000..3c1873a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_isis-jdo-support.adoc
@@ -0,0 +1,129 @@
+= `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.
+
+
+== API
+
+The API provided by `IsisJdoSupport` is:
+
+[source,java]
+----
+public interface IsisJdoSupport {
+ List<Map<String, Object>> executeSql(String sql);
+ Integer executeUpdate(String sql);
+ void deleteAll(Class<?>... pcClasses);
+ <T> T refresh(T domainObject);
+ void ensureLoaded(Collection<?> collectionOfDomainObjects);
+ PersistenceManager getJdoPersistenceManager();
+}
+----
+
+Each of these methods are discussed in more details below.
+
+
+== Executing arbitrary SQL
+
+The `executeSql(...)` method allows arbitrary 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 updates to be performed.
+
+[source,java]
+----
+int count = isisJdoSupport.executeUpdate("select count(*) from custMgmt.customers);
+----
+
+The returned value is the number of rows updated.
+
+
+
+== Fixture support
+
+The `deleteAll(...)` method is provided pretty much exclusively for tearing down fixture data:
+
+[source,java]
+----
+deleteAll(Order.class);
+deleteAll(CustomerAddress.class);
+deleteAll(Customer.class);
+----
+
+[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 <i>force</i> the deletion of all instances), concurrency checking
+is temporarily disabled while this method is performed.
+====
+
+
+
+== Reloading entities
+
+A http://www.datanucleus.org/products/datanucleus/jdo/orm/relationships.html[known limitation] of DataNucleus' implementation of JDO is that persisting a child entity (in a 1:n bidirectional relationship) does not cause the parent's collection to be updated.
+
+The `refresh(T domainObject)` method can be used to reload the parent object (or indeed any object).
+
+For example:
+
+[source,java]
+----
+public Order newOrder(final Customer customer) {
+ Order order = newTransientInstance(Order.class);
+ order.setCustomer(customer);
+ persist(customer);
+ getContainer().flush(); // <1>
+ isisJdoSupport.refresh(customer); // <2>
+ return order;
+}
+----
+<1> flush to database
+<2> reload parent from database
+
+
+[NOTE]
+====
+The particular example that led to this method being added was a 1:m bidirectional relationship,
+analogous to `Customer <-> * 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.
+
+====
+
+
+
+
+== Using JDO `PersistenceManager` directly
+
+Apache Isis provides a simplified API on top of only supports JDO, and so does not support all of JDO's features. For example, Isis (currently) only supports named queries. If you require more flexibility than this, eg for dynamically constructed queries, then the service provides access to the underlying JDO `PersistenceManager` API:
+
+[source,java]
+----
+public List<Order> findOrders(...) {
+ javax.jdo.PersistenceManager pm = isisJdoSupport.getPersistenceManager();
+
+ // knock yourself out...
+
+ return someListOfOrders;
+}
+----
+
+
+
+== Registering the Service
+
+The `IsisJdoSupportImpl` class provides the default implementation and (as of 1.6.0+) is automatically registered using `@DomainService`. No further configuration is necessary.
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_memento-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_memento-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_memento-service.adoc
new file mode 100644
index 0000000..f06a824
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_memento-service.adoc
@@ -0,0 +1,8 @@
+= `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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_metamodel-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_metamodel-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_metamodel-service.adoc
new file mode 100644
index 0000000..cb298dc
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_metamodel-service.adoc
@@ -0,0 +1,8 @@
+= `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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_query-results-cache.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_query-results-cache.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_query-results-cache.adoc
new file mode 100644
index 0000000..0b22d23
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_query-results-cache.adoc
@@ -0,0 +1,8 @@
+= `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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_scratch-pad.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_scratch-pad.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_scratch-pad.adoc
new file mode 100644
index 0000000..0a11596
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_scratch-pad.adoc
@@ -0,0 +1,8 @@
+= `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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_sudo-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_sudo-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_sudo-service.adoc
new file mode 100644
index 0000000..bb33642
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_sudo-service.adoc
@@ -0,0 +1,8 @@
+= `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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_wrapper-factory.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_wrapper-factory.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_wrapper-factory.adoc
new file mode 100644
index 0000000..e2949b1
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_wrapper-factory.adoc
@@ -0,0 +1,18 @@
+= `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/
+
+IMPORTANT: TODO
+
+
+
+
+
+
+
+== `wrapNoExecute()`
+
+
+== `wrapSkipRules()`
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_xml-snapshot-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_xml-snapshot-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_xml-snapshot-service.adoc
new file mode 100644
index 0000000..f82a24a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-api_xml-snapshot-service.adoc
@@ -0,0 +1,8 @@
+= `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/
+
+IMPORTANT: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/97531ca0/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
new file mode 100644
index 0000000..ddf79f6
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_services-spi.adoc
@@ -0,0 +1,25 @@
+= 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/
+
+
+IMPORTANT: TODO
+
+include::_user-guide_reference_services-spi_aaa.adoc[leveloffset=+1]
+
+include::_user-guide_reference_services-spi_auditing-service.adoc[leveloffset=+1]
+include::_user-guide_reference_services-spi_background-command-service.adoc[leveloffset=+1]
+include::_user-guide_reference_services-spi_class-discovery-service.adoc[leveloffset=+1]
+include::_user-guide_reference_services-spi_command-service.adoc[leveloffset=+1]
+include::_user-guide_reference_services-spi_content-mapping-service.adoc[leveloffset=+1]
+include::_user-guide_reference_services-spi_content-negotiation-service.adoc[leveloffset=+1]
+include::_user-guide_reference_services-spi_email-notification-service.adoc[leveloffset=+1]
+include::_user-guide_reference_services-spi_event-serializer.adoc[leveloffset=+1]
+include::_user-guide_reference_services-spi_exception-recognizer.adoc[leveloffset=+1]
+include::_user-guide_reference_services-spi_locale-provider.adoc[leveloffset=+1]
+include::_user-guide_reference_services-spi_publishing-service.adoc[leveloffset=+1]
+include::_user-guide_reference_services-spi_translation-service.adoc[leveloffset=+1]
+include::_user-guide_reference_services-spi_translations-resolver.adoc[leveloffset=+1]
+include::_user-guide_reference_services-spi_user-profile-service.adoc[leveloffset=+1]
+include::_user-guide_reference_services-spi_user-registration-service.adoc[leveloffset=+1]
[21/22] isis git commit: ISIS-1133: renaming _user-guide_ to _ug_
Posted by da...@apache.org.
ISIS-1133: renaming _user-guide_ to _ug_
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/63697165
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/63697165
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/63697165
Branch: refs/heads/master
Commit: 63697165ff0d86af27e7ad933909d4ff61807c30
Parents: 97531ca
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Mon May 18 07:21:21 2015 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Mon May 18 07:21:21 2015 +0100
----------------------------------------------------------------------
.../asciidoc/user-guide/_ug_appendices.adoc | 6 +-
.../user-guide/_ug_appendices_dev-env.adoc | 8 +--
.../asciidoc/user-guide/_ug_core-concepts.adoc | 10 ++--
.../_ug_core-concepts_philosophy.adoc | 12 ++--
.../_ug_core-concepts_principles.adoc | 6 +-
.../asciidoc/user-guide/_ug_deployment.adoc | 8 +--
.../main/asciidoc/user-guide/_ug_extending.adoc | 6 +-
.../_ug_extending_programming-model.adoc | 6 +-
.../user-guide/_ug_extending_wicket-viewer.adoc | 8 +--
.../user-guide/_ug_getting-started.adoc | 4 +-
.../main/asciidoc/user-guide/_ug_how-tos.adoc | 18 +++---
.../user-guide/_ug_how-tos_class-structure.adoc | 14 ++---
.../user-guide/_ug_how-tos_ui-hints.adoc | 10 ++--
.../asciidoc/user-guide/_ug_more-advanced.adoc | 20 +++----
.../_ug_more-advanced_decoupling.adoc | 6 +-
.../_ug_more-advanced_tips-n-tricks.adoc | 12 ++--
.../main/asciidoc/user-guide/_ug_reference.adoc | 20 +++----
.../user-guide/_ug_reference_addons.adoc | 2 +-
.../user-guide/_ug_reference_annotations.adoc | 58 ++++++++++----------
.../_ug_reference_annotations_aaa.adoc | 10 ++--
.../user-guide/_ug_reference_methods.adoc | 10 ++--
.../user-guide/_ug_reference_prefixes.adoc | 32 +++++------
.../user-guide/_ug_reference_services-api.adoc | 38 ++++++-------
.../user-guide/_ug_reference_services-spi.adoc | 32 +++++------
.../user-guide/_ug_reference_superclasses.adoc | 2 +-
.../user-guide/_ug_restfulobjects-viewer.adoc | 6 +-
.../main/asciidoc/user-guide/_ug_runtime.adoc | 8 +--
.../_ug_runtime_configuring-datanucleus.adoc | 10 ++--
.../main/asciidoc/user-guide/_ug_security.adoc | 18 +++---
.../main/asciidoc/user-guide/_ug_testing.adoc | 10 ++--
.../_ug_testing_bdd-spec-support.adoc | 10 ++--
.../user-guide/_ug_testing_fixture-scripts.adoc | 4 +-
.../_ug_testing_integ-test-support.adoc | 8 +--
.../_ug_testing_unit-test-support.adoc | 6 +-
.../user-guide/_ug_troubleshooting.adoc | 2 +-
.../asciidoc/user-guide/_ug_wicket-viewer.adoc | 12 ++--
.../user-guide/_ug_wicket-viewer_layout.adoc | 6 +-
.../main/asciidoc/user-guide/user-guide.adoc | 32 +++++------
38 files changed, 245 insertions(+), 245 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/63697165/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
index 8656e00..c42869f 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_appendices.adoc
@@ -5,8 +5,8 @@
IMPORTANT: TODO
-include::_user-guide_appendices_dev-env.adoc[leveloffset=+1]
+include::_ug_appendices_dev-env.adoc[leveloffset=+1]
-include::_user-guide_appendices_release-notes.adoc[leveloffset=+1]
+include::_ug_appendices_release-notes.adoc[leveloffset=+1]
-include::_user-guide_appendices_migration-notes.adoc[leveloffset=+1]
+include::_ug_appendices_migration-notes.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/63697165/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
index 63dd9d9..1de8983 100644
--- 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
@@ -5,10 +5,10 @@
IMPORTANT: TODO
-include::_user-guide_appendices_dev-env_cmd-line.adoc[leveloffset=+1]
+include::_ug_appendices_dev-env_cmd-line.adoc[leveloffset=+1]
-include::_user-guide_appendices_dev-env_intellij.adoc[leveloffset=+1]
+include::_ug_appendices_dev-env_intellij.adoc[leveloffset=+1]
-include::_user-guide_appendices_dev-env_eclipse.adoc[leveloffset=+1]
+include::_ug_appendices_dev-env_eclipse.adoc[leveloffset=+1]
-include::_user-guide_appendices_dev-env_isis-maven-plugin.adoc[leveloffset=+1]
+include::_ug_appendices_dev-env_isis-maven-plugin.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/63697165/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
index b5a5833..1d81dd6 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_core-concepts.adoc
@@ -11,14 +11,14 @@ Parts of this chapter have been adapted from Dan Haywood's 2009 book, 'Domain Dr
====
-include::_user-guide_core-concepts_philosophy.adoc[leveloffset=+1]
+include::_ug_core-concepts_philosophy.adoc[leveloffset=+1]
-include::_user-guide_core-concepts_principles.adoc[leveloffset=+1]
+include::_ug_core-concepts_principles.adoc[leveloffset=+1]
-include::_user-guide_core-concepts_building-blocks.adoc[leveloffset=+1]
+include::_ug_core-concepts_building-blocks.adoc[leveloffset=+1]
-include::_user-guide_core-concepts_framework-provided-services.adoc[leveloffset=+1]
+include::_ug_core-concepts_framework-provided-services.adoc[leveloffset=+1]
-include::_user-guide_core-concepts_add-ons.adoc[leveloffset=+1]
+include::_ug_core-concepts_add-ons.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/63697165/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
index 5825c02..592363b 100644
--- 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
@@ -5,16 +5,16 @@
This section describes some of the core ideas and architectural patterns upon which Apache Isis builds.
-include::_user-guide_core-concepts_philosophy_domain-driven-design.adoc[leveloffset=+1]
+include::_ug_core-concepts_philosophy_domain-driven-design.adoc[leveloffset=+1]
-include::_user-guide_core-concepts_philosophy_naked-objects-pattern.adoc[leveloffset=+1]
+include::_ug_core-concepts_philosophy_naked-objects-pattern.adoc[leveloffset=+1]
-include::_user-guide_core-concepts_philosophy_hexagonal-architecture.adoc[leveloffset=+1]
+include::_ug_core-concepts_philosophy_hexagonal-architecture.adoc[leveloffset=+1]
-include::_user-guide_core-concepts_philosophy_aop.adoc[leveloffset=+1]
+include::_ug_core-concepts_philosophy_aop.adoc[leveloffset=+1]
-// include::_user-guide_core-concepts_philosophy_dci.adoc[leveloffset=+1]
+// include::_ug_core-concepts_philosophy_dci.adoc[leveloffset=+1]
-include::_user-guide_core-concepts_philosophy_how-eases-ddd.adoc[leveloffset=+1]
+include::_ug_core-concepts_philosophy_how-eases-ddd.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/63697165/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
index 543ec76..cfc28fc 100644
--- 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
@@ -10,8 +10,8 @@ The first of these relate to how we believe your domain application should be wr
The section concludes by contrasting the framework with some other open source frameworks commonly used.
-include::_user-guide_core-concepts_principles_your-apps.adoc[leveloffset=+1]
+include::_ug_core-concepts_principles_your-apps.adoc[leveloffset=+1]
-include::_user-guide_core-concepts_principles_isis-itself.adoc[leveloffset=+1]
+include::_ug_core-concepts_principles_isis-itself.adoc[leveloffset=+1]
-include::_user-guide_core-concepts_principles_apache-isis-vs.adoc[leveloffset=+1]
+include::_ug_core-concepts_principles_apache-isis-vs.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/63697165/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
index 26fdede..d27dacf 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_deployment.adoc
@@ -5,13 +5,13 @@
This chapter provides guidance on some common deployment scenarios.
-include::_user-guide_deployment_cmd-line.adoc[leveloffset=+1]
+include::_ug_deployment_cmd-line.adoc[leveloffset=+1]
-include::_user-guide_deployment_tomcat.adoc[leveloffset=+1]
+include::_ug_deployment_tomcat.adoc[leveloffset=+1]
-include::_user-guide_deployment_gae.adoc[leveloffset=+1]
+include::_ug_deployment_gae.adoc[leveloffset=+1]
-include::_user-guide_deployment_jvm-flags.adoc[leveloffset=+1]
+include::_ug_deployment_jvm-flags.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/63697165/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
index 8f80ea4..0eb2a09 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_extending.adoc
@@ -5,9 +5,9 @@
This chapter explains the main APIs for extending Apache Isis: the programming model conventions, the Wicket viewer, and the Restful Objects viewer.
-include::_user-guide_extending_programming-model.adoc[leveloffset=+1]
+include::_ug_extending_programming-model.adoc[leveloffset=+1]
-include::_user-guide_extending_wicket-viewer.adoc[leveloffset=+1]
+include::_ug_extending_wicket-viewer.adoc[leveloffset=+1]
-include::_user-guide_extending_restfulobjects-viewer.adoc[leveloffset=+1]
+include::_ug_extending_restfulobjects-viewer.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/63697165/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
index bd1e959..f774487 100644
--- 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
@@ -4,9 +4,9 @@
:_imagesdir: images/
-include::_user-guide_extending_programming-model_custom-validator.adoc[leveloffset=+1]
+include::_ug_extending_programming-model_custom-validator.adoc[leveloffset=+1]
-include::_user-guide_extending_programming-model_finetuning.adoc[leveloffset=+1]
+include::_ug_extending_programming-model_finetuning.adoc[leveloffset=+1]
-include::_user-guide_extending_programming-model_layout-metadata-reader.adoc[leveloffset=+1]
+include::_ug_extending_programming-model_layout-metadata-reader.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/63697165/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
index 71f49e3..e57ce09 100644
--- 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
@@ -15,11 +15,11 @@ The Wicket viewer allows you to customize the GUI in several (progressively more
The first two of these options are discussed in the <<Wicket Viewer>> chapter. This chapter describes the remaining "heavier-weight/more powerful" options.
-include::_user-guide_extending_wicket-viewer_custom-bootstrap-theme.adoc[leveloffset=+1]
+include::_ug_extending_wicket-viewer_custom-bootstrap-theme.adoc[leveloffset=+1]
-include::_user-guide_extending_wicket-viewer_replacing-page-elements.adoc[leveloffset=+1]
+include::_ug_extending_wicket-viewer_replacing-page-elements.adoc[leveloffset=+1]
-include::_user-guide_extending_wicket-viewer_custom-pages.adoc[leveloffset=+1]
+include::_ug_extending_wicket-viewer_custom-pages.adoc[leveloffset=+1]
-include::_user-guide_extending_wicket-viewer_isis-addons-extensions.adoc[leveloffset=+1]
+include::_ug_extending_wicket-viewer_isis-addons-extensions.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/63697165/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
index c260365..0b93bbe 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_getting-started.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_getting-started.adoc
@@ -5,7 +5,7 @@
IMPORTANT: TODO
-include::_user-guide_getting-started_simpleapp-archetype.adoc[leveloffset=+1]
+include::_ug_getting-started_simpleapp-archetype.adoc[leveloffset=+1]
-include::_user-guide_getting-started_datanucleus-enhancer.adoc[leveloffset=+1]
+include::_ug_getting-started_datanucleus-enhancer.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/63697165/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
index 58e85d6..0b83aec 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_how-tos.adoc
@@ -5,21 +5,21 @@
IMPORTANT: TODO
-include::_user-guide_how-tos_class-structure.adoc[leveloffset=+1]
+include::_ug_how-tos_class-structure.adoc[leveloffset=+1]
-include::_user-guide_how-tos_ui-hints.adoc[leveloffset=+1]
+include::_ug_how-tos_ui-hints.adoc[leveloffset=+1]
-include::_user-guide_how-tos_domain-services.adoc[leveloffset=+1]
+include::_ug_how-tos_domain-services.adoc[leveloffset=+1]
-include::_user-guide_how-tos_crud.adoc[leveloffset=+1]
+include::_ug_how-tos_crud.adoc[leveloffset=+1]
-include::_user-guide_how-tos_entity-relationships.adoc[leveloffset=+1]
+include::_ug_how-tos_entity-relationships.adoc[leveloffset=+1]
-include::_user-guide_how-tos_contributed-members.adoc[leveloffset=+1]
+include::_ug_how-tos_contributed-members.adoc[leveloffset=+1]
-include::_user-guide_how-tos_business-rules.adoc[leveloffset=+1]
+include::_ug_how-tos_business-rules.adoc[leveloffset=+1]
-include::_user-guide_how-tos_derived-members.adoc[leveloffset=+1]
+include::_ug_how-tos_derived-members.adoc[leveloffset=+1]
-include::_user-guide_how-tos_drop-downs-and-defaults.adoc[leveloffset=+1]
+include::_ug_how-tos_drop-downs-and-defaults.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/63697165/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
index e775741..4b1e7a0 100644
--- 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
@@ -21,19 +21,19 @@ You can learn more about extending Isis programming model <<_extending_the_progr
====
-include::_user-guide_how-tos_class-structure_class-definition.adoc[leveloffset=+1]
+include::_ug_how-tos_class-structure_class-definition.adoc[leveloffset=+1]
-include::_user-guide_how-tos_class-structure_properties.adoc[leveloffset=+1]
+include::_ug_how-tos_class-structure_properties.adoc[leveloffset=+1]
-include::_user-guide_how-tos_class-structure_collections.adoc[leveloffset=+1]
+include::_ug_how-tos_class-structure_collections.adoc[leveloffset=+1]
-include::_user-guide_how-tos_class-structure_actions.adoc[leveloffset=+1]
+include::_ug_how-tos_class-structure_actions.adoc[leveloffset=+1]
-include::_user-guide_how-tos_class-structure_action-parameters.adoc[leveloffset=+1]
+include::_ug_how-tos_class-structure_action-parameters.adoc[leveloffset=+1]
-include::_user-guide_how-tos_class-structure_properties-vs-parameters.adoc[leveloffset=+1]
+include::_ug_how-tos_class-structure_properties-vs-parameters.adoc[leveloffset=+1]
-include::_user-guide_how-tos_class-structure_ignoring-methods.adoc[leveloffset=+1]
+include::_ug_how-tos_class-structure_ignoring-methods.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/63697165/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
index f8e6e1a..f3732ff 100644
--- 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
@@ -5,13 +5,13 @@
IMPORTANT: TODO
-include::_user-guide_how-tos_ui-hints_object-titles-and-icons.adoc[leveloffset=+1]
+include::_ug_how-tos_ui-hints_object-titles-and-icons.adoc[leveloffset=+1]
-include::_user-guide_how-tos_ui-hints_names-and-descriptions.adoc[leveloffset=+1]
+include::_ug_how-tos_ui-hints_names-and-descriptions.adoc[leveloffset=+1]
-include::_user-guide_how-tos_ui-hints_layout.adoc[leveloffset=+1]
+include::_ug_how-tos_ui-hints_layout.adoc[leveloffset=+1]
-include::_user-guide_how-tos_ui-hints_eager-rendering.adoc[leveloffset=+1]
+include::_ug_how-tos_ui-hints_eager-rendering.adoc[leveloffset=+1]
-include::_user-guide_how-tos_ui-hints_action-icons-and-css.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/63697165/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
index dc62e39..b66cbde 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_more-advanced.adoc
@@ -6,25 +6,25 @@
IMPORTANT: TODO
-include::_user-guide_more-advanced_decoupling.adoc[leveloffset=+1]
+include::_ug_more-advanced_decoupling.adoc[leveloffset=+1]
-include::_user-guide_more-advanced_assembling.adoc[leveloffset=+1]
+include::_ug_more-advanced_assembling.adoc[leveloffset=+1]
-include::_user-guide_more-advanced_bulk-actions.adoc[leveloffset=+1]
+include::_ug_more-advanced_bulk-actions.adoc[leveloffset=+1]
-include::_user-guide_more-advanced_view-models.adoc[leveloffset=+1]
+include::_ug_more-advanced_view-models.adoc[leveloffset=+1]
-include::_user-guide_more-advanced_transactions-and-errors.adoc[leveloffset=+1]
+include::_ug_more-advanced_transactions-and-errors.adoc[leveloffset=+1]
-include::_user-guide_more-advanced_i18n.adoc[leveloffset=+1]
+include::_ug_more-advanced_i18n.adoc[leveloffset=+1]
-include::_user-guide_more-advanced_multi-tenancy.adoc[leveloffset=+1]
+include::_ug_more-advanced_multi-tenancy.adoc[leveloffset=+1]
-include::_user-guide_more-advanced_persistence-lifecycle.adoc[leveloffset=+1]
+include::_ug_more-advanced_persistence-lifecycle.adoc[leveloffset=+1]
-include::_user-guide_more-advanced_neo4j.adoc[leveloffset=+1]
+include::_ug_more-advanced_neo4j.adoc[leveloffset=+1]
-include::_user-guide_more-advanced_tips-n-tricks.adoc[leveloffset=+1]
+include::_ug_more-advanced_tips-n-tricks.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/63697165/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
index cdcaf84..4578a9d 100644
--- 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
@@ -15,11 +15,11 @@ The <<_assembling, following section>> describes how to re-assemble an applicati
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::_user-guide_more-advanced_decoupling_db-schemas.adoc[leveloffset=+1]
+include::_ug_more-advanced_decoupling_db-schemas.adoc[leveloffset=+1]
-include::_user-guide_more-advanced_decoupling_contributions.adoc[leveloffset=+1]
+include::_ug_more-advanced_decoupling_contributions.adoc[leveloffset=+1]
-include::_user-guide_more-advanced_decoupling_event-bus.adoc[leveloffset=+1]
+include::_ug_more-advanced_decoupling_event-bus.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/63697165/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
index c555440..aa2ac1e 100644
--- 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
@@ -6,15 +6,15 @@
IMPORTANT: TODO
-include::_user-guide_more-advanced_tips-n-tricks_are-you-sure.adoc[leveloffset=+1]
+include::_ug_more-advanced_tips-n-tricks_are-you-sure.adoc[leveloffset=+1]
-include::_user-guide_more-advanced_tips-n-tricks_simulating-collections-of-values.adoc[leveloffset=+1]
+include::_ug_more-advanced_tips-n-tricks_simulating-collections-of-values.adoc[leveloffset=+1]
-include::_user-guide_more-advanced_tips-n-tricks_render-all-properties-in-tables.adoc[leveloffset=+1]
+include::_ug_more-advanced_tips-n-tricks_render-all-properties-in-tables.adoc[leveloffset=+1]
-include::_user-guide_more-advanced_tips-n-tricks_per-user-themes.adoc[leveloffset=+1]
+include::_ug_more-advanced_tips-n-tricks_per-user-themes.adoc[leveloffset=+1]
-include::_user-guide_more-advanced_tips-n-tricks_suppress-actions-from-the-ui.adoc[leveloffset=+1]
+include::_ug_more-advanced_tips-n-tricks_suppress-actions-from-the-ui.adoc[leveloffset=+1]
-include::_user-guide_more-advanced_tips-n-tricks_enhance-only.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/63697165/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference.adoc
index 62324ed..8159b69 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference.adoc
@@ -12,14 +12,14 @@ Some of the services defined in the applib are intended to be used (primarily) n
Some domain services can be considered both API and SPI; a good example is the `EmailService` that is of direct use for domain objects wishing to send out emails, but is also used by the framework to support the user registration functionality supported by the <<_wicket_viewer, Wicket viewer>>. The same is true of the <<__code_eventbusservice_code, `EventBusService`>>; this can be used by domain objects to broadcast arbitrary events, but is also used by the framework to automatically emit events eg for `@Action(domainEvent=...)`. For these hybrid services we we have categorized the service as an "API" service.
-include::_user-guide_reference_annotations.adoc[leveloffset=+1]
-include::_user-guide_reference_prefixes.adoc[leveloffset=+1]
-include::_user-guide_reference_methods.adoc[leveloffset=+1]
-include::_user-guide_reference_services-api.adoc[leveloffset=+1]
-include::_user-guide_reference_services-spi.adoc[leveloffset=+1]
-include::_user-guide_reference_superclasses.adoc[leveloffset=+1]
-include::_user-guide_reference_value-types.adoc[leveloffset=+1]
-include::_user-guide_reference_applib-utility-classes.adoc[leveloffset=+1]
-include::_user-guide_reference_mixins.adoc[leveloffset=+1]
-include::_user-guide_reference_addons.adoc[leveloffset=+1]
+include::_ug_reference_annotations.adoc[leveloffset=+1]
+include::_ug_reference_prefixes.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_superclasses.adoc[leveloffset=+1]
+include::_ug_reference_value-types.adoc[leveloffset=+1]
+include::_ug_reference_applib-utility-classes.adoc[leveloffset=+1]
+include::_ug_reference_mixins.adoc[leveloffset=+1]
+include::_ug_reference_addons.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/63697165/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_addons.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_addons.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_addons.adoc
index caa04de..c3b3284 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_addons.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_addons.adoc
@@ -12,6 +12,6 @@ The http://isisaddons.org[Isis Addons], while maintained by Isis committers, are
====
-include::_user-guide_reference_addons_settings-module.adoc[leveloffset=+1]
+include::_ug_reference_addons_settings-module.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/63697165/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
index d8f34bc..528ffa7 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_annotations.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_annotations.adoc
@@ -6,34 +6,34 @@
IMPORTANT: TODO
-include::_user-guide_reference_annotations_aaa.adoc[leveloffset=+1]
-
-include::_user-guide_reference_annotations_manpage_action.adoc[leveloffset=+1]
-include::_user-guide_reference_annotations_manpage_actionlayout.adoc[leveloffset=+1]
-include::_user-guide_reference_annotations_manpage_collection.adoc[leveloffset=+1]
-include::_user-guide_reference_annotations_manpage_collectionlayout.adoc[leveloffset=+1]
-include::_user-guide_reference_annotations_manpage_domainobject.adoc[leveloffset=+1]
-include::_user-guide_reference_annotations_manpage_domainobjectlayout.adoc[leveloffset=+1]
-include::_user-guide_reference_annotations_manpage_domainservice.adoc[leveloffset=+1]
-include::_user-guide_reference_annotations_manpage_domainservicelayout.adoc[leveloffset=+1]
-include::_user-guide_reference_annotations_manpage_parameter.adoc[leveloffset=+1]
-include::_user-guide_reference_annotations_manpage_property.adoc[leveloffset=+1]
-include::_user-guide_reference_annotations_manpage_propertylayout.adoc[leveloffset=+1]
-include::_user-guide_reference_annotations_manpage_viewmodel.adoc[leveloffset=+1]
-include::_user-guide_reference_annotations_manpage_viewmodellayout.adoc[leveloffset=+1]
-
-
-include::_user-guide_reference_annotations_manpage_facets.adoc[leveloffset=+1]
-include::_user-guide_reference_annotations_manpage_homepage.adoc[leveloffset=+1]
-include::_user-guide_reference_annotations_manpage_membergrouplayout.adoc[leveloffset=+1]
-include::_user-guide_reference_annotations_manpage_memberorder.adoc[leveloffset=+1]
-include::_user-guide_reference_annotations_manpage_programmatic.adoc[leveloffset=+1]
-include::_user-guide_reference_annotations_manpage_minlength.adoc[leveloffset=+1]
-include::_user-guide_reference_annotations_manpage_title.adoc[leveloffset=+1]
-
-
-include::_user-guide_reference_annotations_manpage_requestscoped.adoc[leveloffset=+1]
-include::_user-guide_reference_annotations_manpage_inject.adoc[leveloffset=+1]
-include::_user-guide_reference_annotations_manpage_digits.adoc[leveloffset=+1]
+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_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_parameter.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_viewmodel.adoc[leveloffset=+1]
+include::_ug_reference_annotations_manpage_viewmodellayout.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_membergrouplayout.adoc[leveloffset=+1]
+include::_ug_reference_annotations_manpage_memberorder.adoc[leveloffset=+1]
+include::_ug_reference_annotations_manpage_programmatic.adoc[leveloffset=+1]
+include::_ug_reference_annotations_manpage_minlength.adoc[leveloffset=+1]
+include::_ug_reference_annotations_manpage_title.adoc[leveloffset=+1]
+
+
+include::_ug_reference_annotations_manpage_requestscoped.adoc[leveloffset=+1]
+include::_ug_reference_annotations_manpage_inject.adoc[leveloffset=+1]
+include::_ug_reference_annotations_manpage_digits.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/63697165/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
index c8ef404..4868532 100644
--- 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
@@ -5,10 +5,10 @@
-include::_user-guide_reference_annotations_aaa_main.adoc[leveloffset=+1]
-include::_user-guide_reference_annotations_aaa_other.adoc[leveloffset=+1]
-include::_user-guide_reference_annotations_aaa_jee.adoc[leveloffset=+1]
-include::_user-guide_reference_annotations_aaa_deprecated.adoc[leveloffset=+1]
-include::_user-guide_reference_annotations_aaa_partial.adoc[leveloffset=+1]
+include::_ug_reference_annotations_aaa_main.adoc[leveloffset=+1]
+include::_ug_reference_annotations_aaa_other.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/63697165/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
index 49106b3..0b2ac78 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_methods.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_methods.adoc
@@ -5,10 +5,10 @@
-include::_user-guide_reference_methods_aaa.adoc[leveloffset=+1]
+include::_ug_reference_methods_aaa.adoc[leveloffset=+1]
-include::_user-guide_reference_methods_manpage_cssClass.adoc[leveloffset=+1]
-include::_user-guide_reference_methods_manpage_iconName.adoc[leveloffset=+1]
-include::_user-guide_reference_methods_manpage_getId.adoc[leveloffset=+1]
-include::_user-guide_reference_methods_manpage_title.adoc[leveloffset=+1]
+include::_ug_reference_methods_manpage_cssClass.adoc[leveloffset=+1]
+include::_ug_reference_methods_manpage_iconName.adoc[leveloffset=+1]
+include::_ug_reference_methods_manpage_getId.adoc[leveloffset=+1]
+include::_ug_reference_methods_manpage_title.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/63697165/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes.adoc
index 2cd4338..08280c4 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_prefixes.adoc
@@ -5,22 +5,22 @@
-include::_user-guide_reference_prefixes_aaa.adoc[leveloffset=+1]
-
-include::_user-guide_reference_prefixes_manpage_addTo.adoc[leveloffset=+1]
-include::_user-guide_reference_prefixes_manpage_autoComplete.adoc[leveloffset=+1]
-include::_user-guide_reference_prefixes_manpage_choices.adoc[leveloffset=+1]
-include::_user-guide_reference_prefixes_manpage_clear.adoc[leveloffset=+1]
-include::_user-guide_reference_prefixes_manpage_default.adoc[leveloffset=+1]
-include::_user-guide_reference_prefixes_manpage_disable.adoc[leveloffset=+1]
-include::_user-guide_reference_prefixes_manpage_get.adoc[leveloffset=+1]
-include::_user-guide_reference_prefixes_manpage_hide.adoc[leveloffset=+1]
-include::_user-guide_reference_prefixes_manpage_modify.adoc[leveloffset=+1]
-include::_user-guide_reference_prefixes_manpage_removeFrom.adoc[leveloffset=+1]
-include::_user-guide_reference_prefixes_manpage_set.adoc[leveloffset=+1]
-include::_user-guide_reference_prefixes_manpage_validate.adoc[leveloffset=+1]
-include::_user-guide_reference_prefixes_manpage_validateAddTo.adoc[leveloffset=+1]
-include::_user-guide_reference_prefixes_manpage_validateRemoveFrom.adoc[leveloffset=+1]
+include::_ug_reference_prefixes_aaa.adoc[leveloffset=+1]
+
+include::_ug_reference_prefixes_manpage_addTo.adoc[leveloffset=+1]
+include::_ug_reference_prefixes_manpage_autoComplete.adoc[leveloffset=+1]
+include::_ug_reference_prefixes_manpage_choices.adoc[leveloffset=+1]
+include::_ug_reference_prefixes_manpage_clear.adoc[leveloffset=+1]
+include::_ug_reference_prefixes_manpage_default.adoc[leveloffset=+1]
+include::_ug_reference_prefixes_manpage_disable.adoc[leveloffset=+1]
+include::_ug_reference_prefixes_manpage_get.adoc[leveloffset=+1]
+include::_ug_reference_prefixes_manpage_hide.adoc[leveloffset=+1]
+include::_ug_reference_prefixes_manpage_modify.adoc[leveloffset=+1]
+include::_ug_reference_prefixes_manpage_removeFrom.adoc[leveloffset=+1]
+include::_ug_reference_prefixes_manpage_set.adoc[leveloffset=+1]
+include::_ug_reference_prefixes_manpage_validate.adoc[leveloffset=+1]
+include::_ug_reference_prefixes_manpage_validateAddTo.adoc[leveloffset=+1]
+include::_ug_reference_prefixes_manpage_validateRemoveFrom.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/63697165/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
index f613063..9b28adb 100644
--- 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
@@ -6,25 +6,25 @@
IMPORTANT: TODO
-include::_user-guide_reference_services-api_aaa.adoc[leveloffset=+1]
+include::_ug_reference_services-api_aaa.adoc[leveloffset=+1]
-include::_user-guide_reference_services-api_action-invocation-context.adoc[leveloffset=+1]
-include::_user-guide_reference_services-api_background-service.adoc[leveloffset=+1]
-include::_user-guide_reference_services-api_bookmark-service.adoc[leveloffset=+1]
-include::_user-guide_reference_services-api_clock-service.adoc[leveloffset=+1]
-include::_user-guide_reference_services-api_command-context.adoc[leveloffset=+1]
-include::_user-guide_reference_services-api_deep-link-service.adoc[leveloffset=+1]
-include::_user-guide_reference_services-api_domain-object-container.adoc[leveloffset=+1]
-include::_user-guide_reference_services-api_email-service.adoc[leveloffset=+1]
-include::_user-guide_reference_services-api_event-bus-service.adoc[leveloffset=+1]
-include::_user-guide_reference_services-api_guice-bean-provider.adoc[leveloffset=+1]
-include::_user-guide_reference_services-api_isis-jdo-support.adoc[leveloffset=+1]
-include::_user-guide_reference_services-api_memento-service.adoc[leveloffset=+1]
-include::_user-guide_reference_services-api_metamodel-service.adoc[leveloffset=+1]
-include::_user-guide_reference_services-api_query-results-cache.adoc[leveloffset=+1]
-include::_user-guide_reference_services-api_scratch-pad.adoc[leveloffset=+1]
-include::_user-guide_reference_services-api_sudo-service.adoc[leveloffset=+1]
-include::_user-guide_reference_services-api_wrapper-factory.adoc[leveloffset=+1]
-include::_user-guide_reference_services-api_xml-snapshot-service.adoc[leveloffset=+1]
+include::_ug_reference_services-api_action-invocation-context.adoc[leveloffset=+1]
+include::_ug_reference_services-api_background-service.adoc[leveloffset=+1]
+include::_ug_reference_services-api_bookmark-service.adoc[leveloffset=+1]
+include::_ug_reference_services-api_clock-service.adoc[leveloffset=+1]
+include::_ug_reference_services-api_command-context.adoc[leveloffset=+1]
+include::_ug_reference_services-api_deep-link-service.adoc[leveloffset=+1]
+include::_ug_reference_services-api_domain-object-container.adoc[leveloffset=+1]
+include::_ug_reference_services-api_email-service.adoc[leveloffset=+1]
+include::_ug_reference_services-api_event-bus-service.adoc[leveloffset=+1]
+include::_ug_reference_services-api_guice-bean-provider.adoc[leveloffset=+1]
+include::_ug_reference_services-api_isis-jdo-support.adoc[leveloffset=+1]
+include::_ug_reference_services-api_memento-service.adoc[leveloffset=+1]
+include::_ug_reference_services-api_metamodel-service.adoc[leveloffset=+1]
+include::_ug_reference_services-api_query-results-cache.adoc[leveloffset=+1]
+include::_ug_reference_services-api_scratch-pad.adoc[leveloffset=+1]
+include::_ug_reference_services-api_sudo-service.adoc[leveloffset=+1]
+include::_ug_reference_services-api_wrapper-factory.adoc[leveloffset=+1]
+include::_ug_reference_services-api_xml-snapshot-service.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/63697165/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
index ddf79f6..55ff71e 100644
--- 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
@@ -6,20 +6,20 @@
IMPORTANT: TODO
-include::_user-guide_reference_services-spi_aaa.adoc[leveloffset=+1]
+include::_ug_reference_services-spi_aaa.adoc[leveloffset=+1]
-include::_user-guide_reference_services-spi_auditing-service.adoc[leveloffset=+1]
-include::_user-guide_reference_services-spi_background-command-service.adoc[leveloffset=+1]
-include::_user-guide_reference_services-spi_class-discovery-service.adoc[leveloffset=+1]
-include::_user-guide_reference_services-spi_command-service.adoc[leveloffset=+1]
-include::_user-guide_reference_services-spi_content-mapping-service.adoc[leveloffset=+1]
-include::_user-guide_reference_services-spi_content-negotiation-service.adoc[leveloffset=+1]
-include::_user-guide_reference_services-spi_email-notification-service.adoc[leveloffset=+1]
-include::_user-guide_reference_services-spi_event-serializer.adoc[leveloffset=+1]
-include::_user-guide_reference_services-spi_exception-recognizer.adoc[leveloffset=+1]
-include::_user-guide_reference_services-spi_locale-provider.adoc[leveloffset=+1]
-include::_user-guide_reference_services-spi_publishing-service.adoc[leveloffset=+1]
-include::_user-guide_reference_services-spi_translation-service.adoc[leveloffset=+1]
-include::_user-guide_reference_services-spi_translations-resolver.adoc[leveloffset=+1]
-include::_user-guide_reference_services-spi_user-profile-service.adoc[leveloffset=+1]
-include::_user-guide_reference_services-spi_user-registration-service.adoc[leveloffset=+1]
+include::_ug_reference_services-spi_auditing-service.adoc[leveloffset=+1]
+include::_ug_reference_services-spi_background-command-service.adoc[leveloffset=+1]
+include::_ug_reference_services-spi_class-discovery-service.adoc[leveloffset=+1]
+include::_ug_reference_services-spi_command-service.adoc[leveloffset=+1]
+include::_ug_reference_services-spi_content-mapping-service.adoc[leveloffset=+1]
+include::_ug_reference_services-spi_content-negotiation-service.adoc[leveloffset=+1]
+include::_ug_reference_services-spi_email-notification-service.adoc[leveloffset=+1]
+include::_ug_reference_services-spi_event-serializer.adoc[leveloffset=+1]
+include::_ug_reference_services-spi_exception-recognizer.adoc[leveloffset=+1]
+include::_ug_reference_services-spi_locale-provider.adoc[leveloffset=+1]
+include::_ug_reference_services-spi_publishing-service.adoc[leveloffset=+1]
+include::_ug_reference_services-spi_translation-service.adoc[leveloffset=+1]
+include::_ug_reference_services-spi_translations-resolver.adoc[leveloffset=+1]
+include::_ug_reference_services-spi_user-profile-service.adoc[leveloffset=+1]
+include::_ug_reference_services-spi_user-registration-service.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/63697165/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_superclasses.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_superclasses.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_superclasses.adoc
index d9aaee1..2882d06 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_superclasses.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference_superclasses.adoc
@@ -35,7 +35,7 @@ Impl'n (g: a:)
-include::_user-guide_reference_superclasses_fixture-scripts.adoc[leveloffset=+1]
+include::_ug_reference_superclasses_fixture-scripts.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/63697165/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
index be399da..e7c62cf 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer.adoc
@@ -9,11 +9,11 @@ The Restful Objects viewer also provides a number of proprietary extensions.
-include::_user-guide_restfulobjects-viewer_features.adoc[leveloffset=+1]
+include::_ug_restfulobjects-viewer_features.adoc[leveloffset=+1]
-include::_user-guide_restfulobjects-viewer_configuration_properties.adoc[leveloffset=+1]
+include::_ug_restfulobjects-viewer_configuration_properties.adoc[leveloffset=+1]
-include::_user-guide_restfulobjects-viewer_hints-and-tips.adoc[leveloffset=+1]
+include::_ug_restfulobjects-viewer_hints-and-tips.adoc[leveloffset=+1]
== Extending the viewer
http://git-wip-us.apache.org/repos/asf/isis/blob/63697165/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
index 8bc64e6..1e49c4a 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime.adoc
@@ -13,13 +13,13 @@ Configuration properties for the viewers can be found in the <<Wicket Viewer>> c
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::_user-guide_runtime_configuration-files.adoc[leveloffset=+1]
+include::_ug_runtime_configuration-files.adoc[leveloffset=+1]
-include::_user-guide_runtime_configuring-core.adoc[leveloffset=+1]
+include::_ug_runtime_configuring-core.adoc[leveloffset=+1]
-include::_user-guide_runtime_web-xml.adoc[leveloffset=+1]
+include::_ug_runtime_web-xml.adoc[leveloffset=+1]
-include::_user-guide_runtime_configuring-datanucleus.adoc[leveloffset=+1]
+include::_ug_runtime_configuring-datanucleus.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/63697165/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
index 1e10db1..67eb300 100644
--- 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
@@ -10,12 +10,12 @@ DataNucleus will for itself also and read the `META-INF/persistence.xml`; at a m
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 <<_overriding_jdo_annotations, Overriding JDO Annotatons>> for further discussion.
-include::_user-guide_runtime_configuring-datanucleus_properties.adoc[leveloffset=+1]
+include::_ug_runtime_configuring-datanucleus_properties.adoc[leveloffset=+1]
-include::_user-guide_runtime_configuring-datanucleus_persistence-xml.adoc[leveloffset=+1]
+include::_ug_runtime_configuring-datanucleus_persistence-xml.adoc[leveloffset=+1]
-include::_user-guide_runtime_configuring-datanucleus_eagerly-registering-entities.adoc[leveloffset=+1]
+include::_ug_runtime_configuring-datanucleus_eagerly-registering-entities.adoc[leveloffset=+1]
-include::_user-guide_runtime_configuring-datanucleus_disabling-persistence-by-reachability.adoc[leveloffset=+1]
+include::_ug_runtime_configuring-datanucleus_disabling-persistence-by-reachability.adoc[leveloffset=+1]
-include::_user-guide_runtime_configuring-datanucleus_using-jndi-data-source.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/63697165/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
index acba897..b5983ad 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security.adoc
@@ -32,21 +32,21 @@ Isis does not itself provide any in-built implementations of these APIs, but the
-include::_user-guide_security_configuring-isis-to-use-shiro.adoc[leveloffset=+1]
+include::_ug_security_configuring-isis-to-use-shiro.adoc[leveloffset=+1]
-include::_user-guide_security_shiro-ini-realm.adoc[leveloffset=+1]
+include::_ug_security_shiro-ini-realm.adoc[leveloffset=+1]
-include::_user-guide_security_shiro-isis-ldap-realm.adoc[leveloffset=+1]
+include::_ug_security_shiro-isis-ldap-realm.adoc[leveloffset=+1]
-include::_user-guide_security_shiro-isisaddons-security-module-realm.adoc[leveloffset=+1]
+include::_ug_security_shiro-isisaddons-security-module-realm.adoc[leveloffset=+1]
-include::_user-guide_security_shiro-jdbc-realm.adoc[leveloffset=+1]
+include::_ug_security_shiro-jdbc-realm.adoc[leveloffset=+1]
-include::_user-guide_security_shiro-isis-enhanced-wildcard-permission.adoc[leveloffset=+1]
+include::_ug_security_shiro-isis-enhanced-wildcard-permission.adoc[leveloffset=+1]
-include::_user-guide_security_configuring-isis-to-use-bypass.adoc[leveloffset=+1]
+include::_ug_security_configuring-isis-to-use-bypass.adoc[leveloffset=+1]
-include::_user-guide_security_api-for-applications.adoc[leveloffset=+1]
+include::_ug_security_api-for-applications.adoc[leveloffset=+1]
-include::_user-guide_security_usage-by-isis-viewers.adoc[leveloffset=+1]
+include::_ug_security_usage-by-isis-viewers.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/63697165/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
index 7acc994..fcc80c7 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing.adoc
@@ -8,9 +8,9 @@
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::_user-guide_testing_overview.adoc[leveloffset=+1]
-include::_user-guide_testing_unit-test-support.adoc[leveloffset=+1]
-include::_user-guide_testing_integ-test-support.adoc[leveloffset=+1]
-include::_user-guide_testing_bdd-spec-support.adoc[leveloffset=+1]
-include::_user-guide_testing_fixture-scripts.adoc[leveloffset=+1]
+include::_ug_testing_overview.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/63697165/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
index 68569c1..bb07e2f 100644
--- 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
@@ -12,10 +12,10 @@ There are many BDD tools out there; Apache Isis provides an integration with lin
-include::_user-guide_testing_bdd-spec-support_how-it-works.adoc[leveloffset=+1]
-include::_user-guide_testing_bdd-spec-support_key-classes.adoc[leveloffset=+1]
-include::_user-guide_testing_bdd-spec-support_writing-a-bdd-spec.adoc[leveloffset=+1]
-include::_user-guide_testing_bdd-spec-support_bdd-tooling.adoc[leveloffset=+1]
-include::_user-guide_testing_bdd-spec-support_maven-configuration.adoc[leveloffset=+1]
+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/63697165/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
index adba36a..c15e9c7 100644
--- 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
@@ -38,6 +38,6 @@ And if you can't write a fixture script for the story, it probably means that th
The following sections explain the API and how to go about using the API.
-include::_user-guide_testing_fixture-scripts_api-and-usage.adoc[leveloffset=+1]
-include::_user-guide_testing_fixture-scripts_sudo-service.adoc[leveloffset=+1]
+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/63697165/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
index f4d4cab..2501012 100644
--- 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
@@ -14,10 +14,10 @@ As discussed in the introductory overview of this chapter, Apache Isis allows yo
We'll get to all that shortly, but let's start by taking a look at what a typical integration test looks like.
-include::_user-guide_testing_integ-test-support_typical-usage.adoc[leveloffset=+1]
-include::_user-guide_testing_integ-test-support_bootstrapping.adoc[leveloffset=+1]
-include::_user-guide_testing_integ-test-support_wrapper-factory.adoc[leveloffset=+1]
-include::_user-guide_testing_integ-test-support_maven-configuration.adoc[leveloffset=+1]
+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/63697165/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
index 2f02863..9a59a70 100644
--- 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
@@ -6,7 +6,7 @@
Isis Core provides a number of unit test helpers for you to use (if you wish) to unit test your domain objects.
-include::_user-guide_testing_unit-test-support_contract-tests.adoc[leveloffset=+1]
-include::_user-guide_testing_unit-test-support_jmock-extensions.adoc[leveloffset=+1]
-include::_user-guide_testing_unit-test-support_maven-configuration.adoc[leveloffset=+1]
+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/63697165/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
index fd42f26..994a048 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_troubleshooting.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_troubleshooting.adoc
@@ -7,7 +7,7 @@ IMPORTANT: TODO
## Logging
-include::_user-guide_troubleshooting_enabling-logging.adoc[leveloffset=+1]
+include::_ug_troubleshooting_enabling-logging.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/63697165/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
index 3c5efb0..365059f 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_wicket-viewer.adoc
@@ -8,15 +8,15 @@ This chapter describes end-user features, configuration and customization of the
Note that extending the Wicket viewer is described in the <<Extending>> chapter.
-include::_user-guide_wicket-viewer_features.adoc[leveloffset=+1]
+include::_ug_wicket-viewer_features.adoc[leveloffset=+1]
-include::_user-guide_wicket-viewer_configuration_properties.adoc[leveloffset=+1]
+include::_ug_wicket-viewer_configuration_properties.adoc[leveloffset=+1]
-include::_user-guide_wicket-viewer_request-parameters.adoc[leveloffset=+1]
+include::_ug_wicket-viewer_request-parameters.adoc[leveloffset=+1]
-include::_user-guide_wicket-viewer_layout.adoc[leveloffset=+1]
+include::_ug_wicket-viewer_layout.adoc[leveloffset=+1]
-include::_user-guide_wicket-viewer_customisation.adoc[leveloffset=+1]
+include::_ug_wicket-viewer_customisation.adoc[leveloffset=+1]
@@ -25,5 +25,5 @@ include::_user-guide_wicket-viewer_customisation.adoc[leveloffset=+1]
APIs to extend the Wicket viewer are discussed in the <<_extending_the_wicket_viewer, Extending>> chapter.
-include::_user-guide_wicket-viewer_isis-addons.adoc[leveloffset=+1]
+include::_ug_wicket-viewer_isis-addons.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/63697165/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
index a5b4c6c..68ad239 100644
--- 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
@@ -8,11 +8,11 @@ In implementing the http://en.wikipedia.org/wiki/Naked_objects[naked objects pat
This section describes how this is done both for domain objects -- statically or dynamically -- and for the application menu bar (containing domain service' actions).
-include::_user-guide_wicket-viewer_layout_static-object-layout.adoc[leveloffset=+1]
+include::_ug_wicket-viewer_layout_static-object-layout.adoc[leveloffset=+1]
-include::_user-guide_wicket-viewer_layout_dynamic-object-layout.adoc[leveloffset=+1]
+include::_ug_wicket-viewer_layout_dynamic-object-layout.adoc[leveloffset=+1]
-include::_user-guide_wicket-viewer_layout_application-menu-layout.adoc[leveloffset=+1]
+include::_ug_wicket-viewer_layout_application-menu-layout.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/63697165/adocs/documentation/src/main/asciidoc/user-guide/user-guide.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/user-guide.adoc b/adocs/documentation/src/main/asciidoc/user-guide/user-guide.adoc
index 2aaa237..300bc2f 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/user-guide.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/user-guide.adoc
@@ -4,19 +4,19 @@
:_imagesdir: images/
:numbered:
-//include::_user-guide_core-concepts.adoc[leveloffset=+1]
-//include::_user-guide_getting-started.adoc[leveloffset=+1]
-//include::_user-guide_how-tos.adoc[leveloffset=+1]
-//include::_user-guide_more-advanced.adoc[leveloffset=+1]
-//include::_user-guide_reference.adoc[leveloffset=+1]
-//include::_user-guide_wicket-viewer.adoc[leveloffset=+1]
-//include::_user-guide_restfulobjects-viewer.adoc[leveloffset=+1]
-//include::_user-guide_security.adoc[leveloffset=+1]
-include::_user-guide_runtime.adoc[leveloffset=+1]
-//include::_user-guide_deployment.adoc[leveloffset=+1]
-include::_user-guide_testing.adoc[leveloffset=+1]
-//include::_user-guide_headless-access.adoc[leveloffset=+1]
-//include::_user-guide_isis-addons-modules.adoc[leveloffset=+1]
-//include::_user-guide_extending.adoc[leveloffset=+1]
-//include::_user-guide_troubleshooting.adoc[leveloffset=+1]
-//include::_user-guide_appendices.adoc[leveloffset=+1]
+//include::_ug_core-concepts.adoc[leveloffset=+1]
+//include::_ug_getting-started.adoc[leveloffset=+1]
+//include::_ug_how-tos.adoc[leveloffset=+1]
+//include::_ug_more-advanced.adoc[leveloffset=+1]
+//include::_ug_reference.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_deployment.adoc[leveloffset=+1]
+include::_ug_testing.adoc[leveloffset=+1]
+//include::_ug_headless-access.adoc[leveloffset=+1]
+//include::_ug_isis-addons-modules.adoc[leveloffset=+1]
+//include::_ug_extending.adoc[leveloffset=+1]
+//include::_ug_troubleshooting.adoc[leveloffset=+1]
+//include::_ug_appendices.adoc[leveloffset=+1]