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 2020/01/31 19:25:49 UTC
[isis] 04/09: ISIS-2062: removes references to 'archetype' ...
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 f815d68fad6eb3ad0c537ecfa0c31c422abd0c04
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Fri Jan 31 17:26:47 2020 +0000
ISIS-2062: removes references to 'archetype' ...
... instead we now have starter apps
---
.../toc/modules/ROOT/pages/downloads/how-to.adoc | 2 +-
.../ROOT/pages/more-thanks/more-thanks.adoc | 2 +-
.../pages/what-is-apache-isis/screencasts.adoc | 16 ++--
.../modules/comguide/pages/cutting-a-release.adoc | 17 +---
.../comguide/pages/post-release-successful.adoc | 104 ---------------------
.../comguide/pages/post-release-unsuccessful.adoc | 24 +----
.../release-process-for-interim-releases.adoc | 11 +--
.../modules/comguide/pages/verifying-releases.adoc | 31 +-----
.../pages/hints-and-tips/datanucleus-enhancer.adoc | 5 +-
.../pages/hints-and-tips/enabling-logging.adoc | 3 +-
.../how-run-fixtures-on-app-startup.adoc | 2 +-
antora/toc/modules/devguide/pages/ide/eclipse.adoc | 61 ++++--------
.../modules/mignotes/pages/migrating-to-2.0.0.adoc | 14 ++-
.../modules/btb/pages/deployment/neo4j.adoc | 14 ---
api/adoc/userguide/modules/btb/pages/i18n.adoc | 53 ++---------
.../fun/pages/programming-model/properties.adoc | 25 ++---
.../pages/classes/AppManifest-bootstrapping.adoc | 41 ++------
.../pages/persistence-layer-api/H2ManagerMenu.adoc | 7 +-
.../FixtureScriptsSpecificationProvider.adoc | 7 +-
.../config/pages/specifying-components.adoc | 13 +--
.../src/main/doc/modules/mvn/pages/intro.adoc | 6 +-
.../disabling-persistence-by-reachability.adoc | 4 +-
.../ROOT/pages/configuring/persistence-xml.adoc | 2 +-
security/adoc/modules/ROOT/pages/about.adoc | 2 +-
.../pages/about/configuring-isis-to-use-shiro.adoc | 6 +-
.../adoc/modules/shiro/pages/about/ini-realm.adoc | 2 +-
starters/adoc/modules/helloworld/pages/about.adoc | 2 +-
starters/adoc/modules/simpleapp/pages/about.adoc | 2 +-
.../pages/fixture-scripts/api-and-usage.adoc | 18 ++--
.../adoc/modules/ROOT/pages/layout/file-based.adoc | 2 +-
.../ROOT/pages/menubars-layout/file-based.adoc | 2 +-
31 files changed, 110 insertions(+), 390 deletions(-)
diff --git a/antora/toc/modules/ROOT/pages/downloads/how-to.adoc b/antora/toc/modules/ROOT/pages/downloads/how-to.adoc
index fd99b00..5a08c5c 100644
--- a/antora/toc/modules/ROOT/pages/downloads/how-to.adoc
+++ b/antora/toc/modules/ROOT/pages/downloads/how-to.adoc
@@ -12,7 +12,7 @@ Use for prototyping or production.
== Getting Started
-If you just want to get going quickly, we suggest using our link:https://github.com/apache/isis-app-simpleapp[Maven archetype].
+If you just want to get going quickly, we suggest using our link:https://github.com/apache/isis-app-helloworld[HelloWorld] or link:https://github.com/apache/isis-app-simpleapp[SimpleApp] starter apps.
diff --git a/antora/toc/modules/ROOT/pages/more-thanks/more-thanks.adoc b/antora/toc/modules/ROOT/pages/more-thanks/more-thanks.adoc
index fdc0984..71b3433 100644
--- a/antora/toc/modules/ROOT/pages/more-thanks/more-thanks.adoc
+++ b/antora/toc/modules/ROOT/pages/more-thanks/more-thanks.adoc
@@ -23,7 +23,7 @@ In addition to the http://www.apache.org/foundation/thanks.html[support given to
|image::more-thanks/icons8-logo.png[link="http://icons8.com"]
-|Icons8, for selected icons on this website and in the link:https://github.com/apache/isis/tree/master/example/application/simpleapp/dom/src/main/resources/images[simpleapp] used to generate the link:https://github.com/apache/isis-app-simpleapp[simpleapp archetype]
+|Icons8, for selected icons on this website and in the link:https://github.com/apache/isis-app-helloworld[HelloWorld] and link:https://github.com/apache/isis-app-simpleapp[SimpleApp] starter apps
|===
diff --git a/antora/toc/modules/ROOT/pages/what-is-apache-isis/screencasts.adoc b/antora/toc/modules/ROOT/pages/what-is-apache-isis/screencasts.adoc
index 60cbdef..c84beee 100644
--- a/antora/toc/modules/ROOT/pages/what-is-apache-isis/screencasts.adoc
+++ b/antora/toc/modules/ROOT/pages/what-is-apache-isis/screencasts.adoc
@@ -36,20 +36,20 @@ Finally, you can also find some screencasts for earlier versions of the framewor
| 11+|*Playlists*
-12+| *Archetype, IDE, layouts*
+12+| *IDE, layouts*
include::screencasts/playlists.adoc[]
-|https://www.youtube.com/watch?v=RQ_FFYd7npU[000^] +
-Searching and using the Apache Isis docs
-|x||||||||||
-
+//|https://www.youtube.com/watch?v=RQ_FFYd7npU[000^] +
+//Searching and using the Apache Isis docs
+//|x||||||||||
-|link:https://www.youtube.com/watch?v=OTNHR5EdAs8[001^] +
-Generating an app using the link:https://github.com/apache/isis-app-simpleapp[SimpleApp archetype]
-|x||||||||||
+//|link:https://www.youtube.com/watch?v=OTNHR5EdAs8[001^] +
+//Generating an app using the link:https://github.com/apache/isis-app-simpleapp[SimpleApp archetype]
+//
+//|x||||||||||
diff --git a/antora/toc/modules/comguide/pages/cutting-a-release.adoc b/antora/toc/modules/comguide/pages/cutting-a-release.adoc
index 7023825..6bd36fa 100644
--- a/antora/toc/modules/comguide/pages/cutting-a-release.adoc
+++ b/antora/toc/modules/comguide/pages/cutting-a-release.adoc
@@ -411,7 +411,7 @@ I've just cut a new release for Apache Isis Framework.
The source code artifacts have been uploaded to staging repositories on repository.apache.org.
For each zip there is a corresponding signature file (append .asc to the zip's url).
-In the source code repo the code has been tagged as isis-{isisnext}-RC1, helloworld-archetype-{isisnext}-RC1 and simpleapp-archetype-{isisnext}-RC1; see https://github.com/apache/isis/tags
+In the source code repo the code has been tagged as isis-{isisnext}-RC1; see https://github.com/apache/isis/tags
To verify the source code, you can use the following commands (in an empty directory):
@@ -423,25 +423,12 @@ To verify the source code, you can use the following commands (in an empty direc
rm -rf isis-$VERSION*
- curl -O -L https://raw.githubusercontent.com/apache/isis/06f947ad7a0968c34d8e6941a77e12aa0196cd17/scripts/verify-isis-release.sh
+ curl -O -L https://raw.githubusercontent.com/apache/isis/xxxx/scripts/verify-isis-release.sh
chmod +x ./verify-isis-release.sh
./verify-isis-release.sh $NEXUSREPONUM $VERSION
-Assuming this completes successfully, you can then test the two applications generated from the `simpleapp` and `helloworld` archetypes:
-
- pushd test-simpleapp/myapp
- mvn -pl webapp jetty:run
- popd
-
-and
-
- pushd test-helloworld/myapp
- mvn jetty:run
- popd
-
-
For more details, see https://isis.apache.org/toc/comguide/about.html#verifying-releases
Please verify the release and cast your vote. The vote will be open for a minimum of 72 hours.
diff --git a/antora/toc/modules/comguide/pages/post-release-successful.adoc b/antora/toc/modules/comguide/pages/post-release-successful.adoc
index 2299302..0fc4987 100644
--- a/antora/toc/modules/comguide/pages/post-release-successful.adoc
+++ b/antora/toc/modules/comguide/pages/post-release-successful.adoc
@@ -21,9 +21,6 @@ If there are not +3 votes after this time then it is perfectly permissible to ke
This section describes the steps to perform if the vote has been successful.
-
-
-
== Inform dev ML
Post the results to the `dev@isis.a.o` mailing list:
@@ -50,8 +47,6 @@ The vote is SUCCESSFUL.
I'll now go ahead and complete the post-release activities.
----
-
-
== Update tags
Replace the `-RCn` tag with another without the qualifier.
@@ -61,8 +56,6 @@ You can do this using the `scripts/promoterctag.sh` script; for example:
[source,bash,subs="attributes+"]
----
sh scripts/promoterctag.sh isis-{isisnext} RC1
-sh scripts/promoterctag.sh helloworld-archetype-{isisnext} RC1
-sh scripts/promoterctag.sh simpleapp-archetype-{isisnext} RC1
----
This script pushes the tag under `refs/tags/rel`.
@@ -70,9 +63,6 @@ As per Apache policy (communicated on 10th Jan 2016 to Apache PMCs), this path i
Then, continue onto the next section for the steps to promote and announce the release.
-
-
-
== Release to Maven Central
From the http://repository.apache.org[ASF Nexus repository], select the staging repository and select 'release' from the top menu.
@@ -83,8 +73,6 @@ image::release-process/nexus-release-1.png[width="600px",link="{imagesdir}/relea
This moves the release artifacts into an Apache releases repository; from there they will be automatically moved to the Maven repository.
-
-
== Release Source Zip
As described in the link:http://www.apache.org/dev/release-publishing.html#distribution_dist[Apache documentation], each Apache TLP has a `release/TLP-name` directory in the distribution Subversion repository at link:https://dist.apache.org/repos/dist[https://dist.apache.org/repos/dist].
@@ -99,9 +87,6 @@ The directory structure of Apache Isis reflects the directory structure in our g
----
isis/
core/
- example/
- archetype/
- simpleapp/
----
If necessary, checkout this directory structure:
@@ -148,47 +133,6 @@ svn delete $fullname-$old_ver-$zip
popd
-
-#
-# helloworld-archetype
-#
-type="archetype"
-fullname="helloworld-archetype"
-pushd $type/$fullname
-
-curl -O $repo_root/$type/$fullname/$new_ver/$fullname-$new_ver-$md5
-svn add $fullname-$new_ver-$md5
-curl -O $repo_root/$type/$fullname/$new_ver/$fullname-$new_ver-$asc
-svn add $fullname-$new_ver-$asc
-curl -O $repo_root/$type/$fullname/$new_ver/$fullname-$new_ver-$zip
-svn add $fullname-$new_ver-$zip
-
-svn delete $fullname-$old_ver-$md5
-svn delete $fullname-$old_ver-$asc
-svn delete $fullname-$old_ver-$zip
-
-popd
-
-
-#
-# simpleapp-archetype
-#
-type="archetype"
-fullname="simpleapp-archetype"
-pushd $type/$fullname
-
-curl -O $repo_root/$type/$fullname/$new_ver/$fullname-$new_ver-$md5
-svn add $fullname-$new_ver-$md5
-curl -O $repo_root/$type/$fullname/$new_ver/$fullname-$new_ver-$asc
-svn add $fullname-$new_ver-$asc
-curl -O $repo_root/$type/$fullname/$new_ver/$fullname-$new_ver-$zip
-svn add $fullname-$new_ver-$zip
-
-svn delete $fullname-$old_ver-$md5
-svn delete $fullname-$old_ver-$asc
-svn delete $fullname-$old_ver-$zip
-
-popd
----
[source,bash,subs="attributes+"]
@@ -198,8 +142,6 @@ sh upd.sh {isiscurr} {isisnext}
The script downloads the artifacts from the Nexus release repository, adds the artifacts to subversion and deletes the previous version.
-
-
Double check that the files are correct; there is sometimes a small delay in the files becoming available in the release repository.
It should be sufficient to check just the `md5` or `.asc` files that these look valid (aren't HTML 404 error pages):
@@ -217,8 +159,6 @@ svn commit -m "publishing isis source releases to dist.apache.org"
If the files are invalid, then revert using `svn revert . --recursive` and try again in a little while.
-
-
== Update JIRA
=== Generate Release Notes
@@ -236,33 +176,25 @@ This script uses 'jq' to parse JSON.
See the script itself for details of how to install this utility.
====
-
=== Close tickets
Close all JIRA tickets for the release, or moved to future releases if not yet addressed.
Any tickets that were partially implemented should be closed, and new tickets created for the functionality on the ticket not yet implemented.
-
-
=== Mark the version as released
In JIRA, go to the link:https://issues.apache.org/jira/plugins/servlet/project-config/ISIS/versions[administration section] for the Apache Isis project and update the version as being released.
In the link:https://issues.apache.org/jira/secure/RapidBoard.jspa?rapidView=87[Kanban view] this will have the effect of marking all tickets as released (clearing the "done" column).
-
=== Create new JIRA
Create a new JIRA ticket as a catch-all for the _next_ release.
-
=== Update the ASF Reporter website
Log the new release in the link:https://reporter.apache.org/addrelease.html?isis[ASF Reporter website].
-
-
-
== Release image to Docker hub
This is currently a placeholder.
@@ -275,8 +207,6 @@ TODO:
* Once this has been implemented, we also need to update the documentation for helloworld and simpleapp in order to explain how to build and deploy a skinny war to a running container.
-
-
The idea is to use `isis-webdocker` to create a new image, then upload.
Prereqs are:
@@ -301,7 +231,6 @@ Prereqs are:
\... because `isis-webdocker/pom.xml` references `docker-hub`.
-
[source,bash]
----
cd core
@@ -313,10 +242,6 @@ mvn -Drevision=$ISISREL \
deploy
----
-
-
-
-
== Update website
In the main `isis` repo (ie containing the asciidoc source):
@@ -327,10 +252,6 @@ Also add a summary line for the release.
* Update the [`site.yml`] file that declares the current and next releases.
-* Update any pages (`.adoc`, `.md`, `.html` etc) that describe how to run the archetype, and ensure they reference the correct version.
-+
-A search for `archetypeGroupId=org.apache.isis.archetype` should find these pages.
-
* update the `doap_isis.rdf` file (which provides a machine-parseable description of the project) with details of the new release.
Validate using the http://www.w3.org/RDF/Validator/[W3C RDF Validator] service.
+
@@ -398,8 +319,6 @@ You can take a copy from one of the older named versions, or just use this text:
** update the menu to reference the new version
-** update the version in the archetype.
-
At this point the files in the root (directly under `content`) will still be out of date; the publish process simply preserves whatever is in `content/versions/current`.
Also, the `SNAPSHOT` will be missing (above it was renamed to `current`).
And, we also need to make sure that any future publishing of snapshots has the correct version in the navbar.
@@ -419,7 +338,6 @@ Therefore:
If everything looks ok, then push the changes to make live.
-
== Announce the release
Announce the release to link:mailto:users@isis.apache.org[users mailing list].
@@ -456,18 +374,11 @@ Enjoy!
[4] http://isis.apache.org/downloads.html
----
-
-
-
== Blog post
link:https://blogs.apache.org/roller-ui/login.rol[Log onto] the http://blogs.apache.org/isis/[Apache blog] and create a new post.
Copy-n-paste the above mailing list announcement should suffice.
-
-
-
-
== Merge in release branch
Because we release from a branch, the changes made in the branch (changes to `pom.xml` made by the `maven-release-plugin`, or any manual edits) should be merged back from the release branch back into the `master` branch:
@@ -481,17 +392,12 @@ git push origin --delete release-{isisnext}-RC1 # remote branch no longer need
git branch -d release-{isisnext}-RC1 # branch no longer needed
----
-
-
-
== Update dependencies
With the release complete, now is a good time to bump versions of dependencies (so that there is a full release cycle to identify any possible issues).
You will probably want to create a new JIRA ticket for these updates (or if minor then use the "catch-all" JIRA ticket raised earlier for the next release).
-
-
=== Update parent of Core
Check (via link:http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.apache%22%20a%3A%22apache%22[search.maven.org]) whether there is a newer version of the Apache parent `org.apache:apache`.
@@ -510,8 +416,6 @@ If there is, update the `<version>` in the `<parent>` element in the
where `NN` is the updated version number.
-
-
=== Update plugin versions
The `maven-versions-plugin` should be used to determine if there are newer versions of any of the plugins used to build Apache Isis.
@@ -526,8 +430,6 @@ grep "\->" /tmp/foo | /bin/sort -u
Review the generated output and make updates as you see fit.
(However, if updating, please check by searching for known issues with newer versions).
-
-
=== Update dependency versions
The `maven-versions-plugin` should be used to determine if there are newer versions of any of Isis' dependencies.
@@ -561,15 +463,11 @@ For example, here is a report showing both of these cases:
For these artifacts you will need to search http://search.maven.org[Maven central repo] directly yourself to confirm there are no newer dependencies not shown in this list.
-
-
== Code formatting
This is also a good time to make source code has been cleaned up and formatted according to the Apache Isis and ASF conventions.
Use link:../dg/resources/eclipse/Apache-code-style-formatting.xml[this] Eclipse template and link:../dg/resources/eclipse/isis.importorder[this] import order.
-
-
== Push changes
Finally, push the changes up to origin:
@@ -580,8 +478,6 @@ git fetch # check no new commits on origin/master
git push
----
-
-
== Release (non-ASF) Modules
The (non-ASF) link:https://platform.incode.org[Incode Platform^] should also be released, as per their link:https://platform.incode.org/pages/committers-guide/committers-guide.html#_release_to_maven_central[release guide].
diff --git a/antora/toc/modules/comguide/pages/post-release-unsuccessful.adoc b/antora/toc/modules/comguide/pages/post-release-unsuccessful.adoc
index 6be5577..b1f7450 100644
--- a/antora/toc/modules/comguide/pages/post-release-unsuccessful.adoc
+++ b/antora/toc/modules/comguide/pages/post-release-unsuccessful.adoc
@@ -50,32 +50,18 @@ The vote is UNSUCCESSFUL.
Tidy up remote branches in the git repo:
-* delete the remote branch, for example: +
-+
[source,bash,subs="attributes+"]
----
git push --delete origin release-{isisnext}-RC1
-----
-
-
-* delete the remote origin server's tags, for example: +
-+
-[source,bash,subs="attributes+"]
-----
git push --delete origin isis-{isisnext}-RC1
-git push --delete origin helloworld-archetype-{isisnext}-RC1
-git push --delete origin simpleapp-archetype-{isisnext}-RC1
+git tag -d isis-{isisnext}
----
+These steps:
-* delete the tags that were created locally, for example: +
-+
-[source,bash,subs="attributes+"]
-----
-git tag -d isis-{isisnext}
-git tag -d helloworld-archetype-{isisnext}
-git tag -d simpleapp-archetype-{isisnext}
-----
+* delete the remote branch
+* delete the remote origin server's tags
+* delete the tags that were created locally
== Tidy up the Nexus repo
diff --git a/antora/toc/modules/comguide/pages/release-process-for-interim-releases.adoc b/antora/toc/modules/comguide/pages/release-process-for-interim-releases.adoc
index 4901d00..9736853 100644
--- a/antora/toc/modules/comguide/pages/release-process-for-interim-releases.adoc
+++ b/antora/toc/modules/comguide/pages/release-process-for-interim-releases.adoc
@@ -14,7 +14,6 @@ Since `-SNAPSHOT` changes on a day-to-day basis, the idea is to tag a particular
Whereas xref:toc:comguide:about.adoc#cutting-a-release.adoc[formal release]s and xref:toc:comguide:release-process-for-snapshots[snapshot release]s are public (released through the Maven repository maintained by Apache Software Foundation), interim releases are non-public and rely on infrastructure provided by a developer team.
The tagged release resides __not__ in the xref:toc:ROOT:downloads.adoc#\__downloads_source_code[official Apache Isis git repository], but instead in a fork/clone maintained by the developer team.
-
== Prerequisites
Create a remote fork/clone of the Apache Isis repository (eg using link:http://github.com[github] or link:http://bitbucket.org[bitbucket] or similar), and ensure that your local fork specifies this remote.
@@ -24,22 +23,16 @@ To build it should use the command:
[source,bash]
----
-mvn clean install -Dskip.app -Dskip.arch
+mvn clean install -Dskip.app
----
-that is, skipping the example simpleapp and archetype; only `core` framework is built
-
The CI server should then also publish the resultant artifacts to a local Maven repository.
For example, Jenkins provides post-build plugins to perform such a task.
-
-
== Sanity Check
Ensure that the framework builds ok using the same command that your CI server is set up to execute (see section above).
-
-
== Release
Deploy the framework using:
@@ -62,8 +55,6 @@ This will result in a new branch and tagged being pushed to the remote, with an
As noted in the prereqs (above), the CI server configured should then detect the new branch (or tag, if you prefer), build the framework (skipping application and architecture, as in the prerequisites) and then publish the resultant artifacts to a private Maven repo.
-
-
=== Implementation details
The script itself:
diff --git a/antora/toc/modules/comguide/pages/verifying-releases.adoc b/antora/toc/modules/comguide/pages/verifying-releases.adoc
index 0945533..f3528e3 100644
--- a/antora/toc/modules/comguide/pages/verifying-releases.adoc
+++ b/antora/toc/modules/comguide/pages/verifying-releases.adoc
@@ -78,10 +78,8 @@ curl http://www.apache.org/dist/isis/KEYS > /tmp/KEYS
gpg --import /tmp/KEYS
rm -rf isis-$VERSION*
-rm -rf simpleapp-archetype-$VERSION*
-rm -rf helloworld-archetype-$VERSION*
-curl -O -L https://gist.githubusercontent.com/danhaywood/9b052f68ef56cfdbeb3eb1603c5f772a/raw/a083599d34a502a18c5ccfd4a4d26f18352ca0e4/verify-isis-release.sh
+curl -O -L https://gist.githubusercontent.com/danhaywood/xxx/raw/xxx/verify-isis-release.sh
chmod +x ./verify-isis-release.sh
./verify-isis-release.sh $NEXUSREPONUM $VERSION
@@ -100,31 +98,10 @@ The location of this repository will be in the VOTE email.
+
in other words, to confirm that the release was created by an Apache Isis committer
-* builds all the framework code from source
-+
-that is, `core`, `simpleapp-archetype` and `helloworld-archetype`
-
-* generates and build an app for each of the two archetypes
+* builds the framework code from source
-Assuming this completes successfully, you can then test the two applications generated from the `simpleapp` and `helloworld` archetypes:
+Assuming this completes successfully, you can then test the two starter applications; adjust the version if required.
-* Test out simpleapp using:
-+
-[source,bash]
-----
-pushd test-simpleapp/myapp
-mvn -pl webapp jetty:run
-popd
-----
-
-* Test out helloworld using:
-+
-[source,bash]
-----
-pushd test-helloworld/myapp
-mvn jetty:run
-popd
-----
You can if you wish perform some additional optional checks, listed in the sections below.
Alternatively, you can xref:toc:comguide:verifying-releases.adoc#casting-a-vote[cast your vote].
@@ -133,7 +110,7 @@ Alternatively, you can xref:toc:comguide:verifying-releases.adoc#casting-a-vote[
== (Optional) Verifying binary artifacts
-You can verify the binary releases by configuring your local Maven install to point to the Maven staging repository (or repositories) and then using them, eg to run the link:https://github.com/apache/isis-app-helloworld[HelloWorld archetype] or the link:https://github.com/apache/isis-app-simpleapp[SimpleApp archetype] and running the resultant app.
+You can verify the binary releases by configuring your local Maven install to point to the Maven staging repository (or repositories) and then using them, eg to run the link:https://github.com/apache/isis-app-helloworld[HelloWorld starter app] or the link:https://github.com/apache/isis-app-simpleapp[SimpleApp starter app] (adjust the parent version if required).
Configuring your local Maven install amounts to updating the `~/.m2/settings.xml` file:
diff --git a/antora/toc/modules/devguide/pages/hints-and-tips/datanucleus-enhancer.adoc b/antora/toc/modules/devguide/pages/hints-and-tips/datanucleus-enhancer.adoc
index b647977..84b3649 100644
--- a/antora/toc/modules/devguide/pages/hints-and-tips/datanucleus-enhancer.adoc
+++ b/antora/toc/modules/devguide/pages/hints-and-tips/datanucleus-enhancer.adoc
@@ -1,4 +1,3 @@
-[[datanucleus-enhancer]]
= Datanucleus Enhancer
: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:
@@ -19,7 +18,7 @@ What this means is that the enhancer -- available as both a Maven plugin and as
If working from the Maven command line, JDO enhancement is done using the `datanucleus-maven-plugin`.
-Both the link:https://github.com/apache/isis-app-helloworld[HelloWorld] and link:https://github.com/apache/isis-app-simpleapp[SimpleApp] Maven archetypes generate applications that have this plugin pre-configured.
+Both the link:https://github.com/apache/isis-app-helloworld[HelloWorld] and link:https://github.com/apache/isis-app-simpleapp[SimpleApp] starter apps have this plugin pre-configured.
@@ -40,7 +39,7 @@ It's also a good idea to ensure that every domain module(s) containing entities
----
<1> change as required; typically is the name of the domain module.
-Again, the applications generated by both the link:https://github.com/apache/isis-app-helloworld[HelloWorld] and link:https://github.com/apache/isis-app-simpleapp[Simpleapp] Maven archetypes do this.
+Again, the link:https://github.com/apache/isis-app-helloworld[HelloWorld] and link:https://github.com/apache/isis-app-simpleapp[Simpleapp] starter apps do this.
[WARNING]
diff --git a/antora/toc/modules/devguide/pages/hints-and-tips/enabling-logging.adoc b/antora/toc/modules/devguide/pages/hints-and-tips/enabling-logging.adoc
index bb27cbb..f631630 100644
--- a/antora/toc/modules/devguide/pages/hints-and-tips/enabling-logging.adoc
+++ b/antora/toc/modules/devguide/pages/hints-and-tips/enabling-logging.adoc
@@ -16,8 +16,7 @@ As per the http://www.datanucleus.org/products/accessplatform/logging.html[DN lo
* In the JDBC Driver +
+
-Configure `log4jdbc` JDBC rather than the vanilla driver (see `WEB-INF/persistor_datanucleus.properties`) and configure log4j logging (see `WEB-INF/logging.properties`).
-There are examples of both in the link:https://github.com/apache/isis-app-simpleapp[SimpleApp archetype].
+Configure `log4jdbc` JDBC rather than the vanilla driver (see `application.properties`).
* In the database +
+
diff --git a/antora/toc/modules/devguide/pages/hints-and-tips/how-run-fixtures-on-app-startup.adoc b/antora/toc/modules/devguide/pages/hints-and-tips/how-run-fixtures-on-app-startup.adoc
index 3d68471..19f2aa0 100644
--- a/antora/toc/modules/devguide/pages/hints-and-tips/how-run-fixtures-on-app-startup.adoc
+++ b/antora/toc/modules/devguide/pages/hints-and-tips/how-run-fixtures-on-app-startup.adoc
@@ -13,7 +13,7 @@ Use events?_
The standard approach is to use xref:fixtures:ROOT:about.adoc[fixture scripts].
-These can be run in on start-up typically by being specified in the xref:refguide:applib-cm:classes/AppManifest-bootstrapping.adoc[`AppManifest`], see for example the link:https://github.com/apache/isis-app-simpleapp[SimpleApp archetype].
+These can be run in on start-up typically by being specified in the xref:refguide:applib-cm:classes/AppManifest-bootstrapping.adoc[`AppManifest`], see for example the link:https://github.com/apache/isis-app-simpleapp[SimpleApp] starter app.
Alternatively just set `isis.fixtures` and `isis.persistor.datanucleus.install-fixtures` properties.
diff --git a/antora/toc/modules/devguide/pages/ide/eclipse.adoc b/antora/toc/modules/devguide/pages/ide/eclipse.adoc
index 36ecbfd..98aaf5c 100644
--- a/antora/toc/modules/devguide/pages/ide/eclipse.adoc
+++ b/antora/toc/modules/devguide/pages/ide/eclipse.adoc
@@ -3,8 +3,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 [...]
:page-partial:
-
-
[NOTE]
====
This material does not constitute an endorsement; Eclipse foundation is not affiliated to Apache Software Foundation in any way.
@@ -18,13 +16,11 @@ This hooks the bytecode enhancement of your domain objects into Eclipse's normal
This plugin needs to be configured for each of your domain modules (usually just one in any given app).
-
-
-
-
== Editor Templates
-We provide a set of editor templates. These are used to add new methods to existing classes. (These are equivalent to the xref:toc:devguide:about.adoc#live-templates[IntelliJ live templates]):
+We provide a set of editor templates.
+These are used to add new methods to existing classes.
+(These are equivalent to the xref:toc:devguide:about.adoc#live-templates[IntelliJ live templates]):
* `is` (Apache Isis domain objects). link:./resources/eclipse/isis-templates.xml[Download]
* `ju` (for JUnit tests) link:./resources/eclipse/junit4-templates.xml[Download]
@@ -33,11 +29,9 @@ We provide a set of editor templates. These are used to add new methods to exis
To install, download each XML file, then go to `Windows > Preferences > Java > Editor > Templates` and choose `Import`.
-
-
== Install Project Lombok
-The link:https://github.com/apache/isis-app-simpleapp[SimpleApp archetype] uses link:http://projectlombok.org[Project Lombok] annotations (`@Getter` and `@Setter` and so on) to reduce the boilerplate.
+The link:https://github.com/apache/isis-app-simpleapp[SimpleApp] starter app uses link:http://projectlombok.org[Project Lombok] annotations (`@Getter` and `@Setter` and so on) to reduce the boilerplate.
For Eclipse IDE this requires an link:https://projectlombok.org/setup/eclipse[installation step]:
* Locate the `lombok.jar` jar file:
@@ -52,7 +46,6 @@ image::eclipse/2017-oxygen/020-lombok-install-into-eclipse.png[width="600px",lin
Then restart Eclipse.
-
== Install the DataNucleus plugin
The DataNucleus plugin hooks into the Eclipse compiler and will automatically enhance the compiled class files:
@@ -76,14 +69,12 @@ image::eclipse/2017-oxygen/050-datanucleus-select-plugin.png[width="600px",link=
Then restart Eclipse
-
== Importing the Project
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
Both DataNucleus and Project Lombok use annotation processors that must be enabled in Eclipse.
@@ -94,7 +85,6 @@ image::eclipse/2017-oxygen/060-enable-annotation-processor.png[width="600px",lin
Eclipse should automatically add this directory as a source path; at this point all remaining compiler errors should disappear.
-
== Configure DataNucleus
[TIP]
@@ -102,7 +92,6 @@ Eclipse should automatically add this directory as a source path; at this point
Make sure you are in the 'Java' Perspective, not the 'Java EE' Perspective.
====
-
In Eclipse, for the _domain object model_ project(s), first add DataNucleus support:
image::eclipse/eclipse-100-project-support.png[width="600px",link="{imagesdir}/eclipse/eclipse-100-project-support.png"]
@@ -112,15 +101,13 @@ Then turn on Auto-Enhancement:
image::eclipse/eclipse-110-project-support.png[width="600px",link="{imagesdir}/eclipse/eclipse-110-project-support.png"]
-
=== Update the classpath
DataNucleus' enhancer uses the domain object model's own classpath to reference DataNucleus JARs.
So, even though your domain objects are unlikely to depend on DataNucleus, these references must still be present.
See the section in xref:toc:devguide:hints-and-tips/datanucleus-enhancer.adoc[DataNucleus enhancer] for details of the contents of the `pom.xml`.
-Chances are it is already set up from running the link:https://github.com/apache/isis-app-helloworld[HelloWorld] or the link:https://github.com/apache/isis-app-simpleapp[SimpleApp] archetype.
-
+If you've based your app on either the link:https://github.com/apache/isis-app-helloworld[HelloWorld] or the link:https://github.com/apache/isis-app-simpleapp[SimpleApp] starter app, then it'll be set up already.
Then, tell DataNucleus to use the project classpath:
@@ -130,21 +117,21 @@ When the enhancer runs, it will print out to the console:
image::eclipse/eclipse-120-console.png[width="500px",link="{imagesdir}/eclipse/eclipse-120-console.png"]
-
=== 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.
To fix this, we configure the enhancer to read from the `persistence.xml` file.
-As a prerequisite, first make sure that your domain object model has a `persistence.xml` file. Then specify the `persistence-unit` in the project properties:
+As a prerequisite, first make sure that your domain object model has a `persistence.xml` file.
+Then specify the `persistence-unit` in the project properties:
image::eclipse/eclipse-025-project-properties.png[width="750px",link="{imagesdir}/eclipse/eclipse-025-project-properties.png"]
-
=== Workaround: If the enhancer fails
-On occasion it appears that Eclipse can attempt to run two instances of the DataNucleus enhancer. This is probably due to multiple Eclipse builders being defined; we've noticed multiple entries in the Eclipse's `Debug` view:
+On occasion it appears that Eclipse can attempt to run two instances of the DataNucleus enhancer.
+This is probably due to multiple Eclipse builders being defined; we've noticed multiple entries in the Eclipse's `Debug` view:
image::eclipse/eclipse-210-enhancer-fails-duplicates.png[width="600px",link="{imagesdir}/eclipse/eclipse-210-enhancer-fails-duplicates.png"]
@@ -165,22 +152,12 @@ image::eclipse/eclipse-220-enhancer-fails-duplicates.png[width="600px",link="{im
If you consistently hit problems, then the final recourse is to disable the automatic enhancement and to remember to manually enhance your domain object model before each run.
-Not ideal, we know. Please feel free to contribute a better solution :-)
-
-
+Not ideal, we know.
+Please feel free to contribute a better solution :-)
== Running the App
-The simpleapp archetype automatically provides a `.launch` configurations in the `webapp` module. You can therefore very simply run the application by right-clicking on one of these files, and choosing "Run As…" or "Debug As…".
-
-
-[NOTE]
-====
-The screencast above shows this in action.
-====
-
-
-
+Create a launch configuration that runs the main class annotated with link:https://docs.spring.io/spring-boot/docs/current/api/org/springframework/boot/autoconfigure/SpringBootApplication.html[@SpringBootApplication].
== Other domain projects.
@@ -191,24 +168,18 @@ You might want to do such that each domain project corresponds to a http://www.m
If you do this, make sure that each project has its own `persistence.xml` file.
And, remember also to configure Eclipse's DataNucleus plugin for these other domain projects.
-
-
== Advanced
In this section are a couple of options that will reduce the length of the change code/build/deploy/review feedback loop.
-
=== Setting up DCEVM
-link:http://github.com/dcevm/dcevm[DCEVM] enhances the JVM with true hot-swap adding/removing of methods as well as more
-reliable hot swapping of the implementation of existing methods.
+link:http://github.com/dcevm/dcevm[DCEVM] enhances the JVM with true hot-swap adding/removing of methods as well as more reliable hot swapping of the implementation of existing methods.
-In the context of Apache Isis, this is very useful for contributed actions and mixins and also view models; you should
-then be able to write these actions and have them be picked up without restarting the application.
+In the context of Apache Isis, this is very useful for contributed actions and mixins and also view models; you should then be able to write these actions and have them be picked up without restarting the application.
-Changing persisting domain entities is more problematic, for two reasons: the JDO/DataNucleus enhancer needs to run on
-domain entities, and also at runtime JDO/DataNucleus would need to rebuild its own metamodel. You may find that adding
-actions will work, but adding new properties or collections is much less likely to.
+Changing persisting domain entities is more problematic, for two reasons: the JDO/DataNucleus enhancer needs to run on domain entities, and also at runtime JDO/DataNucleus would need to rebuild its own metamodel.
+You may find that adding actions will work, but adding new properties or collections is much less likely to.
For details of setting up DCEVM, see the xref:toc:devguide:about.adoc#advanced_dcevm[corresponding section] in the IntelliJ documentation.
diff --git a/antora/toc/modules/mignotes/pages/migrating-to-2.0.0.adoc b/antora/toc/modules/mignotes/pages/migrating-to-2.0.0.adoc
index a49a9e5..e28e9cf 100644
--- a/antora/toc/modules/mignotes/pages/migrating-to-2.0.0.adoc
+++ b/antora/toc/modules/mignotes/pages/migrating-to-2.0.0.adoc
@@ -724,7 +724,19 @@ isis.value-types. +
=== No longer any archetypes
-TODO: document.
+The archetypes have been replaced by starter apps.
+This has several benefits:
+
+* for users of the framework:
+
+** github repos are now better understood than Maven archetypes
+** it is easier to provide improvements/patches as pull requests
+** a forked repo is immediately under code control
+
+* for committers:
+
+** contributions can be merged in more easiler
+** it simplifies the release process
== 2.0.0-M2 to 2.0.0-M3
diff --git a/api/adoc/userguide/modules/btb/pages/deployment/neo4j.adoc b/api/adoc/userguide/modules/btb/pages/deployment/neo4j.adoc
index bc69177..f7332dc 100644
--- a/api/adoc/userguide/modules/btb/pages/deployment/neo4j.adoc
+++ b/api/adoc/userguide/modules/btb/pages/deployment/neo4j.adoc
@@ -6,7 +6,6 @@
Apache Isis has experimental support for Neo4J, courtesy of DataNucleus' http://www.datanucleus.org/products/datanucleus/datastores/neo4j.html[Neo4J Datastore] implementation.
-
[TIP]
====
In addition, the http://github.com/isisaddons/isis-app-neoapp[Isis addons' neoapp] (non-ASF) is configured to run with an embedded Neo4J server running alongside the Apache Isis webapp.
@@ -14,7 +13,6 @@ In addition, the http://github.com/isisaddons/isis-app-neoapp[Isis addons' neoap
The steps below describe the configuration steps required to update an existing app.
-
== ConnectionURL
In `persistor.properties`, update the JDO `ConnectionURL` property, eg:
@@ -45,17 +43,5 @@ Add the following dependency to the `webapp` project's `pom.xml`:
<1> for Isis v1.9.0, use the value shown.
For Isis v1.8.0, use 3.2.3.
-In the link:https://github.com/apache/isis-app-simpleapp[SimpleApp archetype] this is defined under the "neo4j" profile so can be activated using `-P neo4j`.
-
-
-== Try it out!
-
-If you want to quickly try out neo4j for yourself:
-
-* run the link:https://github.com/apache/isis-app-simpleapp[SimpleApp archetype] (v1.8.0)
-
-* build the app:
-* run the app:
-If you visit the about page you should see the neo4j JAR files are linked in, and a `neo4j_DB` subdirectory within the `webapp` directory.
diff --git a/api/adoc/userguide/modules/btb/pages/i18n.adoc b/api/adoc/userguide/modules/btb/pages/i18n.adoc
index a20e385..a5a9608 100644
--- a/api/adoc/userguide/modules/btb/pages/i18n.adoc
+++ b/api/adoc/userguide/modules/btb/pages/i18n.adoc
@@ -14,7 +14,6 @@ If no translations are available, then the Wicket viewer falls back to using Wic
Isis does not translate the values of your domain objects, though.
So, if you have a domain concept such as `Country` whose name is intended to be localized according to the current user, you will need to model this yourself.
-
== Implementation Approach
Most Java frameworks tackle i18n by using Java's own `ResourceBundle` API.
@@ -24,7 +23,8 @@ However, there are some serious drawbacks in this approach, including:
* there is no support for plural forms (see this link:http://stackoverflow.com/questions/14326653/java-internationalization-i18n-with-proper-plurals/14327683#14327683[SO answer])
* there is no tooling support for translators
-Apache Isis therefore takes a different approach, drawing inspiration from GNU's https://www.gnu.org/software/gettext/manual/index.html[gettext] API and specifically its `.pot` and `.po` files. These are intended to be used as follows:
+Apache Isis therefore takes a different approach, drawing inspiration from GNU's https://www.gnu.org/software/gettext/manual/index.html[gettext] API and specifically its `.pot` and `.po` files.
+These are intended to be used as follows:
* the `.pot` (portable object template) file holds the message text to be translated
* this file is translated into multiple `.po` (portable object) files, one per supported locale
@@ -34,7 +34,6 @@ The name of each `.po` resolved in a very similar way to resource bundles.
The format of the `.pot` and `.po` files is identical; the only difference is that the `.po` file has translations for each of the message strings.
These message strings can also have singular and plural forms.
-
[IMPORTANT]
====
Although Apache Isis' implementation is modelled after GNU's API, it does _not_ use any GNU software.
@@ -46,16 +45,12 @@ This design tackles all the issues of ``ResourceBundle``s:
* the `.po` message format is such that any given message text to translate need only be translated once, even if it appears in multiple places in the application (eg "Name")
* the `.po` message format includes translations for (optional) plural form as well as singular form
* there are lots of freely available editors https://www.google.co.uk/search?q=.po+file+editor[to be found], many summarized on this https://www.drupal.org/node/11131[Drupal.org] webpage. +
-+
-In fact, there are also online communities/platforms of translators to assist with translating files.
++ In fact, there are also online communities/platforms of translators to assist with translating files.
One such is https://crowdin.com/[crowdin] (nb: this link does not imply endorsement).
In Apache Isis' implementation, if the translation is missing from the `.po` file then the original message text from the `.pot` file will be returned.
In fact, it isn't even necessary for there to be any `.po` files; `.po` translations can be added piecemeal as the need arises.
-
-
-
== `TranslationService`
The cornerstone of Apache Isis' support for i18n is the `TranslationService` service.
@@ -87,9 +82,8 @@ The `translate(...)` methods are closely modelled on GNU's gettext API.
The first version is used when no translation is required, the second is when both a singular and plural form will be required, with the `num` parameter being used to select which is returned.
In both cases the `context` parameter provides some contextual information for the translator; this generally corresponds to the class member.
-The mode meanwhile determines the behaviour of the service. More on this below.
-
-
+The mode meanwhile determines the behaviour of the service.
+More on this below.
=== `TranslationServicePo`
@@ -112,8 +106,6 @@ It is also possible to set a configuration setting in `isis.properties` to force
When running in write mode the original text is returned to the caller untranslated.
If in read mode, then the translated `.po` files are read and translations provided as required.
-
-
== Imperative messages
The `TranslationService` is used internally by Apache Isis when building up the metamodel; the name and description of every class, property, collection, action and action parameter is automatically translated.
@@ -122,13 +114,12 @@ Thus the simple act of bootstrapping Apache Isis will cause most of the messages
However, for an application to be fully internationalized, any validation messages (from either `disableXxx()` or `validateXxx()` supporting methods) and also possibly an object's title (from the `title()` method) will also require translation.
Moreover, these messages must be captured in the `.pot` file such that they can be translated.
-
=== `TranslatableString`
The first part of the puzzle is tackled by an extension to Apache Isis' programming model.
Whereas previously the `disableXxx()` / `validateXxx()` / `title()` methods could only return a `java.lang.String`, they may now optionally return a `TranslatableString` (defined in Isis applib) instead.
-Here's a (silly) example from the link:https://github.com/apache/isis-app-simpleapp[SimpleApp archetype]:
+Here's a (silly) example from the link:https://github.com/apache/isis-app-simpleapp[SimpleApp] starter app:
[source,java]
----
@@ -192,7 +183,6 @@ msgstr "Ich heisse {firstName} {lastName}."
then the translation would be: "Ich heisse James Bond".
-
The same class is used in xref:refguide:applib-svc:core-domain-api/MessageService.adoc[`MessageService`] so that you can raise translatable info, warning and error messages; each of the relevant methods are overloaded.
For example:
@@ -209,8 +199,6 @@ public interface MessageService {
----
<1> are concatenated together to form the context for the `.pot` file.
-
-
=== `TranslatableException`
Another mechanism by which messages can be rendered to the user are as the result of exception messages thrown and recognized by an xref:refguide:applib-svc:presentation-layer-spi/ExceptionRecognizer.adoc[`ExceptionRecognizer`].
@@ -230,13 +218,9 @@ public interface TranslatableException {
If returns `null`, then the `Exception#getMessage()` is used as a fallback
<2> the context to use when translating the message
-
-
-
== Wicket Viewer
-The xref:vw:ROOT:about.adoc[Wicket viewer] (its labels and messages) is also internationalized using
-the `TranslationService`.
+The xref:vw:ROOT:about.adoc[Wicket viewer] (its labels and messages) is also internationalized using the `TranslationService`.
This is done through an Isis-specific implementation of the Wicket framework's `org.apache.wicket.Localizer` class, namely `LocalizerForIsis`.
The Wicket `Localizer` defines the following API:
@@ -258,13 +242,11 @@ public String getString(
For example, `key` might be a value such as "okLabel", while `component` an internal class of the Wicket viewer, such as `EntityPropertiesForm`.
The `LocalizerForIsis` implementation uses the `key` as the `msgId`, while the fully qualified class name of the `component` is used as a context.
-There is one exception to this: if the component is the third-party select2
-component (used for drop-downs), then that class name is used directly.
+There is one exception to this: if the component is the third-party select2 component (used for drop-downs), then that class name is used directly.
In the main, using Isis' i18n support means simply adding the appropriate translations to the `translation.po` file, for each locale that you require.
If the translations are missing then the original translations from the Wicket resource bundles will be used instead.
-
=== Commonly used
Most of the translation requirements can be covered by adding in the following ``msgId``s:
@@ -335,7 +317,7 @@ msgstr "You can only select 1 item"
=== Login/self-sign-up
In addition, there are a reasonably large number of messages that are used for both login and the
- xref:vw:ROOT:features.adoc#user-registration[user registration] (self sign-up) and password reset features.
+xref:vw:ROOT:features.adoc#user-registration[user registration] (self sign-up) and password reset features.
These are:
@@ -482,11 +464,6 @@ msgid "usernamePlaceholder"
msgstr "Username"
----
-
-
-
-
-
== Integration Testing
So much for the API; but as noted, it is also necessary to ensure that the required translations are recorded (by the `TranslationService`) into the `.pot` file.
@@ -537,9 +514,6 @@ Behind the scenes Apache Isis uses a JUnit 5 extension (`ExceptionRecognizerTran
These are simply passed through to the registered xref:refguide:applib-svc:presentation-layer-spi/ExceptionRecognizer.adoc[`ExceptionRecognizer`]s so that any messages are recorded as requiring translation.
====
-
-
-
== Escaped strings
Translated messages can be escaped if required, eg to include embedded markup.
@@ -565,9 +539,6 @@ public Integer getQuantity() { /* ... */ }
----
<1> required (even though it won't be used when a translation is read; otherwise the escaped flag is ignored)
-
-
-
== Configuration
There are several different aspects of the translation service that can be configured.
@@ -614,7 +585,6 @@ then:
The basename for translation files is always `translations`; this cannot be altered.
-
=== Externalized translation files
Normally Apache Isis configuration files are read from the `WEB-INF` file.
@@ -668,13 +638,11 @@ Note that this default implementation does not support requests made through the
Registering a different implementation of `LocaleProvider` that taps into appropriate REST (RestEasy?) APIs would be the way to address this.
====
-
=== `TranslationsResolver`
The `TranslationResolver` is used by the `TranslationService` implementation to lookup translations for a specified locale.
It is this service that reads from the `WEB-INF/` (or externalized directory).
-
=== `TranslationServicePoMenu`
The `TranslationServicePoMenu` provides a couple of menu actions in the UI (prototype mode only) that interacts with the underlying `TranslationServicePo`:
@@ -687,8 +655,7 @@ While this will contain all the translations from the metamodel, it will not nec
====
* the `clearTranslationsCache()` action - available only in read mode - will clear the cache so that new translations can be loaded. +
-+
-This allows a translator to edit the appropriate `translations-xx-XX.po` file and check the translation is correct without having to restart the app.
++ This allows a translator to edit the appropriate `translations-xx-XX.po` file and check the translation is correct without having to restart the app.
diff --git a/api/adoc/userguide/modules/fun/pages/programming-model/properties.adoc b/api/adoc/userguide/modules/fun/pages/programming-model/properties.adoc
index d40a607..dbbac98 100644
--- a/api/adoc/userguide/modules/fun/pages/programming-model/properties.adoc
+++ b/api/adoc/userguide/modules/fun/pages/programming-model/properties.adoc
@@ -25,8 +25,7 @@ It's also possible (using annotations) to define a link table to hold foreign ke
Apache Isis recognises some of these annotations for JDO/DataNucleus and JAXB and infers some domain semantics from them (for example, the maximum allowable length of a string property).
Since writing getter and setter methods adds quite a bit of boilerplate, it's common to use link:https://projectlombok.org/[Project Lombok] to code generate these methods at compile time (using Java's annotation processor) simply by adding the `@lombok.Getter` and `@lombok.Setter` annotations to the field.
-The link:https://github.com/apache/isis-app-helloworld[HelloWorld] and link:https://github.com/apache/isis-app-simpleapp[SimpleApp] archetypes use this approach.
-
+The link:https://github.com/apache/isis-app-simpleapp[SimpleApp] starter app uses this approach.
== Value vs Reference Types
@@ -71,7 +70,6 @@ For further details on mapping associations, see the JDO/DataNucleus documentati
For domain entities, the annotations for mapping value types tend to be different for properties vs action parameters, because JDO annotations are only valid on properties.
The table in the xref:userguide:fun:programming-model.adoc#properties-vs-parameters[Properties vs Parameters] section provides a handy reference of each.
-
== Optional Properties
(For domain entities) JDO/DataNucleus' default is that a property is assumed to be mandatory if it is a primitive type (eg `int`, `boolean`), but optional if a reference type (eg `String`, `BigDecimal` etc).
@@ -120,7 +118,6 @@ private String notes;
If this is omitted then whether editing is enabled or disabled is defined globally, in the `isis.properties` configuration file; see xref:refguide:config:configuring-core.adoc#isis-objects-editing[reference configuration guide] for further details.
-
== Ignoring Properties
By default Apache Isis will automatically render all properties in the xref:vw:ROOT:about.adoc[Wicket UI] or in the xref:vro:ROOT:about.adoc[REST API].
@@ -132,7 +129,6 @@ This is independent of Apache Isis; in other words that property will still be r
For view models, you can tell JAXB to ignore a property using the `@javax.xml.bind.annotation.XmlTransient` annotation.
Again, this is independent of Apache Isis.
-
== Derived Properties
Derived properties are those with a getter but no setter.
@@ -168,14 +164,10 @@ AddressService addressService; // <3>
<2> the lat/long representation of the address, eg "51.503363;-0.127625"
<3> an injected service that can convert to/from address and latLong.
-
-
== Data types
This section shows specific considerations for various datatypes, in particular how to annotate them for DataNucleus mapping to the persistence object store.
-
-
=== ``String``s (Length)
By default JDO/DataNucleus will map string properties to a `VARCHAR(255)`.
@@ -192,8 +184,6 @@ private String firstName
This is a good example of a case where Apache Isis infers domain semantics from the JDO annotation.
-
-
=== JODA Dates
Isis' JDO objectstore bundles DataNucleus' http://www.datanucleus.org/documentation/products/plugins.html[built-in support] for Joda `LocalDate` and `LocalDateTime` datatypes, meaning that entity properties of these types will be persisted as appropriate data types in the database tables.
@@ -214,7 +204,6 @@ For example, the `ToDoItem` (in the https://github.com/isisaddons/isis-app-todoa
private LocalDate dueBy;
----
-
=== ``BigDecimal``s (Precision)
Working with `java.math.BigDecimal` properties takes a little care due to scale/precision issues.
@@ -227,7 +216,9 @@ For example, suppose we have:
private BigDecimal impact;
----
-JDO/DataNucleus creates, at least with HSQL, the table with the field type as NUMERIC(19). No decimal digits are admitted. (Further details http://hsqldb.org/doc/2.0/guide/sqlgeneral-chapt.html#sgc_numeric_types[here]).
+JDO/DataNucleus creates, at least with HSQL, the table with the field type as NUMERIC(19).
+No decimal digits are admitted.
+(Further details http://hsqldb.org/doc/2.0/guide/sqlgeneral-chapt.html#sgc_numeric_types[here]).
What this implies is that, when a record is inserted, a log entry similar to this one appears:
@@ -251,8 +242,6 @@ In addition, you should also set the scale of the `BigDecimal`, using `setScale(
More information can be found http://www.opentaps.org/docs/index.php/How_to_Use_Java_BigDecimal:_A_Tutorial[here] and http://www.tutorialspoint.com/java/math/bigdecimal_setscale_rm_roundingmode.htm[here].
-
-
=== ``Blob``s
Apache Isis configures JDO/DataNucleus so that the properties of type `org.apache.isis.applib.value.Blob` and `org.apache.isis.applib.value.Clob` can also be persisted.
@@ -301,7 +290,6 @@ There can be differences in behaviour between JDBC drivers.
=== ``Clob``s
-
Mapping `Clob`s works in a very similar way to ``Blob``s, but the `jdbcType` and `sqlType` attributes will, respectively, be `CLOB` and `LONGVARCHAR`:
[source,java]
@@ -320,10 +308,10 @@ private Clob doc;
[NOTE]
====
-If specifying a `sqlType` of "LONGVARCHAR" does not work, try instead "CLOB". There can be differences in behaviour between JDBC drivers.
+If specifying a `sqlType` of "LONGVARCHAR" does not work, try instead "CLOB".
+There can be differences in behaviour between JDBC drivers.
====
-
=== Mapping to VARBINARY or VARCHAR
Instead of mapping to a sqlType of `LONGVARBINARY` (or perhaps `BLOB`), you might instead decide to map to a `VARBINARY`.
@@ -348,6 +336,7 @@ The same argument applies to `LONGVARCHAR` (or `CLOB`); you could instead map to
sqlType = "VARCHAR", length=2048
)
----
+
Support and maximum allowed length will vary by database vendor.
diff --git a/api/applib/src/main/adoc/modules/applib-cm/pages/classes/AppManifest-bootstrapping.adoc b/api/applib/src/main/adoc/modules/applib-cm/pages/classes/AppManifest-bootstrapping.adoc
index ca5761c..beec4ad 100644
--- a/api/applib/src/main/adoc/modules/applib-cm/pages/classes/AppManifest-bootstrapping.adoc
+++ b/api/applib/src/main/adoc/modules/applib-cm/pages/classes/AppManifest-bootstrapping.adoc
@@ -1,7 +1,7 @@
-[[AppManifest-bootstrapping]]
= `AppManifest` (bootstrapping)
: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 [...]
+// TODO: v2: this is all out of date, instead bootstrap with @SpringBootApplication
This section describes how to implement the `AppManifest` interface to bootstrap both an Apache Isis web application, and also its integration tests.
@@ -15,7 +15,6 @@ The app manifest can then be used both to bootstrap the application "proper", or
== API
-
The `AppManifest` interface allows the constituent parts of an application to be defined programmatically, most specifically the packages that contain domain services and/or persistent entities.
Its API is defined as:
@@ -39,9 +38,6 @@ public interface AppManifest {
The following sections describe each of these methods in a little more detail.
-
-
-
=== `getModules()`
The most significant method (the only one which must return a non-`null` value) is the `getModules()` method.
@@ -87,7 +83,6 @@ public List<Class<?>> getModules() {
As can be seen, the various (non-ASF) link:https://platform.incode.org[Incode Platform^] modules also each provide a module class that can be easily referenced.
-
=== `getAdditionalServices()`
We normally we recommend that services are defined exclusively through `getModules()`, and that this method should therefore return an empty list.
@@ -107,9 +102,6 @@ public List<Class<?>> getAdditionalServices() {
If this method returns a non-`null` value, then it overrides the value of `isis.services` configuration property.
-
-
-
=== `getAuthenticationMechanism()`
If non-`null`, this method specifies the authentication mechanism to use.
@@ -123,8 +115,6 @@ See the xref:security:ROOT:about.adoc[security guide] for further details on con
This property is ignored for integration tests (which always uses the `"bypass"` mechanism).
====
-
-
=== `getAuthorizationMechanism()`
If non-`null`, this method specifies the authorization mechanism to use.
@@ -138,9 +128,6 @@ See the xref:security:ROOT:about.adoc[security guide] for further details on con
This property is ignored for integration tests (which always uses the `"bypass"` mechanism).
====
-
-
-
=== `getFixtures()`
If non-`null`, this method specifies the fixture script(s) to be run on startup.
@@ -156,13 +143,9 @@ public List<Class<? extends FixtureScript>> getFixtures() {
}
----
-
-
Note that in order for fixtures to be installed it is also necessary to set the `isis.persistor.datanucleus.install-fixtures` key to `true`.
This can most easily be done using the `getConfigurationProperties()` method, discussed below.
-
-
=== `getConfigurationProperties()`
This method allow arbitrary other configuration properties to be overridden.
@@ -178,8 +161,6 @@ public Map<String, String> getConfigurationProperties() {
}
----
-
-
== Bootstrapping
[NOTE]
@@ -209,8 +190,7 @@ isis.appManifest=domainapp.app.MyAppAppManifest
----
* the second is also as a webapp, but from within the context of the IDE. +
-+
-Here, it's common to use the `org.apache.isis.WebServer` class to launch your application from the xref:userguide:btb:about.adoc#cmd-line[command line].
++ Here, it's common to use the `org.apache.isis.WebServer` class to launch your application from the xref:userguide:btb:about.adoc#cmd-line[command line].
This allows the `AppManifest` to be specified using the `-m` (or `--manifest`) flag: +
+
[source,ini]
@@ -219,8 +199,7 @@ java org.apache.isis.WebServer -m com.mycompany.myapp.MyAppAppManifestWithFixtur
----
* the third case is within an integration test. +
-+
-The code to boostrap an integration test is shown in the xref:testing:integtestsupport:about.adoc#bootstrapping[testing guide], but once again an `AppManifest` is required.
++ The code to boostrap an integration test is shown in the xref:testing:integtestsupport:about.adoc#bootstrapping[testing guide], but once again an `AppManifest` is required.
In some cases an integration test uses the exact same `AppManifest` as the regular webapp.
Sometimes though it is necessary to "tweak" the `AppManifest`:
@@ -231,9 +210,11 @@ Sometimes though it is necessary to "tweak" the `AppManifest`:
The next section describes some helper classes that the framework provides to help achieve this.
-
=== AppManifestAbstract
+CAUTION: TODO: v2: this is all out of date and superceded by Spring Boot
+
+
[IMPORTANT]
====
The framework-provided `AppManifestAbstract2` and `AppManifestAbstract2.Builder` supercede `AppManifestAbstract`, making it easy to write an `AppManifest` defined by a set of xref:refguide:applib-cm:classes/Module.adoc[`Module`] implementations.
@@ -247,14 +228,12 @@ This takes an instance of a `AppManifestAbstract.Builder` in its constructor; th
Moreover, these classes recognise that configuration properties fall into two broad classes:
* those that are fixed and do not change between environments. +
-+
-In other words these describe how the application chooses to configure the framework itself, eg global disable of editing of properties, or enabling of auditing.
++ In other words these describe how the application chooses to configure the framework itself, eg global disable of editing of properties, or enabling of auditing.
* those that change between environments. +
-+
-The classic example here is the JDBC URL.
++ The classic example here is the JDBC URL.
-For example, the link:https://github.com/apache/isis-app-simpleapp[SimpleApp archetype]'s `AppManifest` is defined as:
+For example, the link:https://github.com/apache/isis-app-simpleapp[SimpleApp] starter app's `AppManifest` is defined as:
[source,java]
----
@@ -279,7 +258,7 @@ public class DomainAppAppManifest extends AppManifestAbstract {
}
----
<1> the modules that make up the application; corresponds to `AppManifest#getModules()`
-<2> the (non-changing with environment) set of configuration properties, loaded relative to the manifest itself; corresponds to `AppManifest#getConfigurationProperties()`
+<2> the (non-changing with environment) set of configuration properties, loaded relative to the manifest itself; corresponds to `AppManifest#getConfigurationProperties()`
<3> override of components; correponds to both `AppManifest#getAuthenticationMechanism()` and `AppManifest#getAuthorizationMechanism()`
<4> Pass the builder up to the superclass.
diff --git a/api/applib/src/main/adoc/modules/applib-svc/pages/persistence-layer-api/H2ManagerMenu.adoc b/api/applib/src/main/adoc/modules/applib-svc/pages/persistence-layer-api/H2ManagerMenu.adoc
index 076ac6a..b5295fe 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/pages/persistence-layer-api/H2ManagerMenu.adoc
+++ b/api/applib/src/main/adoc/modules/applib-svc/pages/persistence-layer-api/H2ManagerMenu.adoc
@@ -9,7 +9,6 @@ The `H2ManagerMenu` provides a single menu item to redirect to the H2 web consol
This is only enabled for prototyping, and only if H2 is detected in the underlying JDBC URL.
The menu appears under the "Prototyping" menu.
-
== API & Implementation
The API of the service is:
@@ -25,7 +24,7 @@ Note that this launches the manager on the same host that the webapp runs, and s
== Additional Configuration
-The following additional configuration is also required (all of this is present in the helloworld and simpleapp archetypes):
+The following additional configuration is also required (all of this is present in the helloworld and simpleapp starter apps):
* the h2 jdbc driver is required on the classpath of the webapp:
+
@@ -38,7 +37,7 @@ The following additional configuration is also required (all of this is present
</dependency>
----
-* the `jdbc:h2` URL configuration properties must be defined, eg in `isis.properties`:
+* the `jdbc:h2` URL configuration properties must be defined, eg in `application.properties`:
+
[source,ini]
.isis.properties
@@ -69,12 +68,10 @@ isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionPassword=
</servlet-mapping>
----
-
== Disabling/hiding the menu
The menu can be hidden or disabled by subscribing to its domain event, eg:
-
[source,java]
----
import org.springframework.context.event.EventListener;
diff --git a/api/applib/src/main/adoc/modules/applib-svc/pages/testing/FixtureScriptsSpecificationProvider.adoc b/api/applib/src/main/adoc/modules/applib-svc/pages/testing/FixtureScriptsSpecificationProvider.adoc
index 7798543..212214f 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/pages/testing/FixtureScriptsSpecificationProvider.adoc
+++ b/api/applib/src/main/adoc/modules/applib-svc/pages/testing/FixtureScriptsSpecificationProvider.adoc
@@ -1,4 +1,3 @@
-[[FixtureScriptsSpecificationProvider]]
= `FixtureScriptsSpec'nProvider`
: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:
@@ -15,8 +14,6 @@ Of the two designs, we encourage you to implement this "provider" SPI rather tha
The primary benefit (apart from decoupling responsibilities) is that it ensures that there is always an instance of `FixtureScripts` available for use.
====
-
-
== SPI
The SPI defined by the service is:
@@ -46,11 +43,9 @@ public class FixtureScriptsSpecification {
The class is immutable but it has a builder (obtained using `FixturescriptsSpecification.builder(...)`) for a fluent API.
-
-
== Implementation
-The link:https://github.com/apache/isis-app-simpleapp[SimpleApp archetype] has a simple implementation of this service:
+The link:https://github.com/apache/isis-app-simpleapp[SimpleApp] starter app has a simple implementation of this service:
[source,java]
----
diff --git a/core/config/src/main/adoc/modules/config/pages/specifying-components.adoc b/core/config/src/main/adoc/modules/config/pages/specifying-components.adoc
index f126add..3bae498 100644
--- a/core/config/src/main/adoc/modules/config/pages/specifying-components.adoc
+++ b/core/config/src/main/adoc/modules/config/pages/specifying-components.adoc
@@ -16,7 +16,7 @@ This allows the components, services and entities to be specified from a single
To specify the `AppManifest` as a configuration property, use:
.Core Configuration Properties (ignored if `isis.appManifest` is present)
-[cols="2a,1,3a", options="header"]
+[cols="2a,1,3a",options="header"]
|===
|Property
|Value +
@@ -28,7 +28,7 @@ To specify the `AppManifest` as a configuration property, use:
|`o.a.i.applib.AppManifest` +
By convention this implementation resides in an `myapp-app` Maven module (as opposed to `myapp-dom` or `myapp-fixture`).
-See the link:https://github.com/apache/isis-app-simpleapp[SimpleApp archetype] for details.
+See the link:https://github.com/apache/isis-app-simpleapp[SimpleApp] starter app for details.
|===
@@ -49,17 +49,12 @@ public interface AppManifest {
These can return either:
- * "shiro" - enable integration with Apache Shiro, as described in the xref:security:ROOT:about.adoc[security] user guide
- * "bypass" - bypass security (in effect, configure a no-op implementation that allows everything).
+* "shiro" - enable integration with Apache Shiro, as described in the xref:security:ROOT:about.adoc[security] user guide
+* "bypass" - bypass security (in effect, configure a no-op implementation that allows everything).
Note that these are actually aliases for concrete implementations.
It is also possible to specify a fully qualified class name to replace either of the two security components, implementing the appropriate interface.
-
-
-
-
-
== Viewer Configuration
Viewers are specified by way of the filters and servlets in the xref:userguide:btb:web-xml.adoc[`web.xml`] file; these are not bootstrapped by the framework, rather it is the other way around.
diff --git a/legacy/testing/mavenplugin/src/main/doc/modules/mvn/pages/intro.adoc b/legacy/testing/mavenplugin/src/main/doc/modules/mvn/pages/intro.adoc
index 3741a60..4f07956 100644
--- a/legacy/testing/mavenplugin/src/main/doc/modules/mvn/pages/intro.adoc
+++ b/legacy/testing/mavenplugin/src/main/doc/modules/mvn/pages/intro.adoc
@@ -2,6 +2,9 @@
: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 [...]
+CAUTION: TODO: v2: this has been removed, instead see integtest module for corresponding utilities to perform the same.
+
+
The Apache Isis Maven plugin defines three goals:
* `validate` +
@@ -81,6 +84,3 @@ We recommend the following:
* run the `xsd` plugin in a new `xsd` submodule; contributed actions are irrelevant for this particular goal; having a separate submodule allows the configuration of both the `xsd` goal (to generate the XSD schemas) and any other XSD-related configuration to be kept in a single place.
-The link:https://github.com/apache/isis-app-simpleapp[SimpleApp archetype] reflects these recommendations for the `validate` and `swagger` goals.
-You can find an example of the `xsd` plugin in the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] application.
-
diff --git a/persistence/jdo/src/main/adoc/modules/ROOT/pages/configuring/disabling-persistence-by-reachability.adoc b/persistence/jdo/src/main/adoc/modules/ROOT/pages/configuring/disabling-persistence-by-reachability.adoc
index 9059bcf..d21c4bb 100644
--- a/persistence/jdo/src/main/adoc/modules/ROOT/pages/configuring/disabling-persistence-by-reachability.adoc
+++ b/persistence/jdo/src/main/adoc/modules/ROOT/pages/configuring/disabling-persistence-by-reachability.adoc
@@ -26,12 +26,10 @@ We therefore recommend that you disable persistence-by-reachability by adding th
isis.persistor.datanucleus.impl.datanucleus.persistenceByReachabilityAtCommit=false
----
-This change has been made to both the link:https://github.com/apache/isis-app-helloworld[HelloWorld] and link:https://github.com/apache/isis-app-simpleapp[SimpleApp] archetypes.
+This change has been made to both the link:https://github.com/apache/isis-app-helloworld[HelloWorld] and link:https://github.com/apache/isis-app-simpleapp[SimpleApp] starter apps.
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/src/main/adoc/modules/ROOT/pages/configuring/persistence-xml.adoc b/persistence/jdo/src/main/adoc/modules/ROOT/pages/configuring/persistence-xml.adoc
index b50127d..f553ea5 100644
--- a/persistence/jdo/src/main/adoc/modules/ROOT/pages/configuring/persistence-xml.adoc
+++ b/persistence/jdo/src/main/adoc/modules/ROOT/pages/configuring/persistence-xml.adoc
@@ -8,7 +8,7 @@ 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 link:https://github.com/apache/isis-app-simpleapp[SimpleApp archetype]:
+Here's the one provided by the link:https://github.com/apache/isis-app-simpleapp[SimpleApp] starter app:
[source,xml]
----
diff --git a/security/adoc/modules/ROOT/pages/about.adoc b/security/adoc/modules/ROOT/pages/about.adoc
index 94befe2..c42d4fa 100644
--- a/security/adoc/modules/ROOT/pages/about.adoc
+++ b/security/adoc/modules/ROOT/pages/about.adoc
@@ -32,7 +32,7 @@ Shiro in turn uses the concept of a _realm_ as a source for both authentication
WARNING: TODO: v2: Spring Boot requires that shiro.ini is on classpath, not in WEB-INF.
Shiro ships with a simple text-based realm -- the `IniRealm` -- which reads users (and password), user roles and role permissions from the `WEB-INF/shiro.ini` file.
-The link:https://github.com/apache/isis-app-helloworld[HelloWorld] and link:https://github.com/apache/isis-app-simpleapp[SimpleApp] archetypes are both configured to use this realm.
+The link:https://github.com/apache/isis-app-helloworld[HelloWorld] and link:https://github.com/apache/isis-app-simpleapp[SimpleApp] starter apps are both configured to use this realm.
Shiro also ships with an implementation of an LDAP-based realm; LDAP is often used to manage user/passwords and corresponding user groups.
Apache Isis in turn extends this with its `IsisLdapRealm`, which provides more flexibility for both group/role and role/permissions management.
diff --git a/security/shiro/src/main/adoc/modules/shiro/pages/about/configuring-isis-to-use-shiro.adoc b/security/shiro/src/main/adoc/modules/shiro/pages/about/configuring-isis-to-use-shiro.adoc
index 4692cdd..657f186 100644
--- a/security/shiro/src/main/adoc/modules/shiro/pages/about/configuring-isis-to-use-shiro.adoc
+++ b/security/shiro/src/main/adoc/modules/shiro/pages/about/configuring-isis-to-use-shiro.adoc
@@ -9,7 +9,7 @@ The Shiro security mechanism is an integration wih Apache Shiro that implements
[TIP]
====
-Both the link:https://github.com/apache/isis-app-helloworld[HelloWorld] and link:https://github.com/apache/isis-app-simpleapp[SimpleApp] archetypes are pre-configured to use Apache Shiro, so much of what follows may well have been set up already.
+Both the link:https://github.com/apache/isis-app-helloworld[HelloWorld] and link:https://github.com/apache/isis-app-simpleapp[SimpleApp] starter apps are pre-configured to use Apache Shiro, so much of what follows may well have been set up already.
====
@@ -17,7 +17,9 @@ Both the link:https://github.com/apache/isis-app-helloworld[HelloWorld] and link
To tell Apache Isis to use Shiro when using an xref:refguide:applib-cm:rgcms.adoc#__rgcms_classes_AppManifest-bootstrapping_bootstrapping_AppManifestAbstract[`AppManifestAbstract.BUILDER`], simply specify the "authMechanism" as "shiro".
-For example, the link:https://github.com/apache/isis-app-helloworld[HelloWorld archetype] bootstraps using:
+For example, the link:https://github.com/apache/isis-app-helloworld[HelloWorld] starter app bootstraps using:
+
+// TODO: v2: this is out of date.
[source,java]
----
diff --git a/security/shiro/src/main/adoc/modules/shiro/pages/about/ini-realm.adoc b/security/shiro/src/main/adoc/modules/shiro/pages/about/ini-realm.adoc
index 59b7486..0493fa7 100644
--- a/security/shiro/src/main/adoc/modules/shiro/pages/about/ini-realm.adoc
+++ b/security/shiro/src/main/adoc/modules/shiro/pages/about/ini-realm.adoc
@@ -10,7 +10,7 @@ Probably the simplest realm to use is Shiro's built-in `IniRealm`, which reads f
This is suitable for prototyping, but isn't intended for production use, if only because user/password credentials are stored in plain text.
Nevertheless, it's a good starting point.
-The app generated by both the link:https://github.com/apache/isis-app-helloworld[HelloWorld] and link:https://github.com/apache/isis-app-simpleapp[SimpleApp] archetypes are configured to use this realm.
+The app generated by both the link:https://github.com/apache/isis-app-helloworld[HelloWorld] and link:https://github.com/apache/isis-app-simpleapp[SimpleApp] starter apps are configured to use this realm.
The diagram below shows the Isis and components involved:
diff --git a/starters/adoc/modules/helloworld/pages/about.adoc b/starters/adoc/modules/helloworld/pages/about.adoc
index 6238135..eca5cbc 100644
--- a/starters/adoc/modules/helloworld/pages/about.adoc
+++ b/starters/adoc/modules/helloworld/pages/about.adoc
@@ -232,7 +232,7 @@ src/main/java/
META-INF/
persistence.xml <!--9-->
----
-<1> For simplicity, all the Java source files generated by the archetype are placed in a `domainapp` top-level package.
+<1> For simplicity, all the Java source files reside in a `domainapp` top-level package.
Change as required.
<2> Defines the 'hello' module.
Apache Isis can be used for both microservice and monolithic architectures, but for the latter it encourages "modular monoliths" from the start.
diff --git a/starters/adoc/modules/simpleapp/pages/about.adoc b/starters/adoc/modules/simpleapp/pages/about.adoc
index be2f9dc..19a8b10 100644
--- a/starters/adoc/modules/simpleapp/pages/about.adoc
+++ b/starters/adoc/modules/simpleapp/pages/about.adoc
@@ -358,7 +358,7 @@ src/main/java/
META-INF/
persistence.xml <!--8-->
----
-<1> For simplicity, all the Java source files generated by the archetype are placed in a `domainapp` top-level package.
+<1> For simplicity, all the Java source files reside in a `domainapp` top-level package.
Change as required.
<2> Defines the 'simple' module.
Apache Isis can be used for both microservice and monolithic architectures, but for the latter it encourages "modular monoliths" from the start.
diff --git a/testing/fixtures/adoc/modules/fixtures/pages/fixture-scripts/api-and-usage.adoc b/testing/fixtures/adoc/modules/fixtures/pages/fixture-scripts/api-and-usage.adoc
index 2ec15f2..169caa6 100644
--- a/testing/fixtures/adoc/modules/fixtures/pages/fixture-scripts/api-and-usage.adoc
+++ b/testing/fixtures/adoc/modules/fixtures/pages/fixture-scripts/api-and-usage.adoc
@@ -18,7 +18,7 @@ This is annotated to be rendered on the secondary "Prototyping" menu.
The behaviour of this domain menu service can be refined by providing an implementation of the optional xref:refguide:applib-svc:testing/FixtureScriptsSpecificationProvider.adoc[`FixtureScriptsSpecificationProvider`] SPI.
-For example, here's the `FixtureScriptsSpecificationProvider` service that's generated by the link:https://github.com/apache/isis-app-simpleapp[SimpleApp archetype]:
+For example, here's the `FixtureScriptsSpecificationProvider` service that's generated by the link:https://github.com/apache/isis-app-simpleapp[SimpleApp] starter apps:
[source,java]
----
@@ -88,9 +88,6 @@ You are free, of course, to add additional "convenience" actions into it if you
Let's now look at the `FixtureScript` class, where there's a bit more going on.
-
-
-
== `FixtureScript`
A fixture script is ultimately just a block of code that can be executed, so it's up to you how you implement it to set up the system.
@@ -98,7 +95,7 @@ However, we strongly recommend that you use it to invoke actions on business obj
That way, the fixture script will remain valid even if the underlying implementation of the system changes in the future.
For example, here's a fixture script called `RecreateSimpleObjects`.
-(This used to be part of the link:https://github.com/apache/isis-app-simpleapp[SimpleApp archetype], though the archetype now ships with a more sophisticated design, discussed below):
+(This used to be part of the link:https://github.com/apache/isis-app-simpleapp[SimpleApp] starter app, though it now has a more sophisticated design, discussed below):
[source,java]
----
@@ -152,7 +149,6 @@ Note that although the fixture script is a view model, it's fine to simply insta
<9> calling another fixture script (`SimpleObjectCreate`) using the provided `ExecutionContext`
<10> adding the created object to the list, for the calling object to use.
-
Because this script has exposed a "number" property, it's possible to set this from within the UI.
For example:
@@ -161,13 +157,13 @@ image::prompt-specifying-number.png[width="700px",link="{imagesdir}/prompt-speci
When this is executed, the framework will parse the text and attempt to reflectively set the corresponding properties on the fixture result.
So, in this case, when the fixture script is executed we actually get 6 objects created.
-
-
== Using within Tests
Fixture scripts can be called from integration tests just the same way that fixture scripts can call one another.
-For example, here's an integration test from the link:https://github.com/apache/isis-app-simpleapp[SimpleApp archetype]:
+For example, here's an integration test from the link:https://github.com/apache/isis-app-simpleapp[SimpleApp] starter app:
+
+// TODO: v2: this will be out of date, no doubt.
[source,java]
----
@@ -204,8 +200,6 @@ public class SimpleObjectIntegTest extends SimpleAppIntegTest {
<4> wrap the object (to simulate being interacted with through the UI)
<5> inject the `FixtureScripts` domain service (just like any other domain service)
-
-
== Personas and Builders
Good integration tests are probably the best way to understand the behaviour of the domain model: better, even, than reading the code itself.
@@ -249,7 +243,7 @@ public interface PersonaWithFinder<T> {
}
----
-The link:https://github.com/apache/isis-app-simpleapp[SimpleApp archetype] provides a sample implementation of these interfaces:
+The link:https://github.com/apache/isis-app-simpleapp[SimpleApp] starter app provides a sample implementation of these interfaces:
[source,java]
----
diff --git a/viewers/wicket/adoc/modules/ROOT/pages/layout/file-based.adoc b/viewers/wicket/adoc/modules/ROOT/pages/layout/file-based.adoc
index 51d6f78..ee6580c 100644
--- a/viewers/wicket/adoc/modules/ROOT/pages/layout/file-based.adoc
+++ b/viewers/wicket/adoc/modules/ROOT/pages/layout/file-based.adoc
@@ -458,7 +458,7 @@ Ensure the following is defined in the dom project's `pom.xml`:
</resources>
----
-If using an Apache Isis link:https://github.com/apache/isis-app-helloworld[HelloWorld] link:https://github.com/apache/isis-app-simpleapp[SimpleApp] archetypes, then the POM is already correctly configured.
+If using an Apache Isis link:https://github.com/apache/isis-app-helloworld[HelloWorld] link:https://github.com/apache/isis-app-simpleapp[SimpleApp] starter app, then the POM is already correctly configured.
diff --git a/viewers/wicket/adoc/modules/ROOT/pages/menubars-layout/file-based.adoc b/viewers/wicket/adoc/modules/ROOT/pages/menubars-layout/file-based.adoc
index cc9b2b8..a2eedfe 100644
--- a/viewers/wicket/adoc/modules/ROOT/pages/menubars-layout/file-based.adoc
+++ b/viewers/wicket/adoc/modules/ROOT/pages/menubars-layout/file-based.adoc
@@ -37,7 +37,7 @@ image::/menubars/020-download.png[width="400px",link="{imagesdir}/menubars/020-d
The "Default" layout is that currently in use, while the "Fallback" layout is that provided only from the annotations.
Initially these are identical.
-For example, here's a fragment of that provided by the simpleapp archetype:
+For example, here's a fragment of that provided by the link:https://github.com/apache/isis-app-simpleapp[SimpleApp] starter app:
[source,xml]
----