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/04/21 06:27:59 UTC

[causeway] 02/03: CAUSEWAY-2485: reworks @Property#optionality

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 e2870c0e735e4ab0ac50c71037869514bbdeafa9
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Fri Apr 21 07:15:04 2023 +0100

    CAUSEWAY-2485: reworks @Property#optionality
---
 .../PropertyOptionalityPage-description.adoc       | 80 +++++++++++++++++-----
 .../optionality/PropertyOptionalityPage.java       | 11 ++-
 2 files changed, 69 insertions(+), 22 deletions(-)

diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/properties/Property/optionality/PropertyOptionalityPage-description.adoc b/examples/demo/domain/src/main/java/demoapp/dom/domain/properties/Property/optionality/PropertyOptionalityPage-description.adoc
index 6573bb41c1..3cd64bd04b 100644
--- a/examples/demo/domain/src/main/java/demoapp/dom/domain/properties/Property/optionality/PropertyOptionalityPage-description.adoc
+++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/properties/Property/optionality/PropertyOptionalityPage-description.adoc
@@ -1,7 +1,5 @@
 :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 ag [...]
 
-CAUTION: TODO: can also use `@Nullable`, for parameters at least.
-
 The `optionality` attribute specifies that a property or parameter is either optional or mandatory:
 
 * for properties, the attribute can be specified using the `@Property` annotation
@@ -10,36 +8,86 @@ The `optionality` attribute specifies that a property or parameter is either opt
 
 Without an annotation, the framework assumes that the property or parameter is mandatory, ie required.
 
-[IMPORTANT]
-====
-In addition to specifying optionality at the framework level, it's also important to specify optionality for properties at the persistence layer.
-
-* in the case of entities persisted using JDO/DataNucleus, this can be done using `@Column(allowsNull=...)`.
-* in the case of view models serialized using JAXB, this can be done using `@XmlElement(required=...)`.
+The framework also recognises `@org.springframework.lang.Nullable`, and with entities will recognise JPA's `@javax.persistence.Column#nullable` or JDO's `@javax.jdo.annotations.Column#allowsNull`.
 
-Also note that JDO and JAXB assume a property is not required by default, whereas Apache Causeway assumes that properties are required by default.
-====
 
+== How this demo works
 
-== Annotated
+This page defines three properties, all of which can be edited directly.
+Each also has a corresponding action to update them.
+The three properties are annotated with different optionalities, and the action parameters has a corresponding optionality.
 
-The `optionality` attribute can be specified explicitly using an annotation:
+When editing/modifying, you should be able to leave the two properties that are optional as blank, but the mandatory property will require a value to be set.
 
-* for properties, using `@Property#optionality()`:
+* the `optionalProperty` is annotated using `@Property#optionality()`:
 +
 [source,java,indent=0]
+.PropertyOptionalityPage.java
 ----
-include::PropertyOptionalityPage.java[tags=annotation]
+include::PropertyOptionalityPage.java[tags=optional]
 ----
 <.> explicitly specifies that the property is optional
++
+and its corresponding action's parameter uses `@Parameter#optionality()`:
++
+[source,java,indent=0]
+.PropertyOptionalityPage_updateOptional.java
+----
+include::PropertyOptionalityPage_updateOptional.java[tags=annotation]
+----
+<.> explicitly specifies that the parameter is optional
 
-* for parameters, using `@Parameter#optionality()`:
+
+* the `mandatoryProperty` is also annotated using `@Property#optionality()`:
 +
 [source,java,indent=0]
+.PropertyOptionalityPage.java
+----
+include::PropertyOptionalityPage.java[tags=mandatory]
+----
+<.> indicates that the property is mandatory
++
+and its corresponding action's parameter also uses `@Parameter#optionality()`:
++
+[source,java,indent=0]
+.PropertyOptionalityPage_updateMandatory.java
 ----
 include::PropertyOptionalityPage_updateMandatory.java[tags=annotation]
 ----
 <.> explicitly specifies that the parameter is optional
 
-The annotation could also be applied to a mixin, but would have little effect because mixin properties are always read-only.
+* the `nullableProperty` is also annotated using `@Nullable`:
++
+[source,java,indent=0]
+.PropertyOptionalityPage.java
+----
+include::PropertyOptionalityPage.java[tags=nullable]
+----
+<.> indicates that the property is optional
++
+and its corresponding action's parameter also uses `@Nullable`:
++
+[source,java,indent=0]
+.PropertyOptionalityPage_updateNullable.java
+----
+include::PropertyOptionalityPage_updateNullable.java[tags=annotation]
+----
+<.> explicitly specifies that the parameter is optional
+
+
+
+
+== Persistence Annotations
+
+In addition to specifying optionality at the framework level, it's also important to specify optionality for properties at the persistence layer.
+
+* for JPA, this is done using `@Column(nullable=...)`.
+* for JDO, this is done using `@Column(allowsNull=...)`.
+* for JAXB view models, this is done using `@XmlElement(required=...)`.
+
+If using JPA or JDO entities, the framework will infer the optionality semantics automatically.
+
+WARNING: link:https://issues.apache.org/jira/browse/CAUSEWAY-3437[CAUSEWAY-3437] is to extend the framework to infer optionality from these JPA/JDO/JAXB equivalents.
+
+Be aware that JPA, JDO and JAXB all assume a property is not required by default, whereas Apache Causeway assumes that properties are required by default.
 
diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/properties/Property/optionality/PropertyOptionalityPage.java b/examples/demo/domain/src/main/java/demoapp/dom/domain/properties/Property/optionality/PropertyOptionalityPage.java
index 8706fabdde..36b3fa8275 100644
--- a/examples/demo/domain/src/main/java/demoapp/dom/domain/properties/Property/optionality/PropertyOptionalityPage.java
+++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/properties/Property/optionality/PropertyOptionalityPage.java
@@ -45,11 +45,8 @@ import demoapp.dom._infra.asciidocdesc.HasAsciiDocDescription;
 @XmlRootElement(name = "root")
 @XmlType
 @XmlAccessorType(XmlAccessType.FIELD)
-@Named("demo.PropertyOptionalityVm")
-@DomainObject(
-        nature=Nature.VIEW_MODEL,
-        editing = Editing.ENABLED)
-public class PropertyOptionalityPage implements HasAsciiDocDescription {
+@Named("demo.PropertyOptionalityPage")
+@DomainObject(nature=Nature.VIEW_MODEL) public class PropertyOptionalityPage implements HasAsciiDocDescription {
     // ...
 //end::class[]
 
@@ -59,6 +56,7 @@ public class PropertyOptionalityPage implements HasAsciiDocDescription {
 
 //tag::optional[]
     @Property(
+        editing = Editing.ENABLED,
         optionality = Optionality.OPTIONAL              // <.>
     )
     @XmlElement(required = false)
@@ -68,6 +66,7 @@ public class PropertyOptionalityPage implements HasAsciiDocDescription {
 
 //tag::mandatory[]
     @Property(
+        editing = Editing.ENABLED,
         optionality = Optionality.MANDATORY             // <.>
     )
     @XmlElement(required = true)
@@ -77,7 +76,7 @@ public class PropertyOptionalityPage implements HasAsciiDocDescription {
 
 //tag::nullable[]
     // <.>
-    @Property()
+    @Property(editing = Editing.ENABLED)
     @org.springframework.lang.Nullable                  // <.>
     @XmlElement(required = false)
     @Getter @Setter