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/isis.git
The following commit(s) were added to refs/heads/master by this push:
new 0c65bad011 ISIS-2965: improves docs for jdo/jpa mapping
0c65bad011 is described below
commit 0c65bad011206fe065c301b1f8848050406128b8
Author: Dan Haywood <d...@haywood-associates.co.uk>
AuthorDate: Mon Aug 29 23:17:36 2022 +0100
ISIS-2965: improves docs for jdo/jpa mapping
---
.../asciidocs/jpa/IsisAsciiDocJpa-description.adoc | 15 +-
.../isisext/asciidocs/jpa/IsisAsciiDocJpa.java | 2 +-
.../jdo/adoc/modules/ROOT/pages/mapping-guide.adoc | 160 +++++++++++++++++++++
.../jpa/adoc/modules/ROOT/pages/mapping-guide.adoc | 94 +++++++++++-
4 files changed, 258 insertions(+), 13 deletions(-)
diff --git
a/examples/demo/domain/src/main/java/demoapp/dom/types/isisext/asciidocs/jpa/IsisAsciiDocJpa-description.adoc
b/examples/demo/domain/src/main/java/demoapp/dom/types/isisext/asciidocs/jpa/IsisAsciiDocJpa-description.adoc
index a4171897c9..391de105f2 100644
---
a/examples/demo/domain/src/main/java/demoapp/dom/types/isisext/asciidocs/jpa/IsisAsciiDocJpa-description.adoc
+++
b/examples/demo/domain/src/main/java/demoapp/dom/types/isisext/asciidocs/jpa/IsisAsciiDocJpa-description.adoc
@@ -1,23 +1,18 @@
: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
-====
-
-JDO supports `AsciiDoc` out-of-the-box, so no special annotations are required.
+JPA supports `AsciiDoc` out-of-the-box, so no special annotations are required.
[source,java]
----
include::IsisAsciiDocJpa.java[tags=class]
----
-<.> a no-arg constructor is introduced by JDO enhancer
-<.> required property as defined to JDO/DataNucleus.
+<.> a no-arg constructor is required
+<.> required property as defined to JPA/EclipseLink
+
Apache Isis assumes properties are mandatory, so no additional annotation is
required.
<.> directly editable property as defined to Apache Isis
<.> optional property as defined to Apache Isis
-<.> optional property as defined to JDO/DataNucleus
+<.> optional property as defined to JPA/EclipseLink
-include::../IsisAsciiDocs-common.adoc[]
\ No newline at end of file
+include::../IsisAsciiDocs-common.adoc[]
diff --git
a/examples/demo/domain/src/main/java/demoapp/dom/types/isisext/asciidocs/jpa/IsisAsciiDocJpa.java
b/examples/demo/domain/src/main/java/demoapp/dom/types/isisext/asciidocs/jpa/IsisAsciiDocJpa.java
index 729f7b2b53..fbbac406ca 100644
---
a/examples/demo/domain/src/main/java/demoapp/dom/types/isisext/asciidocs/jpa/IsisAsciiDocJpa.java
+++
b/examples/demo/domain/src/main/java/demoapp/dom/types/isisext/asciidocs/jpa/IsisAsciiDocJpa.java
@@ -60,7 +60,7 @@ import
demoapp.dom.types.isisext.asciidocs.persistence.IsisAsciiDocEntity;
@EntityListeners(IsisEntityListener.class)
@Named("demo.IsisAsciiDocEntity")
@DomainObject
-@NoArgsConstructor
+@NoArgsConstructor // <.>
public class IsisAsciiDocJpa
extends IsisAsciiDocEntity {
diff --git a/persistence/jdo/adoc/modules/ROOT/pages/mapping-guide.adoc
b/persistence/jdo/adoc/modules/ROOT/pages/mapping-guide.adoc
index 711def8bf2..5757bea8a1 100644
--- a/persistence/jdo/adoc/modules/ROOT/pages/mapping-guide.adoc
+++ b/persistence/jdo/adoc/modules/ROOT/pages/mapping-guide.adoc
@@ -13,3 +13,163 @@ 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[]
+
+
+== 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.isis.valuetypes</groupId>
+ <artifactId>isis-valuetypes-asciidoc-persistence-jdo</artifactId>
+</dependency>
+----
+
+** and adding reference the corresponding module in the `AppManifest`:
++
+[source,java]
+.AppManifest.java
+----
+@Configuration
+@Import({
+ ...
+ IsisModuleValAsciidocPersistenceJdo.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.isis.valuetypes</groupId>
+ <artifactId>isis-valuetypes-markdown-persistence-jdo</artifactId>
+</dependency>
+----
+
+** and adding reference the corresponding module in the `AppManifest`:
++
+[source,java]
+.AppManifest.java
+----
+@Configuration
+@Import({
+ ...
+ IsisModuleValMarkdownPersistenceJdo.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
+
+
diff --git a/persistence/jpa/adoc/modules/ROOT/pages/mapping-guide.adoc
b/persistence/jpa/adoc/modules/ROOT/pages/mapping-guide.adoc
index bac0147e01..4683cf359b 100644
--- a/persistence/jpa/adoc/modules/ROOT/pages/mapping-guide.adoc
+++ b/persistence/jpa/adoc/modules/ROOT/pages/mapping-guide.adoc
@@ -29,7 +29,97 @@ This section shows how to map each (and can be adapted for
your own custom types
=== Mapping AsciiDoc
-TODO: not really sufficient to use `@Lob`; should provide a custom converter.
+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 `@Lob`:
++
+[source,java]
+.MyEntity.java
+----
+public class MyEntity ... {
+
+ @Column(nullable = false) @Lob @Basic(fetch=FetchType.LAZY)
+ @Property
+ @Getter @Setter
+ private AsciiDoc documentation;
+
+}
+----
+
+* in the webapp module, register the JPA specific converter by:
+
+** adding a dependency to this module:
++
+[source,xml]
+.pom.xml
+----
+<dependency>
+ <groupId>org.apache.isis.valuetypes</groupId>
+ <artifactId>isis-valuetypes-asciidoc-persistence-jpa</artifactId>
+</dependency>
+----
+
+** and adding reference the corresponding module in the `AppManifest`:
++
+[source,java]
+.AppManifest.java
+----
+@Configuration
+@Import({
+ ...
+ IsisModuleValAsciidocPersistenceJpa.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 `@Lob`:
++
+[source,java]
+.MyEntity.java
+----
+public class MyEntity ... {
+
+ @Column(nullable = false) @Lob @Basic(fetch=FetchType.LAZY)
+ @Property
+ @Getter @Setter
+ private Markdown documentation;
+
+}
+----
+
+* in the webapp module, register the JPA specific converter by:
+
+** adding a dependency to this module:
++
+[source,xml]
+.pom.xml
+----
+<dependency>
+ <groupId>org.apache.isis.valuetypes</groupId>
+ <artifactId>isis-valuetypes-markdown-persistence-jpa</artifactId>
+</dependency>
+----
+
+** and adding reference the corresponding module in the `AppManifest`:
++
+[source,java]
+.AppManifest.java
+----
+@Configuration
+@Import({
+ ...
+ IsisModuleValMarkdownPersistenceJpa.java
+ ...
+})
+public class AppManifest {
+}
+----
=== Mapping Blobs and Clobs
@@ -49,7 +139,7 @@ The framework provides an `@Embeddable` classes for each of
`Blob` and `Clob`, e
To map a xref:refguide:applib:index/value/Blob.adoc[Blob], use the
xref:refguide:persistence:index/jpa/applib/types/BlobJpaEmbeddable.adoc[BlobJpaEmbeddable]
class:
-[source]
+[source,java]
.MyEntity.java
----
public class MyEntity ... {
