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
The following commit(s) were added to refs/heads/CAUSEWAY-3866 by this push:
new a64381e01d7 CAUSEWAY-3866: reconcile two pages both listing value types
a64381e01d7 is described below
commit a64381e01d76b4e88c9669d4026afc1f61709863
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
