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 2019/09/20 07:28:40 UTC
[isis] 02/03: ISIS-2062: ug fun building-blocks chapter now one page
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch v2
in repository https://gitbox.apache.org/repos/asf/isis.git
commit 9ef2bb4270e2012e929243f88faae2073d6f1a94
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Wed Sep 18 21:58:35 2019 +0200
ISIS-2062: ug fun building-blocks chapter now one page
---
.../modules/dg/pages/working-with-many-repos.adoc | 2 +-
.../_partials/_powered-by_gesconsultor-grc.adoc | 2 +-
.../pages/what-is-apache-isis/screencasts.adoc | 6 +--
.../modules/ant/pages/DomainObject/nature.adoc | 3 +-
.../pages/DomainObjectLayout/cssClassUiEvent.adoc | 4 +-
.../ant/pages/DomainObjectLayout/iconUiEvent.adoc | 4 +-
.../ant/pages/DomainObjectLayout/titleUiEvent.adoc | 4 +-
core/_adoc-rg/modules/ant/pages/Mixin.adoc | 2 +-
core/_adoc-rg/modules/ant/pages/PostConstruct.adoc | 2 +-
.../modules/ant/pages/XmlJavaTypeAdapter.adoc | 2 +-
.../_adoc-rg/modules/ant/pages/XmlRootElement.adoc | 53 ++++++++--------------
.../modules/cfg/pages/configuring-core.adoc | 2 +-
.../_adoc-rg/modules/cms/pages/classes/mixins.adoc | 2 +-
.../modules/cms/pages/classes/mixins/Dto.adoc | 2 +-
.../cms/pages/methods/prefixes/disable.adoc | 2 +-
.../modules/cms/pages/methods/prefixes/hide.adoc | 2 +-
core/_adoc-rg/modules/cms/pages/schema/common.adoc | 3 +-
.../ContentNegotiationService.adoc | 2 +-
core/_adoc-rg/modules/mvn/pages/xsd.adoc | 2 +-
.../svc/pages/core-domain-api/Scratchpad.adoc | 2 +-
.../svc/pages/integration-api/JaxbService.adoc | 2 +-
.../svc/pages/integration-api/MementoService.adoc | 2 +-
.../svc/pages/metadata-api/SwaggerService.adoc | 2 +-
.../presentation-layer-spi/UrlEncodingService.adoc | 2 +-
.../btb/pages/hints-and-tips/pushing-changes.adoc | 2 +-
core/_adoc-ug/modules/fun/nav.adoc | 29 +-----------
.../modules/fun/pages/building-blocks.adoc | 33 +++++++++++++-
.../pages/building-blocks/events/ui-events.adoc | 4 +-
.../fun/pages/building-blocks/identifiers/oid.adoc | 2 +-
.../types-of-domain-objects/domain-services.adoc | 2 +-
.../types-of-domain-objects/view-models.adoc | 2 +-
.../_adoc-ug/modules/fun/pages/business-rules.adoc | 2 +-
.../pages/core-concepts/apache-isis-vs/cqrs.adoc | 4 +-
.../fun/pages/core-concepts/philosophy/aop.adoc | 2 +-
core/_adoc-ug/modules/fun/pages/crud.adoc | 4 +-
core/_adoc-ug/modules/fun/pages/crud/deleting.adoc | 2 +-
core/_adoc-ug/modules/fun/pages/crud/finding.adoc | 2 +-
.../modules/fun/pages/crud/instantiating.adoc | 4 +-
.../modules/fun/pages/crud/persisting.adoc | 2 +-
core/_adoc-ug/modules/fun/pages/crud/updating.adoc | 2 +-
.../domain-services/event-subscribers.adoc | 2 +-
.../fun/pages/programming-model/mixins.adoc | 2 +-
.../fun/pages/programming-model/view-models.adoc | 2 +-
.../pages/programming-model/view-models/jaxb.adoc | 2 +-
44 files changed, 104 insertions(+), 113 deletions(-)
diff --git a/antora/components/support/modules/dg/pages/working-with-many-repos.adoc b/antora/components/support/modules/dg/pages/working-with-many-repos.adoc
index 19d8fb4..94acb94 100644
--- a/antora/components/support/modules/dg/pages/working-with-many-repos.adoc
+++ b/antora/components/support/modules/dg/pages/working-with-many-repos.adoc
@@ -7,7 +7,7 @@ include::_attributes.adoc[]
Applications built with Apache Isis often (should) consist of multiple modules.
For example, there are the various modules that make up the (non-ASF) link:http://platform.incode.org[Incode Platform^] that provide various technical/cross-cutting concerns and generic business functionality.
-In addition, your own application may well be structured as a number of distinct modules (probably with the entities in each module being mapped to a different schema), and using such techniques as the xref:ug:fun:building-blocks/events/domain-events.adoc[event bus] and xref:ug:fun:building-blocks/types-of-domain-objects/mixins.adoc[mixins] so that these modules are decoupled from each other.
+In addition, your own application may well be structured as a number of distinct modules (probably with the entities in each module being mapped to a different schema), and using such techniques as the xref:ug:fun:building-blocks.adoc#domain-events[event bus] and xref:ug:fun:building-blocks.adoc#mixins[mixins] so that these modules are decoupled from each other.
All of which is a preamble to say that you will likely have multiple directories on your local development computer, for each such git repository that you contribute to.
diff --git a/antora/components/toc/modules/ROOT/pages/_partials/_powered-by_gesconsultor-grc.adoc b/antora/components/toc/modules/ROOT/pages/_partials/_powered-by_gesconsultor-grc.adoc
index 8fe438f..74697f9 100644
--- a/antora/components/toc/modules/ROOT/pages/_partials/_powered-by_gesconsultor-grc.adoc
+++ b/antora/components/toc/modules/ROOT/pages/_partials/_powered-by_gesconsultor-grc.adoc
@@ -78,7 +78,7 @@ We chose http://wavemaker.com[Wavemaker] for implementing the viewer, also lever
Even so, while GRC does (as the figures above show) include custom views, the majority of the views exposed by GRC are automatically generated from the underlying domain entities; the GRC viewer is a proprietary version of Isis' own xref:vw:ROOT:about.adoc[Wicket viewer].
At the last count more than 400 domain entities, across 6 different Bounded Contexts, are surfaced in the UI in this this way.
-At the Domain level, we also extensively use the xref:ug:fun:building-blocks/events/domain-events.adoc[domain events] functionality available in Apache Isis, along with many of the (non-ASF) link:http://platform.incode.org[Incode Platform^] (such as audit, security and excel modules).
+At the Domain level, we also extensively use the xref:ug:fun:building-blocks.adoc#domain-events[domain events] functionality available in Apache Isis, along with many of the (non-ASF) link:http://platform.incode.org[Incode Platform^] (such as audit, security and excel modules).
The GRC platform currently has more than 5600 automated tests, about 2000 being xref:testing:ROOT:bdd-spec-support.adoc[BDD tests] and 3600 xref:testing:ROOT:integ-test-support.adoc[integration tests], all leveraging Apache Isis' extensive testing capabilities.
diff --git a/antora/components/toc/modules/ROOT/pages/what-is-apache-isis/screencasts.adoc b/antora/components/toc/modules/ROOT/pages/what-is-apache-isis/screencasts.adoc
index 0c874c4..97e6473 100644
--- a/antora/components/toc/modules/ROOT/pages/what-is-apache-isis/screencasts.adoc
+++ b/antora/components/toc/modules/ROOT/pages/what-is-apache-isis/screencasts.adoc
@@ -240,19 +240,19 @@ include::partial$_screencasts-playlists.adoc[]
|link:https://www.youtube.com/watch?v=Wn5215K7_Jg[022^] +
-Shows how to refactor a domain object to move an action implementation out of the domain object itself, and instead implement as a xref:ug:fun:building-blocks/types-of-domain-objects/mixins.adoc[mixin] (useful for decoupling).
+Shows how to refactor a domain object to move an action implementation out of the domain object itself, and instead implement as a xref:ug:fun:building-blocks.adoc#mixins[mixin] (useful for decoupling).
|x|||||x|||||
|link:https://www.youtube.com/watch?v=m633OEBpWqQ[023^] +
-Shows how to refactor a domain object to move (derived) collections out of the domain object and reimplement as a xref:ug:fun:building-blocks/types-of-domain-objects/mixins.adoc[mixin].
+Shows how to refactor a domain object to move (derived) collections out of the domain object and reimplement as a xref:ug:fun:building-blocks.adoc#mixins[mixin].
||||||x|||||
|link:https://www.youtube.com/watch?v=-AQJb9GtIqI[024^] +
-Using a domain event xref:rg:cms:classes/super/AbstractSubscriber.adoc[subscriber] to xref:ug:fun:building-blocks/events/domain-events.adoc[decouple] and abstract business rules (xref:rg:cms:methods/prefixes/validate.adoc[validation]).
+Using a domain event xref:rg:cms:classes/super/AbstractSubscriber.adoc[subscriber] to xref:ug:fun:building-blocks.adoc#domain-events[decouple] and abstract business rules (xref:rg:cms:methods/prefixes/validate.adoc[validation]).
||||||x|||||
diff --git a/core/_adoc-rg/modules/ant/pages/DomainObject/nature.adoc b/core/_adoc-rg/modules/ant/pages/DomainObject/nature.adoc
index 15db57c..14ec904 100644
--- a/core/_adoc-rg/modules/ant/pages/DomainObject/nature.adoc
+++ b/core/_adoc-rg/modules/ant/pages/DomainObject/nature.adoc
@@ -46,7 +46,8 @@ The framework will automatically recreate the domain object each time it is inte
+
indicates that the domain object is part of the domain layer, and is contributing behaviour to objects of some other type as a mixin (also known as a trait).
+
-Equivalent to annotating with xref:rg:ant:Mixin.adoc[`@Mixin`]. For further discussion on using mixins, see xref:ug:fun:building-blocks/types-of-domain-objects/mixins.adoc[mixins] in the user guide.
+Equivalent to annotating with xref:rg:ant:Mixin.adoc[`@Mixin`].
+For further discussion on using mixins, see xref:ug:fun:building-blocks.adoc#mixins[mixins] in the user guide.
* `VIEW_MODEL` +
diff --git a/core/_adoc-rg/modules/ant/pages/DomainObjectLayout/cssClassUiEvent.adoc b/core/_adoc-rg/modules/ant/pages/DomainObjectLayout/cssClassUiEvent.adoc
index de78892..e8579df 100644
--- a/core/_adoc-rg/modules/ant/pages/DomainObjectLayout/cssClassUiEvent.adoc
+++ b/core/_adoc-rg/modules/ant/pages/DomainObjectLayout/cssClassUiEvent.adoc
@@ -12,8 +12,8 @@ From this they can, if they wish, specify a CSS class for the domain object usin
[NOTE]
====
-The feature was originally introduced so that xref:rg:ant:XmlRootElement.adoc[`@XmlRootElement`]-annotated xref:ug:fun:building-blocks/types-of-domain-objects/view-models.adoc[view model]s could be kept as minimal as possible, just defining the data.
-UI events allow subscribers to provide UI hints, while xref:ug:fun:building-blocks/types-of-domain-objects/mixins.adoc[mixin]s can be used to provide the behaviour.
+The feature was originally introduced so that xref:rg:ant:XmlRootElement.adoc[`@XmlRootElement`]-annotated xref:ug:fun:building-blocks.adoc#view-models[view model]s could be kept as minimal as possible, just defining the data.
+UI events allow subscribers to provide UI hints, while xref:ug:fun:building-blocks.adoc#mixins[mixin]s can be used to provide the behaviour.
====
By default the event raised is `CssClassUiEvent.Default`.
diff --git a/core/_adoc-rg/modules/ant/pages/DomainObjectLayout/iconUiEvent.adoc b/core/_adoc-rg/modules/ant/pages/DomainObjectLayout/iconUiEvent.adoc
index aa26eb3..e7f92e5 100644
--- a/core/_adoc-rg/modules/ant/pages/DomainObjectLayout/iconUiEvent.adoc
+++ b/core/_adoc-rg/modules/ant/pages/DomainObjectLayout/iconUiEvent.adoc
@@ -13,8 +13,8 @@ From this they can, if they wish, specify an icon name for the domain object usi
[NOTE]
====
-The feature was originally introduced so that xref:rg:ant:XmlRootElement.adoc[`@XmlRootElement`]-annotated xref:ug:fun:building-blocks/types-of-domain-objects/view-models.adoc[view model]s could be kept as minimal as possible, just defining the data.
-UI events allow subscribers to provide UI hints, while xref:ug:fun:building-blocks/types-of-domain-objects/mixins.adoc[mixin]s can be used to provide the behaviour.
+The feature was originally introduced so that xref:rg:ant:XmlRootElement.adoc[`@XmlRootElement`]-annotated xref:ug:fun:building-blocks.adoc#view-models[view model]s could be kept as minimal as possible, just defining the data.
+UI events allow subscribers to provide UI hints, while xref:ug:fun:building-blocks.adoc#mixins[mixin]s can be used to provide the behaviour.
====
By default the event raised is `IconUiEvent.Default`.
diff --git a/core/_adoc-rg/modules/ant/pages/DomainObjectLayout/titleUiEvent.adoc b/core/_adoc-rg/modules/ant/pages/DomainObjectLayout/titleUiEvent.adoc
index ccd673c..7acb03b 100644
--- a/core/_adoc-rg/modules/ant/pages/DomainObjectLayout/titleUiEvent.adoc
+++ b/core/_adoc-rg/modules/ant/pages/DomainObjectLayout/titleUiEvent.adoc
@@ -13,8 +13,8 @@ From this they can, if they wish, specify a title for the domain object using th
[NOTE]
====
-The feature was originally introduced so that xref:rg:ant:XmlRootElement.adoc[`@XmlRootElement`]-annotated xref:ug:fun:building-blocks/types-of-domain-objects/view-models.adoc[view model]s could be kept as minimal as possible, just defining the data.
-UI events allow subscribers to provide UI hints, while xref:ug:fun:building-blocks/types-of-domain-objects/mixins.adoc[mixin]s can be used to provide the behaviour.
+The feature was originally introduced so that xref:rg:ant:XmlRootElement.adoc[`@XmlRootElement`]-annotated xref:ug:fun:building-blocks.adoc#view-models[view model]s could be kept as minimal as possible, just defining the data.
+UI events allow subscribers to provide UI hints, while xref:ug:fun:building-blocks.adoc#mixins[mixin]s can be used to provide the behaviour.
====
By default the event raised is `TitleUiEvent.Default`.
diff --git a/core/_adoc-rg/modules/ant/pages/Mixin.adoc b/core/_adoc-rg/modules/ant/pages/Mixin.adoc
index e14dc78..634898b 100644
--- a/core/_adoc-rg/modules/ant/pages/Mixin.adoc
+++ b/core/_adoc-rg/modules/ant/pages/Mixin.adoc
@@ -9,7 +9,7 @@ The `@Mixin` annotation indicates that the class acts as a mixin, contributing b
Mixins were originally introduced as a means of allowing contributions from one module to the types of another module; in such cases the mixin type is often an interface type (eg `DocumentHolder`) that might be implemented by numerous different concrete types.
However, mixins are also a convenient mechanism for grouping functionality even for a concrete type.
-For further discussion on using mixins, see xref:ug:fun:building-blocks/types-of-domain-objects/mixins.adoc[mixins] in the user guide.
+For further discussion on using mixins, see xref:ug:fun:building-blocks.adoc#mixins[mixins] in the user guide.
The table below summarizes the annotation's attributes.
diff --git a/core/_adoc-rg/modules/ant/pages/PostConstruct.adoc b/core/_adoc-rg/modules/ant/pages/PostConstruct.adoc
index 1fc872b..1044c7e 100644
--- a/core/_adoc-rg/modules/ant/pages/PostConstruct.adoc
+++ b/core/_adoc-rg/modules/ant/pages/PostConstruct.adoc
@@ -5,7 +5,7 @@ include::_attributes.adoc[]
The `@javax.annotation.PostConstruct` annotation, as defined in link:https://jcp.org/en/jsr/detail?id=250[JSR-250], is recognized by Apache Isis as a callback method on domain services to be called just after they have been constructed, in order that they initialize themselves.
-It is also recognized for xref:ug:fun:building-blocks/types-of-domain-objects/view-models.adoc[view models] (eg annotated with xref:rg:ant:ViewModel.adoc[`@ViewModel`]).
+It is also recognized for xref:ug:fun:building-blocks.adoc#view-models[view models] (eg annotated with xref:rg:ant:ViewModel.adoc[`@ViewModel`]).
For the default application-scoped (singleton) domain services, this means that the method, if present, is called during the bootstrapping of the application. For xref:rg:ant:RequestScoped.adoc[`@RequestScoped`] domain services, the method is called at the beginning of the request.
diff --git a/core/_adoc-rg/modules/ant/pages/XmlJavaTypeAdapter.adoc b/core/_adoc-rg/modules/ant/pages/XmlJavaTypeAdapter.adoc
index 72cf48f..af3ee22 100644
--- a/core/_adoc-rg/modules/ant/pages/XmlJavaTypeAdapter.adoc
+++ b/core/_adoc-rg/modules/ant/pages/XmlJavaTypeAdapter.adoc
@@ -20,6 +20,6 @@ public class ToDoItem ... {
This annotation therefore allows view models/DTOs to have references to persistent entities; a common idiom.
-For a more complete discussion of writing JAXB view models/DTOs, see xref:ug:fun:building-blocks/types-of-domain-objects/view-models.adoc[this topic]
+For a more complete discussion of writing JAXB view models/DTOs, see xref:ug:fun:building-blocks.adoc#view-models[this topic]
in the user guide.
diff --git a/core/_adoc-rg/modules/ant/pages/XmlRootElement.adoc b/core/_adoc-rg/modules/ant/pages/XmlRootElement.adoc
index d695788..afcaa42 100644
--- a/core/_adoc-rg/modules/ant/pages/XmlRootElement.adoc
+++ b/core/_adoc-rg/modules/ant/pages/XmlRootElement.adoc
@@ -3,44 +3,33 @@
include::_attributes.adoc[]
-The `@XmlRootElement` annotation provides an alternative way to define a
-xref:ug:fun:building-blocks/types-of-domain-objects/view-models.adoc[view model], in particular one intended to act as a DTO for use within
-xref:vro:ROOT::about.adoc[RestfulObjects viewer], or which contains arbitrarily complex state.
+The `@XmlRootElement` annotation provides an alternative way to define a xref:ug:fun:building-blocks.adoc#view-models[view model], in particular one intended to act as a DTO for use within xref:vro:ROOT::about.adoc[RestfulObjects viewer], or which contains arbitrarily complex state.
-A view model is a non-persisted domain object whose state is converted to/from a string memento. In the case of a
-JAXB-annotated object this memento is its XML representation. JAXB generally requires that the root element of the
-XML representation is annotated with `@XmlRootElement`. Apache Isis makes this a mandatory requirement.
+A view model is a non-persisted domain object whose state is converted to/from a string memento.
+In the case of a JAXB-annotated object this memento is its XML representation.
+JAXB generally requires that the root element of the XML representation is annotated with `@XmlRootElement`.
+Apache Isis makes this a mandatory requirement.
-In comparison to using either the xref:rg:cms:classes/super/ViewModel.adoc[`ViewModel`] interface or the
-xref:rg:ant:ViewModel.adoc[`@ViewModel`] annotation, using `@XmlRootElement` has a couple of
-significant advantages:
+In comparison to using either the xref:rg:cms:classes/super/ViewModel.adoc[`ViewModel`] interface or the xref:rg:ant:ViewModel.adoc[`@ViewModel`] annotation, using `@XmlRootElement` has a couple of significant advantages:
-* the view model can be used as a "canonical" DTO, for example when accessing data using the
-xref:vro:ROOT::about.adoc[RestfulObjects viewer] in combination with the
-xref:rg:svc:presentation-layer-spi/ContentMappingService.adoc[`ContentMappingService`]. +
+* the view model can be used as a "canonical" DTO, for example when accessing data using the xref:vro:ROOT::about.adoc[RestfulObjects viewer] in combination with the
+xref:rg:svc:presentation-layer-spi/ContentMappingService.adoc[`ContentMappingService`].
+
-This provides a stable and
-versioned API to access data in XML format using whatever client-side technology may be appropriate.
+This provides a stable and versioned API to access data in XML format using whatever client-side technology may be appropriate.
-* the XML graph can be as deep as required; in particular it can contain collections of other objects. +
+* the XML graph can be as deep as required; in particular it can contain collections of other objects.
+
In contrast, if the `@ViewModel` annotation is used then only the state of the properties (not collections) is captured.
-If using `ViewModel` interface then arbitrary state (including that of collections), however the programmer must write
-all the code by hand
+If using `ViewModel` interface then arbitrary state (including that of collections), however the programmer must write all the code by hand
-The main disadvantages of using JAXB-annotated view models is that any referenced persistent entity must be annotated
-with the xref:rg:ant:XmlJavaTypeAdapter.adoc[`@XmlJavaTypeAdapter`], using the
-framework-provided `PersistentEntityAdapter`. This adapter converts any references to such domain entities using the
-`oidDto` complex type (as defined by the Apache Isis xref:rg:cms:schema/common.adoc[common schema]):
-the object's type and its identifier.
+The main disadvantages of using JAXB-annotated view models is that any referenced persistent entity must be annotated with the xref:rg:ant:XmlJavaTypeAdapter.adoc[`@XmlJavaTypeAdapter`], using the framework-provided `PersistentEntityAdapter`.
+This adapter converts any references to such domain entities using the `oidDto` complex type (as defined by the Apache Isis xref:rg:cms:schema/common.adoc[common schema]): the object's type and its identifier.
[TIP]
====
-The memento string for view models is converted into a form compatible with use within a URL. This is performed by the
-xref:rg:svc:presentation-layer-spi/UrlEncodingService.adoc[`UrlEncodingService`], the default implementation of which
-simply encodes to base 64. If the view model XML graph is too large to be serialized to a string, then an alternative
-implementation (eg which maps XML strings to a GUID, say) can be configured using the technique described in
-xref:ug:btb:hints-and-tips/replacing-default-service-implementations.adoc[here] in the user guide.
+The memento string for view models is converted into a form compatible with use within a URL.
+This is performed by the xref:rg:svc:presentation-layer-spi/UrlEncodingService.adoc[`UrlEncodingService`], the default implementation of which simply encodes to base 64.
+If the view model XML graph is too large to be serialized to a string, then an alternative implementation (eg which maps XML strings to a GUID, say) can be configured using the technique described in xref:ug:btb:hints-and-tips/replacing-default-service-implementations.adoc[here] in the user guide.
====
@@ -69,13 +58,9 @@ public class ToDoItemDto implements Dto {
== See also
-Although (like any other viewmodel) a JAXB-annotated can have behaviour (actions) and UI hints, you may wish to keep
-the DTO "clean", just focused on specifying the data contract.
+Although (like any other viewmodel) a JAXB-annotated can have behaviour (actions) and UI hints, you may wish to keep the DTO "clean", just focused on specifying the data contract.
-Behaviour can therefore be provided using xref:ug:fun:building-blocks/types-of-domain-objects/mixins.adoc[mixins] (annotated with
-xref:rg:ant:Mixin.adoc[`@Mixin`]), while xref:rg:cms:classes/uievent.adoc[UI events] can be used
-to obtain title, icons and so on.
+Behaviour can therefore be provided using xref:ug:fun:building-blocks.adoc#mixins[mixins] (annotated with xref:rg:ant:Mixin.adoc[`@Mixin`]), while xref:rg:cms:classes/uievent.adoc[UI events] can be used to obtain title, icons and so on.
-For a more complete discussion of writing JAXB view models/DTOs, see xref:ug:fun:building-blocks/types-of-domain-objects/view-models.adoc[this topic]
-in the user guide.
+For a more complete discussion of writing JAXB view models/DTOs, see xref:ug:fun:building-blocks.adoc#view-models[this topic] in the user guide.
diff --git a/core/_adoc-rg/modules/cfg/pages/configuring-core.adoc b/core/_adoc-rg/modules/cfg/pages/configuring-core.adoc
index ea89b88..7b0c916 100644
--- a/core/_adoc-rg/modules/cfg/pages/configuring-core.adoc
+++ b/core/_adoc-rg/modules/cfg/pages/configuring-core.adoc
@@ -514,7 +514,7 @@ This is by way of possibly deprecating and eventually moving contributed service
| When searching for xref:rg:cms:methods/prefixes/disable.adoc[`disableXxx()`] or xref:rg:cms:methods/prefixes/hide.adoc[`hideXxx()`] methods, whether to search only for the no-param version (or also for supporting methods that match the parameter types of the action). +
If enabled then will not search for supporting methods with the exact set of arguments as the method it was supporting (and any supporting methods that have additional parameters will be treated as invalid).
-Note that this in effect means that xref:ug:fun:building-blocks/types-of-domain-objects/mixins.adoc[mixins] must be used instead of xref:ug:fun:programming-model/domain-services/contributions.adoc[contributed services].
+Note that this in effect means that xref:ug:fun:building-blocks.adoc#mixins[mixins] must be used instead of xref:ug:fun:programming-model/domain-services/contributions.adoc[contributed services].
|`isis.reflector.validator.` +
diff --git a/core/_adoc-rg/modules/cms/pages/classes/mixins.adoc b/core/_adoc-rg/modules/cms/pages/classes/mixins.adoc
index 6da525d..04fedd2 100644
--- a/core/_adoc-rg/modules/cms/pages/classes/mixins.adoc
+++ b/core/_adoc-rg/modules/cms/pages/classes/mixins.adoc
@@ -7,7 +7,7 @@ This chapter defines a number of role interfaces that definea contract for some
[TIP]
====
-See the xref:ug:fun:building-blocks/types-of-domain-objects/mixins.adoc[fundamentals user guide] for a discussion of mixins.
+See the xref:ug:fun:building-blocks.adoc#mixins[fundamentals user guide] for a discussion of mixins.
====
diff --git a/core/_adoc-rg/modules/cms/pages/classes/mixins/Dto.adoc b/core/_adoc-rg/modules/cms/pages/classes/mixins/Dto.adoc
index 8099c14..32ba349 100644
--- a/core/_adoc-rg/modules/cms/pages/classes/mixins/Dto.adoc
+++ b/core/_adoc-rg/modules/cms/pages/classes/mixins/Dto.adoc
@@ -5,7 +5,7 @@ include::_attributes.adoc[]
The `Dto` role interface is intended to be implemented by JAXB-annotated view models, that is, annotated using
xref:rg:ant:XmlRootElement.adoc[`@XmlRootElement`].
-It enables the ability to download the XML and XSD schema of those objects using two xref:ug:fun:building-blocks/types-of-domain-objects/mixins.adoc[mixins], `Dto_downloadXml` and `Dto_downloadXsd`.
+It enables the ability to download the XML and XSD schema of those objects using two xref:ug:fun:building-blocks.adoc#mixins[mixins], `Dto_downloadXml` and `Dto_downloadXsd`.
The interface is just a marker interface (with no members), and is defined as:
diff --git a/core/_adoc-rg/modules/cms/pages/methods/prefixes/disable.adoc b/core/_adoc-rg/modules/cms/pages/methods/prefixes/disable.adoc
index ef0e907..f6cb065 100644
--- a/core/_adoc-rg/modules/cms/pages/methods/prefixes/disable.adoc
+++ b/core/_adoc-rg/modules/cms/pages/methods/prefixes/disable.adoc
@@ -87,7 +87,7 @@ public class Customer {
In the case of actions, the framework will also search for supporting method that has the exact same parameter types as the action itself.
Enabling `isis.reflector.validator.noParamsOnly` configuration property switches this off, so that the framework will only search for supporting method with no parameters.
-Note that enabling this configuration property in effect means that xref:ug:fun:building-blocks/types-of-domain-objects/mixins.adoc[mixins] must be used instead of xref:ug:fun:programming-model/domain-services/contributions.adoc[contributed services] (because contributed actions are the one case where the value of a parameter to a supporting method may be non-null).
+Note that enabling this configuration property in effect means that xref:ug:fun:building-blocks.adoc#mixins[mixins] must be used instead of xref:ug:fun:programming-model/domain-services/contributions.adoc[contributed services] (because contributed actions are the one case where the value of a parameter to a supporting method may be non-null).
====
diff --git a/core/_adoc-rg/modules/cms/pages/methods/prefixes/hide.adoc b/core/_adoc-rg/modules/cms/pages/methods/prefixes/hide.adoc
index a4815fe..67db251 100644
--- a/core/_adoc-rg/modules/cms/pages/methods/prefixes/hide.adoc
+++ b/core/_adoc-rg/modules/cms/pages/methods/prefixes/hide.adoc
@@ -91,7 +91,7 @@ However, if they check the first boolean parameter (ie, to ship the `Order` to t
In the case of actions, the framework will also search for supporting method that has the exact same parameter types as the action itself.
Enabling `isis.reflector.validator.noParamsOnly` configuration property switches this off, so that the framework will only search for supporting method with no parameters.
-Note that enabling this configuration property in effect means that xref:ug:fun:building-blocks/types-of-domain-objects/mixins.adoc[mixins] must be used instead of xref:ug:fun:programming-model/domain-services/contributions.adoc[contributed services] (because contributed actions are the one case where the value of a parameter to a supporting method may be non-null).
+Note that enabling this configuration property in effect means that xref:ug:fun:building-blocks.adoc#mixins[mixins] must be used instead of xref:ug:fun:programming-model/domain-services/contributions.adoc[contributed services] (because contributed actions are the one case where the value of a parameter to a supporting method may be non-null).
====
diff --git a/core/_adoc-rg/modules/cms/pages/schema/common.adoc b/core/_adoc-rg/modules/cms/pages/schema/common.adoc
index 63f0fdf..63fe52c 100644
--- a/core/_adoc-rg/modules/cms/pages/schema/common.adoc
+++ b/core/_adoc-rg/modules/cms/pages/schema/common.adoc
@@ -12,7 +12,8 @@ The `oidDto` complex type captures an object's type and its identifier.
This is basically a formal XML equivalent to the `Bookmark` object obtained from the xref:rg:svc:integration-api/BookmarkService.adoc[`BookmarkService`].
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:ug:fun:building-blocks/identifiers/oid.adoc[here].
+With it, we have the ability to lookup any arbitrary object.
+Further discussion and examples can be found xref:ug:fun:building-blocks.adoc#oid[here].
The `oidDto` complex type is defined as:
diff --git a/core/_adoc-rg/modules/fis/pages/presentation-layer/ContentNegotiationService.adoc b/core/_adoc-rg/modules/fis/pages/presentation-layer/ContentNegotiationService.adoc
index 392c5a5..c7f5db1 100644
--- a/core/_adoc-rg/modules/fis/pages/presentation-layer/ContentNegotiationService.adoc
+++ b/core/_adoc-rg/modules/fis/pages/presentation-layer/ContentNegotiationService.adoc
@@ -12,7 +12,7 @@ Another use case is to support "third party" REST clients over which you have no
Instead you need to create some sort of stable facade over your domain entities, one which you will preserve even if the domain entities change. There are three ways in which you can do this:
-* first is to solve the problem at the domain layer by defining a regular Apache Isis xref:ug:fun:building-blocks/types-of-domain-objects/view-models.adoc[view model]. This is then surfaced over the RO viewer. +
+* first is to solve the problem at the domain layer by defining a regular Apache Isis xref:ug:fun:building-blocks.adoc#view-models[view model]. This is then surfaced over the RO viewer. +
+
If the underlying entities change, then care must be taken to ensure that structure of the view model nevertheless is unchanged.
diff --git a/core/_adoc-rg/modules/mvn/pages/xsd.adoc b/core/_adoc-rg/modules/mvn/pages/xsd.adoc
index b9ce594..6b149db 100644
--- a/core/_adoc-rg/modules/mvn/pages/xsd.adoc
+++ b/core/_adoc-rg/modules/mvn/pages/xsd.adoc
@@ -5,7 +5,7 @@ include::_attributes.adoc[]
The `xsd` goal of the `isis-maven-plugin` uses the xref:rg:svc:integration-api/JaxbService.adoc[`JaxbService`] to
-generate XSD schemas from any JAXB-annotated xref:ug:fun:building-blocks/types-of-domain-objects/view-models.adoc[view model/DTOs].
+generate XSD schemas from any JAXB-annotated xref:ug:fun:building-blocks.adoc#view-models[view model/DTOs].
This is instead of and preferable to using the JAXB link:https://jaxb.java.net/2.2.4/docs/schemagen.html[schemagen]
tool, because it uses the framework's support (via
diff --git a/core/_adoc-rg/modules/svc/pages/core-domain-api/Scratchpad.adoc b/core/_adoc-rg/modules/svc/pages/core-domain-api/Scratchpad.adoc
index 84b92fd..c88dc05 100644
--- a/core/_adoc-rg/modules/svc/pages/core-domain-api/Scratchpad.adoc
+++ b/core/_adoc-rg/modules/svc/pages/core-domain-api/Scratchpad.adoc
@@ -59,7 +59,7 @@ public BigDecimal totalCost() {
Scratchpad scratchpad;
----
-A more complex example could use a xref:ug:fun:building-blocks/types-of-domain-objects/view-models.adoc[view model] to enable bulk updates to a set of objects. The view model's job is to gather track of the items to be updated:
+A more complex example could use a xref:ug:fun:building-blocks.adoc#view-models[view model] to enable bulk updates to a set of objects. The view model's job is to gather track of the items to be updated:
[source,java]
----
diff --git a/core/_adoc-rg/modules/svc/pages/integration-api/JaxbService.adoc b/core/_adoc-rg/modules/svc/pages/integration-api/JaxbService.adoc
index 49193db..d8121f9 100644
--- a/core/_adoc-rg/modules/svc/pages/integration-api/JaxbService.adoc
+++ b/core/_adoc-rg/modules/svc/pages/integration-api/JaxbService.adoc
@@ -49,7 +49,7 @@ To use an alternative implementation, implement `JaxbService` interface and use
This service is provided as a convenience for applications, but is also used internally by the framework to
xref:rg:ant:XmlRootElement.adoc[`@XmlRootElement`]-annotated
-xref:ug:fun:building-blocks/types-of-domain-objects/view-models.adoc[view models]. The functionality to download XML and XSD schemas is also
+xref:ug:fun:building-blocks.adoc#view-models[view models]. The functionality to download XML and XSD schemas is also
exposed in the UI through mixins to xref:rg:cms:classes/mixins/Dto.adoc[`Dto`] interface.
diff --git a/core/_adoc-rg/modules/svc/pages/integration-api/MementoService.adoc b/core/_adoc-rg/modules/svc/pages/integration-api/MementoService.adoc
index adad423..3ee2088 100644
--- a/core/_adoc-rg/modules/svc/pages/integration-api/MementoService.adoc
+++ b/core/_adoc-rg/modules/svc/pages/integration-api/MementoService.adoc
@@ -6,7 +6,7 @@ include::_attributes.adoc[]
// TODO: v2: remove this service.
-The `MementoService` was originally introduced to simplify the implementation of xref:ug:fun:building-blocks/types-of-domain-objects/view-models.adoc[ViewModel]s which are required by the framework to return string representation of all of their backing state, moreover which is safe for use within a URL.
+The `MementoService` was originally introduced to simplify the implementation of xref:ug:fun:building-blocks.adoc#view-models[ViewModel]s which are required by the framework to return string representation of all of their backing state, moreover which is safe for use within a URL.
This usage is deprecated; use xref:ug:fun:programming-model/view-models/jaxb.adoc[JAXB view models] instead.
The service can also be used to create a memento of arbitrary objects, however this usage is also deprecated.
diff --git a/core/_adoc-rg/modules/svc/pages/metadata-api/SwaggerService.adoc b/core/_adoc-rg/modules/svc/pages/metadata-api/SwaggerService.adoc
index 702178f..45f3ce6 100644
--- a/core/_adoc-rg/modules/svc/pages/metadata-api/SwaggerService.adoc
+++ b/core/_adoc-rg/modules/svc/pages/metadata-api/SwaggerService.adoc
@@ -35,7 +35,7 @@ public interface SwaggerService {
}
----
<1> Generate a Swagger spec for use by third-party clients, ie public use. This specification is restricted only to
-xref:ug:fun:building-blocks/types-of-domain-objects/view-models.adoc[view model]s and to domain services with a xref:rg:ant:DomainService/nature.adoc[nature] of `VIEW_REST_ONLY`.
+xref:ug:fun:building-blocks.adoc#view-models[view model]s and to domain services with a xref:rg:ant:DomainService/nature.adoc[nature] of `VIEW_REST_ONLY`.
<2> Generate a Swagger spec for use only by internally-managed clients, ie private internal use. This specification includes domain entities and all menu domain services (as well as any view models).
<3> Generate a Swagger spec that is the same as private case (above), but also including any xref:rg:ant:Action/restrictTo.adoc[prototype] actions.
<4> Swagger specs can be written either in JSON or YAML format.
diff --git a/core/_adoc-rg/modules/svc/pages/presentation-layer-spi/UrlEncodingService.adoc b/core/_adoc-rg/modules/svc/pages/presentation-layer-spi/UrlEncodingService.adoc
index c85e85d..cffa99e 100644
--- a/core/_adoc-rg/modules/svc/pages/presentation-layer-spi/UrlEncodingService.adoc
+++ b/core/_adoc-rg/modules/svc/pages/presentation-layer-spi/UrlEncodingService.adoc
@@ -5,7 +5,7 @@ include::_attributes.adoc[]
The `UrlEncodingService` defines a consistent way to convert strings to/from a form safe for use within a URL.
-The service is used by the framework to map xref:ug:fun:building-blocks/types-of-domain-objects/view-models.adoc[view model] mementos (derived from the state of the view model itself) into a form that can be used as a view model.
+The service is used by the framework to map xref:ug:fun:building-blocks.adoc#view-models[view model] mementos (derived from the state of the view model itself) into a form that can be used as a view model.
When the framework needs to recreate the view model (for example to invoke an action on it), this URL is converted back into a view model memento, from which the view model can then be hydrated.
Defining this functionality as an SPI has two use cases:
diff --git a/core/_adoc-ug/modules/btb/pages/hints-and-tips/pushing-changes.adoc b/core/_adoc-ug/modules/btb/pages/hints-and-tips/pushing-changes.adoc
index 0bd101c..4d8c34b 100644
--- a/core/_adoc-ug/modules/btb/pages/hints-and-tips/pushing-changes.adoc
+++ b/core/_adoc-ug/modules/btb/pages/hints-and-tips/pushing-changes.adoc
@@ -5,7 +5,7 @@ include::_attributes.adoc[]
[NOTE]
====
-This technique is much less powerful than using xref:ug:fun/building-blocks/events/domain-events.adoc[the event bus] or an SPI service.
+This technique is much less powerful than using xref:ug:fun/building-blocks.adoc#domain-events[the event bus] or an SPI service.
We present it mostly for completeness.
====
diff --git a/core/_adoc-ug/modules/fun/nav.adoc b/core/_adoc-ug/modules/fun/nav.adoc
index 30d9ffa..0a0d7f7 100644
--- a/core/_adoc-ug/modules/fun/nav.adoc
+++ b/core/_adoc-ug/modules/fun/nav.adoc
@@ -3,34 +3,7 @@
** xref:core-concepts.adoc[Core Concepts]
-
-
-
-
-
-** xref:building-blocks.adoc[Building Blocks]
-
-*** xref:building-blocks/metamodel.adoc[Metamodel]
-
-*** xref:building-blocks/types-of-domain-objects.adoc[Types of Domain Objects]
-**** xref:building-blocks/types-of-domain-objects/domain-entities.adoc[Domain Entities]
-**** xref:building-blocks/types-of-domain-objects/domain-services.adoc[Domain Services]
-**** xref:building-blocks/types-of-domain-objects/view-models.adoc[View Models]
-**** xref:building-blocks/types-of-domain-objects/mixins.adoc[Mixins]
-
-*** xref:building-blocks/identifiers.adoc[Identifiers]
-**** xref:building-blocks/identifiers/title-and-icon-and-css-class.adoc[Title, Icon and CSS Class]
-**** xref:building-blocks/identifiers/oid.adoc[OID]
-
-*** xref:building-blocks/object-members.adoc[Object Members]
-
-*** xref:building-blocks/events.adoc[Events]
-**** xref:building-blocks/events/domain-events.adoc[Domain Events]
-**** xref:building-blocks/events/ui-events.adoc[UI Events]
-**** xref:building-blocks/events/lifecycle-events.adoc[Lifecycle Events]
-
-*** xref:building-blocks/modules.adoc[Modules]
-
+** xref:ug:fun:building-blocks.adoc[Building Blocks]
diff --git a/core/_adoc-ug/modules/fun/pages/building-blocks.adoc b/core/_adoc-ug/modules/fun/pages/building-blocks.adoc
index d9f5cd7..36fa08d 100644
--- a/core/_adoc-ug/modules/fun/pages/building-blocks.adoc
+++ b/core/_adoc-ug/modules/fun/pages/building-blocks.adoc
@@ -1,7 +1,38 @@
= 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 ag [...]
include::_attributes.adoc[]
-:page-partial:
In this section we run through the main building blocks that make up an Apache Isis application.
+
+include::building-blocks/metamodel.adoc[leveloffset=+1]
+
+
+include::building-blocks/types-of-domain-objects.adoc[leveloffset=+1]
+include::building-blocks/types-of-domain-objects/domain-entities.adoc[leveloffset=+2]
+include::building-blocks/types-of-domain-objects/domain-services.adoc[leveloffset=+2]
+include::building-blocks/types-of-domain-objects/view-models.adoc[leveloffset=+2]
+include::building-blocks/types-of-domain-objects/mixins.adocleveloffset=+2]
+
+
+
+include::building-blocks/identifiers.adoc[leveloffset=+1]
+include::building-blocks/identifiers/title-and-icon-and-css-class.adoc[leveloffset=+2]
+include::building-blocks/identifiers/oid.adoc[leveloffset=+2]
+
+
+
+include::building-blocks/object-members.adoc[leveloffset=+1]
+
+
+
+include::building-blocks/events.adoc[leveloffset=+1]
+include::building-blocks/events/domain-events.adoc[leveloffset=+2]
+include::building-blocks/events/ui-events.adoc[leveloffset=+2]
+include::building-blocks/events/lifecycle-events.adoc[leveloffset=+2]
+
+
+
+include::building-blocks/modules.adoc[leveloffset=+1]
+
+
diff --git a/core/_adoc-ug/modules/fun/pages/building-blocks/events/ui-events.adoc b/core/_adoc-ug/modules/fun/pages/building-blocks/events/ui-events.adoc
index 4ca8299..558ef3c 100644
--- a/core/_adoc-ug/modules/fun/pages/building-blocks/events/ui-events.adoc
+++ b/core/_adoc-ug/modules/fun/pages/building-blocks/events/ui-events.adoc
@@ -4,7 +4,7 @@ include::_attributes.adoc[]
:page-partial:
-As explained xref:ug:fun:building-blocks/identifiers/title-and-icon-and-css-class.adoc[earlier], to allow the end-user to distinguish one domain object from another, it is rendered with a title and an icon.
+As explained xref:ug:fun:building-blocks.adoc#title-and-icon-and-css-class[earlier], to allow the end-user to distinguish one domain object from another, it is rendered with a title and an icon.
xref:ug:fun:ui-hints/object-titles-and-icons.adoc[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.
@@ -15,7 +15,7 @@ If annotated with xref:rg:ant:DomainObjectLayout/titleUiEvent.adoc[`@DomainObjec
This can be particularly useful for xref:ug:fun:programming-model/view-models/jaxb.adoc[JAXB-style view models] which are code generated from XSDs and so cannot have any dependencies on the rest of the Apache Isis framework.
Here a subscriber on the default events can provide a title and icon for such an object.
-Behaviour on such DTOs can also be provided using xref:building-blocks/types-of-domain-objects/mixins.adoc[mixins].
+Behaviour on such DTOs can also be provided using xref:ug:fun:building-blocks.adoc#mixins[mixins].
Events also allow one module to influence/fine-tune the title of entities provided by some other module.
One such case is when reusing library modules, eg as provided by (non-ASF) link:http://platform.incode.org[Incode Platform^].
diff --git a/core/_adoc-ug/modules/fun/pages/building-blocks/identifiers/oid.adoc b/core/_adoc-ug/modules/fun/pages/building-blocks/identifiers/oid.adoc
index be5ba96..7a1f680 100644
--- a/core/_adoc-ug/modules/fun/pages/building-blocks/identifiers/oid.adoc
+++ b/core/_adoc-ug/modules/fun/pages/building-blocks/identifiers/oid.adoc
@@ -4,7 +4,7 @@ include::_attributes.adoc[]
:page-partial:
-As well as defining a xref:ug:fun:building-blocks/metamodel.adoc[metamodel] of the structure (domain classes) of its domain objects, Apache Isis also manages the runtime instances of said domain objects.
+As well as defining a xref:ug:fun:building-blocks.adoc#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.
diff --git a/core/_adoc-ug/modules/fun/pages/building-blocks/types-of-domain-objects/domain-services.adoc b/core/_adoc-ug/modules/fun/pages/building-blocks/types-of-domain-objects/domain-services.adoc
index 93004ba..f26d689 100644
--- a/core/_adoc-ug/modules/fun/pages/building-blocks/types-of-domain-objects/domain-services.adoc
+++ b/core/_adoc-ug/modules/fun/pages/building-blocks/types-of-domain-objects/domain-services.adoc
@@ -24,7 +24,7 @@ Domain services can also be used for a number of other purposes:
* to act as a subscribers to the event bus, potentially influencing events fired by some other module (a key technique for decoupling large applications) +
+
-This is discussed in more detail below, in the section on xref:ug:fun:building-blocks/events.adoc[events].
+This is discussed in more detail below, in the section on xref:ug:fun:building-blocks.adoc#events[events].
* to implement an link:https://en.wikipedia.org/wiki/Service_provider_interface[SPI] of the Apache Isis framework, most notably cross-cutting concerns such as security, command profiling, auditing and publishing.
diff --git a/core/_adoc-ug/modules/fun/pages/building-blocks/types-of-domain-objects/view-models.adoc b/core/_adoc-ug/modules/fun/pages/building-blocks/types-of-domain-objects/view-models.adoc
index cbbbe43..c7cc062 100644
--- a/core/_adoc-ug/modules/fun/pages/building-blocks/types-of-domain-objects/view-models.adoc
+++ b/core/_adoc-ug/modules/fun/pages/building-blocks/types-of-domain-objects/view-models.adoc
@@ -109,7 +109,7 @@ In such cases, exposing domain entities over xref:vro:ROOT::about.adoc[RestfulOb
To support this use case, a view model can be defined such that it can act as a DTO.
This is done by annotating the class using JAXB annotations; this allows the consumer to obtain the DTO in XML format along with a corresponding XSD schema describing the structure of that XML.
-A discussion of how that might be done using an ESB such as link:http://camel.apache.org[Apache Camel(TM)] follows xref:ug:fun:building-blocks/types-of-domain-objects/view-models.adoc#dtos_consumers[below].
+A discussion of how that might be done using an ESB such as link:http://camel.apache.org[Apache Camel(TM)] follows xref:ug:fun:building-blocks.adoc#view-models#dtos_consumers[below].
In case it's not obvious, these DTOs are still usable as "regular" view models; they will render in the xref:vw:ROOT::about.adoc[Wicket viewer] just like any other.
In fact (as the xref:ug:fun:programming-model/view-models/jaxb.adoc[programming model] section below makes clear), these JAXB-annotated view models are in many regards the most powerful of all the alternative ways of writing view models.
diff --git a/core/_adoc-ug/modules/fun/pages/business-rules.adoc b/core/_adoc-ug/modules/fun/pages/business-rules.adoc
index 18de4da..e6eb968 100644
--- a/core/_adoc-ug/modules/fun/pages/business-rules.adoc
+++ b/core/_adoc-ug/modules/fun/pages/business-rules.adoc
@@ -30,7 +30,7 @@ One way to remember this is: *"see it, use it, do it"*
The framework provides a multitude of ways to implement these business rules.
-One decoupled approach is using xref:ug:fun:building-blocks/events/domain-events.adoc[domain events]; the checks above correspond to the phases of the domain event.
+One decoupled approach is using xref:ug:fun:building-blocks.adoc#domain-events[domain events]; the checks above correspond to the phases of the domain event.
A simpler approach is to just implement the business rules imperatively in the domain object, or in a mixin for the object.
diff --git a/core/_adoc-ug/modules/fun/pages/core-concepts/apache-isis-vs/cqrs.adoc b/core/_adoc-ug/modules/fun/pages/core-concepts/apache-isis-vs/cqrs.adoc
index 3b9c1d6..ed76e78 100644
--- a/core/_adoc-ug/modules/fun/pages/core-concepts/apache-isis-vs/cqrs.adoc
+++ b/core/_adoc-ug/modules/fun/pages/core-concepts/apache-isis-vs/cqrs.adoc
@@ -31,7 +31,7 @@ In these cases Apache Isis can often provide a reasonable alternative, namely to
In such cases there is still only a single physical datastore, and so transactional integrity is retained.
Or, the CQRS architecture can be more fully implemented with Apache Isis by introducing a separate read model, synchronized using the xref:rg:svc:persistence-layer-spi/PublisherService.adoc[`PublisherService`], or using xref:rg:cms:classes/super/AbstractSubscriber.adoc[subscribers] on the xref:rg:svc:core-domain-api/EventBusService.adoc[`EventBusService`].
-One can then use xref:ug:fun:building-blocks/types-of-domain-objects/view-models.adoc[view models] to surface the data in the external read datastore.
+One can then use xref:ug:fun:building-blocks.adoc#view-models[view models] to surface the data in the external read datastore.
With respect to commands, Apache Isis does of course support the xref:rg:svc:application-layer-spi/CommandService.adoc[`CommandService`] which allows each business action to be reified into a `Command`.
However, names are misleading here: Apache Isis' commands are relatively passive, merely recording the intent of the user to invoke some operation.
@@ -42,7 +42,7 @@ With Apache Isis, though, the end-user merely invokes the `placeOrder(...)` acti
In CQRS the commands correspond to the business logic that mutates the system.
Whether this logic is part of the command class (`PlaceOrderCommand`) or whether that command delegates to methods on the domain object is an implementation detail; but it certainly is common for the business logic to be wholly within the command object and for the domain object to be merely a data holder of the data within the command/write datastore.
-In Apache Isis this same separation of business logic from the underlying data can be accomplished most straightforwardly using xref:ug:fun:building-blocks/types-of-domain-objects/mixins.adoc[mixins].
+In Apache Isis this same separation of business logic from the underlying data can be accomplished most straightforwardly using xref:ug:fun:building-blocks.adoc#mixins[mixins].
In the UI (surfaced by the xref:vw:ROOT::about.adoc[Wicket viewer]) or in the REST API (surfaced by the xref:vro:ROOT::about.adoc[RestfulObjects viewer]) the behaviour appears to reside on the domain object; however the behaviour actually resides on separate classes and is mixed in (like a trait) only at runtime.
diff --git a/core/_adoc-ug/modules/fun/pages/core-concepts/philosophy/aop.adoc b/core/_adoc-ug/modules/fun/pages/core-concepts/philosophy/aop.adoc
index fbab6c2..a960a8f 100644
--- a/core/_adoc-ug/modules/fun/pages/core-concepts/philosophy/aop.adoc
+++ b/core/_adoc-ug/modules/fun/pages/core-concepts/philosophy/aop.adoc
@@ -61,4 +61,4 @@ Apache Isis' support for contributions (not only contributed actions, but also c
And again, to loop back to the topic of this section, it's an AOP concept that being implemented by the framework.
The nice thing about aspect orientation is that for the most part you can ignore these cross-cutting concerns and - at least initially - just focus on implementing your domain object.
-Later when your app starts to grow and you start to break it out into smaller modules, you can leverage Apache Isis' AOP support for (xref:ug:fun:building-blocks/types-of-domain-objects/mixins.adoc[mixins]), (xref:ug:fun:programming-model/domain-services/contributions.adoc[contributed services]) and interceptors (the xref:ug:fun:building-blocks/events/domain-events.adoc[event bus]) to ensure that your codebase remains maintainable.
+Later when your app starts to grow and you start to break it out into smaller modules, you can leverage Apache Isis' AOP support for (xref:ug:fun:building-blocks.adoc#mixins[mixins]), (xref:ug:fun:programming-model/domain-services/contributions.adoc[contributed services]) and interceptors (the xref:ug:fun:building-blocks.adoc#domain-events[event bus]) to ensure that your codebase remains maintainable.
diff --git a/core/_adoc-ug/modules/fun/pages/crud.adoc b/core/_adoc-ug/modules/fun/pages/crud.adoc
index b1fd976..f54d927 100644
--- a/core/_adoc-ug/modules/fun/pages/crud.adoc
+++ b/core/_adoc-ug/modules/fun/pages/crud.adoc
@@ -4,10 +4,10 @@ include::_attributes.adoc[]
:page-partial:
-This chapter shows the idioms for creating, reading, updating and deleting xref:ug:fun:building-blocks/types-of-domain-objects/domain-entities.adoc[domain entities].
+This chapter shows the idioms for creating, reading, updating and deleting xref:ug:fun:building-blocks.adoc#domain-entities[domain entities].
The main domain services used for this are xref:rg:svc:persistence-layer-api/RepositoryService.adoc[`RepositoryService`] and xref:rg:svc:core-domain-api/FactoryService.adoc[`FactoryService`].
-It also shows how to instantiate xref:ug:fun:building-blocks/types-of-domain-objects/view-models.adoc[view models] and how to programmatically instantiate xref:ug:fun:building-blocks/types-of-domain-objects/mixins.adoc[mixins] (useful primarily for xref:testing:ROOT::integ-test-support.adoc[integration testing]).
+It also shows how to instantiate xref:ug:fun:building-blocks.adoc#view-models[view models] and how to programmatically instantiate xref:ug:fun:building-blocks.adoc#mixins[mixins] (useful primarily for xref:testing:ROOT::integ-test-support.adoc[integration testing]).
diff --git a/core/_adoc-ug/modules/fun/pages/crud/deleting.adoc b/core/_adoc-ug/modules/fun/pages/crud/deleting.adoc
index c93d64b..0a2ba5a 100644
--- a/core/_adoc-ug/modules/fun/pages/crud/deleting.adoc
+++ b/core/_adoc-ug/modules/fun/pages/crud/deleting.adoc
@@ -25,6 +25,6 @@ repositoryService.removeAndFlush(customer);
to eagerly perform the object deletion from the database.
-When an object is deleted the framework will emit `ObjectRemovingEvent` xref:ug:fun:building-blocks/events/lifecycle-events.adoc[lifecycle event].
+When an object is deleted the framework will emit `ObjectRemovingEvent` xref:ug:fun:building-blocks.adoc#lifecycle-events[lifecycle event].
diff --git a/core/_adoc-ug/modules/fun/pages/crud/finding.adoc b/core/_adoc-ug/modules/fun/pages/crud/finding.adoc
index 469ccbb..cb68c4f 100644
--- a/core/_adoc-ug/modules/fun/pages/crud/finding.adoc
+++ b/core/_adoc-ug/modules/fun/pages/crud/finding.adoc
@@ -56,7 +56,7 @@ Whenever a query is submitted, the framework will automatically "flush" any pend
This ensures that the database query runs against an up-to-date table so that all matching instances (with respect to the current transaction) are correctly retrieved.
-When an object is loaded from the database the framework will emit `ObjectLoadedEvent` xref:ug:fun:building-blocks/events/lifecycle-events.adoc[lifecycle event].
+When an object is loaded from the database the framework will emit `ObjectLoadedEvent` xref:ug:fun:building-blocks.adoc#lifecycle-events[lifecycle event].
== Type-safe queries
diff --git a/core/_adoc-ug/modules/fun/pages/crud/instantiating.adoc b/core/_adoc-ug/modules/fun/pages/crud/instantiating.adoc
index c4c6384..862fc74 100644
--- a/core/_adoc-ug/modules/fun/pages/crud/instantiating.adoc
+++ b/core/_adoc-ug/modules/fun/pages/crud/instantiating.adoc
@@ -21,7 +21,7 @@ Dashboard dashboardVM = factoryService.instantiate(Dashboard.class);
----
For this to work the target class _must_ have a no-arg constructor.
-When the framework instantiates the object, all services are injected into the framework, and an `ObjectCreatedEvent` xref:ug:fun:building-blocks/events/lifecycle-events.adoc[lifecycle event] will also be emitted.
+When the framework instantiates the object, all services are injected into the framework, and an `ObjectCreatedEvent` xref:ug:fun:building-blocks.adoc#lifecycle-events[lifecycle event] will also be emitted.
However, you may prefer for your domain objects to have regular constructor defining their minimum set of mandatory properties.
@@ -50,7 +50,7 @@ serviceRegister.injectServicesInto(customer);
Note though that this does _not_ raise any lifecycle event.
-To instantiate a xref:building-blocks/types-of-domain-objects/mixins.adoc[mixin], a different API of `FactoryService` is used:
+To instantiate a xref:ug:fun:building-blocks.adoc#mixins[mixin], a different API of `FactoryService` is used:
[source,java]
----
diff --git a/core/_adoc-ug/modules/fun/pages/crud/persisting.adoc b/core/_adoc-ug/modules/fun/pages/crud/persisting.adoc
index 2b3128b..df3124d 100644
--- a/core/_adoc-ug/modules/fun/pages/crud/persisting.adoc
+++ b/core/_adoc-ug/modules/fun/pages/crud/persisting.adoc
@@ -55,7 +55,7 @@ Nevertheless, if you want to ensure that the persist command is flushed immediat
repositoryService.persistAndFlush(customer);
----
-When an object is persisted the framework will emit `ObjectPersistingEvent` and `ObjectPersistedEvent` xref:ug:fun:building-blocks/events/lifecycle-events.adoc[lifecycle events].
+When an object is persisted the framework will emit `ObjectPersistingEvent` and `ObjectPersistedEvent` xref:ug:fun:building-blocks.adoc#lifecycle-events[lifecycle events].
== Persistence by Reachability
diff --git a/core/_adoc-ug/modules/fun/pages/crud/updating.adoc b/core/_adoc-ug/modules/fun/pages/crud/updating.adoc
index db1e1f4..4a822af 100644
--- a/core/_adoc-ug/modules/fun/pages/crud/updating.adoc
+++ b/core/_adoc-ug/modules/fun/pages/crud/updating.adoc
@@ -15,7 +15,7 @@ That said, it is possible to "flush" pending changes:
* using xref:rg:svc:persistence-layer-api/IsisJdoSupport.adoc[`IsisJdoSupport`] it is possible to reach down to the underlying JDO API, and perform a flush of pending object updates also.
-When an object is updated the framework will emit `ObjectUpdatingEvent` and `ObjectUpdatedEvent` xref:ug:fun:building-blocks/events/lifecycle-events.adoc[lifecycle events].
+When an object is updated the framework will emit `ObjectUpdatingEvent` and `ObjectUpdatedEvent` xref:ug:fun:building-blocks.adoc#lifecycle-events[lifecycle events].
diff --git a/core/_adoc-ug/modules/fun/pages/programming-model/domain-services/event-subscribers.adoc b/core/_adoc-ug/modules/fun/pages/programming-model/domain-services/event-subscribers.adoc
index d9b19a8..a185d01 100644
--- a/core/_adoc-ug/modules/fun/pages/programming-model/domain-services/event-subscribers.adoc
+++ b/core/_adoc-ug/modules/fun/pages/programming-model/domain-services/event-subscribers.adoc
@@ -6,7 +6,7 @@ include::_attributes.adoc[]
// TODO: v2: update for Spring events rather than axon/guava
-Domain services acting as event subscribers can subscribe to xref:ug:fun:building-blocks/events/domain-events.adoc[domain], xref:ug:fun:building-blocks/events/ui-events.adoc[UI] and xref:ug:fun:building-blocks/events/lifecycle-events.adoc[lifecycle] events, influencing the rendering and behaviour of other objects.
+Domain services acting as event subscribers can subscribe to xref:ug:fun:building-blocks.adoc#lifecycle-events[lifecycle] events, influencing the rendering and behaviour of other objects.
All subscribers must subscribe to the xref:rg:svc:core-domain-api/EventBusService.adoc[`EventBusService`]; as this amounts to a few lines of boilerplate it's easiest to inherit from the convenience `AbstractSubscriber` class.
diff --git a/core/_adoc-ug/modules/fun/pages/programming-model/mixins.adoc b/core/_adoc-ug/modules/fun/pages/programming-model/mixins.adoc
index ea1a9ac..f0fc22d 100644
--- a/core/_adoc-ug/modules/fun/pages/programming-model/mixins.adoc
+++ b/core/_adoc-ug/modules/fun/pages/programming-model/mixins.adoc
@@ -4,7 +4,7 @@ include::_attributes.adoc[]
:page-partial:
-A xref:ug:fun:building-blocks/types-of-domain-objects/mixins.adoc[mixin] acts like a trait or extension method, allowing one module to contribute behaviour or derived state to another object.
+A xref:ug:fun:building-blocks.adoc#mixins[mixin] acts like a trait or extension method, allowing one module to contribute behaviour or derived state to another object.
Syntactically, a mixin is defined using either the xref:rg:ant:Mixin.adoc[`@Mixin`] annotation or using xref:rg:ant:DomainObject/nature.adoc[`@DomainObject#nature()`] attribute (specifying a nature of `Nature.MIXIN`).
diff --git a/core/_adoc-ug/modules/fun/pages/programming-model/view-models.adoc b/core/_adoc-ug/modules/fun/pages/programming-model/view-models.adoc
index 2d5f236..9acee25 100644
--- a/core/_adoc-ug/modules/fun/pages/programming-model/view-models.adoc
+++ b/core/_adoc-ug/modules/fun/pages/programming-model/view-models.adoc
@@ -4,7 +4,7 @@ include::_attributes.adoc[]
:page-partial:
-As described in the xref:ug:fun:building-blocks/types-of-domain-objects/view-models.adoc[introduction], view models are domain objects like domain entities, with behaviour and state.
+As described in the xref:ug:fun:building-blocks.adoc#view-models[introduction], view models are domain objects like domain entities, with behaviour and state.
However, unlike domain entities, their state is _not_ persisted to a database but is instead serialized into its identifier (in effect, its URL).
The framework provides two main ways to implement a view model:
diff --git a/core/_adoc-ug/modules/fun/pages/programming-model/view-models/jaxb.adoc b/core/_adoc-ug/modules/fun/pages/programming-model/view-models/jaxb.adoc
index adde187..45ebf89 100644
--- a/core/_adoc-ug/modules/fun/pages/programming-model/view-models/jaxb.adoc
+++ b/core/_adoc-ug/modules/fun/pages/programming-model/view-models/jaxb.adoc
@@ -50,7 +50,7 @@ This is an all-or-nothing affair: either all properties must be listed, or else
For collections, the `@XmlElementWrapper` would also typically be used.
<5> The `@XmlTransient` indicates that the property is derived and should be ignored by JAXB.
+
-The derived properties could also have been implemented using xref:ug:fun:building-blocks/types-of-domain-objects/mixins.adoc[mixins].
+The derived properties could also have been implemented using xref:ug:fun:building-blocks.adoc#mixins[mixins].
[IMPORTANT]