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/03/29 21:32:15 UTC
[causeway] branch master updated: CAUSEWAY-2485: completes @DomainObject#introspection
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/causeway.git
The following commit(s) were added to refs/heads/master by this push:
new 2a94e4106f CAUSEWAY-2485: completes @DomainObject#introspection
2a94e4106f is described below
commit 2a94e4106f5c71ab08564822a5f2d6e265331e69
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Wed Mar 29 22:31:21 2023 +0100
CAUSEWAY-2485: completes @DomainObject#introspection
---
.../objects/DomainObject/DomainObjectMenu.java | 4 +-
.../jpa/DomainObjectAliasedJpaEntities.java | 7 ++++
.../DomainObjectIntrospectionVm-description.adoc | 45 ++++++++++++++++++++--
.../DomainObjectIntrospectionVm.layout.xml | 2 +-
...ObjectIntrospectionAnnotOptJpa-description.adoc | 7 ++--
...bjectIntrospectionAnnotReqdJpa-description.adoc | 3 +-
.../jpa/DomainObjectIntrospectionAnnotReqdJpa.java | 3 +-
7 files changed, 57 insertions(+), 14 deletions(-)
diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/objects/DomainObject/DomainObjectMenu.java b/examples/demo/domain/src/main/java/demoapp/dom/domain/objects/DomainObject/DomainObjectMenu.java
index a93f2e5372..5e319e3f84 100644
--- a/examples/demo/domain/src/main/java/demoapp/dom/domain/objects/DomainObject/DomainObjectMenu.java
+++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/objects/DomainObject/DomainObjectMenu.java
@@ -82,13 +82,13 @@ public class DomainObjectMenu {
}
@Action(semantics = SemanticsOf.SAFE)
- @ActionLayout(cssClassFa="fa-triangle-person-digging", describedAs = "Control over introspection process")
+ @ActionLayout(cssClassFa="fa-pen-ruler", describedAs = "Control over introspection process")
public DomainObjectIntrospectionVm introspection(){
return new DomainObjectIntrospectionVm();
}
@Action(semantics = SemanticsOf.SAFE)
- @ActionLayout(cssClassFa="fa-tools", describedAs = "For mixins, override the default method name")
+ @ActionLayout(cssClassFa="fa-mortar-pestle", describedAs = "For mixins, override the default method name")
public DomainObjectMixinMethodVm mixinMethod() {
return new DomainObjectMixinMethodVm();
}
diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/objects/DomainObject/aliased/jpa/DomainObjectAliasedJpaEntities.java b/examples/demo/domain/src/main/java/demoapp/dom/domain/objects/DomainObject/aliased/jpa/DomainObjectAliasedJpaEntities.java
index cd3f92d90e..8c1c4dec72 100644
--- a/examples/demo/domain/src/main/java/demoapp/dom/domain/objects/DomainObject/aliased/jpa/DomainObjectAliasedJpaEntities.java
+++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/objects/DomainObject/aliased/jpa/DomainObjectAliasedJpaEntities.java
@@ -45,4 +45,11 @@ extends ValueHolderRepository<String, DomainObjectAliasedJpa> implements DomainO
public List<? extends DomainObjectAliased> allInstances() {
return all();
}
+
+ public List<? extends DomainObjectAliased> allMatches(final String s) {
+ return all();
+ }
+ public List<? extends DomainObjectAliased> allMatches() {
+ return all();
+ }
}
diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/objects/DomainObject/introspection/DomainObjectIntrospectionVm-description.adoc b/examples/demo/domain/src/main/java/demoapp/dom/domain/objects/DomainObject/introspection/DomainObjectIntrospectionVm-description.adoc
index e7b3fbc793..e4a83b9cdf 100644
--- a/examples/demo/domain/src/main/java/demoapp/dom/domain/objects/DomainObject/introspection/DomainObjectIntrospectionVm-description.adoc
+++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/objects/DomainObject/introspection/DomainObjectIntrospectionVm-description.adoc
@@ -1,8 +1,47 @@
: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 [...]
-The `introspection` attribute ...
+Introspection is the process by which the framework builds up its internal metamodel, using the Java reflection API to identify various methods and using the naming conventions of the programming model to infer actions, properties and collections.
-WARNING: TODO[CAUSEWAY-3312]
-Controls on a per class basis, how meta-model class introspection should process members, supporting methods and callback methods.
+The framework supports three different introspection policies, depending on your taste of whether the metamodel should be explicitly called out (but that means more 'boilerplate'), or should be inferred so far as possible.
+These introspection policies are:
+* "annotation optional"
++
+Introspect public methods only, recognising getters as either properties or collections, and other public methods as actions.
++
+Supporting methods (hide, disable, validate, choices, autoComplete) do not need to be annotated either.
+* "annotation required"
++
+Requires that getter methods representing properties or collections, and public methods representing actions are all explicitly annotated (with link:https://causeway.apache.org/refguide/2.0.0-SNAPSHOT/applib/index/annotation/Property.html[@Property], link:https://causeway.apache.org/refguide/2.0.0-SNAPSHOT/applib/index/annotation/Collection.html[@Collection] and link:https://causeway.apache.org/refguide/2.0.0-SNAPSHOT/applib/index/annotation/Action.html[@Action])
++
+Supporting methods (hide, disable, validate, choices, autoComplete) do not need to be annotated.
+
+* "encapsulation enabled"
++
+Requires that both the methods representing properties, collections an actions are annotated (with link:https://causeway.apache.org/refguide/2.0.0-SNAPSHOT/applib/index/annotation/Property.html[@Property], link:https://causeway.apache.org/refguide/2.0.0-SNAPSHOT/applib/index/annotation/Collection.html[@Collection] and link:https://causeway.apache.org/refguide/2.0.0-SNAPSHOT/applib/index/annotation/Action.html[@Action]), and _also_ that the supporting methods are annotated (with link:http [...]
++
+However, the methods can have _any_ visibility, including `private` visibility.
+This reduces the programmatic API of the domain object can so can help eliminate bugs.
+
+The default policy is set using a configuration property:
+
+[source,yaml]
+.application.yaml
+----
+causeway:
+ core:
+ meta-model:
+ introspector:
+ policy: annotation_optional <.>
+----
+<.> `annotation_optional` | `annotation_required` | `encapsulation_enabled`
+
+Normally there would be little reason to override this - just adopt the convention that best fits your style, and leave it at that.
+However, it the need arises then it can be overridden on a class by class basis using the link:https://causeway.apache.org/refguide/2.0.0-SNAPSHOT/applib/index/annotation/DomainObject.html#introspection[@DomainObject#introspection] attribute.
+
+=== How this demo works
+
+The collections on the left show three variants of the same entity, each with a property and an action, but each configured to use a different introspection policy.
+
+Navigate through to each class to inspect the differences in their source code.
diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/objects/DomainObject/introspection/DomainObjectIntrospectionVm.layout.xml b/examples/demo/domain/src/main/java/demoapp/dom/domain/objects/DomainObject/introspection/DomainObjectIntrospectionVm.layout.xml
index 885160ce25..cf9d01636b 100644
--- a/examples/demo/domain/src/main/java/demoapp/dom/domain/objects/DomainObject/introspection/DomainObjectIntrospectionVm.layout.xml
+++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/objects/DomainObject/introspection/DomainObjectIntrospectionVm.layout.xml
@@ -27,8 +27,8 @@
<bs3:row>
<bs3:col span="6">
<cpt:fieldSet name="Other" id="other" unreferencedProperties="true"/>
- <cpt:collection id="annotationRequired" paged="5"/>
<cpt:collection id="annotationOptional" paged="5"/>
+ <cpt:collection id="annotationRequired" paged="5"/>
<cpt:collection id="encapsulationEnabled" paged="5"/>
</bs3:col>
<bs3:col span="6">
diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/objects/DomainObject/introspection/annotOpt/jpa/DomainObjectIntrospectionAnnotOptJpa-description.adoc b/examples/demo/domain/src/main/java/demoapp/dom/domain/objects/DomainObject/introspection/annotOpt/jpa/DomainObjectIntrospectionAnnotOptJpa-description.adoc
index 9958511944..d4abcdf3e0 100644
--- a/examples/demo/domain/src/main/java/demoapp/dom/domain/objects/DomainObject/introspection/annotOpt/jpa/DomainObjectIntrospectionAnnotOptJpa-description.adoc
+++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/objects/DomainObject/introspection/annotOpt/jpa/DomainObjectIntrospectionAnnotOptJpa-description.adoc
@@ -7,8 +7,7 @@ The introspection of this domain object indicates that annotations are optional,
----
include::DomainObjectIntrospectionAnnotOptJpa.java[tags=class]
----
-<.> no need to annotate as `@Property`
-+
+<.> no need to annotate with `@Property`.
It would also be ok to remove the methods but then annotate the field with `@lombok.Getter` and `@lombok.Setter`
-<.> no need to annotate as `@Action`
-<.> no need to annotate as `@MemberSupport` or `@Domain.Include`
+<.> no need to annotate with `@Action`
+<.> no need to annotate with `@MemberSupport`
diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/objects/DomainObject/introspection/annotReqd/jpa/DomainObjectIntrospectionAnnotReqdJpa-description.adoc b/examples/demo/domain/src/main/java/demoapp/dom/domain/objects/DomainObject/introspection/annotReqd/jpa/DomainObjectIntrospectionAnnotReqdJpa-description.adoc
index 29f076b628..d58a51072b 100644
--- a/examples/demo/domain/src/main/java/demoapp/dom/domain/objects/DomainObject/introspection/annotReqd/jpa/DomainObjectIntrospectionAnnotReqdJpa-description.adoc
+++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/objects/DomainObject/introspection/annotReqd/jpa/DomainObjectIntrospectionAnnotReqdJpa-description.adoc
@@ -8,7 +8,6 @@ The introspection of this domain object indicates that annotations are required
include::DomainObjectIntrospectionAnnotReqdJpa.java[tags=class]
----
<.> must annotate as `@Property`.
-+
It would also be ok to remove the methods but then annotate the field with `@Property` and also with `@lombok.Getter` and `@lombok.Setter`
<.> must annotate as `@Action`
-<.> must annotate as `@MemberSupport` or `@Domain.Include`
+<.> no need to annotate with `@MemberSupport`
diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/objects/DomainObject/introspection/annotReqd/jpa/DomainObjectIntrospectionAnnotReqdJpa.java b/examples/demo/domain/src/main/java/demoapp/dom/domain/objects/DomainObject/introspection/annotReqd/jpa/DomainObjectIntrospectionAnnotReqdJpa.java
index 9ee6c29769..7f7c899808 100644
--- a/examples/demo/domain/src/main/java/demoapp/dom/domain/objects/DomainObject/introspection/annotReqd/jpa/DomainObjectIntrospectionAnnotReqdJpa.java
+++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/objects/DomainObject/introspection/annotReqd/jpa/DomainObjectIntrospectionAnnotReqdJpa.java
@@ -73,8 +73,7 @@ public class DomainObjectIntrospectionAnnotReqdJpa
setName(name);
return this;
}
- @MemberSupport // <.>
- public String default0UpdateName() {
+ public String default0UpdateName() { // <.>
return getName();
}
}