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/21 08:29:34 UTC
[isis] 01/02: ISIS-2444: updates docs on mavendeps
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch release-2.0.0-M5-RC1
in repository https://gitbox.apache.org/repos/asf/isis.git
commit 7f487c04b3b5d989171c2a36c68081d89766386f
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Sun Mar 21 08:01:41 2021 +0000
ISIS-2444: updates docs on mavendeps
---
antora/playbooks/site-core.yml | 11 ++-
antora/playbooks/site.yml | 11 ++-
core/adoc/modules/ROOT/partials/component-nav.adoc | 1 +
core/interaction/src/main/adoc/antora.yml | 19 +++++
.../src/main/adoc/modules/interaction/nav.adoc | 4 +
.../main/adoc/modules/interaction/pages/about.adoc | 5 ++
.../modules/interaction/partials/module-nav.adoc | 2 +
core/runtimeservices/src/main/adoc/antora.yml | 19 +++++
.../src/main/adoc/modules/runtimeservices/nav.adoc | 4 +
.../adoc/modules/runtimeservices/pages/about.adoc | 5 ++
.../runtimeservices/partials/module-nav.adoc | 2 +
core/transaction/src/main/adoc/antora.yml | 19 +++++
.../src/main/adoc/modules/transaction/nav.adoc | 4 +
.../main/adoc/modules/transaction/pages/about.adoc | 5 ++
.../modules/transaction/partials/module-nav.adoc | 2 +
mavendeps/adoc/modules/mavendeps/pages/about.adoc | 90 ++++++++++++++-------
.../parent-pom/images/parent-pom.drawio.svg | 1 +
.../adoc/modules/parent-pom/images/parent-pom.png | Bin 69175 -> 0 bytes
starters/adoc/modules/parent-pom/pages/about.adoc | 10 +--
19 files changed, 179 insertions(+), 35 deletions(-)
diff --git a/antora/playbooks/site-core.yml b/antora/playbooks/site-core.yml
index 426bfe4..71edc04 100644
--- a/antora/playbooks/site-core.yml
+++ b/antora/playbooks/site-core.yml
@@ -29,7 +29,7 @@ content:
branches: HEAD
# core
- url: .
- start_path: core/adoc # core
+ start_path: core/adoc # core (design docs)
branches: HEAD
- url: .
start_path: core/codegen-bytebuddy/src/main/adoc # core
@@ -38,6 +38,9 @@ content:
start_path: commons/src/main/adoc # core
branches: HEAD
- url: .
+ start_path: core/interaction/src/main/adoc # core
+ branches: HEAD
+ - url: .
start_path: core/internaltestsupport/src/main/adoc # core
branches: HEAD
- url: .
@@ -47,6 +50,12 @@ content:
start_path: core/runtime/src/main/adoc # core
branches: HEAD
- url: .
+ start_path: core/runtimeservices/src/main/adoc # core
+ branches: HEAD
+ - url: .
+ start_path: core/transaction/src/main/adoc # core
+ branches: HEAD
+ - url: .
start_path: core/webapp/src/main/adoc # core
branches: HEAD
diff --git a/antora/playbooks/site.yml b/antora/playbooks/site.yml
index 0dc9095..381e752 100644
--- a/antora/playbooks/site.yml
+++ b/antora/playbooks/site.yml
@@ -68,6 +68,9 @@ content:
start_path: core/config/src/main/adoc # refguide
branches: HEAD
- url: .
+ start_path: core/interaction/src/main/adoc # core
+ branches: HEAD
+ - url: .
start_path: core/internaltestsupport/src/main/adoc # core
branches: HEAD
- url: .
@@ -77,11 +80,17 @@ content:
start_path: core/runtime/src/main/adoc # core
branches: HEAD
- url: .
- start_path: core/webapp/src/main/adoc # core
+ start_path: core/runtimeservices/src/main/adoc # core
branches: HEAD
- url: .
start_path: core/security/src/main/adoc # security
branches: HEAD
+ - url: .
+ start_path: core/transaction/src/main/adoc # core
+ branches: HEAD
+ - url: .
+ start_path: core/webapp/src/main/adoc # core
+ branches: HEAD
# examples
- url: .
diff --git a/core/adoc/modules/ROOT/partials/component-nav.adoc b/core/adoc/modules/ROOT/partials/component-nav.adoc
index 54e631a..9e671bc 100644
--- a/core/adoc/modules/ROOT/partials/component-nav.adoc
+++ b/core/adoc/modules/ROOT/partials/component-nav.adoc
@@ -4,6 +4,7 @@ include::core:commons:partial$module-nav.adoc[]
include::core:codegen-bytebuddy:partial$module-nav.adoc[]
include::core:metamodel:partial$module-nav.adoc[]
include::core:runtime:partial$module-nav.adoc[]
+include::core:runtimeservices:partial$module-nav.adoc[]
include::core:webapp:partial$module-nav.adoc[]
include::core:regressiontests:partial$module-nav.adoc[]
diff --git a/core/interaction/src/main/adoc/antora.yml b/core/interaction/src/main/adoc/antora.yml
new file mode 100644
index 0000000..1a59920
--- /dev/null
+++ b/core/interaction/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: core
+version: latest
diff --git a/core/interaction/src/main/adoc/modules/interaction/nav.adoc b/core/interaction/src/main/adoc/modules/interaction/nav.adoc
new file mode 100644
index 0000000..798e16a
--- /dev/null
+++ b/core/interaction/src/main/adoc/modules/interaction/nav.adoc
@@ -0,0 +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::core:ROOT:partial$component-nav.adoc[]
diff --git a/core/interaction/src/main/adoc/modules/interaction/pages/about.adoc b/core/interaction/src/main/adoc/modules/interaction/pages/about.adoc
new file mode 100644
index 0000000..a0a0249
--- /dev/null
+++ b/core/interaction/src/main/adoc/modules/interaction/pages/about.adoc
@@ -0,0 +1,5 @@
+= Interaction
+
+: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
diff --git a/core/interaction/src/main/adoc/modules/interaction/partials/module-nav.adoc b/core/interaction/src/main/adoc/modules/interaction/partials/module-nav.adoc
new file mode 100644
index 0000000..388ec76
--- /dev/null
+++ b/core/interaction/src/main/adoc/modules/interaction/partials/module-nav.adoc
@@ -0,0 +1,2 @@
+
+* xref:core:interaction:about.adoc[Interaction]
diff --git a/core/runtimeservices/src/main/adoc/antora.yml b/core/runtimeservices/src/main/adoc/antora.yml
new file mode 100644
index 0000000..1a59920
--- /dev/null
+++ b/core/runtimeservices/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: core
+version: latest
diff --git a/core/runtimeservices/src/main/adoc/modules/runtimeservices/nav.adoc b/core/runtimeservices/src/main/adoc/modules/runtimeservices/nav.adoc
new file mode 100644
index 0000000..798e16a
--- /dev/null
+++ b/core/runtimeservices/src/main/adoc/modules/runtimeservices/nav.adoc
@@ -0,0 +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::core:ROOT:partial$component-nav.adoc[]
diff --git a/core/runtimeservices/src/main/adoc/modules/runtimeservices/pages/about.adoc b/core/runtimeservices/src/main/adoc/modules/runtimeservices/pages/about.adoc
new file mode 100644
index 0000000..262b3ac
--- /dev/null
+++ b/core/runtimeservices/src/main/adoc/modules/runtimeservices/pages/about.adoc
@@ -0,0 +1,5 @@
+= Runtime 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
diff --git a/core/runtimeservices/src/main/adoc/modules/runtimeservices/partials/module-nav.adoc b/core/runtimeservices/src/main/adoc/modules/runtimeservices/partials/module-nav.adoc
new file mode 100644
index 0000000..97e2f1f
--- /dev/null
+++ b/core/runtimeservices/src/main/adoc/modules/runtimeservices/partials/module-nav.adoc
@@ -0,0 +1,2 @@
+
+* xref:core:runtimeservices:about.adoc[Runtime Services]
diff --git a/core/transaction/src/main/adoc/antora.yml b/core/transaction/src/main/adoc/antora.yml
new file mode 100644
index 0000000..1a59920
--- /dev/null
+++ b/core/transaction/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: core
+version: latest
diff --git a/core/transaction/src/main/adoc/modules/transaction/nav.adoc b/core/transaction/src/main/adoc/modules/transaction/nav.adoc
new file mode 100644
index 0000000..798e16a
--- /dev/null
+++ b/core/transaction/src/main/adoc/modules/transaction/nav.adoc
@@ -0,0 +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::core:ROOT:partial$component-nav.adoc[]
diff --git a/core/transaction/src/main/adoc/modules/transaction/pages/about.adoc b/core/transaction/src/main/adoc/modules/transaction/pages/about.adoc
new file mode 100644
index 0000000..c30fbd9
--- /dev/null
+++ b/core/transaction/src/main/adoc/modules/transaction/pages/about.adoc
@@ -0,0 +1,5 @@
+= Transaction
+
+: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
diff --git a/core/transaction/src/main/adoc/modules/transaction/partials/module-nav.adoc b/core/transaction/src/main/adoc/modules/transaction/partials/module-nav.adoc
new file mode 100644
index 0000000..c75ea97
--- /dev/null
+++ b/core/transaction/src/main/adoc/modules/transaction/partials/module-nav.adoc
@@ -0,0 +1,2 @@
+
+* xref:core:transaction:about.adoc[Transaction]
diff --git a/mavendeps/adoc/modules/mavendeps/pages/about.adoc b/mavendeps/adoc/modules/mavendeps/pages/about.adoc
index 6a6f231..5c118e7 100644
--- a/mavendeps/adoc/modules/mavendeps/pages/about.adoc
+++ b/mavendeps/adoc/modules/mavendeps/pages/about.adoc
@@ -2,7 +2,7 @@
: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 framework provides a number of "aggregator" POMs that act as a convenient way to aggregate together various common dependencies.
+The framework provides a number of "aggregator" POMs that act as a convenient way to aggregate together various common dependencies.
For example, when writing unit tests for your domain app, it can simply depend on the `isis-mavendeps-unittests` artifact (rather than have to reference all of JUnit, AssertJ, Spring Boot, Hamcrest, Mockito and so on).
@@ -11,6 +11,7 @@ Currently five aggregator POMs are provided.
== Webapp
The `isis-mavendeps-webapp` aggregates the main runtime dependencies of a production webapp.
+Note however that it does _not_ include the runtime dependencies for either JDO or JPA; these have their own "mavendeps" POM, discussed xref:#jdo-and-jpa[below].
To use, add the following :
@@ -32,13 +33,12 @@ For convenience, it includes all of the current components available:
* Apache Isis Core - the xref:refguide:ROOT:about.adoc[Applib] and underlying implementation (xref:core:runtime-services:about.adoc[Runtime Services])
-* All the security implementations (xref:security:bypass:about.adoc[Bypass],
-xref:security:shiro:about.adoc[Shiro], xref:security:keycloak:about.adoc[Keycloak])
+* All the security implementations (xref:security:bypass:about.adoc[Bypass],xref:security:shiro:about.adoc[Shiro] and xref:security:keycloak:about.adoc[Keycloak])
-* All the viewer implementations (
-xref:vw:ROOT:about.adoc[Wicket], xref:vro:ROOT:about.adoc[Restful Objects])
+* All the viewer implementations (xref:vw:ROOT:about.adoc[Wicket], xref:vro:ROOT:about.adoc[Restful Objects])
-* All the persistence implementations (xref:pjdo:ROOT:about.adoc[JDO/DataNucleus])
+// doesn't seem to include these...
+//* All the persistence implementations (xref:pjdo:ROOT:about.adoc[JDO/DataNucleus], xref:pjpa:ROOT:about.adoc[JPA/EclipseLink])
If you don't need any of these (for example, you'll probably only want one security implementation), then you can exclude the others.
@@ -47,6 +47,40 @@ So, you must also add in the appropriate `IsisModuleXxx` to your application's t
For example, see the xref:docs:starters:simpleapp.adoc#appmanifest[AppManifest for the SimpleApp] starter app.
+[#jdo-and-jpa]
+== JDO and JPA
+
+The `isis-mavendeps-jdo` aggregates the xref:pjdo:ROOT:about.adoc[JDO/DataNucleus] dependencies, while the `isis-mavendeps-jpa` similarly aggregates the xref:pjpa:ROOT:about.adoc[JPA/EclipseLink] dependencies.
+Applications should use one or the other:
+
+* to use JDO, add:
++
+[source,xml]
+.pom.xml
+----
+<dependencies>
+ <dependency>
+ <groupId>org.apache.isis.mavendeps</groupId>
+ <artifactId>isis-mavendeps-jdo</artifactId>
+ <type>pom</type>
+ </dependency>
+</dependencies>
+----
+
+* to use JPA, add:
++
+[source,xml]
+.pom.xml
+----
+<dependencies>
+ <dependency>
+ <groupId>org.apache.isis.mavendeps</groupId>
+ <artifactId>isis-mavendeps-jpa</artifactId>
+ <type>pom</type>
+ </dependency>
+</dependencies>
+----
+
== Testing and BDD Specs
Three aggregator POMs are provided to support xref:testing:unittestsupport:about.adoc[unit testing], xref:testing:integtestsupport:about.adoc[integ testing] or running xref:testing:specsupport:about.adoc[BDD (Cucumber) specs].
@@ -111,16 +145,34 @@ integtests
integspecs
-|Apache Isis' own xref:testing:unittestsupport:about.adoc[unit test support] +
-with JMock2 extensions to mock classes
+|Apache Isis +
+xref:testing:unittestsupport:about.adoc[unit test support] +
| Y | |
-|Apache Isis' own xref:testing:integtestsupport:about.adoc[integ test support]
+|Apache Isis +
+xref:testing:integtestsupport:about.adoc[integ test support] +
| | Y | Y
-|Apache Isis' own xref:testing:specsupport:about.adoc[BDD spec support]
+|Apache Isis +
+xref:testing:specsupport:about.adoc[BDD spec support] +
| | | Y
+| Apache Isis +
+xref:refguide:ROOT:about.adoc[Applib]
+| Y | Y | Y
+
+| Apache Isis +
+xref:security:bypass:about.adoc[Bypass] security
+| | Y | Y
+
+| Apache Isis +
+xref:testing:fakedata:about.adoc[Fake Data]
+| Y | Y | Y
+
+|Apache Isis +
+xref:testing:fixtures:about.adoc[Fixture Scripts]
+| | Y | Y
+
| link:https://junit.org/junit5/docs/current/user-guide/[JUnit 5 "jupiter"]
| Y | Y | Y
@@ -149,24 +201,6 @@ with JMock2 extensions to mock classes
(for JMock2 extensions)
| Y | |
-| Apache Isis xref:refguide:ROOT:about.adoc[Applib]
-| Y | Y | Y
-
-| Apache Isis xref:core:runtime-services:about.adoc[Runtime Services]
-| | Y | Y
-
-| Apache Isis xref:security:bypass:about.adoc[Bypass] security
-| | Y | Y
-
-| Apache Isis xref:pjdo:ROOT:about.adoc[JDO/DataNucleus]
-| | Y | Y
-
-| Apache Isis xref:testing:fakedata:about.adoc[Fake Data]
-| Y | Y | Y
-
-| Apache Isis xref:testing:fixtures:about.adoc[Fixture Scripts]
-| | Y | Y
-
| link:https://github.com/google/guava/wiki[Google's Guava]
| Y | |
diff --git a/starters/adoc/modules/parent-pom/images/parent-pom.drawio.svg b/starters/adoc/modules/parent-pom/images/parent-pom.drawio.svg
new file mode 100644
index 0000000..b4ff6b4
--- /dev/null
+++ b/starters/adoc/modules/parent-pom/images/parent-pom.drawio.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="969px" height="587px" viewBox="-0.5 -0.5 969 587" content="<mxfile host="drawio-plugin" modified="2021-03-20T18:50:08.414Z" agent="5.0 (Windows NT 6.2; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/84.0.4147.105 Safari/537.36" etag="UsPSK2NaPMQWWJsnPGkd" version="13.7.9" type="embed"><diagram id="zLki [...]
\ No newline at end of file
diff --git a/starters/adoc/modules/parent-pom/images/parent-pom.png b/starters/adoc/modules/parent-pom/images/parent-pom.png
deleted file mode 100644
index 134ca64..0000000
Binary files a/starters/adoc/modules/parent-pom/images/parent-pom.png and /dev/null differ
diff --git a/starters/adoc/modules/parent-pom/pages/about.adoc b/starters/adoc/modules/parent-pom/pages/about.adoc
index facdf95..bb27cbd8 100644
--- a/starters/adoc/modules/parent-pom/pages/about.adoc
+++ b/starters/adoc/modules/parent-pom/pages/about.adoc
@@ -10,24 +10,24 @@ It builds upon a similar POM provided by the Spring Boot framework, which ensure
To use it, just add:
-[source,xml]
+[source,xml,subs="attributes+"]
.pom.xml
----
<parent>
<groupId>org.apache.isis.app</groupId>
<artifactId>isis-app-starter-parent</artifactId>
- <version>2.0.0</version> <!--1-->
+ <version>{page-isisrel}</version> <!--.-->
</parent>
----
-<1> update as required for new versions of the framework.
+<.> update as required for new versions of the framework.
You'll see that it is used by both the xref:docs:starters:helloworld.adoc[HelloWorld] and xref:docs:starters:simpleapp.adoc[SimpleApp] starter apps.
== Relationship to other POMs
-The diagram below (link:{attachmentsdir}/parent-pom.pptx[PPT]) below shows how the parent POM relates to other POMs:
+The diagram below shows how the parent POM relates to other POMs:
-image::parent-pom.png[width="800px"]
+image::parent-pom.drawio.svg[]
As the diagram shows, the parent POM inherits two Spring Boot parent POMs: directly from `org.springframework.boot:spring-boot-starter-parent`, and transitively inherits from `org.springframework.boot:spring-boot-dependencies`.