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 08:39:45 UTC
[2/2] isis git commit: ISIS-1255, ISIS-1250, ISIS-1252: docs for 1250
(JaxbService) and UI events (1252);
implementation of config properties to suppress broadcast of events for
default (1255)
ISIS-1255, ISIS-1250, ISIS-1252: docs for 1250 (JaxbService) and UI events (1252); implementation of config properties to suppress broadcast of events for default (1255)
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/48102a0d
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/48102a0d
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/48102a0d
Branch: refs/heads/ISIS-1250
Commit: 48102a0db859f139fba4688c1bdef20daeb2fdca
Parents: a1c7e26
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Thu Nov 19 07:39:10 2015 +0000
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Thu Nov 19 07:39:10 2015 +0000
----------------------------------------------------------------------
adocs/documentation/Gemfile | 3 +
adocs/documentation/Gemfile.lock | 2 +
adocs/documentation/monitor.rb | 72 ++--
adocs/documentation/pom.xml | 2 +-
.../asciidoc/guides/_rg_annotations_aaa.adoc | 1 -
.../guides/_rg_annotations_aaa_jee.adoc | 4 +-
.../_rg_annotations_manpage-XmlRootElement.adoc | 28 +-
...annotations_manpage-XmlValueTypeAdapter.adoc | 19 +-
.../guides/_rg_classes_roles_manpage-Dto.adoc | 14 +-
...rg_classes_roles_manpage-HoldsUpdatedAt.adoc | 1 -
.../asciidoc/guides/_rg_classes_uievent.adoc | 62 +++
...classes_uievent_manpage-CssClassUiEvent.adoc | 22 +
..._rg_classes_uievent_manpage-IconUiEvent.adoc | 23 ++
...rg_classes_uievent_manpage-TitleUiEvent.adoc | 22 +
.../main/asciidoc/guides/_rg_services-spi.adoc | 1 +
...services-spi_manpage-UrlEncodingService.adoc | 8 +
...oncepts_philosophy_domain-driven-design.adoc | 1 +
.../src/main/asciidoc/guides/_ug_how-tos.adoc | 3 +-
.../guides/_ug_how-tos_bulk-actions.adoc | 8 +
...aged-1-to-m-bidirectional-relationships.adoc | 5 +-
...placing-default-service-implementations.adoc | 64 ---
.../main/asciidoc/guides/_ug_more-advanced.adoc | 3 +-
.../guides/_ug_more-advanced_bulk-actions.adoc | 8 -
...placing-default-service-implementations.adoc | 64 +++
.../guides/_ug_more-advanced_view-models.adoc | 404 ++++++++++++++++++-
.../src/main/asciidoc/guides/cg.adoc | 2 +-
.../src/main/asciidoc/guides/ug.adoc | 2 +-
.../documentation/src/main/asciidoc/index.html | 2 +-
adocs/template/document.html.erb | 31 ++
.../applib/annotation/DomainObjectLayout.java | 6 +-
.../apache/isis/applib/annotation/Nature.java | 30 +-
.../isis/applib/annotation/ViewModel.java | 22 +
.../services/eventbus/ActionDomainEvent.java | 28 +-
.../eventbus/ActionInteractionEvent.java | 8 +
.../eventbus/CollectionDomainEvent.java | 27 +-
.../eventbus/CollectionInteractionEvent.java | 7 +
.../services/eventbus/CssClassUiEvent.java | 22 +-
.../applib/services/eventbus/IconUiEvent.java | 23 +-
.../services/eventbus/PropertyDomainEvent.java | 26 +-
.../eventbus/PropertyInteractionEvent.java | 5 +
.../applib/services/eventbus/TitleUiEvent.java | 22 +-
.../action/ActionAnnotationFacetFactory.java | 8 +-
.../CollectionAnnotationFacetFactory.java | 11 +
...ectLayoutAnnotationUsingCssClassUiEvent.java | 13 +-
.../DomainObjectLayoutFacetFactory.java | 17 +-
...nObjectLayoutAnnotationUsingIconUiEvent.java | 12 +-
...ObjectLayoutAnnotationUsingTitleUiEvent.java | 12 +-
.../PropertyAnnotationFacetFactory.java | 13 +-
.../isis/core/metamodel/util/EventUtil.java | 45 +++
.../application/simpleapp/integtests/pom.xml | 130 +++---
50 files changed, 1090 insertions(+), 278 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/48102a0d/adocs/documentation/Gemfile
----------------------------------------------------------------------
diff --git a/adocs/documentation/Gemfile b/adocs/documentation/Gemfile
index 5ea2ea7..abaaafd 100644
--- a/adocs/documentation/Gemfile
+++ b/adocs/documentation/Gemfile
@@ -15,6 +15,9 @@ gem 'asciidoctor-diagram', '~> 1.2.1'
gem 'tilt'
gem 'thread_safe'
gem 'coderay'
+
+#gem 'pygments'
+gem 'rouge'
gem 'webrick'
gem 'launchy', '~> 2.4.3'
http://git-wip-us.apache.org/repos/asf/isis/blob/48102a0d/adocs/documentation/Gemfile.lock
----------------------------------------------------------------------
diff --git a/adocs/documentation/Gemfile.lock b/adocs/documentation/Gemfile.lock
index 6a495d9..0d4f467 100644
--- a/adocs/documentation/Gemfile.lock
+++ b/adocs/documentation/Gemfile.lock
@@ -21,6 +21,7 @@ GEM
rb-inotify (0.9.5)
ffi (>= 0.5.0)
rjb (1.4.9)
+ rouge (1.8.0)
slop (4.1.0)
thread_safe (0.3.5)
tilt (2.0.1)
@@ -38,6 +39,7 @@ DEPENDENCIES
coderay
launchy (~> 2.4.3)
listen (~> 2.7)
+ rouge
slop (~> 4.1.0)
thread_safe
tilt
http://git-wip-us.apache.org/repos/asf/isis/blob/48102a0d/adocs/documentation/monitor.rb
----------------------------------------------------------------------
diff --git a/adocs/documentation/monitor.rb b/adocs/documentation/monitor.rb
index 389bf12..f1a9f6b 100644
--- a/adocs/documentation/monitor.rb
+++ b/adocs/documentation/monitor.rb
@@ -21,6 +21,7 @@ $CELLULOID_TEST=false
#
opts = Slop.parse do |o|
o.int '-p', '--port', 'port (default: 4000)', default: 4000
+ o.bool '-x', '--suppress', 'suppress monitoring'
o.bool '-b', '--browser', 'launch browser'
o.bool '-h', '--help', 'help'
end
@@ -84,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=coderay"
+ 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"
unless priming then
puts ""
@@ -120,45 +121,48 @@ def process(file,srcBasePath,targetBasePath,templateDir,i,lastTimeGenerated,prim
end
-i=0
-lastTimeGenerated = Time.now - 10
+if not opts.suppress? then
+ i=0
+ lastTimeGenerated = Time.now - 10
-puts ""
-puts ""
-puts ""
-puts "monitoring..."
-puts ""
-
-#
-# then continue monitoring all directories
-#
-adocFiles = Dir.glob("src/main/asciidoc/**/*.adoc")
-directories = adocFiles.each{ |f| File.new(f) }.uniq{ |f| File.dirname(f) }.map{ |f| File.dirname(f) }
-
-puts "listening to: #{directories}"
-
-fileListener = Listen.to(directories) do |modified, added, removed|
- unless modified.length==0
- modified.each { |file|
- i,lastTimeGenerated = process file, srcBasePath, targetBasePath, templateDir, i, lastTimeGenerated, false
- }
- end
- unless added.length==0
- added.each { |file|
- i,lastTimeGenerated = process file, srcBasePath, targetBasePath, templateDir, i, lastTimeGenerated, false
- }
- end
- unless removed.length==0
- removed.each { |file|
- #puts "removed #{file}"
- }
+ puts ""
+ puts ""
+ puts ""
+ puts "monitoring..."
+ puts ""
+
+
+ #
+ # then continue monitoring all directories
+ #
+ adocFiles = Dir.glob("src/main/asciidoc/**/*.adoc")
+ directories = adocFiles.each{ |f| File.new(f) }.uniq{ |f| File.dirname(f) }.map{ |f| File.dirname(f) }
+
+ puts "listening to: #{directories}"
+
+ fileListener = Listen.to(directories) do |modified, added, removed|
+ unless modified.length==0
+ modified.each { |file|
+ i,lastTimeGenerated = process file, srcBasePath, targetBasePath, templateDir, i, lastTimeGenerated, false
+ }
+ end
+ unless added.length==0
+ added.each { |file|
+ i,lastTimeGenerated = process file, srcBasePath, targetBasePath, templateDir, i, lastTimeGenerated, false
+ }
+ end
+ unless removed.length==0
+ removed.each { |file|
+ #puts "removed #{file}"
+ }
+ end
end
+ fileListener.start
end
-fileListener.start
-
+
httpServer = HTTPServer.new(
:Port => port,
:DocumentRoot => 'target/site',
http://git-wip-us.apache.org/repos/asf/isis/blob/48102a0d/adocs/documentation/pom.xml
----------------------------------------------------------------------
diff --git a/adocs/documentation/pom.xml b/adocs/documentation/pom.xml
index 6a86dce..5c83079 100644
--- a/adocs/documentation/pom.xml
+++ b/adocs/documentation/pom.xml
@@ -116,7 +116,7 @@
</requires>
-->
- <sourceHighlighter>coderay</sourceHighlighter>
+ <sourceHighlighter>rouge</sourceHighlighter>
<backend>html5</backend>
<templateDir>../template</templateDir>
<eruby>erb</eruby>
http://git-wip-us.apache.org/repos/asf/isis/blob/48102a0d/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa.adoc
index 4ef658d..dda6a8a 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa.adoc
@@ -11,7 +11,6 @@ include::_rg_annotations_aaa_main.adoc[leveloffset=+1]
include::_rg_annotations_aaa_other.adoc[leveloffset=+1]
include::_rg_annotations_aaa_jdo.adoc[leveloffset=+1]
include::_rg_annotations_aaa_jee.adoc[leveloffset=+1]
-include::_rg_annotations_aaa_jaxb.adoc[leveloffset=+1]
include::_rg_annotations_aaa_deprecated.adoc[leveloffset=+1]
include::_rg_annotations_aaa_partial.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/48102a0d/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 7753e93..ade88cf 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
@@ -52,7 +52,7 @@ The table below lists the JEE annotations currently recognized. Expect to see m
|Domain
|
-|xref:rg.adoc#_rg_annotations_manpage-RequestScoped[`javax.xml.bind` +
+|xref:rg.adoc#_rg_annotations_manpage-XmlRootElement[`javax.xml.bind` +
`.annotation` +
`XmlRootElement`]
|JAXB annotation indicating the XML root element when serialized to XML; also used by the framework for view models (whose memento is the XML), often also acting as a DTO.
@@ -62,7 +62,7 @@ The table below lists the JEE annotations currently recognized. Expect to see m
|xref:rg.adoc#_rg_annotations_manpage-XmlValueTypeAdapter[`javax.xml.bind` +
`.annotation` +
`XmlValueTypeAdapter`]
-|JAXB annotation defining how to serialize an entity. Used in conjunction with the (framework provided) `PersientEntityAdapter` 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`]).
+|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/48102a0d/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 66682b9..3fad258 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
@@ -51,38 +51,22 @@ This example is taken from the (non-ASF) http://github.com/isisaddons/isis-app-t
[source,java]
----
-@XmlAccessorType(XmlAccessType.FIELD) // <1>
-@XmlType(
- namespace = "http://viewmodels.app.todoapp/v1/todoitem", // <2>
- propOrder = { // <3>
- "description",
- "category",
- "subcategory",
- "cost"
- }
-)
-@XmlRootElement(name = "toDoItemDto") // <4>
+@XmlRootElement(name = "toDoItemDto") // <1>
public class ToDoItemDto implements Dto {
- @XmlElement(required = true) // <5>
- @Getter @Setter
protected String description;
- @XmlElement(required = true)
- @Getter @Setter
protected String category;
- @Getter @Setter
protected String subcategory;
- @Getter @Setter
protected BigDecimal cost;
// getters and setters omitted
}
----
-<1> optional; whether JAXB-serialization reads fields directly (as here) else uses getters/setters
-<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> mandatory, identifies this class as a view model and defines the root element for JAXB serialization
-<5> optional; JAXB metadata can specify such attributes as required/optional
+<1> identifies this class as a view model and defines the root element for JAXB serialization
+
+
+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/48102a0d/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
index 69709df..36609e7 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-XmlValueTypeAdapter.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-XmlValueTypeAdapter.adoc
@@ -5,6 +5,21 @@
:_imagesdir: images/
-The `@XmlValueTypeAdapter` annotation (`1.11.0-SNAPSHOT`) is not recognized directly by the framework, but should be used to annotate any persistent domain entities that are referenced from view models annotated with xref:rg.adoc#_rg_annotations_manpage-XmlRootElement[`@XmlRootElement`].
+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.
-NOTE: TODO
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/48102a0d/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 bd62e5c..b2fb865 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
@@ -23,13 +23,12 @@ The `Dto_downloadXml` mixin defines the following action:
----
@Mixin
public class Dto_downloadXml {
- public Dto_downloadXml(final Dto dto) { ... } // <1>
- public Object downloadXml(final String fileName) { ... } // <2>
+ public Dto_downloadXml(final Dto dto) { ... } // <1>
+ public Object $$(final String fileName) { ... }
...
}
----
<1> provided as an action to any class that (trivially) implements the `Dto` interface
-<2> in fact, the method is called "$$". This is converted to "download Xml", based on the mixin's name
This will return the XML text wrapped up in a xref:rg.adoc#_rg_classes_value-types_manpage-Clob[`Clob`].
@@ -39,17 +38,18 @@ The `Dto_downloadXsd` mixin is similar:
----
@Mixin
public class Dto_downloadXsd {
- public Dto_downloadXsd(final Dto dto) { ... } // <1>
- public Object downloadXsd(final String fileName) { ... } // <2>
+ public Dto_downloadXsd(final Dto dto) { ... } // <1>
+ public Object $$(final String fileName, final IsisSchemes isisSchemas) { ... } // <2>
}
----
<1> provided as an action to any class that (trivially) implements the `Dto` interface
-<2> in fact, the method is called "$$". This is converted to "download Xsd", based on the mixin's 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`].
+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).
+
== Related Services
http://git-wip-us.apache.org/repos/asf/isis/blob/48102a0d/adocs/documentation/src/main/asciidoc/guides/_rg_classes_roles_manpage-HoldsUpdatedAt.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_roles_manpage-HoldsUpdatedAt.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_roles_manpage-HoldsUpdatedAt.adoc
index a9558d1..e63c4ac 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_roles_manpage-HoldsUpdatedAt.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_roles_manpage-HoldsUpdatedAt.adoc
@@ -39,7 +39,6 @@ public class Customer {
public java.sql.Timestamp getVersionSequence() {
return (java.sql.Timestamp) JDOHelper.getVersion(this);
}
- }
}
----
http://git-wip-us.apache.org/repos/asf/isis/blob/48102a0d/adocs/documentation/src/main/asciidoc/guides/_rg_classes_uievent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_uievent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_uievent.adoc
new file mode 100644
index 0000000..0c5f927
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_uievent.adoc
@@ -0,0 +1,62 @@
+[[_rg_classes_uievent]]
+= UI Event Classes (`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/
+
+
+This section catalogues the various UI event classes defined by Apache Isis.
+
+These events are broadcast on the xref:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`]. The domain
+events are broadcast as a result of being specified in the xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_titleUiEvent[`@DomainObjectLayout#titleUiEvent()`], xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_iconUiEvent[`@DomainObjectLayout#iconUiEvent()`] or xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout_cssClassUiEvent[`@DomainObjectLayout#cssClassUiEvent()`] attributes.
+
+They are listed in the table below.
+
+.UI Event Classes
+[cols="2,4a,1,1", options="header"]
+|===
+
+|API
+|Maven Module +
+Impl'n (g: a:)
+|Implementation
+|Notes
+
+
+|xref:rg.adoc#_rg_classes_uievent_manpage-TitleUiEvent[`o.a.i.applib.` +
+`TitleUiEvent`]
+|``o.a.i.core`` +
+``services.eventbus`` +
+``isis-core-applib``
+|(abstract class). +
+`TitleUiEvent.Default` is the concrete implementation used if no `@DomainObjectLayout#titleUiEvent` attribute is specified
+|Broadcast whenever there is a requirement to obtain a title for a domain object. Note that if the domain object defines its own xref:rg.adoc#_rg_methods_reserved_manpage-title[`title()`] supporting method, or has xref:rg.adoc#_rg_annotations_manpage-Title[`@Title`] annotation(s) on its properties, then these will take precedence.
+
+|xref:rg.adoc#_rg_classes_uievent_manpage-IconUiEvent[`o.a.i.applib.` +
+`IconUiEvent`]
+|``o.a.i.core`` +
+``services.eventbus`` +
+``isis-core-applib``
+|(abstract class). +
+`IconUiEvent.Default` is the concrete implementation used if no `@DomainObjectLayout#iconUiEvent` attribute is specified
+|Broadcast whenever there is a requirement to obtain an icon (or rather, the name of an icon) for a domain object. Note that if the domain object defines its own xref:rg.adoc#_rg_methods_reserved_manpage-iconName[`iconName()`] supporting method, or if it has the xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout#cssClassFa[`@DomainObjectLayout#cssClassFa()`] attribute, then these will take precedence.
+
+|xref:rg.adoc#_rg_classes_uievent_manpage-CssClassUiEvent[`o.a.i.applib.` +
+`CssClassUiEvent`]
+|``o.a.i.core`` +
+``services.eventbus`` +
+``isis-core-applib``
+|(abstract class). +
+`CssClassUiEvent.Default` is the concrete implementation used if no `@DomainObjectLayout#cssClassUiEvent` attribute is specified
+|Broadcast whenever there is a requirement to obtain a CSS class hint for a domain object. Note that if the domain object defines its own xref:rg.adoc#_rg_methods_reserved_manpage-cssClass[`cssClass()`] supporting method then this
+will take precedence.
+
+|===
+
+
+
+
+include::_rg_classes_uievent_manpage-TitleUiEvent.adoc[leveloffset=+1]
+include::_rg_classes_uievent_manpage-IconUiEvent.adoc[leveloffset=+1]
+include::_rg_classes_uievent_manpage-CssClassUiEvent.adoc[leveloffset=+1]
+
http://git-wip-us.apache.org/repos/asf/isis/blob/48102a0d/adocs/documentation/src/main/asciidoc/guides/_rg_classes_uievent_manpage-CssClassUiEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_uievent_manpage-CssClassUiEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_uievent_manpage-CssClassUiEvent.adoc
new file mode 100644
index 0000000..ca0987e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_uievent_manpage-CssClassUiEvent.adoc
@@ -0,0 +1,22 @@
+[[_rg_classes_uievent_manpage-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/
+
+
+This event class represents a request to obtain the a CSS class hint of a domain object. The class has a number of
+responsibilities:
+
+* capture the target object being interacted with
+
+* capture the CSS class, if any, as specified to one of the subscribers
+
+The class itself is instantiated automatically by the framework whenever interacting with a rendered object's action.
+
+
+[NOTE]
+====
+if the domain object defines its own xref:rg.adoc#_rg_methods_reserved_manpage-cssClass[`cssClass()`] supporting
+method then this will take precedence.
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/48102a0d/adocs/documentation/src/main/asciidoc/guides/_rg_classes_uievent_manpage-IconUiEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_uievent_manpage-IconUiEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_uievent_manpage-IconUiEvent.adoc
new file mode 100644
index 0000000..7fd97a6
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_uievent_manpage-IconUiEvent.adoc
@@ -0,0 +1,23 @@
+[[_rg_classes_uievent_manpage-IconUiEvent]]
+= `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/
+
+
+This event class represents a request to obtain the icon (or rather, name of icon) of a domain object. The class has a number of responsibilities:
+
+* capture the target object being interacted with
+
+* capture the icon (name), if any, as specified to one of the subscribers
+
+The class itself is instantiated automatically by the framework whenever interacting with a rendered object's action.
+
+
+[NOTE]
+====
+If the domain object defines its own xref:rg.adoc#_rg_methods_reserved_manpage-iconName[`iconName()`] supporting method,
+or if it has the
+xref:rg.adoc#_rg_annotations_manpage-DomainObjectLayout#cssClassFa[`@DomainObjectLayout#cssClassFa()`] attribute, then
+these will take precedence.
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/48102a0d/adocs/documentation/src/main/asciidoc/guides/_rg_classes_uievent_manpage-TitleUiEvent.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_uievent_manpage-TitleUiEvent.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_uievent_manpage-TitleUiEvent.adoc
new file mode 100644
index 0000000..2fd0bca
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_uievent_manpage-TitleUiEvent.adoc
@@ -0,0 +1,22 @@
+[[_rg_classes_uievent_manpage-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/
+
+
+This event class represents a request to obtain the title of a domain object. The class has a number of responsibilities:
+
+* capture the target object being interacted with
+
+* capture the title, if any, as specified to one of the subscribers
+
+The class itself is instantiated automatically by the framework whenever interacting with a rendered object's action.
+
+
+[NOTE]
+====
+If the domain object defines its own xref:rg.adoc#_rg_methods_reserved_manpage-title[`title()`] supporting method, or
+has xref:rg.adoc#_rg_annotations_manpage-Title[`@Title`] annotation(s) on its properties, then these will take
+precedence.
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/48102a0d/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi.adoc
index 76c89a6..554d883 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi.adoc
@@ -294,5 +294,6 @@ include::_rg_services-spi_manpage-PublishingService.adoc[leveloffset=+1]
include::_rg_services-spi_manpage-RepresentationService.adoc[leveloffset=+1]
include::_rg_services-spi_manpage-TranslationService.adoc[leveloffset=+1]
include::_rg_services-spi_manpage-TranslationsResolver.adoc[leveloffset=+1]
+include::_rg_services-spi_manpage-UrlEncodingService.adoc[leveloffset=+1]
include::_rg_services-spi_manpage-UserProfileService.adoc[leveloffset=+1]
include::_rg_services-spi_manpage-UserRegistrationService.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/48102a0d/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 1d21696..c7ef7ee 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
@@ -35,3 +35,11 @@ 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.
+
+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/48102a0d/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_domain-driven-design.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_domain-driven-design.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_domain-driven-design.adoc
index c2c0146..f3994c5 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_domain-driven-design.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_domain-driven-design.adoc
@@ -16,6 +16,7 @@ There are two central ideas at the heart of domain-driven design.
Let's look at each in turn.
+[[_ug_core-concepts_philosophy_domain-driven-design_ubiquitous-language]]
== Ubiquitous Language
It's no secret that the IT industry is plagued by project failures. Too often systems take longer than intended to implement, and when finally implemented, they don't address the real requirements anyway.
http://git-wip-us.apache.org/repos/asf/isis/blob/48102a0d/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos.adoc
index 823e24b..3ea387f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos.adoc
@@ -17,5 +17,6 @@ include::_ug_how-tos_business-rules.adoc[leveloffset=+1]
include::_ug_how-tos_derived-members.adoc[leveloffset=+1]
include::_ug_how-tos_drop-downs-and-defaults.adoc[leveloffset=+1]
include::_ug_how-tos_persisted-title.adoc[leveloffset=+1]
-include::_ug_how-tos_replacing-default-service-implementations.adoc[leveloffset=+1]
+include::_ug_how-tos_bulk-actions.adoc[leveloffset=+1]
+
http://git-wip-us.apache.org/repos/asf/isis/blob/48102a0d/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_bulk-actions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_bulk-actions.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_bulk-actions.adoc
new file mode 100644
index 0000000..a03cba7
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_bulk-actions.adoc
@@ -0,0 +1,8 @@
+[[_ug_how-tos_bulk-actions]]
+= Bulk Actions
+: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: TODO - xref:rg.adoc#_rg_annotations_manpage-Action_invokeOn[`@Action#invokeOn()`]
+
http://git-wip-us.apache.org/repos/asf/isis/blob/48102a0d/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships.adoc
index cbb9135..f94cfab 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_entity-relationships_managed-1-to-m-bidirectional-relationships.adoc
@@ -40,9 +40,10 @@ Moreover, when maintaining a bidirectional 1-n relationship that is automaticall
[WARNING]
====
-If you don't do this then you may (as of Apache Isis 1.4.1) hit an NullPointerException. This may be a bug in DataNucleus, we are not completely sure, but the above idiom seems to fix the issue.
+If you don't do this then you may hit a `NullPointerException`. The above idiom fixes the issue.
-For more information, see http://isis.markmail.org/thread/ipu2lzqqikqdglox[this thread] on the Apache Isis users mailing list, including this http://markmail.org/message/hblptpw675mlw723[message] with the above recommendation.
+For more information, see http://isis.markmail.org/thread/ipu2lzqqikqdglox[this thread] on the Apache Isis users
+mailing list, including this http://markmail.org/message/hblptpw675mlw723[message] with the above recommendation.
====
http://git-wip-us.apache.org/repos/asf/isis/blob/48102a0d/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_replacing-default-service-implementations.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_replacing-default-service-implementations.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_replacing-default-service-implementations.adoc
deleted file mode 100644
index 1acde98..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_how-tos_replacing-default-service-implementations.adoc
+++ /dev/null
@@ -1,64 +0,0 @@
-[[_ug_how-tos_replacing-default-service-implementations]]
-= Replacing 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:rg.adoc#_rg_services-api[API 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:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] attribute, specifying a low number (typically `"1"`).
-
-For example, suppose you wanted to provide your own implementation of xref:rg.adoc#_rg_services-api_manpage-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/48102a0d/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced.adoc
index 4b61cb2..1f4264d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced.adoc
@@ -11,14 +11,13 @@ This chapter pulls together a number of more advanced techniques that we've disc
include::_ug_more-advanced_decoupling.adoc[leveloffset=+1]
include::_ug_more-advanced_overriding-jdo-annotations.adoc[leveloffset=+1]
-include::_ug_more-advanced_bulk-actions.adoc[leveloffset=+1]
include::_ug_more-advanced_view-models.adoc[leveloffset=+1]
include::_ug_more-advanced_mapping-rdbms-views.adoc[leveloffset=+1]
include::_ug_more-advanced_transactions-and-errors.adoc[leveloffset=+1]
include::_ug_more-advanced_i18n.adoc[leveloffset=+1]
include::_ug_more-advanced_multi-tenancy.adoc[leveloffset=+1]
include::_ug_more-advanced_persistence-lifecycle.adoc[leveloffset=+1]
-include::_ug_more-advanced_tips-n-tricks.adoc[leveloffset=+1]
+include::_ug_more-advanced_replacing-default-service-implementations.adoc[leveloffset=+1]include::_ug_more-advanced_tips-n-tricks.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/48102a0d/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_bulk-actions.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_bulk-actions.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_bulk-actions.adoc
deleted file mode 100644
index 4ea1738..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_bulk-actions.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-[[_ug_more-advanced_bulk-actions]]
-= Bulk Actions
-: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: TODO - xref:rg.adoc#_rg_annotations_manpage-Action_invokeOn[`@Action#invokeOn()`]
-
http://git-wip-us.apache.org/repos/asf/isis/blob/48102a0d/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_replacing-default-service-implementations.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_replacing-default-service-implementations.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_replacing-default-service-implementations.adoc
new file mode 100644
index 0000000..b99abae
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_more-advanced_replacing-default-service-implementations.adoc
@@ -0,0 +1,64 @@
+[[_ug_more-advanced_replacing-default-service-implementations]]
+= Replacing 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:rg.adoc#_rg_services-api[API 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:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] attribute, specifying a low number (typically `"1"`).
+
+For example, suppose you wanted to provide your own implementation of xref:rg.adoc#_rg_services-api_manpage-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/48102a0d/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 50272fd..bbf5f64 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
@@ -4,19 +4,405 @@
:_basedir: ../
:_imagesdir: images/
-NOTE: TODO - xref:rg.adoc#_rg_annotations_manpage-ViewModel[`@ViewModel`], xref:rg.adoc#_rg_classes_super_manpage-AbstractViewModel[`AbstractViewModel`], xref:rg.adoc#_rg_annotations_manpage-DomainObject_nature[`@DomainObject#nature()`]
+View models are a type of domain objects (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.
-Nature of view models
+In this topic we'll explore those use cases, and learn the programming model and conventions to use view models in your application.
-* inmemory-entity
-* external_entity
-* application layer
-Consumers of view models
-* within the Wicket viewer
-* within the REST viewer, as an external client consuming a stable API
+[[_ug_more-advanced_view-models_use-cases]]
+== Use Cases
-An alternative to using view models is to map the domain object using the xref:rg.adoc#_rg_services-spi_manpage-ContentMappingService[`ContentMappingService`].
+When developing an Apache Isis application you will most likely start off with the persistent domain entities:
+`Customer`, `Order`, `Product`, and so on. For some applications this may well suffice. However, if the application
+needs to integrate with other systems, or if the application needs to support reasonably complex business processes, then you may need to look beyond just domain entities. This section explores these use cases.
+=== Externally-managed entities
+
+Sometimes the entities that make up your application are persisted not in the local JDO/DataNucleus database
+but reside in some other system, for example accessible only through a SOAP web service. Logically that data
+might still be considered a domain entity and we might want to associate behaviour with it, however it cannot be
+modelled as a domain entity if only because JDO/DataNucleus doesn't know about the entity nor how to retrieve or
+update it.
+
+There are a couple of ways around this: we could either replicate the data somehow from the external system into the
+ Isis-managed database (in which case it is once again just another domain entity), or we could set up a stub/proxy for
+ the externally managed entity. This proxy would hold the reference to the externally-managed domain entity (eg an
+ external id), as well as the "smarts" to know how to interact with that entity (by making SOAP web service calls etc).
+
+The stub/proxy is a type of view model: a view - if you like - onto the domain entity managed by the external system.
+
+[NOTE]
+====
+DataNucleus does in fact define its own link:http://www.datanucleus.org/documentation/extensions/store_manager.html[Store Manager] extension point, so an alternative architecture would be to implement this interface such that DataNucleus
+could make the calls to the external system; these externally-persisted domain entities would therefore be modelled as regular `@PersistenceCapable` entities after all. For entities not persisted externally the implementation would delegate down to the default RDBMS-specific `StoreManager` provided by DataNucleus itself.
+
+An implementation that supported only reading from an external entity ought to be comparatively straight-forward, but
+implementing one that also supported updating external entities would need to carefully consider error conditions if the
+external system is unavailable; distributed transactions are most likely difficult/impossible to implement (and not
+desirable in any case).
+====
+
+
+=== In-memory entities
+
+As a variation on the above, sometimes there are domain objects that are, conceptually at least entities, but whose
+state is not actually persisted anywhere, merely held in-memory (eg in a hash).
+
+A simple example might be read-only configuration data that is read from a config file (eg log4j appender
+definitions) but thereafter is presented in the UI just like any other entity.
+
+
+=== Application-layer view models
+
+Domain entities (whether locally persisted using JDO/DataNucleus or managed externally) are the bread-and-butter of Apache Isis applications: the focus after all, should be on the business domain concepts and ensuring that they are
+solid. Generally those domain entities will make sense to the business domain experts: they form the _ubiquitous language_ of the domain. These domain entities are part of the domain layer.
+
+That said, it may not always be practical to expect end-users of the application to interact solely with those domain
+entities. For example, it may be useful to show a dashboard of the most significant data in the system to a user,
+often pulling in and aggregating information from multiple points of the app. Obtaining this information by hand (by
+ querying the respective services/repositories) would be tedious and slow; far better to have a dashboard do the job for
+ the end user.
+
+A dashboard object is a model of the most relevant state to the end-user, in other words it is (quite literally) a view
+ model. It is not a persisted entity, instead it belongs to the application layer.
+
+A view model need not merely aggregate data; it could also provide actions of its own. Most likely these actions will
+be queries and will always ultimately just delegate down to the appropriate domain-layer service/repository. But in
+some cases such view model actions might also modify state of underlying domain entities.
+
+Another common use for view models is to help co-ordinate complex business processes; for example to perform a
+quarterly invoicing run, or to upload annual interest rates from an Excel spreadsheet. In these cases the view model
+might have some state of its own, but in most cases that state does not need to be persisted per se.
+
+.Desire Lines
+****
+One way to think of application view models is as modelling the "desire line": the commonly-trod path
+that end-users must follow to get from point A to point B as quickly as possible.
+
+To explain: there are link:http://ask.metafilter.com/62599/Where-the-sidewalk-ends[documented]
+link:https://sivers.org/walkways[examples]
+link:http://www.softpanorama.org/People/Wall/larry_wall_articles_and_interviews.shtml[that] architects of university
+campus will only add in paths some while after the campus buildings are complete: let the pedestrians figure out the
+routes they want to take. The name we like best for this idea is "desire lines", though it has also been called
+a "desire path", "paving the path" or "paving the sidewalk".
+
+What that means is you should add view models _after_ having built up the domain layer, rather than before. These view
+models pave that commonly-trod path, automating the steps that the end-user would otherwise have to do by hand.
+
+It takes a little practice though, because even when building the domain layer "first", you should still bear in mind
+what the use cases are that those domain entities are trying to support. You certainly _shouldn't_ try to build out a
+domain layer that could support every conceivable use case before starting to think about view models.
+
+Instead, you should iterate. Identify the use case/story/end-user objective that you will deliver value to the
+business. Then build out the minimum domain entities to support that use case (refining the xref:ug.adoc#_ug_core-concepts_philosophy_domain-driven-design_ubiquitous-language[ubiquitous language] as you
+go). Then, identify if there any view models that could be introduced which would simplify the end-user interactions
+with the system (perhaps automating several related use cases together).
+****
+
+=== DTOs (`1.11.0-SNAPSHOT`)
+
+DTOs (data transfer objects) are simple classes that (according to link:https://en.wikipedia.org/wiki/Data_transfer_object[wikipedia]) "carries data between processes".
+
+If those two processes are parts of the same overall application (the same team builds and deploys both server and
+client) then there's generally no need to define a DTO; just access the entities using Apache Isis'
+xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer].
+
+On the other hand, if the client consuming the DTO is a different application -- by which we mean developed/deployed by
+a different (possible third-party) team -- then the DTOs act as a formal contract between the provider and the consumer.
+In such cases, exposing domain entities over xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects] would be
+"A Bad Thing"(TM) because the consumer would in effect have access to implementation details that could then not be
+easily changed by the producer.
+
+Instead, a view model can be defined to act as a DTO. To put this formal contract onto a solid footing, this view
+model can (as of `1.11.0-SNAPSHOT`) simply be defined as a JAXB-annotated entity; this allows the consumer to obtain
+the DTO in XML format along with a corresponding XSD schema describing the structure of that XML. These XML
+representations can be surfaced by the xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer] (by implementing
+the xref:rg.adoc#_rg_services-spi_manpage-ContentMappingService[`ContentMappingService`]); the XSD can be obtained
+using the xref:rg.adoc#_rg_services-api_manpage-JaxbService[`JaxbService`]. Using the formalism of XML also allows
+DTOs to be carefully and properly versioned using XML namespaces.
+
+[TIP]
+====
+If the view model DTO implements the xref:rg.adoc#_rg_classes_mixins_Dto[`Dto`] marker interface, then the framework
+will also provide the ability to download the XML or its XSD directly from the UI.
+====
+
+In case it's not clear, these DTOs are still usable as "regular" view models; they will render in the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] just like any other. Indeed (as the xref:ug.adoc#_ug_more-advanced_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 view model alternatives.
+
+
+=== ESB Subscribers
+
+One important variation of the DTO use case concerns subscribers on an enterprise event bus such as
+link:http://camel.apache.org[Apache Camel(TM)] and similar.
+
+A xref:rg.adoc#_rg_services-spi_manpage-PublishingService[`PublishingService`] implementation (eg that provided by
+(non-ASF) http://github.com/isisaddons/isis-module-publishmq[Isis addons' publishmq] module) can publish XML events
+onto a message queue, typically representing action invocations within the originating Isis application. The ESB
+(Apache Camel) then dispatches this event to all interested subscribers. These subscribers represent external systems
+in the enterprise, managed by other teams, and so act as the third-party consumers of the data.
+
+Rather than try to anticipate their requirements and push the data that these subscribers might need into the original
+XML event (a hopeless task), DTO objects can be defined to allow these consumers to call back to the publishing Isis
+application to obtain the data they need.
+
+
+[[_ug_more-advanced_view-models_programming-model]]
+== Programming Model
+
+So much for the theory; how should view models be implemented? Fundamentally all view models' state is serialized into
+a string memento; this memento is then held by the client (browser) in the form of a URL. As you might imagine, this
+URL can become quite long, but Apache Isis offers a mechanism (the xref:rg.adoc#_rg_services-spi_manpage-UrlEncodingService[`UrlEncodingService`]) if it exceeds the maximum length for a URL
+(2083 characters). Also, of course, this string memento must only contain characters that it is valid for use within
+a URL.
+
+While the underlying technique is the same irrespective of use case, the programming model provides various ways of
+defining a view model so that the original intent is not lost. They are:
+
+.View model programming model
+[cols="1a,4a,4a", options="header"]
+|===
+
+| Use case
+| Code
+| Description
+
+
+| External entity
+|[source,java]
+----
+@DomainObject(nature=Nature.EXTERNAL_ENTITY)
+public class CustomerRecordOnSAP { ... }
+----
+|Annotated with xref:rg.adoc#_rg_annotations_manpage-DomainObject_nature[`@DomainObject#nature()`] and a nature of `EXTERNAL_ENTITY`, with memento derived automatically from the properties of the domain object. Collections are ignored, as are any properties annotated as xref:rg.adoc#_rg_annotations_manpage-Property_notPersisted[not persisted].
+
+| In-memory entity
+|[source,java]
+----
+@DomainObject(nature=Nature.INMEMORY_ENTITY)
+public class Log4JAppender { ... }
+----
+|As preceding, but using a nature of `INMEMORY_ENTITY`.
+
+|Application view model
+|[source,java]
+----
+@DomainObject(nature=Nature.VIEW_MODEL)
+public class Dashboard { ... }
+----
+|As preceding, but using a nature of `VIEW_MODEL`.
+
+|Application view model
+|
+[source,java]
+----
+@ViewModel
+public class Dashboard { ... }
+----
+
+|Annotated with xref:rg.adoc#_rg_annotations_manpage-ViewModel[`@ViewModel`] annotation (effectively just an alias)' memento is as preceding: from "persisted" properties, collections ignored
+
+|Application view model
+|
+[source,java]
+----
+public class ExcelUploadManager implements ViewModel {
+ public String viewModelMemento() { ... }
+ public void viewModelInit(String memento) { ... }
+}
+|Implement xref: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.
+
+|DTO (`1.11.0-SNAPSHOT`)
+|
+[source,java]
+----
+@XmlRootElement("customer")
+public class CustomerDto { ... }
+----
+|Annotate using JAXB xref:rg.adoc#_rg_annotations_manpage-XmlRootElement[`@XmlRootElement`] annotation. Memento
+derived automatically by serializing the XML graph as implied by the JAXB annotations. Note that (unlike `@ViewModel`
+et al) this state _can_ include collections.
+|===
+
+
+
+[[_ug_more-advanced_view-models_jaxb]]
+== JAXB-annotated DTOs (`1.11.0-SNAPSHOT`)
+
+This section provides some recommended practices if using JAXB and `@XmlRootElement` to define domain models. The
+examples are taken from the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp].
+
+=== Use packages to version DTOs
+
+The whole point of using DTOs (in Apache Isis, at least) is to define a formal contact between two interoperating but
+independent applications. Since the only thing we can predicate about the future with any certainty is that it one or
+both of these applications will change, we should version DTOs from the get-go.
+
+With XML every element may be defined as belonging to a particular namespace; in JAXB this translates to Java packages.
+We therefore should place each DTO within its own package, and that package should include a version identifier.
+
+For example, the http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] defines this DTO (as a versioned
+representation of its underlying `ToDoItem` entity):
+
+[source,java]
+----
+@XmlRootElement(name = "toDoItemDto") // <1>
+@XmlType(
+ namespace = "http://viewmodels.app.todoapp/v1/todoitem", // <2>
+ propOrder = { // <3>
+ "description",
+ "category",
+ "subcategory",
+ "cost"
+ }
+)
+@DomainObjectLayout(
+ titleUiEvent = TitleUiEvent.Default.class // <4>
+)
+public class ToDoItemDto implements Dto {
+
+ @XmlElement(required = true)
+ @Getter @Setter // <5>
+ protected String description;
+
+ @XmlElement(required = true)
+ @Getter @Setter
+ protected String category;
+
+ @Getter @Setter
+ protected String subcategory;
+
+ @Getter @Setter
+ protected BigDecimal cost;
+}
+----
+<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
+<5> optional; JAXB metadata can specify such attributes as required/optional
+
+
+
+[source,java]
+----
+@javax.xml.bind.annotation.XmlSchema(
+ xmlns = {
+ @XmlNs(
+ namespaceURI = "http://isis.apache.org/schema/common",
+ 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;
+----
+
+
+
+This annotation therefore allows view models/DTOs to have references to persistent entities. It is a common
+
+
+
+[source,java]
+----
+package todoapp.app.viewmodels.todoitem.v2;
+
+import java.util.List;
+
+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;
+
+import com.google.common.collect.Lists;
+
+import org.apache.isis.applib.annotation.DomainObjectLayout;
+import org.apache.isis.applib.services.eventbus.TitleUiEvent;
+
+import lombok.Getter;
+import lombok.Setter;
+import todoapp.dom.todoitem.ToDoItem;
+
+@XmlAccessorType(XmlAccessType.FIELD)
+@XmlType(
+ namespace = "http://viewmodels.app.todoapp/v2/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();
+
+}
+----
+
+
+
+[source,java]
+----
+@javax.xml.bind.annotation.XmlSchema(
+ xmlns = {
+ @XmlNs(
+ namespaceURI = "http://isis.apache.org/schema/common",
+ prefix = "common"
+ ),
+ @XmlNs(
+ namespaceURI = "http://viewmodels.app.todoapp/v1/todoitem",
+ prefix = "todoitem-v1"
+ ),
+ @XmlNs(
+ namespaceURI = "http://viewmodels.app.todoapp/v2/todoitem",
+ prefix = "todoitem-v2"
+ )
+ },
+ 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;
+----
+
+
+
+
+[source,java]
+----
+@XmlJavaTypeAdapter(PersistentEntityAdapter.class)
+public class ToDoItem ... {
+ ...
+}
+----
+
+
+
+
+
+
+== `UrlEncodingService`
+
+NOTE: TODO
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/48102a0d/adocs/documentation/src/main/asciidoc/guides/cg.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/cg.adoc b/adocs/documentation/src/main/asciidoc/guides/cg.adoc
index 0821616..233d347 100644
--- a/adocs/documentation/src/main/asciidoc/guides/cg.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/cg.adoc
@@ -17,7 +17,7 @@ This contributors' guide has three related audiences:
* committers of Apache Isis itself who want guidance on release process, publishing documents and other related procedures.
-The developer' guide is _not_ intended as a reference manual; for that see the *xref:rg.adoc#_rg[Reference Guide]*. This guide also doesn't describe how to actually build an Apache Isis application; for that see the *xref:ug.adoc#_ug[Users' Guide]*.
+This contributors' guide is _not_ intended as a reference manual; for that see the *xref:rg.adoc#_rg[Reference Guide]*. This guide also doesn't describe how to actually build an Apache Isis application; for that see the *xref:ug.adoc#_ug[Users' Guide]*.
include::_cg_ide.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/48102a0d/adocs/documentation/src/main/asciidoc/guides/ug.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ug.adoc b/adocs/documentation/src/main/asciidoc/guides/ug.adoc
index b597529..155b507 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ug.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ug.adoc
@@ -15,7 +15,7 @@ It goes on to discuss the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer], both fr
Later chapters discuss essential topics such as xref:ug.adoc#_ug_testing[testing] and how to xref:ug.adoc#_ug_deployment[deploy] your app, and discuss other ways in which you can xref:ug.adoc#_ug_extending[extend] or adapt the framework itself to your particular needs.
-The users' guide is _not_ intended as a reference manual; for that see the *xref:rg.adoc#_rg[Reference Guide]*. The users' guide also doesn't explain how to setup your development environment; for that see the *xref:cg.adoc#_cg[Contributors' Guide]*.
+This users' guide is _not_ intended as a reference manual; for that see the *xref:rg.adoc#_rg[Reference Guide]*. This guide also doesn't explain how to setup your development environment; for that see the *xref:cg.adoc#_cg[Contributors' Guide]*.
http://git-wip-us.apache.org/repos/asf/isis/blob/48102a0d/adocs/documentation/src/main/asciidoc/index.html
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/index.html b/adocs/documentation/src/main/asciidoc/index.html
index 04ab1be..b720f4f 100644
--- a/adocs/documentation/src/main/asciidoc/index.html
+++ b/adocs/documentation/src/main/asciidoc/index.html
@@ -710,7 +710,7 @@ mvn archetype:generate \
</div>
</div>
<div>
- <p align="center"><i>hover to stop scrolling</i></p>
+ <p align="center"><i>hover to stop scrolling; click arrows to resume</i></p>
</div>
</div>
<div class="large-1 medium-1 columns">
http://git-wip-us.apache.org/repos/asf/isis/blob/48102a0d/adocs/template/document.html.erb
----------------------------------------------------------------------
diff --git a/adocs/template/document.html.erb b/adocs/template/document.html.erb
index 86aa8cc..b9685f9 100644
--- a/adocs/template/document.html.erb
+++ b/adocs/template/document.html.erb
@@ -46,6 +46,20 @@
<![endif]-->
+
+ <style type="text/css">
+ pre code {
+ background-color: inherit;
+ border-style: none;
+ }
+
+ pre code > span:first-child {
+ margin-left: -5px;
+ }
+
+ <style>
+
+ <!--
<style type="text/css">
<%= ::Asciidoctor::Stylesheets.instance.coderay_stylesheet_data %>
@@ -76,6 +90,7 @@
}
<style>
+ -->
<style>
.github-fork-ribbon-wrapper.right {
@@ -154,6 +169,22 @@
margin-top: 30px;
}
+ div#doc-content a.header-link {
+ margin-left: -90px;
+ }
+
+ div#doc-content div.sect1 h2 {
+ margin-left: -60px;
+ }
+
+ div#doc-content div.sect3 h4 {
+ margin-left: -60px;
+ }
+
+ div#doc-content div.sect2 h3 {
+ margin-left: -60px;
+ }
+
div.documentation-page table.frame-all {
border-left: none;
border-right: none;
http://git-wip-us.apache.org/repos/asf/isis/blob/48102a0d/core/applib/src/main/java/org/apache/isis/applib/annotation/DomainObjectLayout.java
----------------------------------------------------------------------
diff --git a/core/applib/src/main/java/org/apache/isis/applib/annotation/DomainObjectLayout.java b/core/applib/src/main/java/org/apache/isis/applib/annotation/DomainObjectLayout.java
index d65dc2f..0499cf3 100644
--- a/core/applib/src/main/java/org/apache/isis/applib/annotation/DomainObjectLayout.java
+++ b/core/applib/src/main/java/org/apache/isis/applib/annotation/DomainObjectLayout.java
@@ -45,7 +45,7 @@ public @interface DomainObjectLayout {
* This subclass must provide a no-arg constructor; the fields are set reflectively.
* </p>
*/
- Class<? extends TitleUiEvent<?>> titleUiEvent() default TitleUiEvent.Noop.class;
+ Class<? extends TitleUiEvent<?>> titleUiEvent() default TitleUiEvent.Default.class;
// //////////////////////////////////////
@@ -56,7 +56,7 @@ public @interface DomainObjectLayout {
* This subclass must provide a no-arg constructor; the fields are set reflectively.
* </p>
*/
- Class<? extends IconUiEvent<?>> iconUiEvent() default IconUiEvent.Noop.class;
+ Class<? extends IconUiEvent<?>> iconUiEvent() default IconUiEvent.Default.class;
// //////////////////////////////////////
@@ -67,7 +67,7 @@ public @interface DomainObjectLayout {
* This subclass must provide a no-arg constructor; the fields are set reflectively.
* </p>
*/
- Class<? extends CssClassUiEvent<?>> cssClassUiEvent() default CssClassUiEvent.Noop.class;
+ Class<? extends CssClassUiEvent<?>> cssClassUiEvent() default CssClassUiEvent.Default.class;
/**
* Indicates the css class that a domain class (type) should have.
http://git-wip-us.apache.org/repos/asf/isis/blob/48102a0d/core/applib/src/main/java/org/apache/isis/applib/annotation/Nature.java
----------------------------------------------------------------------
diff --git a/core/applib/src/main/java/org/apache/isis/applib/annotation/Nature.java b/core/applib/src/main/java/org/apache/isis/applib/annotation/Nature.java
index e941e2a..4ffa704 100644
--- a/core/applib/src/main/java/org/apache/isis/applib/annotation/Nature.java
+++ b/core/applib/src/main/java/org/apache/isis/applib/annotation/Nature.java
@@ -18,6 +18,8 @@
*/
package org.apache.isis.applib.annotation;
+import javax.xml.bind.annotation.XmlRootElement;
+
/**
* The different sorts of domain objects recognized by Isis.
*
@@ -30,7 +32,8 @@ public enum Nature {
/**
* The default; allows the programmer to combine <tt>@DomainObject</tt> annotation with the
- * <tt>@ViewModel</tt> annotation or implementing the <tt>ViewModel</tt> interface.
+ * {@link ViewModel} annotation, or the {@link XmlRootElement} annotation, or by implementing the
+ * {@link org.apache.isis.applib.ViewModel} interface.
*/
NOT_SPECIFIED,
@@ -52,8 +55,13 @@ public enum Nature {
* considered to be part of the domain model layer.
*
* <p>
- * The identity of an external entity is determined solely by the state of entity's properties (that have
- * not been set to be ignored using {@link org.apache.isis.applib.annotation.Property#notPersisted()}).
+ * The identity of an external entity is determined solely by the state of object's properties (that have not
+ * been set to be ignored using {@link org.apache.isis.applib.annotation.Property#notPersisted()}).
+ * </p>
+ *
+ * <p>
+ * Note that collections are ignored; if their state is required to fully identify the view model, use
+ * {@link XmlRootElement} annotation instead.
* </p>
*/
EXTERNAL_ENTITY,
@@ -63,7 +71,13 @@ public enum Nature {
*
* <p>
* As for a {@link #EXTERNAL_ENTITY}, the identity of a synthetic entity is determined solely by the state of
- * entity's properties (that have not been set to be ignored using {@link org.apache.isis.applib.annotation.Property#notPersisted()}).
+ * object's properties (that have not been set to be ignored using
+ * {@link org.apache.isis.applib.annotation.Property#notPersisted()}).
+ * </p>
+ *
+ * <p>
+ * Note that collections are ignored; if their state is required to fully identify the view model, use
+ * {@link XmlRootElement} annotation instead.
* </p>
*/
INMEMORY_ENTITY,
@@ -74,6 +88,14 @@ public enum Nature {
* <p>
* The identity of a view model is determined solely by the state of object's properties (that have
* not been set to be ignored using {@link org.apache.isis.applib.annotation.Property#notPersisted()}).
+ * Using this nature should be considered exactly equivalent to annotating with {@link ViewModel}.
+ * </p>
+ *
+ * <p>
+ * Note that collections are ignored; if their state is required to fully identify the view model, define the
+ * view model using the JAXB {@link XmlRootElement} annotation instead (where the object's state is serialized
+ * to an arbitrarily deep graph of data, with references to persistent entities transparently resolved to
+ * <code><oid-dto></code> elements).
* </p>
*
* @see ViewModel
http://git-wip-us.apache.org/repos/asf/isis/blob/48102a0d/core/applib/src/main/java/org/apache/isis/applib/annotation/ViewModel.java
----------------------------------------------------------------------
diff --git a/core/applib/src/main/java/org/apache/isis/applib/annotation/ViewModel.java b/core/applib/src/main/java/org/apache/isis/applib/annotation/ViewModel.java
index 6b18150..f27c4df 100644
--- a/core/applib/src/main/java/org/apache/isis/applib/annotation/ViewModel.java
+++ b/core/applib/src/main/java/org/apache/isis/applib/annotation/ViewModel.java
@@ -21,6 +21,28 @@ package org.apache.isis.applib.annotation;
import java.lang.annotation.*;
+import javax.xml.bind.annotation.XmlRootElement;
+
+/**
+ * An object that is conceptually part of the application layer, and which surfaces behaviour and/or state that
+ * is aggregate of one or more domain entity.
+ *
+ * <p>
+ * The identity of a view model is determined solely by the state of object's properties (that have
+ * not been set to be ignored using {@link org.apache.isis.applib.annotation.Property#notPersisted()}).
+ * Using this nature should be considered exactly equivalent to annotating with {@link DomainObject#nature()} with
+ * a nature of {@link Nature#VIEW_MODEL}.
+ * </p>
+ *
+ * <p>
+ * Note that collections are ignored; if their state is required to fully identify the view model, define the view
+ * model using the JAXB {@link XmlRootElement} annotation instead (where the object's state is serialized
+ * to an arbitrarily deep graph of data, with references to persistent entities transparently resolved to
+ * <code><oid-dto></code> elements).
+ * </p>
+ *
+ * @see ViewModel
+ */
@Inherited
@Target({ ElementType.TYPE })
@Retention(RetentionPolicy.RUNTIME)
http://git-wip-us.apache.org/repos/asf/isis/blob/48102a0d/core/applib/src/main/java/org/apache/isis/applib/services/eventbus/ActionDomainEvent.java
----------------------------------------------------------------------
diff --git a/core/applib/src/main/java/org/apache/isis/applib/services/eventbus/ActionDomainEvent.java b/core/applib/src/main/java/org/apache/isis/applib/services/eventbus/ActionDomainEvent.java
index 93ca053..2b2b81f 100644
--- a/core/applib/src/main/java/org/apache/isis/applib/services/eventbus/ActionDomainEvent.java
+++ b/core/applib/src/main/java/org/apache/isis/applib/services/eventbus/ActionDomainEvent.java
@@ -32,14 +32,16 @@ public abstract class ActionDomainEvent<S> extends AbstractInteractionEvent<S> {
private static final long serialVersionUID = 1L;
//region > Default class
-
/**
- * The default for {@link org.apache.isis.applib.annotation.Action#domainEvent()} annotation attribute, will be
- * used as the event class to be posted if some other subclass wasn't specified (though setting to
- * {@link org.apache.isis.applib.services.eventbus.ActionDomainEvent.Noop} will disable).
+ * This class is the default for the
+ * {@link org.apache.isis.applib.annotation.Action#domainEvent()} annotation attribute. Whether this
+ * raises an event or not depends upon the "isis.services.eventbus.actionDomainEvent.postForDefault"
+ * configuration property.
*/
public static class Default extends ActionInteractionEvent<Object> {
private static final long serialVersionUID = 1L;
+ public Default(){}
+ @Deprecated
public Default(Object source, Identifier identifier, Object... arguments) {
super(source, identifier, arguments);
}
@@ -49,14 +51,26 @@ public abstract class ActionDomainEvent<S> extends AbstractInteractionEvent<S> {
//region > Noop class
/**
- * Disables event propogation if explicitly set as the value of
- * {@link org.apache.isis.applib.annotation.Action#domainEvent()} annotation attribute.
+ * Convenience class to use indicating that an event should <i>not</i> be posted (irrespective of the configuration
+ * property setting for the {@link Default} event.
*/
- public static class Noop extends ActionDomainEvent<Object> {
+ public static class Noop extends ActionInteractionEvent<Object> {
private static final long serialVersionUID = 1L;
}
//endregion
+ //region > Doop class
+
+ /**
+ * Convenience class meaning that an event <i>should</i> be posted (irrespective of the configuration
+ * property setting for the {@link Default} event..
+ */
+ public static class Doop extends ActionInteractionEvent<Object> {
+ private static final long serialVersionUID = 1L;
+ }
+ //endregion
+
+
//region > constructors
/**
http://git-wip-us.apache.org/repos/asf/isis/blob/48102a0d/core/applib/src/main/java/org/apache/isis/applib/services/eventbus/ActionInteractionEvent.java
----------------------------------------------------------------------
diff --git a/core/applib/src/main/java/org/apache/isis/applib/services/eventbus/ActionInteractionEvent.java b/core/applib/src/main/java/org/apache/isis/applib/services/eventbus/ActionInteractionEvent.java
index 7afb412..05d6621 100644
--- a/core/applib/src/main/java/org/apache/isis/applib/services/eventbus/ActionInteractionEvent.java
+++ b/core/applib/src/main/java/org/apache/isis/applib/services/eventbus/ActionInteractionEvent.java
@@ -37,6 +37,8 @@ public abstract class ActionInteractionEvent<S> extends ActionDomainEvent<S> {
@Deprecated
public static class Default extends ActionDomainEvent.Default {
private static final long serialVersionUID = 1L;
+ public Default() {}
+ @Deprecated
public Default(Object source, Identifier identifier, Object... arguments) {
super(source, identifier, arguments);
}
@@ -44,12 +46,17 @@ public abstract class ActionInteractionEvent<S> extends ActionDomainEvent<S> {
//endregion
//region > constructors
+
+ public ActionInteractionEvent(){}
+
+ @Deprecated
public ActionInteractionEvent(
final S source,
final Identifier identifier) {
super(source, identifier);
}
+ @Deprecated
public ActionInteractionEvent(
final S source,
final Identifier identifier,
@@ -57,6 +64,7 @@ public abstract class ActionInteractionEvent<S> extends ActionDomainEvent<S> {
super(source, identifier, arguments);
}
+ @Deprecated
public ActionInteractionEvent(
final S source,
final Identifier identifier,
http://git-wip-us.apache.org/repos/asf/isis/blob/48102a0d/core/applib/src/main/java/org/apache/isis/applib/services/eventbus/CollectionDomainEvent.java
----------------------------------------------------------------------
diff --git a/core/applib/src/main/java/org/apache/isis/applib/services/eventbus/CollectionDomainEvent.java b/core/applib/src/main/java/org/apache/isis/applib/services/eventbus/CollectionDomainEvent.java
index 2fef767..c431483 100644
--- a/core/applib/src/main/java/org/apache/isis/applib/services/eventbus/CollectionDomainEvent.java
+++ b/core/applib/src/main/java/org/apache/isis/applib/services/eventbus/CollectionDomainEvent.java
@@ -27,12 +27,15 @@ public abstract class CollectionDomainEvent<S,T> extends AbstractInteractionEven
//region > Default class
/**
- * The default for {@link org.apache.isis.applib.annotation.Collection#domainEvent()} annotation attribute, will be
- * used as the event class to be posted if some other subclass wasn't specified (though setting to
- * {@link org.apache.isis.applib.services.eventbus.CollectionDomainEvent.Noop} will disable).
+ * This class is the default for the
+ * {@link org.apache.isis.applib.annotation.Collection#domainEvent()} annotation attribute. Whether this
+ * raises an event or not depends upon the "isis.services.eventbus.collectionDomainEvent.postForDefault"
+ * configuration property.
*/
public static class Default extends CollectionInteractionEvent<Object, Object> {
private static final long serialVersionUID = 1L;
+ public Default(){}
+ @Deprecated
public Default(
final Object source,
final Identifier identifier,
@@ -46,14 +49,26 @@ public abstract class CollectionDomainEvent<S,T> extends AbstractInteractionEven
//region > Noop class
/**
- * Disables event propogation if explicitly set as the value of
- * {@link org.apache.isis.applib.annotation.Collection#domainEvent()} annotation attribute.
+ * Convenience class to use indicating that an event should <i>not</i> be posted (irrespective of the configuration
+ * property setting for the {@link Default} event.
*/
- public static class Noop extends CollectionDomainEvent<Object,Object> {
+ public static class Noop extends CollectionInteractionEvent<Object, Object> {
private static final long serialVersionUID = 1L;
}
//endregion
+ //region > Doop class
+
+ /**
+ * Convenience class meaning that an event <i>should</i> be posted (irrespective of the configuration
+ * property setting for the {@link Default} event..
+ */
+ public static class Doop extends CollectionInteractionEvent<Object, Object> {
+ private static final long serialVersionUID = 1L;
+ }
+ //endregion
+
+
//region > constructors
/**