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 2021/03/31 12:54:43 UTC
[isis] 18/20: ISIS-2484: adds in missing docs
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
commit 58286cb60c02a96bf871f9a96ccb417610d20327
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Wed Mar 31 12:31:24 2021 +0100
ISIS-2484: adds in missing docs
(cherry picked from commit b5d6ab4cbcb51506812aa9c92f06f35c1f7fe769)
---
.../components/docs/modules/ROOT/pages/about.adoc | 6 +-
.../refguide/modules/ROOT/pages/about.adoc | 2 +-
.../setupguide/modules/eclipse/pages/about.adoc | 1 +
.../jdo/adoc/modules/ROOT/pages/db-schemas.adoc | 1 -
.../ROOT/pages/setup-and-configuration.adoc | 210 +++++++++++++++++++--
.../jdo/adoc/modules/ROOT/partials/module-nav.adoc | 1 +
.../jpa/adoc/modules/ROOT/partials/module-nav.adoc | 4 +-
preview.sh | 2 +-
8 files changed, 202 insertions(+), 25 deletions(-)
diff --git a/antora/components/docs/modules/ROOT/pages/about.adoc b/antora/components/docs/modules/ROOT/pages/about.adoc
index e8772e3..5247028 100644
--- a/antora/components/docs/modules/ROOT/pages/about.adoc
+++ b/antora/components/docs/modules/ROOT/pages/about.adoc
@@ -165,9 +165,9 @@ _Reading_
_Academia_
-* link:../ug/fun/_attachments/core-concepts/Pawson-Naked-Objects-thesis.pdf[Naked Objects PhD] (Pawson)
-* https://esc.fnwi.uva.nl/thesis/centraal/files/f270412620.pdf[CLIsis: An interface for Visually Impaired Users] (Bachelors dissertation, Ginn)
-* https://esc.fnwi.uva.nl/thesis/centraal/files/f1051832702.pdf[Using blockchain to validate audit trail data in private business applications] (Masters dissertation, Kalis)
+* link:{attachmentsdir}/Pawson-Naked-Objects-thesis.pdf[Naked Objects] (PhD thesis, Pawson)
+* link:https://esc.fnwi.uva.nl/thesis/centraal/files/f270412620.pdf[CLIsis: An interface for Visually Impaired Users] (Bachelors dissertation, Ginn)
+* link:https://esc.fnwi.uva.nl/thesis/centraal/files/f1051832702.pdf[Using blockchain to validate audit trail data in private business applications] (Masters dissertation, Kalis)
diff --git a/antora/components/refguide/modules/ROOT/pages/about.adoc b/antora/components/refguide/modules/ROOT/pages/about.adoc
index 9028728..faa4a03 100644
--- a/antora/components/refguide/modules/ROOT/pages/about.adoc
+++ b/antora/components/refguide/modules/ROOT/pages/about.adoc
@@ -6,10 +6,10 @@
The reference guides cover:
+* xref:refguide:applib-svc:about.adoc[Domain Services]
* xref:refguide:applib-ant:about.adoc[Annotations]
* xref:refguide:applib-methods:about.adoc[Methods]
* xref:refguide:applib-classes:about.adoc[Classes]
-* xref:refguide:applib-svc:about.adoc[Domain Services]
* xref:refguide:config:about.adoc[Configuration]
* xref:refguide:schema:about.adoc[Schemas]
diff --git a/antora/components/setupguide/modules/eclipse/pages/about.adoc b/antora/components/setupguide/modules/eclipse/pages/about.adoc
index 91e00ee..022fec3 100644
--- a/antora/components/setupguide/modules/eclipse/pages/about.adoc
+++ b/antora/components/setupguide/modules/eclipse/pages/about.adoc
@@ -148,6 +148,7 @@ When the enhancer runs, it will print out to the console:
image::eclipse-120-console.png[width="500px"]
+[#workaround-for-path-limits-the-dn-plugin-to-use-the-persistence-xml]
=== Workaround for path limits (the DN plugin to use the persistence.xml)
If running on Windows then the DataNucleus plugin is very likely to hit the Windows path limit.
diff --git a/persistence/jdo/adoc/modules/ROOT/pages/db-schemas.adoc b/persistence/jdo/adoc/modules/ROOT/pages/db-schemas.adoc
index 77661f9..05b9dc4 100644
--- a/persistence/jdo/adoc/modules/ROOT/pages/db-schemas.adoc
+++ b/persistence/jdo/adoc/modules/ROOT/pages/db-schemas.adoc
@@ -4,7 +4,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: this content has not yet been reviewed/updated for v2.0
In the same way that Java packages act as a namespace for domain objects, it's good practice to map domain entities to their own (database) schemas.
diff --git a/persistence/jdo/adoc/modules/ROOT/pages/setup-and-configuration.adoc b/persistence/jdo/adoc/modules/ROOT/pages/setup-and-configuration.adoc
index 4aed448..40f1b1f 100644
--- a/persistence/jdo/adoc/modules/ROOT/pages/setup-and-configuration.adoc
+++ b/persistence/jdo/adoc/modules/ROOT/pages/setup-and-configuration.adoc
@@ -3,27 +3,201 @@
: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 [...]
-== Classpath and Modules
-The
+== Add dependency to pom.xml
+=== Dependency Management
-The xref:refguide:config:about.adoc[Configuration Guide] includes a xref:refguide:config:sections/jdo-datanucleus.adoc[section] for JDO/Persistence object store, and another xref:refguide:config:sections/jdo-datanucleus-conf.adoc[section] for configuration that is passed through to DataNucleus unchanged.
+If your application inherits from the Apache Isis starter app (`org.apache.isis.app:isis-app-starter-parent` then that will define the version automatically:
+
+[source,xml,subs="attributes+"]
+.pom.xml
+----
+<parent>
+ <groupId>org.apache.isis.app</groupId>
+ <artifactId>isis-app-starter-parent</artifactId>
+ <version>{page-isisrel}</version>
+ <relativePath/>
+</parent>
+----
+
+Alternatively, import the core BOM.
+This is usually done in the top-level parent pom of your application:
+
+[source,xml,subs="attributes+"]
+.pom.xml
+----
+<dependencyManagement>
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.isis.core</groupId>
+ <artifactId>isis-core</artifactId>
+ <version>{page-isisrel}</version>
+ <version>2.0.0-SNAPSHOT</version>
+ <scope>import</scope>
+ <type>pom</type>
+ </dependency>
+ </dependencies>
+</dependencyManagement>
+----
+
+
+=== Dependency
+
+For every Maven module that includes JPA entities, add the following dependency:
+
+[source,xml]
+.pom.xml
+----
+<dependencies>
+ <dependency>
+ <groupId>org.apache.isis.mavendeps</groupId>
+ <artifactId>isis-mavendeps-jpa</artifactId>
+ <type>pom</type>
+ </dependency>
+</dependencies>
+----
+
+
+== Update AppManifest
+
+In your application's `AppManifest` (top-level Spring `@Configuration` used to bootstrap the app), import the
+
+[source,java]
+.AppManifest.java
+----
+@Configuration
+@Import({
+ ...
+ IsisModuleJpaEclipselink.class,
+ ...
+})
+public class AppManifest {
+}
+----
+
+== DataSource
+
+The JPA object store uses Spring to provide a `javax.sql.DataSource`.
+Normally this is done by setting the `spring.datasource` configuration properties, as described in the
+link:https://docs.spring.io/spring-boot/docs/current/reference/html/spring-boot-features.html#boot-features-connect-to-production-database-configuration[Spring Boot] documentation.
+
+For example, the xref:docs:starters:simpleapp.adoc[SimpleApp] starter app defines these:
+
+* for H2 (in-memory):
++
+[source,properties]
+.app.properties
+----
+spring.datasource.platform=h2
+spring.datasource.url=jdbc:h2:mem:simple
+spring.datasource.driver-class-name=org.h2.Driver
+----
+
+* for SQL Server:
++
+[source,properties]
+.app.properties
+----
+spring.datasource.platform=sqlserver
+spring.datasource.url=jdbc:sqlserver://localhost;databaseName=simpleapp
+spring.datasource.driver-class-name=com.microsoft.sqlserver.jdbc.SQLServerDriver
+spring.datasource.username=simpleapp
+spring.datasource.password=simpleapp
+----
+
+It is also possible to programmatically define a `DataSource`; see the link:https://docs.spring.io/spring-boot/docs/current/reference/html/howto.html#howto-data-access[Spring docs] for details.
+
+
+== Create Schema
+
+It's good practice to use link:https://crate.io/docs/sql-99/en/latest/chapters/17.html#create-schema-statement[SQL schemas] as a way to organise database tables into groups.
+We recommend all the entities within a module use the same schema, and moreover that the xref:refguide:applib:index/annotation/DomainObject.adoc#objectType[object type] also follows the same pattern.
+
+For example:
+
+[source,java]
+----
+@javax.persistence.Entity
+@javax.persistence.Table(
+ schema="SIMPLE", // <.>
+ ...
+)
+@DomainObject(objectType = "simple.SimpleObject") // <.>
+...
+public class SimpleObject ... {
+
+}
+----
+<.> specifies the database schema.
+The table name will be based on the entity
+<.> corresponding two-part object type.
+
+When prototyping we rely on the ORM to automatically create the entire database tables, which includes the owning schemas.
+As EclipseLink does not do this automatically, the framework will do this if requested.
+The xref:refguide:config:sections/isis.persistence.schema.adoc#isis.persistence.schema.auto-create-schemas[isis.persistence.schema.auto-create-schemas] controls if this is done or not.
+
+Different database vendors have different syntaxes to do this, and so this can be configured using the xref:refguide:config:sections/isis.persistence.schema.adoc#isis.persistence.schema.create-schema-sql-template[isis.persistence.schema.create-schema-sql-template].
+The default value is to use SQL-99 syntax ("CREATE SCHEMA IF NOT EXISTS %S"), passed through to `String.format()`.
+
+
+
+[[persistence-xml]]
+== `persistence.xml`
+
+DataNucleus will for itself also read the `META-INF/persistence.xml`.
+In theory this can hold mappings and even connection strings.
+However, with Apache Isis we tend to use annotations instead and externalize connection strings. so its definition is extremely simply, specifying just the name of the "persistence unit".
+
+Here's the one provided by the xref:docs:starters:simpleapp.adoc[SimpleApp] starter app:
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8" ?>
+<persistence xmlns="http://java.sun.com/xml/ns/persistence"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd" version="1.0">
+
+ <persistence-unit name="simple">
+ </persistence-unit>
+</persistence>
+----
+
+Normally all one needs to do is to change the `persistence-unit` name.
+
+[TIP]
+====
+If you use Eclipse IDE on Windows then
+xref:setupguide:eclipse:about.adoc#workaround-for-path-limits-the-dn-plugin-to-use-the-persistence-xml[note the importance] of the `persistence.xml` file to make DataNucleus enhancer work correctly.
+====
+
+
+See link:http://www.datanucleus.org/products/datanucleus/jdo/persistence.html#persistenceunit[DataNucleus' documentation] on `persistence.xml` to learn more.
+
+
+== Other Configuration Properties
+
+
+Additional configuration properties for DataNucleus itself can be specified directly under the `datanucleus.` configuration key.
+
+We recommend that some of these should be configured:
+
+* disable xref:configuring/disabling-persistence-by-reachability.adoc[persistence by reachability]
+
+
+
+See the xref:refguide:config:sections/datanucleus.adoc[datanucleus] section of the xref:refguide:config:about.adoc[Configuration Guide] for further details.
+
+
+Furthermore, DataNucleus will search for various other XML mapping files, eg `mappings.jdo`.
+A full list can be found http://www.datanucleus.org/products/datanucleus/jdo/metadata.html[here].
+
+[IMPORTANT]
+====
+DataNucleus properties must be specified using `camelCase`, not `kebab-case`.
+
+For example, use
+====
-//WARNING: TODO - v2 - detail on original config properties (not yet reviewed) currently commented out.
-//Apache Isis programmatically configures DataNucleus; any Apache Isis properties with the prefix `isis.persistence.jdo-datanucleus.impl` are passed through directly to the JDO/DataNucleus objectstore (with the prefix stripped off, of course).
-//
-//DataNucleus will for itself also and read the `META-INF/persistence.xml`; at a minimum this defines the name of the "persistence unit".
-//In theory it could also hold mappings, though in Apache Isis we tend to use annotations instead.
-//
-//Furthermore, DataNucleus will search for various other XML mapping files, eg `mappings.jdo`.
-//A full list can be found http://www.datanucleus.org/products/datanucleus/jdo/metadata.html[here].
-//The metadata in these XML can be used to override the annotations of annotated entities; see xref:userguide:btb:about.adoc#overriding-jdo-annotations[Overriding JDO Annotatons] for further discussion.
-//
//
-//include::configuring/properties.adoc[leveloffset=+1]
-//include::configuring/bulk-load.adoc[leveloffset=+1]
-//include::configuring/disabling-persistence-by-reachability.adoc[leveloffset=+1]
-//include::configuring/persistence-xml.adoc[leveloffset=+1]
-//include::configuring/using-jndi-data-source.adoc[leveloffset=+1]
diff --git a/persistence/jdo/adoc/modules/ROOT/partials/module-nav.adoc b/persistence/jdo/adoc/modules/ROOT/partials/module-nav.adoc
index cda6568..a0273ae 100644
--- a/persistence/jdo/adoc/modules/ROOT/partials/module-nav.adoc
+++ b/persistence/jdo/adoc/modules/ROOT/partials/module-nav.adoc
@@ -1,6 +1,7 @@
* xref:pjdo:ROOT:setup-and-configuration.adoc[Setup and Configuration]
+** xref:pjdo:ROOT:configuring/disabling-persistence-by-reachability.adoc[Disabling Persistence by Reachability]
* xref:pjdo:ROOT:jdo-mappings.adoc[JDO Mappings]
* xref:pjdo:ROOT:db-schemas.adoc[DB Schemas]
* xref:pjdo:ROOT:hints-and-tips.adoc[Hints-n-Tips]
diff --git a/persistence/jpa/adoc/modules/ROOT/partials/module-nav.adoc b/persistence/jpa/adoc/modules/ROOT/partials/module-nav.adoc
index 4a1e269..0cf07e4 100644
--- a/persistence/jpa/adoc/modules/ROOT/partials/module-nav.adoc
+++ b/persistence/jpa/adoc/modules/ROOT/partials/module-nav.adoc
@@ -1 +1,3 @@
-* xref:pjpa:ROOT:other-resources.adoc[Other Resources]
+* xref:pjpa:ROOT:setup-and-configuration.adoc[Setup and Configuration]
+* xref:pjpa:ROOT:applib.adoc[JPA Applib]
+* xref:pjpa:ROOT:mapping-guide.adoc[Mapping Guide]
diff --git a/preview.sh b/preview.sh
index 5c99588..715501e 100644
--- a/preview.sh
+++ b/preview.sh
@@ -12,7 +12,7 @@ export ANTORA_TARGET_SITE=antora/target/site
#
PLAYBOOK_FILE=antora/playbooks/site.yml
-while getopts 'ECDAKSLecdaksxyhfl:' opt
+while getopts 'ECDAKSLecdaksxylhf:' opt
do
case $opt in
E) export SKIP_EXAMPLES=false