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:57 UTC
[15/22] isis git commit: ISIS-1133: renamed _user-guide_ to _ug_
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]