You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2017/09/16 17:18:43 UTC
[4/4] isis git commit: ISIS-1712: extra words around view models
ISIS-1712: extra words around view models
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/c412d34c
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/c412d34c
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/c412d34c
Branch: refs/heads/master
Commit: c412d34c1b75b4ceee1eb6c72b53dad93deffc82
Parents: d311075
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Sat Sep 16 18:14:47 2017 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Sat Sep 16 18:14:47 2017 +0100
----------------------------------------------------------------------
.../rgant/_rgant-DomainObject_nature.adoc | 10 +++++
.../asciidoc/guides/rgant/_rgant-ViewModel.adoc | 46 +++++++++++++++-----
2 files changed, 46 insertions(+), 10 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/c412d34c/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_nature.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_nature.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_nature.adoc
index 6b2e107..e40d8cd 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_nature.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-DomainObject_nature.adoc
@@ -64,3 +64,13 @@ Because this particular implementation was originally added to Apache Isis in su
The benefit of `nature()` is that it allows the developer to properly characterize the layer (domain vs application) that an entity lives, thus avoiding confusion as "view model" (the implementation technique) and "view model" (the application layer concept).
====
+
+[NOTE]
+====
+On the other hand, view models defined in this way do have some limitations; see xref:rgant.adoc#_rgant-ViewModel[`@ViewModel`] for further discussion.
+
+These limitations do _not_ apply to xref:../ugfun/ugfun.adoc#_ugfun_programming-model_view-models_jaxb[JAXB] view models.
+If you are using view models heavily, you may wish to restrict yourself to just the JAXB flavour.
+====
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/c412d34c/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModel.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModel.adoc b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModel.adoc
index d88185a..4f46d82 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModel.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgant/_rgant-ViewModel.adoc
@@ -6,35 +6,61 @@
-The `@ViewModel` annotation, applied to a class, is the simplest way to indicate that the class is a view model.
+The `@ViewModel` annotation, applied to a class, indicates that the class is a view model.
+It's a synonym for using `@DomainObject(nature=VIEW_MODEL)`.
-View models are not persisted to the database, instead their state is encoded within their identity (ultimately
-represented in the URL). As such, view models are immutable.
+View models are not persisted to the database, instead their state is encoded within their identity (ultimately represented in the URL).
For example:
[source,java]
----
@ViewModel
-public class MyViewModel {
- public MyViewModel() {} // <1>
+public class CustomerViewModel {
+ public CustomerViewModel() {}
+ public CustomerViewModel(String firstName, int lastName) {
+ this.firstName = firstName;
+ this.lastName = lastName;
+ }
...
}
----
-<1> must have a no-arg constructor for subsequent "recreation" by the framework.
-View models should be instantiated using their constructor, using xref:../rgsvc/rgsvc.adoc#_rgsvc_metadata-api_ServiceRegistry[`ServiceRegistry`] to inject dependencies into the view model as per xref:../ugbtb/ugbtb.adoc#_ugbtb_hints-and-tips_view-model-instantiation[View Model Instantiation].
+Although there are several ways to instantiate a view model, we recommend that they are instantiated using an N-arg constructor that initializes all relevant state.
+The xref:../rgsvc/rgsvc.adoc#_rgsvc_metadata-api_ServiceRegistry[`ServiceRegistry`] can then be used to inject dependencies into the view model.
+For example:
-The view model's memento will be derived from the value of the view model object's properties. Any xref:../rgant/rgant.adoc#_rgant-Property_notPersisted[`@Property#notPersisted()`] properties will be excluded from the memento, as will any xref:../rgant/rgant.adoc#_rgant-Programmatic[`@Programmatic`] properties. Properties that are merely xref:../rgant/rgant.adoc#_rgant-Property_hidden[hidden] _are_ included in the memento.
+[source,java]
+----
+Customer cust = ...
+CustomerViewModel vm = new CustomerViewModel(cust.getFirstName(),cust.getLastName());
+serviceRegistry.injectServicesInto(vm);
+----
+
+[TIP]
+====
+See this xref:../ugbtb/ugbtb.adoc#_ugbtb_hints-and-tips_view-model-instantiation[tip] for further discussion about instantiating view models.
+====
+
+View models must have a no-arg constructor; this is used internally by the framework for subsequent "recreation".
+
+The view model's memento will be derived from the value of the view model object's properties.
+Any xref:../rgant/rgant.adoc#_rgant-Property_notPersisted[`@Property#notPersisted()`] properties will be excluded from the memento, as will any xref:../rgant/rgant.adoc#_rgant-Programmatic[`@Programmatic`] properties.
+Properties that are merely xref:../rgant/rgant.adoc#_rgant-Property_hidden[hidden] _are_ included in the memento.
Only properties supported by the configured xref:../rgsvc/rgsvc.adoc#_rgsvc_integration-api_MementoService[`MementoService`] can be used. The default implementation supports all the value types and persisted entities.
-(As of 1.8.0) there are some limitations:
+View models, as defined by `@ViewModel` (or `@DomainObject(nature=VIEW_MODEL)` for that matter) have some limitations:
+
* view models cannot hold collections other view models (simple properties _are_ supported, though)
* collections (of either view models or entities) are ignored.
+* not every data type is supported,
+
+However, these limitations do _not_ apply to xref:../ugfun/ugfun.adoc#_ugfun_programming-model_view-models_jaxb[JAXB] view models.
+If you are using view models heavily, you may wish to restrict yourself to just the JAXB flavour.
-[WARNING]
+[NOTE]
====
The `@ViewModel` does not allow the objectType to be specified, meaning that it is incompatible with the metamodel validation check ennabled by the xref:../rgcfg/rgcfg.adoc#__rgcfg_configuring-core_metamodel-validation[`explicitObjectType`] configuration property.