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 2015/11/19 19:13:00 UTC
[2/2] isis git commit: ISIS-915, ISIS-1250, ISIS-1251, ISIS-1252,
ISIS-1254, ISIS-1255: documentation and minor code updates.
ISIS-915, ISIS-1250, ISIS-1251, ISIS-1252, ISIS-1254, ISIS-1255: documentation and minor code updates.
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/4b891285
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/4b891285
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/4b891285
Branch: refs/heads/ISIS-1250
Commit: 4b891285bc69f1e295c268175b32fb4b7bb3adf6
Parents: 48102a0
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Thu Nov 19 18:12:11 2015 +0000
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Thu Nov 19 18:12:11 2015 +0000
----------------------------------------------------------------------
adocs/documentation/Gemfile.lock | 3 +
adocs/documentation/monitor.rb | 2 +-
adocs/documentation/pom.xml | 2 +-
.../main/asciidoc/guides/_cg_ide-templates.adoc | 8 +-
.../main/asciidoc/guides/_rg_annotations.adoc | 2 +-
.../guides/_rg_annotations_aaa_jee.adoc | 4 +-
.../guides/_rg_annotations_manpage-Action.adoc | 4 +-
..._annotations_manpage-Action_domainEvent.adoc | 41 ++-
...otations_manpage-Collection_domainEvent.adoc | 36 +-
..._annotations_manpage-DomainObjectLayout.adoc | 19 +-
...page-DomainObjectLayout_cssClassUiEvent.adoc | 125 +++++++
..._manpage-DomainObjectLayout_iconUiEvent.adoc | 120 ++++++
...manpage-DomainObjectLayout_titleUiEvent.adoc | 119 ++++++
...nnotations_manpage-Property_domainEvent.adoc | 42 ++-
..._annotations_manpage-XmlJavaTypeAdapter.adoc | 27 ++
.../_rg_annotations_manpage-XmlRootElement.adoc | 34 +-
...annotations_manpage-XmlValueTypeAdapter.adoc | 25 --
.../src/main/asciidoc/guides/_rg_classes.adoc | 1 +
.../guides/_rg_classes_roles_manpage-Dto.adoc | 17 +-
.../guides/_rg_runtime_configuring-core.adoc | 55 ++-
.../_rg_runtime_specifying-components.adoc | 4 +-
.../main/asciidoc/guides/_rg_schema-common.adoc | 11 +-
.../main/asciidoc/guides/_rg_services-api.adoc | 1 +
.../_rg_services-api_manpage-JaxbService.adoc | 2 +-
...services-spi_manpage-UrlEncodingService.adoc | 30 +-
.../guides/_ug_how-tos_class-structure.adoc | 2 +-
.../guides/_ug_more-advanced_view-models.adoc | 174 +++++----
.../templates/asciidoc-templates-idea.xml | 365 -------------------
.../templates/isis-asciidoc-templates-idea.xml | 365 +++++++++++++++++++
adocs/template/document.html.erb | 2 +-
.../services/eventbus/ActionDomainEvent.java | 2 +-
.../eventbus/CollectionDomainEvent.java | 2 +-
.../services/eventbus/CssClassUiEvent.java | 2 +-
.../applib/services/eventbus/IconUiEvent.java | 2 +-
.../services/eventbus/PropertyDomainEvent.java | 2 +-
.../applib/services/eventbus/TitleUiEvent.java | 18 +-
.../action/ActionAnnotationFacetFactory.java | 2 +-
.../CollectionAnnotationFacetFactory.java | 2 +-
...ectLayoutAnnotationUsingCssClassUiEvent.java | 2 +-
...nObjectLayoutAnnotationUsingIconUiEvent.java | 2 +-
...ObjectLayoutAnnotationUsingTitleUiEvent.java | 4 +-
.../PropertyAnnotationFacetFactory.java | 2 +-
.../src/main/webapp/WEB-INF/isis.properties | 10 +
43 files changed, 1136 insertions(+), 558 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/4b891285/adocs/documentation/Gemfile.lock
----------------------------------------------------------------------
diff --git a/adocs/documentation/Gemfile.lock b/adocs/documentation/Gemfile.lock
index 0d4f467..9b483db 100644
--- a/adocs/documentation/Gemfile.lock
+++ b/adocs/documentation/Gemfile.lock
@@ -45,3 +45,6 @@ DEPENDENCIES
tilt
wdm (>= 0.1.0)
webrick
+
+BUNDLED WITH
+ 1.10.6
http://git-wip-us.apache.org/repos/asf/isis/blob/4b891285/adocs/documentation/monitor.rb
----------------------------------------------------------------------
diff --git a/adocs/documentation/monitor.rb b/adocs/documentation/monitor.rb
index f1a9f6b..ddda73e 100644
--- a/adocs/documentation/monitor.rb
+++ b/adocs/documentation/monitor.rb
@@ -85,7 +85,7 @@ def process(file,srcBasePath,targetBasePath,templateDir,i,lastTimeGenerated,prim
timeUntilNext > 0 then
puts "skipping before regenerating (3 seconds not yet elapsed)"
else
- cmd = "asciidoctor #{regenerate} --require asciidoctor-diagram --backend html --eruby erb --template-dir '#{templateDir}' --destination-dir='#{targetRelDir}' -a imagesdir='' -a toc=right -a icons=font -a source-highlighter=rouge"
+ cmd = "asciidoctor #{regenerate} --require asciidoctor-diagram --backend html --eruby erb --template-dir '#{templateDir}' --destination-dir='#{targetRelDir}' -a imagesdir='' -a toc=right -a icons=font -a source-highlighter=coderay"
unless priming then
puts ""
http://git-wip-us.apache.org/repos/asf/isis/blob/4b891285/adocs/documentation/pom.xml
----------------------------------------------------------------------
diff --git a/adocs/documentation/pom.xml b/adocs/documentation/pom.xml
index 5c83079..6a86dce 100644
--- a/adocs/documentation/pom.xml
+++ b/adocs/documentation/pom.xml
@@ -116,7 +116,7 @@
</requires>
-->
- <sourceHighlighter>rouge</sourceHighlighter>
+ <sourceHighlighter>coderay</sourceHighlighter>
<backend>html5</backend>
<templateDir>../template</templateDir>
<eruby>erb</eruby>
http://git-wip-us.apache.org/repos/asf/isis/blob/4b891285/adocs/documentation/src/main/asciidoc/guides/_cg_ide-templates.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_cg_ide-templates.adoc b/adocs/documentation/src/main/asciidoc/guides/_cg_ide-templates.adoc
index afdf0dd..8cd0784 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_cg_ide-templates.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_cg_ide-templates.adoc
@@ -7,7 +7,7 @@
-We provide IDE templates (for IntelliJ and Eclipse) for writing Apache Isis domain objects, and also for unit tests (JUnit and JMock). We also provide them for IntelliJ for writing Asciidoc documentation (see also the xref:cg.adoc#_cg__cg_asciidoc-templates[appendix]).
+We provide IDE templates (for IntelliJ and Eclipse) for writing Apache Isis domain objects, and also for unit tests (JUnit and JMock). We also provide them for IntelliJ for writing Asciidoc documentation (see also the xref:cg.adoc#_cg_asciidoc-templates[appendix]).
== Download
@@ -42,7 +42,7 @@ The following table lists the templates available to download:
|Asciidoc
|ad
-|link:../resources/templates/asciidoc-templates-idea.xml[Download]
+|link:../resources/templates/isis-asciidoc-templates-idea.xml[Download]
|(none )
|===
@@ -56,13 +56,13 @@ The most commonly used Apache Isis domain objects templates are also listed on t
=== IntelliJ
-To install in IntelliJ (Community edition 14), copy to the relevant `config/templates` directory, eg:
+To install in IntelliJ (Community edition 15), copy to the relevant `config/templates` directory, eg:
* Windows `<User home>\.IdeaIC14\config\templates`
* Linux `~/.IdeaIC14/config/templates`
* Mac OS `~/Library/Preferences/IdeaIC14/templates`
-If using the Ultimate edition, the directory is `.IntelliJIdea14` rather than `IdeaIC14`.
+If using the Ultimate edition, the directory is `.IntelliJIdea15` rather than `IdeaIC15`.
=== Eclipse
http://git-wip-us.apache.org/repos/asf/isis/blob/4b891285/adocs/documentation/src/main/asciidoc/guides/_rg_annotations.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations.adoc
index f25d39d..11f2daa 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations.adoc
@@ -57,8 +57,8 @@ include::_rg_annotations_manpage-RequestScoped.adoc[leveloffset=+1]
include::_rg_annotations_manpage-Title.adoc[leveloffset=+1]
include::_rg_annotations_manpage-ViewModel.adoc[leveloffset=+1]
include::_rg_annotations_manpage-ViewModelLayout.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-XmlJavaTypeAdapter.adoc[leveloffset=+1]
include::_rg_annotations_manpage-XmlRootElement.adoc[leveloffset=+1]
-include::_rg_annotations_manpage-XmlValueTypeAdapter.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/4b891285/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa_jee.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa_jee.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa_jee.adoc
index ade88cf..d74b07f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa_jee.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa_jee.adoc
@@ -59,9 +59,9 @@ The table below lists the JEE annotations currently recognized. Expect to see m
|Application
|
-|xref:rg.adoc#_rg_annotations_manpage-XmlValueTypeAdapter[`javax.xml.bind` +
+|xref:rg.adoc#_rg_annotations_manpage-XmlJavaTypeAdapter[`javax.xml.bind` +
`.annotation` +
-`XmlValueTypeAdapter`]
+`XmlJavaTypeAdapter`]
|JAXB annotation defining how to serialize an entity. Used in conjunction with the (framework provided) `PersistentEntityAdapter` class to serialize persistent entities into a canonical OID (equivalent to the `Bookmark` provided by the xref:rg.adoc#_rg_services-api_manpage-BookmarkService[`BookmarkService`]).
|Domain
|
http://git-wip-us.apache.org/repos/asf/isis/blob/4b891285/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action.adoc
index 9c68b4e..2e31de6 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action.adoc
@@ -40,7 +40,9 @@ The table below summarizes the annotation's attributes.
|xref:rg.adoc#_rg_annotations_manpage-Action_domainEvent[`domainEvent()`]
|subtype of `ActionDomainEvent` +
(`ActionDomainEvent.Default`)
-|the event type to be posted to the xref:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`] to broadcast the action's business rule checking (hide, disable, validate) and its invocation (pre-execute and post-execution).
+|the event type to be posted to the xref:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`] to
+broadcast the action's business rule checking (hide, disable, validate) and its invocation (pre-execute and
+post-execute).
|xref:rg.adoc#_rg_annotations_manpage-Action_hidden[`hidden()`]
http://git-wip-us.apache.org/repos/asf/isis/blob/4b891285/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_domainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_domainEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_domainEvent.adoc
index 8bce8b1..1f7f5a7 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_domainEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Action_domainEvent.adoc
@@ -26,7 +26,11 @@ public class ToDoItem {
}
----
-The purpose of the `domainEvent()` attribute is to allows a custom subclass to be emitted instead. This attribute is also supported for xref:rg.adoc#_rg_annotations_manpage-Collection_domainEvent[collections] and xref:rg.adoc#_rg_annotations_manpage-Property_domainEvent[properties].
+
+The `domainEvent()` attribute allows a custom subclass to be emitted allowing more precise subscriptions (to those
+subclasses) to be defined instead. This attribute is also supported for
+xref:rg.adoc#_rg_annotations_manpage-Collection_domainEvent[collections] and
+xref:rg.adoc#_rg_annotations_manpage-Property_domainEvent[properties].
For example:
@@ -54,9 +58,6 @@ rather than through the constructor. This substantially reduces the boilerplate
-
-
-
== Subscribers
Subscribers (which must be domain services) subscribe using either the link:https://github.com/google/guava[Guava] API or (if the xref:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`] has been appropriately configured) using the link:http://www.axonframework.org/[Axon Framework] API. The examples below use the Guava API.
@@ -65,11 +66,10 @@ Subscribers can be either coarse-grained (if they subscribe to the top-level eve
[source,java]
----
-@DomainService
-public class SomeSubscriber {
- @Programmatic
+@DomainService(nature=NatureOfService.DOMAIN)
+public class SomeSubscriber extends AbstractSubscriber {
@com.google.common.eventbus.Subscribe
- public void on(ActionInteractionEvent ev) {
+ public void on(ActionDomainEvent ev) {
...
}
}
@@ -79,9 +79,8 @@ or can be fine-grained (by subscribing to specific event subtypes):
[source,java]
----
-@DomainService
-public class SomeSubscriber {
- @Programmatic
+@DomainService(nature=NatureOfService.DOMAIN)
+public class SomeSubscriber extends AbstractSubscriber {
@com.google.common.eventbus.Subscribe
public void on(ToDoItem.CompletedEvent ev) {
...
@@ -134,6 +133,26 @@ It is also possible to abort the transaction during the executing or executed ph
+== Default, Doop and Noop events (`1.11.0-SNAPSHOT`)
+
+If the `domainEvent` attribute is not explicitly specified (is left as its default value, `ActionDomainEvent.Default`),
+then the framework will, by default, post an event.
+
+If this is not required, then the `isis.reflector.facet.actionAnnotation.domainEvent.postForDefault`
+configuration property can be set to "false"; this will disable posting.
+
+On the other hand, if the `domainEvent` has been explicitly specified to some subclass, then an event will be posted.
+The framework provides `ActionDomainEvent.Doop` as such a subclass, so setting the `domainEvent` attribute to this class
+will ensure that the event to be posted, irrespective of the configuration property setting.
+
+And, conversely, the framework also provides `ActionDomainEvent.Noop`; if `domainEvent` attribute is set to this class,
+then no event will be posted.
+
+
+
+
+
+
== Raising events programmatically
Normally events are only raised for interactions through the UI. However, events can be raised programmatically either by calling the xref:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`] API directly, or by emulating the UI by
http://git-wip-us.apache.org/repos/asf/isis/blob/4b891285/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Collection_domainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Collection_domainEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Collection_domainEvent.adoc
index 3950861..7846ccd 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Collection_domainEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Collection_domainEvent.adoc
@@ -34,7 +34,10 @@ public class ToDoItem {
}
----
-The purpose of the `domainEvent()` attribute is to allows a custom subclass to be emitted instead. This attribute is also supported for xref:rg.adoc#_rg_annotations_manpage-Action_domainEvent[actions] and xref:rg.adoc#_rg_annotations_manpage-Property_domainEvent[properties].
+The `domainEvent()` attribute allows a custom subclass to be emitted allowing more precise subscriptions (to those
+subclasses) to be defined instead. This attribute is also supported for
+xref:rg.adoc#_rg_annotations_manpage-Action_domainEvent[actions] and
+xref:rg.adoc#_rg_annotations_manpage-Property_domainEvent[properties].
For example:
@@ -76,11 +79,10 @@ Subscribers can be either coarse-grained (if they subscribe to the top-level eve
[source,java]
----
-@DomainService
-public class SomeSubscriber {
- @Programmatic
+@DomainService(nature=NatureOfService.DOMAIN)
+public class SomeSubscriber extends AbstractSubscriber {
@com.google.common.eventbus.Subscribe
- public void on(CollectionInteractionEvent ev) {
+ public void on(CollectionDomainEvent ev) {
...
}
}
@@ -90,9 +92,8 @@ or can be fine-grained (by subscribing to specific event subtypes):
[source,java]
----
-@DomainService
-public class SomeSubscriber {
- @Programmatic
+@DomainService(nature=NatureOfService.DOMAIN)
+public class SomeSubscriber extends AbstractSubscriber {
@com.google.common.eventbus.Subscribe
public void on(ToDoItem.DependenciesChangedEvent ev) {
...
@@ -144,6 +145,25 @@ It is also possible to abort the transaction during the executing or executed ph
+== Default, Doop and Noop events (`1.11.0-SNAPSHOT`)
+
+If the `domainEvent` attribute is not explicitly specified (is left as its default value, `CollectionDomainEvent.Default`),
+then the framework will, by default, post an event.
+
+If this is not required, then the `isis.reflector.facet.collectionAnnotation.domainEvent.postForDefault`
+configuration collection can be set to "false"; this will disable posting.
+
+On the other hand, if the `domainEvent` has been explicitly specified to some subclass, then an event will be posted.
+The framework provides `CollectionDomainEvent.Doop` as such a subclass, so setting the `domainEvent` attribute to this class
+will ensure that the event to be posted, irrespective of the configuration collection setting.
+
+And, conversely, the framework also provides `CollectionDomainEvent.Noop`; if `domainEvent` attribute is set to this class,
+then no event will be posted.
+
+
+
+
+
== Raising events programmatically
Normally events are only raised for interactions through the UI. However, events can be raised programmatically either by calling the xref:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`] API directly, or by emulating the UI by
http://git-wip-us.apache.org/repos/asf/isis/blob/4b891285/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout.adoc
index e9cd15d..e9a8985 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout.adoc
@@ -48,11 +48,19 @@ The table below summarizes the annotation's attributes.
|Currently unused.
+|xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_cssClassUiEvent[`cssClassUiEvent()`]
+|subtype of `CssClassUiEvent` +
+(`CssClassUiEvent.Default`)
+|the event type to be posted (`1.11.0-SNAPSHOT`) to the xref:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`] to obtain a CSS class for the domain object.
+
|xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_describedAs[`describedAs()`]
|String.
|description of this class, eg to be rendered in a tooltip.
-
+|xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_iconUiEvent[`iconUiEvent()`]
+|subtype of `IconUiEvent` +
+(`IconUiEvent.Default`)
+|the event type to be posted (`1.11.0-SNAPSHOT`) to the xref:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`] to obtain the icon (name) for the domain object.
|xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_named[`named()`]
|String.
@@ -70,6 +78,12 @@ A typical use case is if the desired name is a reserved Java keyword, such as `d
|String.
|the plural name of the class
+
+|xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_titleUiEvent[`titleUiEvent()`]
+|subtype of `TitleUiEvent` +
+(`TitleUiEvent.Default`)
+|the event type to be posted (`1.11.0-SNAPSHOT`) to the xref:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`] to obtain the title for the domain object.
+
|===
@@ -107,9 +121,12 @@ Note that there is (currently) no support for specifying UI hints for domain obj
include::_rg_annotations_manpage-DomainObjectLayout_bookmarking.adoc[leveloffset=+1]
include::_rg_annotations_manpage-DomainObjectLayout_cssClass.adoc[leveloffset=+1]
include::_rg_annotations_manpage-DomainObjectLayout_cssClassFa.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-DomainObjectLayout_cssClassUiEvent.adoc[leveloffset=+1]
include::_rg_annotations_manpage-DomainObjectLayout_describedAs.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-DomainObjectLayout_iconUiEvent.adoc[leveloffset=+1]
include::_rg_annotations_manpage-DomainObjectLayout_named.adoc[leveloffset=+1]
include::_rg_annotations_manpage-DomainObjectLayout_paged.adoc[leveloffset=+1]
include::_rg_annotations_manpage-DomainObjectLayout_plural.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-DomainObjectLayout_titleUiEvent.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/4b891285/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_cssClassUiEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_cssClassUiEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_cssClassUiEvent.adoc
new file mode 100644
index 0000000..c79e7a3
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_cssClassUiEvent.adoc
@@ -0,0 +1,125 @@
+[[_rg_annotations_manpage-DomainObjectLayout_cssClassUiEvent]]
+= cssClassUiEvent() (`1.11.0-SNAPSHOT`)
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+Whenever a domain object is to be rendered, the framework fires off an CSS class UI event to obtain a CSS class to use
+in any wrapping ``<div>``s and ``<span>``s that render the domain object. This is as an alternative to implementing
+xref:rg.adoc#_rg_methods_reserved_manpage-cssClass[`cssClass()`] reserved method. (If `cssClass()` is present, then
+it will take precedence).
+
+Subscribers subscribe through the xref:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`] using either link:https://github.com/google/guava[Guava] or link:http://www.axonframework.org/[Axon Framework] annotations and can
+optionally specify a title.
+
+[NOTE]
+====
+The feature was originally introduced so that xref:rg.adoc#_rg_annotations_manpage-XmlRootElement[`@XmlRootElement`]-annotated
+xref:ug.adoc#_ug_more-advanced_view-models[view model]s could be kept as minimal as possible, just defining the data.
+UI events allow subscribers to provide UI hints, while xref:ug.adoc#_ug_more-advanced_decoupling_mixins[mixin]s can be used to provide the behaviour.
+====
+
+By default the event raised is `CssClassUiEvent.Default`. For example:
+
+[source,java]
+----
+@DomainObjectLayout
+public class ToDoItemDto {
+ ...
+}
+----
+
+The purpose of the `cssClassUiEvent()` attribute is to allows a custom subclass to be emitted instead. A similar
+attribute is available for titles and icons.
+
+For example:
+
+[source,java]
+----
+@DomainObjectLayout(
+ iconUiEvent=ToDoItemDto.CssClassUiEvent.class
+)
+public class ToDoItemDto {
+ public static class CssClassUiEvent
+ extends org.apache.isis.applib.services.eventbus.CssClassUiEvent<ToDoItemDto> { }
+ ...
+}
+----
+
+The benefit is that subscribers can be more targeted as to the events that they subscribe to.
+
+
+
+
+== Subscribers
+
+Subscribers (which must be domain services) subscribe using either the link:https://github.com/google/guava[Guava] API
+or (if the xref:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`] has been appropriately configured)
+using the link:http://www.axonframework.org/[Axon Framework] API. The examples below use the Guava API.
+
+Subscribers can be either coarse-grained (if they subscribe to the top-level event type):
+
+[source,java]
+----
+@DomainService(nature=NatureOfService.DOMAIN)
+public class SomeSubscriber extends AbstractSubscriber {
+ @com.google.common.eventbus.Subscribe
+ public void on(CssClassUiEvent ev) {
+ if(ev.getSource() instanceof ToDoItemDto) { ... }
+ }
+}
+----
+
+or can be fine-grained (by subscribing to specific event subtypes):
+
+[source,java]
+----
+@DomainService(nature=NatureOfService.DOMAIN)
+public class SomeSubscriber extends AbstractSubscriber {
+ @com.google.common.eventbus.Subscribe
+ public void on(ToDoItemDto.CssClassUiEvent ev) {
+ ...
+ }
+}
+----
+
+The subscriber should then use `CssClassUiEvent#setCssClass(...)` to actually specify the CSS class to be used.
+
+[TIP]
+====
+If the AxonFramework is being used, replace `@com.google.common.eventbus.Subscribe` with `@org.axonframework.eventhandling.annotation.EventHandler`.
+====
+
+
+
+
+
+== Default, Doop and Noop events
+
+If the `cssClassUiEvent` attribute is not explicitly specified (is left as its default value, `CssClassUiEvent.Default`),
+then the framework will, by default, post an event.
+
+If this is not required, then the `isis.reflector.facet.domainObjectLayoutAnnotation.cssClassUiEvent.postForDefault`
+configuration property can be set to "false"; this will disable posting.
+
+On the other hand, if the `cssClassUiEvent` has been explicitly specified to some subclass, then an event will be posted.
+The framework provides `CssClassUiEvent.Doop` as such a subclass, so setting the `cssClassUiEvent` attribute to this class
+will ensure that the event to be posted, irrespective of the configuration property setting.
+
+And, conversely, the framework also provides `CssClassUiEvent.Noop`; if `cssClassUiEvent` attribute is set to this class,
+thn no event will be posted.
+
+
+
+
+
+
+== Raising events programmatically
+
+Normally events are only raised for interactions through the UI. However, events can be raised programmatically either
+by calling the xref:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`] API directly, or as a result
+of calling the xref:rg.adoc#_rg_services-api_manpage-DomainObjectContainer[`DomainObjectContainer`]'s
+`cssClassOf(...)` method.
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/4b891285/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_iconUiEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_iconUiEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_iconUiEvent.adoc
new file mode 100644
index 0000000..600d3da
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_iconUiEvent.adoc
@@ -0,0 +1,120 @@
+[[_rg_annotations_manpage-DomainObjectLayout_iconUiEvent]]
+= iconUiEvent() (`1.11.0-SNAPSHOT`)
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+Whenever a domain object is to be rendered, the framework fires off an icon UI event to obtain an icon (name) for the
+object (if possible). This is as an alternative to implementing
+xref:rg.adoc#_rg_methods_reserved_manpage-iconName[`iconName()`] reserved method. (If `iconName()` is present, then
+it will take precedence).
+
+Subscribers subscribe through the xref:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`] using either link:https://github.com/google/guava[Guava] or link:http://www.axonframework.org/[Axon Framework] annotations and can
+optionally specify a title.
+
+[NOTE]
+====
+The feature was originally introduced so that xref:rg.adoc#_rg_annotations_manpage-XmlRootElement[`@XmlRootElement`]-annotated
+xref:ug.adoc#_ug_more-advanced_view-models[view model]s could be kept as minimal as possible, just defining the data.
+UI events allow subscribers to provide UI hints, while xref:ug.adoc#_ug_more-advanced_decoupling_mixins[mixin]s can be used to provide the behaviour.
+====
+
+By default the event raised is `IconUiEvent.Default`. For example:
+
+[source,java]
+----
+@DomainObjectLayout
+public class ToDoItemDto {
+ ...
+}
+----
+
+The purpose of the `iconUiEvent()` attribute is to allows a custom subclass to be emitted instead. A similar
+attribute is available for titles and CSS classes.
+
+For example:
+
+[source,java]
+----
+@DomainObjectLayout(
+ iconUiEvent=ToDoItemDto.IconUiEvent.class
+)
+public class ToDoItemDto {
+ public static class IconUiEvent
+ extends org.apache.isis.applib.services.eventbus.IconUiEvent<ToDoItemDto> { }
+ ...
+}
+----
+
+The benefit is that subscribers can be more targeted as to the events that they subscribe to.
+
+
+
+
+== Subscribers
+
+Subscribers (which must be domain services) subscribe using either the link:https://github.com/google/guava[Guava] API
+or (if the xref:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`] has been appropriately configured)
+using the link:http://www.axonframework.org/[Axon Framework] API. The examples below use the Guava API.
+
+Subscribers can be either coarse-grained (if they subscribe to the top-level event type):
+
+[source,java]
+----
+@DomainService(nature=NatureOfService.DOMAIN)
+public class SomeSubscriber extends AbstractSubscriber {
+ @com.google.common.eventbus.Subscribe
+ public void on(IconUiEvent ev) {
+ if(ev.getSource() instanceof ToDoItemDto) { ... }
+ }
+}
+----
+
+or can be fine-grained (by subscribing to specific event subtypes):
+
+[source,java]
+----
+@DomainService(nature=NatureOfService.DOMAIN)
+public class SomeSubscriber extends AbstractSubscriber {
+ @com.google.common.eventbus.Subscribe
+ public void on(ToDoItemDto.IconUiEvent ev) {
+ ...
+ }
+}
+----
+
+The subscriber should then use `IconUiEvent#setIconName(...)` to actually specify the icon name to be used.
+
+[TIP]
+====
+If the AxonFramework is being used, replace `@com.google.common.eventbus.Subscribe` with `@org.axonframework.eventhandling.annotation.EventHandler`.
+====
+
+
+
+== Default, Doop and Noop events
+
+If the `iconUiEvent` attribute is not explicitly specified (is left as its default value, `IconUiEvent.Default`),
+then the framework will, by default, post an event.
+
+If this is not required, then the `isis.reflector.facet.domainObjectLayoutAnnotation.iconUiEvent.postForDefault`
+configuration property can be set to "false"; this will disable posting.
+
+On the other hand, if the `iconUiEvent` has been explicitly specified to some subclass, then an event will be posted.
+The framework provides `IconUiEvent.Doop` as such a subclass, so setting the `iconUiEvent` attribute to this class
+will ensure that the event to be posted, irrespective of the configuration property setting.
+
+And, conversely, the framework also provides `IconUiEvent.Noop`; if `iconUiEvent` attribute is set to this class,
+then no event will be posted.
+
+
+
+== Raising events programmatically
+
+Normally events are only raised for interactions through the UI. However, events can be raised programmatically either
+by calling the xref:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`] API directly, or as a result
+of calling the xref:rg.adoc#_rg_services-api_manpage-DomainObjectContainer[`DomainObjectContainer`]'s
+`iconNameOf(...)` method.
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/4b891285/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_titleUiEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_titleUiEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_titleUiEvent.adoc
new file mode 100644
index 0000000..6404f3e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-DomainObjectLayout_titleUiEvent.adoc
@@ -0,0 +1,119 @@
+[[_rg_annotations_manpage-DomainObjectLayout_titleUiEvent]]
+= titleUiEvent() (`1.11.0-SNAPSHOT`)
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+Whenever a domain object is to be rendered, the framework fires off a title UI event to obtain a title for the object.
+This is as an alternative to implementing xref:rg.adoc#_rg_methods_reserved_manpage-title[`title()`] reserved method, or
+using the xref:rg.adoc#_rg_annotations_manpage-Title[`@Title`] annotation, within the class itself. (If either
+`title()` or `@Title` are present, then they will take precedence).
+
+Subscribers subscribe through the xref:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`] using either link:https://github.com/google/guava[Guava] or link:http://www.axonframework.org/[Axon Framework] annotations and can
+optionally specify a title.
+
+[NOTE]
+====
+The feature was originally introduced so that xref:rg.adoc#_rg_annotations_manpage-XmlRootElement[`@XmlRootElement`]-annotated
+xref:ug.adoc#_ug_more-advanced_view-models[view model]s could be kept as minimal as possible, just defining the data.
+UI events allow subscribers to provide UI hints, while xref:ug.adoc#_ug_more-advanced_decoupling_mixins[mixin]s can be used to provide the behaviour.
+====
+
+By default the event raised is `TitleUiEvent.Default`. For example:
+
+[source,java]
+----
+@DomainObjectLayout
+public class ToDoItemDto {
+ ...
+}
+----
+
+The purpose of the `titleUiEvent()` attribute is to allows a custom subclass to be emitted instead. A similar
+attribute is available for icon names and CSS classes.
+
+For example:
+
+[source,java]
+----
+@DomainObjectLayout(
+ titleUiEvent=ToDoItemDto.TitleUiEvent.class
+)
+public class ToDoItemDto {
+ public static class TitleUiEvent
+ extends org.apache.isis.applib.services.eventbus.TitleUiEvent<ToDoItemDto> { }
+ ...
+}
+----
+
+The benefit is that subscribers can be more targeted as to the events that they subscribe to.
+
+
+
+
+== Subscribers
+
+Subscribers (which must be domain services) subscribe using either the link:https://github.com/google/guava[Guava] API
+or (if the xref:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`] has been appropriately configured)
+using the link:http://www.axonframework.org/[Axon Framework] API. The examples below use the Guava API.
+
+Subscribers can be either coarse-grained (if they subscribe to the top-level event type):
+
+[source,java]
+----
+@DomainService(nature=NatureOfService.DOMAIN)
+public class SomeSubscriber extends AbstractSubscriber {
+ @com.google.common.eventbus.Subscribe
+ public void on(TitleUiEvent ev) {
+ if(ev.getSource() instanceof ToDoItemDto) { ... }
+ }
+}
+----
+
+or can be fine-grained (by subscribing to specific event subtypes):
+
+[source,java]
+----
+@DomainService(nature=NatureOfService.DOMAIN)
+public class SomeSubscriber extends AbstractSubscriber {
+ @com.google.common.eventbus.Subscribe
+ public void on(ToDoItemDto.TitleUiEvent ev) {
+ ...
+ }
+}
+----
+
+The subscriber should then use either `TitleUiEvent#setTranslatableTitle(...)` or `TitleUiEvent#setTitle(...)` to
+actually specify the title to be used.
+
+
+[TIP]
+====
+If the AxonFramework is being used, replace `@com.google.common.eventbus.Subscribe` with `@org.axonframework.eventhandling.annotation.EventHandler`.
+====
+
+
+
+== Default, Doop and Noop events
+
+If the `titleUiEvent` attribute is not explicitly specified (is left as its default value, `TitleUiEvent.Default`),
+then the framework will, by default, post an event.
+
+If this is not required, then the `isis.reflector.facet.domainObjectLayoutAnnotation.titleUiEvent.postForDefault`
+configuration property can be set to "false"; this will disable posting.
+
+On the other hand, if the `titleUiEvent` has been explicitly specified to some subclass, then an event will be posted.
+The framework provides `TitleUiEvent.Doop` as such a subclass, so setting the `titleUiEvent` attribute to this class
+will ensure that the event to be posted, irrespective of the configuration property setting.
+
+And, conversely, the framework also provides `TitleUiEvent.Noop`; if `titleUiEvent` attribute is set to this class,
+thn no event will be posted.
+
+
+== Raising events programmatically
+
+Normally events are only raised for interactions through the UI. However, events can be raised programmatically either
+by calling the xref:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`] API directly, or as a result
+of calling the xref:rg.adoc#_rg_services-api_manpage-DomainObjectContainer[`DomainObjectContainer`]'s
+`titleOf(...)` method.
http://git-wip-us.apache.org/repos/asf/isis/blob/4b891285/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Property_domainEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Property_domainEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Property_domainEvent.adoc
index 080b235..9787f56 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Property_domainEvent.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-Property_domainEvent.adoc
@@ -26,7 +26,10 @@ public class ToDoItem {
}
----
-The purpose of the `domainEvent()` attribute is to allows a custom subclass to be emitted instead. This attribute is also supported for xref:rg.adoc#_rg_annotations_manpage-Action_domainEvent[actions] and xref:rg.adoc#_rg_annotations_manpage-Property_domainEvent[properties].
+The `domainEvent()` attribute allows a custom subclass to be emitted allowing more precise subscriptions (to those
+subclasses) to be defined instead. This attribute is also supported for
+ xref:rg.adoc#_rg_annotations_manpage-Action_domainEvent[actions] and
+ xref:rg.adoc#_rg_annotations_manpage-Property_domainEvent[properties].
For example:
@@ -59,16 +62,12 @@ Subscribers can be either coarse-grained (if they subscribe to the top-level eve
[source,java]
----
-@DomainService
-public class SomeSubscriber {
-
- @Programmatic
+@DomainService(nature=NatureOfService.DOMAIN)
+public class SomeSubscriber extends AbstractSubscriber {
@com.google.common.eventbus.Subscribe
- public void on(PropertyInteractionEvent ev) {
-
+ public void on(PropertyDomainEvent ev) {
...
}
-
}
----
@@ -76,16 +75,12 @@ or can be fine-grained (by subscribing to specific event subtypes):
[source,java]
----
-@DomainService
-public class SomeSubscriber {
-
- @Programmatic
+@DomainService(nature=NatureOfService.DOMAIN)
+public class SomeSubscriber extends AbstractSubscriber {
@com.google.common.eventbus.Subscribe
public void on(ToDoItem.DueByChangedEvent ev) {
-
...
}
-
}
----
@@ -133,6 +128,25 @@ It is also possible to abort the transaction during the executing or executed ph
+== Default, Doop and Noop events (`1.11.0-SNAPSHOT`)
+
+If the `domainEvent` attribute is not explicitly specified (is left as its default value, `PropertyDomainEvent.Default`),
+then the framework will, by default, post an event.
+
+If this is not required, then the `isis.reflector.facet.propertyAnnotation.domainEvent.postForDefault`
+configuration property can be set to "false"; this will disable posting.
+
+On the other hand, if the `domainEvent` has been explicitly specified to some subclass, then an event will be posted.
+The framework provides `PropertyDomainEvent.Doop` as such a subclass, so setting the `domainEvent` attribute to this class
+will ensure that the event to be posted, irrespective of the configuration property setting.
+
+And, conversely, the framework also provides `PropertyDomainEvent.Noop`; if `domainEvent` attribute is set to this class,
+then no event will be posted.
+
+
+
+
+
== Raising events programmatically
Normally events are only raised for interactions through the UI. However, events can be raised programmatically by
http://git-wip-us.apache.org/repos/asf/isis/blob/4b891285/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-XmlJavaTypeAdapter.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-XmlJavaTypeAdapter.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-XmlJavaTypeAdapter.adoc
new file mode 100644
index 0000000..91c2ee9
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-XmlJavaTypeAdapter.adoc
@@ -0,0 +1,27 @@
+[[_rg_annotations_manpage-XmlJavaTypeAdapter]]
+= `@XmlJavaTypeAdapter` (`jaxb`) (`1.11.0-SNAPSHOT`)
+: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 JAXB `@XmlJavaTypeAdapter` annotation (`1.11.0-SNAPSHOT`) is used with the framework-provided
+`PersistentEntityAdapter` to instruct JAXB to serialize references to persistent entities into a canonical `<oid-dto>`
+element: basically a formal XML equivalent to the `Bookmark` provided by the
+xref:rg.adoc#_rg_services-api_manpage-BookmarkService[`BookmarkService`].
+
+For example:
+
+[source,java]
+----
+@XmlJavaTypeAdapter(PersistentEntityAdapter.class)
+public class ToDoItem ... {
+ ...
+}
+----
+
+This annotation therefore allows view models/DTOs to have references to persistent entities; a common idiom.
+
+For a more complete discussion of writing JAXB view models/DTOs, see xref:ug.adoc#_ug_more-advanced_view-models[this topic]
+in the user guide.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/4b891285/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-XmlRootElement.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-XmlRootElement.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-XmlRootElement.adoc
index 3fad258..604c034 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-XmlRootElement.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-XmlRootElement.adoc
@@ -5,9 +5,9 @@
:_imagesdir: images/
-The `@XmlRootElement` annotation (`1.11.0-SNAPSHOT`) provides an alternative way to define a view model, in particular
-one intended to act as a DTO for use within xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer], or which
-contains arbitrarily complex state.
+The `@XmlRootElement` annotation (`1.11.0-SNAPSHOT`) provides an alternative way to define a
+xref:rg.adoc#_ug_more-advanced_view-models[view model], in particular one intended to act as a DTO for use within
+xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer], or which contains arbitrarily complex state.
A view model is a non-persisted domain object whose state is converted to/from a string memento. In the case of a
JAXB-annotated object this memento is its XML representation. JAXB generally requires that the root element of the
@@ -24,14 +24,14 @@ xref:rg.adoc#_rg_services-spi_manpage-ContentMappingService[`ContentMappingServi
This provides a stable and
versioned API to access data in XML format using whatever client-side technology may be appropriate.
-* the XML graph can be as deep as required, in particular it can contain collections of other objects. +
+* the XML graph can be as deep as required; in particular it can contain collections of other objects. +
+
In contrast, if the `@ViewModel` annotation is used then only the state of the properties (not collections) is captured.
If using `ViewModel` interface then arbitrary state (including that of collections), however the programmer must write
all the code by hand
The main disadvantages of using JAXB-annotated view models is that any referenced persistent entity must be annotated
-with the xref:rg.adoc#_rg_annotations_manpage-XmlValueTypeAdapter[`@XmlValueTypeAdapter`], using the
+with the xref:rg.adoc#_rg_annotations_manpage-XmlJavaTypeAdapter[`@XmlJavaTypeAdapter`], using the
framework-provided `PersistentEntityAdapter`. This adapter converts any references to such domain entities into the
`<oid-dto>` element as defined by the Apache Isis xref:rg.adoc#_rg_schema-common[common schema].
@@ -51,22 +51,32 @@ This example is taken from the (non-ASF) http://github.com/isisaddons/isis-app-t
[source,java]
----
-@XmlRootElement(name = "toDoItemDto") // <1>
+@XmlRootElement(name = "toDoItemDto") // <1>
public class ToDoItemDto implements Dto {
-
+ @Getter @Setter // <2>
protected String description;
-
+ @Getter @Setter
protected String category;
-
+ @Getter @Setter
protected String subcategory;
-
+ @Getter @Setter
protected BigDecimal cost;
-
- // getters and setters omitted
}
----
<1> identifies this class as a view model and defines the root element for JAXB serialization
+<2> using Project Lombok for getters and setters
+
+== See also
+
+Although (like any other viewmodel) a JAXB-annotated can have behaviour (actions) and UI hints, you may wish to keep
+the DTO "clean", just focused on specifying the data contract.
+
+Behaviour can therefore be provided using xref:ug.adoc#_ug_more-advanced_decoupling_mixins[mixins] (annotated with
+xref:rg.adoc#_rg_annotations_manpage-Mixin[`@Mixin`]), while xref:rg.adoc#_rg_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:ug.adoc#_ug_more-advanced_view-models[this topic]
in the user guide.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/4b891285/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-XmlValueTypeAdapter.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-XmlValueTypeAdapter.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-XmlValueTypeAdapter.adoc
deleted file mode 100644
index 36609e7..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-XmlValueTypeAdapter.adoc
+++ /dev/null
@@ -1,25 +0,0 @@
-[[_rg_annotations_manpage-XmlRootElement]]
-= `@XmlValueTypeAdapter` (`jaxb`) (`1.11.0-SNAPSHOT`)
-: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 JAXB `@XmlValueTypeAdapter` annotation (`1.11.0-SNAPSHOT`) influences the serialization of objects into XML.
-While not recognized directly by the framework, the framework _does_ provide the `PersistentEntityAdapter` class,
-which causes JAXB to serialize references to persistent entities into a canonical `<oid-dto>` element: equivalent to the `Bookmark` provided by the xref:rg.adoc#_rg_services-api_manpage-BookmarkService[`BookmarkService`].
-
-For example:
-
-[source,java]
-----
-@XmlJavaTypeAdapter(PersistentEntityAdapter.class)
-public class ToDoItem ... {
- ...
-}
-----
-
-This annotation therefore allows view models/DTOs to have references to persistent entities; a common idiom. For a
-more complete discussion of writing JAXB view models/DTOs, see xref:ug.adoc#_ug_more-advanced_view-models[this topic]
-in the user guide.
-
http://git-wip-us.apache.org/repos/asf/isis/blob/4b891285/adocs/documentation/src/main/asciidoc/guides/_rg_classes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes.adoc
index 7155f67..475004e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_classes.adoc
@@ -11,6 +11,7 @@ This chapter describes the usage of various classes and interfaces that are not
include::_rg_classes_AppManifest-bootstrapping.adoc[leveloffset=+1]
include::_rg_classes_super.adoc[leveloffset=+1]
include::_rg_classes_domainevent.adoc[leveloffset=+1]
+include::_rg_classes_uievent.adoc[leveloffset=+1]
include::_rg_classes_lifecycleevent.adoc[leveloffset=+1]
include::_rg_classes_value-types.adoc[leveloffset=+1]
include::_rg_classes_utility.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/4b891285/adocs/documentation/src/main/asciidoc/guides/_rg_classes_roles_manpage-Dto.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_roles_manpage-Dto.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_roles_manpage-Dto.adoc
index b2fb865..b7d5f22 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_roles_manpage-Dto.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_roles_manpage-Dto.adoc
@@ -7,14 +7,14 @@
The `Dto` role interface (`1.11.0-SNAPSHOT`) is intended to be implemented by JAXB-annotated view models, that is, annotated using
xref:rg.adoc#_rg_annotations_manpage-XmlRootElement[`@XmlRootElement`]. It enables the ability to download the XML and
-XSD schema of those objects using two mixins, `Dto_downloadXml` and `Dto_downloadXsd`.
+XSD schema of those objects using two xref:ug.adoc#_ug_more-advanced_decoupling_mixins[mixins],
+`Dto_downloadXml` and `Dto_downloadXsd`.
The interface is just a marker interface (with no members), and is defined as:
[source,java]
----
-public interface Dto {
-}
+public interface Dto { }
----
The `Dto_downloadXml` mixin defines the following action:
@@ -24,11 +24,12 @@ The `Dto_downloadXml` mixin defines the following action:
@Mixin
public class Dto_downloadXml {
public Dto_downloadXml(final Dto dto) { ... } // <1>
- public Object $$(final String fileName) { ... }
+ public Object downloadXml(final String fileName) { ... } // <2>
...
}
----
<1> provided as an action to any class that (trivially) implements the `Dto` interface
+<2> actually this is '$$' in the code, a "special case" that means to use the derive the action name from the class name.
This will return the XML text wrapped up in a xref:rg.adoc#_rg_classes_value-types_manpage-Clob[`Clob`].
@@ -38,17 +39,19 @@ The `Dto_downloadXsd` mixin is similar:
----
@Mixin
public class Dto_downloadXsd {
- public Dto_downloadXsd(final Dto dto) { ... } // <1>
- public Object $$(final String fileName, final IsisSchemes isisSchemas) { ... } // <2>
+ public Dto_downloadXsd(final Dto dto) { ... } // <1>
+ public Object downloadXsd(final String fileName, final IsisSchemes isisSchemas) { ... } // <2>
}
----
<1> provided as an action to any class that (trivially) implements the `Dto` interface
+<2> actually this is '$$' in the code, a "special case" that means to use the derive the action name from the class name.
If the domain object's JAXB annotations reference only a single XSD schema then this will return that XML text as
a xref:rg.adoc#_rg_classes_value-types_manpage-Clob[`Clob`] of that XSD. If there are multiple XSD schemas referenced
then the action will return a zip of those schemas, wrapped up in a
xref:rg.adoc#_rg_classes_value-types_manpage-Blob[`Blob`]. The `IsisSchemas` parameter to the action can be used to
-optionally ignore the common Apache Isis schemas (useful if there is only one other XSD schema referenced by the DTO).
+optionally ignore the common xref:rg.adoc#_rg_schema[Apache Isis schemas] (useful if there is only one other XSD schema
+referenced by the DTO).
http://git-wip-us.apache.org/repos/asf/isis/blob/4b891285/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_configuring-core.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_configuring-core.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_configuring-core.adoc
index 6faf78e..28d83ee 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_configuring-core.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_configuring-core.adoc
@@ -35,6 +35,18 @@ Configuration properties for the JDO/DataNucleus objectstore can be found in the
Only intended for "emergency use" as a workaround while pending fix/patch to Apache Isis itself. (Note that there is no "datanucleus" in the property).
|`isis.reflector.facet.` +
+`actionAnnotation.` +
+`domainEvent.postForDefault`
+|`true`,`false` (`true`)
+|Whether an event should be posted if xref:rg.adoc#_rg_annotations_manpage-Action_domainEvent[`@Action#domainEvent()`] is not specified (is set to `ActionDomainEvent.Default`).
+
+|`isis.reflector.facet.` +
+`collectionAnnotation.` +
+`domainEvent.postForDefault`
+|`true`,`false` (`true`)
+|Whether an event should be posted if xref:rg.adoc#_rg_annotations_manpage-Collection_domainEvent[`@Collection#domainEvent()`] is not specified (is set to `CollectionDomainEvent.Default`).
+
+|`isis.reflector.facet.` +
`cssClass.patterns`
|regex:css1,regex2:css2,...
|Comma separated list of key:value pairs, where the key is a regex matching action names (eg `delete.*`) and the value is a link:http://getbootstrap.com/css/[Bootstrap] CSS button class (eg `btn-warning) to be applied (as per `@CssClass()`) to all action members matching the regex. +
@@ -49,12 +61,36 @@ See xref:ug.adoc#_ug_how-tos_ui-hints_action-icons-and-css[UI hints] for more de
See xref:ug.adoc#_ug_how-tos_ui-hints_action-icons-and-css[UI hints] for more details.
|`isis.reflector.facet.` +
+`domainObjectLayoutAnnotation.` +
+`cssClassUiEvent.postForDefault`
+|`true`,`false` (`true`)
+|Whether an event should be posted if xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_cssClassUiEvent[`@DomainObjectLayout#cssClassUiEvent()`] is not specified (is set to `CssClassUiEvent.Default`).
+
+|`isis.reflector.facet.` +
+`domainObjectLayoutAnnotation.` +
+`iconUiEvent.postForDefault`
+|`true`,`false` (`true`)
+|Whether an event should be posted if xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_iconUiEvent[`@DomainObjectLayout#iconUiEvent()`] is not specified (is set to `IconUiEvent.Default`).
+
+|`isis.reflector.facet.` +
+`domainObjectLayoutAnnotation.` +
+`titleUiEvent.postForDefault`
+|`true`,`false` (`true`)
+|Whether an event should be posted if xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_titleUiEvent[`@DomainObjectLayout#titleUiEvent()`] is not specified (is set to `TitleUiEvent.Default`).
+
+|`isis.reflector.facet.` +
`filterVisibility`
| `true`,`false` (`true`)
|Whether objects should be filtered for visibility. +
See xref:rg.adoc#_rg_runtime_configuring-core_filterVisibility[section below] for further discussion.
+|`isis.reflector.facet.` +
+`propertyAnnotation.` +
+`domainEvent.postForDefault`
+|`true`,`false` (`true`)
+|Whether an event should be posted if xref:rg.adoc#_rg_annotations_manpage-Property_domainEvent[`@Property#domainEvent()`] is not specified (is set to `PropertyDomainEvent.Default`).
+
|`isis.reflector.facets`
|`FQCN`
|Fully qualified class names of a custom implementation of `ProgrammingModel` interface. +
@@ -96,15 +132,6 @@ See xref:ug.adoc#_ug_extending_programming-model_custom-validator[Custom Validat
| Whether deprecated annotations or naming conventions are tolerated or not. If not, then a metamodel validation error will be triggered, meaning the app won't boot (fail-fast).
-|`isis.services.` +
-`ServicesInstallerFromAnnotation.` +
-`packagePrefix`
-|fully qualified package names (CSV)
-|to search for domain services (including all subpackages).
-
-This property is IGNORED if the xref:rg.adoc#_rg_runtime_configuring-components[`isis.appManifest`] configuration property is specified, or if an xref:rg.adoc#_rg_classes_super_manpage-AppManifest[`AppManifest`] is provided programmatically.
-
-
|`isis.services`
|`FQCN`,`FQCN2`,...
|Fully qualified class names of classes to be instantiated as domain services. +
@@ -227,6 +254,16 @@ This implementation provides a default set of recognizers to convert RDBMS const
| `all`, `ignoreSafe`, `none` (`all`)
|Whether actions should be automatically published (for actions annotated with xref:rg.adoc#_rg_annotations_manpage-Action_publishing[`@Action(publishing=Publishing.AS_CONFIGURED)`]. +
+
+|`isis.services.` +
+`ServicesInstallerFromAnnotation.` +
+`packagePrefix`
+|fully qualified package names (CSV)
+|to search for domain services (including all subpackages).
+
+This property is IGNORED if the xref:rg.adoc#_rg_runtime_configuring-components[`isis.appManifest`] configuration property is specified, or if an xref:rg.adoc#_rg_classes_super_manpage-AppManifest[`AppManifest`] is provided programmatically.
+
+
|`isis.services.` +
`translation.po.mode`
| `read`,`write`
http://git-wip-us.apache.org/repos/asf/isis/blob/4b891285/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_specifying-components.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_specifying-components.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_specifying-components.adoc
index 13cb02d..e8f5531 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_specifying-components.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_runtime_specifying-components.adoc
@@ -60,11 +60,11 @@ This property is IGNORED if the `isis.appManifest` configuration property is spe
This property is IGNORED if the `isis.appManifest` configuration property is specified, or if an xref:rg.adoc#_rg_classes_super_manpage-AppManifest[`AppManifest`] is provided programmatically.
|`isis.persistor`
-|`datanucleus`, `inmemory`, `FQCN` +
+|`datanucleus`
(`_datanucleus_`)
|`o.a.i.core.runtime.installerregistry.installerapi.` `PersistenceMechanismInstaller`
-This property is IGNORED completely in 1.9.0.
+This property is IGNORED completely in 1.9.0+; the `datanucleus` implementation is always used.
|`isis.services-installer`
http://git-wip-us.apache.org/repos/asf/isis/blob/4b891285/adocs/documentation/src/main/asciidoc/guides/_rg_schema-common.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_schema-common.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_schema-common.adoc
index 4e6d6cd..086c397 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_schema-common.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_schema-common.adoc
@@ -5,4 +5,13 @@
:_imagesdir: images/
-NOTE: TODO
\ No newline at end of file
+NOTE: TODO
+
+
+
+
+
+However, the identity of the underlying entity can be well defined; Apache Isis defines the
+xref:rg.adoc#_rg_schema-common[Common schema] which defines the `<oid-dto>` element (and corresponding `OidDto` class):
+the object's type and its identifier. This is basically a formal XML equivalent to the `Bookmark` object obtained
+from the xref:rg.adoc#_rg_services-api_manpage-BookmarkService[`BookmarkService`].
http://git-wip-us.apache.org/repos/asf/isis/blob/4b891285/adocs/documentation/src/main/asciidoc/guides/_rg_services-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api.adoc
index f496223..fb063b6 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api.adoc
@@ -294,6 +294,7 @@ include::_rg_services-api_manpage-EventBusService.adoc[leveloffset=+1]
include::_rg_services-api_manpage-FixtureScriptsDefault.adoc[leveloffset=+1]
include::_rg_services-api_manpage-GuiceBeanProvider.adoc[leveloffset=+1]
include::_rg_services-api_manpage-IsisJdoSupport.adoc[leveloffset=+1]
+include::_rg_services-api_manpage-JaxbService.adoc[leveloffset=+1]
include::_rg_services-api_manpage-MementoService.adoc[leveloffset=+1]
include::_rg_services-api_manpage-MetamodelService.adoc[leveloffset=+1]
include::_rg_services-api_manpage-QueryResultsCache.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/4b891285/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-JaxbService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-JaxbService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-JaxbService.adoc
index 61f0d3a..6c3647f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-JaxbService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-JaxbService.adoc
@@ -38,7 +38,7 @@ public interface JaxbService {
With respect to the `IsisSchemas` enum: a JAXB-annotated domain object will live in its own XSD namespace and may
reference multiple other XSD schemas. In particular, many JAXB domain objects will reference the
-link:http://isis.apache.org/schema[common Isis schemas] (for example the `OidDto` class that represents a reference to
+xref:rg.adoc#_rg_schema[common Isis schemas] (for example the `OidDto` class that represents a reference to
a persistent entity). The enum indicates whether these schemas should be included or excluded from the map.
Isis provides a default implementation of the service, `o.a.i.schema.services.jaxb.JaxbServiceDefault`.
http://git-wip-us.apache.org/repos/asf/isis/blob/4b891285/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-UrlEncodingService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-UrlEncodingService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-UrlEncodingService.adoc
index c7ef7ee..aec2971 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-UrlEncodingService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-UrlEncodingService.adoc
@@ -6,10 +6,23 @@
-The `UrlEncodingService` (`1.11.0-SNAPSHOT`) is used by the framework to map 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.
+The `UrlEncodingService` (`1.11.0-SNAPSHOT`) defines a consistent way to convert strings to/from a form safe for use
+within a URL. The service is used by the framework to map xref:ug.adoc#_ug_more-advanced_view-models[view model]
+mementos (derived from the state of the view model itself) into a form that can be used as a view model. When the
+framework needs to recreate the view model (for example to invoke an action on it), this URL is converted back into a
+view model memento, from which the view model can then be hydrated.
+
+Defining this functionality as an SPI has two use cases:
+
+* first, (though some browsers support longer strings), there is a limit of 2083 characters for URLs. For view model
+mementos that correspond to large strings (as might occur when serializing a JAXB
+xref:rg.adoc#_rg_annotations_manpage-XmlRootElement[`@XmlRootElement`]-annotated view model), the service provides a
+hook. +
++
+For example, each memento string could be mapped to a GUID held in some cluster-aware cache.
+
+* the service provides the ability, to encrypt the string in order to avoid leakage of potentially sensitive
+state within the URL.
The framework provides a default implementation of this service, `UrlEncodingServiceUsingBaseEncoding` (also in the
applib) that uses `base-64` encoding to `UTF-8` charset.
@@ -35,11 +48,12 @@ public interface UrlEncodingService {
== Implementation
-The framework provides a default implementation (`UrlEncodingServiceUsingBaseEncoding`) that uses converts the string
-using base-64 encoding and UTF-8 character set. Note that although the maximum length of a URL should not exceed
-2083 characters. For large DTOs (capturing a lot of state), you may therefore wish to register an alternative
-implementation.
+The framework provides a default implementation (`UrlEncodingServiceUsingBaseEncoding`) that simply converts the string
+using base-64 encoding and UTF-8 character set. As already noted, be aware that the maximum length of a URL should not
+exceed 2083 characters. For large view models, there's the possibility that this limit could be exceeded; in such
+cases register an alternative implementation of this service.
To use an alternative implementation, use
xref:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
+
http://git-wip-us.apache.org/repos/asf/isis/blob/4b891285/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure.adoc
index 550a170..8cc7ea0 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_class-structure.adoc
@@ -5,7 +5,7 @@
:_imagesdir: images/
-Apache Isis works by building a metamodel of the domain objects: entities, view models and services. The class members of both entities and view models represent both state -- (single-valued) properties and (multi-valued) collections -- and behaviour -- actions. The class members of domain services is simpler: just behaviour, ie actions.
+Apache Isis works by building a metamodel of the domain objects: entities, xref:ug.adoc#_ug_more-advanced_view-models[view model]s and services. The class members of both entities and view models represent both state -- (single-valued) properties and (multi-valued) collections -- and behaviour -- actions. The class members of domain services is simpler: just behaviour, ie actions.
In the automatically generated UI a property is rendered as a field. This can be either of a value type (a string, number, date, boolean etc) or can be a reference to another entity. A collection is generally rendered as a table.
http://git-wip-us.apache.org/repos/asf/isis/blob/4b891285/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_view-models.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_view-models.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_view-models.adoc
index bbf5f64..2f84f8d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_view-models.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_view-models.adoc
@@ -5,7 +5,7 @@
:_imagesdir: images/
-View models are a type of domain objects (with state, behaviour etc) but where the state is _not_ persisted into the
+View models are a type of domain object (with state, behaviour etc) but where the state is _not_ persisted into the
JDO/DataNucleus-managed database, but is instead converted to/from a string memento, and held by the calling client.
This opens up a number of more advanced use cases.
@@ -164,7 +164,7 @@ While the underlying technique is the same irrespective of use case, the program
defining a view model so that the original intent is not lost. They are:
.View model programming model
-[cols="1a,4a,4a", options="header"]
+[cols="1a,4a,2a", options="header"]
|===
| Use case
@@ -211,8 +211,8 @@ public class Dashboard { ... }
[source,java]
----
public class ExcelUploadManager implements ViewModel {
- public String viewModelMemento() { ... }
- public void viewModelInit(String memento) { ... }
+ public String viewModelMemento() { ... }
+ public void viewModelInit(String memento) { ... }
}
|Implement xref:rg.adoc#_rg_classes_super_manpage-ViewModel[`ViewModel`] interface. The memento is as defined by the
interface's methods: the programmer has full control (but also full responsibility) for the string memento.
@@ -229,6 +229,7 @@ derived automatically by serializing the XML graph as implied by the JAXB annota
et al) this state _can_ include collections.
|===
+JAXB-annotated DTOs are discussed in more detail immediately xref:rg.adoc#_ug_more-advanced_view-models_jaxb[below].
[[_ug_more-advanced_view-models_jaxb]]
@@ -262,10 +263,9 @@ representation of its underlying `ToDoItem` entity):
}
)
@DomainObjectLayout(
- titleUiEvent = TitleUiEvent.Default.class // <4>
+ titleUiEvent = TitleUiEvent.Doop.class // <4>
)
public class ToDoItemDto implements Dto {
-
@XmlElement(required = true)
@Getter @Setter // <5>
protected String description;
@@ -284,111 +284,135 @@ public class ToDoItemDto implements Dto {
<1> identifies this class as a view model and defines the root element for JAXB serialization
<2> specify the XML schema namespace to which this element type belongs
<3> all properties in the class must be listed; (they can be ignored using `@XmlTransient`)
-<4> optional but recommended: using xref:rg.adoc#_rg_classes_uievent_manpage-TitleUiEvent[`TitleUiEvent`] to obtain
+<4> demonstrating use of UI events for a subscriber to provide the DTO's title; see xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_titleUiEvent[`@DomainObjectLayout#titleUiEvent()`].
<5> optional; JAXB metadata can specify such attributes as required/optional
+For the package in which the DTO class resides, we define a corresponding namespace. This goes in `package-info.java`:
[source,java]
----
@javax.xml.bind.annotation.XmlSchema(
+ namespace = "http://viewmodels.app.todoapp/v1/todoitem", // <1>
xmlns = {
- @XmlNs(
- namespaceURI = "http://isis.apache.org/schema/common",
+ @javax.xml.bind.annotation.XmlNs(
+ namespaceURI = "http://isis.apache.org/schema/common", // <2>
prefix = "common"
)
},
- namespace = "http://viewmodels.app.todoapp/v1/todoitem",
elementFormDefault = javax.xml.bind.annotation.XmlNsForm.QUALIFIED
)
-package todoapp.app.viewmodels.todoitem.v1;
-
-import javax.xml.bind.annotation.XmlNs;
+package todoapp.app.viewmodels.todoitem.v1_0; // <3>
----
+<1> the namespace URI. There is no requirement for this to correspond to a physical URL, but it should be unique (this
+usually implies the usage of a company domain name)
+<2> define an alias for all of other Java types used within the DTO class. It's recommended that the Apache Isis xref:rg.adoc#_rg_schema-common[common schema] is always be defined; any references to persistent entities will resultin usage
+of this schema.
+<3> the package in which the DTO resides.
+Note how both the XML namespace and package are broadly equivalent to each other; in particular note that they both
+also include a version "v1".
-This annotation therefore allows view models/DTOs to have references to persistent entities. It is a common
+=== Versioning
+Versioning DTOs enables us to make changes without breaking existing consumers of the data. We can distinguish two
+types of changes:
-[source,java]
-----
-package todoapp.app.viewmodels.todoitem.v2;
-
-import java.util.List;
+* backwardly compatible changes
+* breaking changes.
-import javax.xml.bind.annotation.XmlAccessType;
-import javax.xml.bind.annotation.XmlAccessorType;
-import javax.xml.bind.annotation.XmlElement;
-import javax.xml.bind.annotation.XmlElementWrapper;
-import javax.xml.bind.annotation.XmlRootElement;
-import javax.xml.bind.annotation.XmlType;
+Following link:http://semver.org[semantic versioning] approach, we suggest using `v1_0`, `v1_1`, `v1_2` etc as the
+package version for a sequence of backwardly compatible changes, then bump up to `v2_0` for a breaking change.
-import com.google.common.collect.Lists;
+Backwardly compatible changes can generally (always?) be modelled using class inheritance. Thus, `v1_1.ToDoItemDto`
+is a subclass of `v1_0.ToDoItemDto`. This makes sense too: OO inheritance means "is-substitutable-for", so what is
+true in an OO context is true when processing XML documents.
-import org.apache.isis.applib.annotation.DomainObjectLayout;
-import org.apache.isis.applib.services.eventbus.TitleUiEvent;
+On the other hand, breaking changes probably (always?) imply that the next version of the DTO does not use inheritance.
+Thus `v2_0.ToDoItemDto` might share many of the same properties as the `v1_1.ToDoItemDto`, but any reuse would be
+copy-n-paste rather than through inheritance.
-import lombok.Getter;
-import lombok.Setter;
-import todoapp.dom.todoitem.ToDoItem;
+To see this in practice, here's (the outline of) v1.1 of `ToDoItemDto`:
-@XmlAccessorType(XmlAccessType.FIELD)
+[source,java]
+----
+package todoapp.app.viewmodels.todoitem.v1_1;
+...
+@XmlRootElement(name = "toDoItemDto")
@XmlType(
- namespace = "http://viewmodels.app.todoapp/v2/todoitem",
+ namespace = "http://viewmodels.app.todoapp/v1_1/todoitem",
propOrder = {
"toDoItem",
"similarItems"
}
)
-@XmlRootElement(name = "toDoItemDto")
-@DomainObjectLayout(
- titleUiEvent = TitleUiEvent.Default.class
-)
-public class ToDoItemDto extends todoapp.app.viewmodels.todoitem.v1.ToDoItemDto {
-
- @XmlElement(required = true)
- @Getter @Setter
- protected ToDoItem toDoItem;
-
- @XmlElementWrapper
- @XmlElement(name = "todoItem")
- @Getter @Setter
- protected List<ToDoItem> similarItems = Lists.newArrayList();
-
+public class ToDoItemDto extends todoapp.app.viewmodels.todoitem.v1_0.ToDoItemDto {
+ ...
}
----
+The corresponding `package-info.java` is similar to that for `v1_0`, though note how it also defines a namespace prefix
+for `v1_0`:
[source,java]
----
@javax.xml.bind.annotation.XmlSchema(
+ namespace = "http://viewmodels.app.todoapp/v1_1/todoitem",
xmlns = {
- @XmlNs(
+ @javax.xml.bind.annotation.XmlNs(
namespaceURI = "http://isis.apache.org/schema/common",
prefix = "common"
),
- @XmlNs(
- namespaceURI = "http://viewmodels.app.todoapp/v1/todoitem",
- prefix = "todoitem-v1"
+ @javax.xml.bind.annotation.XmlNs(
+ namespaceURI = "http://viewmodels.app.todoapp/v1_0/todoitem",
+ prefix = "todoitem-v1_0"
),
- @XmlNs(
- namespaceURI = "http://viewmodels.app.todoapp/v2/todoitem",
- prefix = "todoitem-v2"
+ @javax.xml.bind.annotation.XmlNs(
+ namespaceURI = "http://viewmodels.app.todoapp/v1_1/todoitem",
+ prefix = "todoitem-v1_1"
)
},
- namespace = "http://viewmodels.app.todoapp/v2/todoitem",
elementFormDefault = javax.xml.bind.annotation.XmlNsForm.QUALIFIED
)
-package todoapp.app.viewmodels.todoitem.v2;
-
-import javax.xml.bind.annotation.XmlNs;
+package todoapp.app.viewmodels.todoitem.v1_1;
----
+=== Referencing Domain Entities
+
+It's quite common for view models to be "backed by" (be projections of) some underlying domain entity. The
+`ToDoItemDto` we've been using as the example in this section is an example: there is an underlying `ToDoItem` entity.
+
+It wouldn't make sense to serialize out the state of a persistent entity: the point of a DTO is to act as a facade
+on top of the entity so that the implementation details (of the entity's structure) don't leak out to the consumer.
+However, the identity of the underlying entity can be well defined; Apache Isis defines the
+xref:rg.adoc#_rg_schema-common[Common schema] which defines the `<oid-dto>` element (and corresponding `OidDto` class):
+the object's type and its identifier. This is basically a formal XML equivalent to the `Bookmark` object obtained
+from the xref:rg.adoc#_rg_services-api_manpage-BookmarkService[`BookmarkService`].
+
+There is only one requirement to make this work: every referenced domain entity must be annotated with
+xref:rg.adoc#_rg_annotations_manpage-XmlJavaTypeAdapter[`@XmlJavaTypeAdapter`], specifying the framework-provided
+`PersistentEntityAdapter.class`. This class is similar to the `BookmarkService`: it knows how to create an `OidDto`
+from an object reference.
+
+Thus, in our view model we can legitimately write:
+
+[source,java]
+----
+package todoapp.app.viewmodels.todoitem.v1_1;
+...
+public class ToDoItemDto extends todoapp.app.viewmodels.todoitem.v1_0.ToDoItemDto {
+ ...
+ @Getter @Setter
+ protected ToDoItem toDoItem;
+}
+----
+
+All we need to do is remember to add that `@XmlJavaTypeAdapter` annotation to the referenced entity:
[source,java]
----
@@ -400,9 +424,37 @@ public class ToDoItem ... {
+=== Collections
+
+It's also possible for a DTO to hold collections of objects. These can be of any type, either simple properties, or
+references to other objects.
+
+The only bit of boilerplate that is required is the `@XmlElementWrapper` annotation. This instructs JAXB to create
+an XML element (based on the field name) to contain each of the elements. (If this is omitted then the contents of
+the collection are at the same level as the properties; almost certainly not what is required).
+
+For example, the v1.1 of the `ToDoItemDto` could also contain:
+
+[source,java]
+----
+package todoapp.app.viewmodels.todoitem.v1_1;
+...
+public class ToDoItemDto extends todoapp.app.viewmodels.todoitem.v1_0.ToDoItemDto {
+ ...
+ @XmlElementWrapper
+ @XmlElement(name = "todoItem")
+ @Getter @Setter
+ protected List<ToDoItem> similarItems = Lists.newArrayList();
+}
+----
+There's nothing to prevent a JAXB DTO from containing rich graphs of data, parent containing children containing
+children. Be aware though that all of this state will become the DTO's memento, ultimately converted into a URL-safe
+form, by way of the xref:rg.adoc#_rg_services-spi_manpage-UrlEncodingService[`UrlEncodingService`].
-== `UrlEncodingService`
+There are limits to the lengths of URLs, however. Therefore the DTO should not include state that can easily be
+derived from other information. If the URL does exceed limits, then provide a custom implementation of `UrlEncodingService`
+to handle the memento string in some other fashion (eg substituting it with a GUID, with the memento cached somehow
+on the server).
-NOTE: TODO
\ No newline at end of file