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/18 17:12:54 UTC

[causeway] 01/12: CAUSEWAY-3395: removes further TODOs

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 e4c2ef8b611ccceb6df6189a166036c97e5a751d
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Sat Jun 17 16:34:39 2023 +0100

    CAUSEWAY-3395: removes further TODOs
---
 .../adoc/modules/ROOT/pages/hints-and-tips.adoc    |  12 +-
 .../jdo/adoc/modules/ROOT/pages/mapping-guide.adoc | 167 +--------------------
 persistence/jdo/adoc/modules/ROOT/pages/spis.adoc  |   2 +-
 .../hints-and-tips/diagnosing-n-plus-1.adoc        |   0
 .../hints-and-tips/jdoql-and-timestamps.adoc       |   0
 .../hints-and-tips/overriding-jdo-annotations.adoc |   1 -
 .../subtype-entity-not-fully-populated.adoc        |   0
 .../hints-and-tips/tracing-sql-statements.adoc     |   0
 .../typesafe-queries-and-fetchgroups.adoc          |   0
 .../mapping-guide/custom-value-types.adoc}         |  27 +---
 .../mandatory-properties-in-subtypes.adoc          |   0
 .../mapping-guide/mapping-to-a-view.adoc           |   0
 .../one-to-m-bidirectional-relationships.adoc      |   0
 .../jdo/adoc/modules/ROOT/partials/module-nav.adoc |   6 +-
 .../spis/JdoEntityDiscoveryListener.adoc           |   0
 15 files changed, 23 insertions(+), 192 deletions(-)

diff --git a/persistence/jdo/adoc/modules/ROOT/pages/hints-and-tips.adoc b/persistence/jdo/adoc/modules/ROOT/pages/hints-and-tips.adoc
index 3d4992e73b..545423e4f1 100644
--- a/persistence/jdo/adoc/modules/ROOT/pages/hints-and-tips.adoc
+++ b/persistence/jdo/adoc/modules/ROOT/pages/hints-and-tips.adoc
@@ -6,9 +6,9 @@
 
 This page provides some solutions for problems we've encountered ourselves or have been raised on the Apache Causeway mailing lists.
 
-include::hints-and-tips/tracing-sql-statements.adoc[leveloffset=+1]
-include::hints-and-tips/overriding-jdo-annotations.adoc[leveloffset=+1]
-include::hints-and-tips/subtype-entity-not-fully-populated.adoc[leveloffset=+1]
-include::hints-and-tips/diagnosing-n-plus-1.adoc[leveloffset=+1]
-include::hints-and-tips/typesafe-queries-and-fetchgroups.adoc[leveloffset=+1]
-include::hints-and-tips/jdoql-and-timestamps.adoc[leveloffset=+1]
+include::partial$hints-and-tips/tracing-sql-statements.adoc[leveloffset=+1]
+include::partial$hints-and-tips/overriding-jdo-annotations.adoc[leveloffset=+1]
+include::partial$hints-and-tips/subtype-entity-not-fully-populated.adoc[leveloffset=+1]
+include::partial$hints-and-tips/diagnosing-n-plus-1.adoc[leveloffset=+1]
+include::partial$hints-and-tips/typesafe-queries-and-fetchgroups.adoc[leveloffset=+1]
+include::partial$hints-and-tips/jdoql-and-timestamps.adoc[leveloffset=+1]
diff --git a/persistence/jdo/adoc/modules/ROOT/pages/mapping-guide.adoc b/persistence/jdo/adoc/modules/ROOT/pages/mapping-guide.adoc
index ed6f2bc6af..780cc35d26 100644
--- a/persistence/jdo/adoc/modules/ROOT/pages/mapping-guide.adoc
+++ b/persistence/jdo/adoc/modules/ROOT/pages/mapping-guide.adoc
@@ -8,168 +8,11 @@ Take a look at:
 * link:https://www.datanucleus.org/products/accessplatform/jdo/mapping.html[JDO Mapping Guide]
 * link:https://www.datanucleus.org/products/accessplatform/jdo/annotations.html[JDO Annotations]
 
-In addition, we have a couple of articles on specific mapping use cases:
+The remainder of this page provides guidance on several specific mapping use cases.
 
-* xref:pjdo:ROOT:mapping-guide/one-to-m-bidirectional-relationships.adoc[]
-* xref:pjdo:ROOT:mapping-guide/mandatory-properties-in-subtypes.adoc[]
-* xref:pjdo:ROOT:mapping-guide/mapping-to-a-view.adoc[]
-
-
-== Custom Value Types
-
-The framework provides a number of custom value types.
-Some of these are wrappers around a single value (eg `AsciiDoc` or `Password`) while others map onto multiple values (eg `Blob`).
-
-This section shows how to map each (and can be adapted for your own custom types or `@Embedded` values).
-
-
-=== Mapping AsciiDoc
-
-The xref:refguide:valuetypes:index/asciidoc/applib/value/AsciiDoc.adoc[] value type is used for documentation written using the link:https://asciidoctor.org/[AsciiDoc] syntax:
-
-* In the domain entity, map `AsciiDoc` type using `@Column(jdbcType = "CLOB")`:
-+
-[source,java]
-.MyEntity.java
-----
-public class MyEntity ... {
-
-    @Column(allowsNull = "false", jdbcType = "CLOB")
-    @Property
-    @Getter @Setter
-    private AsciiDoc documentation;
-
-}
-----
-
-* in the webapp module, register the JDO specific converter by:
-
-** adding a dependency to this module:
-+
-[source,xml]
-.pom.xml
-----
-<dependency>
-    <groupId>org.apache.causeway.valuetypes</groupId>
-    <artifactId>causeway-valuetypes-asciidoc-persistence-jdo</artifactId>
-</dependency>
-----
-
-** and adding reference the corresponding module in the `AppManifest`:
-+
-[source,java]
-.AppManifest.java
-----
-@Configuration
-@Import({
-        ...
-        CausewayModuleValAsciidocPersistenceJdo.java
-        ...
-})
-public class AppManifest {
-}
-----
-
-=== Mapping Markdown
-
-The xref:refguide:valuetypes:index/markdown/applib/value/Markdown.adoc[] value type is used for documentation written using markdown:
-
-* In the domain entity, map `Markdown` type using `@Column(jdbcType = "CLOB")`:
-+
-[source,java]
-.MyEntity.java
-----
-public class MyEntity ... {
-
-    @Column(allowsNull = "false", jdbcType = "CLOB")
-    @Property
-    @Getter @Setter
-    private Markdown documentation;
-
-}
-----
-
-* in the webapp module, register the JDO specific converter by:
-
-** adding a dependency to this module:
-+
-[source,xml]
-.pom.xml
-----
-<dependency>
-    <groupId>org.apache.causeway.valuetypes</groupId>
-    <artifactId>causeway-valuetypes-markdown-persistence-jdo</artifactId>
-</dependency>
-----
-
-** and adding reference the corresponding module in the `AppManifest`:
-+
-[source,java]
-.AppManifest.java
-----
-@Configuration
-@Import({
-        ...
-        CausewayModuleValMarkdownPersistenceJdo.java
-        ...
-})
-public class AppManifest {
-}
-----
-
-
-=== Mapping Blobs and Clobs
-
-The JDO ObjectStore integration of DataNucleus ORM can automatically persist xref:refguide:applib:index/value/Blob.adoc[] and xref:refguide:applib:index/value/Clob.adoc[] values into multiple columns, corresponding to their constituent parts.
-
-==== Blobs
-
-To map a xref:refguide:applib:index/value/Blob.adoc[Blob], use:
-
-[source,java]
-.MyEntity.java
-----
-public class MyEntity ... {
-
-    @Persistent(defaultFetchGroup="false", columns = {
-            @Column(name = "pdf_name"),                 // <.>
-            @Column(name = "pdf_mimetype"),             // <.>
-            @Column(name = "pdf_bytes")                 // <.>
-    })
-    @Getter @Setter
-    private Blob pdf;
-
-}
-----
-<.> string, maps to a varchar in the database
-<.> string, maps to a varchar in the database
-<.> byte array, maps to a Blob or varbinary in the database
-
-
-==== Clobs
-
-To map a xref:refguide:applib:index/value/Clob.adoc[Clob], use:
-
-[source]
-.MyEntity.java
-----
-public class MyEntity ... {
-
-    @Persistent(defaultFetchGroup="false", columns = {
-            @Column(name = "xml_name"),                 // <.>
-            @Column(name = "xml_mimetype"),             // <.>
-            @Column(name = "xml_chars"                  // <.>
-                    , jdbcType = "CLOB"
-            )
-    })
-    @Getter @Setter
-    private Clob xml;
-
-}
-----
-
-<.> string, maps to a varchar in the database
-<.> string, maps to a varchar in the database
-<.> char array, maps to a Clob or varchar in the database
+include::partial$mapping-guide/one-to-m-bidirectional-relationships.adoc[leveloffset=+1]
+include::partial$mapping-guide/mandatory-properties-in-subtypes.adoc[leveloffset=+1]
+include::partial$mapping-guide/mapping-to-a-view.adoc[leveloffset=+1]
+include::partial$mapping-guide/custom-value-types.adoc[leveloffset=+1]
 
 
diff --git a/persistence/jdo/adoc/modules/ROOT/pages/spis.adoc b/persistence/jdo/adoc/modules/ROOT/pages/spis.adoc
index cbfd08298e..28126bebb0 100644
--- a/persistence/jdo/adoc/modules/ROOT/pages/spis.adoc
+++ b/persistence/jdo/adoc/modules/ROOT/pages/spis.adoc
@@ -5,4 +5,4 @@
 
 This page lists (some of) the hooks available to interact with the JDO persistence mechanism itself.
 
-include::spis/JdoEntityDiscoveryListener.adoc[leveloffset=+1]
+include::partial$spis/JdoEntityDiscoveryListener.adoc[leveloffset=+1]
diff --git a/persistence/jdo/adoc/modules/ROOT/pages/hints-and-tips/diagnosing-n-plus-1.adoc b/persistence/jdo/adoc/modules/ROOT/partials/hints-and-tips/diagnosing-n-plus-1.adoc
similarity index 100%
rename from persistence/jdo/adoc/modules/ROOT/pages/hints-and-tips/diagnosing-n-plus-1.adoc
rename to persistence/jdo/adoc/modules/ROOT/partials/hints-and-tips/diagnosing-n-plus-1.adoc
diff --git a/persistence/jdo/adoc/modules/ROOT/pages/hints-and-tips/jdoql-and-timestamps.adoc b/persistence/jdo/adoc/modules/ROOT/partials/hints-and-tips/jdoql-and-timestamps.adoc
similarity index 100%
rename from persistence/jdo/adoc/modules/ROOT/pages/hints-and-tips/jdoql-and-timestamps.adoc
rename to persistence/jdo/adoc/modules/ROOT/partials/hints-and-tips/jdoql-and-timestamps.adoc
diff --git a/persistence/jdo/adoc/modules/ROOT/pages/hints-and-tips/overriding-jdo-annotations.adoc b/persistence/jdo/adoc/modules/ROOT/partials/hints-and-tips/overriding-jdo-annotations.adoc
similarity index 99%
rename from persistence/jdo/adoc/modules/ROOT/pages/hints-and-tips/overriding-jdo-annotations.adoc
rename to persistence/jdo/adoc/modules/ROOT/partials/hints-and-tips/overriding-jdo-annotations.adoc
index 468e6bc644..95fa1d1cc6 100644
--- a/persistence/jdo/adoc/modules/ROOT/pages/hints-and-tips/overriding-jdo-annotations.adoc
+++ b/persistence/jdo/adoc/modules/ROOT/partials/hints-and-tips/overriding-jdo-annotations.adoc
@@ -3,7 +3,6 @@
 
 :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: to update.
 
 JDO/DataNucleus builds its own persistence metamodel by reading both annotations on the class and also by searching for metadata in XML files.
 The metadata in the XML files takes precedence over the annotations, and so can be used to override metadata that is "hard-coded" in annotations.
diff --git a/persistence/jdo/adoc/modules/ROOT/pages/hints-and-tips/subtype-entity-not-fully-populated.adoc b/persistence/jdo/adoc/modules/ROOT/partials/hints-and-tips/subtype-entity-not-fully-populated.adoc
similarity index 100%
rename from persistence/jdo/adoc/modules/ROOT/pages/hints-and-tips/subtype-entity-not-fully-populated.adoc
rename to persistence/jdo/adoc/modules/ROOT/partials/hints-and-tips/subtype-entity-not-fully-populated.adoc
diff --git a/persistence/jdo/adoc/modules/ROOT/pages/hints-and-tips/tracing-sql-statements.adoc b/persistence/jdo/adoc/modules/ROOT/partials/hints-and-tips/tracing-sql-statements.adoc
similarity index 100%
rename from persistence/jdo/adoc/modules/ROOT/pages/hints-and-tips/tracing-sql-statements.adoc
rename to persistence/jdo/adoc/modules/ROOT/partials/hints-and-tips/tracing-sql-statements.adoc
diff --git a/persistence/jdo/adoc/modules/ROOT/pages/hints-and-tips/typesafe-queries-and-fetchgroups.adoc b/persistence/jdo/adoc/modules/ROOT/partials/hints-and-tips/typesafe-queries-and-fetchgroups.adoc
similarity index 100%
rename from persistence/jdo/adoc/modules/ROOT/pages/hints-and-tips/typesafe-queries-and-fetchgroups.adoc
rename to persistence/jdo/adoc/modules/ROOT/partials/hints-and-tips/typesafe-queries-and-fetchgroups.adoc
diff --git a/persistence/jdo/adoc/modules/ROOT/pages/mapping-guide.adoc b/persistence/jdo/adoc/modules/ROOT/partials/mapping-guide/custom-value-types.adoc
similarity index 86%
copy from persistence/jdo/adoc/modules/ROOT/pages/mapping-guide.adoc
copy to persistence/jdo/adoc/modules/ROOT/partials/mapping-guide/custom-value-types.adoc
index ed6f2bc6af..d36cd42d99 100644
--- a/persistence/jdo/adoc/modules/ROOT/pages/mapping-guide.adoc
+++ b/persistence/jdo/adoc/modules/ROOT/partials/mapping-guide/custom-value-types.adoc
@@ -1,21 +1,10 @@
-= Mapping Guide
+[[custom-value-types]]
+= 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 [...]
-
-The best resource for learning how to map JDO entities is the DataNucleus website.
-Take a look at:
-
-* link:https://www.datanucleus.org/products/accessplatform/jdo/mapping.html[JDO Mapping Guide]
-* link:https://www.datanucleus.org/products/accessplatform/jdo/annotations.html[JDO Annotations]
 
-In addition, we have a couple of articles on specific mapping use cases:
-
-* xref:pjdo:ROOT:mapping-guide/one-to-m-bidirectional-relationships.adoc[]
-* xref:pjdo:ROOT:mapping-guide/mandatory-properties-in-subtypes.adoc[]
-* xref:pjdo:ROOT:mapping-guide/mapping-to-a-view.adoc[]
+: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 [...]
 
 
-== Custom Value Types
 
 The framework provides a number of custom value types.
 Some of these are wrappers around a single value (eg `AsciiDoc` or `Password`) while others map onto multiple values (eg `Blob`).
@@ -23,7 +12,7 @@ Some of these are wrappers around a single value (eg `AsciiDoc` or `Password`) w
 This section shows how to map each (and can be adapted for your own custom types or `@Embedded` values).
 
 
-=== Mapping AsciiDoc
+== Mapping AsciiDoc
 
 The xref:refguide:valuetypes:index/asciidoc/applib/value/AsciiDoc.adoc[] value type is used for documentation written using the link:https://asciidoctor.org/[AsciiDoc] syntax:
 
@@ -70,7 +59,7 @@ public class AppManifest {
 }
 ----
 
-=== Mapping Markdown
+== Mapping Markdown
 
 The xref:refguide:valuetypes:index/markdown/applib/value/Markdown.adoc[] value type is used for documentation written using markdown:
 
@@ -118,11 +107,11 @@ public class AppManifest {
 ----
 
 
-=== Mapping Blobs and Clobs
+== Mapping Blobs and Clobs
 
 The JDO ObjectStore integration of DataNucleus ORM can automatically persist xref:refguide:applib:index/value/Blob.adoc[] and xref:refguide:applib:index/value/Clob.adoc[] values into multiple columns, corresponding to their constituent parts.
 
-==== Blobs
+=== Blobs
 
 To map a xref:refguide:applib:index/value/Blob.adoc[Blob], use:
 
@@ -146,7 +135,7 @@ public class MyEntity ... {
 <.> byte array, maps to a Blob or varbinary in the database
 
 
-==== Clobs
+=== Clobs
 
 To map a xref:refguide:applib:index/value/Clob.adoc[Clob], use:
 
diff --git a/persistence/jdo/adoc/modules/ROOT/pages/mapping-guide/mandatory-properties-in-subtypes.adoc b/persistence/jdo/adoc/modules/ROOT/partials/mapping-guide/mandatory-properties-in-subtypes.adoc
similarity index 100%
rename from persistence/jdo/adoc/modules/ROOT/pages/mapping-guide/mandatory-properties-in-subtypes.adoc
rename to persistence/jdo/adoc/modules/ROOT/partials/mapping-guide/mandatory-properties-in-subtypes.adoc
diff --git a/persistence/jdo/adoc/modules/ROOT/pages/mapping-guide/mapping-to-a-view.adoc b/persistence/jdo/adoc/modules/ROOT/partials/mapping-guide/mapping-to-a-view.adoc
similarity index 100%
rename from persistence/jdo/adoc/modules/ROOT/pages/mapping-guide/mapping-to-a-view.adoc
rename to persistence/jdo/adoc/modules/ROOT/partials/mapping-guide/mapping-to-a-view.adoc
diff --git a/persistence/jdo/adoc/modules/ROOT/pages/mapping-guide/one-to-m-bidirectional-relationships.adoc b/persistence/jdo/adoc/modules/ROOT/partials/mapping-guide/one-to-m-bidirectional-relationships.adoc
similarity index 100%
rename from persistence/jdo/adoc/modules/ROOT/pages/mapping-guide/one-to-m-bidirectional-relationships.adoc
rename to persistence/jdo/adoc/modules/ROOT/partials/mapping-guide/one-to-m-bidirectional-relationships.adoc
diff --git a/persistence/jdo/adoc/modules/ROOT/partials/module-nav.adoc b/persistence/jdo/adoc/modules/ROOT/partials/module-nav.adoc
index 596938d62b..a68585a422 100644
--- a/persistence/jdo/adoc/modules/ROOT/partials/module-nav.adoc
+++ b/persistence/jdo/adoc/modules/ROOT/partials/module-nav.adoc
@@ -6,9 +6,9 @@
 * xref:pjdo:ROOT:db-schemas.adoc[DB Schemas]
 
 * xref:pjdo:ROOT:mapping-guide.adoc[Mapping Guide]
-** xref:pjdo:ROOT:mapping-guide/one-to-m-bidirectional-relationships.adoc[leveloffset=+1]
-** xref:pjdo:ROOT:mapping-guide/mandatory-properties-in-subtypes.adoc[leveloffset=+1]
-** xref:pjdo:ROOT:mapping-guide/mapping-to-a-view.adoc[leveloffset=+1]
+** xref:pjdo:ROOT:mapping-guide.adoc#one-to-m-bidirectional-relationships[leveloffset=+1]
+** xref:pjdo:ROOT:mapping-guide.adoc#mandatory-properties-in-subtypes[leveloffset=+1]
+** xref:pjdo:ROOT:mapping-guide.adoc#mapping-to-a-view[leveloffset=+1]
 
 * xref:pjdo:ROOT:dependency-injection.adoc[Dependency Injection]
 * xref:pjdo:ROOT:hints-and-tips.adoc[Hints-n-Tips]
diff --git a/persistence/jdo/adoc/modules/ROOT/pages/spis/JdoEntityDiscoveryListener.adoc b/persistence/jdo/adoc/modules/ROOT/partials/spis/JdoEntityDiscoveryListener.adoc
similarity index 100%
rename from persistence/jdo/adoc/modules/ROOT/pages/spis/JdoEntityDiscoveryListener.adoc
rename to persistence/jdo/adoc/modules/ROOT/partials/spis/JdoEntityDiscoveryListener.adoc