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:42:36 UTC
[isis] branch ISIS-2484 updated (ec5baae -> c24f2fb)
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a change to branch ISIS-2484
in repository https://gitbox.apache.org/repos/asf/isis.git.
from ec5baae Revert "Bump structurizr.version from 1.6.2 to 1.6.3"
new e92c2ff ISIS-2484: updating docs on JDO and JPA
new 46e10ee ISIS-2484: adds back in docs
new b5d6ab4 ISIS-2484: adds in missing docs
new c24f2fb ISIS-2484: updates docs for JPA and JDO
The 4 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
.../attachments}/Pawson-Naked-Objects-thesis.pdf | Bin
.../components/docs/modules/ROOT/pages/about.adoc | 6 +-
.../JdoSupportService_010-examples-and-usage.adoc | 19 +-
.../refguide/modules/ROOT/pages/about.adoc | 2 +-
.../setupguide/modules/eclipse/pages/about.adoc | 4 +-
antora/playbooks/site-persistence.yml | 6 +
antora/playbooks/site-security.yml | 3 +
antora/playbooks/site.yml | 3 +
.../config/partials/configuring-schemas.adoc | 24 +++
persistence/jdo/adoc/modules/ROOT/pages/about.adoc | 5 +-
.../modules/ROOT/pages/configuring/bulk-load.adoc | 35 ---
.../disabling-persistence-by-reachability.adoc | 1 +
.../ROOT/pages/configuring/persistence-xml.adoc | 36 ----
.../modules/ROOT/pages/configuring/properties.adoc | 15 --
.../pages/configuring/using-jndi-data-source.adoc | 75 -------
.../jdo/adoc/modules/ROOT/pages/db-schemas.adoc | 131 +-----------
.../modules/ROOT/pages/dependency-injection.adoc | 13 +-
.../adoc/modules/ROOT/pages/hints-and-tips.adoc | 4 -
.../jdo/adoc/modules/ROOT/pages/jdo-mappings.adoc | 11 -
.../jdo/adoc/modules/ROOT/pages/mapping-guide.adoc | 17 +-
.../mandatory-properties-in-subtypes.adoc | 0
.../mapping-to-a-view.adoc | 0
.../one-to-m-bidirectional-relationships.adoc | 0
.../ROOT/pages/setup-and-configuration.adoc | 238 ++++++++++++++++++---
.../jdo/adoc/modules/ROOT/partials/module-nav.adoc | 13 +-
persistence/jpa/adoc/modules/ROOT/nav.adoc | 2 +-
persistence/jpa/adoc/modules/ROOT/pages/about.adoc | 8 +-
.../jpa/adoc/modules/ROOT/pages/db-schemas.adoc | 37 ++++
.../modules/ROOT/pages/dependency-injection.adoc | 23 +-
.../adoc/modules/ROOT/pages/domain-services.adoc | 13 +-
.../jpa/adoc/modules/ROOT/pages/mapping-guide.adoc | 17 +-
.../ROOT/pages/setup-and-configuration.adoc | 123 +++++++++++
.../jpa/adoc/modules/ROOT/partials/module-nav.adoc | 6 +
preview.sh | 2 +-
.../adoc/modules/ROOT/partials/component-nav.adoc | 7 +-
.../{shiro => spring}/src/main/adoc/antora.yml | 0
.../src/main/adoc/modules/spring}/nav.adoc | 0
.../src/main/adoc/modules/spring/pages/about.adoc | 7 +-
.../adoc/modules/spring/partials/module-nav.adoc | 2 +
.../adoc/modules/ROOT/pages/about.adoc | 2 +-
.../adoc/modules/ROOT/pages/architecture.adoc | 2 +-
.../adoc/modules/ROOT/pages/other-resources.adoc | 5 +-
.../adoc/modules/ROOT/partials/module-nav.adoc | 2 +
viewers/wicket/adoc/modules/ROOT/pages/about.adoc | 2 +-
.../adoc/modules/ROOT/pages/other-resources.adoc | 5 +-
.../adoc/modules/ROOT/partials/module-nav.adoc | 2 +
46 files changed, 525 insertions(+), 403 deletions(-)
rename antora/components/{userguide/modules/fun/attachments/core-concepts => docs/modules/ROOT/attachments}/Pawson-Naked-Objects-thesis.pdf (100%)
rename persistence/jdo/adoc/modules/ROOT/pages/services/IsisJdoSupport.adoc => antora/components/refguide-index/modules/persistence/pages/index/jdo/applib/services/hooks/JdoSupportService_010-examples-and-usage.adoc (98%)
create mode 100644 core/config/src/main/adoc/modules/config/partials/configuring-schemas.adoc
delete mode 100644 persistence/jdo/adoc/modules/ROOT/pages/configuring/bulk-load.adoc
delete mode 100644 persistence/jdo/adoc/modules/ROOT/pages/configuring/persistence-xml.adoc
delete mode 100644 persistence/jdo/adoc/modules/ROOT/pages/configuring/properties.adoc
delete mode 100644 persistence/jdo/adoc/modules/ROOT/pages/configuring/using-jndi-data-source.adoc
copy antora/components/docs/modules/ROOT/partials/module-nav/guides.adoc => persistence/jdo/adoc/modules/ROOT/pages/dependency-injection.adoc (74%)
delete mode 100644 persistence/jdo/adoc/modules/ROOT/pages/jdo-mappings.adoc
copy antora/components/conguide/modules/eclipse/pages/about.adoc => persistence/jdo/adoc/modules/ROOT/pages/mapping-guide.adoc (56%)
rename persistence/jdo/adoc/modules/ROOT/pages/{jdo-mappings => mapping-guide}/mandatory-properties-in-subtypes.adoc (100%)
rename persistence/jdo/adoc/modules/ROOT/pages/{jdo-mappings => mapping-guide}/mapping-to-a-view.adoc (100%)
rename persistence/jdo/adoc/modules/ROOT/pages/{jdo-mappings => mapping-guide}/one-to-m-bidirectional-relationships.adoc (100%)
create mode 100644 persistence/jpa/adoc/modules/ROOT/pages/db-schemas.adoc
copy antora/components/refguide-index/modules/applib/pages/index/jaxb/JavaSqlJaxbAdapters.adoc => persistence/jpa/adoc/modules/ROOT/pages/dependency-injection.adoc (63%)
copy antora/components/docs/modules/ROOT/partials/module-nav/guides.adoc => persistence/jpa/adoc/modules/ROOT/pages/domain-services.adoc (73%)
copy viewers/wicket/adoc/modules/ROOT/pages/about.adoc => persistence/jpa/adoc/modules/ROOT/pages/mapping-guide.adoc (53%)
create mode 100644 persistence/jpa/adoc/modules/ROOT/pages/setup-and-configuration.adoc
copy security/{shiro => spring}/src/main/adoc/antora.yml (100%)
copy security/{shiro/src/main/adoc/modules/shiro => spring/src/main/adoc/modules/spring}/nav.adoc (100%)
copy viewers/restfulobjects/adoc/modules/ROOT/pages/security.adoc => security/spring/src/main/adoc/modules/spring/pages/about.adoc (84%)
create mode 100644 security/spring/src/main/adoc/modules/spring/partials/module-nav.adoc
copy antora/components/docs/modules/ROOT/pages/what-is-apache-isis/common-use-cases.adoc => viewers/restfulobjects/adoc/modules/ROOT/pages/other-resources.adoc (87%)
copy antora/components/docs/modules/ROOT/pages/what-is-apache-isis/common-use-cases.adoc => viewers/wicket/adoc/modules/ROOT/pages/other-resources.adoc (87%)
[isis] 03/04: ISIS-2484: adds in missing docs
Posted by da...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch ISIS-2484
in repository https://gitbox.apache.org/repos/asf/isis.git
commit b5d6ab4cbcb51506812aa9c92f06f35c1f7fe769
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Wed Mar 31 12:31:24 2021 +0100
ISIS-2484: adds in missing docs
---
.../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
[isis] 01/04: ISIS-2484: updating docs on JDO and JPA
Posted by da...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch ISIS-2484
in repository https://gitbox.apache.org/repos/asf/isis.git
commit e92c2ff3afb1eff320793dabeb8f43d84fbe85b1
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Wed Mar 31 11:26:00 2021 +0100
ISIS-2484: updating docs on JDO and JPA
---
.../attachments}/Pawson-Naked-Objects-thesis.pdf | Bin
antora/playbooks/site-security.yml | 3 +
antora/playbooks/site.yml | 3 +
persistence/jdo/adoc/modules/ROOT/pages/about.adoc | 5 +-
.../modules/ROOT/pages/configuring/bulk-load.adoc | 35 ----------
.../disabling-persistence-by-reachability.adoc | 1 +
.../ROOT/pages/configuring/persistence-xml.adoc | 36 ----------
.../modules/ROOT/pages/configuring/properties.adoc | 15 -----
.../pages/configuring/using-jndi-data-source.adoc | 75 ---------------------
.../adoc/modules/ROOT/pages/other-resources.adoc} | 7 +-
.../jdo/adoc/modules/ROOT/partials/module-nav.adoc | 1 +
persistence/jpa/adoc/modules/ROOT/pages/about.adoc | 8 ++-
.../module-nav.adoc => pages/applib.adoc} | 0
.../jpa/adoc/modules/ROOT/pages/mapping-guide.adoc | 19 ++++--
.../{about.adoc => setup-and-configuration.adoc} | 8 ++-
.../jpa/adoc/modules/ROOT/partials/module-nav.adoc | 1 +
.../adoc/modules/ROOT/partials/component-nav.adoc | 7 +-
security/spring/src/main/adoc/antora.yml | 19 ++++++
.../spring/src/main/adoc/modules/spring/nav.adoc | 6 +-
.../src/main/adoc/modules/spring}/pages/about.adoc | 8 ++-
.../adoc/modules/spring/partials/module-nav.adoc | 2 +
.../adoc/modules/ROOT/pages/about.adoc | 2 +-
.../adoc/modules/ROOT/pages/other-resources.adoc | 7 +-
.../adoc/modules/ROOT/partials/module-nav.adoc | 2 +
viewers/wicket/adoc/modules/ROOT/pages/about.adoc | 2 +-
.../adoc/modules/ROOT/pages/other-resources.adoc | 7 +-
.../adoc/modules/ROOT/partials/module-nav.adoc | 2 +
27 files changed, 83 insertions(+), 198 deletions(-)
diff --git a/antora/components/userguide/modules/fun/attachments/core-concepts/Pawson-Naked-Objects-thesis.pdf b/antora/components/docs/modules/ROOT/attachments/Pawson-Naked-Objects-thesis.pdf
similarity index 100%
rename from antora/components/userguide/modules/fun/attachments/core-concepts/Pawson-Naked-Objects-thesis.pdf
rename to antora/components/docs/modules/ROOT/attachments/Pawson-Naked-Objects-thesis.pdf
diff --git a/antora/playbooks/site-security.yml b/antora/playbooks/site-security.yml
index bc4637e..581162d 100644
--- a/antora/playbooks/site-security.yml
+++ b/antora/playbooks/site-security.yml
@@ -70,6 +70,9 @@ content:
- url: .
start_path: security/keycloak/src/main/adoc # security
branches: HEAD
+ - url: .
+ start_path: security/spring/src/main/adoc # security
+ branches: HEAD
# starters
diff --git a/antora/playbooks/site.yml b/antora/playbooks/site.yml
index 52bd79c..67403a2 100644
--- a/antora/playbooks/site.yml
+++ b/antora/playbooks/site.yml
@@ -236,6 +236,9 @@ content:
- url: .
start_path: security/keycloak/src/main/adoc # security
branches: HEAD
+ - url: .
+ start_path: security/spring/src/main/adoc # security
+ branches: HEAD
# starters
- url: .
diff --git a/persistence/jdo/adoc/modules/ROOT/pages/about.adoc b/persistence/jdo/adoc/modules/ROOT/pages/about.adoc
index a322fec..4cb5be3 100644
--- a/persistence/jdo/adoc/modules/ROOT/pages/about.adoc
+++ b/persistence/jdo/adoc/modules/ROOT/pages/about.adoc
@@ -4,9 +4,10 @@
The JDO/DataNucleus object store enables domain objects to be persisted to relational as well as NoSQL databases.
-The object store is implemented using link:http://datanucleus.org[DataNucleus] ORM.
+The object store is implemented using link:http://datanucleus.org[DataNucleus] ORM using the link:https://www.jcp.org/en/jsr/detail?id=243[JDO] API.
+DataNucleus is the reference implementation for JDO.
-This user guide discuss how to setup the framework to use the JDO/DataNucleus object store, how to configure the ORM, and also provides some examples on common use cases.
+This component guide discuss how to setup the framework to use the JDO/DataNucleus object store, how to configure the ORM, and also provides some examples on common use cases.
diff --git a/persistence/jdo/adoc/modules/ROOT/pages/configuring/bulk-load.adoc b/persistence/jdo/adoc/modules/ROOT/pages/configuring/bulk-load.adoc
deleted file mode 100644
index 8032583..0000000
--- a/persistence/jdo/adoc/modules/ROOT/pages/configuring/bulk-load.adoc
+++ /dev/null
@@ -1,35 +0,0 @@
-[[bulk-load]]
-= Bulk Load of Standalone Collections
-
-: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 implementation of user interactions (meaning either an action invocations or a property edits) in the xref:vw:ROOT:about.adoc[Wicket viewer] is splits into two.
-The first phase performs the actual interaction, with the results (dirtied objects) flushed to the database.
-The second phase then renders the results of the interaction.
-
-When the user interaction in question is an action invocation that returns a list of objects, the resultant list is not rendered in the first phase.
-Instead, only the IDs of the objects in the list are captured.
-When the list is then rendered, the framework re-loads each object.
-
-The default implementation does this row-by-row, resulting in multiple queries against the database.
-Setting the property:
-
-[source,ini]
-----
-isis.persistor.datanucleus.standaloneCollection.bulkLoad=true
-----
-
-changes to a more efficient implementation that bulk loads all the objects using a single query.
-
-
-[NOTE]
-====
-In the future the bulkLoad implementation may be made the default.
-====
-
-[NOTE]
-====
-The implementation of parented collections does not suffer from this issue; the rendering phase runs the query to obtain the matches.
-====
-
diff --git a/persistence/jdo/adoc/modules/ROOT/pages/configuring/disabling-persistence-by-reachability.adoc b/persistence/jdo/adoc/modules/ROOT/pages/configuring/disabling-persistence-by-reachability.adoc
index aaee4d1..276df40 100644
--- a/persistence/jdo/adoc/modules/ROOT/pages/configuring/disabling-persistence-by-reachability.adoc
+++ b/persistence/jdo/adoc/modules/ROOT/pages/configuring/disabling-persistence-by-reachability.adoc
@@ -31,6 +31,7 @@ This change has been made to both the xref:docs:starters:helloworld.adoc[HelloWo
If you do disable this feature, then you will (of course) need to ensure that you explicitly persist all entities using the `RepositoryService#persist(.)` or `RepositoryService#persistAndFlush(.)` methods.
+
== The issue in more detail
Consider these entities (http://yuml.me/edit/b8681268[yuml.me/b8681268]):
diff --git a/persistence/jdo/adoc/modules/ROOT/pages/configuring/persistence-xml.adoc b/persistence/jdo/adoc/modules/ROOT/pages/configuring/persistence-xml.adoc
deleted file mode 100644
index 1b8efac..0000000
--- a/persistence/jdo/adoc/modules/ROOT/pages/configuring/persistence-xml.adoc
+++ /dev/null
@@ -1,36 +0,0 @@
-[[persistence-xml]]
-= `persistence.xml`
-
-: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 [...]
-
-
-
-DataNucleus will for itself also and read the `META-INF/persistence.xml`.
-In theory it 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.
diff --git a/persistence/jdo/adoc/modules/ROOT/pages/configuring/properties.adoc b/persistence/jdo/adoc/modules/ROOT/pages/configuring/properties.adoc
deleted file mode 100644
index 73c7a87..0000000
--- a/persistence/jdo/adoc/modules/ROOT/pages/configuring/properties.adoc
+++ /dev/null
@@ -1,15 +0,0 @@
-[[properties]]
-= Configuration Properties
-
-: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 connection to the database is specified using Spring's link:https://docs.spring.io/spring-boot/docs/current/reference/html/spring-boot-features.html#boot-features-connect-to-production-database-configuration[datasource properties]: `spring.datasource.url` and its kin.
-
-
-DataNucleus configuration properties can be specified and are passed through directly.
-Some of the most common can be found through "intellisense" on `application.properties` or `application.yml`, if your IDE supports it.
-These are listed in the xref:refguide:config:sections/datanucleus.adoc[datanucleus section] of the xref:refguide:config:about.adoc[Configuration Guide].
-
-There are also some configuration properties that Apache Isis defines that applies to both JDO and JPA.
-These can be found in the xref:refguide:config:sections/isis.persistence.schema.adoc[isis.persistence.schema] section of the Configuratoin Guide.
-
diff --git a/persistence/jdo/adoc/modules/ROOT/pages/configuring/using-jndi-data-source.adoc b/persistence/jdo/adoc/modules/ROOT/pages/configuring/using-jndi-data-source.adoc
deleted file mode 100644
index f39a984..0000000
--- a/persistence/jdo/adoc/modules/ROOT/pages/configuring/using-jndi-data-source.adoc
+++ /dev/null
@@ -1,75 +0,0 @@
-[[using-jndi-data-source]]
-= Using JNDI DataSource
-
-: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 - v2 - not yet reviewed/updated.
-
-Apache Isis' JDO objectstore can be configured either to connect to the database using its own connection pool, or by using a container-managed datasource.
-
-== Application managed
-
-Using a connection pool managed directly by the application (that is, by Apache Isis' JDO objectstore and ultimately by DataNucleus) requires a single set of configuration properties to be specified.
-
-Specify the connection driver, url, username and password.
-For example:
-
-[source,ini]
-----
-javax.jdo.option.ConnectionDriverName=net.sf.log4jdbc.DriverSpy
-javax.jdo.option.ConnectionURL=jdbc:log4jdbc:hsqldb:mem:test
-javax.jdo.option.ConnectionUserName=sa
-javax.jdo.option.ConnectionPassword=
-----
-
-
-It is also possible to specify the `datanucleus.ConnectionPasswordDecrypter` property;
-see the link:http://www.datanucleus.org/products/accessplatform_4_1/persistence_properties.html#ConnectionPasswordDecrypter[DataNucleus documentation] for further details.
-
-
-
-
-== Container managed (JNDI)
-
-Using a datasource managed by the servlet container requires three separate bits of configuration.
-
-Firstly, specify the name of the datasource in the `WEB-INF\persistor_datanucleus.properties` file. For example:
-
-If connection pool settings are also present in this file, they will simply be ignored. Any other configuration properties are passed through directly to DataNucleus.
-
-Secondly, in the `WEB-INF/web.xml`, declare the resource reference:
-
-[source,xml]
-----
-<resource-ref>
- <description>db</description>
- <res-ref-name>jdbc/simpleapp</res-ref-name>
- <res-type>javax.sql.DataSource</res-type>
- <res-auth>Container</res-auth>
-</resource-ref>
-----
-
-Finally, declare the datasource as required by the servlet container. For example, if using Tomcat 7, the datasource can be specified by adding the following to `$TOMCAT_HOME/conf/context.xml`:
-
-[source,xml]
-----
-<Resource name="jdbc/simpleapp"
- auth="Container"
- type="javax.sql.DataSource"
- maxActive="100"
- maxIdle="30"
- maxWait="10000"
- username="sa"
- password="p4ssword"
- driverClassName="com.microsoft.sqlserver.jdbc.SQLServerDriver"
- url="jdbc:sqlserver://127.0.0.1:1433;instance=.;databaseName=simpleapp"/>
-----
-
-You will also need to make sure that the JDBC driver is on the servlet container's classpath. For Tomcat, this means copying the driver to `$TOMCAT_HOME/lib`.
-
-[NOTE]
-====
-According to Tomcat's documentation, it is supposedly possible to copy the `conf/context.xml` to the name of the webapp, eg `conf/mywebapp.xml`, and scope the connection to that webapp only. I was unable to get this working, however.
-====
-
diff --git a/persistence/jpa/adoc/modules/ROOT/pages/about.adoc b/persistence/jdo/adoc/modules/ROOT/pages/other-resources.adoc
similarity index 87%
copy from persistence/jpa/adoc/modules/ROOT/pages/about.adoc
copy to persistence/jdo/adoc/modules/ROOT/pages/other-resources.adoc
index b977118..8aab42b 100644
--- a/persistence/jpa/adoc/modules/ROOT/pages/about.adoc
+++ b/persistence/jdo/adoc/modules/ROOT/pages/other-resources.adoc
@@ -1,8 +1,7 @@
-= JPA
+= Other Resources
: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 [...]
+:page-aliases: guides:ugvw:ugvw.adoc
-:page-toc: ~
-
-WARNING: TODO: v2 - to document.
+WARNING: TODO: document 3rd party tutorials and resources.
diff --git a/persistence/jdo/adoc/modules/ROOT/partials/module-nav.adoc b/persistence/jdo/adoc/modules/ROOT/partials/module-nav.adoc
index 5d752ed..cda6568 100644
--- a/persistence/jdo/adoc/modules/ROOT/partials/module-nav.adoc
+++ b/persistence/jdo/adoc/modules/ROOT/partials/module-nav.adoc
@@ -6,3 +6,4 @@
* xref:pjdo:ROOT:hints-and-tips.adoc[Hints-n-Tips]
* Domain Services
** xref:pjdo:ROOT:services/IsisJdoSupport.adoc[IsisJdoSupport]
+* xref:pjdo:ROOT:other-resources.adoc[Other Resources]
diff --git a/persistence/jpa/adoc/modules/ROOT/pages/about.adoc b/persistence/jpa/adoc/modules/ROOT/pages/about.adoc
index b977118..4048e64 100644
--- a/persistence/jpa/adoc/modules/ROOT/pages/about.adoc
+++ b/persistence/jpa/adoc/modules/ROOT/pages/about.adoc
@@ -2,7 +2,11 @@
: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 [...]
-:page-toc: ~
-WARNING: TODO: v2 - to document.
+
+The JPA/EclipseLink object store enables domain objects to be persisted to relational databases.
+The object store is implemented using the link:https://www.eclipse.org/eclipselink/[EclipseLink] ORM, using the link:https://www.jcp.org/en/jsr/detail?id=317[JPA] API.
+EclipseLink is the reference implementation for JPA.
+
+This component guide discuss how to setup the framework to use the JPA/EclipseLink object store, how to configure the ORM, and also provides some examples on common use cases.
diff --git a/persistence/jpa/adoc/modules/ROOT/partials/module-nav.adoc b/persistence/jpa/adoc/modules/ROOT/pages/applib.adoc
similarity index 100%
copy from persistence/jpa/adoc/modules/ROOT/partials/module-nav.adoc
copy to persistence/jpa/adoc/modules/ROOT/pages/applib.adoc
diff --git a/viewers/wicket/adoc/modules/ROOT/pages/about.adoc b/persistence/jpa/adoc/modules/ROOT/pages/mapping-guide.adoc
similarity index 51%
copy from viewers/wicket/adoc/modules/ROOT/pages/about.adoc
copy to persistence/jpa/adoc/modules/ROOT/pages/mapping-guide.adoc
index 8d05228..22c7ab3 100644
--- a/viewers/wicket/adoc/modules/ROOT/pages/about.adoc
+++ b/persistence/jpa/adoc/modules/ROOT/pages/mapping-guide.adoc
@@ -1,15 +1,22 @@
-= Wicket Viewer
+= Other Resources
: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 [...]
:page-aliases: guides:ugvw:ugvw.adoc
-WARNING: TODO: this content has not yet been reviewed/updated for v2.0
-The Wicket Viewer automatically exposes an Apache Isis domain object model for use by end-users.
-The viewer is implemented using link:http://wicket.apache.org[Apache Wicket].
+There are plenty of resources for learning JPA annotations.
+Take a look at:
-This user guide discuss end-user features, configuration and customization of the Wicket viewer.
+* link:https://spring.io/guides/gs/accessing-data-jpa/[Spring Boot: Accessing Data with JPA]
-It also discusses how to extend the viewer, and lists a number of extensions available.
+* link:https://github.com/spring-projects/spring-data-book/tree/master/jpa/src/main/java/com/oreilly/springdata/jpa[Spring Daata Book - sample code showing several entities]
+* link:https://www.vogella.com/tutorials/JavaPersistenceAPI/article.html[Vogella JPA tutorial]
+
+* link:https://docs.jboss.org/hibernate/annotations/3.5/reference/en/html/entity.html[JBoss reference guide]
++
+Although written for Hibernate, the JPA material should work fine.
+
+* link:https://www.baeldung.com/tag/jpa/[JPA Baeldung tags]
+** link:https://www.baeldung.com/jpa-entities[entities]
diff --git a/persistence/jpa/adoc/modules/ROOT/pages/about.adoc b/persistence/jpa/adoc/modules/ROOT/pages/setup-and-configuration.adoc
similarity index 60%
copy from persistence/jpa/adoc/modules/ROOT/pages/about.adoc
copy to persistence/jpa/adoc/modules/ROOT/pages/setup-and-configuration.adoc
index b977118..4048e64 100644
--- a/persistence/jpa/adoc/modules/ROOT/pages/about.adoc
+++ b/persistence/jpa/adoc/modules/ROOT/pages/setup-and-configuration.adoc
@@ -2,7 +2,11 @@
: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 [...]
-:page-toc: ~
-WARNING: TODO: v2 - to document.
+
+The JPA/EclipseLink object store enables domain objects to be persisted to relational databases.
+The object store is implemented using the link:https://www.eclipse.org/eclipselink/[EclipseLink] ORM, using the link:https://www.jcp.org/en/jsr/detail?id=317[JPA] API.
+EclipseLink is the reference implementation for JPA.
+
+This component guide discuss how to setup the framework to use the JPA/EclipseLink object store, how to configure the ORM, and also provides some examples on common use cases.
diff --git a/persistence/jpa/adoc/modules/ROOT/partials/module-nav.adoc b/persistence/jpa/adoc/modules/ROOT/partials/module-nav.adoc
index e69de29..4a1e269 100644
--- a/persistence/jpa/adoc/modules/ROOT/partials/module-nav.adoc
+++ b/persistence/jpa/adoc/modules/ROOT/partials/module-nav.adoc
@@ -0,0 +1 @@
+* xref:pjpa:ROOT:other-resources.adoc[Other Resources]
diff --git a/security/adoc/modules/ROOT/partials/component-nav.adoc b/security/adoc/modules/ROOT/partials/component-nav.adoc
index 80307c6..ffbabc4 100644
--- a/security/adoc/modules/ROOT/partials/component-nav.adoc
+++ b/security/adoc/modules/ROOT/partials/component-nav.adoc
@@ -4,14 +4,15 @@ include::security:core:partial$module-nav.adoc[]
include::security:bypass:partial$module-nav.adoc[]
include::security:shiro:partial$module-nav.adoc[]
include::security:keycloak:partial$module-nav.adoc[]
+include::security:spring:partial$module-nav.adoc[]
include::security:ROOT:partial$module-nav-end.adoc[]
* Extensions
-// commented out the libraries that have not yet been brought over from incode-platform
-
-//include::security:audit-trail:partial$module-nav.adoc[]
include::security:shiro-realm-ldap:partial$module-nav.adoc[]
include::security:secman:partial$module-nav.adoc[]
+
+// commented out the libraries that have not yet been brought over from incode-platform
+//include::security:audit-trail:partial$module-nav.adoc[]
//include::security:session-log:partial$module-nav.adoc[]
diff --git a/security/spring/src/main/adoc/antora.yml b/security/spring/src/main/adoc/antora.yml
new file mode 100644
index 0000000..2be1151
--- /dev/null
+++ b/security/spring/src/main/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: security
+version: latest
diff --git a/persistence/jpa/adoc/modules/ROOT/pages/about.adoc b/security/spring/src/main/adoc/modules/spring/nav.adoc
similarity index 93%
copy from persistence/jpa/adoc/modules/ROOT/pages/about.adoc
copy to security/spring/src/main/adoc/modules/spring/nav.adoc
index b977118..ae4837e 100644
--- a/persistence/jpa/adoc/modules/ROOT/pages/about.adoc
+++ b/security/spring/src/main/adoc/modules/spring/nav.adoc
@@ -1,8 +1,4 @@
-= JPA
: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 [...]
-:page-toc: ~
-
-WARNING: TODO: v2 - to document.
-
+include::security:ROOT:partial$component-nav.adoc[]
diff --git a/persistence/jpa/adoc/modules/ROOT/pages/about.adoc b/security/spring/src/main/adoc/modules/spring/pages/about.adoc
similarity index 77%
copy from persistence/jpa/adoc/modules/ROOT/pages/about.adoc
copy to security/spring/src/main/adoc/modules/spring/pages/about.adoc
index b977118..b168dc9 100644
--- a/persistence/jpa/adoc/modules/ROOT/pages/about.adoc
+++ b/security/spring/src/main/adoc/modules/spring/pages/about.adoc
@@ -1,8 +1,10 @@
-= JPA
+= Sring Security
: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 [...]
+:page-partial:
-:page-toc: ~
+WARNING: TODO: this content has not yet been reviewed/updated for v2.0
+
+This guide describes the configuration of the Spring implementation of Apache Isis' `Authenticator and `Authorizor` APIs.
-WARNING: TODO: v2 - to document.
diff --git a/security/spring/src/main/adoc/modules/spring/partials/module-nav.adoc b/security/spring/src/main/adoc/modules/spring/partials/module-nav.adoc
new file mode 100644
index 0000000..4a42816
--- /dev/null
+++ b/security/spring/src/main/adoc/modules/spring/partials/module-nav.adoc
@@ -0,0 +1,2 @@
+
+* xref:security:spring:about.adoc[Spring Implementation]
diff --git a/viewers/restfulobjects/adoc/modules/ROOT/pages/about.adoc b/viewers/restfulobjects/adoc/modules/ROOT/pages/about.adoc
index 599e1e8..fbce180 100644
--- a/viewers/restfulobjects/adoc/modules/ROOT/pages/about.adoc
+++ b/viewers/restfulobjects/adoc/modules/ROOT/pages/about.adoc
@@ -12,7 +12,7 @@ Apache Isis' Restful Objects viewer is an implementation of the link:http://rest
The Restful Objects viewer also provides a number of extensions specific to Apache Isis.
Most significant of these is enhanced content negotiation support, making it easier to use the returned representations within bespoke clients using standard third-party configurations.
-This user guide discuss features, configuration and also how to extend the Restful Objects viewer.
+This component guide discuss features, configuration and also how to extend the Restful Objects viewer.
diff --git a/persistence/jpa/adoc/modules/ROOT/pages/about.adoc b/viewers/restfulobjects/adoc/modules/ROOT/pages/other-resources.adoc
similarity index 87%
copy from persistence/jpa/adoc/modules/ROOT/pages/about.adoc
copy to viewers/restfulobjects/adoc/modules/ROOT/pages/other-resources.adoc
index b977118..8aab42b 100644
--- a/persistence/jpa/adoc/modules/ROOT/pages/about.adoc
+++ b/viewers/restfulobjects/adoc/modules/ROOT/pages/other-resources.adoc
@@ -1,8 +1,7 @@
-= JPA
+= Other Resources
: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 [...]
+:page-aliases: guides:ugvw:ugvw.adoc
-:page-toc: ~
-
-WARNING: TODO: v2 - to document.
+WARNING: TODO: document 3rd party tutorials and resources.
diff --git a/viewers/restfulobjects/adoc/modules/ROOT/partials/module-nav.adoc b/viewers/restfulobjects/adoc/modules/ROOT/partials/module-nav.adoc
index d2524de..4060253 100644
--- a/viewers/restfulobjects/adoc/modules/ROOT/partials/module-nav.adoc
+++ b/viewers/restfulobjects/adoc/modules/ROOT/partials/module-nav.adoc
@@ -10,4 +10,6 @@
* xref:vro:ROOT:configuration-properties.adoc[Configuration Properties]
* xref:vro:ROOT:security.adoc[Security]
* xref:vro:ROOT:hints-and-tips.adoc[Hints-n-Tips]
+* xref:vro:ROOT:other-resources.adoc[Other Resources]
+
diff --git a/viewers/wicket/adoc/modules/ROOT/pages/about.adoc b/viewers/wicket/adoc/modules/ROOT/pages/about.adoc
index 8d05228..6153684 100644
--- a/viewers/wicket/adoc/modules/ROOT/pages/about.adoc
+++ b/viewers/wicket/adoc/modules/ROOT/pages/about.adoc
@@ -8,7 +8,7 @@ WARNING: TODO: this content has not yet been reviewed/updated for v2.0
The Wicket Viewer automatically exposes an Apache Isis domain object model for use by end-users.
The viewer is implemented using link:http://wicket.apache.org[Apache Wicket].
-This user guide discuss end-user features, configuration and customization of the Wicket viewer.
+This component guide discuss end-user features, configuration and customization of the Wicket viewer.
It also discusses how to extend the viewer, and lists a number of extensions available.
diff --git a/persistence/jpa/adoc/modules/ROOT/pages/about.adoc b/viewers/wicket/adoc/modules/ROOT/pages/other-resources.adoc
similarity index 87%
copy from persistence/jpa/adoc/modules/ROOT/pages/about.adoc
copy to viewers/wicket/adoc/modules/ROOT/pages/other-resources.adoc
index b977118..8aab42b 100644
--- a/persistence/jpa/adoc/modules/ROOT/pages/about.adoc
+++ b/viewers/wicket/adoc/modules/ROOT/pages/other-resources.adoc
@@ -1,8 +1,7 @@
-= JPA
+= Other Resources
: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 [...]
+:page-aliases: guides:ugvw:ugvw.adoc
-:page-toc: ~
-
-WARNING: TODO: v2 - to document.
+WARNING: TODO: document 3rd party tutorials and resources.
diff --git a/viewers/wicket/adoc/modules/ROOT/partials/module-nav.adoc b/viewers/wicket/adoc/modules/ROOT/partials/module-nav.adoc
index 5add83e..811d26e 100644
--- a/viewers/wicket/adoc/modules/ROOT/partials/module-nav.adoc
+++ b/viewers/wicket/adoc/modules/ROOT/partials/module-nav.adoc
@@ -7,6 +7,8 @@
* xref:vw:ROOT:customisation.adoc[Customisation]
* xref:vw:ROOT:extending.adoc[Extending]
* xref:vw:ROOT:hints-and-tips.adoc[Hints-n-Tips]
+* xref:vw:ROOT:other-resources.adoc[Other Resources]
+
[isis] 02/04: ISIS-2484: adds back in docs
Posted by da...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch ISIS-2484
in repository https://gitbox.apache.org/repos/asf/isis.git
commit 46e10eeb5818853fdefe1e3fd6cc86a0adaad936
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Wed Mar 31 12:29:10 2021 +0100
ISIS-2484: adds back in docs
---
.../jpa/adoc/modules/ROOT/pages/applib.adoc | 1 +
.../jpa/adoc/modules/ROOT/pages/mapping-guide.adoc | 2 +-
.../ROOT/pages/setup-and-configuration.adoc | 143 ++++++++++++++++++++-
3 files changed, 140 insertions(+), 6 deletions(-)
diff --git a/persistence/jpa/adoc/modules/ROOT/pages/applib.adoc b/persistence/jpa/adoc/modules/ROOT/pages/applib.adoc
index e69de29..43d4bb56 100644
--- a/persistence/jpa/adoc/modules/ROOT/pages/applib.adoc
+++ b/persistence/jpa/adoc/modules/ROOT/pages/applib.adoc
@@ -0,0 +1 @@
+= JPA Applib
diff --git a/persistence/jpa/adoc/modules/ROOT/pages/mapping-guide.adoc b/persistence/jpa/adoc/modules/ROOT/pages/mapping-guide.adoc
index 22c7ab3..71d14ff 100644
--- a/persistence/jpa/adoc/modules/ROOT/pages/mapping-guide.adoc
+++ b/persistence/jpa/adoc/modules/ROOT/pages/mapping-guide.adoc
@@ -1,4 +1,4 @@
-= Other Resources
+= Mapping Guide
: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 [...]
:page-aliases: guides:ugvw:ugvw.adoc
diff --git a/persistence/jpa/adoc/modules/ROOT/pages/setup-and-configuration.adoc b/persistence/jpa/adoc/modules/ROOT/pages/setup-and-configuration.adoc
index 4048e64..54f5924 100644
--- a/persistence/jpa/adoc/modules/ROOT/pages/setup-and-configuration.adoc
+++ b/persistence/jpa/adoc/modules/ROOT/pages/setup-and-configuration.adoc
@@ -1,12 +1,145 @@
-= JPA
+= Setup and Configuration
: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 JPA/EclipseLink object store enables domain objects to be persisted to relational databases.
-The object store is implemented using the link:https://www.eclipse.org/eclipselink/[EclipseLink] ORM, using the link:https://www.jcp.org/en/jsr/detail?id=317[JPA] API.
-EclipseLink is the reference implementation for JPA.
+This section describes how to include the JPA module and setup its configuration properties.
+
+
+== Add dependency to pom.xml
+
+=== Dependency Management
+
+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.
+
+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.
+
+
+== Schemas
+
+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.
+(For more on database schemas, see for example link:https://crate.io/docs/sql-99/en/latest/chapters/17.html#create-schema-statement[here]).
+
+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, xref:security:secman:about.adoc[SecMan]' JPA implementation resides in the `IsisModuleExtSecmanPersistenceJpa` module.
+Its `ApplicationUser` entity is defined as:
+
+[source,java]
+.ApplicationUser.java
+----
+@Entity
+@Table(
+ schema = "isisExtensionsSecman",
+ name = "ApplicationUser",
+ ...
+)
+public class ApplicationUser ... { /* ... */ }
+----
+
+which results in a `CREATE TABLE` statement of:
+
+[source,sql]
+----
+CREATE TABLE isisExtensionsSecman."ApplicationUser" (
+ ...
+)
+----
-This component guide discuss how to setup the framework to use the JPA/EclipseLink object store, how to configure the ORM, and also provides some examples on common use cases.
[isis] 04/04: ISIS-2484: updates docs for JPA and JDO
Posted by da...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch ISIS-2484
in repository https://gitbox.apache.org/repos/asf/isis.git
commit c24f2fb93cbf22ccef75f9af8fb35b4ae1dadf0d
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Wed Mar 31 13:42:24 2021 +0100
ISIS-2484: updates docs for JPA and JDO
---
.../JdoSupportService_010-examples-and-usage.adoc | 19 +--
.../setupguide/modules/eclipse/pages/about.adoc | 3 +-
antora/playbooks/site-persistence.yml | 6 +
.../config/partials/configuring-schemas.adoc | 24 ++++
.../jdo/adoc/modules/ROOT/pages/db-schemas.adoc | 130 ++-------------------
...er-resources.adoc => dependency-injection.adoc} | 8 +-
.../adoc/modules/ROOT/pages/hints-and-tips.adoc | 4 -
.../{jdo-mappings.adoc => mapping-guide.adoc} | 16 ++-
.../mandatory-properties-in-subtypes.adoc | 0
.../mapping-to-a-view.adoc | 0
.../one-to-m-bidirectional-relationships.adoc | 0
.../ROOT/pages/setup-and-configuration.adoc | 70 ++++++-----
.../jdo/adoc/modules/ROOT/partials/module-nav.adoc | 13 ++-
persistence/jpa/adoc/modules/ROOT/nav.adoc | 2 +-
.../jpa/adoc/modules/ROOT/pages/applib.adoc | 1 -
.../jpa/adoc/modules/ROOT/pages/db-schemas.adoc | 37 ++++++
.../modules/ROOT/pages/dependency-injection.adoc} | 18 ++-
.../adoc/modules/ROOT/pages/domain-services.adoc} | 12 +-
.../jpa/adoc/modules/ROOT/pages/mapping-guide.adoc | 2 -
.../ROOT/pages/setup-and-configuration.adoc | 34 +-----
.../jpa/adoc/modules/ROOT/partials/module-nav.adoc | 7 +-
.../adoc/modules/ROOT/pages/architecture.adoc | 2 +-
22 files changed, 187 insertions(+), 221 deletions(-)
diff --git a/persistence/jdo/adoc/modules/ROOT/pages/services/IsisJdoSupport.adoc b/antora/components/refguide-index/modules/persistence/pages/index/jdo/applib/services/hooks/JdoSupportService_010-examples-and-usage.adoc
similarity index 98%
rename from persistence/jdo/adoc/modules/ROOT/pages/services/IsisJdoSupport.adoc
rename to antora/components/refguide-index/modules/persistence/pages/index/jdo/applib/services/hooks/JdoSupportService_010-examples-and-usage.adoc
index e6d23d8..2d65551 100644
--- a/persistence/jdo/adoc/modules/ROOT/pages/services/IsisJdoSupport.adoc
+++ b/antora/components/refguide-index/modules/persistence/pages/index/jdo/applib/services/hooks/JdoSupportService_010-examples-and-usage.adoc
@@ -1,17 +1,16 @@
-[[IsisJdoSupport]]
-= `IsisJdoSupport`
-
: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 [...]
:page-partial:
+== Examples and Usage
+
The `IsisJdoSupport` service provides a number of general purpose methods for working with the JDO/DataNucleus objectstore.
In general these act at a lower-level of abstraction than the APIs normally used (specifically, those of xref:refguide:applib:index/services/repository/RepositoryService.adoc[RepositoryService]), but nevertheless deal with some of the most common use cases.
For service also provides access to the underlying JDO `PersistenceManager` for full control.
The following sections discuss the functionality provided by the service, broken out into categories.
-== Executing SQL
+=== Executing SQL
You can use the `IsisJdoSupportService` to perform arbitrary SQL SELECTs or UPDATEs:
@@ -50,7 +49,7 @@ As an alternative, consider using DataNucleus' link:http://www.datanucleus.org/p
====
[#type-safe-jdoql-queries]
-== Type-safe JDOQL Queries
+=== Type-safe JDOQL Queries
DataNucleus provides an link:http://www.datanucleus.org/products/accessplatform_4_0/jdo/jdoql_typesafe.html[extension to JDO], so that JDOQL queries can be built up and executed using a set of type-safe classes.
@@ -131,7 +130,8 @@ private static <T> List<T> executeListAndClose(final TypesafeQuery<T> query) {
}
----
-== Fixture support
+
+=== Fixture support
When writing xref:testing:integtestsupport:about.adoc[integration tests] you'll usually need to tear down some/all mutable transactional data before each test.
One way to do that is to use the `executeUpdate(...)` method described xref:pjdo:ROOT:services/IsisJdoSupport.adoc#executing-sql[above].
@@ -169,7 +169,8 @@ JDO/DataNucleus seems to bump up the version of the object prior to its deletion
Therefore to prevent this from happening (ie to _force_ the deletion of all instances), concurrency checking is temporarily disabled while this method is performed.
====
-== Reloading entities
+
+=== Reloading entities
An link:http://www.datanucleus.org:15080/products/accessplatform_5_0/jdo/mapping.html#one_many_relations[(intentional) limitation] of JDO/DataNucleus is that persisting a child entity (in a 1:n bidirectional relationship) does not cause the parent's collection to be updated.
@@ -189,7 +190,8 @@ The `ensureLoaded(...)` method allows a collection of domain objects to be loade
This can be valuable as a performance optimization to avoid multiple roundtrips to the database.
Under the covers it uses the `PersistenceManager#retrieveAll(...)` API.
-== JDO `PersistenceManager`
+
+=== JDO `PersistenceManager`
The functionality provided by `IsisJdoSupport` focus only on the most common use cases.
If you require more flexibility than this, eg for dynamically constructed queries, then you can use the service to access the underlying JDO `PersistenceManager` API:
@@ -222,4 +224,3 @@ public class Orders {
}
----
-TODO: v2: IsisJdoSupport_v3_2
diff --git a/antora/components/setupguide/modules/eclipse/pages/about.adoc b/antora/components/setupguide/modules/eclipse/pages/about.adoc
index 022fec3..57a1fe8 100644
--- a/antora/components/setupguide/modules/eclipse/pages/about.adoc
+++ b/antora/components/setupguide/modules/eclipse/pages/about.adoc
@@ -75,6 +75,7 @@ Use File > Import, then Maven > Existing Maven Projects.
However, you will have some compile errors until you enable annotation processing, discussed below.
+[#enable-annotation-processing]
=== Enable Annotation Processing
Both DataNucleus and Project Lombok use annotation processors that must be enabled in Eclipse.
@@ -90,7 +91,7 @@ Then under _Java Compiler > Annotation Processing > Factory Path_ add the follow
* `datanucleus-jdo-query-5.0.9.jar` (under `.m2/repository/org/datanucleus/datanucleus-jdo-query/5.0.9`)
* `javax.jdo-3.2.0-m13.jar` (under `.m2/repository/org/datanucleus/javax.jdo/3.2.0-m13`)
-The specific versions depend on the DataNucleus version used in your project. You can easily check this in the Dependency Hierarchy tab of the POM.xml viewer in eclipse.
+The specific versions depend on the DataNucleus version used in your project.You can easily check this in the Dependency Hierarchy tab of the POM.xml viewer in eclipse.
Eclipse should automatically add these directories as a source path; at this point all remaining compiler errors should disappear.
diff --git a/antora/playbooks/site-persistence.yml b/antora/playbooks/site-persistence.yml
index 7b30111..52a6532 100644
--- a/antora/playbooks/site-persistence.yml
+++ b/antora/playbooks/site-persistence.yml
@@ -27,6 +27,12 @@ content:
- url: .
start_path: antora/components/docs # docs
branches: HEAD
+
+# core
+ - url: .
+ start_path: core/config/src/main/adoc # refguide
+ branches: HEAD
+
# examples
- url: .
start_path: examples/demo/domain/src/main/adoc # docs
diff --git a/core/config/src/main/adoc/modules/config/partials/configuring-schemas.adoc b/core/config/src/main/adoc/modules/config/partials/configuring-schemas.adoc
new file mode 100644
index 0000000..80c7542
--- /dev/null
+++ b/core/config/src/main/adoc/modules/config/partials/configuring-schemas.adoc
@@ -0,0 +1,24 @@
+= Configuring Schemas
+
+: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 [...]
+
+
+While it is good practice to place tables in schemas, the ORMs do not by default actually create those schema (as per link:https://crate.io/docs/sql-99/en/latest/chapters/17.html#create-schema-statement[CREATE SCHEMA] statement).
+
+The framework therefore allows this to be configured:
+
+* xref:refguide:config:sections/isis.persistence.schema.adoc#isis.persistence.schema.auto-create-schemas[isis.persistence.schema.auto-create-schemas]
++
+whether to automatically create the schemas
+
+* xref:refguide:config:sections/isis.persistence.schema.adoc#isis.persistence.schema.create-schema-sql-template[isis.persistence.schema.create-schema-sql-template]
++
+the SQL text used to create the schema.
+This should be an idempotent command, with the default being SQL-99 compliant:
++
+[source,sql]
+----
+CREATE SCHEMA IF NOT EXISTS %S
+----
++
+The string is interpolated using `String.format()`, passing in the schema name (for all discovered schema names).
diff --git a/persistence/jdo/adoc/modules/ROOT/pages/db-schemas.adoc b/persistence/jdo/adoc/modules/ROOT/pages/db-schemas.adoc
index 05b9dc4..0c1c186 100644
--- a/persistence/jdo/adoc/modules/ROOT/pages/db-schemas.adoc
+++ b/persistence/jdo/adoc/modules/ROOT/pages/db-schemas.adoc
@@ -4,20 +4,25 @@
: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 [...]
-
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.
+(For more on database schemas, see for example link:https://crate.io/docs/sql-99/en/latest/chapters/17.html#create-schema-statement[here]).
+
+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:
+For example, xref:security:secman:about.adoc[SecMan]' JDO implementation resides in the `IsisModuleExtSecmanPersistenceJpa` module.
+Its `ApplicationUser` entity is defined as:
[source,java]
----
-@javax.jdo.annotations.PersistenceCapable( ...
+@javax.jdo.annotations.PersistenceCapable(
schema = "isisExtensionsSecman",
- table = "ApplicationUser")
+ table = "ApplicationUser",
+ ...
+)
public class ApplicationUser ... { /* ... */ }
----
-results in a `CREATE TABLE` statement of:
+which results in a `CREATE TABLE` statement of:
[source,sql]
----
@@ -27,25 +32,6 @@ CREATE TABLE isisExtensionsSecman."ApplicationUser" (
----
-while:
-
-[source,java]
-----
-@javax.jdo.annotations.PersistenceCapable( ...
- schema = "isisaudit",
- table="AuditEntry")
-public class AuditEntry ... { /* ... */ }
-----
-
-similarly results in:
-
-[source,sql]
-----
-CREATE TABLE isisaudit."AuditEntry" (
- ...
-)
-----
-
[TIP]
====
@@ -54,99 +40,5 @@ See the section on xref:pjdo:ROOT:setup-and-configuration.adoc[configuring DataN
====
+include::refguide:config:partial$configuring-schemas.adoc[leveloffset=+1]
-== Flyway
-
-WARNING: TODO - v2 - reference flyway here also.
-
-
-
-//
-// no longer seems to be needed in v2
-//
-//
-//== Listener to create schema
-//
-//Apache Isis automatically creates owning schema objects for the tables that correspond to each entity class in the JDO metamodel.
-//
-//This is done by installing a listener, `CreateSchemaObjectFromClassMetadata`, on a callback provided by JDO/DataNucleus.
-//The listener is invoked on the initialization of each class.
-//It checks for the schema's existence, and creates the schema if required.
-//
-//The guts of its implementation is:
-//
-//[source,java]
-//----
-//public class CreateSchemaObjectFromClassMetadata
-// implements MetaDataListener,
-// DataNucleusPropertiesAware {
-// @Override
-// public void loaded(final AbstractClassMetaData cmd) { /* ... */ }
-//
-// protected String buildSqlToCheck(final AbstractClassMetaData cmd) {
-// final String schemaName = schemaNameFor(cmd);
-// return String.format(
-// "SELECT count(*) FROM INFORMATION_SCHEMA.SCHEMATA where SCHEMA_NAME = '%s'", schemaName);
-// }
-// protected String buildSqlToExec(final AbstractClassMetaData cmd) {
-// final String schemaName = schemaNameFor(cmd);
-// return String.format("CREATE SCHEMA \"%s\"", schemaName);
-// }
-//}
-//----
-//
-//where `MetaDataListener` is the DataNucleus listener API:
-//
-//[source,java]
-//----
-//public interface MetaDataListener {
-// void loaded(AbstractClassMetaData cmd);
-//}
-//----
-//
-//Although not formal API, the default `CreateSchemaObjectFromClassMetadata` has been designed to be easily overrideable if you need to tweak it to support other RDBMS'.
-//Any implementation must implement `org.datanucleus.metadata.MetaDataListener`:
-//
-//The implementation provided has has been tested for HSQLDB, PostgreSQL and MS SQL Server, and is used automatically unless an alternative implementation is specified (as described in the section below).
-//
-//
-//
-//
-//
-//== Alternative implementation
-//
-//An alternative implementation can be registered and used through the
-//
-//xref:refguide:config:sections/jdo-datanucleus-conf.adoc#class
-//
-//configuration property:
-//
-//[source,ini]
-//----
-//isis.persistor.datanucleus.classMetadataLoadedListener=\
-// org.apache.isis.objectstore.jdo.datanucleus.CreateSchemaObjectFromClassMetadata
-//----
-//
-//
-//Because this pertains to JDO/DataNucleus we suggest you put this configuration property in `WEB-INF/persistor_datanucleus.properties`; but putting it in `isis.properties` will also work.
-//
-//Any implementation must implement `org.datanucleus.metadata.MetaDataListener`.
-//In many cases simply subclassing from `CreateSchemaObjectFromClassMetadata` and overriding `buildSqlToCheck(...)` and `buildSqlToExec(...)` should suffice.
-//
-//If you _do_ need more control, your implementation can also optionally implement `org.apache.isis.objectstore.jdo.datanucleus.DataNucleusPropertiesAware`:
-//
-//[source,java]
-//----
-//public interface DataNucleusPropertiesAware {
-// public void setDataNucleusProperties(final Map<String, String> properties);
-//}
-//----
-//
-//This provides access to the properties passed through to JDO/DataNucleus.
-//
-//
-//[IMPORTANT]
-//====
-//If you do extend Apache Isis' `CreateSchemaObjectFromClassMetadata` class for some other database, please https://issues.apache.org/jira/browse/ISIS[contribute back] your improvements.
-//====
-//
diff --git a/persistence/jdo/adoc/modules/ROOT/pages/other-resources.adoc b/persistence/jdo/adoc/modules/ROOT/pages/dependency-injection.adoc
similarity index 74%
rename from persistence/jdo/adoc/modules/ROOT/pages/other-resources.adoc
rename to persistence/jdo/adoc/modules/ROOT/pages/dependency-injection.adoc
index 8aab42b..af6be70 100644
--- a/persistence/jdo/adoc/modules/ROOT/pages/other-resources.adoc
+++ b/persistence/jdo/adoc/modules/ROOT/pages/dependency-injection.adoc
@@ -1,7 +1,9 @@
-= Other Resources
+= Dependency Injection
: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 [...]
-:page-aliases: guides:ugvw:ugvw.adoc
-WARNING: TODO: document 3rd party tutorials and resources.
+
+With Apache Isis it's common to inject domain services into domain entities; this allows behaviour to be pushed down into those entities.
+
+For JDO, this injection performs automatically; there is no configuration or boilerplate required.
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 a025034..121de60 100644
--- a/persistence/jdo/adoc/modules/ROOT/pages/hints-and-tips.adoc
+++ b/persistence/jdo/adoc/modules/ROOT/pages/hints-and-tips.adoc
@@ -4,12 +4,8 @@
: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
-
This chapter provides some solutions for problems we've encountered ourselves or have been raised on the Apache Isis mailing lists.
-
-
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/java8.adoc[leveloffset=+1]
diff --git a/persistence/jdo/adoc/modules/ROOT/pages/jdo-mappings.adoc b/persistence/jdo/adoc/modules/ROOT/pages/mapping-guide.adoc
similarity index 56%
copy from persistence/jdo/adoc/modules/ROOT/pages/jdo-mappings.adoc
copy to persistence/jdo/adoc/modules/ROOT/pages/mapping-guide.adoc
index d64ee7f..711def8 100644
--- a/persistence/jdo/adoc/modules/ROOT/pages/jdo-mappings.adoc
+++ b/persistence/jdo/adoc/modules/ROOT/pages/mapping-guide.adoc
@@ -1,11 +1,15 @@
-[[jdo-mappings]]
-= JDO Mappings
+= Mapping Guide
: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
+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]
-include::jdo-mappings/one-to-m-bidirectional-relationships.adoc[leveloffset=+1]
-include::jdo-mappings/mandatory-properties-in-subtypes.adoc[leveloffset=+1]
-include::jdo-mappings/mapping-to-a-view.adoc[leveloffset=+1]
+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[]
diff --git a/persistence/jdo/adoc/modules/ROOT/pages/jdo-mappings/mandatory-properties-in-subtypes.adoc b/persistence/jdo/adoc/modules/ROOT/pages/mapping-guide/mandatory-properties-in-subtypes.adoc
similarity index 100%
rename from persistence/jdo/adoc/modules/ROOT/pages/jdo-mappings/mandatory-properties-in-subtypes.adoc
rename to persistence/jdo/adoc/modules/ROOT/pages/mapping-guide/mandatory-properties-in-subtypes.adoc
diff --git a/persistence/jdo/adoc/modules/ROOT/pages/jdo-mappings/mapping-to-a-view.adoc b/persistence/jdo/adoc/modules/ROOT/pages/mapping-guide/mapping-to-a-view.adoc
similarity index 100%
rename from persistence/jdo/adoc/modules/ROOT/pages/jdo-mappings/mapping-to-a-view.adoc
rename to persistence/jdo/adoc/modules/ROOT/pages/mapping-guide/mapping-to-a-view.adoc
diff --git a/persistence/jdo/adoc/modules/ROOT/pages/jdo-mappings/one-to-m-bidirectional-relationships.adoc b/persistence/jdo/adoc/modules/ROOT/pages/mapping-guide/one-to-m-bidirectional-relationships.adoc
similarity index 100%
rename from persistence/jdo/adoc/modules/ROOT/pages/jdo-mappings/one-to-m-bidirectional-relationships.adoc
rename to persistence/jdo/adoc/modules/ROOT/pages/mapping-guide/one-to-m-bidirectional-relationships.adoc
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 40f1b1f..69fd297 100644
--- a/persistence/jdo/adoc/modules/ROOT/pages/setup-and-configuration.adoc
+++ b/persistence/jdo/adoc/modules/ROOT/pages/setup-and-configuration.adoc
@@ -4,7 +4,7 @@
-== Add dependency to pom.xml
+== Maven pom.xml
=== Dependency Management
@@ -142,42 +142,27 @@ The default value is to use SQL-99 syntax ("CREATE SCHEMA IF NOT EXISTS %S"), pa
-[[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".
+== Auto-create (or validate) tables
-Here's the one provided by the xref:docs:starters:simpleapp.adoc[SimpleApp] starter app:
+When running against the h2 in-memory database (eg for prototype mode or integration tests), you'll probably want DataNucleus to automatically create the tables.
-[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">
+This can be configured using the:
- <persistence-unit name="simple">
- </persistence-unit>
-</persistence>
-----
+* xref:refguide:config:sections/datanucleus.adoc#datanucleus.schema.auto-create-all[datanucleus.schema.autoCreateAll] configuration property.
-Normally all one needs to do is to change the `persistence-unit` name.
+Conversely, if running in production then you will probably use xref:userguide:flyway:about.adoc[Flyway] to manage database migrations.
+In this case you'll just want to validate that the database table structure of the target database is in line with what DataNucleus expectss.
-[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.
-====
+You can do this using the:
+* xref:refguide:config:sections/datanucleus.adoc#datanucleus.schema.validate-all[datanucleus.schema.validateAll] configuration property.
-See link:http://www.datanucleus.org/products/datanucleus/jdo/persistence.html#persistenceunit[DataNucleus' documentation] on `persistence.xml` to learn more.
+This will fail-fast if there is a mismatch.
== 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:
@@ -196,8 +181,39 @@ A full list can be found http://www.datanucleus.org/products/datanucleus/jdo/met
====
DataNucleus properties must be specified using `camelCase`, not `kebab-case`.
-For example, use
+For example, use `datanucleus.schema.autoCreateAll` not `datanucleus.schema.auto-create-all`
+====
+
+
+[[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.
-//
diff --git a/persistence/jdo/adoc/modules/ROOT/partials/module-nav.adoc b/persistence/jdo/adoc/modules/ROOT/partials/module-nav.adoc
index a0273ae..fc55ffd 100644
--- a/persistence/jdo/adoc/modules/ROOT/partials/module-nav.adoc
+++ b/persistence/jdo/adoc/modules/ROOT/partials/module-nav.adoc
@@ -1,10 +1,13 @@
-
* 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: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:dependency-injection.adoc[Dependency Injection]
* xref:pjdo:ROOT:hints-and-tips.adoc[Hints-n-Tips]
-* Domain Services
-** xref:pjdo:ROOT:services/IsisJdoSupport.adoc[IsisJdoSupport]
-* xref:pjdo:ROOT:other-resources.adoc[Other Resources]
diff --git a/persistence/jpa/adoc/modules/ROOT/nav.adoc b/persistence/jpa/adoc/modules/ROOT/nav.adoc
index 4c4e42b..689950a 100644
--- a/persistence/jpa/adoc/modules/ROOT/nav.adoc
+++ b/persistence/jpa/adoc/modules/ROOT/nav.adoc
@@ -1,4 +1,4 @@
: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 [...]
-include::pjdo:ROOT:partial$component-nav.adoc[]
+include::pjpa:ROOT:partial$component-nav.adoc[]
diff --git a/persistence/jpa/adoc/modules/ROOT/pages/applib.adoc b/persistence/jpa/adoc/modules/ROOT/pages/applib.adoc
deleted file mode 100644
index 43d4bb56..0000000
--- a/persistence/jpa/adoc/modules/ROOT/pages/applib.adoc
+++ /dev/null
@@ -1 +0,0 @@
-= JPA Applib
diff --git a/persistence/jpa/adoc/modules/ROOT/pages/db-schemas.adoc b/persistence/jpa/adoc/modules/ROOT/pages/db-schemas.adoc
new file mode 100644
index 0000000..200ab3b
--- /dev/null
+++ b/persistence/jpa/adoc/modules/ROOT/pages/db-schemas.adoc
@@ -0,0 +1,37 @@
+[[db-schemas]]
+= Database Schemas
+
+: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 [...]
+
+
+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.
+(For more on database schemas, see for example link:https://crate.io/docs/sql-99/en/latest/chapters/17.html#create-schema-statement[here]).
+
+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, xref:security:secman:about.adoc[SecMan]' JPA implementation resides in the `IsisModuleExtSecmanPersistenceJpa` module.
+Its `ApplicationUser` entity is defined as:
+
+[source,java]
+.ApplicationUser.java
+----
+@Entity
+@Table(
+ schema = "isisExtensionsSecman",
+ name = "ApplicationUser",
+ ...
+)
+public class ApplicationUser ... { /* ... */ }
+----
+
+which results in a `CREATE TABLE` statement of:
+
+[source,sql]
+----
+CREATE TABLE isisExtensionsSecman."ApplicationUser" (
+ ...
+)
+----
+
+include::refguide:config:partial$configuring-schemas.adoc[leveloffset=+1]
+
diff --git a/persistence/jdo/adoc/modules/ROOT/pages/jdo-mappings.adoc b/persistence/jpa/adoc/modules/ROOT/pages/dependency-injection.adoc
similarity index 61%
copy from persistence/jdo/adoc/modules/ROOT/pages/jdo-mappings.adoc
copy to persistence/jpa/adoc/modules/ROOT/pages/dependency-injection.adoc
index d64ee7f..e65ad9c 100644
--- a/persistence/jdo/adoc/modules/ROOT/pages/jdo-mappings.adoc
+++ b/persistence/jpa/adoc/modules/ROOT/pages/dependency-injection.adoc
@@ -1,11 +1,17 @@
-[[jdo-mappings]]
-= JDO Mappings
+= Dependency Injection
: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
+With Apache Isis it's common to inject domain services into domain entities; this allows behaviour to be pushed down into those entities.
-include::jdo-mappings/one-to-m-bidirectional-relationships.adoc[leveloffset=+1]
-include::jdo-mappings/mandatory-properties-in-subtypes.adoc[leveloffset=+1]
-include::jdo-mappings/mapping-to-a-view.adoc[leveloffset=+1]
+For JPA, this requires that the following boilerplate:
+
+[source,java]
+----
+import javax.persistence.EntityListeners;
+import org.apache.isis.persistence.jpa.applib.integration.JpaEntityInjectionPointResolver;
+
+@EntityListeners(JpaEntityInjectionPointResolver.class)
+public class SomeEntity ... { /* ... */ }
+----
diff --git a/persistence/jdo/adoc/modules/ROOT/pages/jdo-mappings.adoc b/persistence/jpa/adoc/modules/ROOT/pages/domain-services.adoc
similarity index 70%
rename from persistence/jdo/adoc/modules/ROOT/pages/jdo-mappings.adoc
rename to persistence/jpa/adoc/modules/ROOT/pages/domain-services.adoc
index d64ee7f..efb43fb 100644
--- a/persistence/jdo/adoc/modules/ROOT/pages/jdo-mappings.adoc
+++ b/persistence/jpa/adoc/modules/ROOT/pages/domain-services.adoc
@@ -1,11 +1,11 @@
-[[jdo-mappings]]
-= JDO Mappings
+= Domain Services
: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
+The JPA applib (application library) provides an API fordomain objects to use for more advanced use cases.
+
+It currently provides the following domain service:
+
+* xref:refguide:persistence:index/jpa/applib/services/JpaSupportService.adoc[JpaSupportService]
-include::jdo-mappings/one-to-m-bidirectional-relationships.adoc[leveloffset=+1]
-include::jdo-mappings/mandatory-properties-in-subtypes.adoc[leveloffset=+1]
-include::jdo-mappings/mapping-to-a-view.adoc[leveloffset=+1]
diff --git a/persistence/jpa/adoc/modules/ROOT/pages/mapping-guide.adoc b/persistence/jpa/adoc/modules/ROOT/pages/mapping-guide.adoc
index 71d14ff..b254255 100644
--- a/persistence/jpa/adoc/modules/ROOT/pages/mapping-guide.adoc
+++ b/persistence/jpa/adoc/modules/ROOT/pages/mapping-guide.adoc
@@ -18,5 +18,3 @@ Take a look at:
Although written for Hibernate, the JPA material should work fine.
* link:https://www.baeldung.com/tag/jpa/[JPA Baeldung tags]
-** link:https://www.baeldung.com/jpa-entities[entities]
-
diff --git a/persistence/jpa/adoc/modules/ROOT/pages/setup-and-configuration.adoc b/persistence/jpa/adoc/modules/ROOT/pages/setup-and-configuration.adoc
index 54f5924..51ceaec 100644
--- a/persistence/jpa/adoc/modules/ROOT/pages/setup-and-configuration.adoc
+++ b/persistence/jpa/adoc/modules/ROOT/pages/setup-and-configuration.adoc
@@ -7,7 +7,7 @@
This section describes how to include the JPA module and setup its configuration properties.
-== Add dependency to pom.xml
+== Maven pom.xml
=== Dependency Management
@@ -111,35 +111,13 @@ 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.
-== Schemas
-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.
-(For more on database schemas, see for example link:https://crate.io/docs/sql-99/en/latest/chapters/17.html#create-schema-statement[here]).
+== Other Configuration Properties
-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.
+The JPA object store also supports the following configuraiton properties:
-For example, xref:security:secman:about.adoc[SecMan]' JPA implementation resides in the `IsisModuleExtSecmanPersistenceJpa` module.
-Its `ApplicationUser` entity is defined as:
-
-[source,java]
-.ApplicationUser.java
-----
-@Entity
-@Table(
- schema = "isisExtensionsSecman",
- name = "ApplicationUser",
- ...
-)
-public class ApplicationUser ... { /* ... */ }
-----
-
-which results in a `CREATE TABLE` statement of:
-
-[source,sql]
-----
-CREATE TABLE isisExtensionsSecman."ApplicationUser" (
- ...
-)
-----
+* xref:refguide:config:sections/isis.persistence.schema.adoc#isis.persistence.schema.additional-orm-files[isis.persistence.schema.additional-orm-files]
++
+Lookup additional "mapping-files" in `META-INF/orm-_name_.xml` (equivalent to "mapping-file" entries in `persistence.xml`) and adds these to those that are already configured the _Spring Data_ way (if any).
diff --git a/persistence/jpa/adoc/modules/ROOT/partials/module-nav.adoc b/persistence/jpa/adoc/modules/ROOT/partials/module-nav.adoc
index 0cf07e4..3a78cd6 100644
--- a/persistence/jpa/adoc/modules/ROOT/partials/module-nav.adoc
+++ b/persistence/jpa/adoc/modules/ROOT/partials/module-nav.adoc
@@ -1,3 +1,6 @@
* 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]
+* xref:pjpa:ROOT:db-schemas.adoc[DB Schemas]
+* xref:pjpa:ROOT:mapping-guide.adoc[Mapping
+Guide]
+* xref:pjpa:ROOT:dependency-injection.adoc[Dependency Injection]
+* xref:pjpa:ROOT:domain-services.adoc[Domain Services]
diff --git a/viewers/restfulobjects/adoc/modules/ROOT/pages/architecture.adoc b/viewers/restfulobjects/adoc/modules/ROOT/pages/architecture.adoc
index e62eca8..52ca4f5 100644
--- a/viewers/restfulobjects/adoc/modules/ROOT/pages/architecture.adoc
+++ b/viewers/restfulobjects/adoc/modules/ROOT/pages/architecture.adoc
@@ -23,7 +23,7 @@ This is then surfaced over the RO viewer.
+
If the underlying entities change, then care must be taken to ensure that structure of the view model nevertheless is unchanged.
-* a second option is to solve the problem at the persistence layer, but defining a (SQL) view in the database and then xref:pjdo:ROOT:jdo-mappings.adoc#mapping-to-a-view[mapping this] to a (read-only) entity.
+* a second option is to solve the problem at the persistence layer, but defining a (SQL) view in the database and then xref:pjdo:ROOT:mapping-guide.adoc#mapping-to-a-view[mapping this] to a (read-only) entity.
Again this is surfaced by the RO viewer.
+
If the underlying tables change (as the result of a change in their corresponding domain entities) then once more the view must be refactored so that it still presents the same structure.