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/04/20 08:12:34 UTC
[25/58] [abbrv] isis git commit: ISIS-1521: working on ugfun.adoc
ISIS-1521: working on ugfun.adoc
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/2f2714cc
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/2f2714cc
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/2f2714cc
Branch: refs/heads/wip
Commit: 2f2714cc32230f4304256c07bdd48f99c8b63ab0
Parents: 31534e5
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Mon Apr 17 11:31:17 2017 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Thu Apr 20 09:09:30 2017 +0100
----------------------------------------------------------------------
.../src/main/asciidoc/downloads.adoc | 3 +-
.../guides/rgcms/_rgcms_schema-common.adoc | 2 +-
.../ugbtb/_ugbtb_decoupling_contributions.adoc | 81 +--
.../guides/ugbtb/_ugbtb_decoupling_mixins.adoc | 269 --------
.../guides/ugbtb/_ugbtb_view-models.adoc | 18 -
.../guides/ugbtb/_ugbtb_view-models_jaxb.adoc | 415 ------------
.../_ugbtb_view-models_programming-model.adoc | 89 ---
.../src/main/asciidoc/guides/ugbtb/ugbtb.adoc | 1 -
.../ugfun/_ugfun_available-domain-services.adoc | 18 +
...able-domain-services_framework-provided.adoc | 107 ++++
...vailable-domain-services_incode-catalog.adoc | 31 +
...n_available-domain-services_isis-addons.adoc | 41 ++
.../guides/ugfun/_ugfun_building-blocks.adoc | 23 +
.../ugfun/_ugfun_building-blocks_events.adoc | 79 +++
.../_ugfun_building-blocks_identifiers.adoc | 14 +
.../_ugfun_building-blocks_identifiers_oid.adoc | 47 ++
...lding-blocks_identifiers_title-and-icon.adoc | 27 +
.../ugfun/_ugfun_building-blocks_metamodel.adoc | 32 +
.../ugfun/_ugfun_building-blocks_modules.adoc | 15 +
.../_ugfun_building-blocks_object-members.adoc | 87 +++
...building-blocks_types-of-domain-objects.adoc | 35 +
...types-of-domain-objects_domain-entities.adoc | 37 ++
...types-of-domain-objects_domain-services.adoc | 66 ++
...g-blocks_types-of-domain-objects_mixins.adoc | 56 ++
...cks_types-of-domain-objects_view-models.adoc | 162 +++++
.../guides/ugfun/_ugfun_class-structure.adoc | 46 --
.../ugfun/_ugfun_class-structure_actions.adoc | 264 --------
.../_ugfun_class-structure_collections.adoc | 121 ----
.../_ugfun_class-structure_domain-services.adoc | 155 -----
.../_ugfun_class-structure_inject-services.adoc | 103 ---
...lass-structure_properties-vs-parameters.adoc | 38 --
.../_ugfun_class-structure_properties.adoc | 369 -----------
.../guides/ugfun/_ugfun_core-concepts.adoc | 6 +-
.../ugfun/_ugfun_core-concepts_add-ons.adoc | 54 --
.../_ugfun_core-concepts_apache-isis-vs.adoc | 2 +-
...ache-isis-vs_mvc-server-side-frameworks.adoc | 29 -
...concepts_apache-isis-vs_mvc-server-side.adoc | 29 +
.../_ugfun_core-concepts_building-blocks.adoc | 314 ---------
..._ugfun_core-concepts_deployment-options.adoc | 93 +++
...re-concepts_framework-provided-services.adoc | 107 ----
..._core-concepts_other-deployment-options.adoc | 81 ---
.../ugfun/_ugfun_domain-class-ontology.adoc | 45 --
...n_domain-class-ontology_domain-entities.adoc | 86 ---
...n_domain-class-ontology_domain-services.adoc | 229 -------
.../_ugfun_domain-class-ontology_mixins.adoc | 56 --
...ugfun_domain-class-ontology_view-models.adoc | 196 ------
.../guides/ugfun/_ugfun_programming-model.adoc | 91 +++
.../ugfun/_ugfun_programming-model_actions.adoc | 264 ++++++++
.../_ugfun_programming-model_collections.adoc | 121 ++++
...ugfun_programming-model_domain-entities.adoc | 89 +++
...ugfun_programming-model_domain-services.adoc | 383 +++++++++++
...ugfun_programming-model_inject-services.adoc | 103 +++
.../ugfun/_ugfun_programming-model_mixins.adoc | 346 ++++++++++
...gramming-model_properties-vs-parameters.adoc | 38 ++
.../_ugfun_programming-model_properties.adoc | 369 +++++++++++
.../_ugfun_programming-model_view-models.adoc | 631 +++++++++++++++++++
.../building-blocks/types-of-domain-object.png | Bin 30851 -> 0 bytes
.../building-blocks/types-of-domain-object.pptx | Bin 64342 -> 0 bytes
.../hexagonal-architecture-addons.png | Bin 128533 -> 0 bytes
.../action-semantics-are-you-sure.png | Bin 11046 -> 0 bytes
.../tips-n-tricks/are-you-sure-happy-case.png | Bin 9993 -> 0 bytes
.../tips-n-tricks/are-you-sure-sad-case.png | Bin 10515 -> 0 bytes
.../how-tos/tips-n-tricks/are-you-sure.png | Bin 9312 -> 0 bytes
.../src/main/asciidoc/guides/ugfun/ugfun.adoc | 9 +-
.../guides/ugodn/_ugodn_hints-and-tips.adoc | 1 +
..._ugodn_hints-and-tips_mapping-to-a-view.adoc | 9 +
.../_ugvro_simplified-representations.adoc | 366 +----------
...ified-representations_action-invocation.adoc | 128 ++++
...ied-representations_apache-isis-profile.adoc | 38 ++
...epresentations_configuration-properties.adoc | 2 +-
...implified-representations_domain-object.adoc | 92 +++
...ified-representations_object-collection.adoc | 82 +++
...d-representations_other-representations.adoc | 37 ++
.../tg/_tg_stop-scaffolding-start-coding.adoc | 8 +-
74 files changed, 3848 insertions(+), 3537 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/downloads.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/downloads.adoc b/adocs/documentation/src/main/asciidoc/downloads.adoc
index 3ecfa73..65456b0 100644
--- a/adocs/documentation/src/main/asciidoc/downloads.adoc
+++ b/adocs/documentation/src/main/asciidoc/downloads.adoc
@@ -7,7 +7,8 @@
Apache Isis™ software is a framework for rapidly developing domain-driven apps in Java.
-Write your business logic in entities, domain services and repositories, and the framework dynamically generates a representation of that domain model as a webapp or RESTful API. Use for prototyping or production.
+Write your business logic in entities, domain services and repositories, and the framework dynamically generates a representation of that domain model as a webapp or RESTful API.
+Use for prototyping or production.
http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-common.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-common.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-common.adoc
index d3411a1..20e2a30 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-common.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_schema-common.adoc
@@ -16,7 +16,7 @@ the `Bookmark` object obtained from the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_Book
Although simple, this is an enormously powerful concept, in that it represents a URI to any domain object managed by
a given Apache Isis application. With it, we have the ability to lookup any arbitrary object. Further discussion and
-examples can be found xref:../ugfun/ugfun.adoc#__ugfun_core-concepts_building-blocks_oid[here].
+examples can be found xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_identifiers_oid[here].
The `oidDto` complex type is defined as:
http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_contributions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_contributions.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_contributions.adoc
index 6e93ac7..09844ad 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_contributions.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_contributions.adoc
@@ -5,83 +5,4 @@
:_imagesdir: images/
-Contributed services provide many of the same benefits as xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_mixins[mixins];
-indeed mixins are an evolution and refinement of the contributions concept.
-
-[WARNING]
-====
-It's possible that contributions may be deprecated and eventually removed in a future version of the framework, to be replaced entirely by mixins.
-====
-
-The main difference between contributed services and mixins is that the actions of a contributed service will
-contribute to _all_ the parameters of its actions, whereas a mixin only contributes to the type accepted in its
-constructor. Also, contributed services are long-lived
-singletons, whereas mixins are instantiated as required (by the framework) and then discarded almost immediately.
-
-[NOTE]
-====
-There's further useful information on contributed services in the reference guide, discussing the xref:../rgant/rgant.adoc#_rgant-DomainService_nature[@DomainService#nature()] attribute, for the `NatureOfService.VIEW_CONTRIBUTIONS_ONLY` nature.
-====
-
-
-== Syntax
-
-Any n-parameter action provided by a service will automatically be contributed to the list of actions for each of its (entity) parameters. From the viewpoint of the entity the action is called a contributed action.
-
-For example, given a service:
-
-[source,java]
-----
-public interface Library {
- public Loan borrow(Loanable l, Borrower b);
-}
-----
-
-and the entities:
-
-[source,java]
-----
-public class Book implements Loanable { ... }
-----
-
-and
-
-[source,java]
-----
-public class LibraryMember implements Borrower { ... }
-----
-
-then the `borrow(...)` action will be contributed to both `Book` and to `LibraryMember`.
-
-This is an important capability because it helps to decouple the concrete classes from the services.
-
-If necessary, though, this behaviour can be suppressed by annotating the service action with `@org.apache.isis.applib.annotations.NotContributed`.
-
-For example:
-
-[source,java]
-----
-public interface Library {
- @NotContributed
- public Loan borrow(Loanable l, Borrower b);
-}
-----
-
-If annotated at the interface level, then the annotation will be inherited by every concrete class. Alternatively the annotation can be applied at the implementation class level and only apply to that particular implementation.
-
-Note that an action annotated as being `@NotContributed` will still appear in the service menu for the service. If an action should neither be contributed nor appear in service menu items, then simply annotate it as `@Hidden`.
-
-
-## Contributed Action
-
-NOTE: FIXME
-
-## Contributed Property
-
-NOTE: FIXME
-
-## Contributed Collection
-
-NOTE: FIXME
-
-
+NOTE: FIXME - combine with mixins, above
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_mixins.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_mixins.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_mixins.adoc
index 72af4c3..566b840 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_mixins.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_mixins.adoc
@@ -5,273 +5,4 @@
:_imagesdir: images/
-A mixin object allows one class to contribute behaviour - actions, (derived) properties and (derived) collections - to another domain object, either a domain entity or view model.
-
-Some programming languages use the term "trait" instead of mixin, and some languages (such as AspectJ) define their own syntax for defining such constructs.
-In Apache Isis a mixin is very similar to a domain service, however it also defines a single 1-arg constructor that defines the type of the domain objects that it contributes to.
-
-Why do this?
-Two reasons:
-
-* The main reason is to allow the app to be decoupled, so that it doesn't degrade into the proverbial link:http://www.laputan.org/mud/mud.html#BigBallOfMud["big ball of mud"].
-Mixins (and contributions) allow dependency to be inverted, so that the dependencies between modules can be kept acyclic and under control.
-
-* However, there is another reason: mixins are also a convenient mechanism for grouping functionality even for a concrete type, helping to rationalize about the dependency between the data and the behaviour.
-
-Both use cases are discussed below.
-
-Syntactically, a mixin is defined using either the xref:../rgant/rgant.adoc#_rgant_Mixin[`@Mixin`] annotation or using xref:../rgant/rgant.adoc#_rgant_DomainObject_nature[`@DomainObject#nature()`] attribute (specifying a nature of `Nature.MIXIN`).
-
-
-== Contributed Collection
-
-The example below shows how to contribute a collection:
-
-[source,java]
-----
-@Mixin
-public class DocumentHolderDocuments {
-
- private final DocumentHolder holder;
- public DocumentHolderDocuments(DocumentHolder holder) { this.holder = holder; }
-
- @Action(semantics=SemanticsOf.SAFE) // <1>
- @ActionLayout(contributed = Contributed.AS_ASSOCIATION) // <2>
- @CollectionLayout(render = RenderType.EAGERLY)
- public List<Document> documents() { // <3>
- ...
- }
- public boolean hideDocuments() { ... } // <4>
-}
-----
-<1> required; actions that have side-effects cannot be contributed as collections
-<2> required; otherwise the mixin will default to being rendered as an action
-<3> must accept no arguments.
- The mixin is a collection rather than a property because the return type is a collection, not a scalar.
-<4> supporting methods follow the usual naming conventions.
- (That said, in the case of collections, because the collection is derived/read-only, the only supporting method that is relevant is `hideXxx()`).
-
-The above will result in a contributed collection for all types that implement/extend from `DocumentHolder` (so is probably for a mixin across modules).
-
-
-
-== Contributed Property
-
-Contributed properties are defined similarly, for example:
-
-[source,java]
-----
-@Mixin
-public class DocumentHolderMostRecentDocument {
-
- private final DocumentHolder holder;
- public DocumentHolderDocuments(DocumentHolder holder) { this.holder = holder; }
-
- @Action(semantics=SemanticsOf.SAFE) // <1>
- @ActionLayout(contributed = Contributed.AS_ASSOCIATION) // <2>
- public Document> mostRecentDocument() { // <3>
- ...
- }
- public boolean hideMostRecentDocument() { ... } // <4>
-}
-----
-<1> required; actions that have side-effects cannot be contributed as collections
-<2> required; otherwise the mixin will default to being rendered as an action
-<3> must accept no arguments.
- The mixin is a property rather than a collection because the return type is a scalar.
-<4> supporting methods follow the usual naming conventions.
- (That said, in the case of properties, because the property is derived/read-only, the only supporting method that is relevant is `hideXxx()`).
-
-
-== Contributed Action
-
-Contributed properties are defined similarly, for example:
-
-[source,java]
-----
-@Mixin
-public class DocumentHolderAddDocument {
-
- private final DocumentHolder holder;
- public DocumentHolderDocuments(DocumentHolder holder) { this.holder = holder; }
-
- @Action()
- @ActionLayout(contributed = Contributed.AS_ACTION) // <1>
- public Document> addDocument(Document doc) {
- ...
- }
- public boolean hideAddDocument() { ... } // <2>
-}
-----
-<1> recommended
-<2> supporting methods follow the usual naming conventions.
-
-
-== Inferred Name
-
-Where the mixin follows the naming convention `SomeType_mixinName` then the method name can be abbreviated to "$$".
-The mixin name is everything after the last '_'.
-
-For example:
-
-[source,java]
-----
-@Mixin
-public class DocumentHolder_documents {
-
- private final DocumentHolder holder;
- public DocumentHolder_documents(DocumentHolder holder) { this.holder = holder; }
-
- @Action(semantics=SemanticsOf.SAFE)
- @ActionLayout(contributed = Contributed.AS_ASSOCIATION)
- @CollectionLayout(render = RenderType.EAGERLY)
- public List<Document> $$() { // <1>
- ...
- }
- public boolean hide$$() { ... } // <2>
-}
-----
-<1> using "$$" as the reserved method name
-<2> supporting methods as usual
-
-The character "$" is also recognized as a separator between the mixin type and mixin name.
-This is useful for mixins implemented as nested static types, discussed below.
-
-
-== As Nested Static Classes
-
-As noted in the introduction, while mixins were originally introduced as a means of allowing contributions from one module to the types of another module, they are also a convenient mechanism for grouping functionality/behaviour against a concrete type.
-All the methods and supporting methods end up in a single construct, and the dependency between that functionality and the rest of the object is made more explicit.
-
-When using mixins in this fashion, it is idiomatic to write the mixin as a nested static class, using the naming convention described above to reduce duplication.
-
-For example:
-
-[source,java]
-----
-public class Customer {
-
- @Mixin
- public static class placeOrder { // <1>
-
- private final Customer customer;
- public documents(Customer customer) { this.customer = customer; } // <2>
-
- @Action
- @ActionLayout(contributed = Contributed.AS_ACTION)
- public List<Order> $$(Product p, int quantity) { // <3>
- ...
- }
- public boolean hide$$() { ... } // <4>
- public String validate0$$(Product p) { ... }
- }
-}
-----
-<1> Prior to `1.13.2`, had to be prefixed by an "_"; this is no longer required because "$" is also recognized as a way of parsing the class name in order to infer the mixin's name (eg `Customer$placeOrder`).
-<2> typically contributed to concrete class
-<3> using the "$$" reserved name
-<4> supporting methods as usual
-
-
-Moreover, the mixin class can be capitalized if desired.
-Thus:
-
-[source,java]
-----
-public class Customer {
-
- @Mixin
- public static class PlaceOrder { // <1>
-
- private final Customer customer;
- public documents(Customer customer) { this.customer = customer; } // <2>
-
- @Action
- @ActionLayout(contributed = Contributed.AS_ACTION)
- public List<Order> $$(Product p, int quantity) { // <3>
- ...
- }
- public boolean hide$$() { ... } // <4>
- public String validate0$$(Product p) { ... }
- }
-}
-----
-
-
-In other words, all of the following are allowed:
-
-* `public static class Documents { ... }`
-* `public static class documents { ... }`
-* `public static class _Documents { ... }`
-* `public static class _documents { ... }`
-
-The reserved method name "$$" can also be changed using xref:../rgant/rgant.adoc#_rgant_Mixin_method[`@Mixin#method()`] or xref:../rgant/rgant.adoc#_rgant_DomainObject_mixinMethod[`@DomainObject#mixinMethod()`].
-
-
-
-
-
-
-
-
-== Programmatic usage
-
-When a domain object is rendered, the framework will automatically instantiate all required mixins and delegate to them
-dynamically. If writing integration tests or fixtures, or (sometimes) just regular domain logic, then you may need to
-instantiate mixins directly.
-
-For this you can use the
-xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer_object-creation-api[`DomainObjectContainer#mixin(...)`
-method. For example:
-
-[source,java]
-----
-DocumentHolder_documents mixin = container.mixin(DocumentHolder_documents.class, customer);
-----
-
-The xref:../ugtst/ugtst.adoc#__ugtst_integ-test-support_bootstrapping_IntegrationTestAbstract[`IntegrationTestAbstract`] and
-xref:../rgcms/rgcms.adoc#_rgcms_classes_super_FixtureScript[`FixtureScript`] classes both provide a `mixin(...)` convenience
-method.
-
-
-
-== Other reasons to use mixins
-
-In the introduction to this topic we mentioned that mixins are most useful for ensuring that the domain app remains
-decoupled. This applies to the case where the contributee (eg `Customer`, being mixed into) is in one module, while
-the contributor mixin (`DocumentHolder_documents`) is in some other module. The `customer` module knows about the
-`document` module, but not vice versa.
-
-However, you might also want to consider moving behaviour out of entities even within the same module, perhaps even
-within the same Java package. And the reason for this is to support hot-reloading of Java classes, so that you can
-modify and recompile your application without having to restart it. This can provide substantial productivity gains.
-
-The Hotspot JVM has limited support for hot reloading; generally you can change method implementations but you cannot
-introduce new methods. However, the link:https://dcevm.github.io/[DCEVM] open source project will patch the JVM to
-support much more complete hot reloading support. There are also, of course, commercial products such as JRebel.
-
-The main snag in all this is the DataNucleus enhancer... any change to entities is going to require the entity to be
-re-enhanced, and the JDO metamodel recreated, which usually "stuffs things up". So hot-reloading of an app whose
-fundamental structure is changing is likely to remain a no-no.
-
-However, chances are that the structure of your domain objects (the data) will change much less rapidly than
-the behaviour of those domain objects. Thus, it's the behaviour that you're most likely wanting to change while the
-app is still running. If you move that behaviour out into xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins[mixins] (or
-xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_contributions[contributed services]), then these can be reloaded happily.
-(When running in prototype mode), Apache Isis will automatically recreate the portion of the metamodel for any domain
-object as it is rendered.
-
-
-
-== Related reading
-
-Mixins are an implementation of the link:http://www.artima.com/articles/dci_vision.html[DCI architecture] architecture, as formulated and described by link:https://en.wikipedia.org/wiki/Trygve_Reenskaug[Trygve Reenskaug] and link:https://en.wikipedia.org/wiki/Jim_Coplien[Jim Coplien]. Reenskaug was the inventor of the MVC pattern (and also the external
-examiner for Richard Pawson's PhD thesis), while Coplien has a long history in object-orientation, C++ and patterns.
-
-DCI stands for Data-Context-Interaction and is presented as an evolution of object-oriented programming, but one where
-behaviour is bound to objects dynamically rather than statically in some context or other. The `@Mixin`
-pattern is Apache Isis' straightforward take on the same basic concept.
-
-You might also wish to check out link:http://zest.apache.org[Apache Zest] (formerly Qi4J), which implements a much more
-general purpose implementation of the same concepts.
http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models.adoc
deleted file mode 100644
index 0efd664..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models.adoc
+++ /dev/null
@@ -1,18 +0,0 @@
-[[_ugbtb_view-models]]
-= View Models
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../../
-:_imagesdir: images/
-
-
-View models are a type of domain object (with state, behaviour etc) but where the state is _not_ persisted into the
- JDO/DataNucleus-managed database, but is instead converted to/from a string memento, and held by the calling client.
-This opens up a number of more advanced use cases.
-
-In this topic we'll explore those use cases, and learn the programming model and conventions to use view models in your application.
-
-
-include::_ugbtb_view-models_programming-model.adoc[leveloffset=+1]
-include::_ugbtb_view-models_jaxb.adoc[leveloffset=+1]
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_jaxb.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_jaxb.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_jaxb.adoc
deleted file mode 100644
index fe49916..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_jaxb.adoc
+++ /dev/null
@@ -1,415 +0,0 @@
-[[_ugbtb_view-models_jaxb]]
-= JAXB-annotated View Models/DTOs
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../../
-:_imagesdir: images/
-
-
-
-As noted in the xref:../ugfun/ugfun.adoc#_ugfun_domain-class-ontology_view-models[introduction], view models can also be defined using JAXB annotations.
-The serialized form of these view models is therefore XML, which also enables these view models
-to act as DTOs.
-
-In case it's not obvious, these DTOs are still usable as "regular" view models; they will render in the xref:../ugvw/ugvw.adoc#[Wicket viewer] just like any other.
-In fact, these JAXB-annotated view models are in many regards the most powerful of all the various ways of writing view models:
-
-* their entire state (collections as well as properties) is automatically managed from interaction to interaction. +
-+
-In contrast, using xref:../rgant/rgant.adoc#_rgant-ViewModel[`@ViewModel`] (or its xref:../rgant/rgant.adoc#_rgant-DomainObject_nature[`@DomainObject#nature()`] equivalent) will only manage the state of properties, but not collections.
-And if using the xref:../rgcms/rgcms.adoc#_rgcms_classes_super_ViewModel[`ViewModel`] interface, then the programmer must write all the state management (lots of boilerplate).
-
-* JAXB-annotated view models are "in effect" editable.
-
-The examples in this section uses the DTO for `ToDoItem`, taken from the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp].
-This DTO is defined as follows:
-
-[source,java]
-----
-package todoapp.app.viewmodels.todoitem.v1; // <1>
-@XmlRootElement(name = "toDoItemDto") // <2>
-@XmlType(
- propOrder = { // <3>
- "majorVersion", "minorVersion",
- "description", "category", ...
- "toDoItem", "similarItems"
- }
-)
-@DomainObjectLayout(
- titleUiEvent = TitleUiEvent.Doop.class // <4>
-)
-public class ToDoItemV1_1 implements Dto { // <5>
- @XmlElement(required = true, defaultValue = "1") // <6>
- public final String getMajorVersion() { return "1"; }
- @XmlElement(required = true, defaultValue = "1") // <7>
- public String getMinorVersion() { return "1"; }
-
- @XmlElement(required = true) // <8>
- @Getter @Setter
- protected String description;
- @XmlElement(required = true)
- @Getter @Setter
- protected String category;
- ...
-
- @Getter @Setter // <9>
- protected ToDoItem toDoItem;
- @XmlElementWrapper // <10>
- @XmlElement(name = "todoItem")
- @Getter @Setter
- protected List<ToDoItem> similarItems = Lists.newArrayList();
-}
-----
-<1> package name encodes major version; see discussion on xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_versioning[versioning]
-<2> identifies this class as a view model and defines the root element for JAXB serialization
-<3> all properties in the class must be listed; (they can be ignored using `@XmlTransient`)
-<4> demonstrating use of UI events for a subscriber to provide the DTO's title; see xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout_titleUiEvent[`@DomainObjectLayout#titleUiEvent()`].
-<5> class name encodes (major and) minor version; see discussion on xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_versioning[versioning]
-<6> again, see discussion on xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_versioning[versioning]
-<7> again, see discussion on xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_versioning[versioning]
-<8> simple scalar properties
-<9> reference to a persistent entity; discussed xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_referencing-domain-entities[below]
-<10> reference to a collection of persistent entities; again discussed xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_referencing-domain-entities[below]
-
-
-
-[[__ugbtb_view-models_jaxb_referencing-domain-entities]]
-== Referencing Domain Entities
-
-It's quite common for view models to be "backed by" (be projections of) some underlying domain entity.
-The `ToDoItemDto` we've been using as the example in this section is an example: there is an underlying `ToDoItem` entity.
-
-It wouldn't make sense to serialize out the state of a persistent entity: the point of a DTO is to act as a facade on top of the entity so that the implementation details (of the entity's structure) don't leak out to the consumer.
-However, the identity of the underlying entity can be well defined; Apache Isis defines the xref:../rgcms/rgcms.adoc#_rgcms_schema-common[Common schema] which defines the `<oid-dto>` element (and corresponding `OidDto` class): the object's type and its identifier.
-This is basically a formal XML equivalent to the `Bookmark` object obtained from the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`].
-
-There is only one requirement to make this work: every referenced domain entity must be annotated with xref:../rgant/rgant.adoc#_rgant-XmlJavaTypeAdapter[`@XmlJavaTypeAdapter`], specifying the framework-provided `PersistentEntityAdapter.class`.
-This class is similar to the `BookmarkService`: it knows how to create an `OidDto` from an object reference.
-
-Thus, in our view model we can legitimately write:
-
-[source,java]
-----
-package todoapp.app.viewmodels.todoitem.v1;
-...
-public class ToDoItemV1_1 implements Dto {
- ...
- @Getter @Setter
- protected ToDoItem toDoItem;
-}
-----
-
-All we need to do is remember to add that `@XmlJavaTypeAdapter` annotation to the referenced entity:
-
-[source,java]
-----
-@XmlJavaTypeAdapter(PersistentEntityAdapter.class)
-public class ToDoItem ... {
- ...
-}
-----
-
-
-It's also possible for a DTO to hold collections of objects.
-These can be of any type, either simple properties, or references to other objects.
-The only bit of boilerplate that is required is the `@XmlElementWrapper` annotation.
-This instructs JAXB to create an XML element (based on the field name) to contain each of the elements.
-(If this is omitted then the contents of the collection are at the same level as the properties; almost certainly not what is required).
-
-For example, the DTO also contains:
-
-[source,java]
-----
-package todoapp.app.viewmodels.todoitem.v1;
-...
-public class ToDoItemV1_1 implements Dto {
- ...
- @XmlElementWrapper
- @XmlElement(name = "todoItem")
- @Getter @Setter
- protected List<ToDoItem> similarItems = Lists.newArrayList();
-}
-----
-
-
-There's nothing to prevent a JAXB DTO from containing rich graphs of data, parent containing children containing children.
-Be aware though that all of this state will become the DTO's memento, ultimately converted into a URL-safe form, by way of the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_UrlEncodingService[`UrlEncodingService`].
-
-There are limits to the lengths of URLs, however.
-Therefore the DTO should not include state that can easily be derived from other information.
-If the URL does exceed limits, then provide a custom implementation of xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_UrlEncodingService[`UrlEncodingService`] to handle the memento string in some other fashion (eg substituting it with a GUID, with the memento cached somehow on the server).
-
-
-
-
-
-[[__ugbtb_view-models_jaxb_versioning]]
-== Versioning
-
-The whole point of using DTOs (in Apache Isis, at least) is to define a formal contact between two inter-operating but independent applications.
-Since the only thing we can predicate about the future with any certainty is that it one or both of these applications will change, we should version DTOs from the get-go.
-This allows us to make changes going forward without unnecessarily breaking existing consumers of the data.
-
-[NOTE]
-====
-There are several ways that versioning might be accomplished; we base our guidelines on this link:http://www.xfront.com/Versioning.pdf[article] taken from Roger Costello's blog, well worth a read.
-====
-
-We can distinguish two types of changes:
-
-* backwardly compatible changes
-* breaking changes.
-
-We can immediately say that the XSD namespace should change only when there is a major/breaking change, if following link:http://semver.org[semantic versioning] that means when we bump the major version number v1, v2, etc.
-
-XML namespaces correspond (when using JAXB) to Java packages.
-We should therefore place our DTOs in a package that contains only the major number; this package will eventually contain a range of DTOs that are intended to be backwardly compatible with one another.
-The package should also have a `package-info.java`; it is this that declares the XSD namespace:
-
-[source,java]
-----
-@javax.xml.bind.annotation.XmlSchema(
- namespace = "http://viewmodels.app.todoapp/todoitem/v1/Dto.xsd", // <1>
- xmlns = {
- @javax.xml.bind.annotation.XmlNs(
- namespaceURI = "http://isis.apache.org/schema/common",
- prefix = "com"
- )
- },
- elementFormDefault = javax.xml.bind.annotation.XmlNsForm.QUALIFIED
-)
-package todoapp.app.viewmodels.todoitem.v1; // <2>
-----
-<1> the namespace URI, used by the DTO residing in this package.
-<2> the package in which the DTO resides. Note that this contains only the major version.
-
-Although there is no requirement for the namespace URI to correspond to a physical URL, it should be unique.
-This usually means including a company domain name within the string.
-
-As noted above, this package will contain multiple DTO classes all with the same namespace; these represent a set of minor versions of the DTO, each subsequent one intended to be backwardly compatible with the previous.
-Since these DTO classes will all be in the same package (as per the xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_using-packages-to-version[advice above]), the class should therefore include the minor version name:
-
-[source,java]
-----
-package todoapp.app.viewmodels.todoitem.v1; // <1>
-...
-public class ToDoItemV1_1 implements Dto { // <2>
- ...
-}
-----
-<1> package contains the major version only
-<2> DTO class contains the (major and) minor version
-
-
-We also recommend that each DTO instance should also specify the version of the XSD schema that it is logically compatible with.
-Probably most consumers will not persist the DTOs; they will be processed and then discarded.
-However, it would be wrong to assume that is the case in all cases; some consumers might choose to persist the DTO (eg for replay at some later state).
-
-Thus:
-
-[source,java]
-----
-public class ToDoItemV1_1 implements Dto {
- @XmlElement(required = true, defaultValue = "1")
- public final String getMajorVersion() { return "1"; } // <1>
- @XmlElement(required = true, defaultValue = "1")
- public String getMinorVersion() { return "1"; } // <2>
- ...
-}
-----
-<1> returns the major version (in sync with the package)
-<2> returns the minor version (in sync with the class name)
-
-These methods always return a hard-coded literal.
-Any instances serialized from these classes will implicitly "declare" the (major and) minor version of the schema with which they are compatible.
-If a consumer has a minimum version that it requires, it can therefore inspect the XML instance itself to determine if it is able to consume said XML.
-
-If a new (minor) version of a DTO is required, then we recommend copying-and-pasting the previous version, eg:
-
-[source,java]
-----
-public class ToDoItemV1_2 implements Dto {
- @XmlElement(required = true, defaultValue = "1")
- public final String getMajorVersion() { return "1"; }
- @XmlElement(required = true, defaultValue = "2")
- public String getMinorVersion() { return "2"; }
- ...
-}
-----
-
-Obviously, only changes made must be backward compatible, eg new members must be optional.
-
-Alternatively, you might also consider simply editing the source file, ie renaming the class and bumping up the value returned by `getMinorVersion()`.
-
-We also _don't_ recommend using inheritance (ie `ToDoItemV1_2` should not inherit from `ToDoItemV1_1`; this creates unnecessary complexity downstream if generating XSDs and DTOs for the downstream consumer.
-
-
-[[__ugbtb_view-models_jaxb_generating-xsds-and-dtos]]
-== Generating XSDs and DTOs
-
-In the section xref:../ugbtb/ugbtb.adoc#__ugbtb_view-models_jaxb_referencing-domain-entities[above] it was explained how a view model DTO can transparent reference any "backing" entities; these references are converted to internal object identifiers.
-
-However, if the consumer of the XML is another Java process (eg running within an Apache Camel route), then you might be tempted/expect to be able to use the same DTO within that Java process.
-After a little thought though you'll realize that (duh!) of course you cannot; the consumer runs in a different process space, and will not have references to those containing entities.
-
-There are therefore two options:
-
-* either choose not to have the view model DTO reference any persistent entities, and simply limit the DTO to simple scalars. +
-+
-Such a DTO will then be usable in both the Apache Isis app (to generate the original XML) and in the consumer.
-The xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`] can be used to obtain the object identifiers
-
-* alternatively, generate a different DTO for the consumer from the XSD of the view model DTO.
-
-The (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] uses the second approach; generating the XSD and consumer's DTO is mostly just boilerplate `pom.xml` file.
-In the todoapp this can be found in the `todoapp-xsd` Maven module, whose `pom.xml` is structured as two profiles:
-
-[source,xml]
-----
-<project ... >
- <artifactId>todoapp-xsd</artifactId>
- <dependencies>
- <dependency>
- <groupId>${project.groupId}</groupId>
- <artifactId>todoapp-app</artifactId>
- </dependency>
- </dependencies>
- <profiles>
- <profile>
- <id>isis-xsd</id>
- <activation>
- <property>
- <name>!skip.isis-xsd</name>
- </property>
- </activation>
- ...
- </profile>
- <profile>
- <id>xjc</id>
- <activation>
- <property>
- <name>!skip.xjc</name>
- </property>
- </activation>
- ...
- </profile>
- </profiles>
-</project>
-----
-
-The `isis-xsd` profile generates the XSD using the xref:../rgmvn/rgmvn.adoc#_rgmvn_xsd[`xsd` goal] of Isis' maven plugin:
-
-[source,xml]
-----
-<build>
- <plugins>
- <plugin>
- <groupId>org.apache.isis.tool</groupId>
- <artifactId>isis-maven-plugin</artifactId>
- <version>${isis.version}</version>
- <configuration>
- <appManifest>todoapp.dom.ToDoAppDomManifest</appManifest>
- <jaxbClasses>
- <jaxbClass>todoapp.app.viewmodels.todoitem.v1.ToDoItemV1_1</jaxbClass>
- </jaxbClasses>
- <separate>false</separate>
- <commonSchemas>false</commonSchemas>
- </configuration>
- <dependencies>
- <dependency>
- <groupId>${project.groupId}</groupId>
- <artifactId>todoapp-dom</artifactId>
- <version>${project.version}</version>
- </dependency>
- <dependency>
- <groupId>com.google.guava</groupId>
- <artifactId>guava</artifactId>
- <version>16.0.1</version>
- </dependency>
- </dependencies>
- <executions>
- <execution>
- <phase>generate-sources</phase>
- <goals>
- <goal>xsd</goal>
- </goals>
- </execution>
- </executions>
- </plugin>
- <plugin>
- <artifactId>maven-assembly-plugin</artifactId>
- <version>2.5.3</version>
- <configuration>
- <descriptor>src/assembly/dep.xml</descriptor>
- </configuration>
- <executions>
- <execution>
- <id>create-archive</id>
- <phase>package</phase>
- <goals>
- <goal>single</goal>
- </goals>
- </execution>
- </executions>
- </plugin>
- </plugins>
-</build>
-----
-
-The `todoapp.dom.ToDoAppDomManifest` is a cut-down version of the app manifest that identifies only the `dom` domain services.
-
-The `xjc` profile, meanwhile, uses the `maven-jaxb2-plugin` (a wrapper around the `schemagen` JDK tool) to generate a DTO from the XSD generated by the preceding profile:
-
-[source,xml]
-----
-<build>
- <plugins>
- <plugin>
- <groupId>org.jvnet.jaxb2.maven2</groupId>
- <artifactId>maven-jaxb2-plugin</artifactId>
- <version>0.12.3</version>
- <executions>
- <execution>
- <id>xjc-generate</id>
- <phase>generate-sources</phase>
- <goals>
- <goal>generate</goal>
- </goals>
- </execution>
- </executions>
- <configuration>
- <removeOldOutput>true</removeOldOutput>
- <schemaDirectory>
- target/generated-resources/isis-xsd/viewmodels.app.todoapp
- </schemaDirectory>
- <schemaIncludes>
- <schemaInclude>todoitem/v1/Dto.xsd</schemaInclude>
- </schemaIncludes>
- <bindingDirectory>src/main/resources</bindingDirectory>
- <bindingIncludes>
- <bindingInclude>binding.xml</bindingInclude>
- </bindingIncludes>
- <catalog>src/main/resources/catalog.xml</catalog>
- </configuration>
- </plugin>
- <plugin>
- <groupId>org.codehaus.mojo</groupId>
- <artifactId>build-helper-maven-plugin</artifactId>
- <version>1.9.1</version>
- <executions>
- <execution>
- <id>add-source</id>
- <phase>generate-sources</phase>
- <goals>
- <goal>add-source</goal>
- </goals>
- <configuration>
- <sources>
- <source>target/generated-sources/xjc</source>
- </sources>
- </configuration>
- </execution>
- </executions>
- </plugin>
- </plugins>
-</build>
-----
http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_programming-model.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_programming-model.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_programming-model.adoc
deleted file mode 100644
index 2fd3a82..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_view-models_programming-model.adoc
+++ /dev/null
@@ -1,89 +0,0 @@
-[[_ugbtb_view-models_programming-model]]
-= Programming Model
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../../
-:_imagesdir: images/
-
-
-
-This section describes how to implement view models.
-
-Fundamentally all view models' state is serialized into
-a string memento; this memento is then held by the client (browser) in the form of a URL. As you might imagine, this
-URL can become quite long, but Apache Isis offers a mechanism (the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_UrlEncodingService[`UrlEncodingService`]) if it exceeds the maximum length for a URL
-(2083 characters). Also, of course, this string memento must only contain characters that it is valid for use within
-a URL.
-
-While the underlying technique is the same irrespective of use case, the programming model provides various ways of
-defining a view model so that the original intent is not lost. They are:
-
-.View model programming model
-[cols="1a,4a,2a", options="header"]
-|===
-
-| Use case
-| Code
-| Description
-
-
-| External entity
-|[source,java]
-----
-@DomainObject(nature=Nature.EXTERNAL_ENTITY)
-public class CustomerRecordOnSAP { ... }
-----
-|Annotated with xref:../rgant/rgant.adoc#_rgant-DomainObject_nature[`@DomainObject#nature()`] and a nature of `EXTERNAL_ENTITY`, with memento derived automatically from the properties of the domain object. Collections are ignored, as are any properties annotated as xref:../rgant/rgant.adoc#_rgant-Property_notPersisted[not persisted].
-
-| In-memory entity
-|[source,java]
-----
-@DomainObject(nature=Nature.INMEMORY_ENTITY)
-public class Log4JAppender { ... }
-----
-|As preceding, but using a nature of `INMEMORY_ENTITY`.
-
-|Application view model
-|[source,java]
-----
-@DomainObject(nature=Nature.VIEW_MODEL)
-public class Dashboard { ... }
-----
-|As preceding, but using a nature of `VIEW_MODEL`.
-
-|Application view model
-|
-[source,java]
-----
-@ViewModel
-public class Dashboard { ... }
-----
-
-|Annotated with xref:../rgant/rgant.adoc#_rgant-ViewModel[`@ViewModel`] annotation (effectively just an alias)' memento is as preceding: from "persisted" properties, collections ignored
-
-|Application view model
-|
-[source,java]
-----
-public class ExcelUploadManager implements ViewModel {
- public String viewModelMemento() { ... }
- public void viewModelInit(String memento) { ... }
-}
-|Implement xref:../rgcms/rgcms.adoc#_rgcms_classes_super_ViewModel[`ViewModel`] interface. The memento is as defined by the
-interface's methods: the programmer has full control (but also full responsibility) for the string memento.
-
-|DTO
-|
-[source,java]
-----
-@XmlRootElement("customer")
-public class CustomerDto { ... }
-----
-|Annotate using JAXB xref:../rgant/rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`] annotation. Memento
-derived automatically by serializing the XML graph as implied by the JAXB annotations. Note that (unlike `@ViewModel`
-et al) this state _can_ include collections.
-|===
-
-JAXB-annotated DTOs are discussed in more detail immediately xref:rg.adoc#_ugbtb_view-models_jaxb[below].
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugbtb/ugbtb.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/ugbtb.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/ugbtb.adoc
index c03eedb..3d3c365 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/ugbtb.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/ugbtb.adoc
@@ -43,7 +43,6 @@ The remaining guides are:
* xref:../cgcom/cgcom.adoc#[Committers' Guide] (release procedures and related practices)
-include::_ugbtb_view-models.adoc[leveloffset=+1]
include::_ugbtb_decoupling.adoc[leveloffset=+1]
include::_ugbtb_i18n.adoc[leveloffset=+1]
include::_ugbtb_headless-access.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_available-domain-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_available-domain-services.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_available-domain-services.adoc
new file mode 100644
index 0000000..1331977
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_available-domain-services.adoc
@@ -0,0 +1,18 @@
+[[_ugfun_available-domain-services]]
+= Available Domain Services
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+There are a number of domain services/modules already implemented for you to use directly within your applications.
+Some of these are provided by the framework, while others are third-party (but still open source).
+
+This chapter surveys some of the domain services currently available.
+
+
+include::_ugfun_available-domain-services_framework-provided.adoc[leveloffset=+1]
+include::_ugfun_available-domain-services_isis-addons.adoc[leveloffset=+1]
+include::_ugfun_available-domain-services_incode-catalog.adoc[leveloffset=+1]
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_available-domain-services_framework-provided.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_available-domain-services_framework-provided.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_available-domain-services_framework-provided.adoc
new file mode 100644
index 0000000..11a3622
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_available-domain-services_framework-provided.adoc
@@ -0,0 +1,107 @@
+[[_ugfun_available-domain-services_framework-provided]]
+= Framework-provided Services
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+Most framework domain services are API: they exist to provide support functionality to the application's domain objects and services.
+In this case an implementation of the service will be available, either by Apache Isis itself or by Isis Addons (non ASF).
+
+Some framework domain services are SPI: they exist primarily so that the application can influence the framework's behaviour.
+In these cases there is (usually) no default implementation; it is up to the application to provide an implementation.
+
+
+General purpose:
+
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`]; mostly deprecated, replaced by:
+** xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ClockService[`ClockService`]
+** xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ConfigurationService[`ConfigurationService`]
+** xref:../rgsvc/rgsvc.adoc#_rgsvc_api_MessageService[`MessageService`]
+** xref:../rgsvc/rgsvc.adoc#_rgsvc_api_RepositoryService[`RepositoryService`]
+** xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ServiceRegistry[`ServiceRegistry`]
+** xref:../rgsvc/rgsvc.adoc#_rgsvc_api_TitleService[`TitleService`]
+** xref:../rgsvc/rgsvc.adoc#_rgsvc_api_UserService[`UserService`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_IsisJdoSupport[`IsisJdoSupport`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EmailService[`EmailService`]
+
+Commands/Interactions/Background/Auditing/Publishing/Profiling:
+
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`] (SPI) (deprecated)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditerService[`AuditerService`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BackgroundService[`BackgroundService`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_BackgroundCommandService[`BackgroundCommandService`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`] (SPI) (deprecated)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublisherService[`PublishererService`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_MetricsService[`MetricsService`]
+
+
+Information Sharing:
+
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_Scratchpad[`Scratchpad`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ActionInvocationContext[`ActionInvocationContext`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_QueryResultsCache[`QueryResultsCache`]
+
+UserManagement:
+
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_UserProfileService[`UserProfileService`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_UserRegistrationService[`UserRegistrationService`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_EmailNotificationService[`EmailNotificationService`] (SPI)
+
+Bookmarks and Mementos:
+
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_MementoService[`MementoService`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DeepLinkService[`DeepLinkService`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_JaxbService[`JaxbService`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_XmlSnapshotService[`XmlSnapshotService`]
+
+Layout and UI Management:
+
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_GridLoaderService[`GridLoaderService`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_GridService[`GridService`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_GridSystemService[`GridSystemService`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_HomePageProviderService[`HomePageProviderService`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_HintStore[`HintStore`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_LayoutService[`LayoutService`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_RoutingService[`RoutingService`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_UrlEncodingService[`UrlEncodingService`] (SPI)
+
+REST Support:
+
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_AcceptHeaderService[`AcceptHeaderService`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_SwaggerService[`SwaggerService`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`] (SPI)
+
+Metamodel:
+
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ApplicationFeatureRepository[`ApplicationFeatureRepository`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_MetamodelService[`MetamodelService`]
+
+Other API:
+
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_FixtureScriptsDefault[`FixtureScriptsDefault`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_GuiceBeanProvider[`GuiceBeanProvider`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_SudoService[`SudoService`]
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_TransactionService[`TransactionService`]
+
+Other SPI:
+
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ClassDiscoveryService[`ClassDiscoveryService`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ErrorReportingService[`ErrorReportingService`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_EventSerializer[`EventSerializer`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ExceptionRecognizer[`ExceptionRecognizer`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_FixtureScriptsSpecificationProvider[`FixtureScriptsSpecificationProvider`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_LocaleProvider[`LocaleProvider`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_TranslationService[`TranslationService`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_TranslationsResolver[`TranslationsResolver`] (SPI)
+* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_TranslationsResolver[`TranslationsResolver`] (SPI)
+
+
+A full list of services can be found in the xref:../rgsvc/rgsvc.adoc#_rgsvc[Domain Services] reference guide.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_available-domain-services_incode-catalog.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_available-domain-services_incode-catalog.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_available-domain-services_incode-catalog.adoc
new file mode 100644
index 0000000..50bc834
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_available-domain-services_incode-catalog.adoc
@@ -0,0 +1,31 @@
+[[_ugfun_available-domain-services_incode-catalog]]
+= Incode Catalog
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+The link:http://catalog.incode.org[Incode Catalog] website also provides a number of reusable modules, focusing on business logic for generic subdomains.
+
+This section surveys the functionality available.
+
+
+[WARNING]
+====
+Note that the Incode Catalog, although maintained by Apache Isis committers, are not part of the ASF.
+====
+
+
+
+The modules themselves fall into a number of broader groups:
+
+* modules that provide standalone domain entities (and supporting services) for a particular subdomain +
++
+The http://github.com/incodehq/incode-module-alias[alias], http://github.com/incodehq/incode-module-classification[classification], http://github.com/incodehq/incode-module-commchannel[commchannel], http://github.com/incodehq/incode-module-communications[communications], http://github.com/incodehq/incode-module-country[country], http://github.com/incodehq/incode-module-docfragment[docfragment],
+http://github.com/incodehq/incode-module-document[document] and http://github.com/incodehq/incode-module-document[note] modules fall into this category.
+
+* modules that provide developer/testing utilities +
++
+The http://github.com/incodehq/incode-module-fixturesupport[fixturesupport], http://github.com/incodehq/incode-module-integtestsupport[integtestsupport] and http://github.com/incodehq/incode-module-unittestsupport[unittestsupport] modules fall into this category.
+
+Each of the modules has a full README and demo application demonstrating their usage. The sections below briefly outline the capabilities of these modules.
http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_available-domain-services_isis-addons.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_available-domain-services_isis-addons.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_available-domain-services_isis-addons.adoc
new file mode 100644
index 0000000..d7906a3
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_available-domain-services_isis-addons.adoc
@@ -0,0 +1,41 @@
+[[_ugfun_available-domain-services_isis-addons]]
+= Isis Add-ons
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+The link:http://www.isisaddons.org[Isis Addons] website provides a number of reusable modules for Apache Isis, focusing either on specific technologies or in technical cross-cutting concerns.
+Some of these modules implement SPIs defined by the framework.
+
+
+[WARNING]
+====
+Note that Isis Addons, although maintained by Apache Isis committers, are not part of the ASF.
+====
+
+
+
+The modules themselves fall into a number of broader groups:
+
+* modules that provide an implementations of SPI defined by Apache Isis +
++
+where Apache Isis has hooks to use the service if defined by provides no implementations of its own. +
++
+The http://github.com/isisaddons/isis-module-command[command], http://github.com/isisaddons/isis-module-audit[auditer], http://github.com/isisaddons/isis-module-publishmq[publisher], http://github.com/isisaddons/isis-module-security[security] and http://github.com/isisaddons/isis-module-sessionlogger[sessionlogger] modules fall into this category. Typically the domain objects themselves wouldn't interact with these services
+
+* modules that provide standalone domain services with their own API and implementation +
++
+These are simply intended to be used by domain objects. +
++
+The http://github.com/isisaddons/isis-module-docx[docx], http://github.com/isisaddons/isis-module-excel[excel], http://github.com/isisaddons/isis-module-freemarker[freemarker], http://github.com/isisaddons/isis-module-pdfbox[pdfbox], http://github.com/isisaddons/isis-module-settings[settings], http://github.com/isisaddons/isis-module-servletapi[servletapi], http://github.com/isisaddons/isis-module-stringinterpolator[stringinterpolator] and http://github.com/isisaddons/isis-module-xdocreport[xdocreport] fall into this category.
+
+* modules that provide standalone domain entities (and supporting services) for a particular subdomain +
++
+The http://github.com/isisaddons/isis-module-tags[tags] module falls into this category
+
+* modules that provide developer/testing utilities +
++
+The http://github.com/isisaddons/isis-module-fakedata[fakedata] module provides fakedata for unit- and integration testing.
+
+Each of the modules has a full README and demo application demonstrating their usage. The sections below briefly outline the capabilities of these modules.
http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/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
new file mode 100644
index 0000000..8c61796
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks.adoc
@@ -0,0 +1,23 @@
+[[_ugfun_building-blocks]]
+= Building Blocks
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+In this section we run through the main building blocks that make up an Apache Isis application.
+
+include::_ugfun_building-blocks_metamodel.adoc[leveloffset=+1]
+
+include::_ugfun_building-blocks_types-of-domain-objects.adoc[leveloffset=+1]
+
+include::_ugfun_building-blocks_identifiers.adoc[leveloffset=+1]
+
+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]
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/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
new file mode 100644
index 0000000..ded8c28
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_events.adoc
@@ -0,0 +1,79 @@
+[[_ugfun_building-blocks_events]]
+= 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/
+
+
+When the framework renders a domain object, and as the end-user interacts with the domain object, the framework it emits multiple events using the intra-process xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[event bus].
+These events enable other domain services (possibly in other modules) to influence how the domain object is rendered, or to perform side-effects or even veto an action invocation.
+
+[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
+====
+
+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.
+
+The framework has several categories of events: domain events, UI events and lifecycle events.
+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
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/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
new file mode 100644
index 0000000..c0bc698
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_identifiers.adoc
@@ -0,0 +1,14 @@
+[[_ugfun_building-blocks_identifiers]]
+= Identifiers
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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
+
+
+
+include::_ugfun_building-blocks_identifiers_title-and-icon.adoc[leveloffset=+1]
+
+include::_ugfun_building-blocks_identifiers_oid.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_identifiers_oid.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_identifiers_oid.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_identifiers_oid.adoc
new file mode 100644
index 0000000..b4df70a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_identifiers_oid.adoc
@@ -0,0 +1,47 @@
+[[_ugfun_building-blocks_identifiers_oid]]
+= OIDs
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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 well as defining a xref:../ugfun/ugfun.adoc#__ugfun_building-blocks_metamodel[metamodel] of the structure (domain classes) of its domain objects, Apache Isis also manages the runtime instances of said domain objects.
+
+When a domain entity is recreated from the database, the framework keeps track of its identity through an "OID": an object identifier.
+Fundamentally this is a combination of its type (domain class), along with an identifier.
+You can think of it as its "primary key", except across all domain entity types.
+
+For portability and resilience, though, the object type is generally an alias for the actual domain class: thus "customers.CUS", say, rather than "com.mycompany.myapp.customers.Customer".
+This is derived from an annotation.
+The identifier meanwhile is always converted to a string.
+
+Although simple, the OID is an enormously powerful concept: it represents a URI to any domain object managed by a given Apache Isis application.
+With it, we have the ability to lookup any arbitrary domain objects.
+
+Some examples:
+
+* an OID allows sharing of information between users, eg as a deep link to be pasted into an email.
+
+* the information within an OID could be converted into a barcode, and stamped onto a PDF form.
+When the PDF is scanned by the mail room, the barcode could be read to attach the correspondence to the relevant domain object.
+
+* as a handle to any object in an audit record, as used by xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditerService[`AuditerService`] or xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`] (the latter deprecated);
+
+* similarly within implementations of xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] to persist `Command`
+objects
+
+* similarly within implementations of xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`]
+to persist published action invocations
+
+* and of course both the xref:../ugvro/ugvro.adoc#[RestfulObjects viewer] and
+xref:../ugvw/ugvw.adoc#[Wicket viewer]
+use the oid tuple to look up, render and allow the user to interact with domain objects.
+
+Although the exact content of an OID should be considered opaque by domain objects, it is possible for domain objects to obtain OIDs.
+These are represented as `Bookmark`s, obtained from the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`].
+Deep links meanwhile can be obtained from the xref:../rgant/rgant.adoc#_rgant-DeepLinkService[`@DeepLinkService`].
+
+OIDs can also be converted into XML format, useful for integration scenarios.
+The xref:../rgcms/rgcms.adoc#_rgcms_schema-common[common schema] XSD defines the `oidDto` complex type for precisely this purpose.
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/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
new file mode 100644
index 0000000..356abe8
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_identifiers_title-and-icon.adoc
@@ -0,0 +1,27 @@
+[[_ugfun_building-blocks_identifiers_title-and-icon]]
+= Title and Icon
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 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
+
+
+
+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.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_metamodel.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_metamodel.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_metamodel.adoc
new file mode 100644
index 0000000..7d5731b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_metamodel.adoc
@@ -0,0 +1,32 @@
+[[_ugfun_building-blocks_metamodel]]
+= A MetaModel
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+At its core, Apache Isis is a metamodel that is built at runtime from the domain classes (eg `Customer.java`), along with optional supporting metadata (eg `Customer.layout.xml`).
+
+The contents of this metamodel is inferred from the Java classes discovered on the classpath: the entities and supporting services, as well the members of those classes.
+The detail of the metamodel is generally explicit, usually represented by Java annotations such as `@Title` or `@Action`.
+Notably the metamodel is xref:../ugbtb/ugbtb.adoc#_ugbtb_programming-model[extensible]; it is possible to teach Apache Isis new programming conventions/rules (and conversely to remove those that are built in).
+
+Most of the annotations recognized by the framework are defined by the Apache Isis framework itself.
+For example the `@Title` annotation -- which identifies how the framework should derive a human-readable label for each rendered domain object -- is part of the `org.apache.isis.applib.annotations` package.
+However the framework also recognizes certain other JEE annotations such as `@javax.inject.Inject` (used for dependency injection).
+
+The framework uses DataNucleus for its persistence mechanism.
+This is an ORM that implements the JDO and JPA APIs, and which can map domain objects either to an RDBMS or to various NoSQL objectstores such as MongoDB or Neo4J.
+Apache Isis recognizes a number of the JDO annotations such as `@javax.jdo.annotations.Column(allowsNull=...)`.
+
+In addition, the framework builds up the metamodel for each domain object using
+xref:../ugvw/ugvw.adoc#_ugvw_layout[layout hints], such as `Customer.layout.xml`.
+These provide metadata such as grouping elements of the UI together, using multi-column layouts, and so on.
+The layout file can be modified while the application is still running, and are picked up automatically; a useful way to speed up feedback.
+
+[TIP]
+====
+At the time of writing Apache Isis only recognizes and supports the JDO API, though we expect JPA to be supported in the future.
+====
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/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
new file mode 100644
index 0000000..40dbca0
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_modules.adoc
@@ -0,0 +1,15 @@
+[[_ugfun_building-blocks_modules]]
+= Modules
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+We tend to use Maven modules as a way to group related domain objects together; we can then reason about all the classes in that module as a single unit.
+By convention there will be a single top-level package corresponding to the module.
+
+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.
+
+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.
+