This is an automated email from the ASF dual-hosted git repository. danhaywood pushed a commit to branch CAUSEWAY-3866 in repository https://gitbox.apache.org/repos/asf/causeway.git
commit 09f9f4dccff6b48bafbb0d44e5d9f5640baec207 Author: Dan Haywood <[email protected]> AuthorDate: Sun Oct 19 11:42:46 2025 +0100 CAUSEWAY-3866: reconcile two pages both listing value types --- .../modules/applib-classes/pages/value-types.adoc | 63 ++++++++------ .../userguide/modules/ROOT/pages/value-types.adoc | 95 +++++++++++++++------- 2 files changed, 102 insertions(+), 56 deletions(-) diff --git a/antora/components/refguide/modules/applib-classes/pages/value-types.adoc b/antora/components/refguide/modules/applib-classes/pages/value-types.adoc index ca6c1293db6..6736c434438 100644 --- a/antora/components/refguide/modules/applib-classes/pages/value-types.adoc +++ b/antora/components/refguide/modules/applib-classes/pages/value-types.adoc @@ -5,43 +5,57 @@ :page-partial: -== Built-in +== Built-in: JDK types -Apache Causeway can render and persist all of the JDK primitives and wrapper classes, and a number of other JDK classes that represent value types. +Apache Causeway can render and persist all the JDK primitives and wrapper classes, and a number of other JDK classes that represent value types. It also supports a number of value types that are shipped by the framework itself. In addition to primitives, the JDK Classes supported are: -* the wrapper classes: - -** `java.lang.Boolean`, `java.lang.Character`, `java.lang.Double`, `java.lang.Float`, `java.lang.Long`, `java.lang.Integer`, `java.lang.Short`, `java.lang.Byte` +* the wrapper classes (in `java.lang`) ++ +`Integer`, `Long`, `Short`, `Byte`, `Character`, `Float`, `Double`, `Boolean` -* strings and similar: classes: +* strings and similar: ** `java.lang.String` ** any enum (subtype of `java.lang.Enum`) -* numeric data types: +* numeric data types for arbitrary accuracy: -** `java.math.BigDecimal` -** `java.math.BigInteger` +** `java.math.BigDecimal` and `java.math.BigInteger` ++ +These can be combined with `@Digits` to specify scale. -* date types: +== Built-in: JDK Dates -** `java.sql.Date` -** `java.sql.Time` -** `java.sql.Timestamp` -** `java.util.Date` +Dates are also supported of course, though there are lots of options: -* JDK 8 datetime types: +* in the `java.time` package; these are the most modern and generally is to be preferred: -** `java.time.LocalDate` -** `java.time.LocalTime` -** `java.time.LocalDateTime` -** `java.time.OffsetDateTime` -** `java.time.OffsetTime` -** `java.time.ZonedDateTime` +** local times (no time zone): ++ +`java.time.LocalDate,` `java.time.LocalTime`, `java.time.LocalDateTime` + +** for storing date/time, with respect to the UTC: ++ +`java.time.OffsetDateTime`, `java.time.OffsetTime` + +** primarily for _displaying_ time in a specified time zone: ++ +`java.time.ZonedDateTime` + +* in the `java.util` package (usage is discouraged since these classes are not immutable): ++ +`java.util.Date` + +* in the `java.sql` package: ++ +`java.sql.Date,` `java.sql.Timestamp`, `java.sql.Time` + + +== Built-in: Other JDK types * miscellaneous: @@ -56,9 +70,6 @@ In addition to primitives, the JDK Classes supported are: The framework also defines a number of custom value types: - - - * xref:refguide:applib:index/value/Blob.adoc[Blob] * xref:refguide:applib:index/value/Clob.adoc[Clob] * xref:refguide:applib:index/value/Markup.adoc[Markup] @@ -80,7 +91,7 @@ This is therefore a way to redirect to a custom controller. * xref:refguide:applib:index/graph/tree/TreePath.adoc[TreePath] and xref:refguide:applib:index/graph/tree/TreeNode.adoc[TreeNode] + -These can be used to render filesystem structures and similar +These can be used to render tree structures. In addition, there are a number of non-core value types that can be brought in individually: @@ -119,4 +130,4 @@ The xref:refguide:schema:about.adoc[] of XSDs define a number of DTOs (persisted == Custom value types It is also possible to write your own value types, either scalar or composite. -For more on this topic, see xref:userguide:ROOT:value-types.adoc[value types] topic in the user guide. +For more on this topic, see xref:userguide:ROOT:value-types.adoc#custom-value-types[custom value types] topic in the user guide. diff --git a/antora/components/userguide/modules/ROOT/pages/value-types.adoc b/antora/components/userguide/modules/ROOT/pages/value-types.adoc index a9c9efa6c8c..504ae39451a 100644 --- a/antora/components/userguide/modules/ROOT/pages/value-types.adoc +++ b/antora/components/userguide/modules/ROOT/pages/value-types.adoc @@ -58,46 +58,29 @@ A JAXB view model would require `@XmlJavaTypeAdapter(JavaTimeJaxbAdapters.LocalD In the following sections we look at the other datatypes that you can use as the value types, and then we look at defining custom types. [#jdk-types] -== JDK types +== Built-in: JDK types -The most common value types to use are those built-into JDK. -None of the following require additional annotations when used in entities or view models: +Apache Causeway can render and persist all the JDK primitives and wrapper classes, and a number of other JDK classes that represent value types. -* primitives -+ -`int`, `long`, `short`, `byte`, `char`, `float`, `double`, `boolean` +In addition to primitives, the JDK Classes supported are: -* wrappers +* the wrapper classes (in `java.lang`) + `Integer`, `Long`, `Short`, `Byte`, `Character`, `Float`, `Double`, `Boolean` -* `java.lang.String` - -* `java.math.BigInteger` and `java.math.BigDecimal` -+ -for arbitrary accuracy. -These can be combined with `@Digits` to specify scale. - -* `java.util.UUID` +* strings and similar: -These are also a couple of value types that have special properties when rendered: +** `java.lang.String` +** any enum (subtype of `java.lang.Enum`) -* `java.net.URL` -+ -Essentially a string, but will render as a hyperlink that the end-user can click +* numeric data types for arbitrary accuracy: -* `java.awt.image.BufferedImage` -+ -In essence a byte array containing a `.png` or similar. -Note though that properties if this type must be read-only. +** `java.math.BigDecimal` and `java.math.BigInteger` + -[source,java] ----- -val bytes = _Bytes.of(_Resources.load(getClass(), "spring-boot-logo.png" )); -return javax.imageio.ImageIO.read(new ByteArrayInputStream(bytes)); ----- +for arbitrary accuracy. +These can be combined with `@Digits` to specify scale. -== Dates +== Built-in: JDK Dates Dates are also supported of course, though there are lots of options: @@ -138,8 +121,36 @@ Depending on context, additional entities may be required on the property's fiel This tells JAXB how to serialize the value in and out of XML. Apache Causeway provides adapters for all of these. + +== Built-in: Other JDK types + +These are also a couple of value types that have special properties when rendered: + +* `java.util.UUID` ++ +Essentially a string with a particular format. + +* `java.util.Locale` + +* `java.net.URL` ++ +Renders as a hyperlink that the end-user can click + +* `java.awt.image.BufferedImage` ++ +In essence a byte array containing a `.png` or similar. +Note though that properties if this type must be read-only. ++ +[source,java] +---- +val bytes = _Bytes.of(_Resources.load(getClass(), "spring-boot-logo.png" )); +return javax.imageio.ImageIO.read(new ByteArrayInputStream(bytes)); +---- + + Apache Causeway defines a number of its own custom value types, described next. + [#causeway-specific] == Causeway-specific @@ -177,7 +188,14 @@ There are several such built-in resources that can be useful in a development/pr ** `/db/` - the H2 database console + -You could of course also define additional resources for your own requirements. +You can also use this as a way to redirect to a custom controller. + +* xref:refguide:applib:index/graph/tree/TreePath.adoc[TreePath] and xref:refguide:applib:index/graph/tree/TreeNode.adoc[TreeNode] ++ +These can be used to render tree structures. + + +== Value type catalogue (extensions) The above value types are part of the core framework. There are also several value types that are packaged as extensions in the xref:valuetypes::about.adoc[Value Types Catalog]: @@ -195,6 +213,23 @@ This renders Markdown content (as defined by the link:https://spec.commonmark.or This renders graphics defined by the link:https://vega.github.io/vega-lite/[Vega-Lite] grammar. +== Internal value types + +The core framework also defines a number of value types whose use is primarily internal: + +* xref:refguide:applib:index/services/bookmark/Bookmark.adoc[Bookmark] +* anything supported by xref:refguide:applib:index/services/bookmark/IdStringifier.adoc[IdStringifier] ++ +Used by the xref:userguide:commandlog:about.adoc[], xref:userguide:executionlog:about.adoc[], xref:userguide:executionoutbox:about.adoc[] and xref:security:sessionlog:about.adoc[] externsions modules so that their application primary keys of their corresponding entities are recognised as value types + +* `ApplicationFeatureIdValueSemantics` + +The xref:refguide:schema:about.adoc[] of XSDs define a number of DTOs (persisted by the above core extensions) which are also recognised as value types: + +* xref:refguide:schema:cmd.adoc[CommandDto] (and an XML pretty-render variant) +* xref:refguide:schema:ixn.adoc[InteractionDto] (and an XML pretty-render variant) +* xref:refguide:schema:chg.adoc[ChangesDto] (and an XML pretty-render variant) + [#custom-value-types] == Custom value types
