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 2017/08/01 12:43:59 UTC
[4/6] isis git commit: ISIS-1674: updates documentation to reference
helloworld archetype where necessary.
ISIS-1674: updates documentation to reference helloworld archetype where necessary.
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/ddf0cc50
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/ddf0cc50
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/ddf0cc50
Branch: refs/heads/master
Commit: ddf0cc5028122f2522f3e726a614b910b09683ac
Parents: fc6d72b
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Tue Aug 1 13:21:41 2017 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Tue Aug 1 13:21:41 2017 +0100
----------------------------------------------------------------------
.../src/main/asciidoc/downloads.adoc | 6 +-
.../guides/cgcom/_cgcom_cutting-a-release.adoc | 213 ++++++++++++-
.../cgcom/_cgcom_post-release-successful.adoc | 171 ++++++-----
.../cgcom/_cgcom_post-release-unsuccessful.adoc | 3 +
.../guides/cgcom/_cgcom_verifying-releases.adoc | 44 ++-
.../asciidoc/guides/dg/_dg_ide_eclipse.adoc | 7 +-
.../rgcfg/_rgcfg_specifying-components.adoc | 3 +-
.../asciidoc/guides/rgmvn/_rgmvn_intro.adoc | 35 +--
.../asciidoc/guides/rgmvn/_rgmvn_validate.adoc | 21 +-
...bootstrapping-spi_ClassDiscoveryService.adoc | 17 +-
...ing_FixtureScriptsSpecificationProvider.adoc | 14 +-
.../guides/ugbtb/_ugbtb_deployment_neo4j.adoc | 3 +
.../main/asciidoc/guides/ugbtb/_ugbtb_i18n.adoc | 107 ++++---
.../guides/ugfun/_ugfun_getting-started.adoc | 36 +--
...un_getting-started_datanucleus-enhancer.adoc | 73 +----
...un_getting-started_helloworld-archetype.adoc | 296 +++++++++++++++++++
.../_ugfun_getting-started_prerequisites.adoc | 28 ++
...fun_getting-started_simpleapp-archetype.adoc | 184 ++++++------
.../_ugfun_programming-model_properties.adoc | 2 +-
.../helloworld-before-launch.png | Bin 0 -> 38237 bytes
.../ugfun/images/getting-started/helloworld.png | Bin 0 -> 30714 bytes
.../simpleapp-webapp-before-launch.png | Bin 0 -> 40147 bytes
.../simpleapp-webapp-with-fixtures.png | Bin 36797 -> 32657 bytes
.../images/getting-started/simpleapp-webapp.png | Bin 33311 -> 32086 bytes
.../using-hello-world/010-root-page.png | Bin 0 -> 64409 bytes
.../020-login-to-wicket-viewer.png | Bin 0 -> 25150 bytes
.../using-hello-world/030-home-page.png | Bin 0 -> 42723 bytes
.../040-create-object-from-menu.png | Bin 0 -> 44895 bytes
.../050-create-object-from-menu-prompt.png | Bin 0 -> 48527 bytes
.../using-hello-world/060-created-object.png | Bin 0 -> 27737 bytes
.../using-hello-world/070-update-name.png | Bin 0 -> 28151 bytes
.../using-hello-world/080-edit-notes.png | Bin 0 -> 30637 bytes
.../using-hello-world/090-delete-object.png | Bin 0 -> 34082 bytes
.../using-hello-world/100-object-deleted.png | Bin 0 -> 21273 bytes
.../200-swagger-ui-before-reload.png | Bin 0 -> 18982 bytes
.../210-helloworld-resources.png | Bin 0 -> 63727 bytes
.../220-create-object-thru-rest-api.png | Bin 0 -> 62583 bytes
...230-create-object-thru-rest-api-response.png | Bin 0 -> 59458 bytes
.../240-retrieve-object-using-rest-api.png | Bin 0 -> 65829 bytes
...-retrieve-object-using-rest-api-response.png | Bin 0 -> 62611 bytes
.../using-simple-app/010-root-page.png | Bin 70336 -> 0 bytes
.../020-login-to-wicket-viewer.png | Bin 38080 -> 0 bytes
.../030-home-page-run-fixture-scripts.png | Bin 48682 -> 0 bytes
.../using-simple-app/030-home-page.png | Bin 0 -> 24943 bytes
.../using-simple-app/040-first-object.png | Bin 38474 -> 0 bytes
.../040-run-fixture-script-menu.png | Bin 0 -> 37569 bytes
.../050-run-fixture-script-prompt.png | Bin 0 -> 34941 bytes
.../using-simple-app/050-update-name-prompt.png | Bin 47597 -> 0 bytes
.../using-simple-app/060-object-updated.png | Bin 39452 -> 0 bytes
.../060-run-fixture-script-result.png | Bin 0 -> 43088 bytes
.../using-simple-app/070-home-page.png | Bin 0 -> 26848 bytes
.../using-simple-app/070-list-all-prompt.png | Bin 42560 -> 0 bytes
.../using-simple-app/080-list-all.png | Bin 36487 -> 0 bytes
.../using-simple-app/090-create.png | Bin 41232 -> 0 bytes
.../using-simple-app/100-create-prompt.png | Bin 44741 -> 0 bytes
.../using-simple-app/110-object-created.png | Bin 39691 -> 0 bytes
.../using-simple-app/120-list-all.png | Bin 37239 -> 0 bytes
.../220-login-to-restful-viewer.png | Bin 72319 -> 0 bytes
.../using-simple-app/230-home-page.png | Bin 74329 -> 0 bytes
.../using-simple-app/240-list-all-invoke.png | Bin 78260 -> 0 bytes
.../using-simple-app/250-list-all-results.png | Bin 89138 -> 0 bytes
...g_disabling-persistence-by-reachability.adoc | 25 +-
.../_ugsec_configuring-isis-to-use-shiro.adoc | 27 +-
...c_shiro-realm-implementations_ini-realm.adoc | 19 +-
.../src/main/asciidoc/guides/ugsec/ugsec.adoc | 37 +--
...st_bdd-spec-support_maven-configuration.adoc | 10 +-
...tst_bdd-spec-support_writing-a-bdd-spec.adoc | 26 +-
.../_ugtst_fixture-scripts_api-and-usage.adoc | 80 ++---
..._ugtst_integ-test-support_bootstrapping.adoc | 24 +-
..._integ-test-support_maven-configuration.adoc | 13 +-
...t_unit-test-support_maven-configuration.adoc | 13 +-
.../ugvw/_ugvw_customisation_about-page.adoc | 18 +-
.../guides/ugvw/_ugvw_layout_file-based.adoc | 58 ++--
.../_migration-notes_1.10.0-to-1.11.0.adoc | 45 ++-
.../_migration-notes_1.11.0-to-1.12.0.adoc | 61 ++--
...o-1.9.0_bootstrapping-using-AppManifest.adoc | 15 +-
...n-notes_1.8.0-to-1.9.0_upgrading-to-dn4.adoc | 15 +-
...tion-notes_1.8.0-to-1.9.0_war-packaging.adoc | 14 +-
.../common-use-cases/common-use-cases.adoc | 26 +-
.../isis-in-pictures/isis-in-pictures.adoc | 5 +
.../asciidoc/pages/more-thanks/more-thanks.adoc | 1 -
.../bookmark/BookmarkHolder_lookup.java | 7 +-
.../bookmark/BookmarkHolder_object.java | 4 +-
.../applib/services/dto/Dto_downloadXml.java | 10 +-
.../applib/services/dto/Dto_downloadXsd.java | 18 +-
.../layout/Object_downloadLayoutXml.java | 14 +-
.../layout/Object_rebuildMetamodel.java | 6 +-
.../services/swagger/SwaggerServiceMenu.java | 8 +-
.../Persistable_datanucleusIdLong.java | 8 +-
.../Persistable_datanucleusVersionLong.java | 8 +-
...Persistable_datanucleusVersionTimestamp.java | 8 +-
.../Persistable_downloadJdoMetadata.java | 10 +-
.../viewer/services/Object_clearHints.java | 20 +-
example/application/helloworld/README.adoc | 2 +-
example/application/helloworld/pom.xml | 14 +-
.../domainapp/dom/impl/HelloWorldObject.java | 2 +-
.../domainapp/dom/impl/HelloWorldObjects.java | 2 +-
.../helloworld/src/main/webapp/about/index.html | 2 +-
.../dom/impl/HelloWorldObjectTest_delete.java | 69 +++++
.../impl/HelloWorldObjectTest_updateName.java | 40 +++
example/application/simpleapp/README.adoc | 11 +-
.../tests/SimpleObject_IntegTest.java | 4 +-
recreate_archetype_RELEASE.sh | 2 +-
recreate_archetype_SNAPSHOT.sh | 2 +-
scripts/updateGeneratedArchetypeSources.groovy | 11 +-
105 files changed, 1416 insertions(+), 661 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/downloads.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/downloads.adoc b/adocs/documentation/src/main/asciidoc/downloads.adoc
index c75c375..5a56d3e 100644
--- a/adocs/documentation/src/main/asciidoc/downloads.adoc
+++ b/adocs/documentation/src/main/asciidoc/downloads.adoc
@@ -28,7 +28,11 @@ Core:
* https://www.apache.org/dyn/closer.cgi/isis/isis-core/isis-1.14.0-source-release.zip[isis-1.14.0] (https://www.apache.org/dist/isis/isis-core/isis-1.14.0-source-release.zip.asc[asc], https://www.apache.org/dist/isis/isis-core/isis-1.14.0-source-release.zip.md5[md5])
-Archetype:
+HelloWorld Archetype (`1.15.0-SNAPSHOT` onwards):
+
+* https://www.apache.org/dyn/closer.cgi/isis/archetype/helloworld-archetype/helloworld-archetype-1.14.0-source-release.zip[helloworld-archetype-1.14.0] (https://www.apache.org/dist/isis/archetype/helloworld-archetype/helloworld-archetype-1.14.0-source-release.zip.asc[asc], https://www.apache.org/dist/isis/archetype/helloworld-archetype/helloworld-archetype-1.14.0-source-release.zip.md5[md5])
+
+SimpleApp Archetype:
* https://www.apache.org/dyn/closer.cgi/isis/archetype/simpleapp-archetype/simpleapp-archetype-1.14.0-source-release.zip[simpleapp-archetype-1.14.0] (https://www.apache.org/dist/isis/archetype/simpleapp-archetype/simpleapp-archetype-1.14.0-source-release.zip.asc[asc], https://www.apache.org/dist/isis/archetype/simpleapp-archetype/simpleapp-archetype-1.14.0-source-release.zip.md5[md5])
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_cutting-a-release.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_cutting-a-release.adoc b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_cutting-a-release.adoc
index c8a1cc4..49648c6 100644
--- a/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_cutting-a-release.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_cutting-a-release.adoc
@@ -365,12 +365,13 @@ You may (again) be prompted for gpg passphrase. All being well this command wil
-[[__cgcom_cutting-a-release_releasing-the-archetype]]
-== Releasing the Archetype
+[[__cgcom_cutting-a-release_releasing-the-archetypes]]
+== Releasing the Archetypes
Apache Isis archetypes are reverse engineered from example applications.
Once reverse engineered, the source is checked into git (replacing any earlier version of the archetype) and released.
+There are currently two archetypes, `simpleapp` and `helloworld`.
[NOTE]
====
@@ -382,6 +383,9 @@ The fix is to simple: just copy `mvn.cmd` to `mvn.bat`.
====
+[[__cgcom_cutting-a-release_releasing-the-archetypes_simpleapp_setup-environment-variables]]
+=== Releasing `simpleapp` archetype
+
Switch to the directory containing the `simpleapp` example:
[source,bash]
@@ -389,8 +393,8 @@ Switch to the directory containing the `simpleapp` example:
cd ../example/application/simpleapp
----
-[[__cgcom_cutting-a-release_releasing-the-archetype_setup-environment-variables]]
-=== Setup environment variables
+[[__cgcom_cutting-a-release_releasing-the-archetypes_simpleapp_setup-environment-variables]]
+==== Setup environment variables
Set additional environment variables for the `simpleapp-archetype` artifact:
@@ -407,8 +411,8 @@ env | grep ISIS | sort
<1> `$ISISPAR` is the version of the Apache Isis core that will act as the archetype's parent. Usually this is the same as `$ISISREL`.
-[[__cgcom_cutting-a-release_releasing-the-archetype_check-the-example-app]]
-=== Check the example app
+[[__cgcom_cutting-a-release_releasing-the-archetypes_simpleapp_check-the-example-app]]
+==== Check the example app
Update the parent `pom.xml` to reference the _released_ version of Apache Isis core, eg:
@@ -494,8 +498,8 @@ The Kitematic UI tool is handy for viewing and interacting with running containe
In each case, check the about page and confirm has been built against non-SNAPSHOT versions of the Apache Isis jars.
-[[__cgcom_cutting-a-release_releasing-the-archetype_create-the-archetype]]
-=== Create the archetype
+[[__cgcom_cutting-a-release_releasing-the-archetypes_simpleapp_create-the-archetype]]
+==== Create the archetype
Make sure you are in the correct directory and environment variables are correct.
@@ -518,7 +522,7 @@ The script automatically commits changes; if you wish use `git log` and
`git diff` (or a tool such as SourceTree) to review changes made.
-[[__cgcom_cutting-a-release_releasing-the-archetype_release-prepare]]
+[[__cgcom_cutting-a-release_releasing-the-archetypes_simpleapp_release-prepare]]
=== Release prepare
Switch to the *archetype* directory and execute the `release:prepare`:
@@ -535,8 +539,8 @@ mvn release:prepare -P apache-release \
-[[__cgcom_cutting-a-release_releasing-the-archetype_post-prepare-sanity-check]]
-=== Post-prepare sanity check
+[[__cgcom_cutting-a-release_releasing-the-archetypes_simpleapp_post-prepare-sanity-check]]
+==== Post-prepare sanity check
This is a good point to test the archetype; nothing has yet been uploaded.
@@ -576,8 +580,191 @@ mvn -pl webapp jetty:run # runs as mvn jetty plugin
-[[__cgcom_cutting-a-release_releasing-the-archetype_release-perform-upload]]
-=== Release Perform (upload)
+[[__cgcom_cutting-a-release_releasing-the-archetypes_simplapp_release-perform-upload]]
+==== Release Perform (upload)
+
+Back in the original session (in the *archetype* directory, `example/archetype/$ISISCPN`), execute `release:perform`:
+
+[source]
+----
+mvn release:perform -P apache-release \
+ -DworkingDirectory=$ISISTMP/checkout
+----
+
+This will upload the artifacts to the ASF Nexus repository.
+
+
+[[__cgcom_cutting-a-release_releasing-the-archetypes_helloworld_setup-environment-variables]]
+=== Releasing `helloworld` archetype
+
+We now repeat the procedure for the `helloworld` example app.
+
+Start by switching to the directory containing the `helloworld` example:
+
+[source,bash]
+----
+cd ../example/application/helloworld
+----
+
+[[__cgcom_cutting-a-release_releasing-the-archetypes_helloworld_setup-environment-variables]]
+==== Setup environment variables
+
+Update additional environment variables for the `helloworld-archetype` artifact:
+
+[source,bash]
+----
+export ISISART=helloworld-archetype
+export ISISPAR=$ISISREL
+
+export ISISCPT=$(echo $ISISART | cut -d- -f2)
+export ISISCPN=$(echo $ISISART | cut -d- -f1)
+
+env | grep ISIS | sort
+----
+
+
+[[__cgcom_cutting-a-release_releasing-the-archetypes_helloworld_check-the-example-app]]
+==== Check the example app
+
+Update the parent `pom.xml` to reference the _released_ version of Apache Isis core, eg:
+
+[source,xml]
+----
+<properties>
+ <isis.version>1.15.0</isis.version>
+ ...
+</properties>
+----
+
+
+Finally, double check that the app
+
+* builds:
++
+[source,bash]
+----
+mvn clean install
+----
+
+* can be run from an IDE
+** mainClass=`org.apache.isis.WebServer`
+** args=`-m domainapp.application.HelloWorldAppManifest`
+** run before: `mvn datanucleus:enhance -o` in the root module
+
+* can be run using the mvn jetty plugin:
++
+[source,bash]
+----
+mvn jetty:run
+----
+
+* can be deployed as a WAR
++
+[source,bash]
+----
+cp target/helloworld.war $CATALINA_HOME/webapps/ROOT.war
+pushd $CATALINA_HOME/bin
+sh startup.sh
+tail -f ../logs/catalina.out
+----
++
+quit using:
++
+[source,bash]
+----
+sh shutdown.sh
+popd
+----
+
+This too should be accessed at link:http://localhost:8080[localhost:8080].
+
+In each case, check the about page and confirm has been built against non-SNAPSHOT versions of the Apache Isis jars.
+
+
+[[__cgcom_cutting-a-release_releasing-the-archetypes_helloworld_create-the-archetype]]
+==== Create the archetype
+
+Make sure you are in the correct directory and environment variables are correct.
+
+To recreate the *helloworld* archetype:
+
+[source,bash]
+----
+cd example/application/helloworld
+env | grep ISIS | sort
+----
+
+Then, run the script:
+
+[source,bash]
+----
+sh ../../../scripts/recreate-archetype.sh $ISISJIRA
+----
+
+The script automatically commits changes; if you wish use `git log` and
+`git diff` (or a tool such as SourceTree) to review changes made.
+
+
+[[__cgcom_cutting-a-release_releasing-the-archetypes_helloworld_release-prepare]]
+=== Release prepare
+
+Switch to the *archetype* directory and execute the `release:prepare`:
+
+[source]
+----
+cd ../../../example/archetype/$ISISCPN
+rm -rf $ISISTMP/checkout
+mvn release:prepare -P apache-release \
+ -DreleaseVersion=$ISISREL \
+ -DdevelopmentVersion=$ISISDEV \
+ -Dtag=$ISISART-$ISISREL
+----
+
+
+
+[[__cgcom_cutting-a-release_releasing-the-archetypes_helloworld_post-prepare-sanity-check]]
+==== Post-prepare sanity check
+
+This is a good point to test the archetype; nothing has yet been uploaded.
+
+_In a different session_, create a new app from the archetype. First set up environment variables:
+
+[source,bash]
+----
+export ISISTMP=/c/tmp # or as required
+export ISISCPN=helloworld
+env | grep ISIS | sort
+----
+
+Then generate a new app from the archetype:
+
+[source,bash]
+----
+rm -rf $ISISTMP/test-$ISISCPN
+
+mkdir $ISISTMP/test-$ISISCPN
+cd $ISISTMP/test-$ISISCPN
+mvn archetype:generate \
+ -D archetypeCatalog=local \
+ -D groupId=com.mycompany \
+ -D artifactId=myapp \
+ -D archetypeGroupId=org.apache.isis.archetype \
+ -D archetypeArtifactId=$ISISCPN-archetype
+----
+
+Build the newly generated app and test:
+
+[source,bash]
+----
+cd myapp
+mvn clean install -o
+mvn jetty:run
+----
+
+
+
+[[__cgcom_cutting-a-release_releasing-the-archetypes_simplapp_release-perform-upload]]
+==== Release Perform (upload)
Back in the original session (in the *archetype* directory, `example/archetype/$ISISCPN`), execute `release:perform`:
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_post-release-successful.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_post-release-successful.adoc b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_post-release-successful.adoc
index 0c2b2f1..6321b97 100644
--- a/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_post-release-successful.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_post-release-successful.adoc
@@ -12,7 +12,8 @@ The release process consists of:
* members of the Apache Isis PMC xref:../cgcom/cgcom.adoc#_cgcom_verifying-releases[verifying] and voting on the release
* the release manager performing post-release tasks, for either a successful or an xref:../cgcom/cgcom.adoc#_cgcom_post-release-unsuccessful[unsuccessful] vote (former documented below)
-For a vote to succeed, there must be +3 votes from PMC members, and the vote must have been open at least 72 hours. If there are not +3 votes after this time then it is perfectly permissible to keep the vote open longer.
+For a vote to succeed, there must be +3 votes from PMC members, and the vote must have been open at least 72 hours.
+If there are not +3 votes after this time then it is perfectly permissible to keep the vote open longer.
This section describes the steps to perform if the vote has been successful.
@@ -25,7 +26,7 @@ Post the results to the `dev@isis.a.o` mailing list:
[source,bash]
----
-[RESULT] [VOTE] Apache Isis Core release 1.14.0
+[RESULT] [VOTE] Apache Isis Core release 1.15.0
----
using the body (alter last line as appropriate):
@@ -53,8 +54,9 @@ You can do this using the `scripts/promoterctag.sh` script; for example:
[source,bash]
----
-sh scripts/promoterctag.sh isis-1.14.0 RC1
-sh scripts/promoterctag.sh simpleapp-archetype-1.14.0 RC1
+sh scripts/promoterctag.sh isis-1.15.0 RC1
+sh scripts/promoterctag.sh helloworld-archetype-1.15.0 RC1
+sh scripts/promoterctag.sh simpleapp-archetype-1.15.0 RC1
----
This script pushes the tag under `refs/tags/rel`. As per Apache policy (communicated on 10th Jan 2016 to Apache PMCs),
@@ -79,9 +81,13 @@ This moves the release artifacts into an Apache releases repository; from there
== 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]. Once a release vote passes, the release manager should `svn add` the artifacts (plus signature and hash files) into this location. The release is then automatically pushed to http://www.apache.org/dist/[http://www.apache.org/dist/] by `svnpubsub`. Only the most recent release of each supported release line should be contained here, old versions should be deleted.
+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].
+Once a release vote passes, the release manager should `svn add` the artifacts (plus signature and hash files) into this location.
+The release is then automatically pushed to http://www.apache.org/dist/[http://www.apache.org/dist/] by `svnpubsub`.
+Only the most recent release of each supported release line should be contained here, old versions should be deleted.
-Each project is responsible for the structure of its directory. The directory structure of Apache Isis reflects the directory structure in our git source code repo:
+Each project is responsible for the structure of its directory.
+The directory structure of Apache Isis reflects the directory structure in our git source code repo:
[source]
----
@@ -99,7 +105,8 @@ If necessary, checkout this directory structure:
svn co https://dist.apache.org/repos/dist/release/isis isis-dist
----
-Next, add the new release into the appropriate directory, and delete any previous release. The `upd.sh` script (also downloadable from link:https://gist.github.com/danhaywood/aa79c18d993df1b1e2c5a9933e48bcbc[this gist]) can be used to automate this:
+Next, add the new release into the appropriate directory, and delete any previous release.
+The `upd.sh` script (also downloadable from link:https://gist.github.com/danhaywood/aa79c18d993df1b1e2c5a9933e48bcbc[this gist]) can be used to automate this:
[source,bash]
----
@@ -137,6 +144,27 @@ 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"
@@ -159,14 +187,15 @@ popd
[source,bash]
----
-sh upd.sh 1.14.0 1.15.0
+sh upd.sh 1.15.0 1.16.0
----
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):
+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):
[source,bash]
----
@@ -192,13 +221,14 @@ From the root directory, generate the release notes for the current release, in
[source,bash]
----
-sh scripts/jira-release-notes.sh ISIS 1.14.0 > /tmp/1
+sh scripts/jira-release-notes.sh ISIS 1.15.0 > /tmp/1
----
=== 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.
+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.
@@ -224,7 +254,8 @@ Log the new release in the link:https://reporter.apache.org/addrelease.html?isis
Update the Apache Isis (asciidoc) website:
-* Paste in the JIRA-generated release notes generated above, adding to top of `adocs/documentation/src/main/asciidoc/release-notes.adoc`. Also add a summary line for the release.
+* Paste in the JIRA-generated release notes generated above, adding to top of `adocs/documentation/src/main/asciidoc/release-notes.adoc`.
+Also add a summary line for the release.
* Search for any `-SNAPSHOT` suffices, and remove
@@ -236,7 +267,8 @@ Update the Apache Isis (asciidoc) website:
+
A search for `archetypeGroupId=org.apache.isis.archetype` should find these pages.
-* update the link:../../doap_isis.rdf[DOAP RDF] file (which provides a machine-parseable description of the project) should also be updated with details of the new release. Validate using the http://www.w3.org/RDF/Validator/[W3C RDF Validator] service. +
+* update the link:../../doap_isis.rdf[DOAP RDF] file (which provides a machine-parseable description of the project) should also be updated with details of the new release.
+Validate using the http://www.w3.org/RDF/Validator/[W3C RDF Validator] service. +
+
For more information on DOAP files, see these http://projects.apache.org/doap.html[Apache policy docs].
@@ -248,7 +280,6 @@ Don't forget to commit the `.adoc` changes and publish to the isis-site repo.
-
== Announce the release
Announce the release to link:mailto:users@isis.apache.org[users mailing list].
@@ -257,14 +288,14 @@ For example, for a release of Apache Isis Core, use the following subject:
[source,bash]
----
-[ANN] Apache Isis version 1.14.0 Released
+[ANN] Apache Isis version 1.15.0 Released
----
And use the following body (summarizing the main points as required):
[source]
----
-The Apache Isis team is pleased to announce the release of Apache Isis v1.14.0.
+The Apache Isis team is pleased to announce the release of Apache Isis v1.15.0.
New features in this release include:
* ...
@@ -278,8 +309,8 @@ Enjoy!
--The Apache Isis team
-[1] http://isis.apache.org/release-notes.html#r1.14.0
-[2] http://isis.apache.org/migration-notes.html#_migration-notes_1.13.0-to-1.14.0
+[1] http://isis.apache.org/release-notes.html#r1.15.0
+[2] http://isis.apache.org/migration-notes.html#_migration-notes_1.14.0-to-1.15.0
[3] http://search.maven.org
[4] http://isis.apache.org/downloads.html
----
@@ -289,7 +320,8 @@ Enjoy!
== 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.
+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.
@@ -303,13 +335,13 @@ Because we release from a branch, the changes made in the branch (changes to `po
----
git checkout master # update master with latest
git pull
-git merge release-1.14.0-RC1 # merge branch onto master
-git push origin --delete release-1.14.0-RC1 # remote branch no longer needed
-git branch -d release-1.14.0-RC1 # branch no longer needed
+git merge release-1.15.0-RC1 # merge branch onto master
+git push origin --delete release-1.15.0-RC1 # remote branch no longer needed
+git branch -d release-1.15.0-RC1 # branch no longer needed
----
-Finally, update the simpleapp's root `pom.xml` to reference the next SNAPSHOT release (`1.15.0-SNAPSHOT`)
+Finally, update helloworld's `pom.xml` and simpleapp's root `pom.xml` to reference the next SNAPSHOT release (`1.16.0-SNAPSHOT`)
@@ -320,6 +352,7 @@ With the release complete, now is a good time to bump versions of dependencies (
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`.
@@ -342,7 +375,8 @@ 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. Since this goes off to the internet, it may take a minute or two to run:
+The `maven-versions-plugin` should be used to determine if there are newer versions of any of the plugins used to build Apache Isis.
+Since this goes off to the internet, it may take a minute or two to run:
[source,bash]
----
@@ -350,13 +384,15 @@ mvn versions:display-plugin-updates > /tmp/foo
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).
+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. Since this goes off to the internet, it may take a minute or two to run:
+The `maven-versions-plugin` should be used to determine if there are newer versions of any of Isis' dependencies.
+Since this goes off to the internet, it may take a minute or two to run:
[source,bash]
----
@@ -364,7 +400,9 @@ mvn versions:display-dependency-updates > /tmp/foo
grep "\->" /tmp/foo | /bin/sort -u
----
-Update any of the dependencies that are out-of-date. That said, do note that some dependencies may show up with a new dependency, when in fact the dependency is for an old, badly named version. Also, there may be new dependencies that you do not wish to move to, eg release candidates or milestones.
+Update any of the dependencies that are out-of-date.
+That said, do note that some dependencies may show up with a new dependency, when in fact the dependency is for an old, badly named version.
+Also, there may be new dependencies that you do not wish to move to, eg release candidates or milestones.
For example, here is a report showing both of these cases:
@@ -388,7 +426,8 @@ For these artifacts you will need to search http://search.maven.org[Maven centra
== 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/templates/Apache-code-style-formatting.xml[this] Eclipse template and link:../dg/resources/eclipse/isis.importorder[this] import order.
+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/templates/Apache-code-style-formatting.xml[this] Eclipse template and link:../dg/resources/eclipse/isis.importorder[this] import order.
@@ -434,15 +473,15 @@ The `org.incode:incode-parent` Maven module is used as a parent for both sets of
+
[source,bash]
----
-sh bumpver_isis.sh 1.14.0
+sh bumpver_isis.sh 1.15.0
----
* update the README
** replace each version with next (ie the "How to Configure/Use" section, and the "Release to Maven Central" section at the end):
-*** replace 1.14.0-SNAPSHOT with 1.15.0-SNAPSHOT
-*** replace 1.13.0 with 1.14.0
+*** replace 1.15.0-SNAPSHOT with 1.16.0-SNAPSHOT
+*** replace 1.14.0 with 1.15.0
** update the "Change Log" section
@@ -450,7 +489,7 @@ sh bumpver_isis.sh 1.14.0
+
[source,bash]
----
-sh release.sh "1.14.0" "1.15.0-SNAPSHOT" "dan@haywood-associates.co.uk" "this is not really my password"
+sh release.sh "1.15.0" "1.16.0-SNAPSHOT" "dan@haywood-associates.co.uk" "this is not really my password"
----
@@ -464,15 +503,15 @@ The three `org.incode:mavendeps-isisXXX` module should be released next.
+
[source,bash]
----
-foreach -g incodehq/mavendeps sh bumpver_isis.sh 1.14.0
+foreach -g incodehq/mavendeps sh bumpver_isis.sh 1.15.0
----
* update the README
** replace each version with next (ie the "How to Configure/Use" section, and the "Release to Maven Central" section at the end):
-*** replace 1.14.0-SNAPSHOT with 1.15.0-SNAPSHOT
-*** replace 1.13.0 with 1.14.0
+*** replace 1.15.0-SNAPSHOT with 1.16.0-SNAPSHOT
+*** replace 1.14.0 with 1.15.0
** update the "Change Log" section
@@ -480,14 +519,14 @@ foreach -g incodehq/mavendeps sh bumpver_isis.sh 1.14.0
+
[source,bash]
----
-foreach -g incodehq/mavendeps sh sh release.sh "1.14.0" "1.15.0-SNAPSHOT" "dan@haywood-associates.co.uk" \"this is not really my password\"
+foreach -g incodehq/mavendeps sh sh release.sh "1.15.0" "1.16.0-SNAPSHOT" "dan@haywood-associates.co.uk" \"this is not really my password\"
----
* update its dependency on Apache Isis to reference the next SNAPSHOT: +
+
[source,bash]
----
-foreach -g incodehq/mavendeps sh bumpver_isis.sh 1.15.0-SNAPSHOT
+foreach -g incodehq/mavendeps sh bumpver_isis.sh 1.16.0-SNAPSHOT
----
@@ -503,7 +542,7 @@ Using this link:https://gist.github.com/danhaywood/21b5b885433fd8bc440da3fab88c9
+
[source,bash]
----
-foreach -g isisaddons sh bumpver_isis.sh 1.14.0
+foreach -g isisaddons sh bumpver_isis.sh 1.15.0
----
+
and use: +
@@ -533,8 +572,8 @@ to review changes made.
** replace each version with next (ie the "How to Configure/Use" section, and the "Release to Maven Central" section at the end):
-*** replace `1.14.0` with `1.15.0`
-*** replace `1.13.0` with `1.14.0` as necessary (pretty much everywhere apart from the "Change Log")
+*** replace `1.15.0` with `1.16.0`
+*** replace `1.14.0` with `1.15.0` as necessary (pretty much everywhere apart from the "Change Log")
** update the "Change Log" section
@@ -542,14 +581,14 @@ to review changes made.
+
[source,bash]
----
-foreach -g isisaddons/isis-[mw] sh release.sh "1.14.0" "1.15.0-SNAPSHOT" "dan@haywood-associates.co.uk" \"this is not really my password\"
+foreach -g isisaddons/isis-[mw] sh release.sh "1.15.0" "1.16.0-SNAPSHOT" "dan@haywood-associates.co.uk" \"this is not really my password\"
----
* In the parent directory where the `last_modified.sh` script has been saved (see xref:../cgcom/cgcom.adoc#__cgcom_post-release-successful_release-non-asf-modules_prereqs[above]), use to check that all modules were released successfully: +
+
[source,bash]
----
-foreach -g isisaddons/isis-[mw] sh ../../last-modified.sh 1.14.0
+foreach -g isisaddons/isis-[mw] sh ../../last-modified.sh 1.15.0
----
+
[IMPORTANT]
@@ -561,7 +600,7 @@ Wait at least 10 minutes to check; sync'ing to Maven central from the Sonatype O
+
[source,bash]
----
-foreach -g isisaddons/isis-[mw] "git push origin master && git push origin 1.14.0"
+foreach -g isisaddons/isis-[mw] "git push origin master && git push origin 1.15.0"
----
@@ -576,7 +615,7 @@ Using this link:https://gist.github.com/danhaywood/21b5b885433fd8bc440da3fab88c9
+
[source,bash]
----
-foreach -g incodehq/incode-module sh bumpver_isis.sh 1.14.0
+foreach -g incodehq/incode-module sh bumpver_isis.sh 1.15.0
----
* update the README for each repository. +
@@ -590,8 +629,8 @@ eg if using Windows, then:
** Replace each version with next (ie the "How to Configure/Use" section, and the "Release to Maven Central" section at the end):
-*** replace `1.14.0` with `1.15.0`
-*** replace `1.13.0` with `1.14.0` as necessary (pretty much everywhere apart from the "Change Log")
+*** replace `1.15.0` with `1.16.0`
+*** replace `1.14.0` with `1.15.0` as necessary (pretty much everywhere apart from the "Change Log")
** update the "Change Log" section
@@ -618,14 +657,14 @@ For example, `incode-module-base` must be released prior to `incode-module-alias
+
[source,bash]
----
-foreach -g incodehq/incode-module-[a-w] sh release.sh "1.14.0" "1.15.0-SNAPSHOT" "dan@haywood-associates.co.uk" \"this is not really my password\"
+foreach -g incodehq/incode-module-[a-w] sh release.sh "1.15.0" "1.16.0-SNAPSHOT" "dan@haywood-associates.co.uk" \"this is not really my password\"
----
* In the parent directory where the `last_modified.sh` script has been saved (see xref:../cgcom/cgcom.adoc#__cgcom_post-release-successful_release-non-asf-modules_prereqs[above]), use to check that all modules were released successfully: +
+
[source,bash]
----
-foreach -g incodehq/incode-module-[a-w] sh ../../last-modified.sh 1.14.0
+foreach -g incodehq/incode-module-[a-w] sh ../../last-modified.sh 1.15.0
----
+
[IMPORTANT]
@@ -637,29 +676,29 @@ Wait at least 10 minutes to check; sync'ing to Maven central from the Sonatype O
+
[source,bash]
----
-foreach -g incodehq/incode-module-[a-w] "git push origin master && git push origin 1.14.0"
+foreach -g incodehq/incode-module-[a-w] "git push origin master && git push origin 1.15.0"
----
[[__cgcom_post-release-successful_release-non-asf-modules_incode-catalog_cross-module-dependencies]]
==== Cross-module dependencies
-As of v1.14.0, the list of dependencies that needed to be updated (across all modules) were:
-
-** `<isis-module-fakedata.version>1.14.0</isis-module-fakedata.version>`
-** `<isis-module-freemarker.version>1.14.0</isis-module-freemarker.version>`
-** `<isis-wicket-fullcalendar2-cpt.version>1.14.0</isis-wicket-fullcalendar2-cpt.version>`
-** `<isis-wicket-gmap3-cpt.version>1.14.0</isis-wicket-gmap3-cpt.version>`
-** `<isis-module-poly.version>1.14.0</isis-module-poly.version>`
-** `<isis-module-security.version>1.14.0</isis-module-security.version>`
-** `<incode-module-base.version>1.14.0</incode-module-base.version>`
-** `<incode-module-fixturesupport.version>1.14.0</incode-module-fixturesupport.version>`
-** `<incode-module-unittestsupport.version>1.14.0</incode-module-unittestsupport.version>`
-** `<incode-module-integtestsupport.version>1.14.0</incode-module-integtestsupport.version>`
-** `<incode-module-country.version>1.14.0</incode-module-country.version>`
-** `<incode-module-document.version>1.14.0</incode-module-document.version>`
-** `<incode-module-docrendering-freemarker.version>1.14.0</incode-module-docrendering-freemarker.version>`
-** `<incode-module-docrendering-stringinterpolator.version>1.14.0</incode-module-docrendering-stringinterpolator.version>`
-** `<incode-module-docrendering-xdocreport.version>1.14.0</incode-module-docrendering-xdocreport.version>`
+As of v1.15.0, the list of dependencies that needed to be updated (across all modules) were:
+
+** `<isis-module-fakedata.version>1.15.0</isis-module-fakedata.version>`
+** `<isis-module-freemarker.version>1.15.0</isis-module-freemarker.version>`
+** `<isis-wicket-fullcalendar2-cpt.version>1.15.0</isis-wicket-fullcalendar2-cpt.version>`
+** `<isis-wicket-gmap3-cpt.version>1.15.0</isis-wicket-gmap3-cpt.version>`
+** `<isis-module-poly.version>1.15.0</isis-module-poly.version>`
+** `<isis-module-security.version>1.15.0</isis-module-security.version>`
+** `<incode-module-base.version>1.15.0</incode-module-base.version>`
+** `<incode-module-fixturesupport.version>1.15.0</incode-module-fixturesupport.version>`
+** `<incode-module-unittestsupport.version>1.15.0</incode-module-unittestsupport.version>`
+** `<incode-module-integtestsupport.version>1.15.0</incode-module-integtestsupport.version>`
+** `<incode-module-country.version>1.15.0</incode-module-country.version>`
+** `<incode-module-document.version>1.15.0</incode-module-document.version>`
+** `<incode-module-docrendering-freemarker.version>1.15.0</incode-module-docrendering-freemarker.version>`
+** `<incode-module-docrendering-stringinterpolator.version>1.15.0</incode-module-docrendering-stringinterpolator.version>`
+** `<incode-module-docrendering-xdocreport.version>1.15.0</incode-module-docrendering-xdocreport.version>`
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_post-release-unsuccessful.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_post-release-unsuccessful.adoc b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_post-release-unsuccessful.adoc
index 94b80f5..c414545 100644
--- a/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_post-release-unsuccessful.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_post-release-unsuccessful.adoc
@@ -61,6 +61,7 @@ git push --delete origin release-1.14.0-RC1
[source,bash]
----
git push --delete origin isis-1.14.0-RC1
+git push --delete origin helloworld-archetype-1.14.0-RC1
git push --delete origin simpleapp-archetype-1.14.0-RC1
----
@@ -71,6 +72,8 @@ git push --delete origin simpleapp-archetype-1.14.0-RC1
----
git tag -d isis-1.14.0
git tag -d isis-1.14.0-RC1
+git tag -d helloworld-archetype-1.14.0
+git tag -d helloworld-archetype-1.14.0-RC1
git tag -d simpleapp-archetype-1.14.0
git tag -d simpleapp-archetype-1.14.0-RC1
----
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_verifying-releases.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_verifying-releases.adoc b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_verifying-releases.adoc
index deace8a..60ee43c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_verifying-releases.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_verifying-releases.adoc
@@ -95,7 +95,7 @@ Confirm that the versions of the Isis artifacts now cached in your local reposit
==== 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 xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype1] 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 xref:../ugfun/ugfun.adoc#_ugfun_getting-started_helloworld-archetype[HelloWorld archetype] or the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] and running the resultant app.
Configuring your local Maven install amounts to updating the `~/.m2/settings.xml` file:
@@ -223,12 +223,14 @@ The script could be enhanced in many ways, feel free to contribute improvements!
==== Create an input file
-The input file is a plain `.txt` file containing all urls to the packages to be verified. Here's a sample of the release of Apache Isis 1.8.0:
+The input file is a plain `.txt` file containing all urls to the packages to be verified.
+Here's a sample of the release of Apache Isis 1.15.0:
[source]
----
-https://repository.apache.org/content/repositories/orgapacheisis-063/org/apache/isis/core/isis/1.8.0/isis-1.8.0-source-release.zip
-https://repository.apache.org/content/repositories/orgapacheisis-065/org/apache/isis/archetype/simpleapp-archetype/1.8.0/simpleapp-archetype-1.8.0-source-release.zip
+https://repository.apache.org/content/repositories/orgapacheisis-063/org/apache/isis/core/isis/1.8.0/isis-1.15.0-source-release.zip
+https://repository.apache.org/content/repositories/orgapacheisis-065/org/apache/isis/archetype/helloworld-archetype/1.8.0/simpleapp-archetype-1.15.0-source-release.zip
+https://repository.apache.org/content/repositories/orgapacheisis-065/org/apache/isis/archetype/simpleapp-archetype/1.8.0/simpleapp-archetype-1.15.0-source-release.zip
----
The actual list of packages to be verified will be provided through the mailing list.
@@ -271,16 +273,38 @@ In this report, each binary will have three links listed after its name '(licens
-== Test the archetype
+== Test the archetypes
Assuming that everything builds ok, then test the archetypes (adjust version as necessary):
+* First the `helloworld` archetype: +
++
+[source,bash]
+----
+mvn archetype:generate \
+ -D archetypeGroupId=org.apache.isis.archetype \
+ -D archetypeArtifactId=helloworld-archetype \
+ -D archetypeVersion=1.15.0 \
+ -D groupId=com.mycompany \
+ -D artifactId=myapp \
+ -D version=1.0-SNAPSHOT \
+ -B \
+ -o
+
+cd myapp
+mvn clean install jetty:run -o
+----
++
+Adjust the version as necessary.
+
+* Next, the `simpleapp` archetype: +
++
[source,bash]
----
mvn archetype:generate \
-D archetypeGroupId=org.apache.isis.archetype \
-D archetypeArtifactId=simpleapp-archetype \
- -D archetypeVersion=1.14.0 \
+ -D archetypeVersion=1.15.0 \
-D groupId=com.mycompany \
-D artifactId=myapp \
-D version=1.0-SNAPSHOT \
@@ -288,12 +312,12 @@ mvn archetype:generate \
-o
cd myapp
-mvn clean install -o
-cd webapp
-mvn jetty:run
+mvn clean install -o && mvn -pl jetty:run -o
----
++
+Adjust the version as necessary.
-Adjust the version as necessary. If it runs up ok, then it's time to xref:../cgcom/cgcom.adoc#_cgcom_verifying-releases[vote]!
+If the archetypes run up ok, then it's time to xref:../cgcom/cgcom.adoc#_cgcom_verifying-releases[vote]!
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_eclipse.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_eclipse.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_eclipse.adoc
index 68eac51..f7f68ef 100644
--- a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_eclipse.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_eclipse.adoc
@@ -75,14 +75,15 @@ image::{_imagesdir}eclipse/eclipse-110-project-support.png[width="600px",link="{
=== 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.
+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 earlier section on xref:../ugfun/ugfun.adoc#_ugfun_getting-started_datanucleus-enhancer[DataNucleus enhancer] for details of the contents of the `pom.xml`. Chances are it is already set up from running the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
+See the earlier section on xref:../ugfun/ugfun.adoc#_ugfun_getting-started_datanucleus-enhancer[DataNucleus enhancer] for details of the contents of the `pom.xml`.
+Chances are it is already set up from running the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_helloworld-archetype[HelloWorld] or the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp] archetype.
Then, tell DataNucleus to use the project classpath:
-
image::{_imagesdir}eclipse/eclipse-010-windows-preferences.png[width="750px",link="{_imagesdir}eclipse/eclipse-010-windows-preferences.png"]
When the enhancer runs, it will print out to the console:
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/rgcfg/_rgcfg_specifying-components.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcfg/_rgcfg_specifying-components.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcfg/_rgcfg_specifying-components.adoc
index 77f5632..c1c5eca 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgcfg/_rgcfg_specifying-components.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgcfg/_rgcfg_specifying-components.adoc
@@ -27,7 +27,8 @@ To specify the `AppManifest` as a configuration property, use:
|`FQCN`
|`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 xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] for details.
+By convention this implementation resides in an `myapp-app` Maven module (as opposed to `myapp-dom` or `myapp-fixture`).
+See the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] for details.
|===
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_intro.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_intro.adoc b/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_intro.adoc
index 35fdf85..8b301d6 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_intro.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_intro.adoc
@@ -9,7 +9,8 @@ The Apache Isis Maven plugin defines three goals:
* `validate` +
+
-Use to verify at build time that the metamodel of an application is valid. This runs the `MetaModelValidator` that is also run when the application is started up.
+Use to verify at build time that the metamodel of an application is valid.
+This runs the `MetaModelValidator` that is also run when the application is started up.
* `swagger` +
+
@@ -21,22 +22,22 @@ Uses the xref:../rgsvc/rgsvc.adoc#_rgsvc_integration-api_JaxbService[`JaxbServic
+
This is instead of and preferable to using the JAXB link:https://jaxb.java.net/2.2.4/docs/schemagen.html[schemagen] tool, because it uses the framework's support (via xref:../rgant/rgant.adoc#_rgant-XmlJavaTypeAdapter[`@XmlJavaTypeAdapter`]) to translate any references to domain objects into ``OidDto``s (as defined by the Apache Isis xref:../rgcms/rgcms.adoc#_rgcms_schema-common[common schema]).
-The `validate` goal is by default bound to the `test` phase, and the `swagger` goal is by default bound to the `package` phase; both are typically of your application's `dom` sub-module. The `xsd` goal meanwhile defaults to the `generate-resources` phase, and this is generally used in a completely separate sub-module. An example can be found in the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] example app; the separate submodule that uses the `xsd` goal is (also) called `todoapp-xsd`.
+The `validate` goal is by default bound to the `test` phase, and the `swagger` goal is by default bound to the `package` phase; both are typically of your application's `dom` sub-module.
+The `xsd` goal meanwhile defaults to the `generate-resources` phase, and this is generally used in a completely separate sub-module.
+An example can be found in the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] example app; the separate submodule that uses the `xsd` goal is (also) called `todoapp-xsd`.
-All of these goals require an xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`] to point the plugin at, so that
-it knows how to bootstrap an Isis runtime. This is discussed below, followed by sections on configuring the two goals.
+All of these goals require an xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`] to point the plugin at, so that it knows how to bootstrap an Isis runtime.
+This is discussed below, followed by sections on configuring the two goals.
[[__rgmvn_intro_app-manifest]]
== `AppManifest`
-As noted in the introduction, all the goals require an xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`]
-to point the plugin at, so that it knows how to bootstrap an Isis runtime.
+As noted in the introduction, all the goals require an xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`] to point the plugin at, so that it knows how to bootstrap an Isis runtime.
-This can be extremely minimal; it isn't necessary to use the main `AppManifest` (in the `app` module) used to
-bootstrap the application, you can instead use a cut-down one. This then allows the plugins to be run during the
-build of the `dom` module, rather than having to run in the context of the `integtest` module.
+This can be extremely minimal; it isn't necessary to use the main `AppManifest` (in the `app` module) used to bootstrap the application, you can instead use a cut-down one.
+This then allows the plugins to be run during the build of the `dom` module, rather than having to run in the context of the `integtest` module.
For example, the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp]'s
manifest is:
@@ -74,20 +75,16 @@ public final class DomainAppDomainModule { }
----
-The downside of using a minimal `AppManifest` in the ``dom`` module is that any contributed actions/associations will
-be ignored.
+The downside of using a minimal `AppManifest` in the ``dom`` module is that any contributed actions/associations will be ignored.
We recommend the following:
-* run the `validate` goal in the `dom` submodule; this will give early warning if there are any syntactic errors in the
- model, eg orphaned supporting methods
+* run the `validate` goal in the `dom` submodule; this will give early warning if there are any syntactic errors in the model, eg orphaned supporting methods
-* run the `swagger` goal in the `integtest` submodule; this ensures that the generated Swagger spec files correctly
- include any contributed actions/associations.
+* run the `swagger` goal in the `integtest` submodule; this ensures that the generated Swagger spec files correctly include any contributed actions/associations.
-* 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.
+* 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 xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[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.
+The xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[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.
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_validate.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_validate.adoc b/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_validate.adoc
index 0ddebca..e7376b7 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_validate.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgmvn/_rgmvn_validate.adoc
@@ -8,14 +8,12 @@
The Apache Isis programming model requires that a number of naming conventions are followed.
-For example, the validator will detect any orphaned supporting methods (eg `hideXxx()`) if the corresponding property
-or action has been renamed or deleted but the supporting method was not also updated. Another example is that a class
-cannot have a title specified both using `title()` method and also using `@Title` annotation.
+For example, the validator will detect any orphaned supporting methods (eg `hideXxx()`) if the corresponding property or action has been renamed or deleted but the supporting method was not also updated.
+Another example is that a class cannot have a title specified both using `title()` method and also using `@Title` annotation.
When running the application these are enforced by the `MetaModelValidator` component that detects these errors, failing fast.
-The purpose of the `validate` goal of the `isis-maven-plugin` is to enforce these naming conventions at build time,
-typically enforced by way of a continuous integration server.
+The purpose of the `validate` goal of the `isis-maven-plugin` is to enforce these naming conventions at build time, typically enforced by way of a continuous integration server.
The `validate` goal defines a single property:
@@ -25,8 +23,8 @@ The sections below explain how to configure the plugin within an app.
[NOTE]
====
-The instructions given here relate to `1.10.0`. This goal was also released for `1.9.0`, but with a slightly
-different configuration; see the final section for differences.
+The instructions given here relate to `1.10.0`.
+This goal was also released for `1.9.0`, but with a slightly different configuration; see the final section for differences.
====
@@ -110,7 +108,8 @@ mvn test -Dskip.isis-validate
== Example of failure
-In the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp] application the `SimpleObject` defines an `updateName` action. This has a supporting method:
+In the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp] application the `SimpleObject` defines an `updateName` action.
+This has a supporting method:
[source,java]
@@ -161,7 +160,8 @@ If one were to attempt to run the application, the same error would appear in th
== Custom validation rules
-It is also possible to customize the validation, explained xref:../ugbtb/ugbtb.adoc#_ugbtb_programming-model_custom-validator[here]. For example, you could enforce project-specific conventions by implementing a custom `MetaModelValidator`, and registering using a configuration property.
+It is also possible to customize the validation, explained xref:../ugbtb/ugbtb.adoc#_ugbtb_programming-model_custom-validator[here].
+For example, you could enforce project-specific conventions by implementing a custom `MetaModelValidator`, and registering using a configuration property.
To support this using `AppManifest`s, override its `getConfigurationProperties()` method:
@@ -180,7 +180,8 @@ public class DomainAppDomManifest implements AppManifest {
== 1.9.0 version
-The `1.9.0` version of the plugin requires slightly different configuration. Rather than using an `AppManifest`, instead the configuration directory containing `isis.properties` is specified:
+The `1.9.0` version of the plugin requires slightly different configuration.
+Rather than using an `AppManifest`, instead the configuration directory containing `isis.properties` is specified:
[source,xml]
----
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_bootstrapping-spi_ClassDiscoveryService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_bootstrapping-spi_ClassDiscoveryService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_bootstrapping-spi_ClassDiscoveryService.adoc
index 24ad22c..ee6f151 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_bootstrapping-spi_ClassDiscoveryService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_bootstrapping-spi_ClassDiscoveryService.adoc
@@ -6,7 +6,8 @@
-The `ClassDiscovery` service is used to automatically discover subclasses of any given type on the classpath. The primary use case is to support "convention-over-configuration" designs that work with a minimum of configuration.
+The `ClassDiscovery` service is used to automatically discover subclasses of any given type on the classpath.
+The primary use case is to support "convention-over-configuration" designs that work with a minimum of configuration.
This service is used by the xref:../rgcms/rgcms.adoc#_rgcms_classes_super_FixtureScripts[`FixtureScripts`] service to automatically locate any xref:../rgcms/rgcms.adoc#_rgcms_classes_super_FixtureScript[`FixtureScript`] implementations.
@@ -36,15 +37,16 @@ Isis provides an implementation of this service, namely `o.a.i.applib.services.c
[NOTE]
====
-This implementation is also used to discover domain services annotated with xref:../rgant/rgant.adoc#_rgant-DomainService[`@DomainService`]. Currently this logic uses the implementation directly, so is not pluggable. However, the entire `ServicesInstaller`
+This implementation is also used to discover domain services annotated with xref:../rgant/rgant.adoc#_rgant-DomainService[`@DomainService`].
+Currently this logic uses the implementation directly, so is not pluggable.
====
== Usage
-The usage will vary depending upon the conventions of the design. As of 1.9.0, the usage of the service has been
-centralized such that the packages to be scanned are located from the xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`]'s `#getModules()` method.
+The usage will vary depending upon the conventions of the design.
+As of 1.9.0, the usage of the service has been centralized such that the packages to be scanned are located from the xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`]'s `#getModules()` method.
For example, the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]'s app manifest includes:
@@ -71,12 +73,9 @@ Other usages of the `ClassDiscoveryService` are likely to work in a similar way,
== Registering the Services
Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
-implementation of `ClassDiscoveryService2` service is automatically registered and injected (it is annotated with
-`@DomainService`) so no further configuration is required.
+`AppManifest` to xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core implementation of `ClassDiscoveryService2` service is automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
-To use an alternative implementation, use
-xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+To use an alternative implementation, use xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
in the xref:../rgsvc/rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_testing_FixtureScriptsSpecificationProvider.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_testing_FixtureScriptsSpecificationProvider.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_testing_FixtureScriptsSpecificationProvider.adoc
index c14d79f..2e64fda 100644
--- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_testing_FixtureScriptsSpecificationProvider.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_testing_FixtureScriptsSpecificationProvider.adoc
@@ -6,19 +6,15 @@
-The `FixtureScriptsSpecificationProvider` configures the
-xref:../rgsvc/rgsvc.adoc#_rgsvc_testing_FixtureScriptsDefault[`FixtureScriptsDefault`] domain service, providing the
-location to search for fixture scripts and other settings.
+The `FixtureScriptsSpecificationProvider` configures the xref:../rgsvc/rgsvc.adoc#_rgsvc_testing_FixtureScriptsDefault[`FixtureScriptsDefault`] domain service, providing the location to search for fixture scripts and other settings.
-The service is only used if the `FixtureScriptsDefault` service is instantiated as a fallback by the framework. If
-the application provides its own subclass of xref:../rgcms/rgcms.adoc#_rgcms_classes_super_FixtureScripts[`FixtureScripts`]
-superclass, then this provider service is not used.
+The service is only used if the `FixtureScriptsDefault` service is instantiated as a fallback by the framework.
+If the application provides its own subclass of xref:../rgcms/rgcms.adoc#_rgcms_classes_super_FixtureScripts[`FixtureScripts`] superclass, then this provider service is not used.
[TIP]
====
-Of the two designs, we encourage you to implement this "provider" SPI rather than subclass `FixtureScripts`. The
-primary benefit (apart from decoupling responsibilities) is that it ensures that there is always an instance of
-`FixtureScripts` available for use.
+Of the two designs, we encourage you to implement this "provider" SPI rather than subclass `FixtureScripts`.
+The primary benefit (apart from decoupling responsibilities) is that it ensures that there is always an instance of `FixtureScripts` available for use.
====
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_neo4j.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_neo4j.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_neo4j.adoc
index c3c450d..15eed56 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_neo4j.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_deployment_neo4j.adoc
@@ -4,6 +4,7 @@
:_basedir: ../../
:_imagesdir: images/
+
As of 1.8.0 Apache Isis has experimental support for Neo4J, courtesy of DataNucleus' http://www.datanucleus.org/products/datanucleus/datastores/neo4j.html[Neo4J Datastore] implementation.
The xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] has been updated so that they can be optionally run under Neo4J.
@@ -15,6 +16,7 @@ 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:
@@ -46,6 +48,7 @@ Add the following dependency to the `webapp` project's `pom.xml`:
In the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[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:
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_i18n.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_i18n.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_i18n.adoc
index 416efa2..475f34d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_i18n.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_i18n.adoc
@@ -9,15 +9,18 @@ Apache Isis' support for internationlization (i18n) allows every element of the
It also supports translations of messages raised imperatively, by which we mean as the result of a call to `title()` to obtain an object's title, or messages resulting from any business rule violations (eg xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_disable[`disable...()`] or xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_validate[`validate...()`], and so on.
-The xref:../ugvw/ugvw.adoc#[Wicket viewer] (that is, its labels and messages) is also internationalized using the same mechanism. If no translations are available, then the Wicket viewer falls back to using Wicket resource bundles.
+The xref:../ugvw/ugvw.adoc#[Wicket viewer] (that is, its labels and messages) is also internationalized using the same mechanism.
+If no translations are available, then the Wicket viewer falls back to using Wicket resource bundles.
-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.
+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.
[[__ugbtb_i18n_implementation-approach]]
== Implementation Approach
-Most Java frameworks tackle i18n by using Java's own `ResourceBundle` API. However, there are some serious drawbacks in this approach, including:
+Most Java frameworks tackle i18n by using Java's own `ResourceBundle` API.
+However, there are some serious drawbacks in this approach, including:
* if a string appears more than once (eg "name" or "description") then it must be translated everywhere it appears in every resource bundle file
* 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])
@@ -27,14 +30,17 @@ Apache Isis therefore takes a different approach, drawing inspiration from GNU's
* 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
-* these `.po` files are renamed according to their locale, and placed into the 'appropriate' location to be picked up by the runtime. The name of each `.po` resolved in a very similar way to resource bundles.
+* these `.po` files are renamed according to their locale, and placed into the 'appropriate' location to be picked up by the runtime.
+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.
+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. This is for two reasons: (a) to simplify the toolchain/developer experience, and (b) because GNU software is usually GPL, which would be incompatible with the Apache license.
+Although Apache Isis' implementation is modelled after GNU's API, it does _not_ use any GNU software.
+This is for two reasons: (a) to simplify the toolchain/developer experience, and (b) because GNU software is usually GPL, which would be incompatible with the Apache license.
====
This design tackles all the issues of ``ResourceBundle``s:
@@ -43,9 +49,11 @@ This design tackles all the issues of ``ResourceBundle``s:
* 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. One such is https://crowdin.com/[crowdin] (nb: this link does not imply endorsement).
+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.
+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.
@@ -53,7 +61,8 @@ In Apache Isis' implementation, if the translation is missing from the `.po` fil
[[__ugbtb_i18n_translation-service]]
== `TranslationService`
-The cornerstone of Apache Isis' support for i18n is the `TranslationService` service. This is defined in the applib with the following API:
+The cornerstone of Apache Isis' support for i18n is the `TranslationService` service.
+This is defined in the applib with the following API:
[source,java]
----
@@ -77,7 +86,9 @@ public interface TranslationService {
<2> is to translate the plural form of the text
<3> indicates whether the translation service is in read or write mode.
-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 `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.
@@ -87,32 +98,39 @@ The mode meanwhile determines the behaviour of the service. More on this below.
Isis provides a default implementation of `TranslationService`, namely `TranslationServicePo`.
-If the service is running in the normal read mode, then it simply provides translations for the locale of the current user. This means locates the appropriate `.po` file (based on the requesting user's locale), finds the translation and returns it.
+If the service is running in the normal read mode, then it simply provides translations for the locale of the current user.
+This means locates the appropriate `.po` file (based on the requesting user's locale), finds the translation and returns it.
-If however the service is configured to run in write mode, then it instead records the fact that the message was requested to be translated (a little like a spy/mock in unit testing mock), and returns the original message. The service can then be queried to discover which messages need to be translated. All requested translations are written into the `.pot` file.
+If however the service is configured to run in write mode, then it instead records the fact that the message was requested to be translated (a little like a spy/mock in unit testing mock), and returns the original message.
+The service can then be queried to discover which messages need to be translated.
+All requested translations are written into the `.pot` file.
To make the service as convenient as possible to use, the service configures itself as follows:
-* if running in prototype mode xref:../rgcfg/rgcfg.adoc#_rgcfg_deployment-types[deployment type] or during integration tests, then the service runs in *write* mode, in which case it records all translations into the `.pot` file. The `.pot` file is written out when the system is shutdown.
-* if running in server (production) mode xref:../rgcfg/rgcfg.adoc#_rgcfg_deployment-types[deployment type], then the service runs in *read* mode. It is also possible to set a configuration setting in `isis.properties` to force read mode even if running in prototype mode (useful to manually test/demo the translations).
-
-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.
-
+* if running in prototype mode xref:../rgcfg/rgcfg.adoc#_rgcfg_deployment-types[deployment type] or during integration tests, then the service runs in *write* mode, in which case it records all translations into the `.pot` file.
+The `.pot` file is written out when the system is shutdown.
+* if running in server (production) mode xref:../rgcfg/rgcfg.adoc#_rgcfg_deployment-types[deployment type], then the service runs in *read* mode.
+It is also possible to set a configuration setting in `isis.properties` to force read mode even if running in prototype mode (useful to manually test/demo the translations).
+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.
[[__ugbtb_i18n_imperative-messages]]
== 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. Thus the simple act of bootstrapping Apache Isis will cause most of the messages requiring translation (that is: those for the Apache Isis metamodel) to be captured by the `TranslationService`.
+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.
+Thus the simple act of bootstrapping Apache Isis will cause most of the messages requiring translation (that is: those for the Apache Isis metamodel) to be captured by the `TranslationService`.
-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.
+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.
+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 xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]:
@@ -201,7 +219,8 @@ public interface DomainObjectContainer {
Another mechanism by which messages can be rendered to the user are as the result of exception messages thrown and recognized by an xref:../rgsvc/rgsvc.adoc#_rgsvc_presentation-layer-spi_ExceptionRecognizer[`ExceptionRecognizer`].
-In this case, if the exception implements `TranslatableException`, then the message will automatically be translated before being rendered. The `TranslatableException` itself takes the form:
+In this case, if the exception implements `TranslatableException`, then the message will automatically be translated before being rendered.
+The `TranslatableException` itself takes the form:
[source,java]
----
@@ -211,20 +230,19 @@ public interface TranslatableException {
}
----
-<1> the message to translate. If returns `null`, then the `Exception#getMessage()` is used as a fallback
+<1> the message to translate.
+If returns `null`, then the `Exception#getMessage()` is used as a fallback
<2> the context to use when translating the message
-
-
-
[[__ugbtb_i18n_wicket-viewer]]
== Wicket Viewer
The xref:../ugvw/ugvw.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 `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:
@@ -244,13 +262,13 @@ 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
+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.
-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.
+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
@@ -509,7 +527,8 @@ public void failsValidation() throws Exception {
Running this test will result in the framework calling the `validateUpdateName(...)` method, and thus to record that a translation is required in the `.pot` file.
-When the integration tests are complete (that is, when Apache Isis is shutdown), the `TranslationServicePo` will write out all captured translations to its log (more on this below). This will include all the translations captured from the Apache Isis metamodel, along with all translations as exercised by the integration tests.
+When the integration tests are complete (that is, when Apache Isis is shutdown), the `TranslationServicePo` will write out all captured translations to its log (more on this below).
+This will include all the translations captured from the Apache Isis metamodel, along with all translations as exercised by the integration tests.
To ensure your app is fully internationalized app, you must therefore:
@@ -520,14 +539,13 @@ To ensure your app is fully internationalized app, you must therefore:
====
We make no apologies for this requirement: one of the reasons that we decided to implement Apache Isis' i18n support in this way is because it encourages/requires the app to be properly tested.
-Behind the scenes Apache Isis uses a JUnit rule (`ExceptionRecognizerTranslate`) to intercept any exceptions that are thrown. These are simply passed through to the registered xref:../rgsvc/rgsvc.adoc#_rgsvc_presentation-layer-spi_ExceptionRecognizer[`ExceptionRecognizer`]s so that any messages are recorded as requiring translation.
+Behind the scenes Apache Isis uses a JUnit rule (`ExceptionRecognizerTranslate`) to intercept any exceptions that are thrown.
+These are simply passed through to the registered xref:../rgsvc/rgsvc.adoc#_rgsvc_presentation-layer-spi_ExceptionRecognizer[`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.
@@ -539,9 +557,7 @@ msgid "<i>Quantity</i>"
msgstr "<i>Quantité</i>"
----
-For this to work, the `namedEscaped()` attribute must be specified using either the
-xref:../ugvw/ugvw.adoc#_ugvw_layout_file-based[layout file], or using an annotation such as
-xref:../rgant/rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`] or xref:../rgant/rgant.adoc#_rgant-ParameterLayout[`@ParameterLayout`].
+For this to work, the `namedEscaped()` attribute must be specified using either the xref:../ugvw/ugvw.adoc#_ugvw_layout_file-based[layout file], or using an annotation such as xref:../rgant/rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`] or xref:../rgant/rgant.adoc#_rgant-ParameterLayout[`@ParameterLayout`].
For example:
@@ -583,7 +599,8 @@ Just to repeat, this is _not_ the `WEB-INF/logging.properties` file, it should i
=== Location of the `.po` files
-The default location of the translated `.po` files is in the `WEB-INF` directory. These are named and searched for similarly to regular Java resource bundles.
+The default location of the translated `.po` files is in the `WEB-INF` directory.
+These are named and searched for similarly to regular Java resource bundles.
For example, assuming these translations:
@@ -607,7 +624,8 @@ The basename for translation files is always `translations`; this cannot be alte
=== Externalized translation files
-Normally Apache Isis configuration files are read from the `WEB-INF` file. However, Apache Isis can be configured to read config files from an xref:../ugbtb/ugbtb.adoc#_ugbtb_deployment_externalized-configuration[external directory]; this is also supported for translations.
+Normally Apache Isis configuration files are read from the `WEB-INF` file.
+However, Apache Isis can be configured to read config files from an xref:../ugbtb/ugbtb.adoc#_ugbtb_deployment_externalized-configuration[external directory]; this is also supported for translations.
Thus, if in `web.xml` the external configuration directory has been set:
@@ -623,7 +641,8 @@ Then this directory will be used as the base for searching for translations (rat
=== Force read mode
-As noted above, if running in prototype mode then `TranslationServicePo` will be in write mode, if in production mode then will be in read mode. To force read mode (ie use translations) even if in prototype mode, add the following configuration property to `isis.properties`:
+As noted above, if running in prototype mode then `TranslationServicePo` will be in write mode, if in production mode then will be in read mode.
+To force read mode (ie use translations) even if in prototype mode, add the following configuration property to `isis.properties`:
[source,ini]
----
@@ -642,13 +661,15 @@ A default implementation is provided by the Wicket viewer.
[NOTE]
====
-Note that this default implementation does not support requests made through the Restful Objects viewer (there is no Wicket 'application' object available); the upshot is that requests through Restful Objects are never translated. Registering a different implementation of `LocaleProvider` that taps into appropriate REST (RestEasy?) APIs would be the way to address this.
+Note that this default implementation does not support requests made through the Restful Objects viewer (there is no Wicket 'application' object available); the upshot is that requests through Restful Objects are never translated.
+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).
+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`