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/03/25 23:40:27 UTC
[isis] 04/05: ISIS-2062: removes references to isis.properties
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch ISIS-2062
in repository https://gitbox.apache.org/repos/asf/isis.git
commit aa480d033ce41ee32052c76c7803652fc0bbe619
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Wed Mar 25 23:37:56 2020 +0000
ISIS-2062: removes references to isis.properties
---
.../deployment/externalized-configuration.adoc | 276 +--
.../modules/btb/pages/deployment/neo4j.adoc | 2 +-
api/adoc/userguide/modules/btb/pages/i18n.adoc | 12 +-
.../btb/pages/programming-model/finetuning.adoc | 25 +-
api/adoc/userguide/modules/btb/pages/web-xml.adoc | 1029 +++++------
.../pages/domain-entities-and-services/crud.adoc | 2 +-
.../applib-ant/pages/Action/publishing.adoc | 18 +-
.../modules/applib-ant/pages/Action/semantics.adoc | 1 +
.../applib-ant/pages/DomainObject/editing.adoc | 10 +-
.../applib-ant/pages/DomainObject/publishing.adoc | 12 +-
.../applib-ant/pages/Property/publishing.adoc | 6 +-
.../pages/PropertyLayout/labelPosition.adoc | 8 +-
.../pages/classes/utility/ObjectContracts.adoc | 2 +-
.../applib-svc/pages/ExceptionRecognizer.adoc | 6 +-
.../src/main/java/demoapp/dom/jee/JeeDemo.adoc | 16 +-
.../jdo/adoc/modules/ROOT/pages/configuring.adoc | 28 +-
.../disabling-persistence-by-reachability.adoc | 2 +-
.../modules/ROOT/pages/configuring/properties.adoc | 11 +-
.../pages/configuring/using-jndi-data-source.adoc | 15 +-
.../jdo/adoc/modules/ROOT/pages/db-schemas.adoc | 178 +-
.../hints-and-tips/overriding-jdo-annotations.adoc | 6 +-
.../h2console/pages/services/H2ManagerMenu.adoc | 12 +-
.../ROOT/pages/configuration-properties.adoc | 376 ++--
.../ROOT/pages/configuration-properties.adoc | 1870 ++++++++++----------
.../modules/ROOT/pages/features/where-am-i.adoc | 36 +-
25 files changed, 1991 insertions(+), 1968 deletions(-)
diff --git a/api/adoc/userguide/modules/btb/pages/deployment/externalized-configuration.adoc b/api/adoc/userguide/modules/btb/pages/deployment/externalized-configuration.adoc
index f67c503..43b44a6 100644
--- a/api/adoc/userguide/modules/btb/pages/deployment/externalized-configuration.adoc
+++ b/api/adoc/userguide/modules/btb/pages/deployment/externalized-configuration.adoc
@@ -5,141 +5,141 @@
:page-partial:
-WARNING: TODO - v2 - not yet reviewed, likely no longer relevant.
-
-
-As described xref:refguide:config:configuration-files.adoc[here], by default Apache Isis itself bootstraps from the
-`isis.properties` configuration file.
-It will also read configuration from the (optional) component/implementation-specific configuration files (such as `persistor_datanucleus.properties` or `viewer_wicket.properties`), and also (optional) component-specific configuration files (such as `persistor.properties` or `viewer.properties`).
-
-It's generally not good practice to have the same configuration property in more than one file, but if that does occur, then the subsequent configuration property will be ignored.
-
-[TIP]
-====
-In addition the framework will also load the `overrides.properties` file.
-This is intended to support deployment through Docker, as discussed xref:userguide:btb:about.adoc#docker[next].
-====
-
-All of these files are read from the `WEB-INF` directory.
-Having this configuration "baked into" the application is okay in a development environment, but when the app needs to be deployed to a test or production environment, this configuration should be read from an external location.
-
-There are in fact several frameworks involved here, all of which need to be pointed to this external location:
-
-* Apache Isis itself, which (as already discussed) reads `isis.properties` and optional component-specific config files.
-
-* link:http://shiro.apache.org[Apache Shiro], which reads the `shiro.ini` file (and may read other files referenced from that file)
-
-* http://logging.apache.org/log4j/1.2[Apache log4j 1.2], for logging, which reads `logging.properties` file
-
-* although not used by Apache Isis, there's a good chance you may be using the Spring framework (eg if using http://activemq.apache.org[Apache Active MQ] or http://camel.apache.org[Apache Camel].
-
-Each of these frameworks has its own way of externalizing its configuration.
-
-
-[TIP]
-====
-Subsequent sections explain how to externalize configuration for xref:userguide:btb:about.adoc#docker[Docker].
-====
-
-
-
-== Apache Isis' Config
-
-To tell Apache Isis to load configuration from an external directory, specify the `isis.config.dir` context parameter.
-
-
-If the external configuration directory is fixed for all environments (systest, UAT, prod etc), then you can specify within the `web.xml` itself:
-
-WARNING: TODO: v2: this has almost certainly changed, because the configuration is picked up earlier; this probably no longer works.
-
-[source,xml]
-----
-<context-param>
- <param-name>isis.config.dir</param-name>
- <param-value>location of external config directory</param-value>
-</context-param>
-----
-
-If however the configuration directory varies by environment, then the context parameter will be specified to each installation of your servlet container.
-Most (if not all) servlet containers will provide a means to define context parameters through proprietary config files.
-
-
-
-[NOTE]
-====
-Note that running the app using Apache Isis' `org.apache.isis.WebServer` bootstrapper does not use externalized Apache Isis configuration.
-====
-
-
-
-
-
-
-== Shiro Config
-
-If using Apache Isis' xref:security:shiro:configuring-isis-to-use-shiro.adoc[Shiro integration] for authentication and/or authorization, note that it reads from the `shiro.ini` configuration file.
-By default this also resides in `WEB-INF`.
-
-Similar to Apache Isis, Shiro lets this configuration directory be altered, by specifying the `shiroConfigLocations` context parameter.
-
-You can therefore override the default location using the same technique as described above for Apache Isis' `isis.config.dir` context parameter.
-For example:
-
-[source,xml]
-----
-<Parameter name="shiroConfigLocations"
- value="file:/usr/local/myapp/conf/shiro.ini"
- override="false" />
-----
-
-[TIP]
-====
-Note that Shiro is more flexible than Apache Isis; it will read its configuration from any URL, not just a directory on the local filesystem.
-====
-
-
-
-
-== Log4j Config
-
-By default Apache Isis configures log4j to read the `logging.properties` file in the `WEB-INF` directory.
-This can be overridden by setting the `log4j.properties` system property to the URL of the log4j properties file.
-
-[[log4j-config-tomcat]]
-=== Tomcat
-
-For example, if deploying to Tomcat7 or Tomcat8, this amounts to adding the following to the `CATALINA_OPTS` flags:
-
-[source,bash]
-----
-export CATALINA_OPTS="-Dlog4j.configuration=/usr/local/tomcat/myapp/conf/logging.properties"
-----
-
-[TIP]
-====
-`CATALINA_OPTS` was called `TOMCAT_OPTS` in earlier versions of Tomcat.
-====
-
-Further details an be found in the link:https://logging.apache.org/log4j/1.2/manual.html#Example_Configurations[log4j documentation].
-
-
-
-
-
-
-
-== JVM Args
-
-The xref:refguide:applib-svc:WrapperFactory.adoc[`WrapperFactory`] uses link:http://www.javassist.org[Javassist] to create on-the-fly classes acting as a proxy.
-The cost of these proxies can be mitigated using:
-
-[source,ini]
-----
--XX:+CMSClassUnloadingEnabled -XX:+UseConcMarkSweepGC
-----
-
-
-
-== Using a JNDI Datasource
-
-See the guidance in the xref:pjdo:ROOT:configuring.adoc#using-jndi-data-source[configuring datanucleus] section.
+WARNING: TODO - v2 - not yet reviewed, most is irrelevant since Spring Boot is used instead.
+
+
+//As described xref:refguide:config:configuration-files.adoc[here], by default Apache Isis itself bootstraps from the
+//`isis.properties` configuration file.
+//It will also read configuration from the (optional) component/implementation-specific configuration files (such as `persistor_datanucleus.properties` or `viewer_wicket.properties`), and also (optional) component-specific configuration files (such as `persistor.properties` or `viewer.properties`).
+//
+//It's generally not good practice to have the same configuration property in more than one file, but if that does occur, then the subsequent configuration property will be ignored.
+//
+//[TIP]
+//====
+//In addition the framework will also load the `overrides.properties` file.
+//This is intended to support deployment through Docker, as discussed xref:userguide:btb:about.adoc#docker[next].
+//====
+//
+//All of these files are read from the `WEB-INF` directory.
+//Having this configuration "baked into" the application is okay in a development environment, but when the app needs to be deployed to a test or production environment, this configuration should be read from an external location.
+//
+//There are in fact several frameworks involved here, all of which need to be pointed to this external location:
+//
+//* Apache Isis itself, which (as already discussed) reads `isis.properties` and optional component-specific config files.
+//
+//* link:http://shiro.apache.org[Apache Shiro], which reads the `shiro.ini` file (and may read other files referenced from that file)
+//
+//* http://logging.apache.org/log4j/1.2[Apache log4j 1.2], for logging, which reads `logging.properties` file
+//
+//* although not used by Apache Isis, there's a good chance you may be using the Spring framework (eg if using http://activemq.apache.org[Apache Active MQ] or http://camel.apache.org[Apache Camel].
+//
+//Each of these frameworks has its own way of externalizing its configuration.
+//
+//
+//[TIP]
+//====
+//Subsequent sections explain how to externalize configuration for xref:userguide:btb:about.adoc#docker[Docker].
+//====
+//
+//
+//
+//== Apache Isis' Config
+//
+//To tell Apache Isis to load configuration from an external directory, specify the `isis.config.dir` context parameter.
+//
+//
+//If the external configuration directory is fixed for all environments (systest, UAT, prod etc), then you can specify within the `web.xml` itself:
+//
+//WARNING: TODO: v2: this has almost certainly changed, because the configuration is picked up earlier; this probably no longer works.
+//
+//[source,xml]
+//----
+//<context-param>
+// <param-name>isis.config.dir</param-name>
+// <param-value>location of external config directory</param-value>
+//</context-param>
+//----
+//
+//If however the configuration directory varies by environment, then the context parameter will be specified to each installation of your servlet container.
+//Most (if not all) servlet containers will provide a means to define context parameters through proprietary config files.
+//
+//
+//
+//[NOTE]
+//====
+//Note that running the app using Apache Isis' `org.apache.isis.WebServer` bootstrapper does not use externalized Apache Isis configuration.
+//====
+//
+//
+//
+//
+//
+//
+//== Shiro Config
+//
+//If using Apache Isis' xref:security:shiro:configuring-isis-to-use-shiro.adoc[Shiro integration] for authentication and/or authorization, note that it reads from the `shiro.ini` configuration file.
+//By default this also resides in `WEB-INF`.
+//
+//Similar to Apache Isis, Shiro lets this configuration directory be altered, by specifying the `shiroConfigLocations` context parameter.
+//
+//You can therefore override the default location using the same technique as described above for Apache Isis' `isis.config.dir` context parameter.
+//For example:
+//
+//[source,xml]
+//----
+//<Parameter name="shiroConfigLocations"
+// value="file:/usr/local/myapp/conf/shiro.ini"
+// override="false" />
+//----
+//
+//[TIP]
+//====
+//Note that Shiro is more flexible than Apache Isis; it will read its configuration from any URL, not just a directory on the local filesystem.
+//====
+//
+//
+//
+//
+//== Log4j Config
+//
+//By default Apache Isis configures log4j to read the `logging.properties` file in the `WEB-INF` directory.
+//This can be overridden by setting the `log4j.properties` system property to the URL of the log4j properties file.
+//
+//[[log4j-config-tomcat]]
+//=== Tomcat
+//
+//For example, if deploying to Tomcat7 or Tomcat8, this amounts to adding the following to the `CATALINA_OPTS` flags:
+//
+//[source,bash]
+//----
+//export CATALINA_OPTS="-Dlog4j.configuration=/usr/local/tomcat/myapp/conf/logging.properties"
+//----
+//
+//[TIP]
+//====
+//`CATALINA_OPTS` was called `TOMCAT_OPTS` in earlier versions of Tomcat.
+//====
+//
+//Further details an be found in the link:https://logging.apache.org/log4j/1.2/manual.html#Example_Configurations[log4j documentation].
+//
+//
+//
+//
+//
+//
+//
+//== JVM Args
+//
+//The xref:refguide:applib-svc:WrapperFactory.adoc[`WrapperFactory`] uses link:http://www.javassist.org[Javassist] to create on-the-fly classes acting as a proxy.
+//The cost of these proxies can be mitigated using:
+//
+//[source,ini]
+//----
+//-XX:+CMSClassUnloadingEnabled -XX:+UseConcMarkSweepGC
+//----
+//
+//
+//
+//== Using a JNDI Datasource
+//
+//See the guidance in the xref:pjdo:ROOT:configuring.adoc#using-jndi-data-source[configuring datanucleus] section.
diff --git a/api/adoc/userguide/modules/btb/pages/deployment/neo4j.adoc b/api/adoc/userguide/modules/btb/pages/deployment/neo4j.adoc
index 26acabc..4f659c5 100644
--- a/api/adoc/userguide/modules/btb/pages/deployment/neo4j.adoc
+++ b/api/adoc/userguide/modules/btb/pages/deployment/neo4j.adoc
@@ -22,7 +22,7 @@ In `persistor.properties`, update the JDO `ConnectionURL` property, eg:
[source,ini]
----
-isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionURL=neo4j:neo4j_DB
+isis.persistence.jdo-datanucleus.impl.javax.jdo.option.ConnectionURL=neo4j:neo4j_DB
----
The other connection properties (`ConnectionDriverName`, `ConnectionUserName` and `ConnectionPassword`) should be commented out.
diff --git a/api/adoc/userguide/modules/btb/pages/i18n.adoc b/api/adoc/userguide/modules/btb/pages/i18n.adoc
index 5840321..d7c0acb 100644
--- a/api/adoc/userguide/modules/btb/pages/i18n.adoc
+++ b/api/adoc/userguide/modules/btb/pages/i18n.adoc
@@ -102,7 +102,7 @@ To make the service as convenient as possible to use, the service configures its
* if running in prototype mode xref:refguide:config:deployment-types.adoc[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:refguide:config:deployment-types.adoc[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).
+It is also possible to set a configuration setting in `application.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.
@@ -609,19 +609,21 @@ Then this directory will be used as the base for searching for translations (rat
=== Force read mode, or disable
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`:
+To force read mode (ie use translations) even if in prototype mode, add the xref:refguide:config:sections/isis.core.runtime-services.adoc#isis.core.runtime-services.translation.po.mode[`isis.core.runtime-services.translation.po.mode`] configuration property:
[source,ini]
+.application.properties
----
-isis.services.translation.po.mode=read
+isis.core.runtime-services.translation.po.mode=read
----
-It's also possible to disable the service completely (using values 'disable' or 'disabled').
+It's also possible to disable the service completely.
This can sometimes be useful in integration tests.
[source,ini]
+.application.properties
----
-isis.services.translation.po.mode=disable
+isis.core.runtime-services.translation.po.mode=disabled
----
== Supporting services
diff --git a/api/adoc/userguide/modules/btb/pages/programming-model/finetuning.adoc b/api/adoc/userguide/modules/btb/pages/programming-model/finetuning.adoc
index 424ee16..dc40738 100644
--- a/api/adoc/userguide/modules/btb/pages/programming-model/finetuning.adoc
+++ b/api/adoc/userguide/modules/btb/pages/programming-model/finetuning.adoc
@@ -4,37 +4,39 @@
: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:
+WARNING: TODO - v2 - not yet reviewed/updated.
The core metamodel defines APIs and implementations for building the Apache Isis metamodel: a description of the set of entities, domain services and values that make up the domain model.
-
The description of each domain class consists of a number of elements:
https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/core/metamodel/spec/ObjectSpecification.java[ObjectSpecification]::
Analogous to `java.lang.Class`; holds information about the class itself and holds collections of each of the three types of class' members (below);
https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/core/metamodel/spec/feature/OneToOneAssociation.java[OneToOneAssociation]::
-Represents a class member that is a single-valued property of the class. The property's type is either a reference to another entity, or is a value type.
+Represents a class member that is a single-valued property of the class.
+The property's type is either a reference to another entity, or is a value type.
https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/core/metamodel/spec/feature/OneToManyAssociation.java[OneToManyAssociation]::
-Represents a class member that is a collection of references to other entities. Note that Apache Isis does not currently support collections of values.
+Represents a class member that is a collection of references to other entities.
+Note that Apache Isis does not currently support collections of values.
https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/core/metamodel/spec/feature/ObjectAction.java[ObjectAction]::
-Represents a class member that is an operation that can be performed on the action. Returns either a single value, a collection of entities, or is `void`.
-
+Represents a class member that is an operation that can be performed on the action.
+Returns either a single value, a collection of entities, or is `void`.
-The metamodel is built up through the https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/core/metamodel/progmodel/ProgrammingModel.java[ProgrammingModel], which defines an API for registering a set of https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/core/metamodel/facets/FacetFactory.java[FacetFactory]s. Two special `FacetFactory` implementations - https://github.com/apache/isis/blob/master/core/metamodel/src/ma [...]
+The metamodel is built up through the https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/core/metamodel/progmodel/ProgrammingModel.java[ProgrammingModel], which defines an API for registering a set of https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/core/metamodel/facets/FacetFactory.java[FacetFactory]s.
+Two special `FacetFactory` implementations - https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/core/metamodel/facets/properties/accessor/PropertyAccessorFacetViaAccessorFactory.java[PropertyAccessorFacetFactory] and https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/core/metamodel/facets/collections/accessor/CollectionAccessorFacetViaAccessorFactory.java[CollectionAccessorFacetFactory] - are used to identify the c [...]
Pretty much all the other ``FacetFactory``s are responsible for installing https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/core/metamodel/facetapi/Facet.java[Facet]s onto the metamodel elements.
-There are many many such ``Facet``s, and are used to do such things get values from properties or collections, modify properties or collections, invoke action, hide or disable class members, provide UI hints for class members, and so on. In short, the ``FacetFactory``s registered defines the Apache Isis programming conventions.
-
-
+There are many many such ``Facet``s, and are used to do such things get values from properties or collections, modify properties or collections, invoke action, hide or disable class members, provide UI hints for class members, and so on.
+In short, the ``FacetFactory``s registered defines the Apache Isis programming conventions.
== Modifying the Prog. Model
The default implementation of `ProgrammingModel` is https://github.com/apache/isis/blob/master/core/metamodel/src/main/java/org/apache/isis/progmodels/dflt/ProgrammingModelFacetsJava5.java[ProgrammingModelFacetsJava5], which registers a large number of ``FacetFactory``s.
-By editing `isis.properties` you can modify the programming conventions either by (a) using the default programming model, but tweaking it to include new `FacetFactory`s or exclude existing, or (b) by specifying a completely different programming model implementation.
+By editing `application.properties` you can modify the programming conventions either by (a) using the default programming model, but tweaking it to include new `FacetFactory`s or exclude existing, or (b) by specifying a completely different programming model implementation.
Let's see how this is done.
@@ -43,6 +45,9 @@ Let's see how this is done.
Suppose that you wanted to completely remove support for some existing facet, eg to support the "persisting()" and "persisted()" callback methods.
This would be done using:
+xref:refguide:config:sections/isis.core.meta-model.introspector.adoc#
+
+
[source,ini]
----
isis.reflector.facets.exclude=\
diff --git a/api/adoc/userguide/modules/btb/pages/web-xml.adoc b/api/adoc/userguide/modules/btb/pages/web-xml.adoc
index 8e9d7f0..fec3125 100644
--- a/api/adoc/userguide/modules/btb/pages/web-xml.adoc
+++ b/api/adoc/userguide/modules/btb/pages/web-xml.adoc
@@ -5,517 +5,518 @@
:page-partial:
-WARNING: TODO: v2: a lot of this has changed, because we now use `WebModule_Xxx` instead of `web.xml`, ie set this stuff up programmatically.
-
-
-Apache Isis provides two different viewers, the xref:vw:ROOT:about.adoc[Wicket viewer] and the xref:vro:ROOT:about.adoc[RestfulObjects viewer].
-You can deploy both of these concurrently, or deploy just the Wicket viewer, or deploy just the Restful Objects viewer.
-The configuration in `web.xml` varies accordingly, both in terms of the servlet context listeners, filters and servlets.
-
-If you are using Apache Isis' integration with Apache Shiro (for security) then this also needs configuring in `web.xml`.
-See the xref:security:shiro:configuring-isis-to-use-shiro.adoc[security guide] for full details on this topic.
-
-The servlets and filters are mapped to three main pipelines:
-
-* `/wicket` - the Wicket viewer UI
-* `/restful` - the Restful Objects resources (REST API)
-* other paths, also static resources (such as `.png`, `.css`)
-
-With the following key:
-
-image::runtime/web-xml/key.png[width="800px",link="{imagesdir}/runtime/web-xml/key.png"]
-
-the diagram below shows the components to be configured if deploying both the Wicket viewer and Restful Objects viewer:
-
-image::runtime/web-xml/wicket-and-ro.png[width="800px",link="{imagesdir}/runtime/web-xml/wicket-and-ro.png"]
-
-Here the Wicket viewer is responsible for the main bootstrapping of Apache Isis itself, in other words the shared (global) metadata; this is done by the `IsisWicketApplication` class (extending the `WicketApplication` Wicket API).
-This class is also responsible for Apache Isis' own session and transaction management.
-
-The Restful Objects viewer - being a JAX-RS application implemented using the RestEasy framework - requires the `RestEasyBootstrapper` servlet context listener.
-It is this context listener that also sets up the `RestfulObjectsApplication`, which is then delegated to by the RestEasy `HttpServletDispatcher`.
-This pipeline uses the `IsisSessionFilter` and `IsisTransactionFilterForRestfulObjects` to perform the session and transaction management before it hits the RestEasy servlet.
-
-If only the Wicket viewer is deployed, then the diagram is more or less the same: the RestEasy servlet, context listener and supporting filters are simply removed:
-
-image::runtime/web-xml/wicket-only.png[width="800px",link="{imagesdir}/runtime/web-xml/wicket-only.png"]
-
-Finally, if only the Restful Objects viewer is deployed, then things change a little more subtly. Here, the Wicket filter is no longer needed.
-In its place, though the `IsisWebAppBootstrapper` context listener is required: this is responsible for seting up the shared (global) metadata.
-
-image::runtime/web-xml/ro-only.png[width="800px",link="{imagesdir}/runtime/web-xml/ro-only.png"]
-
-The following sections detail these various listeners, filters and servlets in more detail.
-
-
-
-== Servlet Context Listeners
-
-Servlet context listeners are used to perform initialization on application startup.
-Both Shiro (if configured as the security mechanism) and RestEasy (for the Restful Objects viewer) require their own context listener.
-In addition, if the Wicket viewer is _not_ being used, then additional Apache Isis-specific listener is required for bootstrapping of the Apache Isis framework itself.
-
-
-=== `EnvironmentLoaderListener` (Shiro)
-
-Bootstrap listener to startup and shutdown the web application's Shiro `WebEnvironment` at startup and shutdown respectively.
-
-Its definition is:
-
-[source,xml]
-----
-<listener>
- <listener-class>org.apache.shiro.web.env.EnvironmentLoaderListener</listener-class>
-</listener>
-----
-
-
-
-=== `IsisWebAppBootstrapper`
-
-The `IsisWebAppBootstrapper` servlet context listener bootstraps the shared (global) metadata for the Apache Isis framework.
-This listener is not required (indeed must not be configured) if the Wicket viewer is in use.
-
-Its definition is:
-
-[source,xml]
-----
-<listener>
- <listener-class>org.apache.isis.core.webapp.IsisWebAppBootstrapper</listener-class>
-</listener>
-----
-
-Its context parameters are:
-
-[source,xml]
-----
-<context-param>
- <param-name>deploymentType</param-name>
- <param-value>SERVER_PROTOTYPE</param-value>
-</context-param>
-<context-param>
- <param-name>isis.viewers</param-name>
- <param-value>restfulobjects</param-value>
-</context-param>
-----
-
-
-=== `ResteasyBootstrap` (RestEasy)
-
-The `ResteasyBootstrap` servlet context listener initializes the RestEasy runtime, specifying that classes (namely, those specified in Isis' `RestfulObjectsApplication`) to be exposed as REST resources.
-It is required if the Restful Objects viewer is to be deployed.
-
-Its definition is:
-
-[source,xml]
-----
-<listener>
- <listener-class>org.jboss.resteasy.plugins.server.servlet.ResteasyBootstrap</listener-class>
-</listener>
-----
-
-There are two relevant context parameters:
-
-[source,xml]
-----
-<context-param>
- <param-name>javax.ws.rs.Application</param-name> <!--1-->
- <param-value>org.apache.isis.viewer.restfulobjects.server.RestfulObjectsApplication</param-value>
-</context-param>
-<context-param>
- <param-name>resteasy.servlet.mapping.prefix</param-name>
- <param-value>/restful/</param-value> <!--2-->
-</context-param>
-----
-<1> used by RestEasy to determine the JAX-RS resources and other related configuration
-<2> should correspond to the filter mapping of the `HttpServletDispatcher` servlet
-
-
-
-== Servlets
-
-Servlets process HTTP requests and return corresponding responses.
-
-
-=== `HttpServletDispatcher` (RestEasy)
-
-This servlet is provided by the RestEasy framework, and does the dispatching to the resources defined by Apache Isis' `RestfulObjectsApplication` (see above).
-
-Its definition is:
-
-[source,xml]
-----
-<servlet>
- <servlet-name>RestfulObjectsRestEasyDispatcher</servlet-name>
- <servlet-class>org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher</servlet-class>
-</servlet>
-----
-
-Its mapping is:
-
-[source,xml]
-----
-<servlet-mapping>
- <servlet-name>RestfulObjectsRestEasyDispatcher</servlet-name>
- <url-pattern>/restful/*</url-pattern>
-</servlet-mapping>
-----
-
-
-=== `ResourceServlet`
-
-The `ResourceServlet` loads and services static content either from the filesystem or from the classpath, each with an appropriate mime type.
-
-Static content here means request paths ending in `.js`, `.css`, `.html`, `.png`, `.jpg`, `.jpeg` and `gif`.
-
-
-Its definition is:
-
-[source,xml]
-----
-<servlet>
- <servlet-name>Resource</servlet-name>
- <servlet-class>org.apache.isis.core.webapp.content.ResourceServlet</servlet-class>
-</servlet>
-----
-
-Its mapping is:
-
-[source,xml]
-----
-<servlet-mapping>
- <servlet-name>Resource</servlet-name>
- <url-pattern>*.css</url-pattern>
-</servlet-mapping>
-<servlet-mapping>
- <servlet-name>Resource</servlet-name>
- <url-pattern>*.png</url-pattern>
-</servlet-mapping>
-<servlet-mapping>
- <servlet-name>Resource</servlet-name>
- <url-pattern>*.jpg</url-pattern>
-</servlet-mapping>
-<servlet-mapping>
- <servlet-name>Resource</servlet-name>
- <url-pattern>*.jpeg</url-pattern>
-</servlet-mapping>
-<servlet-mapping>
- <servlet-name>Resource</servlet-name>
- <url-pattern>*.gif</url-pattern>
-</servlet-mapping>
-<servlet-mapping>
- <servlet-name>Resource</servlet-name>
- <url-pattern>*.svg</url-pattern>
-</servlet-mapping>
-<servlet-mapping>
- <servlet-name>Resource</servlet-name>
- <url-pattern>*.js</url-pattern>
-</servlet-mapping>
-<servlet-mapping>
- <servlet-name>Resource</servlet-name>
- <url-pattern>*.html</url-pattern>
-</servlet-mapping>
-<servlet-mapping>
- <servlet-name>Resource</servlet-name>
- <url-pattern>*.swf</url-pattern>
-</servlet-mapping>
-----
-
-
-
-
-== Filters
-
-The order in which filters appear in `web.xml` matters: first to last they define a pipeline.
-This is shown in the above diagrams, and the subsections also list the in the same order that they should appear in your `web.xml`.
-
-
-=== `ShiroFilter` (Shiro)
-
-Shiro filter that sets up a Shiro security manager for the request, obtained from the Shiro `WebEnvironment` set up by the Shiro `EnvironmentLoaderListener` (discussed above).
-
-Its definition is:
-
-[source,xml]
-----
-<filter>
- <filter-name>ShiroFilter</filter-name>
- <filter-class>org.apache.shiro.web.servlet.ShiroFilter</filter-class>
-</filter>
-----
-
-Its mapping is:
-
-[source,xml]
-----
-<filter-mapping>
- <filter-name>ShiroFilter</filter-name>
- <url-pattern>/*</url-pattern>
-</filter-mapping>
-----
-
-
-=== `IsisLogOnExceptionFilter`
-
-The `IsisLogOnExceptionFilter` filter simply logs the URL of any request that causes an exception to be thrown, then re-propagates the exception.
-The use case is simply to ensure that all exceptions are logged (against the `IsisLogOnExceptionFilter` slf4j appender).
-
-Its definition is:
-
-[source,xml]
-----
-<filter>
- <filter-name>IsisLogOnExceptionFilter</filter-name>
- <filter-class>org.apache.isis.core.webapp.diagnostics.IsisLogOnExceptionFilter</filter-class>
-</filter>
-----
-
-
-Its mapping is:
-
-[source,xml]
-----
-<filter-mapping>
- <filter-name>IsisLogOnExceptionFilter</filter-name>
- <url-pattern>/wicket/*</url-pattern>
-</filter-mapping>
-<filter-mapping>
- <filter-name>IsisLogOnExceptionFilter</filter-name>
- <url-pattern>/restful/*</url-pattern>
-</filter-mapping>
-----
-
-
-
-=== `ResourceCachingFilter`
-
-The `ResourceCachingFilter` adds HTTP cache headers to specified resources, based on their pattern.
-
-Its definition is:
-
-[source,xml]
-----
-<filter>
- <filter-name>ResourceCachingFilter</filter-name>
- <filter-class>org.apache.isis.core.webapp.content.ResourceCachingFilter</filter-class>
- <init-param>
- <param-name>CacheTime</param-name> <!--1-->
- <param-value>86400</param-value>
- </init-param>
-</filter>
-----
-<1> cache time, in seconds
-
-Its mapping is:
-
-[source,xml]
-----
-<filter-mapping>
- <filter-name>ResourceCachingFilter</filter-name>
- <url-pattern>*.css</url-pattern>
-</filter-mapping>
-<filter-mapping>
- <filter-name>ResourceCachingFilter</filter-name>
- <url-pattern>*.png</url-pattern>
-</filter-mapping>
-<filter-mapping>
- <filter-name>ResourceCachingFilter</filter-name>
- <url-pattern>*.jpg</url-pattern>
-</filter-mapping>
-<filter-mapping>
- <filter-name>ResourceCachingFilter</filter-name>
- <url-pattern>*.jpeg</url-pattern>
-</filter-mapping>
-<filter-mapping>
- <filter-name>ResourceCachingFilter</filter-name>
- <url-pattern>*.gif</url-pattern>
-</filter-mapping>
-<filter-mapping>
- <filter-name>ResourceCachingFilter</filter-name>
- <url-pattern>*.svg</url-pattern>
-</filter-mapping>
-<filter-mapping>
- <filter-name>ResourceCachingFilter</filter-name>
- <url-pattern>*.html</url-pattern>
-</filter-mapping>
-<filter-mapping>
- <filter-name>ResourceCachingFilter</filter-name>
- <url-pattern>*.js</url-pattern>
-</filter-mapping>
-<filter-mapping>
- <filter-name>ResourceCachingFilter</filter-name>
- <url-pattern>*.swf</url-pattern>
-</filter-mapping>
-----
-
-
-=== `WicketFilter`
-
-The `WicketFilter` is responsible for initiating the handling of Wicket requests.
-
-Its definition is:
-
-[source,xml]
-----
-<filter>
- <filter-name>WicketFilter</filter-name>
- <filter-class>org.apache.wicket.protocol.http.WicketFilter</filter-class>
- <init-param>
- <param-name>applicationClassName</param-name>
- <param-value>org.apache.isis.viewer.wicket.viewer.IsisWicketApplication</param-value>
- </init-param>
-</filter>
-----
-
-This is generally boilerplate.
-It is possible to specify a subclass of `IsisWicketApplication` (and in earlier versions of the framework this was generally required), but there now exist sufficient configuration properties that subclassing is generally not required.
-
-Its mapping is:
-
-[source,xml]
-----
-<filter-mapping>
- <filter-name>WicketFilter</filter-name>
- <url-pattern>/wicket/*</url-pattern>
-</filter-mapping>
-----
-
-This filter reads one context parameter:
-[source,xml]
-----
-<context-param>
- <param-name>configuration</param-name>
- <param-value>deployment</param-value> <!--1-->
-</context-param>
-----
-<1> alternatively set to "development"; see xref:refguide:config:deployment-types.adoc[deployment types] for further discussion.
-
-
-=== `IsisSessionFilter`
-
-The `IsisSessionFilter` is responsible for the (persistence) session management; in effect a wrapper around DataNucleus' `PersistenceManager` object.
-It is only required for the Restful Objects viewer.
-
-[source,xml]
-----
-<filter>
- <filter-name>IsisSessionFilterForRestfulObjects</filter-name>
- <filter-class>org.apache.isis.core.webapp.IsisSessionFilter</filter-class>
- <init-param>
- <param-name>authenticationSessionStrategy</param-name> <!--1-->
- <param-value>
- org.apache.isis.viewer.restfulobjects.server.authentication.AuthenticationSessionStrategyBasicAuth
- </param-value>
- </init-param>
- <init-param>
- <param-name>whenNoSession</param-name> <!--2-->
- <param-value>basicAuthChallenge</param-value>
- </init-param>
- <init-param>
- <param-name>passThru</param-name> <!--3-->
- <param-value>/restful/swagger,/restful/health</param-value>
- </init-param>
- <!--
- <init-param>
- <param-name>restricted</param-name> <!--4-->
- <param-value>...</param-value>
- </init-param>
- <init-param>
- <param-name>redirectToOnException</param-name> <!--5-->
- <param-value>...</param-value>
- </init-param>
- -->
-</filter>
-----
-<1> pluggable strategy for determining what the authentication session (credentials) are of the request
-<2> what the servlet should do if no existing session was found.
-Usual values are either `unauthorized`, `basicAuthChallenge` or `auto`.
-Discussed in more detail below.
-<3> specify which URIs to ignore and simply pass through.
-Originally introduced to allow the `SwaggerSpec` resource (which does not require a session) to be invoked.
-<4> A comma separated list of paths that are allowed through even if not authenticated.
-The servlets mapped to these paths are expected to be able to deal with there being no session.
-Typically they will be logon pages, or for health checks (as per xref:refguide:applib-svc:HealthCheckService.adoc[`HealthCheckService`] SPI.
-See below for further details.
-<5> where to redirect to if an exception occurs.
-
-
-The `whenNoSession` parameter determines what the behaviour should be if no existing session can be found.
-There are a number of predetermined values available:
-
-* `unauthorized` will generates a 401 response
-* `basicAuthChallenge` will also generate a 401 response, and also issues a Basic Auth challenge using `WWW-Authenticate` response header
-* `auto` combines the `unauthorized` and `basicAuthChallenge` strategies: it will generate a 401 response, but only issues a Basic Auth challenge if it detects that the request originates from a web browser (ie that the HTTP `Accept` header is set to `text/html`).
-This means that custom Javascript apps can perform their authentication correctly, while the REST API can still be explored using the web browser (relying upon the web browser's in-built support for HTTP Basic Auth).
-* `continue`, in which case the request is allowed to continue but the destination expected to know that there will be no open session
-* `restricted`, which allows access to a restricted list of URLs, otherwise will redirect to the first of that list of URLs
-
-If accessing the REST API through a web browser, then normally `basicAuthChallenge` is appropriate; the browser will automatically display a simple prompt.
-If accessing the REST API through a custom Javascript app, then `unauthorized` is usually the one to use.
-
-This filter should be mapped to the `servlet-name` for the RestEasy `HttpServletDispatcher`; for example:
-
-[source,xml]
-----
-<filter-mapping>
- <filter-name>IsisSessionFilterForRestfulObjects</filter-name>
- <servlet-name>RestfulObjectsRestEasyDispatcher</servlet-name>
-</filter-mapping>
-----
-
-
-
-
-=== `IsisTransactionFilterForRestfulObjects`
-
-The `IsisTransactionFilterForRestfulObjects` filter simply ensures that a transaction is in progress for all calls routed to the xref:vro:ROOT:about.adoc[RestfulObjects viewer].
-
-Its definition is:
-
-[source,xml]
-----
-<filter>
- <filter-name>IsisTransactionFilterForRestfulObjects</filter-name>
- <filter-class>org.apache.isis.viewer.restfulobjects.server.webapp.IsisTransactionFilterForRestfulObjects</filter-class>
-</filter>
-----
-
-This filter should be mapped to the `servlet-name` for the RestEasy `HttpServletDispatcher`; for example:
-
-[source,xml]
-----
-<filter-mapping>
- <filter-name>IsisTransactionFilterForRestfulObjects</filter-name>
- <servlet-name>RestfulObjectsRestEasyDispatcher</servlet-name>
-</filter-mapping>
-----
-
-
-
-== Configuration Files
-
-However Apache Isis is bootstrapped (using the `IsisWicketApplication` or using `IsisWebAppBootstrapper`), it will read a number of configuration files, such as `isis.properties`.
-
-By default these are read from `WEB-INF` directory.
-This can be overridden using the `isis.config.dir` context parameter:
-
-[source,xml]
-----
-<context-param>
- <param-name>isis.config.dir</param-name>
- <param-value>location of your config directory if fixed</param-value>
-</context-param>
-----
-
-Another context parameter, `isis.viewres` specifies which additional configuration files to search for (over and above the default ones of `isis.properties` et al):
-
-[source,xml]
-----
-<context-param>
- <param-name>isis.viewers</param-name>
- <param-value>wicket,restfulobjects</param-value>
-</context-param>
-----
-
-For example, this will cause `viewer_wicket.properties` and `viewer_restfulobjects.properties` to also be loaded.
-
+WARNING: TODO: v2: to be reviewed/updated.
+A lot of this has changed, because we now use `WebModule_Xxx` instead of `web.xml`, ie set this stuff up programmatically.
+
+
+//Apache Isis provides two different viewers, the xref:vw:ROOT:about.adoc[Wicket viewer] and the xref:vro:ROOT:about.adoc[RestfulObjects viewer].
+//You can deploy both of these concurrently, or deploy just the Wicket viewer, or deploy just the Restful Objects viewer.
+//The configuration in `web.xml` varies accordingly, both in terms of the servlet context listeners, filters and servlets.
+//
+//If you are using Apache Isis' integration with Apache Shiro (for security) then this also needs configuring in `web.xml`.
+//See the xref:security:shiro:configuring-isis-to-use-shiro.adoc[security guide] for full details on this topic.
+//
+//The servlets and filters are mapped to three main pipelines:
+//
+//* `/wicket` - the Wicket viewer UI
+//* `/restful` - the Restful Objects resources (REST API)
+//* other paths, also static resources (such as `.png`, `.css`)
+//
+//With the following key:
+//
+//image::runtime/web-xml/key.png[width="800px",link="{imagesdir}/runtime/web-xml/key.png"]
+//
+//the diagram below shows the components to be configured if deploying both the Wicket viewer and Restful Objects viewer:
+//
+//image::runtime/web-xml/wicket-and-ro.png[width="800px",link="{imagesdir}/runtime/web-xml/wicket-and-ro.png"]
+//
+//Here the Wicket viewer is responsible for the main bootstrapping of Apache Isis itself, in other words the shared (global) metadata; this is done by the `IsisWicketApplication` class (extending the `WicketApplication` Wicket API).
+//This class is also responsible for Apache Isis' own session and transaction management.
+//
+//The Restful Objects viewer - being a JAX-RS application implemented using the RestEasy framework - requires the `RestEasyBootstrapper` servlet context listener.
+//It is this context listener that also sets up the `RestfulObjectsApplication`, which is then delegated to by the RestEasy `HttpServletDispatcher`.
+//This pipeline uses the `IsisSessionFilter` and `IsisTransactionFilterForRestfulObjects` to perform the session and transaction management before it hits the RestEasy servlet.
+//
+//If only the Wicket viewer is deployed, then the diagram is more or less the same: the RestEasy servlet, context listener and supporting filters are simply removed:
+//
+//image::runtime/web-xml/wicket-only.png[width="800px",link="{imagesdir}/runtime/web-xml/wicket-only.png"]
+//
+//Finally, if only the Restful Objects viewer is deployed, then things change a little more subtly. Here, the Wicket filter is no longer needed.
+//In its place, though the `IsisWebAppBootstrapper` context listener is required: this is responsible for seting up the shared (global) metadata.
+//
+//image::runtime/web-xml/ro-only.png[width="800px",link="{imagesdir}/runtime/web-xml/ro-only.png"]
+//
+//The following sections detail these various listeners, filters and servlets in more detail.
+//
+//
+//
+//== Servlet Context Listeners
+//
+//Servlet context listeners are used to perform initialization on application startup.
+//Both Shiro (if configured as the security mechanism) and RestEasy (for the Restful Objects viewer) require their own context listener.
+//In addition, if the Wicket viewer is _not_ being used, then additional Apache Isis-specific listener is required for bootstrapping of the Apache Isis framework itself.
+//
+//
+//=== `EnvironmentLoaderListener` (Shiro)
+//
+//Bootstrap listener to startup and shutdown the web application's Shiro `WebEnvironment` at startup and shutdown respectively.
+//
+//Its definition is:
+//
+//[source,xml]
+//----
+//<listener>
+// <listener-class>org.apache.shiro.web.env.EnvironmentLoaderListener</listener-class>
+//</listener>
+//----
+//
+//
+//
+//=== `IsisWebAppBootstrapper`
+//
+//The `IsisWebAppBootstrapper` servlet context listener bootstraps the shared (global) metadata for the Apache Isis framework.
+//This listener is not required (indeed must not be configured) if the Wicket viewer is in use.
+//
+//Its definition is:
+//
+//[source,xml]
+//----
+//<listener>
+// <listener-class>org.apache.isis.core.webapp.IsisWebAppBootstrapper</listener-class>
+//</listener>
+//----
+//
+//Its context parameters are:
+//
+//[source,xml]
+//----
+//<context-param>
+// <param-name>deploymentType</param-name>
+// <param-value>SERVER_PROTOTYPE</param-value>
+//</context-param>
+//<context-param>
+// <param-name>isis.viewers</param-name>
+// <param-value>restfulobjects</param-value>
+//</context-param>
+//----
+//
+//
+//=== `ResteasyBootstrap` (RestEasy)
+//
+//The `ResteasyBootstrap` servlet context listener initializes the RestEasy runtime, specifying that classes (namely, those specified in Isis' `RestfulObjectsApplication`) to be exposed as REST resources.
+//It is required if the Restful Objects viewer is to be deployed.
+//
+//Its definition is:
+//
+//[source,xml]
+//----
+//<listener>
+// <listener-class>org.jboss.resteasy.plugins.server.servlet.ResteasyBootstrap</listener-class>
+//</listener>
+//----
+//
+//There are two relevant context parameters:
+//
+//[source,xml]
+//----
+//<context-param>
+// <param-name>javax.ws.rs.Application</param-name> <!--1-->
+// <param-value>org.apache.isis.viewer.restfulobjects.server.RestfulObjectsApplication</param-value>
+//</context-param>
+//<context-param>
+// <param-name>resteasy.servlet.mapping.prefix</param-name>
+// <param-value>/restful/</param-value> <!--2-->
+//</context-param>
+//----
+//<1> used by RestEasy to determine the JAX-RS resources and other related configuration
+//<2> should correspond to the filter mapping of the `HttpServletDispatcher` servlet
+//
+//
+//
+//== Servlets
+//
+//Servlets process HTTP requests and return corresponding responses.
+//
+//
+//=== `HttpServletDispatcher` (RestEasy)
+//
+//This servlet is provided by the RestEasy framework, and does the dispatching to the resources defined by Apache Isis' `RestfulObjectsApplication` (see above).
+//
+//Its definition is:
+//
+//[source,xml]
+//----
+//<servlet>
+// <servlet-name>RestfulObjectsRestEasyDispatcher</servlet-name>
+// <servlet-class>org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher</servlet-class>
+//</servlet>
+//----
+//
+//Its mapping is:
+//
+//[source,xml]
+//----
+//<servlet-mapping>
+// <servlet-name>RestfulObjectsRestEasyDispatcher</servlet-name>
+// <url-pattern>/restful/*</url-pattern>
+//</servlet-mapping>
+//----
+//
+//
+//=== `ResourceServlet`
+//
+//The `ResourceServlet` loads and services static content either from the filesystem or from the classpath, each with an appropriate mime type.
+//
+//Static content here means request paths ending in `.js`, `.css`, `.html`, `.png`, `.jpg`, `.jpeg` and `gif`.
+//
+//
+//Its definition is:
+//
+//[source,xml]
+//----
+//<servlet>
+// <servlet-name>Resource</servlet-name>
+// <servlet-class>org.apache.isis.core.webapp.content.ResourceServlet</servlet-class>
+//</servlet>
+//----
+//
+//Its mapping is:
+//
+//[source,xml]
+//----
+//<servlet-mapping>
+// <servlet-name>Resource</servlet-name>
+// <url-pattern>*.css</url-pattern>
+//</servlet-mapping>
+//<servlet-mapping>
+// <servlet-name>Resource</servlet-name>
+// <url-pattern>*.png</url-pattern>
+//</servlet-mapping>
+//<servlet-mapping>
+// <servlet-name>Resource</servlet-name>
+// <url-pattern>*.jpg</url-pattern>
+//</servlet-mapping>
+//<servlet-mapping>
+// <servlet-name>Resource</servlet-name>
+// <url-pattern>*.jpeg</url-pattern>
+//</servlet-mapping>
+//<servlet-mapping>
+// <servlet-name>Resource</servlet-name>
+// <url-pattern>*.gif</url-pattern>
+//</servlet-mapping>
+//<servlet-mapping>
+// <servlet-name>Resource</servlet-name>
+// <url-pattern>*.svg</url-pattern>
+//</servlet-mapping>
+//<servlet-mapping>
+// <servlet-name>Resource</servlet-name>
+// <url-pattern>*.js</url-pattern>
+//</servlet-mapping>
+//<servlet-mapping>
+// <servlet-name>Resource</servlet-name>
+// <url-pattern>*.html</url-pattern>
+//</servlet-mapping>
+//<servlet-mapping>
+// <servlet-name>Resource</servlet-name>
+// <url-pattern>*.swf</url-pattern>
+//</servlet-mapping>
+//----
+//
+//
+//
+//
+//== Filters
+//
+//The order in which filters appear in `web.xml` matters: first to last they define a pipeline.
+//This is shown in the above diagrams, and the subsections also list the in the same order that they should appear in your `web.xml`.
+//
+//
+//=== `ShiroFilter` (Shiro)
+//
+//Shiro filter that sets up a Shiro security manager for the request, obtained from the Shiro `WebEnvironment` set up by the Shiro `EnvironmentLoaderListener` (discussed above).
+//
+//Its definition is:
+//
+//[source,xml]
+//----
+//<filter>
+// <filter-name>ShiroFilter</filter-name>
+// <filter-class>org.apache.shiro.web.servlet.ShiroFilter</filter-class>
+//</filter>
+//----
+//
+//Its mapping is:
+//
+//[source,xml]
+//----
+//<filter-mapping>
+// <filter-name>ShiroFilter</filter-name>
+// <url-pattern>/*</url-pattern>
+//</filter-mapping>
+//----
+//
+//
+//=== `IsisLogOnExceptionFilter`
+//
+//The `IsisLogOnExceptionFilter` filter simply logs the URL of any request that causes an exception to be thrown, then re-propagates the exception.
+//The use case is simply to ensure that all exceptions are logged (against the `IsisLogOnExceptionFilter` slf4j appender).
+//
+//Its definition is:
+//
+//[source,xml]
+//----
+//<filter>
+// <filter-name>IsisLogOnExceptionFilter</filter-name>
+// <filter-class>org.apache.isis.core.webapp.diagnostics.IsisLogOnExceptionFilter</filter-class>
+//</filter>
+//----
+//
+//
+//Its mapping is:
+//
+//[source,xml]
+//----
+//<filter-mapping>
+// <filter-name>IsisLogOnExceptionFilter</filter-name>
+// <url-pattern>/wicket/*</url-pattern>
+//</filter-mapping>
+//<filter-mapping>
+// <filter-name>IsisLogOnExceptionFilter</filter-name>
+// <url-pattern>/restful/*</url-pattern>
+//</filter-mapping>
+//----
+//
+//
+//
+//=== `ResourceCachingFilter`
+//
+//The `ResourceCachingFilter` adds HTTP cache headers to specified resources, based on their pattern.
+//
+//Its definition is:
+//
+//[source,xml]
+//----
+//<filter>
+// <filter-name>ResourceCachingFilter</filter-name>
+// <filter-class>org.apache.isis.core.webapp.content.ResourceCachingFilter</filter-class>
+// <init-param>
+// <param-name>CacheTime</param-name> <!--1-->
+// <param-value>86400</param-value>
+// </init-param>
+//</filter>
+//----
+//<1> cache time, in seconds
+//
+//Its mapping is:
+//
+//[source,xml]
+//----
+//<filter-mapping>
+// <filter-name>ResourceCachingFilter</filter-name>
+// <url-pattern>*.css</url-pattern>
+//</filter-mapping>
+//<filter-mapping>
+// <filter-name>ResourceCachingFilter</filter-name>
+// <url-pattern>*.png</url-pattern>
+//</filter-mapping>
+//<filter-mapping>
+// <filter-name>ResourceCachingFilter</filter-name>
+// <url-pattern>*.jpg</url-pattern>
+//</filter-mapping>
+//<filter-mapping>
+// <filter-name>ResourceCachingFilter</filter-name>
+// <url-pattern>*.jpeg</url-pattern>
+//</filter-mapping>
+//<filter-mapping>
+// <filter-name>ResourceCachingFilter</filter-name>
+// <url-pattern>*.gif</url-pattern>
+//</filter-mapping>
+//<filter-mapping>
+// <filter-name>ResourceCachingFilter</filter-name>
+// <url-pattern>*.svg</url-pattern>
+//</filter-mapping>
+//<filter-mapping>
+// <filter-name>ResourceCachingFilter</filter-name>
+// <url-pattern>*.html</url-pattern>
+//</filter-mapping>
+//<filter-mapping>
+// <filter-name>ResourceCachingFilter</filter-name>
+// <url-pattern>*.js</url-pattern>
+//</filter-mapping>
+//<filter-mapping>
+// <filter-name>ResourceCachingFilter</filter-name>
+// <url-pattern>*.swf</url-pattern>
+//</filter-mapping>
+//----
+//
+//
+//=== `WicketFilter`
+//
+//The `WicketFilter` is responsible for initiating the handling of Wicket requests.
+//
+//Its definition is:
+//
+//[source,xml]
+//----
+//<filter>
+// <filter-name>WicketFilter</filter-name>
+// <filter-class>org.apache.wicket.protocol.http.WicketFilter</filter-class>
+// <init-param>
+// <param-name>applicationClassName</param-name>
+// <param-value>org.apache.isis.viewer.wicket.viewer.IsisWicketApplication</param-value>
+// </init-param>
+//</filter>
+//----
+//
+//This is generally boilerplate.
+//It is possible to specify a subclass of `IsisWicketApplication` (and in earlier versions of the framework this was generally required), but there now exist sufficient configuration properties that subclassing is generally not required.
+//
+//Its mapping is:
+//
+//[source,xml]
+//----
+//<filter-mapping>
+// <filter-name>WicketFilter</filter-name>
+// <url-pattern>/wicket/*</url-pattern>
+//</filter-mapping>
+//----
+//
+//This filter reads one context parameter:
+//[source,xml]
+//----
+//<context-param>
+// <param-name>configuration</param-name>
+// <param-value>deployment</param-value> <!--1-->
+//</context-param>
+//----
+//<1> alternatively set to "development"; see xref:refguide:config:deployment-types.adoc[deployment types] for further discussion.
+//
+//
+//=== `IsisSessionFilter`
+//
+//The `IsisSessionFilter` is responsible for the (persistence) session management; in effect a wrapper around DataNucleus' `PersistenceManager` object.
+//It is only required for the Restful Objects viewer.
+//
+//[source,xml]
+//----
+//<filter>
+// <filter-name>IsisSessionFilterForRestfulObjects</filter-name>
+// <filter-class>org.apache.isis.core.webapp.IsisSessionFilter</filter-class>
+// <init-param>
+// <param-name>authenticationSessionStrategy</param-name> <!--1-->
+// <param-value>
+// org.apache.isis.viewer.restfulobjects.server.authentication.AuthenticationSessionStrategyBasicAuth
+// </param-value>
+// </init-param>
+// <init-param>
+// <param-name>whenNoSession</param-name> <!--2-->
+// <param-value>basicAuthChallenge</param-value>
+// </init-param>
+// <init-param>
+// <param-name>passThru</param-name> <!--3-->
+// <param-value>/restful/swagger,/restful/health</param-value>
+// </init-param>
+// <!--
+// <init-param>
+// <param-name>restricted</param-name> <!--4-->
+// <param-value>...</param-value>
+// </init-param>
+// <init-param>
+// <param-name>redirectToOnException</param-name> <!--5-->
+// <param-value>...</param-value>
+// </init-param>
+// -->
+//</filter>
+//----
+//<1> pluggable strategy for determining what the authentication session (credentials) are of the request
+//<2> what the servlet should do if no existing session was found.
+//Usual values are either `unauthorized`, `basicAuthChallenge` or `auto`.
+//Discussed in more detail below.
+//<3> specify which URIs to ignore and simply pass through.
+//Originally introduced to allow the `SwaggerSpec` resource (which does not require a session) to be invoked.
+//<4> A comma separated list of paths that are allowed through even if not authenticated.
+//The servlets mapped to these paths are expected to be able to deal with there being no session.
+//Typically they will be logon pages, or for health checks (as per xref:refguide:applib-svc:HealthCheckService.adoc[`HealthCheckService`] SPI.
+//See below for further details.
+//<5> where to redirect to if an exception occurs.
+//
+//
+//The `whenNoSession` parameter determines what the behaviour should be if no existing session can be found.
+//There are a number of predetermined values available:
+//
+//* `unauthorized` will generates a 401 response
+//* `basicAuthChallenge` will also generate a 401 response, and also issues a Basic Auth challenge using `WWW-Authenticate` response header
+//* `auto` combines the `unauthorized` and `basicAuthChallenge` strategies: it will generate a 401 response, but only issues a Basic Auth challenge if it detects that the request originates from a web browser (ie that the HTTP `Accept` header is set to `text/html`).
+//This means that custom Javascript apps can perform their authentication correctly, while the REST API can still be explored using the web browser (relying upon the web browser's in-built support for HTTP Basic Auth).
+//* `continue`, in which case the request is allowed to continue but the destination expected to know that there will be no open session
+//* `restricted`, which allows access to a restricted list of URLs, otherwise will redirect to the first of that list of URLs
+//
+//If accessing the REST API through a web browser, then normally `basicAuthChallenge` is appropriate; the browser will automatically display a simple prompt.
+//If accessing the REST API through a custom Javascript app, then `unauthorized` is usually the one to use.
+//
+//This filter should be mapped to the `servlet-name` for the RestEasy `HttpServletDispatcher`; for example:
+//
+//[source,xml]
+//----
+//<filter-mapping>
+// <filter-name>IsisSessionFilterForRestfulObjects</filter-name>
+// <servlet-name>RestfulObjectsRestEasyDispatcher</servlet-name>
+//</filter-mapping>
+//----
+//
+//
+//
+//
+//=== `IsisTransactionFilterForRestfulObjects`
+//
+//The `IsisTransactionFilterForRestfulObjects` filter simply ensures that a transaction is in progress for all calls routed to the xref:vro:ROOT:about.adoc[RestfulObjects viewer].
+//
+//Its definition is:
+//
+//[source,xml]
+//----
+//<filter>
+// <filter-name>IsisTransactionFilterForRestfulObjects</filter-name>
+// <filter-class>org.apache.isis.viewer.restfulobjects.server.webapp.IsisTransactionFilterForRestfulObjects</filter-class>
+//</filter>
+//----
+//
+//This filter should be mapped to the `servlet-name` for the RestEasy `HttpServletDispatcher`; for example:
+//
+//[source,xml]
+//----
+//<filter-mapping>
+// <filter-name>IsisTransactionFilterForRestfulObjects</filter-name>
+// <servlet-name>RestfulObjectsRestEasyDispatcher</servlet-name>
+//</filter-mapping>
+//----
+//
+//
+//
+//== Configuration Files
+//
+//However Apache Isis is bootstrapped (using the `IsisWicketApplication` or using `IsisWebAppBootstrapper`), it will read a number of configuration files, such as `isis.properties`.
+//
+//By default these are read from `WEB-INF` directory.
+//This can be overridden using the `isis.config.dir` context parameter:
+//
+//[source,xml]
+//----
+//<context-param>
+// <param-name>isis.config.dir</param-name>
+// <param-value>location of your config directory if fixed</param-value>
+//</context-param>
+//----
+//
+//Another context parameter, `isis.viewres` specifies which additional configuration files to search for (over and above the default ones of `isis.properties` et al):
+//
+//[source,xml]
+//----
+//<context-param>
+// <param-name>isis.viewers</param-name>
+// <param-value>wicket,restfulobjects</param-value>
+//</context-param>
+//----
+//
+//For example, this will cause `viewer_wicket.properties` and `viewer_restfulobjects.properties` to also be loaded.
+//
diff --git a/api/adoc/userguide/modules/fun/pages/domain-entities-and-services/crud.adoc b/api/adoc/userguide/modules/fun/pages/domain-entities-and-services/crud.adoc
index b70d7f1..758e963 100644
--- a/api/adoc/userguide/modules/fun/pages/domain-entities-and-services/crud.adoc
+++ b/api/adoc/userguide/modules/fun/pages/domain-entities-and-services/crud.adoc
@@ -120,8 +120,8 @@ This avoid the need to explicitly call "persist".
If using xref:pjdo:ROOT:about.adoc[JDO/DataNucleus], this is done using xref:refguide:config:sections/isis.persistence.jdo-datanucleus.impl.adoc#isis.persistence.jdo-datanucleus.impl.datanucleus.persistenceByReachabilityAtCommit[persistence-by-reachability] configuration property:
-.isis.properties
[source,ini]
+.application.properties
----
isis.persistence.jdo-datanucleus.impl.datanucleus.persistenceByReachabilityAtCommit=true
----
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Action/publishing.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Action/publishing.adoc
index 6171e14..aca76b2 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Action/publishing.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Action/publishing.adoc
@@ -9,21 +9,21 @@
The `publishing` attribute determines whether and how an action invocation is published via the registered implementation of xref:refguide:applib-svc:PublisherService.adoc[`PublisherService`].
A common use case is to notify external "downstream" systems of changes in the state of the Apache Isis application.
-The default value for the attribute is `AS_CONFIGURED`, meaning that the xref:refguide:config:configuring-core.adoc[configuration property] `isis.services.publish.actions` is used to determine the whether the action is published:
+The xref:refguide:config:sections/isis.applib.adoc#isis.applib.annotation.action.publishing[`isis.applib.annotation.action.publishing`] configuration property is used to determine the whetherthe action is published:
-* `all` +
+* `all`
+
all action invocations are published
-* `ignoreSafe` (or `ignoreQueryOnly`) +
+* `ignoreSafe` (or `ignoreQueryOnly`)
+
invocations of actions with safe (read-only) semantics are ignored, but actions which may modify data are not ignored
-* `none` +
+* `none`
+
no action invocations are published
-If there is no configuration property in `isis.properties` then publishing is automatically enabled.
+If there is no configuration property in `application.properties` then publishing is automatically enabled.
This default can be overridden on an action-by-action basis; if `publishing()` is set to `ENABLED` then the action invocation is published irrespective of the configured value; if set to `DISABLED` then the action invocation is _not_ published, again irrespective of the configured value.
@@ -32,15 +32,11 @@ For example:
[source,java]
----
public class Order {
- @Action(publishing=Publishing.ENABLED) // <1>
+ @Action(publishing=Publishing.ENABLED) // <.>
public Invoice generateInvoice(...) { /* ... */ }
}
----
-<1> because set to enabled, will be published irrespective of the configured value.
-
-
-
-
+<.> because set to enabled, will be published irrespective of the configured value.
== See also
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Action/semantics.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Action/semantics.adoc
index a0d47fe..5961589 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Action/semantics.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Action/semantics.adoc
@@ -1,3 +1,4 @@
+[#semantics]
= `semantics`
:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/editing.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/editing.adoc
index b24209b..5b937b9 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/editing.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/editing.adoc
@@ -4,6 +4,7 @@
:page-partial:
+WARNING: TODO - v2 - not yet reviewed/updated.
The `editing` attribute determines whether a domain object's properties and collections are not editable (are read-only).
@@ -17,21 +18,20 @@ the object's properties and collections are modifiable.
+
the object's properties and collections are read-only, ie _not_ modifiable.
-If there is no configuration property in `isis.properties` then object are assumed to be modifiable.
+If there is no configuration property in `application.properties` then object are assumed to be modifiable.
[TIP]
====
-In other words, editing can be disabled globally for an application by setting:
+In other words, editing can be disabled globally by setting the xref:refguide:config:sections/isis.applib.adoc#isis.applib.annotation.domain-object.editing[`isis.applib.adoc#isis.applib.annotation.domain-object.editing`] configuration property:
[source,ini]
----
-isis.objects.editing=false
+isis.applib.annotation.domain-object.editing=false
----
-We recommend enabling this feature; it will help drive out the underlying business operations (processes and procedures) that require objects to change; these can then be captured as business actions.
+We recommend this setting; it will help drive out the underlying business operations (processes and procedures) that require objects to change; these can then be captured as business actions.
====
-The related `editingDisabledReason` attribute specifies the a hard-coded reason why the object's properties and collections cannot be modified directly.
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/publishing.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/publishing.adoc
index 6fa9087..f4f087d 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/publishing.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/DomainObject/publishing.adoc
@@ -9,17 +9,17 @@ The `publishing` attribute determines whether and how a modified object instance
A common use case is to notify external "downstream" systems of changes in the state of the Apache Isis application.
-The default value for the attribute is `AS_CONFIGURED`, meaning that the xref:refguide:config:configuring-core.adoc[configuration property] `isis.services.publish.objects` is used to determine the whether the action is published:
+The default value for the attribute is `AS_CONFIGURED`, meaning that the xref:refguide:config:sections/isis.applib.adoc#isis.applib.annotation.domain-object.publishing[`isis.applib.annotation.domain-object.publishing`] configuration property is used to determine the whether the domain object's changes are published:
-* `all` +
+* `all`
+
all changed objects are published
-* `none` +
+* `none`
+
no changed objects are published
-If there is no configuration property in `isis.properties` then publishing is automatically disabled for domain objects.
+If there is no configuration property in `application.properties` then publishing is automatically disabled for domain objects.
This default can be overridden on an object-by-object basis; if `publishing()` is set to `ENABLED` then changed instances of the domain class are published irrespective of the configured value; if set to `DISABLED` then the changed instances are _not_ published, again irrespective of the configured value.
@@ -36,10 +36,6 @@ public class InterestRate {
----
<1> because set to enabled, will be published irrespective of the configured value.
-
-
-
-
== See also
This attribute is also supported for:
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/Property/publishing.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/Property/publishing.adoc
index 1549ed7..d066c1f 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/Property/publishing.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/Property/publishing.adoc
@@ -9,9 +9,7 @@
The `publishing` attribute determines whether and how a property edit is published via the registered implementation of xref:refguide:applib-svc:PublisherService.adoc[`PublisherService`].
A common use case is to notify external "downstream" systems of changes in the state of the Apache Isis application.
-The default value for the attribute is `AS_CONFIGURED`, meaning that the
-xref:refguide:config:configuring-core.adoc[configuration property] `isis.services.publish.properties` is used to
-determine the whether the property is published:
+The default value for the attribute is `AS_CONFIGURED`, meaning that the xref:refguide:config:sections/isis.applib.adoc#isis.applib.annotation.property.publishing[`isis.applib.annotation.property.publishing`] configuration property is used to determine the whether the property edits are published:
* `all`
+
@@ -21,7 +19,7 @@ all property edits are published
+
no property edits are published
-If there is no configuration property in `isis.properties` then publishing is automatically enabled.
+If there is no configuration property in `application.properties` then publishing is automatically enabled.
This default can be overridden on an property-by-property basis; if `publishing()` is set to `ENABLED` then the
property edit is published irrespective of the configured value; if set to `DISABLED` then the property edit is
diff --git a/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/labelPosition.adoc b/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/labelPosition.adoc
index 64843da..af44481 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/labelPosition.adoc
+++ b/api/applib/src/main/adoc/modules/applib-ant/pages/PropertyLayout/labelPosition.adoc
@@ -63,18 +63,20 @@ image::reference-annotations/PropertyLayout/labelPosition-boolean-RIGHT.png[widt
====
If you want a consistent look-n-feel throughout the app, eg all property labels to the top, then it'd be rather frustrating to have to annotate every property.
-Instead, a default can be specified using a xref:refguide:config:configuring-core.adoc[configuration property] in `isis.properties`:
+Instead, a default can be specified using the xref:refguide:config:sections/isis.applib.adoc#isis.applib.annotation.property-layout.label-position[`isis.applib.annotation.property-layout.label-position`] configuration property:
[source,ini]
+.application.properties
----
-isis.viewers.propertyLayout.labelPosition=TOP
+isis.applib.annotation.property-layout.label-position=TOP
----
or
[source,ini]
+.application.properties
----
-isis.viewers.propertyLayout.labelPosition=LEFT
+isis.applib.annotation.property-layout.label-position=LEFT
----
If these are not present then Apache Isis will render according to internal defaults. At the time of writing, this means labels are to the left for all datatypes except multiline strings.
diff --git a/api/applib/src/main/adoc/modules/applib-cm/pages/classes/utility/ObjectContracts.adoc b/api/applib/src/main/adoc/modules/applib-cm/pages/classes/utility/ObjectContracts.adoc
index 4ae4042..04d398a 100644
--- a/api/applib/src/main/adoc/modules/applib-cm/pages/classes/utility/ObjectContracts.adoc
+++ b/api/applib/src/main/adoc/modules/applib-cm/pages/classes/utility/ObjectContracts.adoc
@@ -44,7 +44,7 @@ We therefore recommend that you disable persistence-by-reachability by adding:
[source,ini]
.persistor_datanucleus.properties
----
-isis.persistor.datanucleus.impl.datanucleus.persistenceByReachabilityAtCommit=false
+isis.persistence.jdo-datanucleus.impl.datanucleus.persistenceByReachabilityAtCommit=false
----
====
diff --git a/api/applib/src/main/adoc/modules/applib-svc/pages/ExceptionRecognizer.adoc b/api/applib/src/main/adoc/modules/applib-svc/pages/ExceptionRecognizer.adoc
index 9c9ae42..294b918 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/pages/ExceptionRecognizer.adoc
+++ b/api/applib/src/main/adoc/modules/applib-svc/pages/ExceptionRecognizer.adoc
@@ -3,8 +3,7 @@
:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...]
:page-partial:
-WARNING: TODO - to review for v2.
-
+WARNING: TODO - v2 - not yet reviewed/updated.
The `ExceptionRecognizer` SPI provides the mechanism for both the domain programmer and also for components to be able to recognize and handle certain exceptions that may be thrown by the system.
Rather than display an obscure error to the end-user, the application can instead display a user-friendly message.
@@ -12,9 +11,6 @@ Rather than display an obscure error to the end-user, the application can instea
For example, the JDO/DataNucleus Objectstore provides a set of recognizers to recognize and handle SQL constraint exceptions such as uniqueness violations.
These can then be rendered back to the user as expected errors, rather than fatal stacktraces.
-It is also possible to provide additional implementations, registered in `isis.properties`.
-Unlike other services, where any service registered in `isis.properties` replaces any default implementations, in the case of this service all implementations registered are "consulted" to see if they recognize an exception (the chain-of-responsibility pattern).
-
diff --git a/examples/demo/src/main/java/demoapp/dom/jee/JeeDemo.adoc b/examples/demo/src/main/java/demoapp/dom/jee/JeeDemo.adoc
index af67a85..0cf0051 100644
--- a/examples/demo/src/main/java/demoapp/dom/jee/JeeDemo.adoc
+++ b/examples/demo/src/main/java/demoapp/dom/jee/JeeDemo.adoc
@@ -10,7 +10,7 @@ import javax.ejb.Singleton;
@Singleton
public class JeeDemoService {
-
+
public String getMessage() {
return "Hello World from JEE";
}
@@ -25,14 +25,14 @@ CDI managed beans:
----
@DomainObject
public class JeeDemo {
-
+
@Inject private JeeDemoService jeeDemoService;
@Action
public String getJeeMessage(){
return jeeDemoService.getMessage();
}
-
+
...
}
@@ -50,9 +50,9 @@ connection pool via `JNDI` lookup.
=== Setup JDO
....
-isis.persistor.datanucleus.impl.datanucleus.ConnectionFactoryName=jdbc/demo-domain
-isis.persistor.datanucleus.impl.datanucleus.ConnectionFactory2Name=jdbc/demo-domain-nontx
-isis.persistor.datanucleus.impl.javax.jdo.option.TransactionType=JTA
+isis.persistence.jdo-datanucleus.impl.datanucleus.ConnectionFactoryName=jdbc/demo-domain
+isis.persistence.jdo-datanucleus.impl.datanucleus.ConnectionFactory2Name=jdbc/demo-domain-nontx
+isis.persistence.jdo-datanucleus.impl.javax.jdo.option.TransactionType=JTA
....
=== Setup JNDI resource provider
@@ -67,7 +67,7 @@ import javax.ejb.*;
@Singleton
@Startup
public class ConnectionResources {
-
+
@Resource(lookup="jdbc/demo-domain")
private javax.sql.DataSource domainDS;
@@ -75,4 +75,4 @@ public class ConnectionResources {
private javax.sql.DataSource domainDS_nontx;
}
-----
\ No newline at end of file
+----
diff --git a/persistence/jdo/adoc/modules/ROOT/pages/configuring.adoc b/persistence/jdo/adoc/modules/ROOT/pages/configuring.adoc
index c102147..130acbf 100644
--- a/persistence/jdo/adoc/modules/ROOT/pages/configuring.adoc
+++ b/persistence/jdo/adoc/modules/ROOT/pages/configuring.adoc
@@ -3,16 +3,22 @@
: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 [...]
-Apache Isis programmatically configures DataNucleus; any Apache Isis properties with the prefix `isis.persistor.datanucleus.impl` are passed through directly to the JDO/DataNucleus objectstore (with the prefix stripped off, of course).
+The xref:refguide:config:about.adoc[Configuration Guide] includes a xref:refguide:config:sections/isis.persistence.jdo-datanucleus.adoc[section] for JDO/Persistence object store, and another xref:refguide:config:sections/isis.persistence.jdo-datanucleus.impl.adoc[section] for configuration that is passed through to DataNucleus unchanged.
-DataNucleus will for itself also and read the `META-INF/persistence.xml`; at a minimum this defines the name of the "persistence unit".
-In theory it could also hold mappings, though in Apache Isis we tend to use annotations instead.
+WARNING: TODO - v2 - detail on original config properties (not yet reviewed) currently commented out.
-Furthermore, DataNucleus will search for various other XML mapping files, eg `mappings.jdo`. A full list can be found http://www.datanucleus.org/products/datanucleus/jdo/metadata.html[here]. The metadata in these XML can be used to override the annotations of annotated entities; see xref:userguide:btb:about.adoc#overriding-jdo-annotations[Overriding JDO Annotatons] for further discussion.
-
-
-include::configuring/properties.adoc[leveloffset=+1]
-include::configuring/bulk-load.adoc[leveloffset=+1]
-include::configuring/disabling-persistence-by-reachability.adoc[leveloffset=+1]
-include::configuring/persistence-xml.adoc[leveloffset=+1]
-include::configuring/using-jndi-data-source.adoc[leveloffset=+1]
+//Apache Isis programmatically configures DataNucleus; any Apache Isis properties with the prefix `isis.persistence.jdo-datanucleus.impl` are passed through directly to the JDO/DataNucleus objectstore (with the prefix stripped off, of course).
+//
+//DataNucleus will for itself also and read the `META-INF/persistence.xml`; at a minimum this defines the name of the "persistence unit".
+//In theory it could also hold mappings, though in Apache Isis we tend to use annotations instead.
+//
+//Furthermore, DataNucleus will search for various other XML mapping files, eg `mappings.jdo`.
+//A full list can be found http://www.datanucleus.org/products/datanucleus/jdo/metadata.html[here].
+//The metadata in these XML can be used to override the annotations of annotated entities; see xref:userguide:btb:about.adoc#overriding-jdo-annotations[Overriding JDO Annotatons] for further discussion.
+//
+//
+//include::configuring/properties.adoc[leveloffset=+1]
+//include::configuring/bulk-load.adoc[leveloffset=+1]
+//include::configuring/disabling-persistence-by-reachability.adoc[leveloffset=+1]
+//include::configuring/persistence-xml.adoc[leveloffset=+1]
+//include::configuring/using-jndi-data-source.adoc[leveloffset=+1]
diff --git a/persistence/jdo/adoc/modules/ROOT/pages/configuring/disabling-persistence-by-reachability.adoc b/persistence/jdo/adoc/modules/ROOT/pages/configuring/disabling-persistence-by-reachability.adoc
index 9e2bb0c..cfe776c 100644
--- a/persistence/jdo/adoc/modules/ROOT/pages/configuring/disabling-persistence-by-reachability.adoc
+++ b/persistence/jdo/adoc/modules/ROOT/pages/configuring/disabling-persistence-by-reachability.adoc
@@ -24,7 +24,7 @@ We therefore recommend that you disable persistence-by-reachability by adding th
[source,ini]
----
-isis.persistor.datanucleus.impl.datanucleus.persistenceByReachabilityAtCommit=false
+isis.persistence.jdo-datanucleus.impl.datanucleus.persistenceByReachabilityAtCommit=false
----
This change has been made to both the xref:docs:starters:helloworld.adoc[HelloWorld] and xref:docs:starters:simpleapp.adoc[SimpleApp] starter apps.
diff --git a/persistence/jdo/adoc/modules/ROOT/pages/configuring/properties.adoc b/persistence/jdo/adoc/modules/ROOT/pages/configuring/properties.adoc
index 1d5aea0..04999d4 100644
--- a/persistence/jdo/adoc/modules/ROOT/pages/configuring/properties.adoc
+++ b/persistence/jdo/adoc/modules/ROOT/pages/configuring/properties.adoc
@@ -3,9 +3,10 @@
:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...]
-WARNING: TODO: v2: these are now in core config properties
+The xref:refguide:config:about.adoc[Configuration Guide] includes a xref:refguide:config:sections/isis.persistence.jdo-datanucleus.adoc[section] for JDO/Persistence object store, and another xref:refguide:config:sections/isis.persistence.jdo-datanucleus.impl.adoc[section] for configuration that is passed through to DataNucleus unchanged.
+
+WARNING: TODO - v2 - detail on original config properties (not yet reviewed) currently commented out.
-These configuration properties are typically stored in `WEB-INF/persistor_datanucleus.properties`. However, you can place all configuration properties into `WEB-INF/isis.properties` if you wish (the configuration properties from all config files are merged together).
== Configuration Properties for Apache Isis itself
@@ -85,11 +86,11 @@ Only intended for "emergency use" as a workaround while pending fix/patch to Apa
(_default value_)
|Description
-|`isis.persistor.datanucleus.impl.*`
+|`isis.persistence.jdo-datanucleus.impl.*`
|
-| Passed through directly to Datanucleus (with `isis.persistor.datanucleus.impl` prefix stripped)
+| Passed through directly to Datanucleus (with `isis.persistence.jdo-datanucleus.impl` prefix stripped)
-|`isis.persistor.datanucleus.impl.` +
+|`isis.persistence.jdo-datanucleus.impl.` +
`datanucleus.persistenceByReachabilityAtCommit`
|`false`
|We recommend this setting is disabled. +
diff --git a/persistence/jdo/adoc/modules/ROOT/pages/configuring/using-jndi-data-source.adoc b/persistence/jdo/adoc/modules/ROOT/pages/configuring/using-jndi-data-source.adoc
index e27f1b5..5a55326 100644
--- a/persistence/jdo/adoc/modules/ROOT/pages/configuring/using-jndi-data-source.adoc
+++ b/persistence/jdo/adoc/modules/ROOT/pages/configuring/using-jndi-data-source.adoc
@@ -3,9 +3,10 @@
: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 [...]
-Isis' JDO objectstore can be configured either to connect to the database using its own connection pool, or by using a container-managed datasource.
+WARNING: TODO - v2 - not yet reviewed/updated.
+Apache Isis' JDO objectstore can be configured either to connect to the database using its own connection pool, or by using a container-managed datasource.
== Application managed
@@ -17,13 +18,13 @@ For example:
[source,ini]
----
-isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionDriverName=net.sf.log4jdbc.DriverSpy
-isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionURL=jdbc:log4jdbc:hsqldb:mem:test
-isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionUserName=sa
-isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionPassword=
+isis.persistence.jdo-datanucleus.impl.javax.jdo.option.ConnectionDriverName=net.sf.log4jdbc.DriverSpy
+isis.persistence.jdo-datanucleus.impl.javax.jdo.option.ConnectionURL=jdbc:log4jdbc:hsqldb:mem:test
+isis.persistence.jdo-datanucleus.impl.javax.jdo.option.ConnectionUserName=sa
+isis.persistence.jdo-datanucleus.impl.javax.jdo.option.ConnectionPassword=
----
-Those configuration properties that start with the prefix `isis.persistor.datanucleus.impl.` are passed through directly to DataNucleus (with the prefix removed).
+Those configuration properties that start with the prefix `isis.persistence.jdo-datanucleus.impl.` are passed through directly to DataNucleus (with the prefix removed).
It is also possible to specify the `
datanucleus.ConnectionPasswordDecrypter
@@ -38,7 +39,7 @@ Using a datasource managed by the servlet container requires three separate bits
Firstly, specify the name of the datasource in the `WEB-INF\persistor_datanucleus.properties` file. For example:
-If connection pool settings are also present in this file, they will simply be ignored. Any other configuration properties that start with the prefix `isis.persistor.datanucleus.impl.` are passed through directly to DataNucleus (with the prefix removed).
+If connection pool settings are also present in this file, they will simply be ignored. Any other configuration properties that start with the prefix `isis.persistence.jdo-datanucleus.impl.` are passed through directly to DataNucleus (with the prefix removed).
Secondly, in the `WEB-INF/web.xml`, declare the resource reference:
diff --git a/persistence/jdo/adoc/modules/ROOT/pages/db-schemas.adoc b/persistence/jdo/adoc/modules/ROOT/pages/db-schemas.adoc
index e947b35..ae74fb1 100644
--- a/persistence/jdo/adoc/modules/ROOT/pages/db-schemas.adoc
+++ b/persistence/jdo/adoc/modules/ROOT/pages/db-schemas.adoc
@@ -3,7 +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 [...]
-
In the same way that Java packages act as a namespace for domain objects, it's good practice to map domain entities to their own (database) schemas.
For example:
@@ -54,85 +53,98 @@ See the section on xref:pjdo:ROOT:configuring.adoc[configuring DataNucleus Overr
-
-== Listener to create schema
-
-Apache Isis automatically creates owning schema objects for the tables that correspond to each entity class in the JDO metamodel.
-
-This is done by installing a listener, `CreateSchemaObjectFromClassMetadata`, on a callback provided by JDO/DataNucleus.
-The listener is invoked on the initialization of each class.
-It checks for the schema's existence, and creates the schema if required.
-
-The guts of its implementation is:
-
-[source,java]
-----
-public class CreateSchemaObjectFromClassMetadata
- implements MetaDataListener,
- DataNucleusPropertiesAware {
- @Override
- public void loaded(final AbstractClassMetaData cmd) { /* ... */ }
-
- protected String buildSqlToCheck(final AbstractClassMetaData cmd) {
- final String schemaName = schemaNameFor(cmd);
- return String.format(
- "SELECT count(*) FROM INFORMATION_SCHEMA.SCHEMATA where SCHEMA_NAME = '%s'", schemaName);
- }
- protected String buildSqlToExec(final AbstractClassMetaData cmd) {
- final String schemaName = schemaNameFor(cmd);
- return String.format("CREATE SCHEMA \"%s\"", schemaName);
- }
-}
-----
-
-where `MetaDataListener` is the DataNucleus listener API:
-
-[source,java]
-----
-public interface MetaDataListener {
- void loaded(AbstractClassMetaData cmd);
-}
-----
-
-Although not formal API, the default `CreateSchemaObjectFromClassMetadata` has been designed to be easily overrideable if you need to tweak it to support other RDBMS'.
-Any implementation must implement `org.datanucleus.metadata.MetaDataListener`:
-
-The implementation provided has has been tested for HSQLDB, PostgreSQL and MS SQL Server, and is used automatically unless an alternative implementation is specified (as described in the section below).
-
-
-
-
-
-== Alternative implementation
-
-An alternative implementation can be registered and used through the following configuration property:
-
-[source,ini]
-----
-isis.persistor.datanucleus.classMetadataLoadedListener=\
- org.apache.isis.objectstore.jdo.datanucleus.CreateSchemaObjectFromClassMetadata
-----
-
-
-Because this pertains to JDO/DataNucleus we suggest you put this configuration property in `WEB-INF/persistor_datanucleus.properties`; but putting it in `isis.properties` will also work.
-
-Any implementation must implement `org.datanucleus.metadata.MetaDataListener`.
-In many cases simply subclassing from `CreateSchemaObjectFromClassMetadata` and overriding `buildSqlToCheck(...)` and `buildSqlToExec(...)` should suffice.
-
-If you _do_ need more control, your implementation can also optionally implement `org.apache.isis.objectstore.jdo.datanucleus.DataNucleusPropertiesAware`:
-
-[source,java]
-----
-public interface DataNucleusPropertiesAware {
- public void setDataNucleusProperties(final Map<String, String> properties);
-}
-----
-
-This provides access to the properties passed through to JDO/DataNucleus.
-
-
-[IMPORTANT]
-====
-If you do extend Apache Isis' `CreateSchemaObjectFromClassMetadata` class for some other database, please https://issues.apache.org/jira/browse/ISIS[contribute back] your improvements.
-====
-
+== Flyway
+
+WARNING: TODO - v2 - reference flyway here also.
+
+
+
+//
+// no longer seems to be needed in v2
+//
+//
+//== Listener to create schema
+//
+//Apache Isis automatically creates owning schema objects for the tables that correspond to each entity class in the JDO metamodel.
+//
+//This is done by installing a listener, `CreateSchemaObjectFromClassMetadata`, on a callback provided by JDO/DataNucleus.
+//The listener is invoked on the initialization of each class.
+//It checks for the schema's existence, and creates the schema if required.
+//
+//The guts of its implementation is:
+//
+//[source,java]
+//----
+//public class CreateSchemaObjectFromClassMetadata
+// implements MetaDataListener,
+// DataNucleusPropertiesAware {
+// @Override
+// public void loaded(final AbstractClassMetaData cmd) { /* ... */ }
+//
+// protected String buildSqlToCheck(final AbstractClassMetaData cmd) {
+// final String schemaName = schemaNameFor(cmd);
+// return String.format(
+// "SELECT count(*) FROM INFORMATION_SCHEMA.SCHEMATA where SCHEMA_NAME = '%s'", schemaName);
+// }
+// protected String buildSqlToExec(final AbstractClassMetaData cmd) {
+// final String schemaName = schemaNameFor(cmd);
+// return String.format("CREATE SCHEMA \"%s\"", schemaName);
+// }
+//}
+//----
+//
+//where `MetaDataListener` is the DataNucleus listener API:
+//
+//[source,java]
+//----
+//public interface MetaDataListener {
+// void loaded(AbstractClassMetaData cmd);
+//}
+//----
+//
+//Although not formal API, the default `CreateSchemaObjectFromClassMetadata` has been designed to be easily overrideable if you need to tweak it to support other RDBMS'.
+//Any implementation must implement `org.datanucleus.metadata.MetaDataListener`:
+//
+//The implementation provided has has been tested for HSQLDB, PostgreSQL and MS SQL Server, and is used automatically unless an alternative implementation is specified (as described in the section below).
+//
+//
+//
+//
+//
+//== Alternative implementation
+//
+//An alternative implementation can be registered and used through the
+//
+//xref:refguide:config:sections/isis.persistence.jdo-datanucleus.impl.adoc#class
+//
+//configuration property:
+//
+//[source,ini]
+//----
+//isis.persistor.datanucleus.classMetadataLoadedListener=\
+// org.apache.isis.objectstore.jdo.datanucleus.CreateSchemaObjectFromClassMetadata
+//----
+//
+//
+//Because this pertains to JDO/DataNucleus we suggest you put this configuration property in `WEB-INF/persistor_datanucleus.properties`; but putting it in `isis.properties` will also work.
+//
+//Any implementation must implement `org.datanucleus.metadata.MetaDataListener`.
+//In many cases simply subclassing from `CreateSchemaObjectFromClassMetadata` and overriding `buildSqlToCheck(...)` and `buildSqlToExec(...)` should suffice.
+//
+//If you _do_ need more control, your implementation can also optionally implement `org.apache.isis.objectstore.jdo.datanucleus.DataNucleusPropertiesAware`:
+//
+//[source,java]
+//----
+//public interface DataNucleusPropertiesAware {
+// public void setDataNucleusProperties(final Map<String, String> properties);
+//}
+//----
+//
+//This provides access to the properties passed through to JDO/DataNucleus.
+//
+//
+//[IMPORTANT]
+//====
+//If you do extend Apache Isis' `CreateSchemaObjectFromClassMetadata` class for some other database, please https://issues.apache.org/jira/browse/ISIS[contribute back] your improvements.
+//====
+//
diff --git a/persistence/jdo/adoc/modules/ROOT/pages/hints-and-tips/overriding-jdo-annotations.adoc b/persistence/jdo/adoc/modules/ROOT/pages/hints-and-tips/overriding-jdo-annotations.adoc
index 17b8404..2f3acef 100644
--- a/persistence/jdo/adoc/modules/ROOT/pages/hints-and-tips/overriding-jdo-annotations.adoc
+++ b/persistence/jdo/adoc/modules/ROOT/pages/hints-and-tips/overriding-jdo-annotations.adoc
@@ -69,13 +69,13 @@ For example:
----
It's also necessary to tell JDO/DataNucleus about which vendor is being used (`sqlserver` in the example above).
-This is done using a configuration property:
+This is done using the pass-thru `datanucleus.Mapping` configuration property:
-.isis.properties
[source,ini]
+.application.properties
----
-isis.persistor.datanucleus.impl.datanucleus.Mapping=sqlserver
+isis.persistence.jdo-datanucleus.impl.datanucleus.Mapping=sqlserver
----
diff --git a/testing/h2console/adoc/modules/h2console/pages/services/H2ManagerMenu.adoc b/testing/h2console/adoc/modules/h2console/pages/services/H2ManagerMenu.adoc
index 6c32f50..e93276d 100644
--- a/testing/h2console/adoc/modules/h2console/pages/services/H2ManagerMenu.adoc
+++ b/testing/h2console/adoc/modules/h2console/pages/services/H2ManagerMenu.adoc
@@ -3,7 +3,7 @@
:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...]
:page-partial:
-
+WARNING: TODO - v2 - not yet reviewed/updated.
The `H2ManagerMenu` provides a single menu item to redirect to the H2 web console.
This is only enabled for prototyping, and only if H2 is detected in the underlying JDBC URL.
@@ -40,12 +40,12 @@ The following additional configuration is also required (all of this is present
* the `jdbc:h2` URL configuration properties must be defined, eg in `application.properties`:
+
[source,ini]
-.isis.properties
+.application.properties
----
-isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionDriverName=org.h2.Driver
-isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionURL=jdbc:h2:mem:test
-isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionUserName=sa
-isis.persistor.datanucleus.impl.javax.jdo.option.ConnectionPassword=
+isis.persistence.jdo-datanucleus.impl.javax.jdo.option.ConnectionDriverName=org.h2.Driver
+isis.persistence.jdo-datanucleus.impl.javax.jdo.option.ConnectionURL=jdbc:h2:mem:test
+isis.persistence.jdo-datanucleus.impl.javax.jdo.option.ConnectionUserName=sa
+isis.persistence.jdo-datanucleus.impl.javax.jdo.option.ConnectionPassword=
----
* finally, and most importantly, the h2 console servlet must be configured in `web.xml`, and must be mapped to `/db`:
diff --git a/viewers/restfulobjects/adoc/modules/ROOT/pages/configuration-properties.adoc b/viewers/restfulobjects/adoc/modules/ROOT/pages/configuration-properties.adoc
index 0f358e8..a760b44 100644
--- a/viewers/restfulobjects/adoc/modules/ROOT/pages/configuration-properties.adoc
+++ b/viewers/restfulobjects/adoc/modules/ROOT/pages/configuration-properties.adoc
@@ -2,190 +2,192 @@
:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...]
-
-WARNING: TODO: v2 : moved instead to core config.
-
-The Restful Objects viewer provides a couple of configuration option that extend/simplify/alter the representations generated from the Restful Objects specification.
-
-These configuration properties are typically stored in `WEB-INF/viewer_restfulobjects.properties`.
-However, you can place all configuration properties into `WEB-INF/isis.properties` if you wish (the configuration properties from all config files are merged together).
-
-
-== Standard
-
-The following configuration properties are supported:
-
-.Restful Objects Viewer Configuration Properties
-[cols="2a,1,3", options="header"]
-|===
-|Property
-|Value +
-(_default value_)
-|Description
-
-|`isis.viewer.restfulobjects.` +
-`honorUiHints`
-| `true`,`false` (`_false_`)
-|A mechanism for reducing the number of round-trips by eagerly rendering collections; discussed xref:vro:ROOT:ro-spec.adoc#honor-ui-hints[here].
-
-|`isis.viewer.restfulobjects.` +
-`strictAcceptChecking`
-| `true`,`false` (`_false_`)
-|Whether to strictly enforce the `Accept` header checking for the default RO-spec representations (by the
-`ContentNegotiationServiceForRestfulObjectsV1_0` service). Will otherwise accept anything. +
-
-This is convenient because it allows the `Accept` header to be set to that of the
-xref:vro:ROOT:simplified-representations.adoc[Apache Isis profile] for all resources, rather than simply the
-handful of resources that supported that profile.
-
-|===
-
-In addition:
-
-[cols="2a,1,3a", options="header"]
-|===
-|Property
-|Value +
-(default value)
-|Description
-
-|`isis.services.` +
-`ContentNegotiation-` +
-`ServiceXRoDomainType` +
-.`prettyPrint`
-| `true`,`false` +
-(depends)
-|If a domain object has been mapped to the specified JAXB `x-ro-domain-type`, then determines whether the result is pretty-printed or not. +
-
-If no configuration property is available, then the defaults is determined by the xref:refguide:config:deployment-types.adoc[deployment type]: production mode disables pretty printing, while prototype mode enables it.
-
-|===
-
-
-
-== Deprecated
-
-There are also a number of configuration properties that can be used to suppress or simplify the default RO-spec
-representations.
-
-These configuration properties pre-date the support for the Apache Isis profile, and are limited by the fact that they are global configuration settings, so cannot be influenced on a request-by-request basis (as is the case with the `Accept` header used for the Apache Isis profile).
-They have therefore been deprecated, and may be removed in the future.
-
-Nevertheless, those configuration properties are:
-
-.Deprecated Configuration Properties
-[cols="2a,1,3", options="header"]
-|===
-|Property
-|Value +
-(_default value_)
-|Description
-
-|`isis.viewer.restfulobjects.` +
-`suppressDescribedByLinks`
-| `true`,`false` (`_false_`)
-|Suppresses the "describedby" links (on all representations)
-
-|`isis.viewer.restfulobjects.` +
-`suppressUpdateLink`
-| `true`,`false` (`_false_`)
-|suppresses the "update" link (on object representation)
-
-|`isis.viewer.restfulobjects.` +
-`suppressMemberId`
-| `true`,`false` (`_false_`)
-|suppresses the "id" json-prop for object members (on object representation and member detail representations)
-
-|`isis.viewer.restfulobjects.` +
-`suppressMemberLinks`
-| `true`,`false` (`_false_`)
-|suppresses the "links" json-prop for object members (on the object representation and member detail representations)
-
-|`isis.viewer.restfulobjects.` +
-`suppressMemberExtensions`
-| `true`,`false` (`_false_`)
-|suppresses the "extensions" json-prop for object members (on the object representation and member detail representations)
-
-|`isis.viewer.restfulobjects.` +
-`suppressMemberDisabledReason`
-| `true`,`false` (`_false_`)
-|suppresses the "disabledReason" json-prop for object members (on the object representation and member detail representations)
-
-|`isis.viewer.restfulobjects.` +
-`objectPropertyValuesOnly`
-| `true`,`false` (`_false_`)
-| See discussionp below.
-|
-
-|===
-
-
-For example, these configuration properties could all be added in the `WEB-INF/viewer_restfulobjects.properties`):
-
-[source,ini]
-----
-isis.viewer.restfulobjects.suppressDescribedByLinks=true
-isis.viewer.restfulobjects.suppressUpdateLink=true
-isis.viewer.restfulobjects.suppressMemberId=true
-isis.viewer.restfulobjects.suppressMemberLinks=true
-isis.viewer.restfulobjects.suppressMemberExtensions=true
-isis.viewer.restfulobjects.suppressMemberDisabledReason=true
-----
-
-
-[NOTE]
-====
-If these configuration settings are set in conjunction with using the xref:vro:ROOT:simplified-representations.adoc#apache-isis-profile[Apache Isis profile], then the special `$$ro` property in the representations with reflect these settings.
-====
-
-
-
-If the `objectPropertyValuesOnly` configuration property is set:
-
-[source,ini]
-----
-isis.viewer.restfulobjects.objectPropertyValuesOnly=true
-----
-
-then this generates a representation such as:
-
-[source,javascript]
-----
-{
- "title" : "Buy milk due by 2014-10-27",
- "domainType" : "TODO",
- "instanceId" : "0",
- "members" : {
- "description" : "Buy milk",
- "category" : "Domestic",
- "subcategory" : "Shopping",
- "complete" : false,
- "versionSequence" : 1,
- "relativePriority" : 2,
- "dueBy" : "2014-10-27",
- "cost" : "0.75",
- "notes" : null,
- "attachment" : null,
- "doc" : null
- },
- "links" : [
- {
- "rel" : "self",
- "href" : "http://localhost:8080/restful/objects/TODO/0",
- "method" : "GET",
- "type" : "application/json;profile=\"urn:org.restfulobjects:repr-types/object\"",
- "title" : "Buy milk due by 2014-10-27"
- },
- {
- "rel" : "describedby",
- "href" : "http://localhost:8080/restful/domain-types/TODO",
- "method" : "GET",
- "type" : "application/json;profile=\"urn:org.restfulobjects:repr-types/domain-type\""
- }
- ],
- "extensions" : {
- "oid" : "TODO:0"
- },
-}
-----
-
+The xref:refguide:config:about.adoc[Configuration Guide] includes a xref:refguide:config:sections/isis.viewer.restfulobjects.adoc[section] for the Restful Objects viewer.
+
+
+WARNING: TODO - v2 - detail on original config properties (not yet reviewed) currently commented out.
+
+//The Restful Objects viewer provides a couple of configuration option that extend/simplify/alter the representations generated from the Restful Objects specification.
+//
+//These configuration properties are typically stored in `WEB-INF/viewer_restfulobjects.properties`.
+//However, you can place all configuration properties into `WEB-INF/isis.properties` if you wish (the configuration properties from all config files are merged together).
+//
+//
+//== Standard
+//
+//The following configuration properties are supported:
+//
+//.Restful Objects Viewer Configuration Properties
+//[cols="2a,1,3", options="header"]
+//|===
+//|Property
+//|Value +
+//(_default value_)
+//|Description
+//
+//|`isis.viewer.restfulobjects.` +
+//`honorUiHints`
+//| `true`,`false` (`_false_`)
+//|A mechanism for reducing the number of round-trips by eagerly rendering collections; discussed xref:vro:ROOT:ro-spec.adoc#honor-ui-hints[here].
+//
+//|`isis.viewer.restfulobjects.` +
+//`strictAcceptChecking`
+//| `true`,`false` (`_false_`)
+//|Whether to strictly enforce the `Accept` header checking for the default RO-spec representations (by the
+//`ContentNegotiationServiceForRestfulObjectsV1_0` service). Will otherwise accept anything. +
+//
+//This is convenient because it allows the `Accept` header to be set to that of the
+//xref:vro:ROOT:simplified-representations.adoc[Apache Isis profile] for all resources, rather than simply the
+//handful of resources that supported that profile.
+//
+//|===
+//
+//In addition:
+//
+//[cols="2a,1,3a", options="header"]
+//|===
+//|Property
+//|Value +
+//(default value)
+//|Description
+//
+//|`isis.services.` +
+//`ContentNegotiation-` +
+//`ServiceXRoDomainType` +
+//.`prettyPrint`
+//| `true`,`false` +
+//(depends)
+//|If a domain object has been mapped to the specified JAXB `x-ro-domain-type`, then determines whether the result is pretty-printed or not. +
+//
+//If no configuration property is available, then the defaults is determined by the xref:refguide:config:deployment-types.adoc[deployment type]: production mode disables pretty printing, while prototype mode enables it.
+//
+//|===
+//
+//
+//
+//== Deprecated
+//
+//There are also a number of configuration properties that can be used to suppress or simplify the default RO-spec
+//representations.
+//
+//These configuration properties pre-date the support for the Apache Isis profile, and are limited by the fact that they are global configuration settings, so cannot be influenced on a request-by-request basis (as is the case with the `Accept` header used for the Apache Isis profile).
+//They have therefore been deprecated, and may be removed in the future.
+//
+//Nevertheless, those configuration properties are:
+//
+//.Deprecated Configuration Properties
+//[cols="2a,1,3", options="header"]
+//|===
+//|Property
+//|Value +
+//(_default value_)
+//|Description
+//
+//|`isis.viewer.restfulobjects.` +
+//`suppressDescribedByLinks`
+//| `true`,`false` (`_false_`)
+//|Suppresses the "describedby" links (on all representations)
+//
+//|`isis.viewer.restfulobjects.` +
+//`suppressUpdateLink`
+//| `true`,`false` (`_false_`)
+//|suppresses the "update" link (on object representation)
+//
+//|`isis.viewer.restfulobjects.` +
+//`suppressMemberId`
+//| `true`,`false` (`_false_`)
+//|suppresses the "id" json-prop for object members (on object representation and member detail representations)
+//
+//|`isis.viewer.restfulobjects.` +
+//`suppressMemberLinks`
+//| `true`,`false` (`_false_`)
+//|suppresses the "links" json-prop for object members (on the object representation and member detail representations)
+//
+//|`isis.viewer.restfulobjects.` +
+//`suppressMemberExtensions`
+//| `true`,`false` (`_false_`)
+//|suppresses the "extensions" json-prop for object members (on the object representation and member detail representations)
+//
+//|`isis.viewer.restfulobjects.` +
+//`suppressMemberDisabledReason`
+//| `true`,`false` (`_false_`)
+//|suppresses the "disabledReason" json-prop for object members (on the object representation and member detail representations)
+//
+//|`isis.viewer.restfulobjects.` +
+//`objectPropertyValuesOnly`
+//| `true`,`false` (`_false_`)
+//| See discussionp below.
+//|
+//
+//|===
+//
+//
+//For example, these configuration properties could all be added in the `WEB-INF/viewer_restfulobjects.properties`):
+//
+//[source,ini]
+//----
+//isis.viewer.restfulobjects.suppressDescribedByLinks=true
+//isis.viewer.restfulobjects.suppressUpdateLink=true
+//isis.viewer.restfulobjects.suppressMemberId=true
+//isis.viewer.restfulobjects.suppressMemberLinks=true
+//isis.viewer.restfulobjects.suppressMemberExtensions=true
+//isis.viewer.restfulobjects.suppressMemberDisabledReason=true
+//----
+//
+//
+//[NOTE]
+//====
+//If these configuration settings are set in conjunction with using the xref:vro:ROOT:simplified-representations.adoc#apache-isis-profile[Apache Isis profile], then the special `$$ro` property in the representations with reflect these settings.
+//====
+//
+//
+//
+//If the `objectPropertyValuesOnly` configuration property is set:
+//
+//[source,ini]
+//----
+//isis.viewer.restfulobjects.objectPropertyValuesOnly=true
+//----
+//
+//then this generates a representation such as:
+//
+//[source,javascript]
+//----
+//{
+// "title" : "Buy milk due by 2014-10-27",
+// "domainType" : "TODO",
+// "instanceId" : "0",
+// "members" : {
+// "description" : "Buy milk",
+// "category" : "Domestic",
+// "subcategory" : "Shopping",
+// "complete" : false,
+// "versionSequence" : 1,
+// "relativePriority" : 2,
+// "dueBy" : "2014-10-27",
+// "cost" : "0.75",
+// "notes" : null,
+// "attachment" : null,
+// "doc" : null
+// },
+// "links" : [
+// {
+// "rel" : "self",
+// "href" : "http://localhost:8080/restful/objects/TODO/0",
+// "method" : "GET",
+// "type" : "application/json;profile=\"urn:org.restfulobjects:repr-types/object\"",
+// "title" : "Buy milk due by 2014-10-27"
+// },
+// {
+// "rel" : "describedby",
+// "href" : "http://localhost:8080/restful/domain-types/TODO",
+// "method" : "GET",
+// "type" : "application/json;profile=\"urn:org.restfulobjects:repr-types/domain-type\""
+// }
+// ],
+// "extensions" : {
+// "oid" : "TODO:0"
+// },
+//}
+//----
+//
diff --git a/viewers/wicket/adoc/modules/ROOT/pages/configuration-properties.adoc b/viewers/wicket/adoc/modules/ROOT/pages/configuration-properties.adoc
index 49fdf53..80276e0 100644
--- a/viewers/wicket/adoc/modules/ROOT/pages/configuration-properties.adoc
+++ b/viewers/wicket/adoc/modules/ROOT/pages/configuration-properties.adoc
@@ -3,937 +3,939 @@
:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or ag [...]
-WARNING: TODO: v2: instead x-ref core config.
-
-Wicket configuration properties alter the way in which Apache Isis' Wicket viewer renders domain objects.
-
-== Loading Configuration Properties
-
-Configuration properties are typically stored in `WEB-INF/isis.properties` or in `WEB-INF/viewer_wicket.properties`.
-
-To tell Apache Isis that the Wicket viewer is in use (and should therefore search for the `viewer_wicket.properties` file), add the following to `WEB-INF/web.xml`:
-
-// TODO: v2: is this still supported? I doubt it.
-
-[source, xml]
-----
-<context-param>
- <param-name>isis.viewers</param-name>
- <param-value>wicket</param-value>
-</context-param>
-----
-
-Alternatively, because most of these configuration properties tend not to change between environment (development and production), another practice is to load them programmatically from the `AppManifest`:
-
-// TODO: v2: any reference to AppManifestAbstract will need updating.
-
-[source,java]
-----
-public class MyAppAppManifest extends AppManifestAbstract2 {
-
- public static final Builder BUILDER = Builder
- .forModule(new MyApplicationModule())
- //...
- .withConfigurationPropertiesFile(
- MyAppManifest.class, "isis-non-changing.properties") ;
-
- ...
-}
-----
-
-where `isis-non-changing.properties` is on the classpath in the same package as `MyAppAppManifest`.
-
-Whichever approach is used, the configuration properties from all config files are merged together.
-
-
-== Application Identity
-
-Configuration properties that identify the application, in the sign-in page, welcome and about pages.
-
-These also include top-level overrides for CSS and Javascript.
-
-.Application Identity
-[cols="2a,1,3a", options="header"]
-|===
-|Property
-|Value +
-(_default value_)
-|Description
-
-|`isis.viewer.wicket.` +
-`application.about`
-|Apache Isis ™
-|Label used on the about page.
-
-If not specified, then `application.name` is used instead.
-
-|`isis.viewer.wicket.` +
-`application.` +
-`brandLogoHeader`
-|Image URL
-|Either the location of the image file (relative to `src/main/webapp`), or an absolute URL.
-This is rendered on the header panel.
-
-An image with a size of 160x40 works well.
-
-If not specified, the `application.name` is used instead.
-
-
-|`isis.viewer.wicket.` +
-`application.` +
-`brandLogoSignin`
-|Image URL
-|Either the location of the image file (relative to `src/main/webapp`), or an absolute URL.
-This is rendered on the sign-in page.
-
-An image with a size of 400x40 works well.
-
-If not specified, the `application.name` is used instead.
-
-|`isis.viewer.wicket.` +
-`application.css`
-|File name +
-(_`scripts/application.css`_)
-|File to read any custom CSS, relative to `src/main/webapp` directory.
-
-|`isis.viewer.wicket.` +
-`application.js`
-|File name +
-(_`scripts/application.js`_)
-|File to read any custom Javascript, relative to `src/main/webapp` directory.
-
-|`isis.viewer.wicket.` +
-`application.name`
-|Apache Isis ™
-|Identifies the application on the sign-in page (unless a `brandLogoSignin` image is configured) and on top-left in the header (unless a `brandLogoHeader` image is configured).
-
-|`isis.viewer.wicket.` +
-`application.version`
-|(none)
-|The version of the application, eg `1.0`, `1.1`, or something more complex such as `20181115.2011.EST-1862.8d8e1c16`.
-
-If present, then this will be shown in the footer on every page as well as on the about page.
-
-See below for further discussion on this topic.
-
-
-|`isis.viewer.wicket.` +
-`welcome.file`
-|File name +
-(_`welcome.html`_)
-|Location of the HTML file (relative to `src/main/webapp`) whose contents should be displayed on the application's home page.
-
-Note though that if a xref:refguide:applib-ant:HomePage.adoc[@HomePage] action exists, then that will take precedence.
-
-If no welcome file exists, then the value of `welcome.text` is shown as a fallback.
-
-|`isis.viewer.wicket.` +
-`welcome.text`
-|Text
-|To be displayed on the application's home page, used as a fallback if `welcome.file` is not specified.
-
-Note though that if a xref:refguide:applib-ant:HomePage.adoc[@HomePage] action exists, then that will take precedence.
-
-
-|===
-
-
-
-
-=== Application versioning
-
-If the `isis.viewer.wicket.application.version` configuration property is present, then this will be shown in the footer on every page as well as on the about page.
-
-However, maintaining this configuration property manually is likely to be error prone.
-An alternative approach is to configure your build system to generate a version identifier automatically.
-
-For example, the version `20181115.2011.EST-1862.8d8e1c16` consists of four parts:
-
-* the date of the build
-* the time of the build (to the nearest minute)
-* the branch
-* the git shaId
-
-This can be computed using a simple script, for example:
-
-[source,bash]
-----
-DATE=$(date +%Y%m%d.%H%M)
-BRANCH=$(echo $GIT_BRANCH | sed 's|^rel/||g' | sed 's|[.]|_|g' | awk -F/ '{ print $NF }')
-GIT_SHORT_COMMIT=$(echo $GIT_COMMIT | cut -c1-8)
-APPLICATION_VERSION=$DATE.$BRANCH.$GIT_SHORT_COMMIT
-----
-
-where `$GIT_BRANCH` and `$GIT_COMMIT` are provided by the CI server/build environment.
-
-This environment variable can be passed into the (Maven) build using a system property, for example:
-
-[source,bash]
-----
-mvn -DapplicationVersion=$APPLICATION_VERSION clean install
-----
-
-Suppose we now provide a file `application-version.properties` is in the same package as the app manifest file, but in the `src/main/resources` directory:
-
-[source,ini]
-.application-version.properties
-----
-isis.viewer.wicket.application.version=$\{applicationVersion}
-----
-
-then Maven will automatically interpolate the actual revision when this file is copied over to the build (ie `target/classes`) directory.
-
-The last step is for Spring Boot to also load this file.
-One way to do this is using the Spring link:https://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/context/annotation/PropertySource.html[@PropertySource] annotation on the top-level "app manifest":
-
-[source,java]
-----
-@Configuration
-@Import({
- IsisModuleCoreRuntimeServices.class,
- IsisModuleSecurityShiro.class,
- IsisModuleJdoDataNucleus5.class,
- IsisModuleViewerRestfulObjectsJaxrsResteasy4.class,
- IsisModuleViewerWicketViewer.class,
-
- /* ... application-specific modules ... */
-})
-@PropertySource("classpath:application-version.properties") //<1>
-public class AppManifest {
-}
-----
-<1> picks up the additional configuration property.
-
-
-
-
-
-== Sign-in, Sign-up and Remember Me
-
-Configuration properties that influence the behaviour and appearance of the sign-in page.
-
-.Sign-in, Sign-up and Remember Me
-[cols="2a,1,3a", options="header"]
-|===
-|Property
-|Value +
-(_default value_)
-|Description
-
-|`isis.viewer.wicket.` +
-`rememberMe.cookieKey`
-| ascii chars +
-(`_isisWicketRememberMe_`)
-|Cookie key holding the (encrypted) 'rememberMe' user/password.
-There is generally no need to change this.
-
-Valid values as per link:http://stackoverflow.com/a/1969339/56880[this StackOverflow answer].
-
-|`isis.viewer.wicket.` +
-`rememberMe.encryptionKey`
-| any string +
-(in prod, a random UUID each time)
-|Encryption key is used to encrypt the rememberMe user/password.
-
-Apache Isis leverages link:http://wicket.apache.org[Apache Wicket]'s rememberMe support which holds remembered user/passwords in an encrypted cookie.
-
-If a hard-coded and publicly known value were to be used (as was the case prior to `1.13.0`), then it would be possible for rememberMe user/password to be intercepted and decrypted, possibly compromising access.
-This configuration property therefore allows a private key to be specified, baked into the application.
-
-If no value is set then, in production, a random UUID will be used as the encryption key.
-The net effect of this fallback behaviour is that 'rememberMe' will work, but only until the webapp is restarted (after which the end-user will have to log in again.
-In prototype mode, though, a fixed key will still be used; this saves the developer having to login each time.
-
-|`isis.viewer.wicket.` +
-`rememberMe.suppress`
-| `true`,`false` +
-(`_false_`)
-|Whether to suppress "remember me" checkbox on the login page.
-
-Further discussion xref:vw:ROOT:configuration-properties.adoc#sign-in_remember-me[below].
-
-|`isis.viewer.wicket.` +
-`suppressPasswordReset`
-| `true`,`false` +
-(`_false_`)
-|If user registration is enabled, whether to suppress the "password reset" link on the login page.
-
-Further discussion xref:vw:ROOT:configuration-properties.adoc#sign-in_password-reset[below].
-
-|`isis.viewer.wicket.` +
-`suppressSignUp`
-| `true`,`false` +
-(`_false_`)
-|Whether to suppress "sign-up" link.
-
-Note though that user registration services must also be configured.
-
-Further discussion xref:vw:ROOT:configuration-properties.adoc#sign-in_sign-up[below].
-
-
-|===
-
-
-
-=== Remember Me
-
-// TODO: v2: these screenshots could be updated, perhaps now with secman we could use examples from helloworld?
-
-The 'remember me' checkbox on the login page can be suppressed, if required, by setting a configuration flag:
-
-[source,ini]
-----
-isis.viewer.wicket.rememberMe.suppress=true
-----
-
-
-With 'remember me' not suppressed (the default):
-
-image::suppress-remember-me/login-page-default.png[width="300px",link="{imagesdir}/suppress-remember-me/login-page-default.png"]
-
-and with the checkbox suppressed:
-
-image::suppress-remember-me/login-page-suppress-remember-me.png[width="300px",link="{imagesdir}/suppress-remember-me/login-page-suppress-remember-me.png"]
-
-
-
-
-
-
-=== Sign-up
-
-If user registration has been configured, then the Wicket viewer allows the user to sign-up a new account and to reset their password from the login page.
-
-The 'sign up' link can be suppressed, if required, by setting a configuration flag.
-
-[source,ini]
-----
-isis.viewer.wicket.suppressSignUp=true
-----
-
-
-With 'sign up' not suppressed (the default):
-
-image::suppress-sign-up/login-page-default.png[width="300px",link="{imagesdir}/suppress-sign-up/login-page-default.png"]
-
-and with the link suppressed:
-
-image::suppress-sign-up/login-page-suppress-sign-up.png[width="300px",link="{imagesdir}/suppress-sign-up/login-page-suppress-sign-up.png"]
-
-
-
-=== Password Reset
-
-If user registration has been configured, then the Wicket viewer allows the user to sign-up a new account and to reset their password from the login page.
-
-The 'password reset' link can be suppressed, if required, by setting a configuration flag:
-
-[source,ini]
-----
-isis.viewer.wicket.suppressPasswordReset=true
-----
-
-
-With 'password reset' not suppressed (the default):
-
-image::suppress-password-reset/login-page-default.png[width="300px",link="{imagesdir}/suppress-password-reset/login-page-default.png"]
-
-and with the link suppressed:
-
-image::suppress-password-reset/login-page-suppress-password-reset.png[width="300px",link="{imagesdir}/suppress-password-reset/login-page-suppress-password-reset.png"]
-
-
-
-
-
-
-== Header and Footer
-
-Configuration properties that influence the appearance of the header and footer panels.
-
-See also the xref:vw:ROOT:configuration-properties.adoc#bookmarks-and-breadcrumbs[bookmarks and breadcrumbs] and xref:vw:ROOT:configuration-properties.adoc#themes
-[themes] configuration properties, because these also control UI elements that appear on the header/footer panels.
-
-.Header and Footer
-[cols="2a,1,3a", options="header"]
-|===
-|Property
-|Value +
-(_default value_)
-|Description
-
-
-|`isis.viewer.wicket.` +
-`credit.1.image`
-|File path
-|File path to a logo image for the first credited organisation, relative to `src/main/webapp` directory.
-
-For example: +
-`/images/apache-isis/logo-48x48.png`.
-
-Either/both of `name` and `image` must be defined for the credit to be rendered in the footer.
-
-|`isis.viewer.wicket.` +
-`credit.1.name`
-|String
-|Name of the first credited organisation.
-
-For example: "Apache Isis"
-
-Either/both of `name` and `image` must be defined for the credit to be rendered in the footer.
-
-|`isis.viewer.wicket.` +
-`credit.1.url`
-|URL
-|URL to the website of the first credited organisation.
-
-For example: +
-`http://isis.apache.org`.
-
-Optional.
-
-|`isis.viewer.wicket.` +
-`credit.2.image`
-|File path
-|File path to a logo image for the second credited organisation, relative to `src/main/webapp` directory.
-
-Either/both of `name` and `image` must be defined for the credit to be rendered in the footer.
-
-|`isis.viewer.wicket.` +
-`credit.2.name`
-|String
-|Name of the second credited organisation.
-
-Either/both of `name` and `image` must be defined for the credit to be rendered in the footer.
-
-|`isis.viewer.wicket.` +
-`credit.2.url`
-|URL
-|URL to the website of the second credited organisation.
-
-Optional.
-
-|`isis.viewer.wicket.` +
-`credit.3.image`
-|File path
-|File path to a logo image for the third credited organisation, relative to `src/main/webapp` directory.
-
-Either/both of `name` and `image` must be defined for the credit to be rendered in the footer.
-
-|`isis.viewer.wicket.` +
-`credit.3.name`
-|String
-|Name of the third credited organisation.
-
-Either/both of `name` and `image` must be defined for the credit to be rendered in the footer.
-
-|`isis.viewer.wicket.` +
-`credit.3.url`
-|URL
-|URL to the website of the third credited organisation.
-
-Optional.
-
-|`isis.viewer.wicket.showFooter`
-| `true`,`false` +
-(`_true_`)
-| Whether to show the footer at all.
-
-|===
-
-
-
-== Presentation
-
-These configuration properties that effect the overall presentation and appearance of the viewer.
-
-// TODO: v2: we should rename these
-
-[NOTE]
-====
-Some of the properties below use the prefix `isis.viewers.` (rather than the usual `isis.viewer.wicket.`).
-====
-
-.Presentation
-[cols="2a,1,3a", options="header"]
-|===
-|Property
-|Value +
-(default value)
-|Description
-
-
-|`isis.viewers.` +
-`collectionLayout.` +
-`defaultView`
-|`hidden`, `table` +
-(`hidden`)
-|Default for the default view for all (parented) collections if not explicitly specified using xref:refguide:applib-ant:CollectionLayout.adoc#defaultView[`@CollectionLayout#defaultView()`]
-
-By default the framework renders (parented) collections as "hidden", ie collapsed.
-These can be overridden on a case-by-case basis using the xref:refguide:applib-ant:CollectionLayout.adoc#defaultView[`@CollectionLayout#defaultView()`] or the corresponding `<collectionLayout defaultView="...">` element in the `Xxx.layout.xml` layout file.
-
-If the majority of collections should be displayed as "table" form, then it is more convenient to specify the default view globally.
-
-
-|`isis.viewers.` +
-`paged.parented`
-|positive integer (12)
-|Default page size for parented collections (as owned by an object, eg `Customer#getOrders()`)
-
-
-|`isis.viewers.` +
-`paged.standalone`
-|positive integer (25)
-|Default page size for standalone collections (as returned from an action invocation)
-
-
-|`isis.viewers.` +
-`propertyLayout.` +
-`labelPosition`
-|`TOP`, `LEFT` +
-(`LEFT`)
-|Default for label position for all properties if not explicitly specified using xref:refguide:applib-ant:PropertyLayout.adoc#labelPosition[`@PropertyLayout#labelPosition()`]
-
-
-If you want a consistent look-n-feel throughout the app, eg all property labels to the top, then it'd be rather frustrating to have to annotate every property.
-
-If these are not present then Apache Isis will render according to internal defaults.
-At the time of writing, this means labels are to the left for all datatypes except multiline strings.
-
-
-|`isis.viewer.wicket.` +
-`maxTitleLength` +
-`InParentedTables`
-| +ve integer +
-(`_12_`)
-| See further discussion (immediately below).
-
-|`isis.viewer.wicket.` +
-`maxTitleLength` +
-`InStandaloneTables`
-| +ve integer, +
-(`_12_`)
-| See further discussion (immediately below).
-
-|`isis.viewer.wicket.` +
-`maxTitleLengthInTables`
-| +ve integer, +
-(`_12_`)
-| See further discussion (immediately below).
-
-|`isis.viewer.wicket.` +
-`promptStyle`
-|`dialog`,`inline`, +
-`inline_as_if_edit` +
-(`inline`)
-| whether the prompt for editing a domain object property or invoking an action (associated with a property) is shown inline within the property's form, or instead shown in a modal dialog box.
-For actions, `inline_as_if_edit` will suppress the action's button, and instead let the action be invoked as if editing the property.
-The net effect is that being able to "edit" complex properties with multiple parts (eg a date) using a multi-argument editor (this editor, in fact, being the action's argument panel).
-
-The property can be overridden on a property-by-property basis using xref:refguide:applib-ant:PropertyLayout.adoc#promptStyle[`@Property#promptStyle()`]) or xref:refguide:applib-ant:ActionLayout.adoc#promptStyle[`@Action#promptStyle()`]).
-
-Note that `inline_as_if_edit` does not make sense for a configuration property default, and will instead be interpreted as `inline`.
-
-
-|`isis.viewer.wicket.` +
-`dialogMode`
-| `sidebar`,`modal` +
-(`_sidebar_`)
-| Whether an action on a domain object (entity or view model) which prompts with a style of `DIALOG` - as in, `@ActionLayout(promptStyle="DIALOG")` - should be rendered using a sidebar or alternatively in a modal dialog box.
-
-See the discussion on the xref:vw:ROOT:features.adoc#sidebar-vs-modal-dialogs[sidebar vs modal dialogs] feature for further details.
-
-|`isis.viewer.wicket.` +
-`dialogModeForMenu`
-| `sidebar`,`modal` +
-(`_sidebar_`)
-| Whether an action for a domain service should be rendered using a sidebar or alternatively in a modal dialog box.
-
-See the discussion on the xref:vw:ROOT:features.adoc#sidebar-vs-modal-dialogs[sidebar vs modal dialogs] feature for further details.
-
-
-
-|===
-
-
-Objects whose title is overly long can be cumbersome in titles.
-The Wicket viewer has a xref:vw:ROOT:features.adoc#titles-in-tables[mechanism to automatically shorten] the titles of objects specified using `@Title`.
-As an alternative/in addition, the viewer can also be configured to simply truncate titles longer than a certain length.
-
-The properties themselves are:
-
-[source,ini]
-----
-isis.viewer.wicket.maxTitleLengthInStandaloneTables=20
-isis.viewer.wicket.maxTitleLengthInParentedTables=8
-----
-
-If you wish to use the same value in both cases, you can also specify just:
-
-[source,ini]
-----
-isis.viewer.wicket.maxTitleLengthInTables=15
-----
-
-This is used as a fallback if the more specific properties are not provided.
-
-If no properties are provided, then the Wicket viewer defaults to abbreviating titles to a length of `12`.
-
-
-
-
-
-
-
-== Bookmarks and Breadcrumbs
-
-These configuration properties enable or disable the mechanisms for locating previously accessed objects.
-
-.Bookmarks and Breadcrumbs
-[cols="2a,1,3a", options="header"]
-|===
-|Property
-|Value +
-(_default value_)
-|Description
-
-|`isis.viewer.wicket` +
-`whereAmI.` +
-`maxParentChainLength`
-| +ve int +
-(`_64_`)
-| The number of levels to show in the "Where am I" chain.
-
-|`isis.viewer.wicket.` +
-`bookmarkedPages.maxSize`
-| +ve int +
-(`_15_`)
-| number of pages to bookmark
-
-|`isis.viewer.wicket.` +
-`bookmarkedPages.showChooser`
-| +ve int +
-(`_15_`)
-| whether to show the bookmark panel (top-left in the Wicket viewer)
-
-|`isis.viewer.wicket.` +
-`breadcrumbs.showChooser`
-| `true`,`false` +
-(`_true_`)
-| Whether to show chooser for Breadcrumbs (bottom-left footer in the Wicket viewer)
-
-
-
-|===
-
-
-
-
-== Themes
-
-These configuration properties control the switching of themes.
-
-.Themes
-[cols="2a,1,3a", options="header"]
-|===
-|Property
-|Value +
-(default value)
-|Description
-
-|`isis.viewer.wicket.` +
-`themes.enabled`
-| comma separated list ...
-| \... of bootswatch themes. Only applies if `themes.showChooser`==`true`.
-
-See further discussion below.
-
-|`isis.viewer.wicket.` +
-`themes.initial`
-| theme name
-| Which theme to show initially.
-
-See further discussion below.
-
-|`isis.viewer.wicket.` +
-`themes.showChooser`
-| `true`,`false` +
-(`_false_`)
-| Whether to show chooser for Bootstrap themes.
-
-See further discussion below.
-
-|`isis.viewer.wicket.` +
-`themes.default`
-| bootswatch theme name +
-(`_Flatly_`)
-| Which Bootstrap theme to use by default.
-
-
-|===
-
-
-
-The Wicket viewer uses link:http://getbootstrap.com/[Bootstrap] styles and components (courtesy of the https://github.com/l0rdn1kk0n/wicket-bootstrap[Wicket Bootstrap] integration).
-
-By default the viewer uses the "Flatly" theme from http://bootswatch.com[bootswatch.com].
-This can be overridden using the following configuration property:
-
-[source,ini]
-----
-isis.viewer.wicket.themes.initial=Darky
-----
-
-[TIP]
-====
-Set this configuration property to different values for different environments (dev, test, prod) so you can know at a glance which environment you are connected to.
-====
-
-The end-user can also be given the choice of changing the theme:
-
-[source,ini]
-----
-isis.viewer.wicket.themes.showChooser=true
-----
-
-.Example 1
-image::theme-chooser/example-1.png[width="720px",link="{imagesdir}/theme-chooser/example-1.png"]
-
-
-.Example 2:
-image::theme-chooser/example-2.png[width="720px",link="{imagesdir}/theme-chooser/example-2.png"]
-
-
-It is also possible to restrict the themes shown to some subset of those in bootswatch.
-This is done using a further
-property:
-
-[source,ini]
-----
-isis.viewer.wicket.themes.enabled=bootstrap-theme,Cosmo,Flatly,Darkly,Sandstone,United
-----
-
-where the value is the list of themes (from http://bootswatch.com[bootswatch.com]) to be made available.
-
-[TIP]
-====
-You can also develop and install a custom themes (eg to fit your company's look-n-feel/interface guidelines); see the xref:vw:ROOT:extending.adoc#custom-bootstrap-theme[Extending] chapter for further details.
-====
-
-
-
-== Date Formatting & Date Picker
-
-These configuration properties influence the way in which date/times are rendered and can be selected using the date/time pickers.
-
-.Date Formatting & Date Picker
-[cols="2a,1,3a", options="header"]
-|===
-|Property
-|Value +
-(_default value_)
-|Description
-
-
-|`isis.viewer.wicket.` +
-`datePattern`
-| date format +
-(`dd-MM-yyyy`)
-|The `SimpleDateFormat` used to render dates.
-For the date picker (which uses `moment.js` library), this is converted dynamically into the corresponding `moment.js` format.
-
-|`isis.viewer.wicket.` +
-`dateTimePattern`
-| date/time format +
-(`dd-MM-yyyy HH:mm`)
-|The `SimpleDateFormat` used to render date/times.
-For the date picker (which uses `moment.js` library), this is
-converted dynamically into the corresponding `moment.js` format.
-
-|`isis.viewer.wicket.` +
-`datePicker.maxDate`
-| ISO format date +
-(`2100-01-01T00:00:00.000Z`)
-|Specifies a maximum date after which dates may not be specified.
-
-See link:http://eonasdan.github.io/bootstrap-datetimepicker/Options/#maxdate[datetimepicker reference docs] for further details.
-The string must be in ISO date format (see link:https://github.com/moment/moment/issues/1407[here]
-for further details).
-
-|`isis.viewer.wicket.` +
-`datePicker.minDate`
-| ISO format date +
-(`1900-01-01T00:00:00.000Z`)
-|Specifies a minimum date before which dates may not be specified.
-
-See link:http://eonasdan.github.io/bootstrap-datetimepicker/Options/#mindate[datetimepicker reference docs] for further details.
-The string must be in ISO date format (see link:https://github.com/moment/moment/issues/1407[here] for further details).
-
-
-|`isis.viewer.wicket.` +
-`timestampPattern`
-| date/time format +
-(`yyyy-MM-dd HH:mm:ss.SSS`)
-|The `SimpleDateFormat` used to render timestamps.
-
-
-
-
-|===
-
-
-== Debugging
-
-These configuration properties can assist with debugging the behaviour of the Wicket viewer itself.
-
-.Debugging
-[cols="2a,1,3a", options="header"]
-|===
-|Property
-|Value +
-(_default value_)
-|Description
-
-|`isis.viewer.wicket.` +
-`ajaxDebugMode`
-| `true`,`false` +
-(`_false_`)
-| whether the Wicket debug mode should be enabled.
-
-|`isis.viewer.wicket.` +
-`developmentUtilities.enable`
-| `true`,`false` +
-(`_false_`)
-| when running in production mode, whether to show enable the Wicket development utilities anyway.
-From a UI perspective, this will cause the DebugBar to be shown (top-right).
-
-If running in prototyping mode, the development utilities (debug bar) is always enabled.
-This feature is primarily just to help track any memory leakage issues that might be suspected when running in production.
-
-|`isis.viewer.wicket.` +
-`liveReloadUrl`
-| URL
-|Specifies the URL if live reload is set up, eg: +
-`http://localhost:35729/livereload.js?snipver=1`
-// xref:setupguide:intellij:hints-and-tips.adoc#using-gradle-for-livereload[live reload] is set up, eg: +
-
-|`isis.viewer.wicket.` +
-`stripWicketTags`
-| `true`,`false` +
-(`_true_`)
-| Whether to force Wicket tags to be stripped in prototype/development mode.
-
-[NOTE]
-====
-In 1.7.0 and earlier, the behaviour is different; the Apache Isis Wicket viewer will preserve wicket tags when running in Apache Isis' prototype/development mode, but will still strip wicket tags in Apache Isis' server/deployment mode.
-
-We changed the behaviour in 1.8.0 because we found that Internet Explorer can be sensitive to the presence of Wicket tags.
-====
-
-|`isis.viewer.wicket.` +
-`wicketSourcePlugin`
-| `true`,`false` +
-(`_false_`)
-| Whether the WicketSource plugin should be enabled; by default it is not enabled.
-
-[WARNING]
-====
-Enabling this setting can significantly slow down rendering performance of the Wicket viewer.
-====
-
-|===
-
-
-
-
-
-
-
-
-
-== Feature Toggles
-
-These configuration properties are used to enable/disable features that are either on the way to becoming the default behaviour (but can temporarily be disabled) or conversely for features that are to be removed (but can temporarily be left as enabled).
-
-.Feature Toggles
-[cols="2a,1,3a", options="header"]
-|===
-|Property
-|Value +
-(_default value_)
-|Description
-
-|`isis.viewer.wicket.` +
-`whereAmI.enabled`
-| `true`,`false` +
-(`_true_`)
-| To disable the xref:vw:ROOT:features.adoc#where-am-i["Where am I"] feature.
-
-
-|`isis.viewer.wicket.` +
-`disableDependent` +
-`ChoiceAutoSelection`
-| `true`,`false` +
-(`_false_`)
-| For dependent choices, whether to automatically select the first dependent (eg subcategory) when the parameter on which it depends (category) changes.
-
-|`isis.viewer.wicket.` +
-`disableModalDialogs`
-| `true`,`false` +
-(`_false_`)
-|No longer supported.
-
-|`isis.viewer.wicket.` +
-`preventDoubleClick` +
-`ForFormSubmit`
-| `true`,`false` +
-(`_true_`)
-| Whether to disable a form submit button after it has been clicked, to prevent users causing an error if they do a double click.
-
-|`isis.viewer.wicket.` +
-`preventDoubleClick` +
-`ForNoArgAction`
-| `true`,`false` +
-(`_true_`)
-| Whether to disable a no-arg action button after it has been clicked, to prevent users causing an error if they do a double click.
-
-
-|`isis.viewer.wicket.` +
-`redirectEvenIfSameObject`
-| `true`,`false` +
-(`_false_`)
-| By default, an action invocation that returns the same object will result in the page being updated.
-The same is true for property edits.
-
-If this setting is enabled, then the viewer will always render to a new page.
-
-|`isis.viewer.wicket.` +
-`regularCase`
-| `true`,`false` +
-(`_false_`)
-| Ignored for 1.8.0+; in earlier versions forced regular case rather than title case in the UI
-
-|`isis.viewer.wicket.` +
-`replaceDisabledTag`- +
-`WithReadonlyTag`
-| `true`,`false` +
-(`_true_`)
-| Whether to replace 'disabled' tag with 'readonly' (for link:https://www.w3.org/TR/2014/REC-html5-20141028/forms.html#the-readonly-attribute[w3 spec]-compliant browsers such as for Firefox and Chrome 54+) which prevent copy from 'disabled' fields.
-
-|`isis.viewer.wicket.` +
-`useIndicatorForFormSubmit`
-| `true`,`false` +
-(`_true_`)
-| Whether to show an indicator for a form submit button that it has been clicked.
-
-|`isis.viewer.wicket.` +
-`useIndicatorForNoArgAction`
-| `true`,`false` +
-(`_true_`)
-| Whether to show an indicator for a no-arg action button that it has been clicked.
-
-
-|===
-
-
+The xref:refguide:config:about.adoc[Configuration Guide] includes a xref:refguide:config:sections/isis.viewer.wicket.adoc[section] for the Wicket viewer.
+
+WARNING: TODO - v2 - detail on original config properties (not yet reviewed) currently commented out.
+
+//Wicket configuration properties alter the way in which Apache Isis' Wicket viewer renders domain objects.
+//
+//== Loading Configuration Properties
+//
+//Configuration properties are typically stored in `WEB-INF/isis.properties` or in `WEB-INF/viewer_wicket.properties`.
+//
+//To tell Apache Isis that the Wicket viewer is in use (and should therefore search for the `viewer_wicket.properties` file), add the following to `WEB-INF/web.xml`:
+//
+//// TODO: v2: is this still supported? I doubt it.
+//
+//[source, xml]
+//----
+//<context-param>
+// <param-name>isis.viewers</param-name>
+// <param-value>wicket</param-value>
+//</context-param>
+//----
+//
+//Alternatively, because most of these configuration properties tend not to change between environment (development and production), another practice is to load them programmatically from the `AppManifest`:
+//
+//// TODO: v2: any reference to AppManifestAbstract will need updating.
+//
+//[source,java]
+//----
+//public class MyAppAppManifest extends AppManifestAbstract2 {
+//
+// public static final Builder BUILDER = Builder
+// .forModule(new MyApplicationModule())
+// //...
+// .withConfigurationPropertiesFile(
+// MyAppManifest.class, "isis-non-changing.properties") ;
+//
+// ...
+//}
+//----
+//
+//where `isis-non-changing.properties` is on the classpath in the same package as `MyAppAppManifest`.
+//
+//Whichever approach is used, the configuration properties from all config files are merged together.
+//
+//
+//== Application Identity
+//
+//Configuration properties that identify the application, in the sign-in page, welcome and about pages.
+//
+//These also include top-level overrides for CSS and Javascript.
+//
+//.Application Identity
+//[cols="2a,1,3a", options="header"]
+//|===
+//|Property
+//|Value +
+//(_default value_)
+//|Description
+//
+//|`isis.viewer.wicket.` +
+//`application.about`
+//|Apache Isis ™
+//|Label used on the about page.
+//
+//If not specified, then `application.name` is used instead.
+//
+//|`isis.viewer.wicket.` +
+//`application.` +
+//`brandLogoHeader`
+//|Image URL
+//|Either the location of the image file (relative to `src/main/webapp`), or an absolute URL.
+//This is rendered on the header panel.
+//
+//An image with a size of 160x40 works well.
+//
+//If not specified, the `application.name` is used instead.
+//
+//
+//|`isis.viewer.wicket.` +
+//`application.` +
+//`brandLogoSignin`
+//|Image URL
+//|Either the location of the image file (relative to `src/main/webapp`), or an absolute URL.
+//This is rendered on the sign-in page.
+//
+//An image with a size of 400x40 works well.
+//
+//If not specified, the `application.name` is used instead.
+//
+//|`isis.viewer.wicket.` +
+//`application.css`
+//|File name +
+//(_`scripts/application.css`_)
+//|File to read any custom CSS, relative to `src/main/webapp` directory.
+//
+//|`isis.viewer.wicket.` +
+//`application.js`
+//|File name +
+//(_`scripts/application.js`_)
+//|File to read any custom Javascript, relative to `src/main/webapp` directory.
+//
+//|`isis.viewer.wicket.` +
+//`application.name`
+//|Apache Isis ™
+//|Identifies the application on the sign-in page (unless a `brandLogoSignin` image is configured) and on top-left in the header (unless a `brandLogoHeader` image is configured).
+//
+//|`isis.viewer.wicket.` +
+//`application.version`
+//|(none)
+//|The version of the application, eg `1.0`, `1.1`, or something more complex such as `20181115.2011.EST-1862.8d8e1c16`.
+//
+//If present, then this will be shown in the footer on every page as well as on the about page.
+//
+//See below for further discussion on this topic.
+//
+//
+//|`isis.viewer.wicket.` +
+//`welcome.file`
+//|File name +
+//(_`welcome.html`_)
+//|Location of the HTML file (relative to `src/main/webapp`) whose contents should be displayed on the application's home page.
+//
+//Note though that if a xref:refguide:applib-ant:HomePage.adoc[@HomePage] action exists, then that will take precedence.
+//
+//If no welcome file exists, then the value of `welcome.text` is shown as a fallback.
+//
+//|`isis.viewer.wicket.` +
+//`welcome.text`
+//|Text
+//|To be displayed on the application's home page, used as a fallback if `welcome.file` is not specified.
+//
+//Note though that if a xref:refguide:applib-ant:HomePage.adoc[@HomePage] action exists, then that will take precedence.
+//
+//
+//|===
+//
+//
+//
+//
+//=== Application versioning
+//
+//If the `isis.viewer.wicket.application.version` configuration property is present, then this will be shown in the footer on every page as well as on the about page.
+//
+//However, maintaining this configuration property manually is likely to be error prone.
+//An alternative approach is to configure your build system to generate a version identifier automatically.
+//
+//For example, the version `20181115.2011.EST-1862.8d8e1c16` consists of four parts:
+//
+//* the date of the build
+//* the time of the build (to the nearest minute)
+//* the branch
+//* the git shaId
+//
+//This can be computed using a simple script, for example:
+//
+//[source,bash]
+//----
+//DATE=$(date +%Y%m%d.%H%M)
+//BRANCH=$(echo $GIT_BRANCH | sed 's|^rel/||g' | sed 's|[.]|_|g' | awk -F/ '{ print $NF }')
+//GIT_SHORT_COMMIT=$(echo $GIT_COMMIT | cut -c1-8)
+//APPLICATION_VERSION=$DATE.$BRANCH.$GIT_SHORT_COMMIT
+//----
+//
+//where `$GIT_BRANCH` and `$GIT_COMMIT` are provided by the CI server/build environment.
+//
+//This environment variable can be passed into the (Maven) build using a system property, for example:
+//
+//[source,bash]
+//----
+//mvn -DapplicationVersion=$APPLICATION_VERSION clean install
+//----
+//
+//Suppose we now provide a file `application-version.properties` is in the same package as the app manifest file, but in the `src/main/resources` directory:
+//
+//[source,ini]
+//.application-version.properties
+//----
+//isis.viewer.wicket.application.version=$\{applicationVersion}
+//----
+//
+//then Maven will automatically interpolate the actual revision when this file is copied over to the build (ie `target/classes`) directory.
+//
+//The last step is for Spring Boot to also load this file.
+//One way to do this is using the Spring link:https://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/context/annotation/PropertySource.html[@PropertySource] annotation on the top-level "app manifest":
+//
+//[source,java]
+//----
+//@Configuration
+//@Import({
+// IsisModuleCoreRuntimeServices.class,
+// IsisModuleSecurityShiro.class,
+// IsisModuleJdoDataNucleus5.class,
+// IsisModuleViewerRestfulObjectsJaxrsResteasy4.class,
+// IsisModuleViewerWicketViewer.class,
+//
+// /* ... application-specific modules ... */
+//})
+//@PropertySource("classpath:application-version.properties") //<1>
+//public class AppManifest {
+//}
+//----
+//<1> picks up the additional configuration property.
+//
+//
+//
+//
+//
+//== Sign-in, Sign-up and Remember Me
+//
+//Configuration properties that influence the behaviour and appearance of the sign-in page.
+//
+//.Sign-in, Sign-up and Remember Me
+//[cols="2a,1,3a", options="header"]
+//|===
+//|Property
+//|Value +
+//(_default value_)
+//|Description
+//
+//|`isis.viewer.wicket.` +
+//`rememberMe.cookieKey`
+//| ascii chars +
+//(`_isisWicketRememberMe_`)
+//|Cookie key holding the (encrypted) 'rememberMe' user/password.
+//There is generally no need to change this.
+//
+//Valid values as per link:http://stackoverflow.com/a/1969339/56880[this StackOverflow answer].
+//
+//|`isis.viewer.wicket.` +
+//`rememberMe.encryptionKey`
+//| any string +
+//(in prod, a random UUID each time)
+//|Encryption key is used to encrypt the rememberMe user/password.
+//
+//Apache Isis leverages link:http://wicket.apache.org[Apache Wicket]'s rememberMe support which holds remembered user/passwords in an encrypted cookie.
+//
+//If a hard-coded and publicly known value were to be used (as was the case prior to `1.13.0`), then it would be possible for rememberMe user/password to be intercepted and decrypted, possibly compromising access.
+//This configuration property therefore allows a private key to be specified, baked into the application.
+//
+//If no value is set then, in production, a random UUID will be used as the encryption key.
+//The net effect of this fallback behaviour is that 'rememberMe' will work, but only until the webapp is restarted (after which the end-user will have to log in again.
+//In prototype mode, though, a fixed key will still be used; this saves the developer having to login each time.
+//
+//|`isis.viewer.wicket.` +
+//`rememberMe.suppress`
+//| `true`,`false` +
+//(`_false_`)
+//|Whether to suppress "remember me" checkbox on the login page.
+//
+//Further discussion xref:vw:ROOT:configuration-properties.adoc#sign-in_remember-me[below].
+//
+//|`isis.viewer.wicket.` +
+//`suppressPasswordReset`
+//| `true`,`false` +
+//(`_false_`)
+//|If user registration is enabled, whether to suppress the "password reset" link on the login page.
+//
+//Further discussion xref:vw:ROOT:configuration-properties.adoc#sign-in_password-reset[below].
+//
+//|`isis.viewer.wicket.` +
+//`suppressSignUp`
+//| `true`,`false` +
+//(`_false_`)
+//|Whether to suppress "sign-up" link.
+//
+//Note though that user registration services must also be configured.
+//
+//Further discussion xref:vw:ROOT:configuration-properties.adoc#sign-in_sign-up[below].
+//
+//
+//|===
+//
+//
+//
+//=== Remember Me
+//
+//// TODO: v2: these screenshots could be updated, perhaps now with secman we could use examples from helloworld?
+//
+//The 'remember me' checkbox on the login page can be suppressed, if required, by setting a configuration flag:
+//
+//[source,ini]
+//----
+//isis.viewer.wicket.rememberMe.suppress=true
+//----
+//
+//
+//With 'remember me' not suppressed (the default):
+//
+//image::suppress-remember-me/login-page-default.png[width="300px",link="{imagesdir}/suppress-remember-me/login-page-default.png"]
+//
+//and with the checkbox suppressed:
+//
+//image::suppress-remember-me/login-page-suppress-remember-me.png[width="300px",link="{imagesdir}/suppress-remember-me/login-page-suppress-remember-me.png"]
+//
+//
+//
+//
+//
+//
+//=== Sign-up
+//
+//If user registration has been configured, then the Wicket viewer allows the user to sign-up a new account and to reset their password from the login page.
+//
+//The 'sign up' link can be suppressed, if required, by setting a configuration flag.
+//
+//[source,ini]
+//----
+//isis.viewer.wicket.suppressSignUp=true
+//----
+//
+//
+//With 'sign up' not suppressed (the default):
+//
+//image::suppress-sign-up/login-page-default.png[width="300px",link="{imagesdir}/suppress-sign-up/login-page-default.png"]
+//
+//and with the link suppressed:
+//
+//image::suppress-sign-up/login-page-suppress-sign-up.png[width="300px",link="{imagesdir}/suppress-sign-up/login-page-suppress-sign-up.png"]
+//
+//
+//
+//=== Password Reset
+//
+//If user registration has been configured, then the Wicket viewer allows the user to sign-up a new account and to reset their password from the login page.
+//
+//The 'password reset' link can be suppressed, if required, by setting a configuration flag:
+//
+//[source,ini]
+//----
+//isis.viewer.wicket.suppressPasswordReset=true
+//----
+//
+//
+//With 'password reset' not suppressed (the default):
+//
+//image::suppress-password-reset/login-page-default.png[width="300px",link="{imagesdir}/suppress-password-reset/login-page-default.png"]
+//
+//and with the link suppressed:
+//
+//image::suppress-password-reset/login-page-suppress-password-reset.png[width="300px",link="{imagesdir}/suppress-password-reset/login-page-suppress-password-reset.png"]
+//
+//
+//
+//
+//
+//
+//== Header and Footer
+//
+//Configuration properties that influence the appearance of the header and footer panels.
+//
+//See also the xref:vw:ROOT:configuration-properties.adoc#bookmarks-and-breadcrumbs[bookmarks and breadcrumbs] and xref:vw:ROOT:configuration-properties.adoc#themes
+//[themes] configuration properties, because these also control UI elements that appear on the header/footer panels.
+//
+//.Header and Footer
+//[cols="2a,1,3a", options="header"]
+//|===
+//|Property
+//|Value +
+//(_default value_)
+//|Description
+//
+//
+//|`isis.viewer.wicket.` +
+//`credit.1.image`
+//|File path
+//|File path to a logo image for the first credited organisation, relative to `src/main/webapp` directory.
+//
+//For example: +
+//`/images/apache-isis/logo-48x48.png`.
+//
+//Either/both of `name` and `image` must be defined for the credit to be rendered in the footer.
+//
+//|`isis.viewer.wicket.` +
+//`credit.1.name`
+//|String
+//|Name of the first credited organisation.
+//
+//For example: "Apache Isis"
+//
+//Either/both of `name` and `image` must be defined for the credit to be rendered in the footer.
+//
+//|`isis.viewer.wicket.` +
+//`credit.1.url`
+//|URL
+//|URL to the website of the first credited organisation.
+//
+//For example: +
+//`http://isis.apache.org`.
+//
+//Optional.
+//
+//|`isis.viewer.wicket.` +
+//`credit.2.image`
+//|File path
+//|File path to a logo image for the second credited organisation, relative to `src/main/webapp` directory.
+//
+//Either/both of `name` and `image` must be defined for the credit to be rendered in the footer.
+//
+//|`isis.viewer.wicket.` +
+//`credit.2.name`
+//|String
+//|Name of the second credited organisation.
+//
+//Either/both of `name` and `image` must be defined for the credit to be rendered in the footer.
+//
+//|`isis.viewer.wicket.` +
+//`credit.2.url`
+//|URL
+//|URL to the website of the second credited organisation.
+//
+//Optional.
+//
+//|`isis.viewer.wicket.` +
+//`credit.3.image`
+//|File path
+//|File path to a logo image for the third credited organisation, relative to `src/main/webapp` directory.
+//
+//Either/both of `name` and `image` must be defined for the credit to be rendered in the footer.
+//
+//|`isis.viewer.wicket.` +
+//`credit.3.name`
+//|String
+//|Name of the third credited organisation.
+//
+//Either/both of `name` and `image` must be defined for the credit to be rendered in the footer.
+//
+//|`isis.viewer.wicket.` +
+//`credit.3.url`
+//|URL
+//|URL to the website of the third credited organisation.
+//
+//Optional.
+//
+//|`isis.viewer.wicket.showFooter`
+//| `true`,`false` +
+//(`_true_`)
+//| Whether to show the footer at all.
+//
+//|===
+//
+//
+//
+//== Presentation
+//
+//These configuration properties that effect the overall presentation and appearance of the viewer.
+//
+//// TODO: v2: we should rename these
+//
+//[NOTE]
+//====
+//Some of the properties below use the prefix `isis.viewers.` (rather than the usual `isis.viewer.wicket.`).
+//====
+//
+//.Presentation
+//[cols="2a,1,3a", options="header"]
+//|===
+//|Property
+//|Value +
+//(default value)
+//|Description
+//
+//
+//|`isis.viewers.` +
+//`collectionLayout.` +
+//`defaultView`
+//|`hidden`, `table` +
+//(`hidden`)
+//|Default for the default view for all (parented) collections if not explicitly specified using xref:refguide:applib-ant:CollectionLayout.adoc#defaultView[`@CollectionLayout#defaultView()`]
+//
+//By default the framework renders (parented) collections as "hidden", ie collapsed.
+//These can be overridden on a case-by-case basis using the xref:refguide:applib-ant:CollectionLayout.adoc#defaultView[`@CollectionLayout#defaultView()`] or the corresponding `<collectionLayout defaultView="...">` element in the `Xxx.layout.xml` layout file.
+//
+//If the majority of collections should be displayed as "table" form, then it is more convenient to specify the default view globally.
+//
+//
+//|`isis.viewers.` +
+//`paged.parented`
+//|positive integer (12)
+//|Default page size for parented collections (as owned by an object, eg `Customer#getOrders()`)
+//
+//
+//|`isis.viewers.` +
+//`paged.standalone`
+//|positive integer (25)
+//|Default page size for standalone collections (as returned from an action invocation)
+//
+//
+//|`isis.viewers.` +
+//`propertyLayout.` +
+//`labelPosition`
+//|`TOP`, `LEFT` +
+//(`LEFT`)
+//|Default for label position for all properties if not explicitly specified using xref:refguide:applib-ant:PropertyLayout.adoc#labelPosition[`@PropertyLayout#labelPosition()`]
+//
+//
+//If you want a consistent look-n-feel throughout the app, eg all property labels to the top, then it'd be rather frustrating to have to annotate every property.
+//
+//If these are not present then Apache Isis will render according to internal defaults.
+//At the time of writing, this means labels are to the left for all datatypes except multiline strings.
+//
+//
+//|`isis.viewer.wicket.` +
+//`maxTitleLength` +
+//`InParentedTables`
+//| +ve integer +
+//(`_12_`)
+//| See further discussion (immediately below).
+//
+//|`isis.viewer.wicket.` +
+//`maxTitleLength` +
+//`InStandaloneTables`
+//| +ve integer, +
+//(`_12_`)
+//| See further discussion (immediately below).
+//
+//|`isis.viewer.wicket.` +
+//`maxTitleLengthInTables`
+//| +ve integer, +
+//(`_12_`)
+//| See further discussion (immediately below).
+//
+//|`isis.viewer.wicket.` +
+//`promptStyle`
+//|`dialog`,`inline`, +
+//`inline_as_if_edit` +
+//(`inline`)
+//| whether the prompt for editing a domain object property or invoking an action (associated with a property) is shown inline within the property's form, or instead shown in a modal dialog box.
+//For actions, `inline_as_if_edit` will suppress the action's button, and instead let the action be invoked as if editing the property.
+//The net effect is that being able to "edit" complex properties with multiple parts (eg a date) using a multi-argument editor (this editor, in fact, being the action's argument panel).
+//
+//The property can be overridden on a property-by-property basis using xref:refguide:applib-ant:PropertyLayout.adoc#promptStyle[`@Property#promptStyle()`]) or xref:refguide:applib-ant:ActionLayout.adoc#promptStyle[`@Action#promptStyle()`]).
+//
+//Note that `inline_as_if_edit` does not make sense for a configuration property default, and will instead be interpreted as `inline`.
+//
+//
+//|`isis.viewer.wicket.` +
+//`dialogMode`
+//| `sidebar`,`modal` +
+//(`_sidebar_`)
+//| Whether an action on a domain object (entity or view model) which prompts with a style of `DIALOG` - as in, `@ActionLayout(promptStyle="DIALOG")` - should be rendered using a sidebar or alternatively in a modal dialog box.
+//
+//See the discussion on the xref:vw:ROOT:features.adoc#sidebar-vs-modal-dialogs[sidebar vs modal dialogs] feature for further details.
+//
+//|`isis.viewer.wicket.` +
+//`dialogModeForMenu`
+//| `sidebar`,`modal` +
+//(`_sidebar_`)
+//| Whether an action for a domain service should be rendered using a sidebar or alternatively in a modal dialog box.
+//
+//See the discussion on the xref:vw:ROOT:features.adoc#sidebar-vs-modal-dialogs[sidebar vs modal dialogs] feature for further details.
+//
+//
+//
+//|===
+//
+//
+//Objects whose title is overly long can be cumbersome in titles.
+//The Wicket viewer has a xref:vw:ROOT:features.adoc#titles-in-tables[mechanism to automatically shorten] the titles of objects specified using `@Title`.
+//As an alternative/in addition, the viewer can also be configured to simply truncate titles longer than a certain length.
+//
+//The properties themselves are:
+//
+//[source,ini]
+//----
+//isis.viewer.wicket.maxTitleLengthInStandaloneTables=20
+//isis.viewer.wicket.maxTitleLengthInParentedTables=8
+//----
+//
+//If you wish to use the same value in both cases, you can also specify just:
+//
+//[source,ini]
+//----
+//isis.viewer.wicket.maxTitleLengthInTables=15
+//----
+//
+//This is used as a fallback if the more specific properties are not provided.
+//
+//If no properties are provided, then the Wicket viewer defaults to abbreviating titles to a length of `12`.
+//
+//
+//
+//
+//
+//
+//
+//== Bookmarks and Breadcrumbs
+//
+//These configuration properties enable or disable the mechanisms for locating previously accessed objects.
+//
+//.Bookmarks and Breadcrumbs
+//[cols="2a,1,3a", options="header"]
+//|===
+//|Property
+//|Value +
+//(_default value_)
+//|Description
+//
+//|`isis.viewer.wicket` +
+//`whereAmI.` +
+//`maxParentChainLength`
+//| +ve int +
+//(`_64_`)
+//| The number of levels to show in the "Where am I" chain.
+//
+//|`isis.viewer.wicket.` +
+//`bookmarkedPages.maxSize`
+//| +ve int +
+//(`_15_`)
+//| number of pages to bookmark
+//
+//|`isis.viewer.wicket.` +
+//`bookmarkedPages.showChooser`
+//| +ve int +
+//(`_15_`)
+//| whether to show the bookmark panel (top-left in the Wicket viewer)
+//
+//|`isis.viewer.wicket.` +
+//`breadcrumbs.showChooser`
+//| `true`,`false` +
+//(`_true_`)
+//| Whether to show chooser for Breadcrumbs (bottom-left footer in the Wicket viewer)
+//
+//
+//
+//|===
+//
+//
+//
+//
+//== Themes
+//
+//These configuration properties control the switching of themes.
+//
+//.Themes
+//[cols="2a,1,3a", options="header"]
+//|===
+//|Property
+//|Value +
+//(default value)
+//|Description
+//
+//|`isis.viewer.wicket.` +
+//`themes.enabled`
+//| comma separated list ...
+//| \... of bootswatch themes. Only applies if `themes.showChooser`==`true`.
+//
+//See further discussion below.
+//
+//|`isis.viewer.wicket.` +
+//`themes.initial`
+//| theme name
+//| Which theme to show initially.
+//
+//See further discussion below.
+//
+//|`isis.viewer.wicket.` +
+//`themes.showChooser`
+//| `true`,`false` +
+//(`_false_`)
+//| Whether to show chooser for Bootstrap themes.
+//
+//See further discussion below.
+//
+//|`isis.viewer.wicket.` +
+//`themes.default`
+//| bootswatch theme name +
+//(`_Flatly_`)
+//| Which Bootstrap theme to use by default.
+//
+//
+//|===
+//
+//
+//
+//The Wicket viewer uses link:http://getbootstrap.com/[Bootstrap] styles and components (courtesy of the https://github.com/l0rdn1kk0n/wicket-bootstrap[Wicket Bootstrap] integration).
+//
+//By default the viewer uses the "Flatly" theme from http://bootswatch.com[bootswatch.com].
+//This can be overridden using the following configuration property:
+//
+//[source,ini]
+//----
+//isis.viewer.wicket.themes.initial=Darky
+//----
+//
+//[TIP]
+//====
+//Set this configuration property to different values for different environments (dev, test, prod) so you can know at a glance which environment you are connected to.
+//====
+//
+//The end-user can also be given the choice of changing the theme:
+//
+//[source,ini]
+//----
+//isis.viewer.wicket.themes.showChooser=true
+//----
+//
+//.Example 1
+//image::theme-chooser/example-1.png[width="720px",link="{imagesdir}/theme-chooser/example-1.png"]
+//
+//
+//.Example 2:
+//image::theme-chooser/example-2.png[width="720px",link="{imagesdir}/theme-chooser/example-2.png"]
+//
+//
+//It is also possible to restrict the themes shown to some subset of those in bootswatch.
+//This is done using a further
+//property:
+//
+//[source,ini]
+//----
+//isis.viewer.wicket.themes.enabled=bootstrap-theme,Cosmo,Flatly,Darkly,Sandstone,United
+//----
+//
+//where the value is the list of themes (from http://bootswatch.com[bootswatch.com]) to be made available.
+//
+//[TIP]
+//====
+//You can also develop and install a custom themes (eg to fit your company's look-n-feel/interface guidelines); see the xref:vw:ROOT:extending.adoc#custom-bootstrap-theme[Extending] chapter for further details.
+//====
+//
+//
+//
+//== Date Formatting & Date Picker
+//
+//These configuration properties influence the way in which date/times are rendered and can be selected using the date/time pickers.
+//
+//.Date Formatting & Date Picker
+//[cols="2a,1,3a", options="header"]
+//|===
+//|Property
+//|Value +
+//(_default value_)
+//|Description
+//
+//
+//|`isis.viewer.wicket.` +
+//`datePattern`
+//| date format +
+//(`dd-MM-yyyy`)
+//|The `SimpleDateFormat` used to render dates.
+//For the date picker (which uses `moment.js` library), this is converted dynamically into the corresponding `moment.js` format.
+//
+//|`isis.viewer.wicket.` +
+//`dateTimePattern`
+//| date/time format +
+//(`dd-MM-yyyy HH:mm`)
+//|The `SimpleDateFormat` used to render date/times.
+//For the date picker (which uses `moment.js` library), this is
+//converted dynamically into the corresponding `moment.js` format.
+//
+//|`isis.viewer.wicket.` +
+//`datePicker.maxDate`
+//| ISO format date +
+//(`2100-01-01T00:00:00.000Z`)
+//|Specifies a maximum date after which dates may not be specified.
+//
+//See link:http://eonasdan.github.io/bootstrap-datetimepicker/Options/#maxdate[datetimepicker reference docs] for further details.
+//The string must be in ISO date format (see link:https://github.com/moment/moment/issues/1407[here]
+//for further details).
+//
+//|`isis.viewer.wicket.` +
+//`datePicker.minDate`
+//| ISO format date +
+//(`1900-01-01T00:00:00.000Z`)
+//|Specifies a minimum date before which dates may not be specified.
+//
+//See link:http://eonasdan.github.io/bootstrap-datetimepicker/Options/#mindate[datetimepicker reference docs] for further details.
+//The string must be in ISO date format (see link:https://github.com/moment/moment/issues/1407[here] for further details).
+//
+//
+//|`isis.viewer.wicket.` +
+//`timestampPattern`
+//| date/time format +
+//(`yyyy-MM-dd HH:mm:ss.SSS`)
+//|The `SimpleDateFormat` used to render timestamps.
+//
+//
+//
+//
+//|===
+//
+//
+//== Debugging
+//
+//These configuration properties can assist with debugging the behaviour of the Wicket viewer itself.
+//
+//.Debugging
+//[cols="2a,1,3a", options="header"]
+//|===
+//|Property
+//|Value +
+//(_default value_)
+//|Description
+//
+//|`isis.viewer.wicket.` +
+//`ajaxDebugMode`
+//| `true`,`false` +
+//(`_false_`)
+//| whether the Wicket debug mode should be enabled.
+//
+//|`isis.viewer.wicket.` +
+//`developmentUtilities.enable`
+//| `true`,`false` +
+//(`_false_`)
+//| when running in production mode, whether to show enable the Wicket development utilities anyway.
+//From a UI perspective, this will cause the DebugBar to be shown (top-right).
+//
+//If running in prototyping mode, the development utilities (debug bar) is always enabled.
+//This feature is primarily just to help track any memory leakage issues that might be suspected when running in production.
+//
+//|`isis.viewer.wicket.` +
+//`liveReloadUrl`
+//| URL
+//|Specifies the URL if live reload is set up, eg: +
+//`http://localhost:35729/livereload.js?snipver=1`
+//// xref:setupguide:intellij:hints-and-tips.adoc#using-gradle-for-livereload[live reload] is set up, eg: +
+//
+//|`isis.viewer.wicket.` +
+//`stripWicketTags`
+//| `true`,`false` +
+//(`_true_`)
+//| Whether to force Wicket tags to be stripped in prototype/development mode.
+//
+//[NOTE]
+//====
+//In 1.7.0 and earlier, the behaviour is different; the Apache Isis Wicket viewer will preserve wicket tags when running in Apache Isis' prototype/development mode, but will still strip wicket tags in Apache Isis' server/deployment mode.
+//
+//We changed the behaviour in 1.8.0 because we found that Internet Explorer can be sensitive to the presence of Wicket tags.
+//====
+//
+//|`isis.viewer.wicket.` +
+//`wicketSourcePlugin`
+//| `true`,`false` +
+//(`_false_`)
+//| Whether the WicketSource plugin should be enabled; by default it is not enabled.
+//
+//[WARNING]
+//====
+//Enabling this setting can significantly slow down rendering performance of the Wicket viewer.
+//====
+//
+//|===
+//
+//
+//
+//
+//
+//
+//
+//
+//
+//== Feature Toggles
+//
+//These configuration properties are used to enable/disable features that are either on the way to becoming the default behaviour (but can temporarily be disabled) or conversely for features that are to be removed (but can temporarily be left as enabled).
+//
+//.Feature Toggles
+//[cols="2a,1,3a", options="header"]
+//|===
+//|Property
+//|Value +
+//(_default value_)
+//|Description
+//
+//|`isis.viewer.wicket.` +
+//`whereAmI.enabled`
+//| `true`,`false` +
+//(`_true_`)
+//| To disable the xref:vw:ROOT:features.adoc#where-am-i["Where am I"] feature.
+//
+//
+//|`isis.viewer.wicket.` +
+//`disableDependent` +
+//`ChoiceAutoSelection`
+//| `true`,`false` +
+//(`_false_`)
+//| For dependent choices, whether to automatically select the first dependent (eg subcategory) when the parameter on which it depends (category) changes.
+//
+//|`isis.viewer.wicket.` +
+//`disableModalDialogs`
+//| `true`,`false` +
+//(`_false_`)
+//|No longer supported.
+//
+//|`isis.viewer.wicket.` +
+//`preventDoubleClick` +
+//`ForFormSubmit`
+//| `true`,`false` +
+//(`_true_`)
+//| Whether to disable a form submit button after it has been clicked, to prevent users causing an error if they do a double click.
+//
+//|`isis.viewer.wicket.` +
+//`preventDoubleClick` +
+//`ForNoArgAction`
+//| `true`,`false` +
+//(`_true_`)
+//| Whether to disable a no-arg action button after it has been clicked, to prevent users causing an error if they do a double click.
+//
+//
+//|`isis.viewer.wicket.` +
+//`redirectEvenIfSameObject`
+//| `true`,`false` +
+//(`_false_`)
+//| By default, an action invocation that returns the same object will result in the page being updated.
+//The same is true for property edits.
+//
+//If this setting is enabled, then the viewer will always render to a new page.
+//
+//|`isis.viewer.wicket.` +
+//`regularCase`
+//| `true`,`false` +
+//(`_false_`)
+//| Ignored for 1.8.0+; in earlier versions forced regular case rather than title case in the UI
+//
+//|`isis.viewer.wicket.` +
+//`replaceDisabledTag`- +
+//`WithReadonlyTag`
+//| `true`,`false` +
+//(`_true_`)
+//| Whether to replace 'disabled' tag with 'readonly' (for link:https://www.w3.org/TR/2014/REC-html5-20141028/forms.html#the-readonly-attribute[w3 spec]-compliant browsers such as for Firefox and Chrome 54+) which prevent copy from 'disabled' fields.
+//
+//|`isis.viewer.wicket.` +
+//`useIndicatorForFormSubmit`
+//| `true`,`false` +
+//(`_true_`)
+//| Whether to show an indicator for a form submit button that it has been clicked.
+//
+//|`isis.viewer.wicket.` +
+//`useIndicatorForNoArgAction`
+//| `true`,`false` +
+//(`_true_`)
+//| Whether to show an indicator for a no-arg action button that it has been clicked.
+//
+//
+//|===
+//
+//
diff --git a/viewers/wicket/adoc/modules/ROOT/pages/features/where-am-i.adoc b/viewers/wicket/adoc/modules/ROOT/pages/features/where-am-i.adoc
index c9126b7..bd81194 100644
--- a/viewers/wicket/adoc/modules/ROOT/pages/features/where-am-i.adoc
+++ b/viewers/wicket/adoc/modules/ROOT/pages/features/where-am-i.adoc
@@ -87,20 +87,22 @@ Horizontally arranged text links separated by the 'greater than' symbol (>) are
The navigable tree-structure, as provided by the 'Where am I' feature, is declared at compile-time (predefined by the programmer), whereas related features (xref:vw:ROOT:features.adoc#recent-pages[Recent Pages] and xref:vw:ROOT:features.adoc#bookmarked-pages[Bookmarked Pages]) are populated at runtime only after user interaction.
-== Configuration
-
-By default, the 'Where am I' feature will show a maximum of 64 links.
-This can be overridden using a property (in `isis.properties`), for example:
-
-[source,ini]
-----
-isis.viewer.wicket.whereAmI.maxParentChainLength=20
-----
-
-To disable the 'Where am I' feature, override the default (=enabled) by using a property (in `isis.properties`):
-
-[source,ini]
-----
-isis.viewer.wicket.whereAmI.enabled=false
-----
-
+//== Configuration
+//
+//By default, the 'Where am I' feature will show a maximum of 64 links.
+//This can be overridden using the
+//xref:refguide:config:sections/isis.viewer.wicket.adoc
+//configuration property, for example:
+//
+//[source,ini]
+//----
+//isis.viewer.wicket.whereAmI.maxParentChainLength=20
+//----
+//
+//To disable the 'Where am I' feature, override the default (=enabled) by using a property (in `isis.properties`):
+//
+//[source,ini]
+//----
+//isis.viewer.wicket.whereAmI.enabled=false
+//----
+//