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/04/05 14:33:31 UTC
[isis] branch 2.0.0-M5 updated: ISIS-2484: improve docs re: flyway,
also simpleapp reference quartz.
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch 2.0.0-M5
in repository https://gitbox.apache.org/repos/asf/isis.git
The following commit(s) were added to refs/heads/2.0.0-M5 by this push:
new 0c57033 ISIS-2484: improve docs re: flyway, also simpleapp reference quartz.
0c57033 is described below
commit 0c570332ff17a9d0db74f324ebe660bde7976d3b
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Mon Apr 5 15:33:03 2021 +0100
ISIS-2484: improve docs re: flyway, also simpleapp reference quartz.
---
.../documentation/pages/asciidoc-syntax.adoc | 7 +++-
.../flyway/adoc/modules/flyway/pages/about.adoc | 49 ++++++++++++----------
persistence/jpa/adoc/modules/ROOT/pages/about.adoc | 2 +-
.../adoc/modules/starters/pages/simpleapp.adoc | 19 ++++++---
4 files changed, 45 insertions(+), 32 deletions(-)
diff --git a/antora/components/conguide/modules/documentation/pages/asciidoc-syntax.adoc b/antora/components/conguide/modules/documentation/pages/asciidoc-syntax.adoc
index bb4eeb2..397995c 100644
--- a/antora/components/conguide/modules/documentation/pages/asciidoc-syntax.adoc
+++ b/antora/components/conguide/modules/documentation/pages/asciidoc-syntax.adoc
@@ -761,6 +761,11 @@ For example, the `setting-up/concepts/concepts.adoc` file starts:
Asciidoctor includes support for the link:http://plantuml.com/[plantuml], allowing simple UML diagrams to be easily sketched.
+[TIP]
+====
+for much more on the layout of plantuml diagrams, see https://crashedmind.github.io/PlantUMLHitchhikersGuide/layout/layout.html
+====
+
For example:
....
@@ -786,8 +791,6 @@ Car -- Person : < owns
----
-
-
== C4 diagrams
Asciidoctor includes support for the link:https://c4model.com//[c4 model].
diff --git a/extensions/core/flyway/adoc/modules/flyway/pages/about.adoc b/extensions/core/flyway/adoc/modules/flyway/pages/about.adoc
index a6c3fdd..6886a58 100644
--- a/extensions/core/flyway/adoc/modules/flyway/pages/about.adoc
+++ b/extensions/core/flyway/adoc/modules/flyway/pages/about.adoc
@@ -30,53 +30,56 @@ public static class AppManifest {
}
----
-Also configure Flyway connection parameters to use those of JDO JDO/DataNucleus object store:
+Configure Flyway connection parameters:
[source,properties]
.application.properties
----
-spring.flyway.url=...
-spring.flyway.user=...
-spring.flyway.password=...
+spring.flyway.enabled=true
+spring.flyway.default-schema=SIMPLE // <.>
+spring.flyway.schemas=SIMPLE // <.>
+spring.flyway.create-schemas=true // <.>
+
+isis.persistence.schema.auto-create-schemas= // <.>
----
+<.> the default schema managed by Flyway (containing the `schema_version` table); see link:https://flywaydb.org/documentation/configuration/parameters/defaultSchema[flyway.defaultSchema] config property (Flyway docs) for more info
+<.> all of the schemas managed by Flyway; see link:https://flywaydb.org/documentation/configuration/parameters/schemas[flyway.schemas] config property (Flyway docs) for more info
+<.> whether Flyway should automatically create schemas ; see link:https://flywaydb.org/documentation/configuration/parameters/createSchemas[flyway.createSchemas] for more info
+<.> instruct Apache Isis to _not_ attempt to create schemas
-If Flyway is enabled, then `autoCreateAll` should also be disabled:
+The ORM should also be configured to _not_ automatically create tables:
+* if using xref:pjpa:ROOT:about.adoc[JPA/Eclipselink], then:
++
+[source,properties]
+.application.properties
+----
+eclipselink.ddl-generation=none
+----
+
+* if using xref:pjdo:ROOT:about.adoc[JDO/DataNucleus], then:
++
[source,properties]
.application.properties
----
-spring.flyway.enabled=true
datanucleus.schema.autoCreateAll=false
----
-== Using in-memory object stores
+== Managing different variants
When running with an in-memory object store - either for prototyping or integration tests - you will need the database tables to be created first.
-In normal circumstances this is most easily peformed using with `autoCreateAll` enabled (and Flyway disabled).
-If you want your tests to check your Flyway scripts beforehand, there is nothing to prevent you from using Flyway all the time, even for integration tests.
+In normal circumstances this is most easily accomplished with the ORM automatically creating the tables (and Flyway disabled).
+However, if you want your tests to check your Flyway scripts beforehand, there is nothing to prevent you from using Flyway all the time, even for integration tests.
One point to be aware of though is that the DDL syntax may vary between an in-memory database (such as H2) and a typical production database (such as PostgreSQL or SQL Server).
+
Luckily, Spring Boot's Flyway integration allows different variants of scripts for different vendors to be stored, in `+db.migration.{vendor}+` package (where `+{vendor}+` is as defined by the https://github.com/spring-projects/spring-boot/blob/v2.2.3.RELEASE/spring-boot-project/spring-boot/src/main/java/org/springframework/boot/jdbc/DatabaseDriver.java[DatabaseDriver] class).
The xref:docs:starters:simpleapp.adoc[simpleapp starter app] also provides an example of this.
-=== Custom schemas
-
-In some circumstances DataNucleus -- when running with `autoCreateAll` enabled -- has been known to not create the prerequisite schema objects.
-
-If this occurs, consider enabling Flyway for in-memory tests, and then use a custom value of `spring.flyway.locations` property to pick up the custom schema files:
-
-[source,properties]
-----
-spring.flyway.locations=classpath:db/migration/custom-schema
-----
-
-This property could be configured for example using `@TestPropertySource`, or `@ActiveProfile`.
-
== Reference
* https://docs.spring.io/spring-boot/docs/current/reference/html/howto.html#howto-execute-flyway-database-migrations-on-startup[Spring Boot docs] for Flyway integration
-* https://www.baeldung.com/spring-boot-configure-data-source-programmatic[www.baeldung.com] docs on how to programmatically build a `DataSource`
diff --git a/persistence/jpa/adoc/modules/ROOT/pages/about.adoc b/persistence/jpa/adoc/modules/ROOT/pages/about.adoc
index 4048e64..288b8d6 100644
--- a/persistence/jpa/adoc/modules/ROOT/pages/about.adoc
+++ b/persistence/jpa/adoc/modules/ROOT/pages/about.adoc
@@ -1,4 +1,4 @@
-= JPA
+= JPA/Eclipselink
: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 [...]
diff --git a/starters/adoc/modules/starters/pages/simpleapp.adoc b/starters/adoc/modules/starters/pages/simpleapp.adoc
index 7cee727..e7df446 100644
--- a/starters/adoc/modules/starters/pages/simpleapp.adoc
+++ b/starters/adoc/modules/starters/pages/simpleapp.adoc
@@ -637,8 +637,12 @@ src/main/java/
ApplicationModule.java <.>
custom/
restapi/
- CustomController.class <.>
+ CustomController.class <.>
CustomModule.class
+ quartz/
+ job/
+ SampleJob.class <.>
+ QuartzModule.class
AppManifest.java <.>
SimpleApp.java <.>
----
@@ -661,7 +665,9 @@ This integrates with Spring Boot's link:https://docs.spring.io/spring-boot/docs/
+
Discussed in more detail below.
-<.> Demonstrates how to implement custom REST controller using business logic.
+<.> Demonstrates how to implement a custom REST controller, accessing the domain object model managed by Apache Isis.
+
+<.> Demonstrates how to run quartz as a background service, accessing the domain object model managed by Apache Isis.
<.> `AppManifest` is the top-level Spring link:https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/context/annotation/Configuration.html[@Configuration] that specifies the components of Apache Isis to use, along with the modules making up the application itself (ie `ApplicationModule`, which depends in turn on `SimpleModule`, and `CustomModule`).
+
@@ -706,7 +712,7 @@ It looks like this:
@Import({
IsisModuleCoreRuntimeServices.class, // <.>
IsisModuleSecurityShiro.class, // <.>
- IsisModuleJdoDataNucleus5.class, // <.>
+ IsisModuleJpaEclipseLink.class, // <.>
IsisModuleViewerRestfulObjectsJaxrsResteasy4.class, // <.>
IsisModuleViewerWicketViewer.class, // <.>
@@ -717,6 +723,7 @@ It looks like this:
ApplicationModule.class, // <.>
CustomModule.class, // <9>
+ QuartzModule.class, // <9>
DomainAppDemo.class // <.>
})
@@ -732,9 +739,9 @@ public class AppManifest {
<.> Enables the Shiro security mechanism.
There are several security implementations, precisely one must be selected
-<.> Enables JDO/DataNucleus for persistence.
+<.> Enables JPA/Eclipselink for persistence.
+
-If using JPA as the ORM, replace with `IsisModuleJpaEclipseLink.class`.
+If using JDO as the ORM, replace with `IsisModuleJdoDataNucleus5`.
<.> Enables the xref:vro:ROOT:about.adoc[Restful Objects viewer] (ie REST API).
@@ -746,7 +753,7 @@ If using JPA as the ORM, replace with `IsisModuleJpaEclipseLink.class`.
<.> Enables the xref:userguide:flyway:about.adoc[Flyway] integration.
-<.> References the application's module(s), in this case `ApplicationModule` and `CustomModule`.
+<.> References the application's module(s), in this case `ApplicationModule` , `CustomModule` and `QuartzModule`.
+
`ApplicationModule` is discussed below.