You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2021/03/31 12:54:44 UTC
[isis] 19/20: ISIS-2484: updates docs for JPA and JDO
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/isis.git
commit 8cd63e0a90e5987d5dc16fd6b6e825d025a43719
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Wed Mar 31 13:42:24 2021 +0100
ISIS-2484: updates docs for JPA and JDO
(cherry picked from commit c24f2fb93cbf22ccef75f9af8fb35b4ae1dadf0d)
---
.../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 87f1ffa..3709277 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.