more on ugfun.adoc - identifiers, programming model for services etc

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

Branch: refs/heads/wip
Commit: 2ca2ea184da8d9ef1a65e22139d0a2030290a2c2
Parents: 2f2714c
Author: Dan Haywood <d...@haywood-associates.co.uk>
Authored: Mon Apr 17 14:51:19 2017 +0100
Committer: Dan Haywood <d...@haywood-associates.co.uk>
Committed: Thu Apr 20 09:09:30 2017 +0100

----------------------------------------------------------------------
 .../guides/ugfun/_ugfun_building-blocks.adoc    |   4 +-
 .../ugfun/_ugfun_building-blocks_events.adoc    |  61 +-----
 ...un_building-blocks_events_domain-events.adoc |  40 ++++
 ...building-blocks_events_lifecycle-events.adoc |  32 +++
 ..._ugfun_building-blocks_events_ui-events.adoc |  28 +++
 .../_ugfun_building-blocks_identifiers.adoc     |   4 +-
 ...lding-blocks_identifiers_title-and-icon.adoc |  24 ++-
 .../ugfun/_ugfun_building-blocks_modules.adoc   |   9 +
 ...ugfun_programming-model_domain-entities.adoc | 129 ++++++++----
 ...ugfun_programming-model_domain-services.adoc | 209 +++++++++----------
 ...gfun_programming-model_view-models_jaxb.adoc |  10 +
 ..._programming-model_view-models_non-jaxb.adoc |  12 ++
 ..._ugfun_ui-hints_object-titles-and-icons.adoc |  12 +-
 13 files changed, 350 insertions(+), 224 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/2ca2ea18/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks.adoc
index 8c61796..fe81aa7 100644
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks.adoc
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks.adoc
@@ -16,8 +16,6 @@ 
include::_ugfun_building-blocks_object-members.adoc[leveloffset=+1]
 
 include::_ugfun_building-blocks_events.adoc[leveloffset=+1]
 
-include::_ugfun_building-blocks_identifiers.adoc[leveloffset=+1]
-
-nclude::_ugfun_building-blocks_modules.adoc[leveloffset=+1]
+include::_ugfun_building-blocks_modules.adoc[leveloffset=+1]
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/2ca2ea18/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_events.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_events.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_events.adoc
index ded8c28..1746b40 100644
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_events.adoc
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_events.adoc
@@ -11,7 +11,7 @@ These events enable other domain services (possibly in other 
modules) to influen
 [TIP]
 ====
 It is also possible to simulate the rendering of a domain object by way of the 
xref:../rgsvc/rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`].
-This
+This allows business rules to be enforced for programmatic interactions 
between objects.
 ====
 
 To receive the events, the domain service should subscribe to the 
xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`], and 
implement an appropriately annotated method to receive the events.
@@ -20,60 +20,7 @@ The framework has several categories of events: domain 
events, UI events and lif
 These are explored in the sections below.
 
 
-
-== Domain Events
-Domain events are fired for each object member (property, collection or 
action).
-
-By default, rendering a property causes a `PropertyDomainEvent` to be fired, 
though the 
xref:../rgant/rgant.adoc#_rgant_Property_domainEvent[`@Property#domainEvent()`] 
attribute allows a custom subclass to be specified if necessary.
-Similarly, rendering a collection causes a `CollectionDomainEvent` to be 
fired, and rendering an action causes an `ActionDomainEvent` to be fired.
-
-In fact, each event can be fired up to five times, with the event's 
`getEventPhase()` method indicating to the subscriber the phase:
-
-* *hide* phase allows the subscriber to hide the member
-
-* *disable* phase allows the subscriber to disable the member. +
-
-For a property this makes it read-only; for an action this makes it "greyed 
out".
-(Collections are implicitly read-only).
-
-* *validate* phase allows the subscriber to validate the proposed change.
-
-For a property this means validating the proposed new value of the property; 
for an action this means validating the action parameter arguments.
-For example, a referential integrity restrict could be implemented here.
-
-* *executing* phase is prior to the actual property edit/action invocation, 
allowing the subscriber to perform side-effects. +
-
-For example, a cascade delete could be implemented here.
-
-* *executed* phase is after the actual property edit/action invocation. +
-+
-For example, a business audit event could be implemented here.
-
-
-For more details on the actual domain event classes, see the 
xref:../rgcms/rgcms.adoc#_rgcms_classes_domainevent[domain event] section of 
the relevant reference guide.
-
-
-
-
-== UI Events
-
-To allow the end-user to distinguish one domain object from another, it is 
rendered with a title and an icon.
-The icon informally identifies the type of the domain object, while the title 
identifies the instance.
-The title is not formally required to be a unique identify the object within 
its type, but it needs to be "unique enough" that a human user is able to 
distinguish one instance from another.
-
-Sometimes it's helpful for the icon to represent more than just the object's 
type; it might also indicate the state of an object.
-For example, a shipped `Order` might have a slightly different icon to a 
yet-to-be-shipped `Order`; or an overdue `Loan` might be distinguished 
separately from a
-
-Customisable icons
-
-and optionally with custom CSS
-Each domain object is rendered with a
-NOTE: FIXME
-
-
-For more details on the actual domain event classes, see the 
xref:../rgcms/rgcms.adoc#_rgcms_classes_uievent[UI event] section of the 
relevant reference guide.
-
-
-== Lifecycle Events
-
+include::_ugfun_building-blocks_events_domain-events.adoc[leveloffset=+1]
+include::_ugfun_building-blocks_events_ui-events.adoc[leveloffset=+1]
+include::_ugfun_building-blocks_events_lifecycle-events.adoc[leveloffset=+1]
 

http://git-wip-us.apache.org/repos/asf/isis/blob/2ca2ea18/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_events_domain-events.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_events_domain-events.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_events_domain-events.adoc
new file mode 100644
index 0000000..9911cc6
--- /dev/null
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_events_domain-events.adoc
@@ -0,0 +1,40 @@
+[[_ugfun_building-blocks_events_domain-events]]
+= Domain Events
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more 
contributor license agreements. See the NOTICE file distributed with this work 
for additional information regarding copyright ownership. The ASF licenses this 
file to you under the Apache License, Version 2.0 (the "License"); you may not 
use this file except in compliance with the License. You may obtain a copy of 
the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by 
applicable law or agreed to in writing, software distributed under the License 
is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY 
KIND, either express or implied. See the License for the specific language 
governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+Domain events are fired for each object member (property, collection or 
action).
+
+By default, rendering a property causes a `PropertyDomainEvent` to be fired, 
though the 
xref:../rgant/rgant.adoc#_rgant_Property_domainEvent[`@Property#domainEvent()`] 
attribute allows a custom subclass to be specified if necessary.
+Similarly, rendering a collection causes a `CollectionDomainEvent` to be 
fired, and rendering an action causes an `ActionDomainEvent` to be fired.
+
+In fact, each event can be fired up to five times, with the event's 
`getEventPhase()` method indicating to the subscriber the phase:
+
+* *hide* phase allows the subscriber to hide the member
+
+* *disable* phase allows the subscriber to disable the member. +
+
+For a property this makes it read-only; for an action this makes it "greyed 
out".
+(Collections are implicitly read-only).
+
+* *validate* phase allows the subscriber to validate the proposed change.
+
+For a property this means validating the proposed new value of the property; 
for an action this means validating the action parameter arguments.
+For example, a referential integrity restrict could be implemented here.
+
+* *executing* phase is prior to the actual property edit/action invocation, 
allowing the subscriber to perform side-effects. +
+
+For example, a cascade delete could be implemented here.
+
+* *executed* phase is after the actual property edit/action invocation. +
++
+For example, a business audit event could be implemented here.
+
+
+For more details on the actual domain event classes, see the 
xref:../rgcms/rgcms.adoc#_rgcms_classes_domainevent[domain event] section of 
the relevant reference guide.
+
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2ca2ea18/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_events_lifecycle-events.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_events_lifecycle-events.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_events_lifecycle-events.adoc
new file mode 100644
index 0000000..5e9d666
--- /dev/null
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_events_lifecycle-events.adoc
@@ -0,0 +1,32 @@
+[[_ugfun_building-blocks_events_lifecycle-events]]
+= Lifecycle Events
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more 
contributor license agreements. See the NOTICE file distributed with this work 
for additional information regarding copyright ownership. The ASF licenses this 
file to you under the Apache License, Version 2.0 (the "License"); you may not 
use this file except in compliance with the License. You may obtain a copy of 
the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by 
applicable law or agreed to in writing, software distributed under the License 
is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY 
KIND, either express or implied. See the License for the specific language 
governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+Lifecycle events allow domain object subscribers to listen for changes to the 
persistence state of domain entities, and act accordingly.
+
+[NOTE]
+====
+Lifecycle events are _not_ fired for view models.
+====
+
+
+The lifecycle events supported are:
+
+* object created - just instantiated
+* updated loaded - just retrieved from the database
+* object persisting - object about to be inserted into the database
+* object persisted - object just inserted into the database
+* object updating - object about to be updated
+* object updated - object just updated
+* object removing - object about to be deleted from the database
+
+There is no lifecycle event for object creating because the framework doesn't 
know about newly created objects until they have been created; and there is no 
lifecycle event for obejcts removed because it is not valid to "touch" a domain 
entity once deleted.
+
+
+For example, if annotated with 
xref:../rgant/rgant.adoc#_rgant_DomainObject_updatingLifecycleEvent[`@DomainObjectLayout#updatingLifecycleEvent()`],
 the appropriate (subclass of) `ObjectUpdatingEvent` will be emitted.
+ Similarly for 
xref:../rgant/rgant.adoc#_rgant_DomainObjectLayout_iconUiEvent[`iconUiEvent()`] 
and 
xref:../rgant/rgant.adoc#_rgant_DomainObjectLayout_cssClassUiEvent[`cssClassUiEvent()`].
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2ca2ea18/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_events_ui-events.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_events_ui-events.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_events_ui-events.adoc
new file mode 100644
index 0000000..3a88ce3
--- /dev/null
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_events_ui-events.adoc
@@ -0,0 +1,28 @@
+[[_ugfun_building-blocks_events_ui-events]]
+= UI Events
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more 
contributor license agreements. See the NOTICE file distributed with this work 
for additional information regarding copyright ownership. The ASF licenses this 
file to you under the Apache License, Version 2.0 (the "License"); you may not 
use this file except in compliance with the License. You may obtain a copy of 
the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by 
applicable law or agreed to in writing, software distributed under the License 
is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY 
KIND, either express or implied. See the License for the specific language 
governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+As explained 
xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_identifiers_title-and-icon[earlier],
 to allow the end-user to distinguish one domain object from another, it is 
rendered with a title and an icon.
+
+Normally the code to return title and icon of an object is part of the domain 
object's implementation.
+However, UI events allow this title and icon to be provided instead by a 
subscriber.
+
+If annotated with 
xref:../rgant/rgant.adoc#_rgant_DomainObjectLayout_titleUiEvent[`@DomainObjectLayout#titleUiEvent()`],
 the appropriate (subclass of) `TitleUiEvent` will be emitted.
+ Similarly for 
xref:../rgant/rgant.adoc#_rgant_DomainObjectLayout_iconUiEvent[`iconUiEvent()`] 
and 
xref:../rgant/rgant.adoc#_rgant_DomainObjectLayout_cssClassUiEvent[`cssClassUiEvent()`].
+
+This can be particularly useful for 
xref:../ugfun/ugfun.adoc#_ugfun_programming-model_view-models_jaxb[JAXB-style 
view models] which are used as DTOs and so must have no dependencies on the 
rest of the Apache Isis framework.
+
+
+
+[TIP]
+====
+Details on how to actually implement titles and icons, see
+xref:../ugfun/ugfun.adoc#_ugfun_ui-hints_object-titles-and-icons[here].
+====
+
+
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2ca2ea18/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_identifiers.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_identifiers.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_identifiers.adoc
index c0bc698..1117f2b 100644
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_identifiers.adoc
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_identifiers.adoc
@@ -5,8 +5,10 @@
 :_imagesdir: images/
 
 
-NOTE: FIXME
+The Apache Isis framework actively tracks the identity of each domain object.
+This identity is represented to the end-user in human-readable form so that 
they know which object they are interacting with, and is also used and is 
available internally/for integrations.
 
+This section explores these two related concepts.
 
 
 include::_ugfun_building-blocks_identifiers_title-and-icon.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/2ca2ea18/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_identifiers_title-and-icon.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_identifiers_title-and-icon.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_identifiers_title-and-icon.adoc
index 356abe8..f9446ff 100644
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_identifiers_title-and-icon.adoc
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_identifiers_title-and-icon.adoc
@@ -5,23 +5,31 @@
 :_imagesdir: images/
 
 
-NOTE: FIXME
+To allow the end-user to distinguish one domain object from another, it is 
rendered with a title and an icon.
+The icon informally identifies the type of the domain object, while the title 
identifies the instance.
 
+== Title
 
+The title of a domain object is shown in several places: as the main heading 
for an object; as a link text for an object referencing another object, and 
also in tables representing collections of objects.
 
-To allow the end-user to distinguish one domain object from another, it is 
rendered with a title and an icon.
-The icon informally identifies the type of the domain object, while the title 
identifies the instance.
 The title is not formally required to be a unique identify the object within 
its type, but it needs to be "unique enough" that a human user is able to 
distinguish one instance from another.
 
+The title is usually just a simple string, but the framework also allows for 
the title to be translated into different locales.
+
+== Icon
+
 Sometimes it's helpful for the icon to represent more than just the object's 
type; it might also indicate the state of an object.
 For example, a shipped `Order` might have a slightly different icon to a 
yet-to-be-shipped `Order`; or an overdue `Loan` might be distinguished 
separately from a
 
-Customisable icons
+== CSS Class
 
-and optionally with custom CSS
-Each domain object is rendered with a
-NOTE: FIXME
+In addition to the title and icon, it is also possible for a domain object to 
provide a CSS class hint.
+In conjunction with 
xref:../ugvw/ugvw.adoc#_ugvw_customisation_tweaking-css-classes[customized CSS] 
this can be used to apply arbitrary styling; for example each object could be 
rendered in a page with a different background colour.
 
 
-For more details on the actual domain event classes, see the 
xref:../rgcms/rgcms.adoc#_rgcms_classes_uievent[UI event] section of the 
relevant reference guide.
+[TIP]
+====
+Details on how to actually write titles, icons and CSS classes can be found
+xref:../ugfun/ugfun.adoc#_ugfun_ui-hints_object-titles-and-icons[here].
+====
 

http://git-wip-us.apache.org/repos/asf/isis/blob/2ca2ea18/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_modules.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_modules.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_modules.adoc
index 40dbca0..dfe956e 100644
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_modules.adoc
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_modules.adoc
@@ -11,5 +11,14 @@ By convention there will be a single top-level package 
corresponding to the modu
 For example, the (non-ASF) 
link:https://github.com/incodehq/incode-module-document[Document module] (part 
of the link:http://catalog.incode.org[Incode Catalog]) has a top-level package 
of `org.incode.module.document`.
 Within the module there may be various subpackages, but its the module defines 
the namespace.
 
+The bootstrapping of Apache Isis also relies on module classes.
+(Currently) the only role of these classes is to identify a fully qualified 
package name, for example `org.incode.modules.document`.
+The framework then performs classpath scanning across all such packages to 
locate any domain entities provided by that module (though some modules have no 
entities), all domain services provided by the module (every module is likely 
to define at least one), and also any fixture scripts provided by the module.
+
+[TIP]
+====
 In the same way that the Java module act as a namespace for domain objects, 
it's good practice to map domain entities to their own (database) schemas.
+====
+
+
 

http://git-wip-us.apache.org/repos/asf/isis/blob/2ca2ea18/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-entities.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-entities.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-entities.adoc
index ad2bd72..3102fe6 100644
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-entities.adoc
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-entities.adoc
@@ -5,12 +5,14 @@
 :_imagesdir: images/
 
 
-
 Entities are persistent domain objects, with their persistence handled by 
JDO/DataNucleus.
 As such, they are mapped to a persistent object store, typically an RDBMS, 
with DataNucleus taking care of both lazy loading and also the persisting of 
modified ("dirty") objects.
 
 Domain entities are generally decorated with both DataNucleus and Apache Isis 
annotations.
-The following is typical:
+Let's look at some of the most commonly-used annotations.
+
+To start with, entities are flagged as being "persistence capable", indicating 
how JDO/DataNucleus should manage their identity:
+
 
 [source,java]
 ----
@@ -27,63 +29,116 @@ The following is typical:
         strategy= VersionStrategy.DATE_TIME,
         column="version"
 )
-@javax.jdo.annotations.Queries({
-        @javax.jdo.annotations.Query(                                          
 // <6>
-                name = "findByName",
-                value = "SELECT "
-                        + "FROM domainapp.modules.simple.dom.impl.SimpleObject 
"
-                        + "WHERE name.indexOf(:name) >= 0 ")
-})
-@javax.jdo.annotations.Unique(name="SimpleObject_name_UNQ", members = 
{"name"}) // <7>
-@DomainObject(                                                                 
 // <8>
+@DomainObject(                                                                 
 // <6>
         objectType = "simple.SimpleObject"
 )
+public class SimpleObject { ... }
+----
+<1> The `@PersistenceCapable` annotation indicates that this is an entity to 
DataNucleus.
+The DataNucleus enhancer acts on the bytecode of compiled entities, injecting 
lazy loading and dirty object tracking functionality.
+Enhanced entities end up also implementing the 
`javax.jdo.spi.PersistenceCapable` interface.
+<2> Indicates how identifiers for the entity are handled.
+Using `DATASTORE` means that a DataNucleus is responsible for assigning the 
value (rather than the application).
+<3> Specifies the RDBMS database schema and table name for this entity will 
reside.
+The schema should correspond with the module in which the entity resides.
+The table will default to the entity name if omitted.
+<4> For entities that are using `DATASTORE` identity, indicates how the id 
will be assigned.
+A common strategy is to allow the database to assign the id, for example using 
an identity column or a sequence.
+<5> The `@Version` annotation is useful for optimistic locking; the strategy 
indicates what to store in the `version` column.
+<6> The `@DomainObject` annotation identifies the domain object to Apache Isis 
(not DataNucleus).
+It isn't necessary to include this annotation -- at least, not for entities -- 
but it is nevertheless recommended.
+In particular, its strongly recommended that the `objectType` (which acts like 
an alias to the concrete domain class) is specified; note that it corresponds 
to the schema/table for DataNucleus' `@PersistenceCapable` annotation.
+
+
+All domain entities will have some sort of mandatory key properties.
+The example below is a very simple case, where the entity is identified by a 
`name` property:
+
+[source,java]
+----
+...
+@javax.jdo.annotations.Unique(name="SimpleObject_name_UNQ", members = 
{"name"}) // <1>
 public class SimpleObject
-             implements Comparable<SimpleObject> {                             
 // <9>
+             implements Comparable<SimpleObject> {                             
 // <2>
 
-    public SimpleObject(final String name) {                                   
 // <10>
+    public SimpleObject(final String name) {                                   
 // <3>
         setName(name);
     }
 
-    ...
+    @javax.jdo.annotations.Column(allowsNull="false", length=50)               
 // <4>
+    @lombok.Getter @lombok.Setter
+    private String name;
 
     @Override
     public String toString() {
-        return ObjectContracts.toString(this, "name");                         
 // <11>
+        return ObjectContracts.toString(this, "name");                         
 // <5>
     }
     @Override
     public int compareTo(final SimpleObject other) {
-        return ObjectContracts.compare(this, other, "name");                   
 // <9>
+        return ObjectContracts.compare(this, other, "name");                   
 // <2>
     }
 }
 ----
-<1> The `@PersistenceCapable` annotation indicates that this is an entity to 
DataNucleus.
-The DataNucleus enhancer acts on the bytecode of compiled entities, injecting 
lazy loading and dirty object tracking functionality.
-Enhanced entities end up also implementing the 
`javax.jdo.spi.PersistenceCapable` interface.
-<2> Indicates how identifiers for the entity are handled.
-Using `DATASTORE` means that a DataNucleus is responsible for assigning the 
value (rather than the application).
-<3> Specifies the RDBMS database schema and table name for this entity will 
reside.
-The schema should correspond with the module in which the entity resides.
-The table will default to the entity name if omitted.
-<4> For entities that are using `DATASTORE` identity, indicates how the id 
will be assigned.
-A common strategy is to allow the database to assign the id, for example using 
an identity column or a sequence.
-<5> The `@Version` annotation is useful for optimistic locking; the strategy 
indicates what to store in the `version` column.
-<6> The `@Query` annotation (usually several of them, nested within a 
`@Queries` annotation) defines queries using JDOQL.
-DataNucleus provides several APIs for defining queries, including entirely 
programmatic and type-safe APIs; but JDOQL is very similar to SQL and so easily 
learnt.
-<7> DataNucleus will automatically add a unique index to the primary surrogate 
id (discussed above), but additional alternative keys can be defined using the 
`@Unique` annotation.
+<1> DataNucleus will automatically add a unique index to the primary surrogate 
id (discussed above), but additional alternative keys can be defined using the 
`@Unique` annotation.
 In the example above, the "name" property is assumed to be unique.
-<8> The `@DomainObject` annotation identifies the domain object to Apache Isis 
(not DataNucleus).
-It isn't necessary to include this annotation -- at least, not for entities -- 
but it is nevertheless recommended.
-In particular, its strongly recommended that the `objectType` (which acts like 
an alias to the concrete domain class) is specified; note that it corresponds 
to the schema/table for DataNucleus' `@PersistenceCapable` annotation.
-<9> Although not required, we strongly recommend that all entities are 
naturally `Comparable`.
+<2> Although not required, we strongly recommend that all entities are 
naturally `Comparable`.
 This then allows parent/child relationships to be defined using 
``SortedSet``s; RDBMS after all are set-oriented.
 The `ObjectContracts` utility class provided by Apache Isis makes it easy to 
implement the `compareTo()` method, but you can also just use an IDE to 
generate an implementation or roll your own.
-<10> Chances are that some of the properties of the entity will be mandatory, 
for example any properties that represent an alternate unique key to the entity.
+<3> Chances are that some of the properties of the entity will be mandatory, 
for example any properties that represent an alternate unique key to the entity.
 In regular Java programming we would represent this using a constructor that 
defines these mandatory properties, and in Apache Isis/DataNucleus we can 
likewise define such a constructor.
 When DataNucleus rehydrates domain entities from the database at runtime, it 
actually requires a no-arg constructor (it then sets all state reflectively).
 However, there is no need to provide such a no-arg constructor; it is added by 
the enhancer process.
-<11> The `ObjectContracts` utility class also provides assistance for 
`toString()`, useful when debugging in an IDE.
+<4> The `name` property itself, using Lombok to generate the getter and setter.
+The `@Column` annotation specifies the length of the column in the RDBMS; this 
metadata is read by JDO/DataNucleus but Apache Isis itself also infers that the 
property is mandatory and its length from this annotation.
+<5> The `ObjectContracts` utility class also provides assistance for 
`toString()`, useful when debugging in an IDE.
+
+It's also common for domain entities to have queries annotated on them.
+These are used by repository domain services to query for instances of the 
entity:
+
+[source,java]
+----
+...
+@javax.jdo.annotations.Queries({
+    @javax.jdo.annotations.Query(                                           // 
<1>
+        name = "findByName",                                                // 
<2>
+        value = "SELECT "                                                   // 
<3>
+                + "FROM domainapp.modules.simple.dom.impl.SimpleObject "    // 
<4>
+                + "WHERE name.indexOf(:name) >= 0 ")                        // 
<5>
+})
+...
+public class SimpleObject { ... }
+----
+<1> There may be several `@Query` annotations, nested within a `@Queries` 
annotation) defines queries using JDOQL.
+<2> Defines the name of the query.
+<3> The definition of the query, using JDOQL syntax.
+<4> The fully-qualified class name.
+Must correspond to the class on which the annotation is defined (the framework 
checks this automatically on bootstrapping).
+<5> In this particular query, is an implementation of a LIKE "name%" query.
+
+DataNucleus provides several APIs for defining queries, including entirely 
programmatic and type-safe APIs; but JDOQL is very similar to SQL and so easily 
learnt.
+
+The corresponding repository method for the above query is:
+
+[source,java]
+----
+public List<SimpleObject> findByName(String name) {
+    return repositoryService.allMatches(                                    // 
<1>
+            new QueryDefault<>(SimpleObject.class,                          // 
<2>
+                        "findByName",                                       // 
<3>
+                        "name",                                             // 
<4>
+                        name);
+}
+
+@javax.inject.Inject
+RepositoryService repositoryService;
+----
+<1> The `RepositoryService` is a generic facade over the JDO/DataNucleus API, 
provided by the Apache Isis framework.
+<2> Specifies the class that is annotated with `@Query`
+<3> Corresponds to the `@Query#name()` attribute
+<4> Corresponds to the `:name` parameter in the query JDOQL string
 
 
-NOTE: FIXME - xref the ugodn guide for other mappings of persistent entities.
+[TIP]
+====
+See the xref:../ugodn/ugodn.adoc#[DataNucleus objectstore guide] for further 
information on annotating domain entities.
+====
 

http://git-wip-us.apache.org/repos/asf/isis/blob/2ca2ea18/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services.adoc
index 68f8919..4a322f3 100644
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services.adoc
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services.adoc
@@ -5,10 +5,8 @@
 :_imagesdir: images/
 
 
-This section looks at the programming conventions of writing your own domain 
services.
+This section looks at the programming model for writing your own domain 
services.
 
-''''
-''''
 
 [[__ugfun_building-blocks_domain-services_organizing-services]]
 == Organizing Services
@@ -17,45 +15,30 @@ In larger applications we have found it worthwhile to 
ensure that our domain ser
 
 The application provides the `@DomainService(nature=...)` annotation that 
helps distinguish some of these responsibilities:
 
-- `VIEW` indicates that the actions should appear both on the menu and also be 
used as contributions
-- `VIEW_MENU_ONLY` indicates that the actions should appear on the menu
-- `VIEW_CONTRIBUTIONS_ONLY` indicates that the actions should not appear on 
the menu
-- `DOMAIN` indicates that the actions are for other domain objects to invoke 
(either directly or indirectly through the event bus), but in any case should 
not be rendered at all in the UI
+* `VIEW_MENU_ONLY` indicates that the actions should appear on the menu of the 
xref:../ugvw/ugvw.adoc#[Wicket viewer], and as top-level actions for the REST 
API provided by the xref:../ugvro/ugvro.adoc#[Restful Objects viewer]
 
-NOTE: FIXME - deprecate any mention of VIEW_CONTRIBUTIONS_ONLY
+* `DOMAIN` indicates that the actions are for other domain objects to invoke 
(either directly or indirectly through the event bus), but in any case should 
not be rendered at all in the UI
 
-Pulling all the above together, here are our suggestions as to how you should 
organize your domain services.
-
-NOTE: FIXME - instead, xref to progamming model sections
+* `VIEW_REST_ONLY` indicates that the actions should appear in the REST API 
provided by the xref:../ugvro/ugvro.adoc#[Restful Objects viewer], but not 
rendered by the xref:../ugvw/ugvw.adoc#[Wicket viewer].
 
+There are also two other natures that should be considered "deprecated":
 
+* `VIEW_CONTRIBUTIONS_ONLY` which indicates that the actions should be 
contributed as actions to its action parameters. +
++
+This feature is deprecated because 
xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_types-of-domain-objects_mixins[mixins]
 are equivalent in functionality with a simpler programming model.
 
+* `VIEW` combines both `VIEW_MENU_ONLY` and the deprecated 
`VIEW_CONTRIBUTIONS_ONLY`.
 
-== Prototyping
+If the domain service nature is not specified (or is left to its default, 
`VIEW`), then the service's actions will appear in the UI.
 
 While for long-term maintainability we do recommend the naming conventions 
described 
xref:../ugfun/ugfun.adoc#__ugfun_building-blocks_domain-services_organizing-services[above],
 you can get away with far fewer services when just prototyping a domain.
-
-If the domain service nature is not specified (or is left to its default, 
`VIEW`), then the service's actions will
-appear in the UI both as menu items _and_ as contributions (and the service 
can of course be injected into other domain objects for programmatic 
invocation).
-
 Later on it is easy enough to refactor the code to tease apart the different 
responsibilities.
 
+Pulling all the above together, here are our suggestions as to how you should 
organize your domain services.
 
 
-
-
-''''
-''''
-
-
-== Typical Implementation
-
-Domain services are generally singletons that are automatically injected into 
other domain services.
-A very common usage is as a repository (to find/locate existing entities) or 
as a factory (to create new instances of entities).
-But services can also be exposed in the UI as top-level menus; and services 
are also used as a bridge to access technical resources (eg rendering a 
document object as a PDF).
-
-The Apache Isis framework itself also provides a large number of number of 
domain services, catalogued in the xref:../rgsvc/rgsvc.adoc#[Domain Services 
Reference Guide].
-Some of these are APIs (intended to be called by your application's own domain 
objects) and some are SPIs (implemented by your application and called by the 
framework, customising the way it works).
+[[__ugfun_programming-model_domain-services_menu]]
+== Menu
 
 The following is a typical menu service:
 
@@ -86,25 +69,10 @@ public class SimpleObjectMenu {
     SimpleObjectRepository simpleObjectRepository;              // <4>
 }
 ----
-<1> The (Apache Isis) `@DomainService` annotation is used to identify the 
class as a domain service.
-Apache Isis scans the classpath looking for classes with this annotation, so 
there very little configuration other than to tell the framework which packages 
to scan underneath.
-The `VIEW_MENU_ONLY` nature indicates that this service's actions should be 
exposed as menu items.
-<2> The (Apache Isis) `@DomainServiceLayout` annotation provides UI hints.
-In the example above the menu is named "Simple Objects" (otherwise it would 
have defaulted to "Simple Object Menu", based on the class name, while the 
`menuOrder` attribute determines the order of the menu with respect to other 
menu services.
-<3> The `findByName` method is annotated with various Apache Isis annotations 
(`@Action`, `@ActionLayout` and `@MemberOrder`) and is itself rendered in the 
UI as a "Find By Name" menu item underneath the "Simple Objects" menu.
-The implementation delegates to an `SimpleObjectRepository` service, which is 
injected.
-<4> The `javax.inject.Inject` annotation instructs Apache Isis framework to 
inject the `SimpleObjectRepository` service into this domain object.
-The framework can inject into not just other domain services but will also 
automatically into domain entities and view models.
-There is further discussion of service injection 
xref:../ugfun/ugfun.adoc#_ugfun_programming-model_inject-services[below].
-
-
-
-''''
-''''
 
 
 
-[[__ugfun_building-blocks_domain-services_factory-and-repository]]
+[[__ugfun_programming-model_domain-services_factory-and-repository]]
 == Factory and Repository
 
 The factory/repository uses an injected 
xref:../rgsvc/rgsvc.adoc#_rgsvc_api_RepositoryService[`RepositoryService`] to 
both instantiate new objects and to query the database for existing objects of 
a given entity type.  It is not visible in UI, rather other services delegate 
to it.
@@ -153,21 +121,26 @@ We suggest naming such classes `XxxMenu`, eg:
 
 [source,java]
 ----
-@DomainService(
-    nature = NatureOfService.VIEW_MENU_ONLY                     // <1>
+@DomainService(                                                 // <1>
+    nature = NatureOfService.VIEW_MENU_ONLY
 )
-@DomainServiceLayout(
-        named = "Customers",                                    // <2>
+@DomainServiceLayout(                                           // <2>
+        named = "Customers",
         menuBar = DomainServiceLayout.MenuBar.PRIMARY,
         menuOrder = "10"
 )
 public class CustomerMenu {
+
     @Action(
             semantics = SemanticsOf.SAFE
     )
+    @ActionLayout(bookmarking = BookmarkPolicy.AS_ROOT)
     @MemberOrder( sequence = "1" )
-    public List<Customer> findCustomerBy...(...) {
-        return customerRepository.findCustomerBy(...);          // <3>
+    public List<Customer> findByName(                           // <3>
+            @ParameterLayout(named="Name")
+            final String name
+    ) {
+        return customerRepository.findByName(name);             // <4>
     }
 
     @Action(
@@ -180,114 +153,127 @@ public class CustomerMenu {
 
     @Action(
             semantics = SemanticsOf.SAFE,
-            restrictTo = RestrictTo.PROTOTYPING
+            restrictTo = RestrictTo.PROTOTYPING                 // <5>
     )
     @MemberOrder( sequence = "99" )
-    public List<Customer> allCustomers() {
-        return customerRepository.allBankMandates();
+    public List<Customer> listAll() {
+        return customerRepository.listAll();
     }
 
     @Inject
-    protected CustomerRepository customerRepository;
+    protected CustomerRepository customerRepository;            // <4>
 }
 ----
-<1> the service's actions should be rendered as menu items
-<2> specifies the menu name.  All services with the same menu name will be 
displayed on the same menu, with separators between
-<3> delegates to an injected repository.
+<1> The (Apache Isis) 
xref:../rgant/rgant.adoc#_rgant_DomainService[`@DomainService`] annotation is 
used to identify the class as a domain service.
+Apache Isis scans the classpath looking for classes with this annotation, so 
there very little configuration other than to tell the framework which packages 
to scan underneath.
+The `VIEW_MENU_ONLY` nature indicates that this service's actions should be 
exposed as menu items.
+<3> The 
xref:../rgant/rgant.adoc#_rgant_DomainServiceLayout[`@DomainServiceLayout`] 
annotation provides UI hints.
+The menu is named "Customers" (otherwise it would have defaulted to "Customer 
Menu", based on the class name, while the 
xref:../rgant/rgant.adoc#_rgant_DomainServiceLayout_menuOrder[`menuOrder`] 
attribute determines the order of the menu with respect to other menu services.
+<3> The `findByName` method is annotated with various Apache Isis annotations 
(xref:../rgant/rgant.adoc#_rgant_Action[`@Action`], 
xref:../rgant/rgant.adoc#_rgant_ActionLayout[`@ActionLayout`] and 
xref:../rgant/rgant.adoc#_rgant_MemberOrder[`@MemberOrder`] and is itself 
rendered in the UI as a "Find By Name" menu item underneath the "Simple 
Objects" menu.
+<4> the action implementation delegates to an injected repository.
+The framework can inject into not just other domain services but will also 
automatically into domain entities and view models.
+There is further discussion of service injection 
xref:../ugfun/ugfun.adoc#_ugfun_programming-model_inject-services[below].
+<4> xref:../rgant/rgant.adoc#_rgant_Action_restrictTo[Prototype] actions are 
rendered only in prototyping mode.
+A "list all" action such as this can be useful when exploring the domain with 
a small dataset.
 
 Not every action on the repository need to be delegated to of course (the 
above example does but only because it is very simple).
 
 [TIP]
 ====
-Note also that while there's nothing to stop `VIEW_MENU` domain services being 
injected into other domain objects and interacted with programmatically, we 
recommend against it.  Instead, inject the underlying repository.  If there is 
additional business logic, then consider introducing a further `DOMAIN`-scoped 
service and call that instead.
+While there's nothing to stop `VIEW_MENU` domain services being injected into 
other domain objects and interacted with programmatically, we recommend against 
it.
+Instead, inject the underlying repository.
+If there is additional business logic, then consider introducing a further 
`DOMAIN`-scoped service and call that instead.
 ====
 
 
 
-[[__ugfun_building-blocks_domain-services_contributions]]
-== Contributions (deprecated)
 
+[[__ugfun_building-blocks_domain-services_event-subscribers]]
+== Event Subscribers
 
-Services can contribute either actions, properties or collections, based on 
the type of their parameters.
+Domain services acting as event subscribers can subscribe to 
xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_events_domain-events[domain], 
xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_events_ui-events[UI] and 
xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_events_lifecycle-events[lifecycle]
 events, influencing the rendering and behaviour of other objects.
 
-[TIP]
-====
-Contributed services can instead be implemented as
-xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_mixins[mixins].
-As such, contributed services should be considered as deprecated.
-====
+All subscribers must subscribe to the 
xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`]; as this 
amounts to a few lines of boilerplate it's easiest to inherit from the 
convenience `AbstractSubscriber` class.
 
-We suggest naming such classes `XxxContributions`, eg:
+We suggest naming such classes `XxxSubscriptions`, for example:
 
 [source,java]
 ----
 @DomainService(
-    nature=NatureOfService.VIEW_CONTRIBUTIONS_ONLY              // <1>
+    nature=NatureOfService.DOMAIN                               // <1>
 )
 @DomainServiceLayout(
     menuOrder="10",
     name="...",
 }
-public class OrderContributions {
-    @Action(semantics=SemanticsOf.SAFE)
-    @ActionLayout(contributed=Contributed.AS_ASSOCIATION)       // <2>
-    @CollectionLayout(render=RenderType.EAGERLY)
-    public List<Order> orders(Customer customer) {              // <3>
-        return container.allMatches(...);
+public class CustomerOrderSubscriptions
+                    extends AbstractSubscriber {                // <2>
+
+    @org.axonframework.eventhandling.annotation.EventHandler    // <3>
+    @com.google.common.eventbus.Subscribe                       // <3>
+    public void on(final Customer.DeletedEvent ev) {            // <4>
+        Customer customer = ev.getSource();
+        orderRepository.delete(customer);
     }
 
     @Inject
-    CustomerRepository customerRepository;
+    OrderRepository orderRepository;
 }
 ----
-<1> the service's actions should be contributed to the entities of the 
parameters of those actions
-<2> contributed as an association, in particular as a collection because 
returns a `List<T>`.
-<3> Only actions with a single argument can be contributed as associations
-
-More information about contributions can be found 
xref:../ugfun/ugfun.adoc#_ugfun_how-tos_contributed-members[here].  More 
information
-about using contributions and mixins to keep your domain application decoupled 
can be found xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_contributions[here] and 
xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_mixins[here].
-
-
+<1> subscriptions do not appear in the UI at all, so should use the domain 
nature of service
+<2> subclass from the `AbstractSubscriber` convenience superclass
+<3> The framework supports two different implementations for the 
xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] - Axon 
framework and Guava.
+Subscribers should use the appropriate annotation type depending on the 
implementation chosen (or as shown here, use both annotations).
+<4> the parameter type of the method corresponds to the event emitted on the 
event bus.
+The actual method name does not matter (though it must have `public` 
visibility).
 
 
-[[__ugfun_building-blocks_domain-services_event-subscribers]]
-== Event Subscribers
+[[__ugfun_building-blocks_domain-services_contributions]]
+== Contributions (deprecated)
 
-NOTE: FIXME - use AbstractSubscriber, need to show how to subscribe with event 
service bus...
+Services can contribute either actions, properties or collections, based on 
the type of their parameters.
 
-Event subscribers can both veto interactions (hiding members, disabling 
members or validating changes), or can react to interactions (eg action 
invocation or property edit).
+[WARNING]
+====
+Contributed services should be considered a deprecated feature.
+Instead, contribute the behaviour using 
xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_mixins[mixins].
+====
 
-We suggest naming such classes `XxxSubscriptions`, eg:
+We suggest naming such classes `XxxContributions`, eg:
 
 [source,java]
 ----
 @DomainService(
-    nature=NatureOfService.DOMAIN                       // <1>
+    nature=NatureOfService.VIEW_CONTRIBUTIONS_ONLY              // <1>
 )
 @DomainServiceLayout(
     menuOrder="10",
     name="...",
 }
-public class CustomerOrderSubscriptions {
-    @com.google.common.eventbus.Subscribe
-    public void on(final Customer.DeletedEvent ev) {
-        Customer customer = ev.getSource();
-        orderRepository.delete(customer);
+public class OrderContributions {
+    @Action(semantics=SemanticsOf.SAFE)
+    @ActionLayout(contributed=Contributed.AS_ASSOCIATION)       // <2>
+    @CollectionLayout(render=RenderType.EAGERLY)
+    public List<Order> orders(Customer customer) {              // <3>
+        return container.allMatches(...);
     }
+
     @Inject
-    OrderRepository orderRepository;
+    CustomerRepository customerRepository;
 }
 ----
-<1> subscriptions do not appear in the UI at all, so should use the domain 
nature of service
-
+<1> the service's actions should be contributed to the entities of the 
parameters of those actions
+<2> contributed as an association, in particular as a collection because 
returns a `List<T>`.
+<3> Only actions with a single argument can be contributed as associations
 
+More information about contributions can be found 
xref:../ugfun/ugfun.adoc#_ugfun_how-tos_contributed-members[here].  More 
information
+about using contributions and mixins to keep your domain application decoupled 
can be found xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_contributions[here] and 
xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_mixins[here].
 
 
-''''
-''''
 
 
 
+[[__ugfun_building-blocks_domain-services_scoped-services]]
 == Scoped services
 
 By default all domain services are considered to be singletons, and 
thread-safe.
@@ -309,10 +295,11 @@ The framework provides a number of request-scoped 
services, include a xref:../rg
 
 
 
-== Registering domain services
+[[__ugfun_building-blocks_domain-services_registering]]
+== Registering
 
-The easiest way to register domain services is using 
xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`]
 to specify the modules
-which contain 
xref:../rgant/rgant.adoc#_rgant-DomainService[`@DomainService`]-annotated 
classes.
+The easiest way to register domain services with the framework is to use an 
xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`].
+This specifies the modules which contain 
xref:../rgant/rgant.adoc#_rgant-DomainService[`@DomainService`]-annotated 
classes.
 
 For example:
 
@@ -359,25 +346,17 @@ Examples of framework-provided services (as defined in 
the applib) include clock
 
 
 
+[[__ugfun_building-blocks_domain-services_initialization]]
 == Initialization
 
 Services can optionally declare lifecycle callbacks to initialize them (when 
the app is deployed) and to shut them down (when the app is undeployed).
 
 An Apache Isis session _is_ available when initialization occurs (so services 
can interact with the object store, for example).
 
-
-The framework will call any `public` method annotated with 
xref:../rgant/rgant.adoc#_rgant-PostConstruct[`@PostConstruct`] with either no 
arguments of an argument of type `Map<String,String>`
-
-or
-
+The framework will call any `public` method annotated with 
xref:../rgant/rgant.adoc#_rgant-PostConstruct[`@PostConstruct`] with either no 
arguments of an argument of type `Map<String,String>`.
 In the latter case, the framework passes in the configuration 
(`isis.properties` and any other component-specific configuration files).
 
-
 Shutdown is similar; the framework will call any method annotated with 
xref:../rgant/rgant.adoc#_rgant-PreDestroy[`@PreDestroy`].
 
 
 
-== The getId() method
-
-Optionally, a service may provide a 
xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_getId[`getId()`] method.  This 
method returns a logical identifier for a service, independent of its 
implementation.
-

http://git-wip-us.apache.org/repos/asf/isis/blob/2ca2ea18/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_jaxb.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_jaxb.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_jaxb.adoc
new file mode 100644
index 0000000..8eadadb
--- /dev/null
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_jaxb.adoc
@@ -0,0 +1,10 @@
+[[_ugfun_programming-model_view-models_jaxb]]
+= JAXB View Models
+
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more 
contributor license agreements. See the NOTICE file distributed with this work 
for additional information regarding copyright ownership. The ASF licenses this 
file to you under the Apache License, Version 2.0 (the "License"); you may not 
use this file except in compliance with the License. You may obtain a copy of 
the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by 
applicable law or agreed to in writing, software distributed under the License 
is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY 
KIND, either express or implied. See the License for the specific language 
governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+
+NOTE: FIXME

http://git-wip-us.apache.org/repos/asf/isis/blob/2ca2ea18/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_non-jaxb.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_non-jaxb.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_non-jaxb.adoc
new file mode 100644
index 0000000..2069a9a
--- /dev/null
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_non-jaxb.adoc
@@ -0,0 +1,12 @@
+[[_ugfun_programming-model_view-models_non-jaxb]]
+= Non-JAXB View Models
+
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more 
contributor license agreements. See the NOTICE file distributed with this work 
for additional information regarding copyright ownership. The ASF licenses this 
file to you under the Apache License, Version 2.0 (the "License"); you may not 
use this file except in compliance with the License. You may obtain a copy of 
the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by 
applicable law or agreed to in writing, software distributed under the License 
is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY 
KIND, either express or implied. See the License for the specific language 
governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+
+
+NOTE: FIXME
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2ca2ea18/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_object-titles-and-icons.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_object-titles-and-icons.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_object-titles-and-icons.adoc
index 1c8663a..a1a3301 100644
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_object-titles-and-icons.adoc
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_ui-hints_object-titles-and-icons.adoc
@@ -5,11 +5,14 @@
 :_imagesdir: images/
 
 
-In Apache Isis every object is identified to the user by a title (label) and 
an icon.  This is shown in several places: as the main heading for an object; 
as a link text for an object referencing another object, and also in tables 
representing collections of objects.
+In Apache Isis every object is identified to the user by a title (label) and 
an icon.
+This is shown in several places: as the main heading for an object; as a link 
text for an object referencing another object, and also in tables representing 
collections of objects.
 
-The icon is often the same for all instances of a particular class, but it's 
also possible for an individual instance to return a custom icon.  This could 
represent the state of that object (eg a shipped order, say, or overdue library 
book).
+The icon is often the same for all instances of a particular class, but it's 
also possible for an individual instance to return a custom icon.
+This could represent the state of that object (eg a shipped order, say, or 
overdue library book).
 
-It is also possible for an object to provide a CSS class hint.  In conjunction 
with xref:../ugvw/ugvw.adoc#_ugvw_customisation_tweaking-css-classes[customized 
CSS] this can be used to apply arbitrary styling; for example each object could 
be rendered in a page with a different background colour.
+It is also possible for an object to provide a CSS class hint.
+In conjunction with 
xref:../ugvw/ugvw.adoc#_ugvw_customisation_tweaking-css-classes[customized CSS] 
this can be used to apply arbitrary styling; for example each object could be 
rendered in a page with a different background colour.
 
 
 == Object Title
@@ -79,6 +82,9 @@ NOTE: FIXME - see 
xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_title[`title(
 
 
 
+NOTE: FIXME -
+For more details on the actual UI event classes, see the 
xref:../rgcms/rgcms.adoc#_rgcms_classes_uievent[UI event] section of the 
relevant reference guide.
+
 
 == Object Icon
 

Reply via email to