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 06:46:39 UTC
[1/5] isis git commit: completes ugfun.adoc - drop downs chapter
Repository: isis
Updated Branches:
refs/heads/wip 92b9579df -> bbf2414ab
completes ugfun.adoc - drop downs chapter
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/aec83c62
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/aec83c62
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/aec83c62
Branch: refs/heads/wip
Commit: aec83c622483e3d95bd186cfaeb680ba7ca865d2
Parents: 92b9579
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Wed Apr 19 15:49:59 2017 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Wed Apr 19 15:49:59 2017 +0100
----------------------------------------------------------------------
.../ugfun/_ugfun_drop-downs-and-defaults.adoc | 192 ++++++++++++++++---
1 file changed, 167 insertions(+), 25 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/aec83c62/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_drop-downs-and-defaults.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_drop-downs-and-defaults.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_drop-downs-and-defaults.adoc
index 44bab58..6b2fef1 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_drop-downs-and-defaults.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_drop-downs-and-defaults.adoc
@@ -4,62 +4,204 @@
:_basedir: ../../
:_imagesdir: images/
-NOTE: FIXME
+Invoking an action whose parameters are primitives or values (int, date, string etc) is simple: the user can just type in or use a date picker.
+Invoking an action with a parameter of reference type (such as `Customer` or `Order`) requires the viewer to provide some mechanism by which the end-user can select the relevant instance.
+If the list of available options is fixed then the developer can provided a list a xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_choices[`choices...()`] supporting method (for either and action parameter or when editing a property).
+These are rendered in a drop-down.
-== For Properties
+If the list of available options is much larger, then the developer can use an xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`] supporting method.
+The user user enters a few characters and this is used to search for matching reference(s), again rendered in a drop-down.
-NOTE: FIXME
+Similarly, when invoking an action, there may well be suitable defaults for the action arguments.
+For example, if placing an `Order` then -- even if the `Product` argument might not have a sensible default -- the quantity argument could reasonably be defaulted to 1.
+Or, the `Product` might indeed have a default, say the product previously placed by this user.
+The developer indicates this using a xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_default[`default...()`] supporting method.
-### Choices for Property
-NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_choices[`choices...()`]
+== Choices and Default
-### Auto-complete for property
+For example, _choices_ for a property are specified using:
-NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`]
+[source,java]
+----
+@Getter @Setter
+private String paymentMethod;
-### Default for property
+public List<String> choicesPaymentMethod() {
+ return Arrays.asList("Visa", "Mastercard", "Amex");
+}
+----
-NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_default[`default...()`]
+Note the "choices" prefix, while the suffix matches up with the getter.
+Or, for an action the _choices_ and a suitable _default_ method would be:
+[source,java]
+----
+public Order changePaymentMethod(
+ @ParameterLayout(named="Payment Method")
+ String paymentMethod) {
+ setPaymentMethod(paymentMethod);
+ return this;
+}
+public List<String> choices0ChangePaymentMethod() {
+ return Arrays.asList("Visa", "Mastercard", "Amex");
+}
-== For Action Parameters
+public String default0ChangePaymentMethod() {
+ return getPaymentMethod();
+}
+----
-NOTE: FIXME
+Note the "choices" and "default" prefix, the digit is the 0-based argument number, while the suffix matches up with the action's name.
-### Choices for action parameter
-NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_choices[`choices...()`]
+== AutoComplete
-### Dependent choices for action params
+The _autocomplete_ is similar to _choices_, but accepts a string parameter, to search for matching results.
+A property for example might have:
-NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_choices[`choices...()`]
+[source,java]
+----
+@Getter @Setter
+private Product product;
-### Auto-complete for action param
+public List<Product> autoCompleteProduct(@MinLength(2) String search) {
+ return productRepository.findByReferenceOrName(search);
+}
+----
-NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_autoComplete[`autoComplete...()`]
+Note the "autoComplete" prefix, while (again) the suffix matches up with the getter.
+The `@MinLength(...)` annotation indicates the minimum number of characters that must be entered before a search is initiated.
-### Default for action param
+Actions are very similar:
-NOTE: FIXME - xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_default[`default...()`]
+[source,java]
+----
+public Order changeProduct(Product product) {
+ setProduct(product);
+ return this;
+}
+public List<Product> autoComplete0Product(@MinLength(2) String search) {
+ return productRepository.findByReferenceOrName(search);
+}
+----
+An _autoComplete_ method can be used in conjunction with a _default_ method, but it doesn't make sense to provide both an _autoComplete_ and a _choices_ method.
-== For both Properties and Params
-NOTE: FIXME
+== "Globally" defined drop-downs
+Very often the set of available choices depends on the data type of the property/action parameter, rather than the individual property/parameter itself.
+And similarly the algorithm to search for references again may well depend only on that reference type.
-### Drop-down for limited number of instances
+In the case of _choices_, annotating a class as "bounded" (as in a "bounded" or fixed number of instances) means that a _choices_ drop-down will automatically be defined.
+For example:
-NOTE: FIXME - xref:../rgant/rgant.adoc#_rgant-DomainObject_bounded[`@DomainObject#bounded()`]
+[source,java]
+----
+@DomainObject(
+ bounded = true
+)
+public class Product { ... }
+----
+
+For more on this, see xref:../rgant/rgant.adoc#_rgant-DomainObject_bounded[`@DomainObject#bounded()`].
+
+Or, if the data type is an enum, then a drop-down will be provided automatically.
+A payment method is a good example of this:
+
+
+[source,java]
+----
+public enum PaymentMethod {
+ VISA, MASTERCARD, AMEX;
+}
+----
+
+Something similar can be achieved for _autoComplete_.
+Here the domain object indicates a repository query to execute.
+For example:
+
+[source,java]
+----
+@DomainObject(
+ autoCompleteRepository = Customers.class,
+ autoCompleteAction = "findByReferenceOrName"
+)
+public class Customer { ... }
+----
+
+with:
+
+[source,java]
+----
+@DomainService(nature=NatureOfService.VIEW_MENU_ONLY)
+public class Customers {
+ @Action(semantics=SemanticsOf.SAFE)
+ public List<Customer> findByReferenceOrName(@MinLength(3) String refOrName) {
+ ...
+ }
+}
+----
+
+For more on this, see xref:../rgant/rgant.adoc#_rgant-DomainObject_autoCompleteRepository[`@DomainObject#autoCompleteRepository()`].
+
+[TIP]
+====
+There's no need for the nominated method to be an actual action; any method of any domain service will do, so long as it accepts a string and returns the correct list.
+====
+
+
+== Multi-select action parameters
+
+As well as scalar values, action parameters can also be collections.
+For this to be valid, a _choices_ or _autoComplete_ supporting method must be provided.
+
+For example, suppose we want to "tag" or "label" an object:
+
+[source,java]
+----
+public StoryCard tag(List<Tag> tags) {
+ getTags().addAll(tags);
+}
+
+public List<Tag> autoCompleteTag(@MinLength(1) search) {
+ return tagRepository.findByName(search);
+}
+----
+
+
+
+
+== Dependent choices for action parameters
+
+For action it is also possible (in a limited form) to define dependencies between parameters.
+Specifically, if one parameter is a drop-down choice, then other drop-down choices can be derived from it.
+
+A good example is a category/sub-category:
+
+[source,java]
+----
+public ToDoItem categorize(Category category, Subcategory subcategory) {
+ setCategory(category);
+ setSubcategory(subcategory);
+}
+
+public List<Category> choices0Categorize() {
+ return categoryRepository.allCategories();
+}
+public List<Subcategory> choices1Categorize(Category category) {
+ return subcategoryRepository.findBy(category);
+}
+----
+
+Note how the _choices_ method for the 2nd parameter also accepts the first parameter.
-### Auto-complete (repository-based)
-xref:../rgant/rgant.adoc#_rgant-DomainObject_autoCompleteRepository[`@DomainObject#autoCompleteRepository()`]
[3/5] isis git commit: fixes up references to view models and mixins.
Posted by da...@apache.org.
fixes up references to view models and mixins.
Also moves remaining decoupling material from ugbtb elsewhere
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/01fb90ba
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/01fb90ba
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/01fb90ba
Branch: refs/heads/wip
Commit: 01fb90ba01a6112e3eb92e0074adb90bfa19b777
Parents: aec83c6
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Wed Apr 19 19:45:06 2017 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Wed Apr 19 19:45:06 2017 +0100
----------------------------------------------------------------------
.../guides/dg/_dg_working-with-many-repos.adoc | 2 +-
...gant-DomainObjectLayout_cssClassUiEvent.adoc | 4 +-
.../_rgant-DomainObjectLayout_iconUiEvent.adoc | 4 +-
.../_rgant-DomainObjectLayout_titleUiEvent.adoc | 4 +-
.../rgant/_rgant-DomainObject_nature.adoc | 2 +-
.../asciidoc/guides/rgant/_rgant-Mixin.adoc | 2 +-
.../guides/rgant/_rgant-PostConstruct.adoc | 2 +-
.../guides/rgant/_rgant-XmlJavaTypeAdapter.adoc | 2 +-
.../guides/rgant/_rgant-XmlRootElement.adoc | 6 +-
.../guides/rgcfg/_rgcfg_configuring-core.adoc | 2 +-
.../guides/rgcms/_rgcms_classes_mixins.adoc | 8 +-
.../guides/rgcms/_rgcms_classes_mixins_Dto.adoc | 3 +-
.../rgcms/_rgcms_methods_prefixes_disable.adoc | 2 +-
.../rgcms/_rgcms_methods_prefixes_hide.adoc | 2 +-
.../_rgfis_spi_ContentNegotiationService.adoc | 2 +-
.../main/asciidoc/guides/rgmvn/_rgmvn_xsd.adoc | 4 +-
.../guides/rgsvc/_rgsvc_api_JaxbService.adoc | 2 +-
.../guides/rgsvc/_rgsvc_api_MementoService.adoc | 4 +-
.../guides/rgsvc/_rgsvc_api_Scratchpad.adoc | 2 +-
.../guides/rgsvc/_rgsvc_api_SwaggerService.adoc | 2 +-
.../guides/rgsvc/_rgsvc_spi_AuditerService.adoc | 2 +-
.../rgsvc/_rgsvc_spi_AuditingService.adoc | 2 +-
.../_rgsvc_spi_BackgroundCommandService.adoc | 2 +-
.../guides/rgsvc/_rgsvc_spi_CommandService.adoc | 2 +-
.../rgsvc/_rgsvc_spi_PublisherService.adoc | 2 +-
.../rgsvc/_rgsvc_spi_PublishingService.adoc | 2 +-
.../rgsvc/_rgsvc_spi_TranslationService.adoc | 2 +-
.../rgsvc/_rgsvc_spi_UrlEncodingService.adoc | 2 +-
.../guides/ugbtb/_ugbtb_decoupling.adoc | 30 ----
.../_ugbtb_decoupling_contributed-members.adoc | 9 --
.../ugbtb/_ugbtb_decoupling_contributions.adoc | 8 -
.../ugbtb/_ugbtb_decoupling_db-schemas.adoc | 141 ------------------
.../ugbtb/_ugbtb_decoupling_event-bus.adoc | 11 --
.../guides/ugbtb/_ugbtb_decoupling_mixins.adoc | 8 -
.../_ugbtb_decoupling_pushing-changes.adoc | 140 ------------------
.../_ugbtb_decoupling_vetoing-visibility.adoc | 15 --
.../guides/ugbtb/_ugbtb_hints-and-tips.adoc | 2 +
.../_ugbtb_hints-and-tips_are-you-sure.adoc | 8 +-
.../_ugbtb_hints-and-tips_pushing-changes.adoc | 140 ++++++++++++++++++
...ugbtb_hints-and-tips_vetoing-visibility.adoc | 15 ++
.../action-semantics-are-you-sure.png | Bin 0 -> 11046 bytes
.../hints-and-tips/are-you-sure-happy-case.png | Bin 0 -> 9993 bytes
.../hints-and-tips/are-you-sure-sad-case.png | Bin 0 -> 10515 bytes
.../images/hints-and-tips/are-you-sure.png | Bin 0 -> 9312 bytes
.../src/main/asciidoc/guides/ugbtb/ugbtb.adoc | 1 -
...un_building-blocks_events_domain-events.adoc | 2 +-
...cks_types-of-domain-objects_view-models.adoc | 2 +-
...ugfun_core-concepts_apache-isis-vs_cqrs.adoc | 4 +-
.../_ugfun_core-concepts_philosophy_aop.adoc | 2 +-
...ing-model_domain-services_contributions.adoc | 2 +-
...ugfun_programming-model_view-models_dto.adoc | 12 +-
...amming-model_view-models_dto_versioning.adoc | 2 +-
.../guides/ugodn/_ugodn_db-schemas.adoc | 147 +++++++++++++++++++
...nts-and-tips_overriding-jdo-annotations.adoc | 2 +-
.../src/main/asciidoc/guides/ugodn/ugodn.adoc | 1 +
.../ugvw/_ugvw_layout_application-menu.adoc | 2 +-
.../powered-by/_powered-by_contactapp.adoc | 2 +-
.../_powered-by_gesconsultor-grc.adoc | 2 +-
.../asciidoc/pages/screencasts/screencasts.adoc | 16 +-
59 files changed, 374 insertions(+), 429 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/dg/_dg_working-with-many-repos.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_working-with-many-repos.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_working-with-many-repos.adoc
index 086f329..1e39537 100644
--- a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_working-with-many-repos.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_working-with-many-repos.adoc
@@ -8,7 +8,7 @@
Applications built with Apache Isis often (should) consist of multiple modules, each in separate git repositories. For example, there are the various (non-ASF) link:http://isisaddons.org[Isis Addons] that provide various cross-cutting concerns/technical services (security, mail-merge etc), as well the modules eg as provided by the (non-ASF) link:http://catalog.incode.org[Incode Catalog], which provides generic business subdomains (communication channels, documents etc).
-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:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_event-bus[event bus] and xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_mixins[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:../ugfun/ugfun.adoc#_ugfun_building-blocks_events_domain-events[event bus] and xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_types-of-domain-objects_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.
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_cssClassUiEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_cssClassUiEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_cssClassUiEvent.adoc
index 8b948aa..de5d393 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_cssClassUiEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_cssClassUiEvent.adoc
@@ -17,8 +17,8 @@ the domain object using the event's API.
[NOTE]
====
The feature was originally introduced so that xref:../rgant/rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`]-annotated
-xref:../ugbtb/ugbtb.adoc#_ugbtb_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:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_mixins[mixin]s can be used to provide the behaviour.
+xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_types-of-domain-objects_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:../ugfun/ugfun.adoc#_ugfun_building-blocks_types-of-domain-objects_mixins[mixin]s can be used to provide the behaviour.
====
By default the event raised is `CssClassUiEvent.Default`. For example:
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_iconUiEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_iconUiEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_iconUiEvent.adoc
index 21d5f81..418ed07 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_iconUiEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_iconUiEvent.adoc
@@ -18,8 +18,8 @@ the domain object using the event's API.
[NOTE]
====
The feature was originally introduced so that xref:../rgant/rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`]-annotated
-xref:../ugbtb/ugbtb.adoc#_ugbtb_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:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_mixins[mixin]s can be used to provide the behaviour.
+xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_types-of-domain-objects_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:../ugfun/ugfun.adoc#_ugfun_building-blocks_types-of-domain-objects_mixins[mixin]s can be used to provide the behaviour.
====
By default the event raised is `IconUiEvent.Default`. For example:
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_titleUiEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_titleUiEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_titleUiEvent.adoc
index aa1fb75..12f13f7 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_titleUiEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObjectLayout_titleUiEvent.adoc
@@ -17,8 +17,8 @@ the domain object using the event's API.
[NOTE]
====
The feature was originally introduced so that xref:../rgant/rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`]-annotated
-xref:../ugbtb/ugbtb.adoc#_ugbtb_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:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_mixins[mixin]s can be used to provide the behaviour.
+xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_types-of-domain-objects_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:../ugfun/ugfun.adoc#_ugfun_building-blocks_types-of-domain-objects_mixins[mixin]s can be used to provide the behaviour.
====
By default the event raised is `TitleUiEvent.Default`. For example:
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_nature.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_nature.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_nature.adoc
index 097e71b..6b2e107 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_nature.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_nature.adoc
@@ -44,7 +44,7 @@ The identity of an inmemory entity is determined solely by the state of entity's
+
indicates that the domain object is part of the domain layer, and is contributing behaviour to objects of some other type as a mixin (also known as a trait).
-Equivalent to annotating with xref:../rgant/rgant.adoc#_rgant-Mixin[`@Mixin`]. For further discussion on using mixins, see xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_mixins[mixins] in the user guide.
+Equivalent to annotating with xref:../rgant/rgant.adoc#_rgant-Mixin[`@Mixin`]. For further discussion on using mixins, see xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_types-of-domain-objects_mixins[mixins] in the user guide.
* `VIEW_MODEL` +
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Mixin.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Mixin.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Mixin.adoc
index 03abb65..ecae971 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Mixin.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-Mixin.adoc
@@ -11,7 +11,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:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_mixins[mixins] in the user guide.
+For further discussion on using mixins, see xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_types-of-domain-objects_mixins[mixins] in the user guide.
The table below summarizes the annotation's attributes.
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PostConstruct.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PostConstruct.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PostConstruct.adoc
index 78d60f7..7b5cba3 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PostConstruct.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-PostConstruct.adoc
@@ -7,7 +7,7 @@
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:../ugbtb/ugbtb.adoc#_ugbtb_view-models[view models] (eg annotated with xref:../rgant/rgant.adoc#_rgant-ViewModel[`@ViewModel`]).
+It is also recognized for xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_types-of-domain-objects_view-models[view models] (eg annotated with xref:../rgant/rgant.adoc#_rgant-ViewModel[`@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:../rgant/rgant.adoc#_rgant-RequestScoped[`@RequestScoped`] domain services, the method is called at the beginning of the request.
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-XmlJavaTypeAdapter.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-XmlJavaTypeAdapter.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-XmlJavaTypeAdapter.adoc
index b24585c..48eb4e3 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-XmlJavaTypeAdapter.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-XmlJavaTypeAdapter.adoc
@@ -22,6 +22,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:../ugbtb/ugbtb.adoc#_ugbtb_view-models[this topic]
+For a more complete discussion of writing JAXB view models/DTOs, see xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_types-of-domain-objects_view-models[this topic]
in the user guide.
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-XmlRootElement.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-XmlRootElement.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-XmlRootElement.adoc
index 220a1fe..51c290d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-XmlRootElement.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-XmlRootElement.adoc
@@ -6,7 +6,7 @@
The `@XmlRootElement` annotation provides an alternative way to define a
-xref:rg.adoc#_ugbtb_view-models[view model], in particular one intended to act as a DTO for use within
+xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_types-of-domain-objects_view-models[view model], in particular one intended to act as a DTO for use within
xref:../ugvro/ugvro.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
@@ -74,10 +74,10 @@ public class ToDoItemDto implements Dto {
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:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_mixins[mixins] (annotated with
+Behaviour can therefore be provided using xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_types-of-domain-objects_mixins[mixins] (annotated with
xref:../rgant/rgant.adoc#_rgant-Mixin[`@Mixin`]), while xref:../rgcms/rgcms.adoc#_rgcms_classes_uievent[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:../ugbtb/ugbtb.adoc#_ugbtb_view-models[this topic]
+For a more complete discussion of writing JAXB view models/DTOs, see xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_types-of-domain-objects_view-models[this topic]
in the user guide.
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/rgcfg/_rgcfg_configuring-core.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcfg/_rgcfg_configuring-core.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcfg/_rgcfg_configuring-core.adoc
index 4535000..bacff5d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcfg/_rgcfg_configuring-core.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcfg/_rgcfg_configuring-core.adoc
@@ -547,7 +547,7 @@ This is by way of possibly deprecating and eventually moving contributed service
| When searching for xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_disable[`disableXxx()`] or xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_hide[`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:../rgcms/rgcms.adoc#_rgcms_classes_mixins[mixins] must be used instead of xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_contributions[contributed services].
+Note that this in effect means that xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_types-of-domain-objects_mixins[mixins] must be used instead of xref:../ugfun/ugfun.adoc#_ugfun_programming-model_domain-services_contributions[contributed services].
|`isis.reflector.validator.` +
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_mixins.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_mixins.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_mixins.adoc
index 355759c..96480d9 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_mixins.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_mixins.adoc
@@ -5,8 +5,12 @@
:_imagesdir: images/
-The interfaces listed in this chapter are role interfaces; they define a contract for the framework
- to interact with those domain objects that implement these interfaces.
+This chapter defines a number of role interfaces that definea contract for some framework-defined mixins.
+
+[TIP]
+====
+See the xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_types-of-domain-objects_mixins[fundamentals user guide] for a discussion of mixins.
+====
include::_rgcms_classes_mixins_Object.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_mixins_Dto.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_mixins_Dto.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_mixins_Dto.adoc
index 31e709e..48992e9 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_mixins_Dto.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_mixins_Dto.adoc
@@ -7,8 +7,7 @@
The `Dto` role interface is intended to be implemented by JAXB-annotated view models, that is, annotated using
xref:../rgant/rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`]. It enables the ability to download the XML and
-XSD schema of those objects using two xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_mixins[mixins],
-`Dto_downloadXml` and `Dto_downloadXsd`.
+XSD schema of those objects using two xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_types-of-domain-objects_mixins[mixins], `Dto_downloadXml` and `Dto_downloadXsd`.
The interface is just a marker interface (with no members), and is defined as:
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_disable.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_disable.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_disable.adoc
index b4e4e86..e2bae19 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_disable.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_disable.adoc
@@ -89,6 +89,6 @@ 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:../rgcms/rgcms.adoc#_rgcms_classes_mixins[mixins] must be used instead of xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_contributions[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:../ugfun/ugfun.adoc#_ugfun_building-blocks_types-of-domain-objects_mixins[mixins] must be used instead of xref:../ugfun/ugfun.adoc#_ugfun_programming-model_domain-services_contributions[contributed services] (because contributed actions are the one case where the value of a parameter to a supporting method may be non-null).
====
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_hide.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_hide.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_hide.adoc
index 7c90d4b..94d12ca 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_hide.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_hide.adoc
@@ -65,6 +65,6 @@ 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:../rgcms/rgcms.adoc#_rgcms_classes_mixins[mixins] must be used instead of xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_contributions[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:../ugfun/ugfun.adoc#_ugfun_building-blocks_types-of-domain-objects_mixins[mixins] must be used instead of xref:../ugfun/ugfun.adoc#_ugfun_programming-model_domain-services_contributions[contributed services] (because contributed actions are the one case where the value of a parameter to a supporting method may be non-null).
====
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_ContentNegotiationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_ContentNegotiationService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_ContentNegotiationService.adoc
index 6a6df6e..05c486e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_ContentNegotiationService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_ContentNegotiationService.adoc
@@ -14,7 +14,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:../ugbtb/ugbtb.adoc#_ugbtb_view-models[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:../ugfun/ugfun.adoc#_ugfun_building-blocks_types-of-domain-objects_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.
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_xsd.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_xsd.adoc b/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_xsd.adoc
index 987fc6c..b2173c4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_xsd.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_xsd.adoc
@@ -7,7 +7,7 @@
The `xsd` goal of the `isis-maven-plugin` uses the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_JaxbService[`JaxbService`] to
-generate XSD schemas from any JAXB-annotated xref:../ugbtb/ugbtb.adoc#_ugbtb_view-models[view model/DTOs].
+generate XSD schemas from any JAXB-annotated xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_types-of-domain-objects_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
@@ -18,7 +18,7 @@ The `xsd` goal defines the following properties:
* `appManifest` - fully qualified class name for the app manifest used to bootstrap the application (see discussion above)
-* `jaxbClasses` - a list of xref:rg.adoc#_ugbtb_view-models_jaxb[JAXB-annotated view model] classes;
+* `jaxbClasses` - a list of xref:../ugfun/ugfun.adoc#_ugfun_programming-model_view-models_jaxb[JAXB-annotated view model] classes;
* `output` - (optional) subdirectory under the `target` directory to generate the XSDs +
+
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_JaxbService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_JaxbService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_JaxbService.adoc
index 1cc6cc1..faa0fb8 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_JaxbService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_JaxbService.adoc
@@ -50,7 +50,7 @@ Isis provides a default implementation of the service, `o.a.i.schema.services.ja
This service is provided as a convenience for applications, but is also used internally by the framework to
xref:../rgant/rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`]-annotated
-xref:../ugbtb/ugbtb.adoc#_ugbtb_view-models[view models]. The functionality to download XML and XSD schemas is also
+xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_types-of-domain-objects_view-models[view models]. The functionality to download XML and XSD schemas is also
exposed in the UI through mixins to xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins_Dto[`Dto`] interface.
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_MementoService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_MementoService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_MementoService.adoc
index 11caf67..0d6a143 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_MementoService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_MementoService.adoc
@@ -7,8 +7,8 @@
The `MementoService` was originally introduced to simplify the implementation of
-xref:../ugbtb/ugbtb.adoc#_ugbtb_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:../ugbtb/ugbtb.adoc#_ugbtb_view-models_jaxb[JAXB view models] instead.
+xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_types-of-domain-objects_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:../ugfun/ugfun.adoc#_ugfun_programming-model_view-models_jaxb[JAXB view models] instead.
The service can also be used to create a memento of arbitrary objects, however this usage is also deprecated. (Prior
to `1.13.0` it was used internally by the core implementation of
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_Scratchpad.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_Scratchpad.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_Scratchpad.adoc
index f513b20..c31d530 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_Scratchpad.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_Scratchpad.adoc
@@ -59,7 +59,7 @@ public BigDecimal totalCost() {
Scratchpad scratchpad;
----
-A more complex example could use a xref:../ugbtb/ugbtb.adoc#_ugbtb_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:
+A more complex example could use a xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_types-of-domain-objects_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]
----
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_SwaggerService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_SwaggerService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_SwaggerService.adoc
index 3bc5d7b..99681a8 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_SwaggerService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_SwaggerService.adoc
@@ -38,7 +38,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:../ugbtb/ugbtb.adoc#_ugbtb_view-models[view model]s and to domain services with a xref:../rgant/rgant.adoc#_rgant-DomainService_nature[nature] of `VIEW_REST_ONLY`.
+xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_types-of-domain-objects_view-models[view model]s and to domain services with a xref:../rgant/rgant.adoc#_rgant-DomainService_nature[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:../rgant/rgant.adoc#_rgant-Action_restrictTo[prototype] actions.
<4> Swagger specs can be written either in JSON or YAML format.
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_AuditerService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_AuditerService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_AuditerService.adoc
index 85e0ec7..16ec117 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_AuditerService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_AuditerService.adoc
@@ -109,7 +109,7 @@ Assuming that an `AppManifest` is being used to xref:../rgcms/rgcms.adoc#_rgcms_
then this can be activated by updating the `pom.xml` and updating the `AppManifest#getModules()` method.
If menu items or contributions are not required in the UI, these can be suppressed either using security or by
-implementing a xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_vetoing-visibility[vetoing subscriber].
+implementing a xref:../ugbtb/ugbtb.adoc#_ugbtb_hints-and-tips_vetoing-visibility[vetoing subscriber].
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_AuditingService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_AuditingService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_AuditingService.adoc
index 062c87e..a80990d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_AuditingService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_AuditingService.adoc
@@ -71,7 +71,7 @@ Assuming that an `AppManifest` is being used to xref:../rgcms/rgcms.adoc#_rgcms_
then this can be activated by updating the `pom.xml` and updating the `AppManifest#getModules()` method.
If menu items or contributions are not required in the UI, these can be suppressed either using security or by
-implementing a xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_vetoing-visibility[vetoing subscriber].
+implementing a xref:../ugbtb/ugbtb.adoc#_ugbtb_hints-and-tips_vetoing-visibility[vetoing subscriber].
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_BackgroundCommandService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_BackgroundCommandService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_BackgroundCommandService.adoc
index 7040283..410673a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_BackgroundCommandService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_BackgroundCommandService.adoc
@@ -114,7 +114,7 @@ Assuming that an `AppManifest` is being used to xref:../rgcms/rgcms.adoc#_rgcms_
then this can be activated by updating the `pom.xml` and updating the `AppManifest#getModules()` method.
If contributions are not required in the UI, these can be suppressed either using security or by implementing a
-xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_vetoing-visibility[vetoing subscriber].
+xref:../ugbtb/ugbtb.adoc#_ugbtb_hints-and-tips_vetoing-visibility[vetoing subscriber].
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_CommandService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_CommandService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_CommandService.adoc
index d0dcb05..5f6d036 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_CommandService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_CommandService.adoc
@@ -101,7 +101,7 @@ Assuming that an `AppManifest` is being used to xref:../rgcms/rgcms.adoc#_rgcms_
then this can be activated by updating the `pom.xml` and updating the `AppManifest#getModules()` method.
If contributions are not required in the UI, these can be suppressed either using security or by implementing a
-xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_vetoing-visibility[vetoing subscriber].
+xref:../ugbtb/ugbtb.adoc#_ugbtb_hints-and-tips_vetoing-visibility[vetoing subscriber].
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_PublisherService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_PublisherService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_PublisherService.adoc
index 192638f..4d0d648 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_PublisherService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_PublisherService.adoc
@@ -120,7 +120,7 @@ the `pom.xml` and updating the `AppManifest#getModules()` method.
The module also provide services that contribute to the UI. If contributions are not required in the UI, these can be
suppressed either using security or by implementing a
-xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_vetoing-visibility[vetoing subscriber].
+xref:../ugbtb/ugbtb.adoc#_ugbtb_hints-and-tips_vetoing-visibility[vetoing subscriber].
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_PublishingService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_PublishingService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_PublishingService.adoc
index f64091a..a8a7787 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_PublishingService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_PublishingService.adoc
@@ -160,7 +160,7 @@ the `pom.xml` and updating the `AppManifest#getModules()` method.
The module also provides services that contribute to the UI. If contributions are not required in the UI, these can be
suppressed either using security or by implementing a
-xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_vetoing-visibility[vetoing subscriber].
+xref:../ugbtb/ugbtb.adoc#_ugbtb_hints-and-tips_vetoing-visibility[vetoing subscriber].
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_TranslationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_TranslationService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_TranslationService.adoc
index 16a713e..53bc9b6 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_TranslationService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_TranslationService.adoc
@@ -64,7 +64,7 @@ Assuming that the `configuration-and-annotation` services installer is configure
`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
implementation of `TranslationService` service (along with the supporting menu service) are automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
-If the menu items are not required then these can be suppressed either using security or by implementing a xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_vetoing-visibility[vetoing subscriber].
+If the menu items are not required then these can be suppressed either using security or by implementing a xref:../ugbtb/ugbtb.adoc#_ugbtb_hints-and-tips_vetoing-visibility[vetoing subscriber].
To use an alternative implementation, use
xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_UrlEncodingService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_UrlEncodingService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_UrlEncodingService.adoc
index 05f948c..0dd1e21 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_UrlEncodingService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_UrlEncodingService.adoc
@@ -7,7 +7,7 @@
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:../ugbtb/ugbtb.adoc#_ugbtb_view-models[view model]
+within a URL. The service is used by the framework to map xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_types-of-domain-objects_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.
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling.adoc
deleted file mode 100644
index 48b29ca..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling.adoc
+++ /dev/null
@@ -1,30 +0,0 @@
-[[_ugbtb_decoupling]]
-= Decoupling
-: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 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.
-
-
-This section describes how to use Apache Isis' features to ensure that your domain application remains decoupled.
-The techniques described here are also the ones that have been adopted by the various http://github.com/isisaddons[Isis Addons] modules (not ASF) for security, commands, auditing etc.
-
-The following sections describe how to re-assemble an application, in particular where some modules are in-house but others are potentially third-party (eg the Isis Addons modules).
-
-[NOTE]
-====
-There is some overlap with Java 9's Jigsaw concepts of "module"; in the future we expect to refactor Apache Isis to build on top of this module system.
-====
-
-include::_ugbtb_decoupling_db-schemas.adoc[leveloffset=+1]
-include::_ugbtb_decoupling_mixins.adoc[leveloffset=+1]
-include::_ugbtb_decoupling_contributions.adoc[leveloffset=+1]
-include::_ugbtb_decoupling_vetoing-visibility.adoc[leveloffset=+1]
-include::_ugbtb_decoupling_event-bus.adoc[leveloffset=+1]
-include::_ugbtb_decoupling_pushing-changes.adoc[leveloffset=+1]
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_contributed-members.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_contributed-members.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_contributed-members.adoc
deleted file mode 100644
index 92c37b4..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_contributed-members.adoc
+++ /dev/null
@@ -1,9 +0,0 @@
-[[_ugbtb_decoupling_contributed-members]]
-= Contributed Members
-: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/
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/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
deleted file mode 100644
index 09844ad..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_contributions.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-[[_ugbtb_decoupling_contributions]]
-= Contributions
-: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 - combine with mixins, above
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_db-schemas.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_db-schemas.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_db-schemas.adoc
deleted file mode 100644
index 389185c..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_db-schemas.adoc
+++ /dev/null
@@ -1,141 +0,0 @@
-[[_ugbtb_decoupling_db-schemas]]
-= Database Schemas
-: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 the same way that Java packages act as a namespace for domain objects, it's good practice to map domain entities to
-their own (database) schemas. As of 1.9.0, all the link:http://www.isisaddons.org[Isis Addons] (non-ASF) modules do this, for example:
-
-
-
-[source,java]
-----
-@javax.jdo.annotations.PersistenceCapable( ...
- schema = "isissecurity",
- table = "ApplicationUser")
-public class ApplicationUser ... { ... }
-----
-
-results in a `CREATE TABLE` statement of:
-
-[source,sql]
-----
-CREATE TABLE isissecurity."ApplicationUser" (
- ...
-)
-----
-
-
-while:
-
-[source,java]
-----
-@javax.jdo.annotations.PersistenceCapable( ...
- schema = "isisaudit",
- table="AuditEntry")
-public class AuditEntry ... { ... }
-----
-
-similarly results in:
-
-[source,sql]
-----
-CREATE TABLE isisaudit."AuditEntry" (
- ...
-)
-----
-
-
-[TIP]
-====
-If for some reason you don't want to use schemas (though we strongly recommend that you do), then note that you can override the `@PersistenceCapable` annotation by providing XML metadata (the `mappings.jdo` file); see the section on xref:../ugodn/ugodn.adoc#_ugodn_configuring[configuring DataNucleus Overriding Annotations] for more details.
-====
-
-
-
-
-== Listener to create schema
-
-JDO/DataNucleus does not automatically create these schema objects, but it _does_ provide a listener callback API
-on the initialization of each class into the JDO metamodel.
-
-[TIP]
-====
-Actually, the above statement isn't quite true. In DN 3.2.x (as used by Apache Isis up to v1.8.0) there was no support for schemas. As of Apache Isis 1.9.0 and DN 4.0 there is now support. But we implemented this feature initially against DN 3.2.x, and it still works, so for now we've decided to leave it in.
-====
-
-Therefore Apache Isis attaches a listener, `CreateSchemaObjectFromClassMetadata`, that checks for the schema's existence, and creates the schema if required.
-
-The guts of its implementation is:
-
-[source,java]
-----
-public class CreateSchemaObjectFromClassMetadata
- implements MetaDataListener,
- DataNucleusPropertiesAware {
- @Override
- public void loaded(final AbstractClassMetaData cmd) { ... }
-
- protected String buildSqlToCheck(final AbstractClassMetaData cmd) {
- final String schemaName = schemaNameFor(cmd);
- return String.format(
- "SELECT count(*) FROM INFORMATION_SCHEMA.SCHEMATA where SCHEMA_NAME = '%s'", schemaName);
- }
- protected String buildSqlToExec(final AbstractClassMetaData cmd) {
- final String schemaName = schemaNameFor(cmd);
- return String.format("CREATE SCHEMA \"%s\"", schemaName);
- }
-}
-----
-
-where `MetaDataListener` is the DataNucleus listener API:
-
-[source,java]
-----
-public interface MetaDataListener {
- void loaded(AbstractClassMetaData cmd);
-}
-----
-
-Although not formal API, the default `CreateSchemaObjectFromClassMetadata` has been designed to be easily overrideable if you
-need to tweak it to support other RDBMS'. Any implementation must implement `org.datanucleus.metadata.MetaDataListener`:
-
-The implementation provided has has been tested for HSQLDB, PostgreSQL and MS SQL Server, and is used automatically unless an alternative implementation is specified (as described in the section below).
-
-
-
-
-
-== Alternative implementation
-
-An alternative implementation can be registered and used through the following configuration property:
-
-[source,ini]
-----
-isis.persistor.datanucleus.classMetadataLoadedListener=\
- org.apache.isis.objectstore.jdo.datanucleus.CreateSchemaObjectFromClassMetadata
-----
-
-
-Because this pertains to the JDO Objectstore we suggest you put this configuration property in `WEB-INF/persistor_datanucleus.properties`; but putting it in `isis.properties` will also work.
-
-Any implementation must implement `org.datanucleus.metadata.MetaDataListener`. In many cases simply subclassing from `CreateSchemaObjectFromClassMetadata` and overriding `buildSqlToCheck(...)` and `buildSqlToExec(...)` should suffice.
-
-If you _do_ need more control, your implementation can also optionally implement `org.apache.isis.objectstore.jdo.datanucleus.DataNucleusPropertiesAware`:
-
-[source,java]
-----
-public interface DataNucleusPropertiesAware {
- public void setDataNucleusProperties(final Map<String, String> properties);
-}
-----
-
-This provides access to the properties passed through to JDO/DataNucleus.
-
-
-[IMPORTANT]
-====
-If you do extend Apache Isis' `CreateSchemaObjectFromClassMetadata` class for some other database, please https://issues.apache.org/jira/browse/ISIS[contribute back] your improvements.
-====
-
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_event-bus.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_event-bus.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_event-bus.adoc
deleted file mode 100644
index 9f866fc..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_event-bus.adoc
+++ /dev/null
@@ -1,11 +0,0 @@
-[[_ugbtb_decoupling_event-bus]]
-= Event Bus
-: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 - see xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`], xref:../rgant/rgant.adoc#_rgant-Action_domainEvent[`@Action#domainEvent()`], xref:../rgant/rgant.adoc#_rgant-Property_domainEvent[`@Property#domainEvent()`], xref:../rgant/rgant.adoc#_rgant-Collection_domainEvent[`@Collection#domainEvent()`], xref:../rgsvc/rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`].
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/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
deleted file mode 100644
index 566b840..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_mixins.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-[[_ugbtb_decoupling_mixins]]
-= Mixins
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../../
-:_imagesdir: images/
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_pushing-changes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_pushing-changes.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_pushing-changes.adoc
deleted file mode 100644
index abd6e52..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_pushing-changes.adoc
+++ /dev/null
@@ -1,140 +0,0 @@
-[[_ugbtb_decoupling_pushing-changes]]
-= Pushing Changes
-: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]
-====
-This technique is much less powerful than using xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_event-bus[the event bus] . We present it mostly for completeness.
-====
-
-
-
-
-== When a property is changed
-
-If you want to invoke functionality whenever a property is changed by the user, then you should create a supporting `modifyXxx()` method and include the functionality within that. The syntax is:
-
-[source,java]
---
-public void modifyPropertyName(PropertyType param) { ... }
---
-
-Why not just put this functionality in the setter? Well, the setter is used by the object store to recreate the state of an already persisted object. Putting additional behaviour in the setter would cause it to be triggered incorrectly.
-
-For example:
-
-[source,java]
---
-public class Order() {
- public Integer getAmount() { ... }
- public void setAmount(Integer amount) { ... }
- public void modifyAmount(Integer amount) { // <1>
- setAmount(amount); // <3>
- addToTotal(amount); // <2>
- }
- ...
-}
---
-<1> The `modifyAmount()` method calls ...
-<2> ... the `addToTotal()` (not shown) to maintain some running total.
-
-We don't want this `addToCall()` method to be called when pulling the object back from the object store, so we put it into the modify, not the setter.
-
-You may optionally also specify a `clearXxx()` which works the same way as modify `modify Xxx()` but is called when the property is cleared by the user (i.e. the current value replaced by nothing). The syntax is:
-
-[source,java]
---
-public void clearPropertyName() { ... }
---
-
-To extend the above example:
-
-[source,java]
---
-public class Order() {
- public Integer getAmount() { ... }
- public void setAmount(Integer amount) { ... }
- public void modifyAmount(Integer amount) { ... }
- public void clearAmount() {
- removeFromTotal(this.amount);
- setAmount(null);
- }
- ...
-}
---
-
-
-
-
-== When a collection is modified
-
-A collection may have a corresponding `addToXxx()` and/or
-`removeFromXxx()` method. If present, and direct manipulation of the
-contents of the connection has not been disabled (see ?), then they will
-be called (instead of adding/removing an object directly to the
-collection returned by the accessor).
-
-The reason for this behaviour is to allow other behaviour to be
-triggered when the contents of the collection is altered. That is, it is
-directly equivalent to the supporting `modifyXxx()` and `clearXxx()`
-methods for properties (see ?).
-
-The syntax is:
-
-[source,java]
---
-public void addTo<CollectionName>(EntityType param) { ... }
---
-
-and
-
-[source,java]
---
-public void removeFromCollectionName(EntityType param) { ... }
---
-
-where `EntityType` is the same type as the generic collection type.
-
-For example:
-
-[source,java]
---
-public class Employee { ... }
-
-public class Department {
-
- private int numMaleEmployees; // <1>
- private int numFemaleEmployees; // <2>
-
- private Set<Employee> employees = new TreeSet<Employee>();
- public Set<Employee> getEmployees() {
- return employees;
- }
- private void setEmployees(Set<Employee> employees) {
- this.employees = employees;
- }
- public void addToEmployees(Employee employee) { // <3>
- numMaleEmployees += countOneMale(employee);
- numFemaleEmployees += countOneFemale(employee);
- employees.add(employee);
- }
- public void removeFromEmployees(Employee employee) { // <4>
- numMaleEmployees -= countOneMale(employee);
- numFemaleEmployees -= countOneFemale(employee);
- employees.remove(employee);
- }
- private int countOneMale(Employee employee) { return employee.isMale()?1:0; }
- private int countOneFemale(Employee employee) { return employee.isFemale()?1:0; }
-
- ...
-}
---
-<1> maintain a count of the number of male ...
-<2> ... and female employees (getters and setters omitted)
-<3> the xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_addTo[`addTo...()`] method increments the derived properties
-<4> the xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_removeFrom[`removeFrom...()`] method similarly decrements the derived properties
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_vetoing-visibility.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_vetoing-visibility.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_vetoing-visibility.adoc
deleted file mode 100644
index c012be3..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_decoupling_vetoing-visibility.adoc
+++ /dev/null
@@ -1,15 +0,0 @@
-[[_ugbtb_decoupling_vetoing-visibility]]
-= Vetoing Visibility
-: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 - a write-up of the "vetoing subscriber" design pattern, eg as described in the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`]
-
-
-eg if included an addon such as auditing or security.
-
-solution is to write a domain event subscriber that vetoes the visibility
-
-All the addons actions inherit from common base classes so this can be as broad-brush or fine-grained as required
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips.adoc
index 8ebe0a7..c79c0c4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips.adoc
@@ -24,7 +24,9 @@ See also hints-n-tips chapters in the:
include::_ugbtb_hints-and-tips_are-you-sure.adoc[leveloffset=+1]
+include::_ugbtb_hints-and-tips_vetoing-visibility.adoc[leveloffset=+1]
include::_ugbtb_hints-and-tips_how-to-handle-void-and-null-results.adoc[leveloffset=+1]
include::_ugbtb_hints-and-tips_subclass-properties-in-tables.adoc[leveloffset=+1]
include::_ugbtb_hints-and-tips_simulating-collections-of-values.adoc[leveloffset=+1]
+include::_ugbtb_hints-and-tips_pushing-changes.adoc[leveloffset=+1]
include::_ugbtb_hints-and-tips_how-to-implement-a-spellchecker.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_are-you-sure.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_are-you-sure.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_are-you-sure.adoc
index 66bc6d7..be0e1b4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_are-you-sure.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_are-you-sure.adoc
@@ -29,7 +29,7 @@ public SimpleObject updateName(
This will render as:
-image::{_imagesdir}/how-tos/tips-n-tricks/action-semantics-are-you-sure.png[]
+image::{_imagesdir}/hints-and-tips/action-semantics-are-you-sure.png[]
== Using a checkbox
@@ -38,7 +38,7 @@ An alternative approach (for all versions of the framework) is to require the en
For example:
-image::{_imagesdir}/how-tos/tips-n-tricks/are-you-sure.png[]
+image::{_imagesdir}/hints-and-tips/are-you-sure.png[]
[NOTE]
====
@@ -47,13 +47,13 @@ Note that these screenshots shows an earlier version of the xref:../ugvw/ugvw.ad
If the user checks the box:
-image::{_imagesdir}/how-tos/tips-n-tricks/are-you-sure-happy-case.png[]
+image::{_imagesdir}/hints-and-tips/are-you-sure-happy-case.png[]
then the action will complete.
However, if the user fails to check the box, then a validation message is shown:
-image::{_imagesdir}/how-tos/tips-n-tricks/are-you-sure-sad-case.png[]
+image::{_imagesdir}/hints-and-tips/are-you-sure-sad-case.png[]
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_pushing-changes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_pushing-changes.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_pushing-changes.adoc
new file mode 100644
index 0000000..44f6eb9
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_pushing-changes.adoc
@@ -0,0 +1,140 @@
+[[_ugbtb_hints-and-tips_pushing-changes]]
+= Pushing Changes (deprecated)
+: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]
+====
+This technique is much less powerful than using ../ugfun/ugfun.adoc#_ugfun_building-blocks_events_domain-events[the event bus] or an SPI service.
+We present it mostly for completeness.
+====
+
+
+
+
+== When a property is changed
+
+If you want to invoke functionality whenever a property is changed by the user, then you can create a supporting `modifyXxx()` method and include the functionality within that. The syntax is:
+
+[source,java]
+--
+public void modifyPropertyName(PropertyType param) { ... }
+--
+
+Why not just put this functionality in the setter? Well, the setter is used by the object store to recreate the state of an already persisted object. Putting additional behaviour in the setter would cause it to be triggered incorrectly.
+
+For example:
+
+[source,java]
+--
+public class Order() {
+ public Integer getAmount() { ... }
+ public void setAmount(Integer amount) { ... }
+ public void modifyAmount(Integer amount) { // <1>
+ setAmount(amount); // <3>
+ addToTotal(amount); // <2>
+ }
+ ...
+}
+--
+<1> The `modifyAmount()` method calls ...
+<2> ... the `addToTotal()` (not shown) to maintain some running total.
+
+We don't want this `addToCall()` method to be called when pulling the object back from the object store, so we put it into the modify, not the setter.
+
+You may optionally also specify a `clearXxx()` which works the same way as modify `modify Xxx()` but is called when the property is cleared by the user (i.e. the current value replaced by nothing). The syntax is:
+
+[source,java]
+--
+public void clearPropertyName() { ... }
+--
+
+To extend the above example:
+
+[source,java]
+--
+public class Order() {
+ public Integer getAmount() { ... }
+ public void setAmount(Integer amount) { ... }
+ public void modifyAmount(Integer amount) { ... }
+ public void clearAmount() {
+ removeFromTotal(this.amount);
+ setAmount(null);
+ }
+ ...
+}
+--
+
+
+
+== When a collection is modified
+
+A collection may have a corresponding `addToXxx()` and/or
+`removeFromXxx()` method. If present, and direct manipulation of the
+contents of the connection has not been disabled (see ?), then they will
+be called (instead of adding/removing an object directly to the
+collection returned by the accessor).
+
+The reason for this behaviour is to allow other behaviour to be
+triggered when the contents of the collection is altered. That is, it is
+directly equivalent to the supporting `modifyXxx()` and `clearXxx()`
+methods for properties (see ?).
+
+The syntax is:
+
+[source,java]
+--
+public void addTo<CollectionName>(EntityType param) { ... }
+--
+
+and
+
+[source,java]
+--
+public void removeFromCollectionName(EntityType param) { ... }
+--
+
+where `EntityType` is the same type as the generic collection type.
+
+For example:
+
+[source,java]
+--
+public class Employee { ... }
+
+public class Department {
+
+ private int numMaleEmployees; // <1>
+ private int numFemaleEmployees; // <2>
+
+ private Set<Employee> employees = new TreeSet<Employee>();
+ public Set<Employee> getEmployees() {
+ return employees;
+ }
+ private void setEmployees(Set<Employee> employees) {
+ this.employees = employees;
+ }
+ public void addToEmployees(Employee employee) { // <3>
+ numMaleEmployees += countOneMale(employee);
+ numFemaleEmployees += countOneFemale(employee);
+ employees.add(employee);
+ }
+ public void removeFromEmployees(Employee employee) { // <4>
+ numMaleEmployees -= countOneMale(employee);
+ numFemaleEmployees -= countOneFemale(employee);
+ employees.remove(employee);
+ }
+ private int countOneMale(Employee employee) { return employee.isMale()?1:0; }
+ private int countOneFemale(Employee employee) { return employee.isFemale()?1:0; }
+
+ ...
+}
+--
+<1> maintain a count of the number of male ...
+<2> ... and female employees (getters and setters omitted)
+<3> the xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_addTo[`addTo...()`] method increments the derived properties
+<4> the xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_removeFrom[`removeFrom...()`] method similarly decrements the derived properties
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_vetoing-visibility.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_vetoing-visibility.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_vetoing-visibility.adoc
new file mode 100644
index 0000000..da0742b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_vetoing-visibility.adoc
@@ -0,0 +1,15 @@
+[[_ugbtb_hints-and-tips_vetoing-visibility]]
+= Vetoing Visibility
+: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 - a write-up of the "vetoing subscriber" design pattern, eg as described in the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`]
+
+
+eg if included an addon such as auditing or security.
+
+solution is to write a domain event subscriber that vetoes the visibility
+
+All the addons actions inherit from common base classes so this can be as broad-brush or fine-grained as required
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/ugbtb/images/hints-and-tips/action-semantics-are-you-sure.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/images/hints-and-tips/action-semantics-are-you-sure.png b/adocs/documentation/src/main/asciidoc/guides/ugbtb/images/hints-and-tips/action-semantics-are-you-sure.png
new file mode 100644
index 0000000..f0cf269
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/ugbtb/images/hints-and-tips/action-semantics-are-you-sure.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/ugbtb/images/hints-and-tips/are-you-sure-happy-case.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/images/hints-and-tips/are-you-sure-happy-case.png b/adocs/documentation/src/main/asciidoc/guides/ugbtb/images/hints-and-tips/are-you-sure-happy-case.png
new file mode 100644
index 0000000..1981c09
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/ugbtb/images/hints-and-tips/are-you-sure-happy-case.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/ugbtb/images/hints-and-tips/are-you-sure-sad-case.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/images/hints-and-tips/are-you-sure-sad-case.png b/adocs/documentation/src/main/asciidoc/guides/ugbtb/images/hints-and-tips/are-you-sure-sad-case.png
new file mode 100644
index 0000000..6182447
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/ugbtb/images/hints-and-tips/are-you-sure-sad-case.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/ugbtb/images/hints-and-tips/are-you-sure.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/images/hints-and-tips/are-you-sure.png b/adocs/documentation/src/main/asciidoc/guides/ugbtb/images/hints-and-tips/are-you-sure.png
new file mode 100644
index 0000000..e1a76fe
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/ugbtb/images/hints-and-tips/are-you-sure.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/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 3d3c365..5f29c15 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_decoupling.adoc[leveloffset=+1]
include::_ugbtb_i18n.adoc[leveloffset=+1]
include::_ugbtb_headless-access.adoc[leveloffset=+1]
include::_ugbtb_hints-and-tips.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_events_domain-events.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_events_domain-events.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_events_domain-events.adoc
index 9911cc6..f491a21 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_events_domain-events.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_events_domain-events.adoc
@@ -5,7 +5,7 @@
:_imagesdir: images/
-Domain events are fired for each object member (property, collection or action).
+Domain events are fired -- through the internal xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[event bus] -- for every user interaction with 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.
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_types-of-domain-objects_view-models.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_types-of-domain-objects_view-models.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_types-of-domain-objects_view-models.adoc
index 07c8b50..020a3d2 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_types-of-domain-objects_view-models.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_types-of-domain-objects_view-models.adoc
@@ -127,7 +127,7 @@ This is done by annotating the class using JAXB annotations; this allows the con
A discussion of how that might be done using an ESB such as link:http://camel.apache.org[Apache Camel(TM)] follows xref:../ugbtb/ugbtb.adoc#__ugfun_building-blocks_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:../ugvw/ugvw.adoc#[Wicket viewer] just like any other.
-In fact (as the xref:../ugbtb/ugbtb.adoc#_ugbtb_view-models_programming-model[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.
+In fact (as the xref:../ugfun/ugfun.adoc#_ugfun_programming-model_view-models_jaxb[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.
It's also worth noting that it is also possible to download the XML (or XSD) straight from the UI, useful during development.
The view model simply needs to implement the xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins_Dto[`Dto`] marker interface; the framework has xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins_Dto[mixins] that contribute the download actions to the view model.
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_cqrs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_cqrs.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_cqrs.adoc
index 9f7b296..d80779f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_cqrs.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_cqrs.adoc
@@ -32,7 +32,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:../rgsvc/rgsvc.adoc#_rgsvc_api_PublishingService[`PublishingService`], or using xref:../rgcms/rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[subscribers] on the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`].
-One can then use xref:../ugbtb/ugbtb.adoc#_ugbtb_view-models[view models] to surface the data in the external read datastore.
+One can then use xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_types-of-domain-objects_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:../rgsvc/rgsvc.adoc#_rgsvc_spi_CommandService[`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.
@@ -43,7 +43,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:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_mixins[mixins] or xref:../ugfun/ugfun.adoc#_ugfun_how-tos_contributed-members[contributions].
+In Apache Isis this same separation of business logic from the underlying data can be accomplished most straightforwardly using xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_types-of-domain-objects_mixins[mixins] or xref:../ugfun/ugfun.adoc#_ugfun_how-tos_contributed-members[contributions].
In the UI (surfaced by the xref:../ugvw/ugvw.adoc#[Wicket viewer]) or in the REST API (surfaced by the xref:../ugvro/ugvro.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.
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_aop.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_aop.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_aop.adoc
index b1f20e0..bbe6b6a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_aop.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_aop.adoc
@@ -62,4 +62,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 at least - 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:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_mixins[mixins]), (xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_contributions[contributions]) and interceptors (the xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_event-bus[event bus]) to ensure that your codebase remains maintainable.
\ No newline at end of file
+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:../ugfun/ugfun.adoc#_ugfun_building-blocks_types-of-domain-objects_mixins[mixins]), (xref:../ugfun/ugfun.adoc#_ugfun_programming-model_domain-services_contributions[contributed services]) and interceptors (the xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_events_domain-events[event bus]) to ensure that your codebase remains maintainable.
\ No newline at end of file
[4/5] isis git commit: cleans up ugbtb a little
Posted by da...@apache.org.
cleans up ugbtb a little
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/074b9113
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/074b9113
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/074b9113
Branch: refs/heads/wip
Commit: 074b9113f490a61981735c2eb46cbe518260b9e1
Parents: 01fb90b
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Thu Apr 20 06:07:08 2017 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Thu Apr 20 06:07:08 2017 +0100
----------------------------------------------------------------------
.../_rgfis_spi_ContentNegotiationService.adoc | 2 +-
.../guides/ugbtb/_ugbtb_deployment_docker.adoc | 4 +-
.../guides/ugbtb/_ugbtb_hints-and-tips.adoc | 10 ++-
.../_ugbtb_hints-and-tips_multi-tenancy.adoc | 13 ++++
.../_ugbtb_hints-and-tips_persisted-title.adoc | 82 ++++++++++++++++++++
...placing-default-service-implementations.adoc | 64 +++++++++++++++
..._hints-and-tips_transactions-and-errors.adoc | 78 +++++++++++++++++++
.../guides/ugbtb/_ugbtb_other-techniques.adoc | 5 --
...tb_other-techniques_mapping-rdbms-views.adoc | 9 ---
.../_ugbtb_other-techniques_multi-tenancy.adoc | 13 ----
..._ugbtb_other-techniques_persisted-title.adoc | 82 --------------------
...placing-default-service-implementations.adoc | 64 ---------------
...ther-techniques_transactions-and-errors.adoc | 78 -------------------
.../_ugbtb_programming-model_finetuning.adoc | 2 +-
.../src/main/asciidoc/guides/ugbtb/ugbtb.adoc | 1 -
15 files changed, 250 insertions(+), 257 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/074b9113/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_ContentNegotiationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_ContentNegotiationService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_ContentNegotiationService.adoc
index 05c486e..0342d47 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_ContentNegotiationService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_ContentNegotiationService.adoc
@@ -18,7 +18,7 @@ Instead you need to create some sort of stable facade over your domain entities,
+
If the underlying entities change, then care must be taken to ensure that structure of the view model nevertheless is unchanged.
-* a second option is to solve the problem at the persistence layer, but defining a (SQL) view in the database and then xref:../ugbtb/ugbtb.adoc#_ugbtb_other-techniques_mapping-rdbms-views[mapping this] to a (read-only) entity. Again this is surfaced by the RO viewer. +
+* a second option is to solve the problem at the persistence layer, but defining a (SQL) view in the database and then xref:../ugodn/ugodn.adoc#_ugodn_hints-and-tips_mapping-to-a-view[mapping this] to a (read-only) entity. Again this is surfaced by the RO viewer. +
+
If the underlying tables change (as the result of a change in their corresponding domain entities) then once more the view must be refactored so that it still presents the same structure.
http://git-wip-us.apache.org/repos/asf/isis/blob/074b9113/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_docker.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_docker.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_docker.adoc
index dc84356..ea3b08e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_docker.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_docker.adoc
@@ -18,7 +18,7 @@ Docker host can be assured.
====
-== Using an `overrides.properties` file
+== Using an `overrides.properties`
In addition to loading the regular configuration properties from `WEB-INF` directory (described
xref:../rgcfg/rgcfg.adoc#_rgcfg_configuration-files[here]), Apache Isis will also load the `overrides.properties` file.
@@ -63,7 +63,7 @@ The Docker's `ENTRYPOINT` therefore just needs to parse the Docker container's o
create this file.
-== Using the `ISIS_OPTS` environment variable
+== Using `$ISIS_OPTS`
The servlet context initializer will search for an environment variable called `$ISIS_OPTS`
and if present will parse the content as a set of key/value pairs. Each key/value pair is separated by "||".
http://git-wip-us.apache.org/repos/asf/isis/blob/074b9113/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips.adoc
index c79c0c4..6286cf7 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips.adoc
@@ -24,9 +24,17 @@ See also hints-n-tips chapters in the:
include::_ugbtb_hints-and-tips_are-you-sure.adoc[leveloffset=+1]
+include::_ugbtb_hints-and-tips_replacing-default-service-implementations.adoc[leveloffset=+1]
include::_ugbtb_hints-and-tips_vetoing-visibility.adoc[leveloffset=+1]
+include::_ugbtb_hints-and-tips_transactions-and-errors.adoc[leveloffset=+1]
+include::_ugbtb_hints-and-tips_persisted-title.adoc[leveloffset=+1]
+
+include::_ugbtb_hints-and-tips_simulating-collections-of-values.adoc[leveloffset=+1]
+
include::_ugbtb_hints-and-tips_how-to-handle-void-and-null-results.adoc[leveloffset=+1]
+include::_ugbtb_hints-and-tips_multi-tenancy.adoc[leveloffset=+1]
+
include::_ugbtb_hints-and-tips_subclass-properties-in-tables.adoc[leveloffset=+1]
-include::_ugbtb_hints-and-tips_simulating-collections-of-values.adoc[leveloffset=+1]
include::_ugbtb_hints-and-tips_pushing-changes.adoc[leveloffset=+1]
include::_ugbtb_hints-and-tips_how-to-implement-a-spellchecker.adoc[leveloffset=+1]
+
http://git-wip-us.apache.org/repos/asf/isis/blob/074b9113/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_multi-tenancy.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_multi-tenancy.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_multi-tenancy.adoc
new file mode 100644
index 0000000..3922514
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_multi-tenancy.adoc
@@ -0,0 +1,13 @@
+[[_ugbtb_hints-and-tips_multi-tenancy]]
+= Multi-tenancy
+: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/
+
+
+Of the various Isis Addons, the https://github.com/isisaddons/isis-module-security[security module] has the most features. One significant feature is the ability to associate users and objects with a "tenancy".
+
+
+For more details, see the https://github.com/isisaddons/isis-module-security[security module] README.
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/074b9113/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_persisted-title.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_persisted-title.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_persisted-title.adoc
new file mode 100644
index 0000000..d19b068
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_persisted-title.adoc
@@ -0,0 +1,82 @@
+[[_ugbtb_hints-and-tips_persisted-title]]
+= Persisted Title
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+
+Normally the title of an object is not persisted to the database, rather it is recomputed automatically from underlying properties. On occasion though you might want the title to also be persisted; either to make things easier for the DBA, or for an integration scenario, or some other purpose.
+
+We can implement this feature by leveraging the xref:../rgcms/rgcms.adoc#_rgcms_methods_lifecycle_jdo-api[JDO lifecycle]. In the design we discuss here we make it a responsibility of the entities to persist the title as a property, by implementing a `ObjectWithPersistedTitle` interface:
+
+[source,java]
+----
+public interface ObjectWithPersistedTitle {
+ @PropertyLayout(hidden = Where.EVERYWHERE) // <1>
+ String getTitle();
+ void setTitle(final String title);
+}
+----
+<1> we don't want to expose this in the UI because the title is already prominently displayed.
+
+We can then define a subscribing domain service that leverage this.
+
+[source,java]
+----
+@DomainService(nature = NatureOfService.DOMAIN)
+public class TitlingService extends AbstractSubscriber {
+ @Subscribe
+ public void on(final ObjectPersistingEvent ev) {
+ handle(ev.getSource());
+ }
+ @Subscribe
+ public void on(final ObjectUpdatingEvent ev) {
+ handle(ev.getSource());
+ }
+ private void handle(final Object persistentInstance) {
+ if(persistentInstance instanceof ObjectWithPersistedTitle) {
+ final ObjectWithPersistedTitle objectWithPersistedTitle =
+ (ObjectWithPersistedTitle) persistentInstance;
+ objectWithPersistedTitle.setTitle(container.titleOf(objectWithPersistedTitle));
+ }
+ }
+ @Inject
+ private DomainObjectContainer container;
+}
+----
+
+Prior to 1.10.0 (when lifecycle events were introduced), this could also be be done by accessing the JDO API directly:
+
+[source,java]
+----
+@RequestScoped
+@DomainService(nature = NatureOfService.DOMAIN)
+public class TitlingService {
+ @PostConstruct
+ public void init() {
+ isisJdoSupport.getJdoPersistenceManager().addInstanceLifecycleListener(
+ new StoreLifecycleListener() {
+ @Override
+ public void preStore(final InstanceLifecycleEvent event) {
+ final Object persistentInstance = event.getPersistentInstance();
+ if(persistentInstance instanceof ObjectWithPersistedTitle) {
+ final ObjectWithPersistedTitle objectWithPersistedTitle =
+ (ObjectWithPersistedTitle) persistentInstance;
+ objectWithPersistedTitle.setTitle(container.titleOf(objectWithPersistedTitle));
+ }
+ }
+ @Override
+ public void postStore(final InstanceLifecycleEvent event) {
+ }
+ }, null);
+ }
+ @Inject
+ private IsisJdoSupport isisJdoSupport;
+ @Inject
+ private DomainObjectContainer container;
+}
+----
+
+The above is probably the easiest and most straightforward design. One could imagine other designs where the persisted title is stored elsewhere. It could even be stored off into an link:http://lucene.apache.org/[Apache Lucene] (or similar) database to allow for free-text searches.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/074b9113/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_replacing-default-service-implementations.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_replacing-default-service-implementations.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_replacing-default-service-implementations.adoc
new file mode 100644
index 0000000..dea5096
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_replacing-default-service-implementations.adoc
@@ -0,0 +1,64 @@
+[[_ugbtb_hints-and-tips_replacing-default-service-implementations]]
+= Overriding Default Service Implns
+: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 framework provides default implementations for many of the xref:../rgsvc/rgsvc.adoc#[domain services]. This is convenient, but sometimes you will want to replace the default implementation with your own service implementation.
+
+The trick is to use the xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] attribute, specifying a low number (typically `"1"`).
+
+For example, suppose you wanted to provide your own implementation of xref:../rgsvc/rgsvc.adoc#_rgsvc_api_LocaleProvider[`LocaleProvider`]. Here's how:
+
+[source,java]
+----
+@DomainService(
+ nature = NatureOfService.DOMAIN
+)
+@DomainServiceLayout(
+ menuOrder = "1" // <1>
+)
+public class MyLocaleProvider implements LocaleProvider {
+ @Override
+ public Locale getLocale() {
+ return ...
+ }
+}
+----
+<1> takes precedence over the default implementation.
+
+
+It's also quite common to want to decorate the existing implementation (ie have your own implementation delegate to the default); this is also possible and quite easy if using `1.10.0` or later:
+
+[source,java]
+----
+@DomainService(
+ nature = NatureOfService.DOMAIN
+)
+@DomainServiceLayout(
+ menuOrder = "1" // <1>
+)
+public class MyLocaleProvider implements LocaleProvider {
+ @Override
+ public Locale getLocale() {
+ return getDelegateLocaleProvider().getLocale(); // <2>
+ }
+ Optional<LocaleProvider> delegateLocaleProvider; // <3>
+ private LocaleProvider getDelegateLocaleProvider() {
+ if(delegateLocaleProvider == null) {
+ delegateLocaleProvider = Iterables.tryFind(localeProviders, input -> input != this); // <4>
+ }
+ return delegateLocaleProvider.orNull();
+ }
+ @Inject
+ List<LocaleProvider> localeProviders; // <5>
+}
+----
+<1> takes precedence over the default implementation when injected elsewhere.
+<2> this implementation merely delegates to the default implementation
+<3> lazily populated
+<4> delegate to the first implementation that isn't _this_ implementation (else infinite loop!)
+<5> Injects all implementations, including this implemenation
+
http://git-wip-us.apache.org/repos/asf/isis/blob/074b9113/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_transactions-and-errors.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_transactions-and-errors.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_transactions-and-errors.adoc
new file mode 100644
index 0000000..fa8150f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_hints-and-tips_transactions-and-errors.adoc
@@ -0,0 +1,78 @@
+[[_ugbtb_hints-and-tips_transactions-and-errors]]
+= Transactions and Errors
+: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 Apache Isis, every interaction (action invocation or property edit) is automatically wrapped in a transaction,
+and any repository query automatically does a flush before hand.
+
+What that means is that there's no need to explicitly start or commit transactions in Apache Isis; this will be done
+for you. Indeed, if you do try to manage transactions (eg by reaching into the JDO `PersistenceManager` exposed by the
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_IsisJdoSupport[IsisJdoSupport] domain service, then you are likely to confuse the
+framework and get a stack trace for your trouble.
+
+However, you can complete a given transaction and start a new one. This is sometimes useful if writing a fixture
+script which is going to perform some sort of bulk migration of data from an old system. For this use case, use the
+xref:../rgsvc/rgsvc.adoc#_rgsvc_api_TransactionService[`TransactionService`].
+
+For example:
+
+[source,java]
+----
+public class SomeLongRunningFixtureScript extends FixtureScript
+
+ protected void execute(final ExecutionContext executionContext) {
+ // do some work
+ transactionService.nextTransaction();
+ // do some work
+ transactionService.nextTransaction();
+ // do yet more work
+ }
+
+ @javax.inject.Inject
+ TransactionService transactionService;
+}
+----
+
+You get the idea.
+
+
+== Raise message in the UI
+
+The framework provides the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_MessageService[`MessageService`] as a means to return an out-of-band
+message to the end-user. In the xref:../ugvw/ugvw.adoc#[Wicket viewer] these are shown as "toast" pop-ups; the
+xref:../ugvro/ugvro.adoc#[Restful Objects viewer] returns an HTTP header.
+
+The `UserService` provides three APIs, for different:
+
+* `informUser()` - an informational message. In the Wicket viewer these are short-lived pop-ups that disappear after a short time.
+* `warnUser()` - a warning. In the Wicket viewer these do not auto-close; they must be acknowledged.
+* `raiseError()` - an error. In the Wicket viewer these do not auto-close; they must be acknowledged.
+
+Each pop-up has a different background colour indicating its severity.
+
+None of these messages/errors has any influence on the transaction; any changes to objects will be committed.
+
+
+== Aborting transactions
+
+If you want to abort Apache Isis' transaction, this can be done by throwing an exception. The exception message
+is displayed to the user on the error page (if xref:../ugvw/ugvw.adoc#[Wicket viewer]) or a 500 status error code (if the
+xref:../ugvro/ugvro.adoc#[Restful Objects] viewer).
+
+If the exception thrown is because of an unexpected error (eg a `NullPointerException` in the domain app itself), then
+the error page will include a stack trace. If however you want to indicate that the exception is in some sense
+"expected", then throw a `RecoverableException` (or any subclass, eg `ApplicationException`); the stack trace will then
+be suppressed from the error page.
+
+Another way in which exceptions might be considered "expected" could be as the result of attempting to persist an
+object which then violates some type of database constraint. Even if the domain application checks beforehand, it
+could be that another user operating on the object at the same moment of time might result in the conflict.
+
+To handle this the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ExceptionRecognizer[`ExceptionRecognizer`] SPI can be used. The
+framework provides a number of implementations out-of-the-box; whenever an exception is thrown it is passed to each
+known recognizer implementation to see if it recognizes the exception and can return a user-meaningful error message.
+For example, `ExceptionRecognizerForSQLIntegrityConstraintViolationUniqueOrIndexException` checks if the
+exception inherits from `java.sql.SQLIntegrityConstraintViolationException`, and if so, constructs a suitable message.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/074b9113/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques.adoc
index 7cdb1e6..36961ca 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques.adoc
@@ -9,11 +9,6 @@
This chapter pulls together a number of more advanced techniques that we've discovered and developed while building our own Isis applications.
-include::_ugbtb_other-techniques_mapping-rdbms-views.adoc[leveloffset=+1]
-include::_ugbtb_other-techniques_transactions-and-errors.adoc[leveloffset=+1]
-include::_ugbtb_other-techniques_multi-tenancy.adoc[leveloffset=+1]
-include::_ugbtb_other-techniques_persisted-title.adoc[leveloffset=+1]
-include::_ugbtb_other-techniques_replacing-default-service-implementations.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/074b9113/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_mapping-rdbms-views.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_mapping-rdbms-views.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_mapping-rdbms-views.adoc
deleted file mode 100644
index a362148..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_mapping-rdbms-views.adoc
+++ /dev/null
@@ -1,9 +0,0 @@
-[[_ugbtb_other-techniques_mapping-rdbms-views]]
-= Mapping RDBMS Views
-: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 - as used in link:http://github.com/estatio/estatio[Estatio]
-
http://git-wip-us.apache.org/repos/asf/isis/blob/074b9113/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_multi-tenancy.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_multi-tenancy.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_multi-tenancy.adoc
deleted file mode 100644
index b6b5ed9..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_multi-tenancy.adoc
+++ /dev/null
@@ -1,13 +0,0 @@
-[[_ugbtb_other-techniques_multi-tenancy]]
-= Multi-tenancy
-: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/
-
-
-Of the various Isis Addons, the https://github.com/isisaddons/isis-module-security[security module] has the most features. One significant feature is the ability to associate users and objects with a "tenancy".
-
-
-For more details, see the https://github.com/isisaddons/isis-module-security[security module] README.
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/074b9113/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_persisted-title.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_persisted-title.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_persisted-title.adoc
deleted file mode 100644
index d04a082..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_persisted-title.adoc
+++ /dev/null
@@ -1,82 +0,0 @@
-[[_ugbtb_other-techniques_persisted-title]]
-= Persisted Title
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../../
-:_imagesdir: images/
-
-
-
-Normally the title of an object is not persisted to the database, rather it is recomputed automatically from underlying properties. On occasion though you might want the title to also be persisted; either to make things easier for the DBA, or for an integration scenario, or some other purpose.
-
-We can implement this feature by leveraging the xref:../rgcms/rgcms.adoc#_rgcms_methods_lifecycle_jdo-api[JDO lifecycle]. In the design we discuss here we make it a responsibility of the entities to persist the title as a property, by implementing a `ObjectWithPersistedTitle` interface:
-
-[source,java]
-----
-public interface ObjectWithPersistedTitle {
- @PropertyLayout(hidden = Where.EVERYWHERE) // <1>
- String getTitle();
- void setTitle(final String title);
-}
-----
-<1> we don't want to expose this in the UI because the title is already prominently displayed.
-
-We can then define a subscribing domain service that leverage this.
-
-[source,java]
-----
-@DomainService(nature = NatureOfService.DOMAIN)
-public class TitlingService extends AbstractSubscriber {
- @Subscribe
- public void on(final ObjectPersistingEvent ev) {
- handle(ev.getSource());
- }
- @Subscribe
- public void on(final ObjectUpdatingEvent ev) {
- handle(ev.getSource());
- }
- private void handle(final Object persistentInstance) {
- if(persistentInstance instanceof ObjectWithPersistedTitle) {
- final ObjectWithPersistedTitle objectWithPersistedTitle =
- (ObjectWithPersistedTitle) persistentInstance;
- objectWithPersistedTitle.setTitle(container.titleOf(objectWithPersistedTitle));
- }
- }
- @Inject
- private DomainObjectContainer container;
-}
-----
-
-Prior to 1.10.0 (when lifecycle events were introduced), this could also be be done by accessing the JDO API directly:
-
-[source,java]
-----
-@RequestScoped
-@DomainService(nature = NatureOfService.DOMAIN)
-public class TitlingService {
- @PostConstruct
- public void init() {
- isisJdoSupport.getJdoPersistenceManager().addInstanceLifecycleListener(
- new StoreLifecycleListener() {
- @Override
- public void preStore(final InstanceLifecycleEvent event) {
- final Object persistentInstance = event.getPersistentInstance();
- if(persistentInstance instanceof ObjectWithPersistedTitle) {
- final ObjectWithPersistedTitle objectWithPersistedTitle =
- (ObjectWithPersistedTitle) persistentInstance;
- objectWithPersistedTitle.setTitle(container.titleOf(objectWithPersistedTitle));
- }
- }
- @Override
- public void postStore(final InstanceLifecycleEvent event) {
- }
- }, null);
- }
- @Inject
- private IsisJdoSupport isisJdoSupport;
- @Inject
- private DomainObjectContainer container;
-}
-----
-
-The above is probably the easiest and most straightforward design. One could imagine other designs where the persisted title is stored elsewhere. It could even be stored off into an link:http://lucene.apache.org/[Apache Lucene] (or similar) database to allow for free-text searches.
-
http://git-wip-us.apache.org/repos/asf/isis/blob/074b9113/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_replacing-default-service-implementations.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_replacing-default-service-implementations.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_replacing-default-service-implementations.adoc
deleted file mode 100644
index c4abd5d..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_replacing-default-service-implementations.adoc
+++ /dev/null
@@ -1,64 +0,0 @@
-[[_ugbtb_other-techniques_replacing-default-service-implementations]]
-= Overriding Default Service Implns
-: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 framework provides default implementations for many of the xref:../rgsvc/rgsvc.adoc#[domain services]. This is convenient, but sometimes you will want to replace the default implementation with your own service implementation.
-
-The trick is to use the xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] attribute, specifying a low number (typically `"1"`).
-
-For example, suppose you wanted to provide your own implementation of xref:../rgsvc/rgsvc.adoc#_rgsvc_api_LocaleProvider[`LocaleProvider`]. Here's how:
-
-[source,java]
-----
-@DomainService(
- nature = NatureOfService.DOMAIN
-)
-@DomainServiceLayout(
- menuOrder = "1" // <1>
-)
-public class MyLocaleProvider implements LocaleProvider {
- @Override
- public Locale getLocale() {
- return ...
- }
-}
-----
-<1> takes precedence over the default implementation.
-
-
-It's also quite common to want to decorate the existing implementation (ie have your own implementation delegate to the default); this is also possible and quite easy if using `1.10.0` or later:
-
-[source,java]
-----
-@DomainService(
- nature = NatureOfService.DOMAIN
-)
-@DomainServiceLayout(
- menuOrder = "1" // <1>
-)
-public class MyLocaleProvider implements LocaleProvider {
- @Override
- public Locale getLocale() {
- return getDelegateLocaleProvider().getLocale(); // <2>
- }
- Optional<LocaleProvider> delegateLocaleProvider; // <3>
- private LocaleProvider getDelegateLocaleProvider() {
- if(delegateLocaleProvider == null) {
- delegateLocaleProvider = Iterables.tryFind(localeProviders, input -> input != this); // <4>
- }
- return delegateLocaleProvider.orNull();
- }
- @Inject
- List<LocaleProvider> localeProviders; // <5>
-}
-----
-<1> takes precedence over the default implementation when injected elsewhere.
-<2> this implementation merely delegates to the default implementation
-<3> lazily populated
-<4> delegate to the first implementation that isn't _this_ implementation (else infinite loop!)
-<5> Injects all implementations, including this implemenation
-
http://git-wip-us.apache.org/repos/asf/isis/blob/074b9113/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_transactions-and-errors.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_transactions-and-errors.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_transactions-and-errors.adoc
deleted file mode 100644
index 54d068c..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_transactions-and-errors.adoc
+++ /dev/null
@@ -1,78 +0,0 @@
-[[_ugbtb_other-techniques_transactions-and-errors]]
-= Transactions and Errors
-: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 Apache Isis, every interaction (action invocation or property edit) is automatically wrapped in a transaction,
-and any repository query automatically does a flush before hand.
-
-What that means is that there's no need to explicitly start or commit transactions in Apache Isis; this will be done
-for you. Indeed, if you do try to manage transactions (eg by reaching into the JDO `PersistenceManager` exposed by the
-xref:../rgsvc/rgsvc.adoc#_rgsvc_api_IsisJdoSupport[IsisJdoSupport] domain service, then you are likely to confuse the
-framework and get a stack trace for your trouble.
-
-However, you can complete a given transaction and start a new one. This is sometimes useful if writing a fixture
-script which is going to perform some sort of bulk migration of data from an old system. For this use case, use the
-xref:../rgsvc/rgsvc.adoc#_rgsvc_api_TransactionService[`TransactionService`].
-
-For example:
-
-[source,java]
-----
-public class SomeLongRunningFixtureScript extends FixtureScript
-
- protected void execute(final ExecutionContext executionContext) {
- // do some work
- transactionService.nextTransaction();
- // do some work
- transactionService.nextTransaction();
- // do yet more work
- }
-
- @javax.inject.Inject
- TransactionService transactionService;
-}
-----
-
-You get the idea.
-
-
-== Raise message/errors to users
-
-The framework provides the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_MessageService[`MessageService`] as a means to return an out-of-band
-message to the end-user. In the xref:../ugvw/ugvw.adoc#[Wicket viewer] these are shown as "toast" pop-ups; the
-xref:../ugvro/ugvro.adoc#[Restful Objects viewer] returns an HTTP header.
-
-The `UserService` provides three APIs, for different:
-
-* `informUser()` - an informational message. In the Wicket viewer these are short-lived pop-ups that disappear after a short time.
-* `warnUser()` - a warning. In the Wicket viewer these do not auto-close; they must be acknowledged.
-* `raiseError()` - an error. In the Wicket viewer these do not auto-close; they must be acknowledged.
-
-Each pop-up has a different background colour indicating its severity.
-
-None of these messages/errors has any influence on the transaction; any changes to objects will be committed.
-
-
-== Aborting transactions
-
-If you want to abort Apache Isis' transaction, this can be done by throwing an exception. The exception message
-is displayed to the user on the error page (if xref:../ugvw/ugvw.adoc#[Wicket viewer]) or a 500 status error code (if the
-xref:../ugvro/ugvro.adoc#[Restful Objects] viewer).
-
-If the exception thrown is because of an unexpected error (eg a `NullPointerException` in the domain app itself), then
-the error page will include a stack trace. If however you want to indicate that the exception is in some sense
-"expected", then throw a `RecoverableException` (or any subclass, eg `ApplicationException`); the stack trace will then
-be suppressed from the error page.
-
-Another way in which exceptions might be considered "expected" could be as the result of attempting to persist an
-object which then violates some type of database constraint. Even if the domain application checks beforehand, it
-could be that another user operating on the object at the same moment of time might result in the conflict.
-
-To handle this the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ExceptionRecognizer[`ExceptionRecognizer`] SPI can be used. The
-framework provides a number of implementations out-of-the-box; whenever an exception is thrown it is passed to each
-known recognizer implementation to see if it recognizes the exception and can return a user-meaningful error message.
-For example, `ExceptionRecognizerForSQLIntegrityConstraintViolationUniqueOrIndexException` checks if the
-exception inherits from `java.sql.SQLIntegrityConstraintViolationException`, and if so, constructs a suitable message.
-
http://git-wip-us.apache.org/repos/asf/isis/blob/074b9113/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_programming-model_finetuning.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_programming-model_finetuning.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_programming-model_finetuning.adoc
index 26eb886..cf77b50 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_programming-model_finetuning.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_programming-model_finetuning.adoc
@@ -58,7 +58,7 @@ To include/exclude more than one `FacetFactory`, specify as a comma-separated li
[TIP]
====
-This http://isis.markmail.org/thread/472c3mrvcgnripst[thread] from the users mailing list (in Apr 2014) shows a typical customization (to enable per-instance security) (though note that xref:../ugbtb/ugbtb.adoc#_ugbtb_other-techniques_multi-tenancy[Multi-Tenancy] is now a better solution to that particular use-case.
+This http://isis.markmail.org/thread/472c3mrvcgnripst[thread] from the users mailing list (in Apr 2014) shows a typical customization (to enable per-instance security) (though note that xref:../ugbtb/ugbtb.adoc#_ugbtb_hints-and-tips_multi-tenancy[Multi-Tenancy] is now a better solution to that particular use-case.
====
http://git-wip-us.apache.org/repos/asf/isis/blob/074b9113/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 5f29c15..5e9c576 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/ugbtb.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/ugbtb.adoc
@@ -46,7 +46,6 @@ The remaining guides are:
include::_ugbtb_i18n.adoc[leveloffset=+1]
include::_ugbtb_headless-access.adoc[leveloffset=+1]
include::_ugbtb_hints-and-tips.adoc[leveloffset=+1]
-include::_ugbtb_other-techniques.adoc[leveloffset=+1]
include::_ugbtb_programming-model.adoc[leveloffset=+1]
include::_ugbtb_deployment.adoc[leveloffset=+1]
include::_ugbtb_web-xml.adoc[leveloffset=+1]
[2/5] isis git commit: fixes up references to view models and mixins.
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_contributions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_contributions.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_contributions.adoc
index 107a550..a3126d0 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_contributions.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_contributions.adoc
@@ -42,7 +42,7 @@ public class OrderContributions {
<3> Only actions with a single argument can be contributed as associations
More information about contributions can be found xref:../ugfun/ugfun.adoc#_ugfun_how-tos_contributed-members[here]. More information
-about using contributions and mixins to keep your domain application decoupled can be found xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_contributions[here] and xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_mixins[here].
+about using contributions and mixins to keep your domain application decoupled can be found xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_types-of-domain-objects_mixins[here] and xref:../ugfun/ugfun.adoc#_ugfun_programming-model_domain-services_contributions[contributed services]).
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_dto.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_dto.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_dto.adoc
index ad5b8fd..809402b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_dto.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_dto.adoc
@@ -47,16 +47,16 @@ public class ToDoItemV1_1 implements Dto { // <5>
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]
+<1> package name encodes major version; see discussion on xref:../ugfun/ugfun.adoc#_ugfun_programming-model_view-models_dto_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]
+<5> class name encodes (major and) minor version; see discussion on xref:../ugfun/ugfun.adoc#_ugfun_programming-model_view-models_dto_versioning[versioning]
+<6> again, see discussion on xref:../ugfun/ugfun.adoc#_ugfun_programming-model_view-models_dto_versioning[versioning]
+<7> again, see discussion on xref:../ugfun/ugfun.adoc#_ugfun_programming-model_view-models_dto_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]
+<9> reference to a persistent entity; discussed xref:../ugfun/ugfun.adoc#_ugfun_programming-model_view-models_jaxb_referencing-domain-entities[here]
+<10> reference to a collection of persistent entities; again discussed xref:../ugfun/ugfun.adoc#_ugfun_programming-model_view-models_jaxb_referencing-domain-entities[here]
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_dto_versioning.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_dto_versioning.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_dto_versioning.adoc
index 2c61f4e..4d1f778 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_dto_versioning.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_view-models_dto_versioning.adoc
@@ -47,7 +47,7 @@ Although there is no requirement for the namespace URI to correspond to a physic
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:
+Since these DTO classes will all be in the same package (as per the advice above), the class should therefore include the minor version name:
[source,java]
----
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_db-schemas.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_db-schemas.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_db-schemas.adoc
new file mode 100644
index 0000000..795c4cf
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_db-schemas.adoc
@@ -0,0 +1,147 @@
+[[_ugodn_db-schemas]]
+= Database Schemas
+: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 the same way that Java packages act as a namespace for domain objects, it's good practice to map domain entities to their own (database) schemas.
+
+As of 1.9.0, all the link:http://www.isisaddons.org[Isis Addons] (non-ASF) modules do this.
+For example:
+
+
+[source,java]
+----
+@javax.jdo.annotations.PersistenceCapable( ...
+ schema = "isissecurity",
+ table = "ApplicationUser")
+public class ApplicationUser ... { ... }
+----
+
+results in a `CREATE TABLE` statement of:
+
+[source,sql]
+----
+CREATE TABLE isissecurity."ApplicationUser" (
+ ...
+)
+----
+
+
+while:
+
+[source,java]
+----
+@javax.jdo.annotations.PersistenceCapable( ...
+ schema = "isisaudit",
+ table="AuditEntry")
+public class AuditEntry ... { ... }
+----
+
+similarly results in:
+
+[source,sql]
+----
+CREATE TABLE isisaudit."AuditEntry" (
+ ...
+)
+----
+
+
+[TIP]
+====
+If for some reason you don't want to use schemas (though we strongly recommend that you do), then note that you can override the `@PersistenceCapable` annotation by providing XML metadata (the `mappings.jdo` file).
+See the section on xref:../ugodn/ugodn.adoc#_ugodn_configuring[configuring DataNucleus Overriding Annotations] for more details.
+====
+
+
+
+
+== Listener to create schema
+
+JDO/DataNucleus does not automatically create these schema objects, but it _does_ provide a listener callback API on the initialization of each class into the JDO metamodel.
+
+[TIP]
+====
+Actually, the above statement isn't quite true.
+In DN 3.2.x (as used by Apache Isis up to v1.8.0) there was no support for schemas.
+As of Apache Isis 1.9.0 and DN 4.0 there is now support.
+But we implemented this feature initially against DN 3.2.x, and it still works, so for now we've decided to leave it in.
+====
+
+Therefore Apache Isis attaches a listener, `CreateSchemaObjectFromClassMetadata`, that checks for the schema's existence, and creates the schema if required.
+
+The guts of its implementation is:
+
+[source,java]
+----
+public class CreateSchemaObjectFromClassMetadata
+ implements MetaDataListener,
+ DataNucleusPropertiesAware {
+ @Override
+ public void loaded(final AbstractClassMetaData cmd) { ... }
+
+ protected String buildSqlToCheck(final AbstractClassMetaData cmd) {
+ final String schemaName = schemaNameFor(cmd);
+ return String.format(
+ "SELECT count(*) FROM INFORMATION_SCHEMA.SCHEMATA where SCHEMA_NAME = '%s'", schemaName);
+ }
+ protected String buildSqlToExec(final AbstractClassMetaData cmd) {
+ final String schemaName = schemaNameFor(cmd);
+ return String.format("CREATE SCHEMA \"%s\"", schemaName);
+ }
+}
+----
+
+where `MetaDataListener` is the DataNucleus listener API:
+
+[source,java]
+----
+public interface MetaDataListener {
+ void loaded(AbstractClassMetaData cmd);
+}
+----
+
+Although not formal API, the default `CreateSchemaObjectFromClassMetadata` has been designed to be easily overrideable if you need to tweak it to support other RDBMS'.
+Any implementation must implement `org.datanucleus.metadata.MetaDataListener`:
+
+The implementation provided has has been tested for HSQLDB, PostgreSQL and MS SQL Server, and is used automatically unless an alternative implementation is specified (as described in the section below).
+
+
+
+
+
+== Alternative implementation
+
+An alternative implementation can be registered and used through the following configuration property:
+
+[source,ini]
+----
+isis.persistor.datanucleus.classMetadataLoadedListener=\
+ org.apache.isis.objectstore.jdo.datanucleus.CreateSchemaObjectFromClassMetadata
+----
+
+
+Because this pertains to the JDO Objectstore we suggest you put this configuration property in `WEB-INF/persistor_datanucleus.properties`; but putting it in `isis.properties` will also work.
+
+Any implementation must implement `org.datanucleus.metadata.MetaDataListener`.
+In many cases simply subclassing from `CreateSchemaObjectFromClassMetadata` and overriding `buildSqlToCheck(...)` and `buildSqlToExec(...)` should suffice.
+
+If you _do_ need more control, your implementation can also optionally implement `org.apache.isis.objectstore.jdo.datanucleus.DataNucleusPropertiesAware`:
+
+[source,java]
+----
+public interface DataNucleusPropertiesAware {
+ public void setDataNucleusProperties(final Map<String, String> properties);
+}
+----
+
+This provides access to the properties passed through to JDO/DataNucleus.
+
+
+[IMPORTANT]
+====
+If you do extend Apache Isis' `CreateSchemaObjectFromClassMetadata` class for some other database, please https://issues.apache.org/jira/browse/ISIS[contribute back] your improvements.
+====
+
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_overriding-jdo-annotations.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_overriding-jdo-annotations.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_overriding-jdo-annotations.adoc
index 015e8ca..3430709 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_overriding-jdo-annotations.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_overriding-jdo-annotations.adoc
@@ -56,7 +56,7 @@ For example, in writing up the above example we found that writing `schema="
* Forcing the schema to "PUBLIC" (as in the above example) works, but it isn't ideal because the name "PUBLIC" is not vendor-neutral (it works for HSQLDB, but MS SQL Server uses "dbo" as its default).
-* As of 1.9.0 Apache Isis will automatically (attempt) to create the owning schema for a given table if it does not exist. This behaviour can be customized, as described in the section on xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_db-schemas[using modules].
+* As of 1.9.0 Apache Isis will automatically (attempt) to create the owning schema for a given table if it does not exist. This behaviour can be customized, as described in the section on xref:../ugbtb/ugbtb.adoc#_ugodn_db-schemas[using modules].
* You may need to override the entire class metadata rather than individual elements; the mixin mentioned above can help here.
====
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/ugodn/ugodn.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/ugodn.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/ugodn.adoc
index 03887c2..85e3071 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugodn/ugodn.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugodn/ugodn.adoc
@@ -59,5 +59,6 @@ The remaining guides are:
include::_ugodn_configuring.adoc[leveloffset=+1]
include::_ugodn_jdo-mappings.adoc[leveloffset=+1]
+include::_ugodn_db-schemas.adoc[leveloffset=+1]
include::_ugodn_hints-and-tips.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_application-menu.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_application-menu.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_application-menu.adoc
index 3fb3ba5..e377934 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_application-menu.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_application-menu.adoc
@@ -167,5 +167,5 @@ Meanwhile the http://github.com/isisaddons/isis-module-devutils[devutils] module
so forth - on a "Prototyping" top-level menu, on the SECONDARY menu bar.
Currently there is no facility to alter the placement of these services. However, their UI can be suppressed
-using security or using a xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_vetoing-visibility[vetoing subscriber].
+using security or using a xref:../ugbtb/ugbtb.adoc#_ugbtb_hints-and-tips_vetoing-visibility[vetoing subscriber].
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/pages/powered-by/_powered-by_contactapp.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/pages/powered-by/_powered-by_contactapp.adoc b/adocs/documentation/src/main/asciidoc/pages/powered-by/_powered-by_contactapp.adoc
index a7c76dc..b1cc461 100644
--- a/adocs/documentation/src/main/asciidoc/pages/powered-by/_powered-by_contactapp.adoc
+++ b/adocs/documentation/src/main/asciidoc/pages/powered-by/_powered-by_contactapp.adoc
@@ -34,7 +34,7 @@ image:http://i.imgur.com/qhXhKiu.png[width="32%"]
As our first Apache Isis app making use of mobile technologies it opens the doors for more to follow.
Ionic has proven easy to learn and build apps with, and has a helpful community. Meanwhile we've used
-Apache Isis' support for link://http://isis.apache.org/guides/ugbtb.html#_ugbtb_view-models_jaxb[JAXB view models]
+Apache Isis' support for xref:../../guides/ugfun/ugfun.adoc#_ugfun_programming-model_view-models_jaxb[JAXB view models]
and in particular the http://isis.apache.org/guides/ugvro.html#__ugvro_simplified-representations_apache-isis-profile[simplified REST representations] introduced in v1.12.0. The result is code that is easy to follow and enhance.
We expect that the scope of _Contact App_ will expand and new features added, these will (almost certainly) remain open source.
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/pages/powered-by/_powered-by_gesconsultor-grc.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/pages/powered-by/_powered-by_gesconsultor-grc.adoc b/adocs/documentation/src/main/asciidoc/pages/powered-by/_powered-by_gesconsultor-grc.adoc
index 32f40c8..3ff5647 100644
--- a/adocs/documentation/src/main/asciidoc/pages/powered-by/_powered-by_gesconsultor-grc.adoc
+++ b/adocs/documentation/src/main/asciidoc/pages/powered-by/_powered-by_gesconsultor-grc.adoc
@@ -85,7 +85,7 @@ automatically generated from the underlying domain entities; the GRC viewer is a
xref:../../guides/ugvw/ugvw.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:../../guides/ugbtb/ugbtb.adoc#_ugbtb_decoupling_event-bus[domain events]
+At the Domain level, we also extensively use the xref:../../guides/ugfun/ugfun.adoc#_ugfun_building-blocks_events_domain-events[domain events]
functionality available in Apache Isis, along with many of the (non-ASF) link:http://isisaddons.org[Isis Addons] (such
as http://github.com/isisaddons/isis-module-audit[audit], http://github.com/isisaddons/isis-module-security[security]
and the http://github.com/isisaddons/isis-module-excel[excel] modules).
http://git-wip-us.apache.org/repos/asf/isis/blob/01fb90ba/adocs/documentation/src/main/asciidoc/pages/screencasts/screencasts.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/pages/screencasts/screencasts.adoc b/adocs/documentation/src/main/asciidoc/pages/screencasts/screencasts.adoc
index b8cb5d5..4dacc27 100644
--- a/adocs/documentation/src/main/asciidoc/pages/screencasts/screencasts.adoc
+++ b/adocs/documentation/src/main/asciidoc/pages/screencasts/screencasts.adoc
@@ -60,7 +60,7 @@ Importing the generated app into an xref:guides/dg.adoc#_dg_ide[IDE] +
|link:https://www.youtube.com/watch?v=xVTjtiJM8XM[003^] +
-Walking through the main classes that make up the SimpleApp: `SimpleObject` persistent entity, `HomePageViewModel` xref:guides/ugbtb.adoc#_ugbtb_view-models[view model] and `SimpleObjects` domain service (repository).
+Walking through the main classes that make up the SimpleApp: `SimpleObject` persistent entity, `HomePageViewModel` xref:guides/ugfun/ugfun/_ugfun_building-blocks_types-of-domain-objects_view-models[view model] and `SimpleObjects` domain service (repository).
||||x|||||||
@@ -241,19 +241,19 @@ include::_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:guides/ugbtb.adoc#_ugbtb_decoupling_mixins[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:guides/ugfun/ugfun.adoc#_ugfun_building-blocks_types-of-domain-objects_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:guides/ugbtb.adoc#_ugbtb_decoupling_mixins[mixin].
+Shows how to refactor a domain object to move (derived) collections out of the domain object and reimplement as a xref:guides/ugfun/ugfun.adoc#_ugfun_building-blocks_types-of-domain-objects_mixins[mixin].
||||||x|||||
|link:https://www.youtube.com/watch?v=-AQJb9GtIqI[024^] +
-Using a domain event xref:guides/rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[subscriber] to xref:guides/ugbtb.adoc#_ugbtb_decoupling_event-bus[decouple] and abstract business rules ( xref:guides/rgcms.adoc#_rgcms_methods_prefixes_validate[validation]).
+Using a domain event xref:guides/rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[subscriber] to xref:guides/ugfun/ugfun.adoc#_ugfun_building-blocks_events_domain-events[decouple] and abstract business rules (xref:guides/rgcms.adoc#_rgcms_methods_prefixes_validate[validation]).
||||||x|||||
@@ -517,22 +517,22 @@ include::_screencasts-playlists.adoc[]
|link:https://www.youtube.com/watch?v=puG-pzxRSd0[052^] +
-How to write a xref:guides/ugbtb.adoc#_ugbtb_view-models_jaxb[(JAXB) view model], holding references to two domain objects.
+How to write a xref:guides/ugfun/ugfun.adoc#_ugfun_programming-model_view-models_jaxb[(JAXB) view model], holding references to two domain objects.
|x||||||||x||
|link:https://www.youtube.com/watch?v=tdBkmA2CCZY[053^] +
-Updating the title, icon and layout of a xref:guides/ugbtb.adoc#_ugbtb_view-models_jaxb[(JAXB) view model].
+Updating the title, icon and layout of a xref:guides/ugfun/ugfun.adoc#_ugfun_programming-model_view-models_jaxb[(JAXB) view model].
||||x|||||||
|link:https://www.youtube.com/watch?v=TKF0FB_od00[054^] +
-How to expose information from underlying domain entities referenced by a xref:guides/ugbtb.adoc#_ugbtb_view-models_jaxb[(JAXB) view model] using derived properties
+How to expose information from underlying domain entities referenced by a xref:guides/ugfun/ugfun.adoc#_ugfun_programming-model_view-models_jaxb[(JAXB) view model] using derived properties
||||||||||x|
|link:https://www.youtube.com/watch?v=TMMeVhRNi8A[055^] +
-Adding an action to a xref:guides/ugbtb.adoc#_ugbtb_view-models_jaxb[(JAXB) view model], and adjusting the layout using custom CSS.
+Adding an action to a xref:guides/ugfun/ugfun.adoc#_ugfun_programming-model_view-models_jaxb[(JAXB) view model], and adjusting the layout using custom CSS.
||||x|||||||
[5/5] isis git commit: fixes FIXMEs in ugodn, rearranging some content
Posted by da...@apache.org.
fixes FIXMEs in ugodn, rearranging some content
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/bbf2414a
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/bbf2414a
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/bbf2414a
Branch: refs/heads/wip
Commit: bbf2414ab3d6bd333e1255a0e3d238c10e759af9
Parents: 074b911
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Thu Apr 20 07:46:30 2017 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Thu Apr 20 07:46:30 2017 +0100
----------------------------------------------------------------------
.../src/main/asciidoc/guides/dg/_dg_ide.adoc | 3 +-
.../asciidoc/guides/dg/_dg_ide_eclipse.adoc | 2 +-
.../_rgfis_spi_ContentNegotiationService.adoc | 2 +-
.../guides/ugodn/_ugodn_configuring.adoc | 3 +-
.../_ugodn_configuring_persistence-xml.adoc | 28 ++++++++++++-
.../guides/ugodn/_ugodn_hints-and-tips.adoc | 2 -
...ndling-mandatory-properties-in-subtypes.adoc | 44 --------------------
..._ugodn_hints-and-tips_mapping-to-a-view.adoc | 9 ----
.../guides/ugodn/_ugodn_jdo-mappings.adoc | 2 +
...ppings_mandatory-properties-in-subtypes.adoc | 44 ++++++++++++++++++++
.../_ugodn_jdo-mappings_mapping-to-a-view.adoc | 18 ++++++++
11 files changed, 97 insertions(+), 60 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/bbf2414a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide.adoc
index db76f89..ca81d39 100644
--- a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide.adoc
@@ -7,7 +7,8 @@
-The vast majority of Java developers use an IDE to assist with developing their code, and we highly recommend that you do like wise as you develop your Apache Isis applications using an IDE. Apache Isis is built with Maven, and all modern IDEs can import Maven projects.
+The vast majority of Java developers use an IDE to assist with developing their code, and we highly recommend that you do likewise as you develop your Apache Isis applications using an IDE.
+Apache Isis is built with Maven, and all modern IDEs can import Maven projects.
This chapter shows how to setup and use two of the most popular IDEs, IntelliJ IDEA and Eclipse.
http://git-wip-us.apache.org/repos/asf/isis/blob/bbf2414a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_eclipse.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_eclipse.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_eclipse.adoc
index a3f0dab..43ff34f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_eclipse.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_eclipse.adoc
@@ -90,7 +90,7 @@ When the enhancer runs, it will print out to the console:
image::{_imagesdir}eclipse/eclipse-120-console.png[width="500px",link="{_imagesdir}/appendices/dev-env/eclipse/eclipse-120-console.png"]
-
+[[__dg_ide_eclipse_workaround-for-path-limits]]
=== Workaround for path limits (the DN plugin to use the persistence.xml)
If running on Windows then the DataNucleus plugin is very likely to hit the Windows path limit.
http://git-wip-us.apache.org/repos/asf/isis/blob/bbf2414a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_ContentNegotiationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_ContentNegotiationService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_ContentNegotiationService.adoc
index 0342d47..b4d62d7 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_ContentNegotiationService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_ContentNegotiationService.adoc
@@ -18,7 +18,7 @@ Instead you need to create some sort of stable facade over your domain entities,
+
If the underlying entities change, then care must be taken to ensure that structure of the view model nevertheless is unchanged.
-* a second option is to solve the problem at the persistence layer, but defining a (SQL) view in the database and then xref:../ugodn/ugodn.adoc#_ugodn_hints-and-tips_mapping-to-a-view[mapping this] to a (read-only) entity. Again this is surfaced by the RO viewer. +
+* a second option is to solve the problem at the persistence layer, but defining a (SQL) view in the database and then xref:../ugodn/ugodn.adoc#_ugodn_jdo-mappings_mapping-to-a-view[mapping this] to a (read-only) entity. Again this is surfaced by the RO viewer. +
+
If the underlying tables change (as the result of a change in their corresponding domain entities) then once more the view must be refactored so that it still presents the same structure.
http://git-wip-us.apache.org/repos/asf/isis/blob/bbf2414a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring.adoc
index 1734c98..5614dbe 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring.adoc
@@ -6,7 +6,8 @@
Apache Isis programmatically configures DataNucleus; any Apache Isis properties with the prefix `isis.persistor.datanucleus.impl` are passed through directly to the JDO/DataNucleus objectstore (with the prefix stripped off, of course).
-DataNucleus will for itself also and read the `META-INF/persistence.xml`; at a minimum this defines the name of the "persistence unit". n theory it could also hold mappings, though in Apache Isis we tend to use annotations instead.
+DataNucleus will for itself also and read the `META-INF/persistence.xml`; at a minimum this defines the name of the "persistence unit".
+In theory it could also hold mappings, though in Apache Isis we tend to use annotations instead.
Furthermore, DataNucleus will search for various other XML mapping files, eg `mappings.jdo`. A full list can be found http://www.datanucleus.org/products/datanucleus/jdo/metadata.html[here]. The metadata in these XML can be used to override the annotations of annotated entities; see xref:../ugbtb/ugbtb.adoc#_ugbtb_other-techniques_overriding-jdo-annotations[Overriding JDO Annotatons] for further discussion.
http://git-wip-us.apache.org/repos/asf/isis/blob/bbf2414a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_persistence-xml.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_persistence-xml.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_persistence-xml.adoc
index db4a42e..cbfbad4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_persistence-xml.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_configuring_persistence-xml.adoc
@@ -5,6 +5,32 @@
:_imagesdir: images/
-NOTE: FIXME
+DataNucleus will for itself also and read the `META-INF/persistence.xml`.
+In theory it can hold mappings and even connection strings.
+However, with Apache Isis we tend to use annotations instead and externalize connection strings. so its definition is extremely simply, specifying just the name of the "persistence unit".
+Here's the one provided by the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]:
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8" ?>
+<persistence xmlns="http://java.sun.com/xml/ns/persistence"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd" version="1.0">
+
+ <persistence-unit name="simple">
+ </persistence-unit>
+</persistence>
+----
+
+Normally all one needs to do is to change the `persistence-unit` name.
+
+[TIP]
+====
+If you use Eclipse IDE on Windows then xref:../dg/dg.adoc#__dg_ide_eclipse_workaround-for-path-limits[note the importance] of the `persistence.xml` file to make DataNucleus enhancer work correctly.
+====
+
+
+
+See link:http://www.datanucleus.org/products/datanucleus/jdo/persistence.html#persistenceunit[DataNucleus' documentation] on `persistence.xml` to learn more.
http://git-wip-us.apache.org/repos/asf/isis/blob/bbf2414a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips.adoc
index 1efd665..7f02c3b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips.adoc
@@ -23,8 +23,6 @@ See also hints-n-tips chapters in the:
include::_ugodn_hints-and-tips_overriding-jdo-annotations.adoc[leveloffset=+1]
-include::_ugodn_hints-and-tips_handling-mandatory-properties-in-subtypes.adoc[leveloffset=+1]
-include::_ugodn_hints-and-tips_mapping-to-a-view.adoc[leveloffset=+1]
include::_ugodn_hints-and-tips_subtype-entity-not-fully-populated.adoc[leveloffset=+1]
include::_ugodn_hints-and-tips_java8.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/bbf2414a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_handling-mandatory-properties-in-subtypes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_handling-mandatory-properties-in-subtypes.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_handling-mandatory-properties-in-subtypes.adoc
deleted file mode 100644
index eff87e0..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_handling-mandatory-properties-in-subtypes.adoc
+++ /dev/null
@@ -1,44 +0,0 @@
-[[_ugodn_hints-and-tips_handling-mandatory-properties-in-subtypes]]
-= Handling Mandatory Properties in Subtypes
-: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/
-
-
-
-If you have a hierarchy of classes then you need to decide which inheritance strategy to use.
-
-* "table per hierarchy", or "rollup" (`InheritanceStrategy.SUPERCLASS_TABLE`) +
-+
-whereby a single table corresponds to the superclass, and also holds the properties of the subtype (or subtypes) being rolled up
-
-* "table per class" (`InheritanceStrategy.NEW_TABLE`) +
-+
-whereby there is a table for both superclass and subclass, in 1:1 correspondence
-
-* "rolldown" (`InheritanceStrategy.SUBCLASS_TABLE`) +
-+
-whereby a single table holds the properties of the subtype, and also holds the properties of its supertype
-
-In the first "rollup" case, we can have a situation where - logically speaking - the property is mandatory in the subtype - but it must be mapped as nullable in the database because it is n/a for any other subtypes that are rolled up.
-
-In this situation we must tell JDO that the column is optional, but to Apache Isis we want to enforce it being mandatory. This can be done using the `@Property(optionality=Optionality.MANDATORY)` annotation.
-
-For example:
-
-[source,java]
-----
-@javax.jdo.annotations.Inheritance(strategy = InheritanceStrategy.SUPER_TABLE)
-public class SomeSubtype extends SomeSuperType {
- @javax.jdo.annotations.Column(allowsNull="true")
- @Property(optionality=Optionality.MANDATORY)
- @lombok.Getter @lombok.Setter
- private LocalDate date;
-}
-----
-
-[TIP]
-====
-The `@Property(optionality=...)` annotation is equivalent to the older but still supported `@Optional` annotation and `@Mandatory` annotations.
-====
-
http://git-wip-us.apache.org/repos/asf/isis/blob/bbf2414a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_mapping-to-a-view.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_mapping-to-a-view.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_mapping-to-a-view.adoc
deleted file mode 100644
index a50c2a0..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_hints-and-tips_mapping-to-a-view.adoc
+++ /dev/null
@@ -1,9 +0,0 @@
-[[_ugodn_hints-and-tips_mapping-to-a-view]]
-= Mapping to a View
-: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 - as per Estatio's Invoice stuff
-
http://git-wip-us.apache.org/repos/asf/isis/blob/bbf2414a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_jdo-mappings.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_jdo-mappings.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_jdo-mappings.adoc
index 7a7de94..18a8b08 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_jdo-mappings.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_jdo-mappings.adoc
@@ -8,3 +8,5 @@
include::_ugodn_jdo-mappings_1-to-m-bidirectional-relationships.adoc[leveloffset=+1]
+include::_ugodn_jdo-mappings_mandatory-properties-in-subtypes.adoc[leveloffset=+1]
+include::_ugodn_jdo-mappings_mapping-to-a-view.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/bbf2414a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_jdo-mappings_mandatory-properties-in-subtypes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_jdo-mappings_mandatory-properties-in-subtypes.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_jdo-mappings_mandatory-properties-in-subtypes.adoc
new file mode 100644
index 0000000..1720d5f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_jdo-mappings_mandatory-properties-in-subtypes.adoc
@@ -0,0 +1,44 @@
+[[_ugodn_jdo-mappings_mandatory-properties-in-subtypes]]
+= Mandatory Properties in Subtypes
+: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/
+
+
+
+If you have a hierarchy of classes then you need to decide which inheritance strategy to use.
+
+* "table per hierarchy", or "rollup" (`InheritanceStrategy.SUPERCLASS_TABLE`) +
++
+whereby a single table corresponds to the superclass, and also holds the properties of the subtype (or subtypes) being rolled up
+
+* "table per class" (`InheritanceStrategy.NEW_TABLE`) +
++
+whereby there is a table for both superclass and subclass, in 1:1 correspondence
+
+* "rolldown" (`InheritanceStrategy.SUBCLASS_TABLE`) +
++
+whereby a single table holds the properties of the subtype, and also holds the properties of its supertype
+
+In the first "rollup" case, we can have a situation where - logically speaking - the property is mandatory in the subtype - but it must be mapped as nullable in the database because it is n/a for any other subtypes that are rolled up.
+
+In this situation we must tell JDO that the column is optional, but to Apache Isis we want to enforce it being mandatory. This can be done using the `@Property(optionality=Optionality.MANDATORY)` annotation.
+
+For example:
+
+[source,java]
+----
+@javax.jdo.annotations.Inheritance(strategy = InheritanceStrategy.SUPER_TABLE)
+public class SomeSubtype extends SomeSuperType {
+ @javax.jdo.annotations.Column(allowsNull="true")
+ @Property(optionality=Optionality.MANDATORY)
+ @lombok.Getter @lombok.Setter
+ private LocalDate date;
+}
+----
+
+[TIP]
+====
+The `@Property(optionality=...)` annotation is equivalent to the older but still supported `@Optional` annotation and `@Mandatory` annotations.
+====
+
http://git-wip-us.apache.org/repos/asf/isis/blob/bbf2414a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_jdo-mappings_mapping-to-a-view.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_jdo-mappings_mapping-to-a-view.adoc b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_jdo-mappings_mapping-to-a-view.adoc
new file mode 100644
index 0000000..e9311f4
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugodn/_ugodn_jdo-mappings_mapping-to-a-view.adoc
@@ -0,0 +1,18 @@
+[[_ugodn_jdo-mappings_mapping-to-a-view]]
+= Mapping to a View
+: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/
+
+
+JDO/DataNucleus supports the ability to map the entity that is mapped to a view rather than a database table.
+Moreover, DataNucleus itself can create/maintain this view.
+
+One use case for this is to support use cases which act upon aggregate information.
+An link:https://github.com/estatio/estatio/blob/b77d0b03ec86463227ba90f8341299066ddba69f/estatioapp/module/lease/dom/src/main/java/org/estatio/dom/lease/invoicing/viewmodel/InvoiceSummaryForPropertyDueDateStatus.java#L57[example] is in the (non-ASF) http://github.com/estatio/estatio[Estatio] application, which uses a view to define an "invoice run": a representatoin of all pending invoices to be sent out for a particular shopping centre.
+(Note that example also shows the entity as being "non-durable", but if the view is read/write then -- I think -- that this isn't necessary required).
+
+
+For more on this topic, see the link:http://www.datanucleus.org/products/datanucleus/jdo/mapping.html#schema_rdbms_views[DataNucleus documentation].
+
+