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 2017/03/31 07:10:40 UTC

[04/51] [partial] isis git commit: ISIS-1521: reorganizes asciidoc documentation, moves into subdirs (both guides and other pages)

http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_createdLifecycleEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_createdLifecycleEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_createdLifecycleEvent.adoc
new file mode 100644
index 0000000..79e2a2c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_createdLifecycleEvent.adoc
@@ -0,0 +1,108 @@
+[[_rgant-DomainObject_createdLifecycleEvent]]
+= createdLifecycleEvent()
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+Whenever a domain object is instantiated or otherwise becomes known to the framework, a "created" lifecycle event is fired.  This is typically when the xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`]'s xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-creation-api[`newTransientInstance()`] is called;
+it will also happen if the object is simply instantiated with `new(...)`, and then the container's
+xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer_services-api[`injectServicesInto(...)`] method is called.
+
+Subscribers subscribe through the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] and can
+use the event to obtain a reference to the object just created.  The subscriber could then, for example, update the
+object, eg looking up state from some external datastore.
+
+
+By default the event raised is `ObjectCreatedEvent.Default`. For example:
+
+[source,java]
+----
+@DomainObject
+public class ToDoItemDto {
+    ...
+}
+----
+
+The purpose of the `createdLifecycleEvent()` attribute is to allows a custom subclass to be emitted instead.  A similar
+attribute is available for other lifecycle events.
+
+For example:
+
+[source,java]
+----
+@DomainObjectLayout(
+    createdLifecycleEvent=ToDoItem.CreatedEvent.class
+)
+public class ToDoItem {
+    public static class CreatedEvent
+        extends org.apache.isis.applib.services.eventbus.ObjectCreatedEvent<ToDoItem> { }
+    ...
+}
+----
+
+The benefit is that subscribers can be more targeted as to the events that they subscribe to.
+
+
+
+
+== Subscribers
+
+Subscribers (which must be domain services) subscribe using either the link:https://github.com/google/guava[Guava] API
+or (if the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] has been appropriately configured)
+using the link:http://www.axonframework.org/[Axon Framework] API.  The examples below use the Guava API.
+
+Subscribers can be either coarse-grained (if they subscribe to the top-level event type):
+
+[source,java]
+----
+@DomainService(nature=NatureOfService.DOMAIN)
+public class SomeSubscriber extends AbstractSubscriber {
+    @com.google.common.eventbus.Subscribe
+    public void on(ObjectCreatedEvent ev) {
+        if(ev.getSource() instanceof ToDoItem) { ... }
+    }
+}
+----
+
+or can be fine-grained (by subscribing to specific event subtypes):
+
+[source,java]
+----
+@DomainService(nature=NatureOfService.DOMAIN)
+public class SomeSubscriber extends AbstractSubscriber {
+    @com.google.common.eventbus.Subscribe
+    public void on(ToDoItem.ObjectCreatedEvent ev) {
+        ...
+    }
+}
+----
+
+
+[TIP]
+====
+If the AxonFramework is being used, replace `@com.google.common.eventbus.Subscribe` with `@org.axonframework.eventhandling.annotation.EventHandler`.
+====
+
+
+
+
+
+== Default, Doop and Noop events
+
+If the `createdLifecycleEvent` attribute is not explicitly specified (is left as its default value, `ObjectCreatedEvent.Default`),
+then the framework will, by default, post an event.
+
+If this is not required, then the `isis.reflector.facet.domainObjectAnnotation.createdLifecycleEvent.postForDefault`
+configuration property can be set to "false"; this will disable posting.
+
+On the other hand, if the `createdLifecycleEvent` has been explicitly specified to some subclass, then an event will be posted.
+The framework provides `ObjectCreatedEvent.Doop` as such a subclass, so setting the `createdLifecycleEvent` attribute to this class
+will ensure that the event to be posted, irrespective of the configuration property setting.
+
+And, conversely, the framework also provides `ObjectCreatedEvent.Noop`; if `createdLifecycleEvent` attribute is set to this class,
+then no event will be posted.
+
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_editing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_editing.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_editing.adoc
new file mode 100644
index 0000000..fd852eb
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_editing.adoc
@@ -0,0 +1,61 @@
+[[_rgant-DomainObject_editing]]
+= `editing()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+
+The `editing()` attribute determines whether a domain object's properties and collections are not editable (are read-only).
+
+The default is `AS_CONFIGURED`, meaning that the xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.objects.editing` is used to determine the whether the object is modifiable:
+
+* `true` +
++
+the object's properties and collections are modifiable.
+
+* `false` +
++
+the object's properties and collections are read-only, ie _not_ modifiable.
+
+If there is no configuration property in `isis.properties` then object are assumed to be modifiable.
+
+[TIP]
+====
+In other words, editing can be disabled globally for an application by setting:
+
+[source,ini]
+----
+isis.objects.editing=false
+----
+
+We recommend enabling this feature; it will help drive out the underlying business operations (processes and procedures) that require objects to change; these can then be captured as business actions.
+====
+
+The related `editingDisabledReason()` attribute specifies the a hard-coded reason why the object's properties and collections cannot be modified directly.
+
+
+
+This default can be overridden on an object-by-object basis; if `editing()` is set to `ENABLED` then the object's properties and collections are editable irrespective of the configured value; if set to `DISABLED` then the object's properties and collections are not editable irrespective of the configured value.
+
+For example:
+
+[source,java]
+----
+@DomainObject(
+    editing=Editing.DISABLED,
+    editingDisabledReason="Reference data, so cannot be modified"
+)
+public class Country {
+    ...
+}
+----
+
+[TIP]
+====
+Another interesting example of immutable reference data is to define an entity to represent individual dates; after all, for a system with an expected lifetime of 20 years that equates to only 7,300 days, a comparatively tiny number of rows to hold in a database.
+====
+
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_loadedLifecycleEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_loadedLifecycleEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_loadedLifecycleEvent.adoc
new file mode 100644
index 0000000..f83a82c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_loadedLifecycleEvent.adoc
@@ -0,0 +1,105 @@
+[[_rgant-DomainObject_loadedLifecycleEvent]]
+= loadedLifecycleEvent()
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+Whenever a persistent domain object is loaded from the database, a "loaded" lifecycle event is fired.
+
+Subscribers subscribe through the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] and can
+use the event to obtain a reference to the domain object just loaded.  The subscriber could then, for example, update
+or default values on the object (eg to support on-the-fly migration scenarios).
+
+By default the event raised is `ObjectLoadedEvent.Default`. For example:
+
+[source,java]
+----
+@DomainObject
+public class ToDoItemDto {
+    ...
+}
+----
+
+The purpose of the `loadedLifecycleEvent()` attribute is to allows a custom subclass to be emitted instead.  A similar
+attribute is available for other lifecycle events.
+
+For example:
+
+[source,java]
+----
+@DomainObjectLayout(
+    loadedLifecycleEvent=ToDoItem.LoadedEvent.class
+)
+public class ToDoItem {
+    public static class LoadedEvent
+        extends org.apache.isis.applib.services.eventbus.ObjectLoadedEvent<ToDoItem> { }
+    ...
+}
+----
+
+The benefit is that subscribers can be more targeted as to the events that they subscribe to.
+
+
+
+
+== Subscribers
+
+Subscribers (which must be domain services) subscribe using either the link:https://github.com/google/guava[Guava] API
+or (if the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] has been appropriately configured)
+using the link:http://www.axonframework.org/[Axon Framework] API.  The examples below use the Guava API.
+
+Subscribers can be either coarse-grained (if they subscribe to the top-level event type):
+
+[source,java]
+----
+@DomainService(nature=NatureOfService.DOMAIN)
+public class SomeSubscriber extends AbstractSubscriber {
+    @com.google.common.eventbus.Subscribe
+    public void on(ObjectLoadedEvent ev) {
+        if(ev.getSource() instanceof ToDoItem) { ... }
+    }
+}
+----
+
+or can be fine-grained (by subscribing to specific event subtypes):
+
+[source,java]
+----
+@DomainService(nature=NatureOfService.DOMAIN)
+public class SomeSubscriber extends AbstractSubscriber {
+    @com.google.common.eventbus.Subscribe
+    public void on(ToDoItem.ObjectLoadedEvent ev) {
+        ...
+    }
+}
+----
+
+
+[TIP]
+====
+If the AxonFramework is being used, replace `@com.google.common.eventbus.Subscribe` with `@org.axonframework.eventhandling.annotation.EventHandler`.
+====
+
+
+
+
+
+== Default, Doop and Noop events
+
+If the `loadedLifecycleEvent` attribute is not explicitly specified (is left as its default value, `ObjectLoadedEvent.Default`),
+then the framework will, by default, post an event.
+
+If this is not required, then the `isis.reflector.facet.domainObjectAnnotation.loadedLifecycleEvent.postForDefault`
+configuration property can be set to "false"; this will disable posting.
+
+On the other hand, if the `loadedLifecycleEvent` has been explicitly specified to some subclass, then an event will be posted.
+The framework provides `ObjectLoadedEvent.Doop` as such a subclass, so setting the `loadedLifecycleEvent` attribute to this class
+will ensure that the event to be posted, irrespective of the configuration property setting.
+
+And, conversely, the framework also provides `ObjectLoadedEvent.Noop`; if `loadedLifecycleEvent` attribute is set to this class,
+then no event will be posted.
+
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_mixinMethod.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_mixinMethod.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_mixinMethod.adoc
new file mode 100644
index 0000000..edf94ca
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_mixinMethod.adoc
@@ -0,0 +1,40 @@
+[[_rgant-DomainObject_mixinMethod]]
+= `mixinMethod()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+
+The `mixinMethod()` attribute specifies the name of the method to be treated as a "reserved" method name, meaning that the mixin's name should instead be inferred from the mixin's type.
+
+For example:
+
+[source,java]
+----
+@DomainObject
+public class Customer {
+
+    @DomainObject(nature=Nature.MIXIN, mixinMethod="execute")
+    public static class placeOrder {
+
+        Customer customer;
+        public placeOrder(Customer customer) { this.customer = customer; }
+
+        public Customer execute(Product p, int quantity) { ... }
+        public String disableExecute() { ... }
+        public String validate0Execute() { ... }
+    }
+    ...
+)
+----
+
+This allows all mixins to follow a similar convention, with the name of the mixin inferred entirely from its type ("placeOrder").
+
+When invoked programmatically, the code reads:
+
+[source,java]
+----
+mixin(Customer.placeOrder.class, someCustomer).execute(someProduct, 3);
+----
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_nature.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_nature.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_nature.adoc
new file mode 100644
index 0000000..755bbec
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_nature.adoc
@@ -0,0 +1,66 @@
+[[_rgant-DomainObject_nature]]
+= `nature()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+
+The `nature()` attribute is used to characterize the domain object as either an entity (part of the domain layer) or as a view model (part of the application layer).  If the domain object should be thought of as an entity, it also captures how the persistence of that entity is managed.
+
+For example:
+
+[source,java]
+----
+@DomainObject(nature=Nature.VIEW_MODEL)
+public class PieChartAnalysis {
+    ...
+}
+----
+
+Specifically, the nature must be one of:
+
+* `NOT_SPECIFIED,` +
++
+(the default); specifies no paricular semantics for the domain class.
+
+* `JDO_ENTITY` +
++
+indicates that the domain object is an entity whose persistence is managed internally by Apache Isis, using the JDO/DataNucleus objectstore.
+
+* `EXTERNAL_ENTITY` +
++
+indicates that the domain objecct is a wrapper/proxy/stub (choose your term) to an entity that is managed by some related external system.  For example, the domain object may hold just the URI to a RESTful resource of some third party REST service, or the id of some system accessible over SOAP. +
++
+The identity of an external entity is determined solely by the state of entity's properties.  The framework will automatically recreate the domain object each time it is interacted with.
+
+* `INMEMORY_ENTITY` +
++
+indicates that the domain object is a wrapper/proxy/stub to a "synthetic" entity, for example one that is constructed from some sort of internal memory data structure. +
++
+The identity of an inmemory entity is determined solely by the state of entity's properties.  The framework will automatically recreate the domain object each time it is interacted with.
+
+* `MIXIN` +
++
+indicates that the domain object is part of the domain layer, and is contributing behaviour to objects of some other type as a mixin (also known as a trait).
+
+Equivalent to annotating with xref:rgant.adoc#_rgant-Mixin[`@Mixin`].  For further discussion on using mixins, see xref:ugbtb.adoc#_ugbtb_decoupling_mixins[mixins] in the user guide.
+
+
+* `VIEW_MODEL` +
++
+indicates that the domain object is conceptually part of the application layer, and exists to surfaces behaviour and/or state that is aggregate of one or more domain entities.
+
+The identity of an inmemory entity is determined solely by the state of entity's properties.  The framework will automatically recreate the domain object each time it is interacted with.
+
+Those natures that indicate the domain object is an entity (of some sort or another) mean then that the domain object is considered to be part of the domain model layer.  As such the domain object's class cannot be annotated with xref:rgant.adoc#_rgant-ViewModel[`@ViewModel`] or implement the xref:rgcms.adoc#_rgcms_classes_super_ViewModel[`ViewModel`] interface.
+
+
+[NOTE]
+====
+Under the covers Apache Isis' support for `VIEW_MODEL`, `EXTERNAL_ENTITY` and `INMEMORY_ENTITY` domain objects is identical; the state of the object is encoded into its internal OID (represented ultimately as its URL), and is recreated directly from that URL.
+
+Because this particular implementation was originally added to Apache Isis in support of view models, the term was also used for the logically different external entities and inmemory entities.
+
+The benefit of `nature()` is that it allows the developer to properly characterize the layer (domain vs application) that an entity lives, thus avoiding confusion as "view model" (the implementation technique) and "view model" (the application layer concept).
+====

http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_objectType.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_objectType.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_objectType.adoc
new file mode 100644
index 0000000..14fa17a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_objectType.adoc
@@ -0,0 +1,64 @@
+[[_rgant-DomainObject_objectType]]
+= `objectType()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+The `objectType()` attribute is used to provide a unique alias for the object's class name.
+
+This value is used internally to generate a string representation of an objects identity (the `Oid`).
+This can appear in several contexts, including:
+
+* as the value of `Bookmark#getObjectType()` and in the `toString()` value of `Bookmark`
+ (see xref:rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`])
+ ** and thus in the "table-of-two-halves" pattern, as per (non-ASF) http://github.com/isisaddons/isis-module-poly[Isis addons' poly] module
+* in the serialization of `OidDto` in the xref:rgcms.adoc#_rgcms_schema-cmd[command] and xref:rgcms.adoc#_rgcms_schema-ixn[interaction] schemas
+* in the URLs of the xref:ugvro.adoc#[RestfulObjects viewer]
+* in the URLs of the xref:ugvw.adoc#[Wicket viewer] (in general and in particular if xref:ugvw.adoc#_ugvw_features_hints-and-copy-url[copying URLs])
+* in XML snapshots generated by the xref:rgsvc.adoc#_rgsvc_api_XmlSnapshotService[`XmlSnapshotService`]
+
+
+
+== Examples
+
+For example:
+
+[source,java]
+----
+@DomainObject(
+    objectType="orders.Order"
+)
+public class Order {
+    ...
+}
+----
+
+
+== Precedence
+
+The rules of precedence are:
+
+1. xref:rgant.adoc#_rgant_Discriminator[`@Discriminator`]
+2. `@DomainObject#objectType`, or xref:rgant.adoc#_rgant_aaa_deprecated[`@ObjectType`] (deprecated)
+3. xref:rgant.adoc#_rgant_PersistenceCapable[`@PersistenceCapable`], if at least the `schema` attribute is defined.  +
++
+If both `schema` and `table` are defined, then the value is "`schema.table`".
+If only `schema` is defined, then the value is "`schema.className`".
+
+4. Fully qualified class name of the entity.
+
+
+[TIP]
+====
+This might be obvious, but to make explicit: we recommend that you always specify an object type for your domain objects.
+
+Otherwise, if you refactor your code (change class name or move package), then any externally held references to the OID of the object will break.
+At best this will require a data migration in the database; at worst it could cause external clients accessing data through the xref:ugvro.adoc#[Restful Objects] viewer to break.
+====
+
+[NOTE]
+====
+If the object type is not unique across all domain classes then the framework will fail-fast and fail to boot.
+An error message will be printed in the log to help you determine which classes have duplicate object tyoes.
+====

http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_persistedLifecycleEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_persistedLifecycleEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_persistedLifecycleEvent.adoc
new file mode 100644
index 0000000..cf34e34
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_persistedLifecycleEvent.adoc
@@ -0,0 +1,111 @@
+[[_rgant-DomainObject_persistedLifecycleEvent]]
+= persistedLifecycleEvent()
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+Whenever a (just created, still transient) domain object has been saved (INSERTed in)to the database, a "persisted" lifecycle
+event is fired.
+
+Subscribers subscribe through the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] and can
+use the event to obtain a reference to the domain object.  The subscriber could then, for example, maintain an
+external datastore.
+
+[WARNING]
+====
+The object should _not_ be modified during the persisted callback.
+====
+
+By default the event raised is `ObjectPersistedEvent.Default`. For example:
+
+[source,java]
+----
+@DomainObject
+public class ToDoItemDto {
+    ...
+}
+----
+
+The purpose of the `persistedLifecycleEvent()` attribute is to allows a custom subclass to be emitted instead.  A similar
+attribute is available for other lifecycle events.
+
+For example:
+
+[source,java]
+----
+@DomainObjectLayout(
+    persistedLifecycleEvent=ToDoItem.PersistedEvent.class
+)
+public class ToDoItem {
+    public static class PersistedEvent
+        extends org.apache.isis.applib.services.eventbus.ObjectPersistedEvent<ToDoItem> { }
+    ...
+}
+----
+
+The benefit is that subscribers can be more targeted as to the events that they subscribe to.
+
+
+
+
+== Subscribers
+
+Subscribers (which must be domain services) subscribe using either the link:https://github.com/google/guava[Guava] API
+or (if the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] has been appropriately configured)
+using the link:http://www.axonframework.org/[Axon Framework] API.  The examples below use the Guava API.
+
+Subscribers can be either coarse-grained (if they subscribe to the top-level event type):
+
+[source,java]
+----
+@DomainService(nature=NatureOfService.DOMAIN)
+public class SomeSubscriber extends AbstractSubscriber {
+    @com.google.common.eventbus.Subscribe
+    public void on(ObjectPersistedEvent ev) {
+        if(ev.getSource() instanceof ToDoItem) { ... }
+    }
+}
+----
+
+or can be fine-grained (by subscribing to specific event subtypes):
+
+[source,java]
+----
+@DomainService(nature=NatureOfService.DOMAIN)
+public class SomeSubscriber extends AbstractSubscriber {
+    @com.google.common.eventbus.Subscribe
+    public void on(ToDoItem.ObjectPersistedEvent ev) {
+        ...
+    }
+}
+----
+
+
+[TIP]
+====
+If the AxonFramework is being used, replace `@com.google.common.eventbus.Subscribe` with `@org.axonframework.eventhandling.annotation.EventHandler`.
+====
+
+
+
+
+
+== Default, Doop and Noop events
+
+If the `persistedLifecycleEvent` attribute is not explicitly specified (is left as its default value, `ObjectPersistedEvent.Default`),
+then the framework will, by default, post an event.
+
+If this is not required, then the `isis.reflector.facet.domainObjectAnnotation.persistedLifecycleEvent.postForDefault`
+configuration property can be set to "false"; this will disable posting.
+
+On the other hand, if the `persistedLifecycleEvent` has been explicitly specified to some subclass, then an event will be posted.
+The framework provides `ObjectPersistedEvent.Doop` as such a subclass, so setting the `persistedLifecycleEvent` attribute to this class
+will ensure that the event to be posted, irrespective of the configuration property setting.
+
+And, conversely, the framework also provides `ObjectPersistedEvent.Noop`; if `persistedLifecycleEvent` attribute is set to this class,
+then no event will be posted.
+
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_persistingLifecycleEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_persistingLifecycleEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_persistingLifecycleEvent.adoc
new file mode 100644
index 0000000..ae1f54a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_persistingLifecycleEvent.adoc
@@ -0,0 +1,114 @@
+[[_rgant-DomainObject_persistingLifecycleEvent]]
+= persistingLifecycleEvent()
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+Whenever a (just created, still transient) domain object is about to be saved (INSERTed in)to the database, a "persisting" lifecycle
+event is fired.
+
+Subscribers subscribe through the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] and can
+use the event to obtain a reference to the domain object.  The subscriber could then, for example, update the object,
+or it could use it maintain an external datastore.  One possible application is to maintain a full-text search database using
+link:https://lucene.apache.org/[Apache Lucene] or similar.
+
+[NOTE]
+====
+Another use case is to maintain "last updated by"/"last updated at" properties.  While you can roll your own, note that
+the framework provides built-in support for this use case through the
+xref:rgcms.adoc#_rgcms_classes_roles_Timestampable[`Timestampable`] role interface.
+====
+
+By default the event raised is `ObjectPersistingEvent.Default`. For example:
+
+[source,java]
+----
+@DomainObject
+public class ToDoItemDto {
+    ...
+}
+----
+
+The purpose of the `persistingLifecycleEvent()` attribute is to allows a custom subclass to be emitted instead.  A similar
+attribute is available for other lifecycle events.
+
+For example:
+
+[source,java]
+----
+@DomainObjectLayout(
+    persistingLifecycleEvent=ToDoItem.PersistingEvent.class
+)
+public class ToDoItem {
+    public static class PersistingEvent
+        extends org.apache.isis.applib.services.eventbus.ObjectPersistingEvent<ToDoItem> { }
+    ...
+}
+----
+
+The benefit is that subscribers can be more targeted as to the events that they subscribe to.
+
+
+
+
+== Subscribers
+
+Subscribers (which must be domain services) subscribe using either the link:https://github.com/google/guava[Guava] API
+or (if the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] has been appropriately configured)
+using the link:http://www.axonframework.org/[Axon Framework] API.  The examples below use the Guava API.
+
+Subscribers can be either coarse-grained (if they subscribe to the top-level event type):
+
+[source,java]
+----
+@DomainService(nature=NatureOfService.DOMAIN)
+public class SomeSubscriber extends AbstractSubscriber {
+    @com.google.common.eventbus.Subscribe
+    public void on(ObjectPersistingEvent ev) {
+        if(ev.getSource() instanceof ToDoItem) { ... }
+    }
+}
+----
+
+or can be fine-grained (by subscribing to specific event subtypes):
+
+[source,java]
+----
+@DomainService(nature=NatureOfService.DOMAIN)
+public class SomeSubscriber extends AbstractSubscriber {
+    @com.google.common.eventbus.Subscribe
+    public void on(ToDoItem.ObjectPersistingEvent ev) {
+        ...
+    }
+}
+----
+
+
+[TIP]
+====
+If the AxonFramework is being used, replace `@com.google.common.eventbus.Subscribe` with `@org.axonframework.eventhandling.annotation.EventHandler`.
+====
+
+
+
+
+
+== Default, Doop and Noop events
+
+If the `persistingLifecycleEvent` attribute is not explicitly specified (is left as its default value, `ObjectPersistingEvent.Default`),
+then the framework will, by default, post an event.
+
+If this is not required, then the `isis.reflector.facet.domainObjectAnnotation.persistingLifecycleEvent.postForDefault`
+configuration property can be set to "false"; this will disable posting.
+
+On the other hand, if the `persistingLifecycleEvent` has been explicitly specified to some subclass, then an event will be posted.
+The framework provides `ObjectPersistingEvent.Doop` as such a subclass, so setting the `persistingLifecycleEvent` attribute to this class
+will ensure that the event to be posted, irrespective of the configuration property setting.
+
+And, conversely, the framework also provides `ObjectPersistingEvent.Noop`; if `persistingLifecycleEvent` attribute is set to this class,
+then no event will be posted.
+
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_publishing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_publishing.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_publishing.adoc
new file mode 100644
index 0000000..173f5d5
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_publishing.adoc
@@ -0,0 +1,63 @@
+[[_rgant-DomainObject_publishing]]
+= `publishing()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+
+The `publishing()` attribute determines whether and how a modified object instance is published via the registered
+implementation of a xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`]) or
+xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`].  This attribute is also supported
+for xref:rgant.adoc#_rgant-Action_publishing[actions], where it controls whether action invocations are published as
+events, and for xref:rgant.adoc#_rgant_Property_publishing[`@Property#publishing()`], where it controls whether
+property edits are published as events.
+
+A common use case is to notify external "downstream" systems of changes in the state of the Isis application.
+
+The default value for the attribute is `AS_CONFIGURED`, meaning that the xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.services.publish.objects` is used to determine the whether the action is published:
+
+* `all` +
++
+all changed objects are published
+
+* `none` +
++
+no changed objects are published
+
+If there is no configuration property in `isis.properties` then publishing is automatically enabled for domain objects.
+
+This default can be overridden on an object-by-object basis; if `publishing()` is set to `ENABLED` then changed instances of the domain class are published irrespective of the configured value; if set to `DISABLED` then the changed instances are _not_ published, again irrespective of the configured value.
+
+For example:
+
+[source,java]
+----
+@DomainObject(
+    publishing=Publishing.ENABLED  // <1>
+)
+public class InterestRate {
+    ...
+}
+----
+<1> because set to enabled, will be published irrespective of the configured value.
+
+
+
+
+== `publishingPayloadFactory()`
+
+The (optional) related `publishingPayloadFactory()` specifies the class to use to create the (payload of the) event to
+be published by the publishing factory.
+
+Rather than simply broadcast that the object was changed, the payload factory allows a "fatter" payload to be
+instantiated that can eagerly push commonly-required information to all subscribers. For at least some subscribers
+this should avoid the necessity to query back for additional information.
+
+
+[WARNING]
+====
+Be aware that this attribute is only honoured by the (deprecated)
+xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`], so should itself be considered as deprecated.  It
+is ignored by the replacement xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`],
+====

http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_removingLifecycleEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_removingLifecycleEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_removingLifecycleEvent.adoc
new file mode 100644
index 0000000..190725a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_removingLifecycleEvent.adoc
@@ -0,0 +1,114 @@
+[[_rgant-DomainObject_removingLifecycleEvent]]
+= removingLifecycleEvent()
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+Whenever a (persistent) domain object is about to be removed (DELETEd) from the database, a "removing"
+lifecycle event is fired.
+
+Subscribers subscribe through the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] and can
+use the event to obtain a reference to the domain object.  The subscriber could then, for example, could use it
+maintain an external datastore.  One possible application is to maintain a full-text search database
+using link:https://lucene.apache.org/[Apache Lucene] or similar.
+
+[NOTE]
+====
+Another use case is to maintain "last updated by"/"last updated at" properties.  While you can roll your own, note that
+the framework provides built-in support for this use case through the
+xref:rgcms.adoc#_rgcms_classes_roles_Timestampable[`Timestampable`] role interface.
+====
+
+By default the event raised is `ObjectRemovingEvent.Default`. For example:
+
+[source,java]
+----
+@DomainObject
+public class ToDoItemDto {
+    ...
+}
+----
+
+The purpose of the `removingLifecycleEvent()` attribute is to allows a custom subclass to be emitted instead.  A similar
+attribute is available for other lifecycle events.
+
+For example:
+
+[source,java]
+----
+@DomainObjectLayout(
+    removingLifecycleEvent=ToDoItem.RemovingEvent.class
+)
+public class ToDoItem {
+    public static class RemovingEvent
+        extends org.apache.isis.applib.services.eventbus.ObjectRemovingEvent<ToDoItem> { }
+    ...
+}
+----
+
+The benefit is that subscribers can be more targeted as to the events that they subscribe to.
+
+
+
+
+== Subscribers
+
+Subscribers (which must be domain services) subscribe using either the link:https://github.com/google/guava[Guava] API
+or (if the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] has been appropriately configured)
+using the link:http://www.axonframework.org/[Axon Framework] API.  The examples below use the Guava API.
+
+Subscribers can be either coarse-grained (if they subscribe to the top-level event type):
+
+[source,java]
+----
+@DomainService(nature=NatureOfService.DOMAIN)
+public class SomeSubscriber extends AbstractSubscriber {
+    @com.google.common.eventbus.Subscribe
+    public void on(ObjectRemovingEvent ev) {
+        if(ev.getSource() instanceof ToDoItem) { ... }
+    }
+}
+----
+
+or can be fine-grained (by subscribing to specific event subtypes):
+
+[source,java]
+----
+@DomainService(nature=NatureOfService.DOMAIN)
+public class SomeSubscriber extends AbstractSubscriber {
+    @com.google.common.eventbus.Subscribe
+    public void on(ToDoItem.ObjectRemovingEvent ev) {
+        ...
+    }
+}
+----
+
+
+[TIP]
+====
+If the AxonFramework is being used, replace `@com.google.common.eventbus.Subscribe` with `@org.axonframework.eventhandling.annotation.EventHandler`.
+====
+
+
+
+
+
+== Default, Doop and Noop events
+
+If the `removingLifecycleEvent` attribute is not explicitly specified (is left as its default value, `ObjectRemovingEvent.Default`),
+then the framework will, by default, post an event.
+
+If this is not required, then the `isis.reflector.facet.domainObjectAnnotation.removingLifecycleEvent.postForDefault`
+configuration property can be set to "false"; this will disable posting.
+
+On the other hand, if the `removingLifecycleEvent` has been explicitly specified to some subclass, then an event will be posted.
+The framework provides `ObjectRemovingEvent.Doop` as such a subclass, so setting the `removingLifecycleEvent` attribute to this class
+will ensure that the event to be posted, irrespective of the configuration property setting.
+
+And, conversely, the framework also provides `ObjectRemovingEvent.Noop`; if `removingLifecycleEvent` attribute is set to this class,
+then no event will be posted.
+
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_updatedLifecycleEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_updatedLifecycleEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_updatedLifecycleEvent.adoc
new file mode 100644
index 0000000..da3845b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_updatedLifecycleEvent.adoc
@@ -0,0 +1,110 @@
+[[_rgant-DomainObject_updatedLifecycleEvent]]
+= updatedLifecycleEvent()
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+Whenever a (persistent) domain object has been modified and has been updated in the database, an "updated" lifecycle
+event is fired.
+
+Subscribers subscribe through the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] and can
+use the event to obtain a reference to the domain object.
+
+[WARNING]
+====
+The object should _not_ be modified during the updated callback.
+====
+
+By default the event raised is `ObjectUpdatedEvent.Default`. For example:
+
+[source,java]
+----
+@DomainObject
+public class ToDoItemDto {
+    ...
+}
+----
+
+The purpose of the `updatedLifecycleEvent()` attribute is to allows a custom subclass to be emitted instead.  A similar
+attribute is available for other lifecycle events.
+
+For example:
+
+[source,java]
+----
+@DomainObjectLayout(
+    updatedLifecycleEvent=ToDoItem.UpdatedEvent.class
+)
+public class ToDoItem {
+    public static class UpdatedEvent
+        extends org.apache.isis.applib.services.eventbus.ObjectUpdatedEvent<ToDoItem> { }
+    ...
+}
+----
+
+The benefit is that subscribers can be more targeted as to the events that they subscribe to.
+
+
+
+
+== Subscribers
+
+Subscribers (which must be domain services) subscribe using either the link:https://github.com/google/guava[Guava] API
+or (if the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] has been appropriately configured)
+using the link:http://www.axonframework.org/[Axon Framework] API.  The examples below use the Guava API.
+
+Subscribers can be either coarse-grained (if they subscribe to the top-level event type):
+
+[source,java]
+----
+@DomainService(nature=NatureOfService.DOMAIN)
+public class SomeSubscriber extends AbstractSubscriber {
+    @com.google.common.eventbus.Subscribe
+    public void on(ObjectUpdatedEvent ev) {
+        if(ev.getSource() instanceof ToDoItem) { ... }
+    }
+}
+----
+
+or can be fine-grained (by subscribing to specific event subtypes):
+
+[source,java]
+----
+@DomainService(nature=NatureOfService.DOMAIN)
+public class SomeSubscriber extends AbstractSubscriber {
+    @com.google.common.eventbus.Subscribe
+    public void on(ToDoItem.ObjectUpdatedEvent ev) {
+        ...
+    }
+}
+----
+
+
+[TIP]
+====
+If the AxonFramework is being used, replace `@com.google.common.eventbus.Subscribe` with `@org.axonframework.eventhandling.annotation.EventHandler`.
+====
+
+
+
+
+
+== Default, Doop and Noop events
+
+If the `updatedLifecycleEvent` attribute is not explicitly specified (is left as its default value, `ObjectUpdatedEvent.Default`),
+then the framework will, by default, post an event.
+
+If this is not required, then the `isis.reflector.facet.domainObjectAnnotation.updatedLifecycleEvent.postForDefault`
+configuration property can be set to "false"; this will disable posting.
+
+On the other hand, if the `updatedLifecycleEvent` has been explicitly specified to some subclass, then an event will be posted.
+The framework provides `ObjectUpdatedEvent.Doop` as such a subclass, so setting the `updatedLifecycleEvent` attribute to this class
+will ensure that the event to be posted, irrespective of the configuration property setting.
+
+And, conversely, the framework also provides `ObjectUpdatedEvent.Noop`; if `updatedLifecycleEvent` attribute is set to this class,
+then no event will be posted.
+
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_updatingLifecycleEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_updatingLifecycleEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_updatingLifecycleEvent.adoc
new file mode 100644
index 0000000..af5d2fb
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_updatingLifecycleEvent.adoc
@@ -0,0 +1,114 @@
+[[_rgant-DomainObject_updatingLifecycleEvent]]
+= updatingLifecycleEvent()
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+Whenever a (persistent) domain object has been modified and is about to be updated to the database, an "updating"
+lifecycle event is fired.
+
+Subscribers subscribe through the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] and can
+use the event to obtain a reference to the domain object.  The subscriber could then, for example, update the object,
+or it could use it maintain an external datastore.  One possible application is to maintain a full-text search database
+using link:https://lucene.apache.org/[Apache Lucene] or similar.
+
+[NOTE]
+====
+Another use case is to maintain "last updated by"/"last updated at" properties.  While you can roll your own, note that
+the framework provides built-in support for this use case through the
+xref:rgcms.adoc#_rgcms_classes_roles_Timestampable[`Timestampable`] role interface.
+====
+
+By default the event raised is `ObjectUpdatingEvent.Default`. For example:
+
+[source,java]
+----
+@DomainObject
+public class ToDoItemDto {
+    ...
+}
+----
+
+The purpose of the `updatingLifecycleEvent()` attribute is to allows a custom subclass to be emitted instead.  A similar
+attribute is available for other lifecycle events.
+
+For example:
+
+[source,java]
+----
+@DomainObjectLayout(
+    updatingLifecycleEvent=ToDoItem.UpdatingEvent.class
+)
+public class ToDoItem {
+    public static class UpdatingEvent
+        extends org.apache.isis.applib.services.eventbus.ObjectUpdatingEvent<ToDoItem> { }
+    ...
+}
+----
+
+The benefit is that subscribers can be more targeted as to the events that they subscribe to.
+
+
+
+
+== Subscribers
+
+Subscribers (which must be domain services) subscribe using either the link:https://github.com/google/guava[Guava] API
+or (if the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] has been appropriately configured)
+using the link:http://www.axonframework.org/[Axon Framework] API.  The examples below use the Guava API.
+
+Subscribers can be either coarse-grained (if they subscribe to the top-level event type):
+
+[source,java]
+----
+@DomainService(nature=NatureOfService.DOMAIN)
+public class SomeSubscriber extends AbstractSubscriber {
+    @com.google.common.eventbus.Subscribe
+    public void on(ObjectUpdatingEvent ev) {
+        if(ev.getSource() instanceof ToDoItem) { ... }
+    }
+}
+----
+
+or can be fine-grained (by subscribing to specific event subtypes):
+
+[source,java]
+----
+@DomainService(nature=NatureOfService.DOMAIN)
+public class SomeSubscriber extends AbstractSubscriber {
+    @com.google.common.eventbus.Subscribe
+    public void on(ToDoItem.ObjectUpdatingEvent ev) {
+        ...
+    }
+}
+----
+
+
+[TIP]
+====
+If the AxonFramework is being used, replace `@com.google.common.eventbus.Subscribe` with `@org.axonframework.eventhandling.annotation.EventHandler`.
+====
+
+
+
+
+
+== Default, Doop and Noop events
+
+If the `updatingLifecycleEvent` attribute is not explicitly specified (is left as its default value, `ObjectUpdatingEvent.Default`),
+then the framework will, by default, post an event.
+
+If this is not required, then the `isis.reflector.facet.domainObjectAnnotation.updatingLifecycleEvent.postForDefault`
+configuration property can be set to "false"; this will disable posting.
+
+On the other hand, if the `updatingLifecycleEvent` has been explicitly specified to some subclass, then an event will be posted.
+The framework provides `ObjectUpdatingEvent.Doop` as such a subclass, so setting the `updatingLifecycleEvent` attribute to this class
+will ensure that the event to be posted, irrespective of the configuration property setting.
+
+And, conversely, the framework also provides `ObjectUpdatingEvent.Noop`; if `updatingLifecycleEvent` attribute is set to this class,
+then no event will be posted.
+
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainService.adoc
new file mode 100644
index 0000000..1b00e29
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainService.adoc
@@ -0,0 +1,72 @@
+[[_rgant-DomainService]]
+= `@DomainService`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+
+The `@DomainService` annotation indicates that the (concrete) class should be automatically instantiated as a domain service.
+
+Domain services with this annotation do NOT need to be registered explicitly in `isis.properties`; they will be
+discovered automatically on the CLASSPATH.
+
+The table below summarizes the annotation's attributes.
+
+.`@DomainService` attributes
+[cols="2,2,4a", options="header"]
+|===
+
+| Attribute
+| Values (default)
+| Description
+
+
+|xref:rgant.adoc#_rgant-DomainService_nature[`nature()`]
+|`VIEW`, `VIEW_MENU_ONLY`, `VIEW_CONTRIBUTIONS_ONLY`, `VIEW_REST_ONLY`, `DOMAIN` (`VIEW`)
+|the nature of this service: providing actions for menus, or as contributed actions, or for the xref:ugvro.adoc#[RestfulObjects REST API], or neither
+
+
+|xref:rgant.adoc#_rgant-DomainService_objectType[`objectType()`]
+|
+|equivalent to xref:rgant.adoc#_rgant_DomainObject_objectType[`@DomainObject#objectType()`], specifies the objectType of the service.
+
+The instanceId for services is always "1".
+
+
+|xref:rgant.adoc#_rgant-DomainService_repositoryFor[`repositoryFor()`]
+|
+|if this domain service acts as a repository for an entity type, specify that entity type.  This is used to determine an icon to use for the service (eg as shown in action prompts).
+
+
+|`menuOrder()`
+|
+|Deprecated in 1.8.0; use instead xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`]
+
+|===
+
+
+
+For example:
+
+[source,java]
+----
+@DomainService(
+    nature=NatureOfService.DOMAIN,
+    repositoryFor=Loan.class
+)
+public class LoanRepository {
+    @Programmatic
+    public List<Loan> findLoansFor(Borrower borrower) { ... }
+}
+----
+
+
+
+include::_rgant-DomainService_nature.adoc[leveloffset=+1]
+include::_rgant-DomainService_objectType.adoc[leveloffset=+1]
+include::_rgant-DomainService_repositoryFor.adoc[leveloffset=+1]
+
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainServiceLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainServiceLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainServiceLayout.adoc
new file mode 100644
index 0000000..e034dea
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainServiceLayout.adoc
@@ -0,0 +1,78 @@
+[[_rgant-DomainServiceLayout]]
+= `@DomainServiceLayout`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+
+The `@DomainServiceLayout` annotation applies to domain services, collecting together all view layout semantics within a single annotation.
+
+[TIP]
+====
+You will also find some additional material in the xref:ugfun.adoc#_ugfun_object-layout_application-menu[object layout] chapter.
+====
+
+
+The table below summarizes the annotation's attributes.
+
+.`@DomainServiceLayout` attributes
+[cols="2,2,4a", options="header"]
+|===
+
+| Attribute
+| Values (default)
+| Description
+
+
+|xref:rgant.adoc#_rgant-DomainServiceLayout_menuBar[`menuBar()`]
+|`PRIMARY`, `SECONDARY`, `TERTIARY` (`PRIMARY`).
+|the menubar in which the menu that holds this service's actions should reside.
+
+
+|xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`menuOrder()`]
+|
+|the order of the service's menu with respect to other service's.
+
+
+|xref:rgant.adoc#_rgant-DomainServiceLayout_named[`named()`]
+|string, eg "Customers"
+|name of this class (overriding the name derived from its name in code)
+
+
+
+|===
+
+
+
+For example:
+
+[source,java]
+----
+@DomainService
+@DomainServiceLayout(
+    menuBar=MenuBar.PRIMARY,
+    menuOrder="100",
+    named="ToDos"
+)
+public class ToDoItems {
+    ...
+}
+----
+
+
+
+[NOTE]
+====
+Note that there is (currently) no support for specifying UI hints for domain services through the dynamic xref:ugfun.adoc#_ugfun_object-layout_dynamic[`.layout.json`] file (only for properties, collections and actions are supported).
+====
+
+
+
+include::_rgant-DomainServiceLayout_menuBar.adoc[leveloffset=+1]
+include::_rgant-DomainServiceLayout_menuOrder.adoc[leveloffset=+1]
+include::_rgant-DomainServiceLayout_named.adoc[leveloffset=+1]
+
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainServiceLayout_menuBar.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainServiceLayout_menuBar.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainServiceLayout_menuBar.adoc
new file mode 100644
index 0000000..1f0b649
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainServiceLayout_menuBar.adoc
@@ -0,0 +1,43 @@
+[[_rgant-DomainServiceLayout_menuBar]]
+= `menuBar()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+
+The `menuBar()` attribute is a hint to specify where on the application menu a domain service's actions should be rendered.
+
+For example:
+
+[source,java]
+----
+@DomainService
+@DomainServiceLayout(menuBar=MenuBar.PRIMARY)
+public class ToDoItems {
+    ...
+}
+----
+
+In the xref:ugvw.adoc#[Wicket viewer], domain services placed on the `PRIMARY` menu bar appears to the left:
+
+image::{_imagesdir}reference-annotations/DomainServiceLayout/menuBar-primary.png[width="720px",link="{_imagesdir}reference-annotations/DomainServiceLayout/menuBar-primary.png"]
+
+Domain services placed on the `SECONDARY` menu bar appear to the right:
+
+image::{_imagesdir}reference-annotations/DomainServiceLayout/menuBar-secondary.png[width="720px",link="{_imagesdir}reference-annotations/DomainServiceLayout/menuBar-secondary.png"]
+
+
+Domain services placed on the `TERTIARY` appear in the menu bar associated with the user's name (far top-right)
+
+image::{_imagesdir}reference-annotations/DomainServiceLayout/menuBar-tertiary.png[width="720px",link="{_imagesdir}reference-annotations/DomainServiceLayout/menuBar-tertiary.png"]
+
+
+The grouping of multiple domain services actions within a single drop-down is managed by the xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] attribute.
+
+
+[NOTE]
+====
+The xref:ugvro.adoc#[RestfulObjects viewer] does not support this attribute.
+====
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainServiceLayout_menuOrder.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainServiceLayout_menuOrder.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainServiceLayout_menuOrder.adoc
new file mode 100644
index 0000000..ee56c12
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainServiceLayout_menuOrder.adoc
@@ -0,0 +1,74 @@
+[[_rgant-DomainServiceLayout_menuOrder]]
+= `menuOrder()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+
+The `menuOrder()` attribute determines the ordering of a domain service's actions as menu items within a specified menu bar and top-level menu.
+
+
+The algorithm works as follows:
+
+* first, the xref:rgant.adoc#_rgant-DomainServiceLayout_menuBar[`menuBar()`] determines which of the three menu bars the service's actions should be rendered
+* then, the domain service's top-level name (typically explicitly specified using xref:rgant.adoc#_rgant-DomainServiceLayout_named[`named()`]) is used to determine the top-level menu item to be rendered on the menu bar
+* finally, if there is more than domain service that has the same name, then the `menuOrder` attribute is used to order those actions on the menu item drop-down.
+
+For example, the screenshot below shows the "prototyping" menu from the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp]:
+
+image::{_imagesdir}reference-annotations/DomainServiceLayout/menuOrder.png[width="500px",link="{_imagesdir}reference-annotations/DomainServiceLayout/menuOrder.png"]
+
+
+The xref:ugvw.adoc#[Wicket viewer] automatically places separators between actions from different domain services.  From this we can infer that there are actually five different domain services that are all rendered on the "prototyping" top-level menu.
+
+One of these is the todoapp's `DemoDomainEventSubscriptions` service:
+
+[source,java]
+----
+@DomainService(
+        nature = NatureOfService.VIEW_MENU_ONLY
+)
+@DomainServiceLayout(
+        menuBar = MenuBar.SECONDARY,
+        named = "Prototyping",                   // <1>
+        menuOrder = "500.20")                    // <2>
+public class DemoDomainEventSubscriptions {
+    @ActionLayout(named="Set subscriber behaviour")
+    @MemberOrder(sequence = "500.20.1")          // <3>
+    public void subscriberBehaviour(...) { ... }
+    ...
+}
+----
+<1> render on the "Prototyping" menu
+<2> positioning relative to other service's on the "Prototyping" menu
+<3> by convention (nothing more) the `@MemberOrder#sequence()` attribute continues the same Dewey decimal sequence format (a simple string "1" could in fact have been used instead)
+
+
+while another comes from the (non-ASF) http://github.com/isisaddons/isis-module-devutils[Isis addons' devutils] module:
+
+[source,java]
+----
+@DomainServiceLayout(
+    menuBar = MenuBar.SECONDARY,
+    named = "Prototyping",                    // <1>
+    menuOrder = "500.600"                     // <2>
+)
+public class DeveloperUtilitiesServiceMenu {
+    @MemberOrder( sequence = "500.600.1" )    // <3>
+    public Clob downloadMetaModel() { ... }
+    @MemberOrder( sequence = "500.600.2" )
+    public Blob downloadLayouts() { ... }
+    @ActionLayout(named = "Rebuild Services Meta Model")
+    @MemberOrder( sequence = "500.600.3")
+    public void refreshServices() { ... }
+    ...
+}
+----
+<1> render on the "Prototyping" menu
+<2> positioning relative to other service's on the "Prototyping" menu; this appears after the `DemoDomainEventSubscriptions` service shown above
+<3> by convention (nothing more) the `@MemberOrder#sequence()` attribute continues the same Dewey decimal sequence format (a simple string "1", "2", "3", ... could in fact have been used instead)
+
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainServiceLayout_named.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainServiceLayout_named.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainServiceLayout_named.adoc
new file mode 100644
index 0000000..9ee9806
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainServiceLayout_named.adoc
@@ -0,0 +1,29 @@
+[[_rgant-DomainServiceLayout_named]]
+= `named()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+The `named()` attribute explicitly specifies the domain service's name, overriding the name that would normally be inferred from the Java source code.  This attribute can also be specified for xref:rgant.adoc#_rgant-ActionLayout_named[actions], xref:rgant.adoc#_rgant-CollectionLayout_named[collections], xref:rgant.adoc#_rgant-PropertyLayout_named[properties], xref:rgant.adoc#_rgant-ParameterLayout_named[parameters], xref:rgant.adoc#_rgant-DomainObjectLayout_named[domain objects] and xref:rgant.adoc#_rgant-ViewModelLayout_named[view models].
+
+
+[TIP]
+====
+The value of this attribute also has an important role to play in the positioning of the domain service's actions relative to the actions of other domain services.  See xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`menuOrder()`] for a full discussion with examples.
+====
+
+For example:
+
+[source,java]
+----
+@DomainService
+@DomainServiceLayout(
+    named="Customers"
+)
+public class CustomerRepository {
+   ...
+}
+----
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainService_nature.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainService_nature.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainService_nature.adoc
new file mode 100644
index 0000000..bedafaf
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainService_nature.adoc
@@ -0,0 +1,89 @@
+[[_rgant-DomainService_nature]]
+= `nature()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+By default, a domain service's actions will be rendered in the application menu bar _and_ be contributed _and_ appear in the REST API _and_ (of course) be available to invoke programmatically wherever that domain service is injected.  This is great for initial prototyping, but later on you may prefer to add a little more structure.  This is the purpose of the `nature()` attribute: to indicates the intent of (all of) the actions defined within the domain service.
+
+The values of the enum are:
+
+* `VIEW` +
++
+The default; the service's actions appear on menu bars, can be contributed, appear in the REST API
+
+* `VIEW_MENU_ONLY` +
++
+The service's actions appear on menus and in the REST API, but are not contributed to domain objects or view models
+
+* `VIEW_CONTRIBUTIONS_ONLY` +
++
+The service's actions are intended only to be used as contributed actions/associations to domain objects and view models. +
++
+The related xref:rgant.adoc#_rgant-ActionLayout_contributedAs[`@ActionLayout#contributedAs()`] determines whether any given (1-arg) action is contributed as an association rather than an action.
+
+* `VIEW_REST_ONLY` +
++
+The service's actions are intended only to be listed in the REST API exposed by the xref:ugvro.adoc#[RestfulObjects viewer].
+
+* `DOMAIN` +
++
+The service and its actions are only intended to be invoked programmatically; they are a domain layer responsibility.
+
+
+The actual class name of the domain service is only rendered for the `VIEW`, `VIEW_MENU_ONLY` and `VIEW_REST_ONLY` natures.  Thus, you might also want to adopt naming conventions for your domain classes so you can infer the nature from the class.  For example, the naming convention adopted (by and large) by the (non-ASF) link:http://isisaddons.org[Isis Addons] is `ProgrammaticServices` or `Repository` as a suffix for `DOMAIN` services, and `Contributions` as a suffix for `VIEW_CONTRIBUTIONS_ONLY` services.
+
+For example:
+
+[source,java]
+----
+@DomainService(
+    nature=NatureOfService.VIEW_CONTRIBUTIONS_ONLY
+)
+public class LoanContributions {                                  // <1>
+    @Action(semantics=SemanticsOf.SAFE)                           // <2>
+    @ActionLayout(contributed=Contributed.AS_ASSOCIATION )
+    public List<Loan> currentLoans(Borrower borrower) { ... }
+    public Borrower newLoan(Borrower borrower, Book book) { ... }
+}
+----
+<1> `Contributions` as a suffix for a domain service that contributes a number of actions to ``Borrower``s.  Note that `Borrower` could be a (marker) interface, so this functionality is "mixed in" merely by the class (eg `LibraryMember`) implementing this interface
+<2> actions contibuted as associations (a collection in this case) must have safe semantics
+
+
+Another example:
+
+[source,java]
+----
+@DomainService(
+    nature=NatureOfService.DOMAIN
+)
+public class LoanRepository {                                  // <1>
+    @Programmatic                                              // <2>
+    public List<Loan> findLoansFor(Borrower borrower) { ... }
+}
+----
+<1> `Repository` as a suffix for a domain-layer service
+<2> methods on `DOMAIN` services are often xref:rgant.adoc#_rgant-Programmatic[`@Programmatic`]; they will never be exposed in the UI, so there's little point in including them in Apache Isis' metamodel
+
+
+
+A final example:
+
+[source,java]
+----
+@DomainService(
+    nature=NatureOfService.VIEW_MENU_ONLY
+)
+public class Loans {                               // <1>
+    @Action(semantics=SemanticsOf.SAFE)
+    public List<Loan> findOverdueLoans() { ... }
+    @Inject
+    LoanRepository loanRepository;                 // <2>
+}
+----
+<1> name is intended to be rendered in the UI
+<2> it's common for domain-layer domain services to be injected into presentation layer services (such as `VIEW_MENU_ONLY` and `VIEW_CONTRIBUTIONS_ONLY`).
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainService_objectType.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainService_objectType.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainService_objectType.adoc
new file mode 100644
index 0000000..767c8a7
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainService_objectType.adoc
@@ -0,0 +1,58 @@
+[[_rgant-DomainService_objectType]]
+= `objectType()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+The `objectType()` attribute is used to provide a unique alias for the domain service's class name.
+
+This value is used internally to generate a string representation of an service identity (the `Oid`).
+This can appear in several contexts, including:
+
+* as the value of `Bookmark#getObjectType()` and in the `toString()` value of `Bookmark`
+ (see xref:rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`])
+* in the serialization of `OidDto` in the xref:rgcms.adoc#_rgcms_schema-cmd[command] and xref:rgcms.adoc#_rgcms_schema-ixn[interaction] schemas
+* in the URLs of the xref:ugvro.adoc#[RestfulObjects viewer]
+* in the URLs of the xref:ugvw.adoc#[Wicket viewer] (specifically, for bookmarked actions)
+
+
+
+== Example
+
+For example:
+
+[source,java]
+----
+@DomainService(
+    objectType="orders.OrderMenu"
+)
+public class OrderMenu {
+    ...
+}
+----
+
+
+
+== Precedence
+
+The rules of precedence are:
+
+1. `@DomainService#objectType`
+2. xref:rgcms.adoc#_rgcms_methods_reserved_getId[`getId()`]
+3. The fully qualified class name.
+
+
+[TIP]
+====
+This might be obvious, but to make explicit: we recommend that you always specify an object type for your domain services.
+
+Otherwise, if you refactor your code (change class name or move package), then any externally held references to the OID of the service will break.
+At best this will require a data migration in the database; at worst it could cause external clients accessing data through the xref:ugvro.adoc#[Restful Objects] viewer to break.
+====
+
+[NOTE]
+====
+If the object type is not unique across all domain classes then the framework will fail-fast and fail to boot.
+An error message will be printed in the log to help you determine which classes have duplicate object tyoes.
+====

http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainService_repositoryFor.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainService_repositoryFor.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainService_repositoryFor.adoc
new file mode 100644
index 0000000..4656a01
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainService_repositoryFor.adoc
@@ -0,0 +1,26 @@
+[[_rgant-DomainService_repositoryFor]]
+= `repositoryFor()`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+The `repositoryFor()` attribute is intended for domain services (probably with a xref:rgant.adoc#_rgant-DomainService_nature[`nature=DOMAIN`]) that are intended to act as repositories for domain entities.
+
+For example:
+
+[source,java]
+----
+@DomainService(
+    nature=NatureOfService.DOMAIN,
+    repositoryFor=Loan.class
+)
+public class LoanRepository {
+    @Programmatic
+    public List<Loan> findLoansFor(Borrower borrower) { ... }
+}
+----
+
+
+Currently the metadata is unused; one planned use is to infer the icon for the domain service from the icon of the nominated entity.
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Facets.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Facets.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Facets.adoc
new file mode 100644
index 0000000..377bd6e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Facets.adoc
@@ -0,0 +1,15 @@
+[[_rgant-Facets]]
+= `@Facets`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+
+The `@Facets` annotation allows `FacetFactory` implementations and so can be used to run install arbitrary `Facet`s for a type. Generally this is not needed, but can be useful for overriding a custom programming model where a `FacetFactory` is not typically included.
+
+
+[NOTE]
+====
+`FacetFactory` is an important internal API that is used by Apache Isis to
+====

http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-HomePage.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-HomePage.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-HomePage.adoc
new file mode 100644
index 0000000..2c39974
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-HomePage.adoc
@@ -0,0 +1,52 @@
+[[_rgant-HomePage]]
+= `@HomePage`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+
+The `@HomePage` annotation allows a _single_ (no-arg, query-only) action on a _single_ domain service to be nominated as the action to invoke for the default home page.  This often returns a view model that acts as some sort of dashboard, presenting key information and makeing the most commonly used actions easy to invoke.
+
+For example, the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] uses `@HomePage` to return a dashboard of todo items to complete:
+
+image::{_imagesdir}reference-annotations/HomePage/HomePage.png[width="800px",link="{_imagesdir}reference-annotations/HomePage/HomePage.png"]
+
+
+The corresponding code is:
+
+[source,java]
+----
+@DomainService(nature = NatureOfService.DOMAIN)
+public class ToDoAppDashboardService  {
+    @Action(
+            semantics = SemanticsOf.SAFE
+    )
+    @HomePage
+    public ToDoAppDashboard lookup() {
+        return container.injectServicesInto(new ToDoAppDashboard());
+    }
+    @Inject
+    private DomainObjectContainer container;
+}
+----
+
+where `ToDoAppDashboard` is:
+
+[source,java]
+----
+@DomainObject(nature = Nature.VIEW_MODEL)
+public class ToDoAppDashboard {
+    public String title() { return "Dashboard"; }
+
+    public List<ToDoItem> getNotYetComplete() { ... }
+    public List<ToDoItem> getComplete() { ... }
+
+    public Blob exportToWordDoc() { ... }  // <1>
+}
+----
+<1> associated using xref:ugfun.adoc#_ugfun_object-layout_dynamic[dynamic layouts] with the `notYetComplete` collection.
+
+The other two actions shown in the above screenshot -- `exportAsXml` and `downloadLayout` -- are actually contributed to the `ToDoAppDashboard` through various domain services, as is the `downloadLayout` action.
+
+