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/16 07:57:38 UTC

[causeway] branch master updated: CAUSEWAY-3395: updates blob demo docs, jpa and jdo

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


The following commit(s) were added to refs/heads/master by this push:
     new 87d0fe4b0f CAUSEWAY-3395: updates blob demo docs, jpa and jdo
87d0fe4b0f is described below

commit 87d0fe4b0f3966508a1e539c28e9ad3bd4501a36
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Fri Jun 16 08:57:17 2023 +0100

    CAUSEWAY-3395: updates blob demo docs, jpa and jdo
---
 .../asciidoc/CausewayAsciiDocSamples-sample1.adoc  |  3 +-
 .../blobs/jdo/CausewayBlobJdo-description.adoc     | 33 +++++++++++++-----
 .../types/causeway/blobs/jdo/CausewayBlobJdo.java  |  9 +++--
 .../blobs/jpa/CausewayBlobJpa-description.adoc     | 39 ++++++++++++++--------
 .../types/causeway/blobs/jpa/CausewayBlobJpa.java  | 12 ++++---
 5 files changed, 66 insertions(+), 30 deletions(-)

diff --git a/examples/demo/domain/src/main/java/demoapp/dom/_infra/samples/asciidoc/CausewayAsciiDocSamples-sample1.adoc b/examples/demo/domain/src/main/java/demoapp/dom/_infra/samples/asciidoc/CausewayAsciiDocSamples-sample1.adoc
index 751e741d77..a9e6023e37 100644
--- a/examples/demo/domain/src/main/java/demoapp/dom/_infra/samples/asciidoc/CausewayAsciiDocSamples-sample1.adoc
+++ b/examples/demo/domain/src/main/java/demoapp/dom/_infra/samples/asciidoc/CausewayAsciiDocSamples-sample1.adoc
@@ -18,6 +18,5 @@ to test Asciidoctor compliance.
 This document exercises many of the features of AsciiDoc to test the {library} implementation.
 ****
 
-TIP: If you want the output to look familiar, copy (or link) the AsciiDoc stylesheet, asciidoc.css, to the output directory.
+TIP: If you want the output to look familiar, copy (or link) the AsciiDoc stylesheet, `asciidoc-default.css,` to the output directory.
 
-NOTE: Items marked with TODO are either not yet supported or a work in progress.
diff --git a/examples/demo/domain/src/main/java/demoapp/dom/types/causeway/blobs/jdo/CausewayBlobJdo-description.adoc b/examples/demo/domain/src/main/java/demoapp/dom/types/causeway/blobs/jdo/CausewayBlobJdo-description.adoc
index 1d85752cd8..965756a541 100644
--- a/examples/demo/domain/src/main/java/demoapp/dom/types/causeway/blobs/jdo/CausewayBlobJdo-description.adoc
+++ b/examples/demo/domain/src/main/java/demoapp/dom/types/causeway/blobs/jdo/CausewayBlobJdo-description.adoc
@@ -1,19 +1,36 @@
 :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 [...]
 
-Apache Causeway implements the relevant JDO extension points to allow the `Blob` type to be persisted.
+Apache Causeway implements the relevant JDO extension points to allow the link:https://causeway.apache.org/refguide/2.0.0-RC1/applib/index/value/Blob.html[Blob] type to be persisted.
 To do so correctly, it requires that the column names for the three constituent parts of a `Blob` are specified using `@Column`:
 
+== About this demo
+
+On the left hand side of this page, four `Blob` properties are defined for a JPA entity, along with a variety of contributed properties and action.
+The properties can variously be edited directly or through actions.
+
+In terms of code:
+
+* the entity class is:
++
 [source,java]
 ----
 include::CausewayBlobJdo.java[tags=class]
 ----
-<.> a no-arg constructor is introduced by JDO enhancer
-<.> required property as defined to JDO/DataNucleus.
+
+* the `readOnlyProperty` (mandatory) property is mapped using:
 +
-Apache Causeway assumes properties are mandatory, so no additional annotation is required.
-<.> directly editable property as defined to Apache Causeway
-<.> optional property as defined to Apache Causeway
-<.> optional property as defined to JDO/DataNucleus
+[source,java]
+----
+include::CausewayBlobJdo.java[tags=property]
+----
+
+* while an optional property is mapped using:
++
+[source,java]
+----
+include::CausewayBlobJdo.java[tags=optional-property]
+----
 
+The remainder of this page describes the mixin actions and label placement for this datatype.
 
-include::../CausewayBlobs-common.adoc[]
+include::../CausewayBlobs-common.adoc[leveloffset=+1]
diff --git a/examples/demo/domain/src/main/java/demoapp/dom/types/causeway/blobs/jdo/CausewayBlobJdo.java b/examples/demo/domain/src/main/java/demoapp/dom/types/causeway/blobs/jdo/CausewayBlobJdo.java
index d836a074ea..df9dcc03ad 100644
--- a/examples/demo/domain/src/main/java/demoapp/dom/types/causeway/blobs/jdo/CausewayBlobJdo.java
+++ b/examples/demo/domain/src/main/java/demoapp/dom/types/causeway/blobs/jdo/CausewayBlobJdo.java
@@ -49,14 +49,14 @@ import demoapp.dom.types.causeway.blobs.persistence.CausewayBlobEntity;
 @DomainObject
 public class CausewayBlobJdo                                            // <.>
         extends CausewayBlobEntity {
-
+    // ...
 //end::class[]
     public CausewayBlobJdo(final Blob initialValue) {
         this.readOnlyProperty = initialValue;
         this.readWriteProperty = initialValue;
     }
 
-//tag::class[]
+//tag::property[]
     @Title(prepend = "Blob JDO entity: ")
     @PropertyLayout(fieldSetId = "read-only-properties", sequence = "1")
     @Persistent(defaultFetchGroup="false", columns = {              // <.>
@@ -66,8 +66,9 @@ public class CausewayBlobJdo                                            // <.>
     })
     @Getter @Setter
     private Blob readOnlyProperty;
+//end::property[]
 
-    @Property(editing = Editing.ENABLED,                            // <.>
+    @Property(editing = Editing.ENABLED,
             optionality = Optionality.MANDATORY)
     @PropertyLayout(fieldSetId = "editable-properties", sequence = "1")
     @Persistent(defaultFetchGroup="false", columns = {
@@ -78,6 +79,7 @@ public class CausewayBlobJdo                                            // <.>
     @Getter @Setter
     private Blob readWriteProperty;
 
+//tag::optional-property[]
     @Property(optionality = Optionality.OPTIONAL)                   // <.>
     @PropertyLayout(fieldSetId = "optional-properties", sequence = "1")
     @Persistent(defaultFetchGroup="false", columns = {
@@ -90,6 +92,7 @@ public class CausewayBlobJdo                                            // <.>
     })
     @Getter @Setter
     private Blob readOnlyOptionalProperty;
+//end::optional-property[]
 
     @Property(editing = Editing.ENABLED, optionality = Optionality.OPTIONAL)
     @PropertyLayout(fieldSetId = "optional-properties", sequence = "2")
diff --git a/examples/demo/domain/src/main/java/demoapp/dom/types/causeway/blobs/jpa/CausewayBlobJpa-description.adoc b/examples/demo/domain/src/main/java/demoapp/dom/types/causeway/blobs/jpa/CausewayBlobJpa-description.adoc
index 59c74967f8..8c6e3b1169 100644
--- a/examples/demo/domain/src/main/java/demoapp/dom/types/causeway/blobs/jpa/CausewayBlobJpa-description.adoc
+++ b/examples/demo/domain/src/main/java/demoapp/dom/types/causeway/blobs/jpa/CausewayBlobJpa-description.adoc
@@ -1,24 +1,37 @@
 :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 this yet is just a copy from JDO
-====
+Apache Causeway supports JPA persistence of the link:https://causeway.apache.org/refguide/2.0.0-RC1/applib/index/value/Blob.html[Blob] type using the link:https://causeway.apache.org/refguide/2.0.0-RC1/persistence/index/jpa/applib/types/BlobJpaEmbeddable.html[BlobJpaEmbeddable] utility class.
+This is declared as a persisted field, while getters and setters expose the `Blob` to the user interface.
 
-Apache Causeway implements the relevant JDO extension points to allow the `Blob` type to be persisted.
-To do so correctly, it requires that the column names for the three constituent parts of a `Blob` are specified using `@Column`:
+== About this demo
 
+On the left hand side of this page, four `Blob` properties are defined for a JPA entity, along with a variety of contributed properties and action.
+The properties can variously be edited directly or through actions.
+
+In terms of code:
+
+* the entity class is:
++
 [source,java]
 ----
 include::CausewayBlobJpa.java[tags=class]
 ----
-<.> a no-arg constructor is introduced by JDO enhancer
-<.> required property as defined to JDO/DataNucleus.
+
+* each field is defined of type `BlobJpaEmbeddable`, mapping the 3 attributes to separate columns.
+For example, the `readOnlyProperty` is mapped using:
++
+[source,java,indent=0]
+----
+include::CausewayBlobJpa.java[tags=field]
+----
+
+* the corresponding getter and setters marshal the `Blob` to and from the user interface:
 +
-Apache Causeway assumes properties are mandatory, so no additional annotation is required.
-<.> directly editable property as defined to Apache Causeway
-<.> optional property as defined to Apache Causeway
-<.> optional property as defined to JDO/DataNucleus
+[source,java,indent=0]
+----
+include::CausewayBlobJpa.java[tags=accessors]
+----
 
+The remainder of this page describes the mixin actions and label placement for this datatype.
 
-include::../CausewayBlobs-common.adoc[]
+include::../CausewayBlobs-common.adoc[leveloffset=+1]
diff --git a/examples/demo/domain/src/main/java/demoapp/dom/types/causeway/blobs/jpa/CausewayBlobJpa.java b/examples/demo/domain/src/main/java/demoapp/dom/types/causeway/blobs/jpa/CausewayBlobJpa.java
index f1c63159c5..acc68f5326 100644
--- a/examples/demo/domain/src/main/java/demoapp/dom/types/causeway/blobs/jpa/CausewayBlobJpa.java
+++ b/examples/demo/domain/src/main/java/demoapp/dom/types/causeway/blobs/jpa/CausewayBlobJpa.java
@@ -58,18 +58,18 @@ import demoapp.dom.types.causeway.blobs.persistence.CausewayBlobEntity;
 @NoArgsConstructor
 public class CausewayBlobJpa
         extends CausewayBlobEntity {
-
+    // ...
 //end::class[]
     public CausewayBlobJpa(final Blob initialValue) {
         setReadOnlyProperty(initialValue);
         setReadWriteProperty(initialValue);
     }
 
-//tag::class[]
     @Id
     @GeneratedValue
     private Long id;
 
+//tag::field[]
     @AttributeOverrides({
         @AttributeOverride(name="name",    column=@Column(name="readOnlyProperty_name")),
         @AttributeOverride(name="mimeType",column=@Column(name="readOnlyProperty_mimeType")),
@@ -77,7 +77,9 @@ public class CausewayBlobJpa
     })
     @Embedded
     private BlobJpaEmbeddable readOnlyProperty;
+//end::field[]
 
+//tag::accessors[]
     @Override
     @Title(prepend = "Blob JPA entity: ")
     @PropertyLayout(fieldSetId = "read-only-properties", sequence = "1")
@@ -88,6 +90,7 @@ public class CausewayBlobJpa
     public void setReadOnlyProperty(final Blob readOnlyProperty) {
         this.readOnlyProperty = BlobJpaEmbeddable.fromBlob(readOnlyProperty);
     }
+//end::accessors[]
 
     @AttributeOverrides({
             @AttributeOverride(name="name",    column=@Column(name="readWriteProperty_name")),
@@ -98,7 +101,7 @@ public class CausewayBlobJpa
     private BlobJpaEmbeddable readWriteProperty;
 
     @Override
-    @Property(editing = Editing.ENABLED)                            // <.>
+    @Property(editing = Editing.ENABLED)
     @PropertyLayout(fieldSetId = "editable-properties", sequence = "1")
     public Blob getReadWriteProperty() {
         return BlobJpaEmbeddable.toBlob(readWriteProperty);
@@ -118,7 +121,7 @@ public class CausewayBlobJpa
     private BlobJpaEmbeddable readOnlyOptionalProperty;
 
     @Override
-    @Property(optionality = Optionality.OPTIONAL)                   // <.>
+    @Property(optionality = Optionality.OPTIONAL)
     @PropertyLayout(fieldSetId = "optional-properties", sequence = "1")
     public Blob getReadOnlyOptionalProperty() {
         return BlobJpaEmbeddable.toBlob(readOnlyOptionalProperty);
@@ -149,5 +152,6 @@ public class CausewayBlobJpa
     public void setReadWriteOptionalProperty(final Blob readWriteOptionalProperty) {
         this.readWriteOptionalProperty = BlobJpaEmbeddable.fromBlob(readWriteOptionalProperty);
     }
+//tag::class[]
 }
 //end::class[]