You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@causeway.apache.org by da...@apache.org on 2023/05/30 06:24:29 UTC

[causeway] 03/03: CAUSEWAY-2485: polishes demo app descriptions

This is an automated email from the ASF dual-hosted git repository.

danhaywood pushed a commit to branch CAUSEWAY-2485
in repository https://gitbox.apache.org/repos/asf/causeway.git

commit 95b3e0a07397de13e17fca3d632352eeba3217e7
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Tue May 30 07:23:56 2023 +0100

    CAUSEWAY-2485: polishes demo app descriptions
---
 .../nature/DomainObjectNaturePage-description.adoc | 49 ++++++++++++++++------
 .../nature/DomainObjectNaturePage_entities.java    | 11 ++++-
 .../nature/DomainObjectNaturePage_viewModels.java  |  1 -
 .../DomainObjectNatureViewModel-description.adoc   |  1 -
 .../viewmodel/DomainObjectNatureViewModel.java     |  6 +++
 5 files changed, 52 insertions(+), 16 deletions(-)

diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/objects/DomainObject/nature/DomainObjectNaturePage-description.adoc b/examples/demo/domain/src/main/java/demoapp/dom/domain/objects/DomainObject/nature/DomainObjectNaturePage-description.adoc
index 3811bfca8f..c0f99f3046 100644
--- a/examples/demo/domain/src/main/java/demoapp/dom/domain/objects/DomainObject/nature/DomainObjectNaturePage-description.adoc
+++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/objects/DomainObject/nature/DomainObjectNaturePage-description.adoc
@@ -6,27 +6,40 @@ Domain classes fall into three broad categories:
 * domain entities, representing shared persistence state (eg `Customer`, `Order`, `Product` and so on)
 * link:https://causeway.apache.org/userguide/${CAUSEWAY_VERSION}/fun/overview.html#view-models[view models], which hold session-specific (temporary) state.
 View models can be used for a variety of use cases, such as a "manager" class to handle a complicated workflow (part of an "application layer"), or as an object to render as a simplified representation of an entity (part of the "presentation layer").
+The object you are looking at right now is a view model.
 
 Strictly speaking mixins are domain objects (with a `nature` of "MIXIN"), though they manifest as contributed domain members (properties, collections or actions) rather than as individual object instances in their own right.
 
-The object you are looking at right now is a view model.
-Its source code is:
 
+
+== How this demo works
+
+There are two collections on the left hand side, one of domain entities and the other of view models.
+The entities are obtained by querying a repository, while the view models are created on the fly, each wrapping a corresponding entity.
+
+In terms of code:
+
+* collection of entities:
++
 [source,java]
-.DomainObjectNaturePage.java
+.DomainObjectNaturePage_entities.java
 ----
-include::DomainObjectNaturePage.java[tags=class]
+include::DomainObjectNaturePage_entities.java[tags=class]
 ----
-<.> Specifies this is a JAXB element.
-This is actually enough for the framework to infer that this domain object is a view model.
++
+where `DomainObjectNatureEntity` (JPA version) is defined as:
++
+[source,java]
+.DomainObjectNaturePage_entities.java
+----
+include::entity/jpa/DomainObjectNatureEntityImpl.java[tags=class]
+----
+<.> The framework can infer the nature of the domain class from these annotations
 <.> Nevertheless, it's generally good practice to specify the nature explicitly.
 
 
-== How this demo works
-
-There are two collections on the left hand side, one of domain entities and the other of view models.
-The entities are obtained by querying a repository, while the view models are created on the fly, each wrapping a corresponding entity:
-
+* collection of view models:
++
 [source,java]
 .DomainObjectNaturePage_viewModels.java
 ----
@@ -34,5 +47,17 @@ include::DomainObjectNaturePage_viewModels.java[tags=class]
 ----
 <.> creates view model on the fly.
 
-Navigate through to these domain objects to inspect their source code; both the entity and view model explicitly indicates its `nature`.
++
+where `DomainObjectNatureEntity` is defined as:
++
+[source,java]
+.DomainObjectNaturePage_entities.java
+----
+include::viewmodel/DomainObjectNatureViewModel.java[tags=class]
+----
+<.> Specifies this is a JAXB element.
+This is actually enough for the framework to infer that this domain object is a view model.
+<.> Nevertheless, it's generally good practice to specify the nature explicitly.
+<.> Required to reference a persistent entity (or the entity class itself can be so annotated).
+
 
diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/objects/DomainObject/nature/DomainObjectNaturePage_entities.java b/examples/demo/domain/src/main/java/demoapp/dom/domain/objects/DomainObject/nature/DomainObjectNaturePage_entities.java
index c504bb7fd6..81d3f7f173 100644
--- a/examples/demo/domain/src/main/java/demoapp/dom/domain/objects/DomainObject/nature/DomainObjectNaturePage_entities.java
+++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/objects/DomainObject/nature/DomainObjectNaturePage_entities.java
@@ -11,16 +11,23 @@ import lombok.RequiredArgsConstructor;
 import demoapp.dom._infra.values.ValueHolderRepository;
 import demoapp.dom.domain.objects.DomainObject.nature.entity.DomainObjectNatureEntity;
 
+//tag::class[]
 @Collection()
 @RequiredArgsConstructor
 public class DomainObjectNaturePage_entities {
+    // ...
+//end::class[]
 
     @SuppressWarnings("unused")
     private final DomainObjectNaturePage page;
 
+//tag::class[]
     public List<? extends DomainObjectNatureEntity> coll() {
-        return objectRepository.all();
+        return entities.all();
     }
+//end::class[]
 
-    @Inject ValueHolderRepository<String, ? extends DomainObjectNatureEntity> objectRepository;
+    @Inject ValueHolderRepository<String, ? extends DomainObjectNatureEntity> entities;
+//tag::class[]
 }
+//end::class[]
diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/objects/DomainObject/nature/DomainObjectNaturePage_viewModels.java b/examples/demo/domain/src/main/java/demoapp/dom/domain/objects/DomainObject/nature/DomainObjectNaturePage_viewModels.java
index 72ad49162d..2ddaf3b5d1 100644
--- a/examples/demo/domain/src/main/java/demoapp/dom/domain/objects/DomainObject/nature/DomainObjectNaturePage_viewModels.java
+++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/objects/DomainObject/nature/DomainObjectNaturePage_viewModels.java
@@ -31,7 +31,6 @@ public class DomainObjectNaturePage_viewModels {
 //end::class[]
 
     @Inject ValueHolderRepository<String, ? extends DomainObjectNatureEntity> entities;
-
 //tag::class[]
 }
 //end::class[]
diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/objects/DomainObject/nature/viewmodel/DomainObjectNatureViewModel-description.adoc b/examples/demo/domain/src/main/java/demoapp/dom/domain/objects/DomainObject/nature/viewmodel/DomainObjectNatureViewModel-description.adoc
index 186cdc01cf..0a8b355573 100644
--- a/examples/demo/domain/src/main/java/demoapp/dom/domain/objects/DomainObject/nature/viewmodel/DomainObjectNatureViewModel-description.adoc
+++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/objects/DomainObject/nature/viewmodel/DomainObjectNatureViewModel-description.adoc
@@ -10,7 +10,6 @@ include::DomainObjectNatureViewModel.java[tags=class]
 <.> Specifies this is a JAXB element.
 This is actually enough for the framework to infer that this domain object is a view model.
 <.> Nevertheless, it's generally good practice to specify the nature explicitly.
-<.> Presentation logic that build on the behaviour of the underlying entity.
 <.> Required to reference a persistent entity (or the entity class itself can be so annotated).
 
 In many cases the framework is able to infer the nature of the domain object from annotations such as `@Entity` or `@PersistenceCapable` (for JPA or JDO entities), or from `@XmlElement` for JAXB-style view models.
diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/objects/DomainObject/nature/viewmodel/DomainObjectNatureViewModel.java b/examples/demo/domain/src/main/java/demoapp/dom/domain/objects/DomainObject/nature/viewmodel/DomainObjectNatureViewModel.java
index d212051d6e..da40f4994e 100644
--- a/examples/demo/domain/src/main/java/demoapp/dom/domain/objects/DomainObject/nature/viewmodel/DomainObjectNatureViewModel.java
+++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/objects/DomainObject/nature/viewmodel/DomainObjectNatureViewModel.java
@@ -56,6 +56,9 @@ public class DomainObjectNatureViewModel
         this.message = underlying.getName();
         this.underlying = underlying;
     }
+    // ...
+
+//end::class[]
 
     @ObjectSupport public String title() {                  // <.>
         return message != null ? message : titleService.titleOf(underlying);
@@ -66,12 +69,15 @@ public class DomainObjectNatureViewModel
     @XmlElement(required = false)
     private String message;
 
+//tag::class[]
     @Property
     @Getter @Setter
     @XmlElement
     @XmlJavaTypeAdapter(PersistentEntityAdapter.class)      // <.>
     private DomainObjectNatureEntity underlying;
 
+//end::class[]
     @Inject @XmlTransient TitleService titleService;
+//tag::class[]
 }
 //end::class[]