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/06/17 11:22:44 UTC

[causeway] 02/04: CAUSEWAY-3395: updates details of 'other' annotations (2)

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

commit 66412cfb11681a3ff2acb9070ce54f135596429f
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Sat Jun 17 11:20:09 2023 +0100

    CAUSEWAY-3395: updates details of 'other' annotations (2)
---
 .../modules/applib-ant/pages/about/jdo.adoc        | 14 +++---
 .../modules/applib-ant/pages/about/other.adoc      | 54 ++++++++++++++++++++--
 .../modules/applib-ant/partials/module-nav.adoc    | 33 +++++++++----
 3 files changed, 79 insertions(+), 22 deletions(-)

diff --git a/antora/components/refguide/modules/applib-ant/pages/about/jdo.adoc b/antora/components/refguide/modules/applib-ant/pages/about/jdo.adoc
index cc06ef95b2..1f7638f58f 100644
--- a/antora/components/refguide/modules/applib-ant/pages/about/jdo.adoc
+++ b/antora/components/refguide/modules/applib-ant/pages/about/jdo.adoc
@@ -26,27 +26,25 @@ Column]
 
 |xref:refguide:applib-ant:Discriminator.adoc[@javax.jdo.annotations. +
 Discriminator]
-|Override for the object type, as used in `Bookmark`s, URLs for xref:vro:ROOT:about.adoc[RestfulObjects viewer] and elsewhere. +
-
-Note that the discriminator overrides the object type that may otherwise be inferred from the xref:refguide:applib-ant:PersistenceCapable.adoc[@PersistenceCapable] annotation.
+|Infer the logical type name.
+This takes precedence of `@PersistenceCapable` (below).
+However, `@DomainObject#logicalTypeName` takes precedence over this.
 |Domain / persistence
 |Class
 
 
 |xref:refguide:applib-ant:NotPersistent.adoc[@javax.jdo.annotations. +
 NotPersistent]
-|Used to determine whether to enforce or skip some metamodel validation for `@Column` versus equivalent Causeway annotations.
+|Used to determine whether to enforce or skip some metamodel validation on nullability (`@Column` vs equivalent Causeway annotations).
 
 |Domain / persistence
 |Property
 
 
-
 |xref:refguide:applib-ant:PersistenceCapable.adoc[@javax.jdo.annotations. +
 PersistenceCapable]
-|Used to build Apache Causeway' own internal identifier for objects. +
-
-If the `schema` attribute is specified (and if xref:refguide:applib-ant:Discriminator.adoc[@Discriminator] __hasn't__ been specified), is also used to derive the object type, as used in `Bookmark`s, URLs for xref:vro:ROOT:about.adoc[RestfulObjects viewer] and elsewhere.
+|The `schema` attribute plus table name is used to the logical type name.
+However, `@Discriminator` (above) takes precedence, as does `@DomainObject#logicalTypeName`.
 
 |Domain / persistence
 |Class
diff --git a/antora/components/refguide/modules/applib-ant/pages/about/other.adoc b/antora/components/refguide/modules/applib-ant/pages/about/other.adoc
index 0d4d5cbcf0..7887bfbb2d 100644
--- a/antora/components/refguide/modules/applib-ant/pages/about/other.adoc
+++ b/antora/components/refguide/modules/applib-ant/pages/about/other.adoc
@@ -30,7 +30,7 @@ The following are commonly used:
 |===
 
 
-Meanwhile, the following are used to indicate whether a given should be included or excluded in the metamodel.
+The following are used to indicate whether a given should be included or excluded in the metamodel.
 Whether they are required depends on the setting of xref:refguide:config:sections/causeway.core.meta-model.introspector.adoc#causeway.core.meta-model.introspector.policy[causeway.core.meta-model.introspector.policy], but it is always safe to use them.
 
 .Programming Model Inclusion/Exclusion
@@ -48,23 +48,67 @@ Whether they are required depends on the setting of xref:refguide:config:section
 |Explicitly exclude the method as part of the metamodel.
 |UI/Domain
 
-|xref:refguide:applib:index/annotation/Programmatic.adoc[]
-|Equivalent to (and the original name of) xref:refguide:applib:index/annotation/Domain_Exclude.adoc[]
-|UI/Domain
-
 |xref:refguide:applib:index/annotation/MemberSupport.adoc[]
 |Intended to be annotated on `hideXxx()`, `disableXxx()` and other supporting methods, explicitly include the method as part of the metamodel.
+Equivalent to xref:refguide:applib:index/annotation/Domain_Include.adoc[]
 |Domain
 
 |xref:refguide:applib:index/annotation/ObjectSupport.adoc[]
 |Intended to be annotated on `title()`, `iconName()` and other UI hint methods, explicitly include the method as part of the metamodel.
+Equivalent to xref:refguide:applib:index/annotation/Domain_Include.adoc[]
 |UI
 
 |xref:refguide:applib:index/annotation/ObjectLifecycle.adoc[]
 |Intended to be annotated on `created()`, `updated()` and other lifecycle methods, explicitly include the method as part of the metamodel.
+Equivalent to xref:refguide:applib:index/annotation/Domain_Include.adoc[]
 |Persistence
 
+|xref:refguide:applib:index/annotation/Programmatic.adoc[]
+|Indicates that a method is to be called only programmatically, and so is _not_ part of the metamodel.
+Equivalent to (and the original name of) xref:refguide:applib:index/annotation/Domain_Exclude.adoc[]
+|UI/Domain
+
 |===
 
 
+The next annotations relate to the overall system architecture.
 
+.Architecture
+[cols="2,4a,1", options="header"]
+|===
+|Annotation
+|Purpose
+|Layer
+
+|xref:refguide:applib:index/annotation/Module.adoc[@Module]
+|An alias for Spring's own `@Configuration`, identifies a logical module consisting of a set of services, entities, mixins, fixtures etc.
+|Domain
+
+|xref:refguide:applib:index/annotation/InteractionScope.adoc[@InteractionScope]
+|Annotated on a domain service to indicate that it should be scoped by the interaction (roughly equivalent to an HTTP request).
+|Domain
+
+|===
+
+The final annotations relate to the definition of custom value types:
+
+
+.Custom value type support
+[cols="2,4a,1", options="header"]
+|===
+|Annotation
+|Purpose
+|Layer
+
+|xref:refguide:applib:index/annotation/Value.adoc[@Value]
+|Marker annotation that indicates the object is a value type (as opposed to a domain service, entity, view model or mixin).
+
+Value types also require an implementation of a xref:refguide:applib:index/value/semantics/ValueSemanticsProvider.adoc[].
+
+|Domain
+
+|xref:refguide:applib:index/annotation/ValueSemantics.adoc[@ValueSemantics]
+|Annotated on a property or parameter, indicating that the property/parameter's type should be considered a value type, and supplying details of the service implementing xref:refguide:applib:index/value/semantics/ValueSemanticsProvider.adoc[] that describes how the framework should interact with the value type.
+|Domain
+
+|===
diff --git a/antora/components/refguide/modules/applib-ant/partials/module-nav.adoc b/antora/components/refguide/modules/applib-ant/partials/module-nav.adoc
index d914d4d143..8d15179d6a 100644
--- a/antora/components/refguide/modules/applib-ant/partials/module-nav.adoc
+++ b/antora/components/refguide/modules/applib-ant/partials/module-nav.adoc
@@ -11,20 +11,35 @@
 ** xref:refguide:applib:index/annotation/DomainObjectLayout.adoc[@DomainObjectLayout]
 ** xref:refguide:applib:index/annotation/DomainService.adoc[@DomainService]
 ** xref:refguide:applib:index/annotation/DomainServiceLayout.adoc[@DomainServiceLayout]
-** xref:refguide:applib:index/annotation/HomePage.adoc[@HomePage]
-** xref:refguide:applib:index/annotation/InteractionScope.adoc[@InteractionScope]
-** xref:refguide:applib:index/annotation/MemberSupport.adoc[@MemberSupport]
-** xref:refguide:applib:index/annotation/MinLength.adoc[@MinLength]
-** xref:refguide:applib:index/annotation/Module.adoc[@Module]
 ** xref:refguide:applib:index/annotation/Parameter.adoc[@Parameter]
 ** xref:refguide:applib:index/annotation/ParameterLayout.adoc[@ParameterLayout]
-** xref:refguide:applib:index/annotation/Programmatic.adoc[@Programmatic]
 ** xref:refguide:applib:index/annotation/Property.adoc[@Property]
 ** xref:refguide:applib:index/annotation/PropertyLayout.adoc[@PropertyLayout]
-** xref:refguide:applib:index/annotation/Title.adoc[@Title]
-** xref:refguide:applib:index/annotation/Value.adoc[@Value]
 
-** javax.validation
+** Other Causeway Annotations
+
+*** xref:refguide:applib:index/annotation/HomePage.adoc[]
+*** xref:refguide:applib:index/annotation/Title.adoc[]
+*** xref:refguide:applib:index/annotation/MinLength.adoc[]
+
+*** include/exclude
+**** xref:refguide:applib:index/annotation/Domain_Include.adoc[]
+**** xref:refguide:applib:index/annotation/Domain_Exclude.adoc[]
+**** xref:refguide:applib:index/annotation/MemberSupport.adoc[]
+**** xref:refguide:applib:index/annotation/ObjectSupport.adoc[]
+**** xref:refguide:applib:index/annotation/ObjectLifecycle.adoc[]
+**** xref:refguide:applib:index/annotation/Programmatic.adoc[@Programmatic]
+
+*** architecture
+
+**** xref:refguide:applib:index/annotation/Module.adoc[@Module]
+**** xref:refguide:applib:index/annotation/InteractionScope.adoc[@InteractionScope]
+
+*** custom value type support
+**** xref:refguide:applib:index/annotation/Value.adoc[@Value]
+**** xref:refguide:applib:index/annotation/ValueSemantics.adoc[@ValueSemantics]
+
+** Java EE Annotations
 *** xref:refguide:applib-ant:Digits.adoc[@Digits]
 *** xref:refguide:applib-ant:Nullable.adoc[@Nullable]
 *** xref:refguide:applib-ant:Pattern.adoc[@Pattern]