You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2022/08/22 06:13:13 UTC
[isis] branch release-2.0.0-M8-RC1 updated: ISIS-2965 - cleans up docs a little for value types
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch release-2.0.0-M8-RC1
in repository https://gitbox.apache.org/repos/asf/isis.git
The following commit(s) were added to refs/heads/release-2.0.0-M8-RC1 by this push:
new 49775ba9f7 ISIS-2965 - cleans up docs a little for value types
49775ba9f7 is described below
commit 49775ba9f789ef6fa2e70db84ba84c15b821011c
Author: Dan Haywood <da...@haywood-associates.co.uk>
AuthorDate: Mon Aug 22 07:12:57 2022 +0100
ISIS-2965 - cleans up docs a little for value types
---
.../modules/applib-classes/pages/value-types.adoc | 53 +++++++++++++++++-----
antora/playbooks/site-valuetypes.yml | 3 ++
antora/playbooks/site.yml | 3 ++
valuetypes/adoc/modules/ROOT/pages/about.adoc | 19 +++++++-
.../pages/{about.adoc => custom-value-types.adoc} | 8 +++-
.../adoc/modules/ROOT/partials/component-nav.adoc | 1 +
valuetypes/jodatime/adoc/antora.yml | 19 ++++++++
.../adoc/modules/jodatime/nav.adoc} | 5 +-
.../adoc/modules/jodatime}/pages/about.adoc | 9 +++-
.../adoc/modules/jodatime/partials/module-nav.adoc | 4 ++
10 files changed, 102 insertions(+), 22 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 7a0f078e67..74a36df8e2 100644
--- a/antora/components/refguide/modules/applib-classes/pages/value-types.adoc
+++ b/antora/components/refguide/modules/applib-classes/pages/value-types.adoc
@@ -5,11 +5,26 @@
:page-partial:
-== Built-in
+Value types (or value objects) are building blocks of domain objects (entities and view models), used as the data types for the object's properties.
+
+For complete support:
+
+* the framework must now how to render and parse the values (the UI/presentation)
+* the framework must now how to encode/decode the value (if used in a view model)
+* the persistence mechanism (xref:pjpa::about.adoc[JPA] or xref:pjdo:ROOT:about.adoc[JDO]) must know how to persist the value
+
+The framework supports a large number of JDK value types (strings, dates, numbers), and provides an additional set of value types; see the xref:#built-in[sections] xref:#framework-defined[below].
+
+The xref:valuetypes:ROOT:about.adoc[] provides a set of optional value types that can also be added to your application.
+
+You can also define custom value types.
+This topic is also discussed in the xref:valuetypes:ROOT:about.adoc[].
+
-Apache Isis can render and persist all of the JDK primitives and wrapper classes, and a number of other JDK (7.x) classes that represent value types.
+[#built-in]
+== Built-in
-It also supports some of the link:http://www.joda.org/joda-time/[Joda-Time] datatypes, and a number of value types that are shipped by the framework itself.
+Apache Isis can render and persist all of the JDK primitives and wrapper classes, and a number of other JDK classes that represent value types.
In addition to primitives, the JDK Classes supported are:
@@ -24,33 +39,47 @@ In addition to primitives, the JDK Classes supported are:
** `java.math.BigDecimal`
** `java.math.BigInteger`
-* date types:
+* dates in the `java.time` package:
+
+** `java.time.LocalTime`
+** `java.time.LocalDate`
+** `java.time.LocalDateTime`
+** `java.time.OffsetDateTime`
+** `java.time.OffsetTime`
+** `java.time.ZonedDateTime`
+
+* dates in the `java.sql` package:
** `java.sql.Date`
** `java.sql.Time`
** `java.sql.Timestamp`
+
+* dates in the `java.util` package:
+
** `java.util.Date`
+* images:
+
+** `java.awt.BufferedImage`
+
+* URLs
-== Joda Time
+** `java.net.URL` - for external URLs
-It also supports these Joda-Time classes:
+* identifiers
-* `org.joda.time.DateTime`
-* `org.joda.time.LocalDateTime`
-* `org.joda.time.LocalDate`
+** `java.util.UUID` q
+[#framework-defined]
== Framework-defined
The framework also defines a number of custom value types:
-* xref:refguide:applib:index/value/Blob.adoc[Blob]
+* xref:refguide:applib:index/value/Blob.adoc[Blob] - eg to represent application/pdf
* xref:refguide:applib:index/value/Clob.adoc[Clob]
* xref:refguide:applib:index/value/Markup.adoc[Markup]
* xref:refguide:applib:index/value/LocalResourcePath.adoc[LocalResourcePath]
* xref:refguide:applib:index/value/Password.adoc[Password]
-In addition, there are a number of non-core value types that can be brought in individually.
-These can be found in the xref:valuetypes:ROOT:about.adoc[Value Type Catalog].
diff --git a/antora/playbooks/site-valuetypes.yml b/antora/playbooks/site-valuetypes.yml
index 8efa88aafc..1747b3aa6c 100644
--- a/antora/playbooks/site-valuetypes.yml
+++ b/antora/playbooks/site-valuetypes.yml
@@ -49,6 +49,9 @@ content:
- url: .
start_path: valuetypes/asciidoc/adoc # valuetypes
branches: HEAD
+ - url: .
+ start_path: valuetypes/jodatime/adoc # valuetypes
+ branches: HEAD
- url: .
start_path: valuetypes/markdown/adoc # valuetypes
branches: HEAD
diff --git a/antora/playbooks/site.yml b/antora/playbooks/site.yml
index cd0da7c93e..687793e56e 100644
--- a/antora/playbooks/site.yml
+++ b/antora/playbooks/site.yml
@@ -268,6 +268,9 @@ content:
- url: .
start_path: valuetypes/asciidoc/adoc # valuetypes
branches: HEAD
+ - url: .
+ start_path: valuetypes/jodatime/adoc # valuetypes
+ branches: HEAD
- url: .
start_path: valuetypes/markdown/adoc # valuetypes
branches: HEAD
diff --git a/valuetypes/adoc/modules/ROOT/pages/about.adoc b/valuetypes/adoc/modules/ROOT/pages/about.adoc
index 7962428e6f..4b080e427b 100644
--- a/valuetypes/adoc/modules/ROOT/pages/about.adoc
+++ b/valuetypes/adoc/modules/ROOT/pages/about.adoc
@@ -2,6 +2,21 @@
: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 [...]
-WARNING: TODO
-In addition, the core framework defines a number of value types; see xref:refguide:applib-classes:value-types.adoc[].
+Value types (or value objects) are building blocks of domain objects (entities and view models), used as the data types for the object's properties.
+
+For complete support:
+
+* the framework must now how to render and parse the values (the UI/presentation)
+* the framework must now how to encode/decode the value (if used in a view model)
+* the persistence mechanism (xref:pjpa::about.adoc[JPA] or xref:pjdo:ROOT:about.adoc[JDO]) must know how to persist the value
+
+The framework of course supports a whole set of value types (strings, dates, URL); Java's primitive types (`int`, `boolean` etc).
+See the reference guide's section on xref:refguide:applib-classes:value-types.adoc[value types] for the full list of types supported out-of-the-box.
+
+The framework also provides this catalog of additional value types that can be used in your application with a minimum amount of setup.
+
+It's also possible to define your own xref:custom-value-types.adoc[custom value types], or even to use 3rd party value types.
+
+
+
diff --git a/valuetypes/adoc/modules/ROOT/pages/about.adoc b/valuetypes/adoc/modules/ROOT/pages/custom-value-types.adoc
similarity index 84%
copy from valuetypes/adoc/modules/ROOT/pages/about.adoc
copy to valuetypes/adoc/modules/ROOT/pages/custom-value-types.adoc
index 7962428e6f..bfc91806d3 100644
--- a/valuetypes/adoc/modules/ROOT/pages/about.adoc
+++ b/valuetypes/adoc/modules/ROOT/pages/custom-value-types.adoc
@@ -1,7 +1,11 @@
-= Value Type Catalog
+= Custom Value Types
: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 [...]
+
WARNING: TODO
-In addition, the core framework defines a number of value types; see xref:refguide:applib-classes:value-types.adoc[].
+
+== ValueSemanticsProvider
+
+WARNING: TODO - describe how this works, provide examples.
diff --git a/valuetypes/adoc/modules/ROOT/partials/component-nav.adoc b/valuetypes/adoc/modules/ROOT/partials/component-nav.adoc
index 7c1f3b5a06..ebd25e1936 100644
--- a/valuetypes/adoc/modules/ROOT/partials/component-nav.adoc
+++ b/valuetypes/adoc/modules/ROOT/partials/component-nav.adoc
@@ -5,5 +5,6 @@
include::valuetypes:ROOT:partial$module-nav.adoc[]
include::valuetypes:asciidoc:partial$module-nav.adoc[]
+include::valuetypes:jodatime:partial$module-nav.adoc[]
include::valuetypes:markdown:partial$module-nav.adoc[]
diff --git a/valuetypes/jodatime/adoc/antora.yml b/valuetypes/jodatime/adoc/antora.yml
new file mode 100644
index 0000000000..0f50856e63
--- /dev/null
+++ b/valuetypes/jodatime/adoc/antora.yml
@@ -0,0 +1,19 @@
+# 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 agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+name: valuetypes
+version: latest
diff --git a/valuetypes/adoc/modules/ROOT/pages/about.adoc b/valuetypes/jodatime/adoc/modules/jodatime/nav.adoc
similarity index 83%
copy from valuetypes/adoc/modules/ROOT/pages/about.adoc
copy to valuetypes/jodatime/adoc/modules/jodatime/nav.adoc
index 7962428e6f..ebdb5577b3 100644
--- a/valuetypes/adoc/modules/ROOT/pages/about.adoc
+++ b/valuetypes/jodatime/adoc/modules/jodatime/nav.adoc
@@ -1,7 +1,4 @@
-= Value Type Catalog
: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 [...]
-WARNING: TODO
-
-In addition, the core framework defines a number of value types; see xref:refguide:applib-classes:value-types.adoc[].
+include::vw:ROOT:partial$component-nav.adoc[]
diff --git a/valuetypes/adoc/modules/ROOT/pages/about.adoc b/valuetypes/jodatime/adoc/modules/jodatime/pages/about.adoc
similarity index 77%
copy from valuetypes/adoc/modules/ROOT/pages/about.adoc
copy to valuetypes/jodatime/adoc/modules/jodatime/pages/about.adoc
index 7962428e6f..bb9d6646ce 100644
--- a/valuetypes/adoc/modules/ROOT/pages/about.adoc
+++ b/valuetypes/jodatime/adoc/modules/jodatime/pages/about.adoc
@@ -1,7 +1,12 @@
-= Value Type Catalog
+= JodaTime
: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 [...]
WARNING: TODO
-In addition, the core framework defines a number of value types; see xref:refguide:applib-classes:value-types.adoc[].
+The module provides support for these link:https://www.joda.org/joda-time/[Joda-Time] classes:
+
+* `org.joda.time.LocalDate`
+* `org.joda.time.LocalDateTime`
+* `org.joda.time.LocalTime`
+* `org.joda.time.DateTime`
diff --git a/valuetypes/jodatime/adoc/modules/jodatime/partials/module-nav.adoc b/valuetypes/jodatime/adoc/modules/jodatime/partials/module-nav.adoc
new file mode 100644
index 0000000000..38071c3864
--- /dev/null
+++ b/valuetypes/jodatime/adoc/modules/jodatime/partials/module-nav.adoc
@@ -0,0 +1,4 @@
+
+
+* xref:valuetypes:jodatime:about.adoc[JodaTime]
+