You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2017/08/01 12:43:57 UTC
[2/6] isis git commit: ISIS-1674: updates documentation to reference
helloworld archetype where necessary.
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_ini-realm.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_ini-realm.adoc b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_ini-realm.adoc
index d72defc..b7178af 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_ini-realm.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugsec/_ugsec_shiro-realm-implementations_ini-realm.adoc
@@ -7,13 +7,16 @@
Probably the simplest realm to use is Shiro's built-in `IniRealm`, which reads from the (same) `WEB-INF/shiro.ini` file.
-This is suitable for prototyping, but isn't intended for production use, if only because user/password credentials are stored in plain text. Nevertheless, it's a good starting point. The app generated by the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] is configured to use this realm.
+This is suitable for prototyping, but isn't intended for production use, if only because user/password credentials are stored in plain text.
+Nevertheless, it's a good starting point.
+The app generated by both the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_helloworld-archetype[HelloWorld] and xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp] archetypes are configured to use this realm.
The diagram below shows the Isis and components involved:
image::{_imagesdir}security/security-apis-impl/configure-shiro-to-use-ini-realm.PNG[width="600px"]
-The realm is responsible for validating the user credentials, and then creates a Shiro link:http://shiro.apache.org/static/latest/apidocs/org/apache/shiro/subject/Subject.html[`Subject`] which represents the user (for the current request). Apache Isis `Authenticator` component then interacts with the `Subject` in order to check permissions.
+The realm is responsible for validating the user credentials, and then creates a Shiro link:http://shiro.apache.org/static/latest/apidocs/org/apache/shiro/subject/Subject.html[`Subject`] which represents the user (for the current request).
+Apache Isis `Authenticator` component then interacts with the `Subject` in order to check permissions.
@@ -29,7 +32,8 @@ securityManager.realms = $iniRealm
(Unlike other realms) there is no need to "define" `$iniRealm`; it is automatically available to us.
-Specifying `$iniRealm` means that the usernames/passwords, roles and permissions are read from the `shiro.ini` file itself. Specifically:
+Specifying `$iniRealm` means that the usernames/passwords, roles and permissions are read from the `shiro.ini` file itself.
+Specifically:
* the users/passwords and their roles from the `[users]` sections;
* the roles are mapped to permissions in the `[roles]` section.
@@ -113,7 +117,8 @@ The format of the permissions string is configurable in Shiro, and Apache Isis u
== Externalized IniRealm
-There's no requirement for all users/roles to be defined in the `shiro.ini` file. Instead, a realm can be defined that loads its users/roles from some other resource.
+There's no requirement for all users/roles to be defined in the `shiro.ini` file.
+Instead, a realm can be defined that loads its users/roles from some other resource.
For example:
@@ -125,9 +130,11 @@ realm1.resourcePath=classpath:webapp/realm1.ini # <2>
<1> happens to (coincidentally) be the link:http://shiro.apache.org/static/latest/apidocs/org/apache/shiro/realm/text/IniRealm.html[same implementation] as Shiro's built-in $iniRealm
<2> in this case load the users/roles from the `src/main/resources/webapp/realm1.ini` file.
-Note that a URL could be provided as the `resourcePath`, so a centralized config file could be used. Even so, the
+Note that a URL could be provided as the `resourcePath`, so a centralized config file could be used.
+Even so, the
[NOTE]
====
-If configured this way then the `[users]` and `[roles]` sections of `shiro.ini` become unused. Instead, the corresponding sections from for `realm1.ini` are used instead.
+If configured this way then the `[users]` and `[roles]` sections of `shiro.ini` become unused.
+Instead, the corresponding sections from for `realm1.ini` are used instead.
====
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugsec/ugsec.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugsec/ugsec.adoc b/adocs/documentation/src/main/asciidoc/guides/ugsec/ugsec.adoc
index 0edf472..265eba5 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugsec/ugsec.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugsec/ugsec.adoc
@@ -46,19 +46,27 @@ The remaining guides are:
Apache Isis has built-in support for authentication and authorization:
-* By "authentication" we mean logging into the application using some credentials, typically a username and password. Authentication also means looking up the set of roles to which a user belongs.
+* By "authentication" we mean logging into the application using some credentials, typically a username and password.
+Authentication also means looking up the set of roles to which a user belongs.
* By "authorization" we mean permissions: granting roles to have access to features (object member) of the app.
-Isis has two levels of permissions. _Read_ permission means that the user can view the object member; it will be rendered in the UI. An action with only read permission will be shown disabled ("greyed out". _Write_ permission means that the object member can be changed. For actions this means that they can be invoked.
+Isis has two levels of permissions.
+_Read_ permission means that the user can view the object member; it will be rendered in the UI. An action with only read permission will be shown disabled ("greyed out".
+_Write_ permission means that the object member can be changed. For actions this means that they can be invoked.
-Isis provides an API for both authentication and authorization, and provides an implementation that integrates with link:http://shiro.apache.org[Apache Shiro]. Shiro in turn uses the concept of a _realm_ as a source for both authentication and optionally authorization.
+Isis provides an API for both authentication and authorization, and provides an implementation that integrates with link:http://shiro.apache.org[Apache Shiro].
+Shiro in turn uses the concept of a _realm_ as a source for both authentication and optionally authorization.
-Shiro ships with a simple text-based realm -- the `IniRealm` -- which reads users (and password), user roles and role permissions from the `WEB-INF/shiro.ini` file. The xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] is configured to use this realm.
+Shiro ships with a simple text-based realm -- the `IniRealm` -- which reads users (and password), user roles and role permissions from the `WEB-INF/shiro.ini` file.
+The xref:../ugfun/ugfun.adoc#_ugfun_getting-started_helloworld-archetype[HelloWorld] and xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp] archetypes are both configured to use this realm.
-Shiro also ships with an implementation of an LDAP-based realm; LDAP is often used to manage user/passwords and corresponding user groups. Apache Isis in turn extends this with its `IsisLdapRealm`, which provides more flexibility for both group/role and role/permissions management.
+Shiro also ships with an implementation of an LDAP-based realm; LDAP is often used to manage user/passwords and corresponding user groups.
+Apache Isis in turn extends this with its `IsisLdapRealm`, which provides more flexibility for both group/role and role/permissions management.
-In addition, the (non-ASF) link:http://www.isisaddons.org[Isis Addons] provides the http://github.com/isisaddons/isis-module-security[Isis addons' security] module, which also provides an implementation of the Shiro `Realm` API. However, the security module also represents users, roles and permissions as domain objects, allowing them to be administered through Apache Isis itself. Moreover, the security module can optionally delegate password management to a subsidiary (delegate) realm (usually LDAP as discussed above).
+In addition, the (non-ASF) link:http://www.isisaddons.org[Isis Addons] provides the http://github.com/isisaddons/isis-module-security[Isis addons' security] module, which also provides an implementation of the Shiro `Realm` API.
+However, the security module also represents users, roles and permissions as domain objects, allowing them to be administered through Apache Isis itself.
+Moreover, the security module can optionally delegate password management to a subsidiary (delegate) realm (usually LDAP as discussed above).
In addition to Apache Isis' Shiro-based implementation of its authentication and authorization APIs, Isis also provides a "bypass" implementation, useful for quick-n-dirty prototyping when you want to in effect disable (bypass) security completely.
@@ -69,14 +77,12 @@ A further aspect of security is auditing: recording what data was modified by wh
Apache Isis provides the xref:../rgsvc/rgsvc.adoc#_rgsvc_application-layer-api_InteractionContext[`InteractionContext`]
can be used to track the actions being invoked, and the xref:../rgsvc/rgsvc.adoc#_rgsvc_persistence-layer-spi_AuditerService[`AuditerService`]
-captures what data was modified as a result (auditing). When ``Interaction``s are persisted (eg by way of
-(non-ASF) http://github.com/isisaddons/isis-module-publishmq[Isis addons' publishmq] module) this provides excellent
-traceability. The (non-ASF) http://github.com/isisaddons/isis-module-audit[Isis addons' audit] module provides an
-implementation of the `AuditerService`.
-
-For earlier versions of the framework the
-xref:../rgsvc/rgsvc.adoc#_rgsvc_application-layer-spi_CommandService[`CommandService`] can be used to capture actions, while the (deprecated)
-xref:../rgsvc/rgsvc.adoc#_rgsvc_persistence-layer-spi_AuditingService[`AuditingService`] used to capture data modified.
+captures what data was modified as a result (auditing).
+When ``Interaction``s are persisted (eg by way of (non-ASF) http://github.com/isisaddons/isis-module-publishmq[Isis addons' publishmq] module) this provides excellent
+traceability.
+The (non-ASF) http://github.com/isisaddons/isis-module-audit[Isis addons' audit] module provides an implementation of the `AuditerService`.
+
+For earlier versions of the framework the xref:../rgsvc/rgsvc.adoc#_rgsvc_application-layer-spi_CommandService[`CommandService`] can be used to capture actions, while the (deprecated) xref:../rgsvc/rgsvc.adoc#_rgsvc_persistence-layer-spi_AuditingService[`AuditingService`] used to capture data modified.
====
@@ -85,11 +91,8 @@ include::_ugsec_configuring-isis-to-use-shiro.adoc[leveloffset=+1]
include::_ugsec_shiro-realm-implementations.adoc[leveloffset=+1]
-
-
include::_ugsec_shiro-isis-enhanced-wildcard-permission.adoc[leveloffset=+1]
-
include::_ugsec_hints-and-tips.adoc[leveloffset=+1]
include::_ugsec_api-for-applications.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_bdd-spec-support_maven-configuration.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_bdd-spec-support_maven-configuration.adoc b/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_bdd-spec-support_maven-configuration.adoc
index 7febe87..891d210 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_bdd-spec-support_maven-configuration.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_bdd-spec-support_maven-configuration.adoc
@@ -7,7 +7,8 @@
-Apache Isis' BDD spec support is automatically configured if you use the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]. To set it up manually, update the `pom.xml` of your domain object model module:
+Apache Isis' BDD spec support is automatically configured if you use the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
+To set it up manually, update the `pom.xml` of your domain object model module:
[source,xml]
----
@@ -47,8 +48,13 @@ We also recommend that you configure the `maven-surefire-plugin` to pick up the
</plugin>
----
+[NOTE]
+====
+As of 1.14.0, this configuration has been replaced to use mavenmixins.
+====
-You may also find it more convenient to place the `.feature` files in `src/test/java`, rather than `src/test/resources`. If you wish to do this, then your integtest module's `pom.xml` must contain:
+You may also find it more convenient to place the `.feature` files in `src/test/java`, rather than `src/test/resources`.
+If you wish to do this, then your integtest module's `pom.xml` must contain:
[source,xml]
----
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_bdd-spec-support_writing-a-bdd-spec.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_bdd-spec-support_writing-a-bdd-spec.adoc b/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_bdd-spec-support_writing-a-bdd-spec.adoc
index 6e5ffff..7faca21 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_bdd-spec-support_writing-a-bdd-spec.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_bdd-spec-support_writing-a-bdd-spec.adoc
@@ -11,11 +11,13 @@ BDD specifications contain:
* a `XxxSpec.feature` file, describing the feature and the scenarios (given/when/then)s that constitute its acceptance criteria
-* a `RunSpecs.java` class file to run the specification (all boilerplate). This will run all `.feature` files in the same package or subpackages.
+* a `RunSpecs.java` class file to run the specification (all boilerplate).
+This will run all `.feature` files in the same package or subpackages.
* one or several `XxxGlue` constituting the step definitions to be matched against. +
+
-The "glue" (step definitions) are intended to be reused across features. We therefore recommend that they reside in a separate package, and are organized by the entity type upon which they act. +
+The "glue" (step definitions) are intended to be reused across features.
+We therefore recommend that they reside in a separate package, and are organized by the entity type upon which they act. +
+
For example, given a feature that involves `Customer` and `Order`, have the step definitions pertaining to `Customer` reside in `CustomerGlue`, and the step definitions pertaining to `Order` reside in `OrderGlue`. +
+
@@ -38,18 +40,25 @@ Feature: List and Create New Simple Objects
Then there are 4 simple objects
----
-The `@SimpleObjectsFixture` is a custom tag we've specified to indicate the prerequisite fixtures to be loaded; more on this in a moment. The `@integration` tag, meanwhile, says that this feature should be run with integration-level scope.
+The `@SimpleObjectsFixture` is a custom tag we've specified to indicate the prerequisite fixtures to be loaded; more on this in a moment.
+The `@integration` tag, meanwhile, says that this feature should be run with integration-level scope.
[NOTE]
====
-Although BDD specs are most commonly used for end-to-end tests (ie at the same scope as an integration test), the two concerns (expressability of a test to a business person vs granularity of the test) should not be conflated. There are a couple of http://silkandspinach.net/2013/01/18/a-testing-strategy/[good] blog http://claysnow.co.uk/the-testing-iceberg/[posts] discussing http://claysnow.co.uk/living-documentation-can-be-readable-and-fast/[this]. The basic idea is to avoid the overhead of a heavy-duty integration test if possible.
+Although BDD specs are most commonly used for end-to-end tests (ie at the same scope as an integration test), the two concerns (expressability of a test to a business person vs granularity of the test) should not be conflated.
+There are a couple of http://silkandspinach.net/2013/01/18/a-testing-strategy/[good] blog http://claysnow.co.uk/the-testing-iceberg/[posts] discussing http://claysnow.co.uk/living-documentation-can-be-readable-and-fast/[this].
+The basic idea is to avoid the overhead of a heavy-duty integration test if possible.
-Apache Isis does also support running BDD specs in unit test mode; by annotating the scenario with the `@unit` (rather than `@integration` tag). When running under unit-level scope, the Apache Isis system is _not_ instantiated. Instead, the `ScenarioExecution` class returns JMock mocks (except for the `WrapperFactory`, if configured).
+Apache Isis does also support running BDD specs in unit test mode; by annotating the scenario with the `@unit` (rather than `@integration` tag).
+When running under unit-level scope, the Apache Isis system is _not_ instantiated.
+Instead, the `ScenarioExecution` class returns JMock mocks (except for the `WrapperFactory`, if configured).
-To support unit testing scope Apache Isis provides the `InMemoryDB` class; a glorified hashmap of "persisted" objects. Use of this utility class is optional.
+To support unit testing scope Apache Isis provides the `InMemoryDB` class; a glorified hashmap of "persisted" objects.
+Use of this utility class is optional.
-Writing a BDD spec that supports both modes of operation therefore takes more effort and we expect most users interested in BDD will use integration-testing scope; for these reasons we have chosen _not_ to include unit-testing support in the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]. For those who do require faster-executing test suite, it's worthwhile knowing that Apache Isis can support this.
+Writing a BDD spec that supports both modes of operation therefore takes more effort and we expect most users interested in BDD will use integration-testing scope; for these reasons we have chosen _not_ to include unit-testing support in the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
+For those who do require faster-executing test suite, it's worthwhile knowing that Apache Isis can support this.
====
@@ -109,7 +118,8 @@ public class CatalogOfFixturesGlue extends CukeGlueAbstract {
Note that this is annotated with a tag (`@SimpleObjectsFixture`) so that the correct fixture runs. (We might have a whole variety of these).
-The step definitions pertaining to `SimpleObject` domain entity then reside in the https://github.com/apache/isis/blob/07fe61ef3fb029ae36427f60da2afeeb931e4f88/example/application/simpleapp/integtests/src/test/java/domainapp/integtests/specglue/modules/simple/SimpleObjectGlue.java#L31[`SimpleObjectGlue`] class. This is where the heavy lifting gets done:
+The step definitions pertaining to `SimpleObject` domain entity then reside in the https://github.com/apache/isis/blob/07fe61ef3fb029ae36427f60da2afeeb931e4f88/example/application/simpleapp/integtests/src/test/java/domainapp/integtests/specglue/modules/simple/SimpleObjectGlue.java#L31[`SimpleObjectGlue`] class.
+This is where the heavy lifting gets done:
[source,java]
----
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_fixture-scripts_api-and-usage.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_fixture-scripts_api-and-usage.adoc b/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_fixture-scripts_api-and-usage.adoc
index 9170fe9..4697e88 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_fixture-scripts_api-and-usage.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_fixture-scripts_api-and-usage.adoc
@@ -9,7 +9,8 @@ There are two parts to using fixture scripts: the `FixtureScripts` domain servic
* The role of the `FixtureScripts` domain service is to locate all fixture scripts from the classpath and to let them be invoked, either from an integration test/BDD spec or from the UI of your Isis app.
-* The role of `FixtureScript` meanwhile is to subclass for each of the scenarios that you want to define. You can also subclass from `FixtureScript` to create helpers; more on this below.
+* The role of `FixtureScript` meanwhile is to subclass for each of the scenarios that you want to define.
+You can also subclass from `FixtureScript` to create helpers; more on this below.
Let's look at `FixtureScripts` domain service in more detail first.
@@ -17,11 +18,16 @@ Let's look at `FixtureScripts` domain service in more detail first.
There are two ways in which you can provide a `FixtureScripts` service.
-The original (pre-1.9.0) approach is to subclass subclass `FixtureScripts` domain service, with your subclass specifying which package to search for. Various other settings can also be provided, and - being a custom class - you can also add in additional actions. A common example is to provide a "one-shot" action to recreate a standard demo set of objects.
+The original (pre-1.9.0) approach is to subclass subclass `FixtureScripts` domain service, with your subclass specifying which package to search for.
+Various other settings can also be provided, and - being a custom class - you can also add in additional actions.
+A common example is to provide a "one-shot" action to recreate a standard demo set of objects.
-As of 1.9.0 there is an alternative design. Instead of subclassing `FixtureScripts` you instead implement the xref:../rgsvc/rgsvc.adoc#_rgsvc_testing_FixtureScriptsSpecificationProvider[`FixtureScriptsSpecificationProvider`] SPI. (As its name suggests), this provides a `FixtureScriptsSpecification` object that contains the same information as would otherwise have been in the `FixtureScripts` subclass.
+As of 1.9.0 there is an alternative design.
+Instead of subclassing `FixtureScripts` you instead implement the xref:../rgsvc/rgsvc.adoc#_rgsvc_testing_FixtureScriptsSpecificationProvider[`FixtureScriptsSpecificationProvider`] SPI.
+(As its name suggests), this provides a `FixtureScriptsSpecification` object that contains the same information as would otherwise have been in the `FixtureScripts` subclass.
-The actual implementation of the `FixtureScripts` service is then provided by the framework itself, namely the xref:../rgsvc/rgsvc.adoc#_rgsvc_testing_FixtureScriptsDefault[`FixtureScriptsDefault`] domain service, annotated to be rendered on the secondary "Prototyping" menu. This uses the `FixtureScriptsSpecificationProvider` to adjust itself accordinly.
+The actual implementation of the `FixtureScripts` service is then provided by the framework itself, namely the xref:../rgsvc/rgsvc.adoc#_rgsvc_testing_FixtureScriptsDefault[`FixtureScriptsDefault`] domain service, annotated to be rendered on the secondary "Prototyping" menu.
+This uses the `FixtureScriptsSpecificationProvider` to adjust itself accordinly.
For example, here's the `FixtureScriptsSpecificationProvider` service that's generated by the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]:
@@ -48,7 +54,8 @@ public class DomainAppFixturesProvider implements FixtureScriptsSpecificationPro
<5> if present, enables a "recreate objects and return first" action to be displayed in the UI
-The benefit of this design - decoupling the responsibilities of the superclass and the subclass - is that it ensures that there is always an instance of `FixtureScripts` available, even if the application itself doesn't provide one. Some of the (non-ASF) link:http://www.isisaddons.org[Isis Addons] modules (eg http://github.com/isisaddons/isis-module-security[Isis addons' security] module) expect there to be a `FixtureScripts` service for seeding data, which has caused some confusion.
+The benefit of this design - decoupling the responsibilities of the superclass and the subclass - is that it ensures that there is always an instance of `FixtureScripts` available, even if the application itself doesn't provide one.
+Some of the (non-ASF) link:http://www.isisaddons.org[Isis Addons] modules (eg http://github.com/isisaddons/isis-module-security[Isis addons' security] module) expect there to be a `FixtureScripts` service for seeding data, which has caused some confusion.
By way of comparison, if using the older pre-1.9.0 approach then you would create a subclass:
@@ -137,7 +144,9 @@ Let's now look at the `FixtureScript` class, where there's a bit more going on.
== `FixtureScript`
-A fixture script is ultimately just a block of code that can be executed, so it's up to you how you implement it to set up the system. However, we strongly recommend that you use it to invoke actions on business objects, in essence to replay what a real-life user would have done. That way, the fixture script will remain valid even if the underlying implementation of the system changes in the future.
+A fixture script is ultimately just a block of code that can be executed, so it's up to you how you implement it to set up the system.
+However, we strongly recommend that you use it to invoke actions on business objects, in essence to replay what a real-life user would have done.
+That way, the fixture script will remain valid even if the underlying implementation of the system changes in the future.
Here's the `RecreateSimpleObjects` fixture script from the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]:
@@ -182,29 +191,35 @@ public class RecreateSimpleObjects extends FixtureScript { //
}
----
<1> inherit from `org.apache.isis.applib.fixturescripts.FixtureScript`
-<2> a hard-coded list of values for the names. Note that the http://github.com/isisaddons/isis-module-fakedata[Isis addons' fakedata] module (non-ASF) could also have been used
+<2> a hard-coded list of values for the names.
+Note that the http://github.com/isisaddons/isis-module-fakedata[Isis addons' fakedata] module (non-ASF) could also have been used
<3> whether the script is "discoverable"; in other words whether it should be rendered in the drop-down by the `FixtureScripts` service
-<4> input property: the number of objects to create, up to 10; for the calling test to specify, but note this is optional and has a default (see below). It's important that a wrapper class is used (ie `java.lang.Integer`, not `int`)
+<4> input property: the number of objects to create, up to 10; for the calling test to specify, but note this is optional and has a default (see below).
+It's important that a wrapper class is used (ie `java.lang.Integer`, not `int`)
<5> output property: the generated list of objects, for the calling test to grab
<6> the mandatory execute(...) API
<7> the `defaultParam(...)` (inherited from `FixtureScript`) will default the `number` property (using Java's Reflection API) if none was specified
-<8> call another fixture script (`SimpleObjectsTearDown`) using the provided `ExecutionContext`. Note that although the fixture script is a view model, it's fine to simply instantiate it (rather than using `DomainObjectContainer#newTransientInstance(...)`).
+<8> call another fixture script (`SimpleObjectsTearDown`) using the provided `ExecutionContext`.
+Note that although the fixture script is a view model, it's fine to simply instantiate it (rather than using `FactoryService#instantiate(...)`).
<9> calling another fixture script (`SimpleObjectCreate`) using the provided `ExecutionContext`
<10> adding the created object to the list, for the calling object to use.
-Because this script has exposed a "number" property, it's possible to set this from within the UI. For example:
+Because this script has exposed a "number" property, it's possible to set this from within the UI.
+For example:
image::{_imagesdir}testing/fixture-scripts/prompt.png[width="700px"]
-
-When this is executed, the framework will parse the text and attempt to reflectively set the corresponding properties on the fixture result. So, in this case, when the fixture script is executed we actually get 6 objects created:
+When this is executed, the framework will parse the text and attempt to reflectively set the corresponding properties on the fixture result.
+So, in this case, when the fixture script is executed we actually get 6 objects created:
image::{_imagesdir}testing/fixture-scripts/result-list.png[width="700px"]
-It's commonplace for one fixture script to call another. In the above example this script called `SimpleObjectsTearDown` and `SimpleObjectCreate`. Let's take a quick look at `SimpleObjectCreate`:
+It's commonplace for one fixture script to call another.
+In the above example this script called `SimpleObjectsTearDown` and `SimpleObjectCreate`.
+Let's take a quick look at `SimpleObjectCreate`:
[source,java]
----
@@ -245,8 +260,6 @@ public class SimpleObjectCreate extends FixtureScript { // <1>
-
-
== Using within Tests
Fixture scripts can be called from integration tests just the same way that fixture scripts can call one another.
@@ -300,7 +313,8 @@ There are lots of ways to organize fixture scripts, but we've used them as eithe
* in a "composite pattern" style, eg as in the https://github.com/estatio/estatio/blob/ea20a6ce257acede50de6ce4fd2ff29713fcd689/estatioapp/fixture/src/main/java/org/estatio/fixture/invoice/InvoiceForLeaseItemTypeOfDiscountOneQuarterForOxfMiracle005.java#L66)[Estatio open source app].
-These two styles are probably best illustrated with, well, some illustrations. Here's a fixture script in the "flat" style for setting up a customer with some orders, a number of which has been placed:
+These two styles are probably best illustrated with, well, some illustrations.
+Here's a fixture script in the "flat" style for setting up a customer with some orders, a number of which has been placed:
image::{_imagesdir}testing/fixture-scripts/flat-1.png[width="700px",link="{_imagesdir}testing/fixture-scripts/flat-1.png"]
@@ -312,41 +326,39 @@ image::{_imagesdir}testing/fixture-scripts/flat-2.png[width="500px",link="{_imag
We can reuse the same fixture "customer" script, either calling it twice or (perhaps better) passing it an array of customer details to set up.
-With the composite style, we rely on each fixture script to set up its own prerequisites. Thus:
+With the composite style, we rely on each fixture script to set up its own prerequisites.
+Thus:
image::{_imagesdir}testing/fixture-scripts/composite.png[width="550px",link="{_imagesdir}testing/fixture-scripts/composite.png"]
-Back in the earlier section we noted the `MultipleExecutionStrategy` setting. We can now explain the meaning of this: the enum value of `EXECUTE` is designed for the flat style (where every fixture script will be called), whereas the enum value of `IGNORE` is designed for the composite style, and ensures that any fixture scripts visited more than once (eg TearDown) are only every executed the first time.
+Back in the earlier section we noted the `MultipleExecutionStrategy` setting.
+We can now explain the meaning of this: the enum value of `EXECUTE` is designed for the flat style (where every fixture script will be called), whereas the enum value of `IGNORE` is designed for the composite style, and ensures that any fixture scripts visited more than once (eg TearDown) are only every executed the first time.
As already noted , the app generated by the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] uses the flat structure, and we feel that it's a better at separating out the "how" (how we set up some graph of domain objects into a known state, eg a customer with shipped placed orders and a newly placed order) from the "what" (what data should we actually use for the customer's name, say).
-The composite style tends to combine these, which one could argue does not separate responsibilities well enough. On the other hand, one could also make an argument that the composite style is a good way to implement precanned personas, eg "Joe", the customer who has a newly placed order, from "Mary" customer who has none.
+The composite style tends to combine these, which one could argue does not separate responsibilities well enough.
+On the other hand, one could also make an argument that the composite style is a good way to implement precanned personas, eg "Joe", the customer who has a newly placed order, from "Mary" customer who has none.
=== Further approaches
As of there are two other approaches.
-The first is to take advantage of a new `MultipleExecutionStrategy`, namely `EXECUTE_ONCE_BY_VALUE`. Under this strategy the determination as to whether to run a given fixture script is by comparing the fixture script against all others that have run. If all fixture scripts implement value semantics, then they can effectively determine
-whether they need to run or not.
+The first is to take advantage of a new `MultipleExecutionStrategy`, namely `EXECUTE_ONCE_BY_VALUE`. Under this strategy the determination as to whether to run a given fixture script is by comparing the fixture script against all others that have run.
+If all fixture scripts implement value semantics, then they can effectively determine whether they need to run or not.
-This strategy was introduced in order to better support the `ExcelFixture` fixture script (provided by the
-(non-ASF) http://github.com/isisaddons/isis-module-excel[Isis addons' excel] module. The `ExcelFixture` takes an
-Excel spreadsheet and loads up each row. For those cases where we wish to ensure that the same spreadsheet is not
-loaded more than once, the `IGNORE` strategy would have required that a trivial subclass of `ExcelFixture` is created
-for each and every spreadsheet. The `EXECUTE_ONCE_BY_VALUE` on the other hand delegates the determination to the
-value semantics of the `ExcelFixture`, which is based on the contents of the spreadsheet.
+This strategy was introduced in order to better support the `ExcelFixture` fixture script (provided by the (non-ASF) http://github.com/isisaddons/isis-module-excel[Isis addons' excel] module.
+The `ExcelFixture` takes an Excel spreadsheet and loads up each row.
+For those cases where we wish to ensure that the same spreadsheet is not loaded more than once, the `IGNORE` strategy would have required that a trivial subclass of `ExcelFixture` is created for each and every spreadsheet.
+The `EXECUTE_ONCE_BY_VALUE` on the other hand delegates the determination to the value semantics of the `ExcelFixture`, which is based on the contents of the spreadsheet.
[NOTE]
====
Note that as of `1.10.0` the `IGNORE` enum has been deprecated, replaced by `EXECUTE_ONCE_BY_CLASS`
====
-The second approach is in recognition that there is, in fact, something of a design flaw with the concept of
-`MultipleExecutionStrategy`: it requires that all fixture scripts being run follow the same conventions. There's a
-good argument that this shouldn't be a global "setting": the responsibility for determining whether a given fixture
-script should be executed should reside not in the `FixtureScripts` service but in the `FixtureScript` itself.
+The second approach is in recognition that there is, in fact, something of a design flaw with the concept of `MultipleExecutionStrategy`: it requires that all fixture scripts being run follow the same conventions.
+There's a good argument that this shouldn't be a global "setting": the responsibility for determining whether a given fixture script should be executed should reside not in the `FixtureScripts` service but in the `FixtureScript` itself.
-Thus, the `FixtureScripts.ExecutionContext` exposes the `getPreviouslyExecuted()` method that allows the fixture
-script to check for itself which fixture scripts have already been run, and act accordingly. For this approach, the
-`MultipleExecutionStrategy` should be left as simply `EXECUTE`.
+Thus, the `FixtureScripts.ExecutionContext` exposes the `getPreviouslyExecuted()` method that allows the fixture script to check for itself which fixture scripts have already been run, and act accordingly.
+For this approach, the `MultipleExecutionStrategy` should be left as simply `EXECUTE`.
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_integ-test-support_bootstrapping.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_integ-test-support_bootstrapping.adoc b/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_integ-test-support_bootstrapping.adoc
index 883b36e..7d546d2 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_integ-test-support_bootstrapping.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_integ-test-support_bootstrapping.adoc
@@ -5,11 +5,13 @@
:_imagesdir: images/
-Integration tests instantiate an Apache Isis "runtime" (as a singleton) within a JUnit test. Because (depending on the size of your app) it takes a little time to bootstrap Apache Isis, the framework caches the runtime on a thread-local from one test to the next.
+Integration tests instantiate an Apache Isis "runtime" (as a singleton) within a JUnit test.
+Because (depending on the size of your app) it takes a little time to bootstrap Apache Isis, the framework caches the runtime on a thread-local from one test to the next.
Nevertheless, we do need to bootstrap the runtime for the very first test.
-As of 1.9.0 the bootstrapping of integration tests and webapps has been simplified through the xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`] class. Since this isn't mandatory, for now we present both techniques.
+As of 1.9.0 the bootstrapping of integration tests and webapps has been simplified through the xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`] class.
+Since this isn't mandatory, for now we present both techniques.
The example code in this section is taken from the app generated by the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
@@ -18,7 +20,8 @@ The example code in this section is taken from the app generated by the xref:../
== System Initializer
-The bootstrapping itself is performed by a "system initializer" class. This is responsible for instantiating the Apache Isis runtime, and binding it to a thread-local.
+The bootstrapping itself is performed by a "system initializer" class.
+This is responsible for instantiating the Apache Isis runtime, and binding it to a thread-local.
=== 1.13.0 (Improved intent)
@@ -51,9 +54,8 @@ public class DomainAppSystemInitializer {
}
----
-While the code is slightly longer than previously, the responsibilities for returning the configuration properties to
-use for the test now reside in a single location. The new `AppManifest.Util` class provides the helper methods to
-actually add in the appropriate config properties.
+While the code is slightly longer than previously, the responsibilities for returning the configuration properties to use for the test now reside in a single location.
+The new `AppManifest.Util` class provides the helper methods to actually add in the appropriate config properties.
=== 1.9.0 (`AppManifest`)
@@ -154,7 +156,8 @@ public class DomainAppSystemInitializer {
Integration tests are configured programmatically, with a default set of properties to bootstrap the JDO/DataNucleus objectstore using an HSQLDB in-memory database.
-To remove a little bit of boilerplate, the `IsisConfigurationForJdoIntegTests` class (in the `org.apache.isis.objectstore.jdo.datanucleus` package) can be used to bootstrap the application. If necessary, this class can be subclassed to override these defaults.
+To remove a little bit of boilerplate, the `IsisConfigurationForJdoIntegTests` class (in the `org.apache.isis.objectstore.jdo.datanucleus` package) can be used to bootstrap the application.
+If necessary, this class can be subclassed to override these defaults.
.Default Configuration Properties for Integration Tests
@@ -242,7 +245,8 @@ See the link:http://www.datanucleus.org/products/accessplatform_4_1/persistence_
== Abstract Class
-We recommend defining a base class for all your other classes to integration classes to inherit from. The main responsibility of this class is tocall the system initializer, described earlier. We only need the initialization to be performed once, so this call is performed in a `@BeforeClass` hook.
+We recommend defining a base class for all your other classes to integration classes to inherit from. The main responsibility of this class is tocall the system initializer, described earlier.
+We only need the initialization to be performed once, so this call is performed in a `@BeforeClass` hook.
The code below shows the general form:
@@ -298,9 +302,7 @@ Although not mandatory, this provides a number of helper/convenience methods and
All of these rules could be inlined in your own base class; as we say, they are a convenience.
-The `IntegrationTestAbstract` also provides a number of helper/convenience methods, though most of these have been
-deprecated because the functionality they expose is now readily accessible through various domain services; most
-notably these are:
+The `IntegrationTestAbstract` also provides a number of helper/convenience methods, though most of these have been deprecated because the functionality they expose is now readily accessible through various domain services; most notably these are:
* xref:../rgsvc/rgsvc.adoc#_rgsvc_application-layer-api_WrapperFactory[`WrapperFactory`] +
+
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_integ-test-support_maven-configuration.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_integ-test-support_maven-configuration.adoc b/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_integ-test-support_maven-configuration.adoc
index 7b98813..22abee2 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_integ-test-support_maven-configuration.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_integ-test-support_maven-configuration.adoc
@@ -5,7 +5,8 @@
:_imagesdir: images/
-Apache Isis' integration test support is automatically configured if you use the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]. To set it up manually, update the `pom.xml` of your domain object model module:
+Apache Isis' integration test support is automatically configured if you use the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
+To set it up manually, update the `pom.xml` of your domain object model module:
[source,xml]
----
@@ -19,6 +20,11 @@ Apache Isis' integration test support is automatically configured if you use the
</dependency>
----
+[NOTE]
+====
+As of `1.15.0-SNAPSHOT` this can also be done by adding a dependency to `org.apache.isis.mavendeps:isis-mavendeps-testing` module; see the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
+====
+
We also recommend that you configure the `maven-surefire-plugin` to pick up the following class patterns:
[source,xml]
@@ -44,3 +50,8 @@ We also recommend that you configure the `maven-surefire-plugin` to pick up the
</configuration>
</plugin>
----
+
+[NOTE]
+====
+As of `1.14.0` this can also be done using mavenmixins; see the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_unit-test-support_maven-configuration.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_unit-test-support_maven-configuration.adoc b/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_unit-test-support_maven-configuration.adoc
index d6bd084..4001898 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_unit-test-support_maven-configuration.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugtst/_ugtst_unit-test-support_maven-configuration.adoc
@@ -5,7 +5,8 @@
:_imagesdir: images/
-Apache Isis' unit test support is automatically configured if you use the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]. To set it up manually, update the `pom.xml` of your domain object model module:
+Apache Isis' unit test support is automatically configured if you use the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_helloworld-archetype[HelloWorld] or the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp] archetypes.
+To set it up manually, update the `pom.xml` of your domain object model module:
[source,xml]
----
@@ -18,6 +19,11 @@ Apache Isis' unit test support is automatically configured if you use the xref:.
<1> Normally `test`; usual Maven scoping rules apply.
+[NOTE]
+====
+As of `1.15.0-SNAPSHOT` this can also be done by adding a dependency to `org.apache.isis.mavendeps:isis-mavendeps-testing` module; see the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
+====
+
We also recommend that you configure the `maven-surefire-plugin` to pick up the following class patterns:
@@ -44,3 +50,8 @@ We also recommend that you configure the `maven-surefire-plugin` to pick up the
</configuration>
</plugin>
----
+
+[NOTE]
+====
+As of `1.14.0` this can also be done using mavenmixins; see the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_customisation_about-page.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_customisation_about-page.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_customisation_about-page.adoc
index 3e4f01b..cd4429d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_customisation_about-page.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_customisation_about-page.adoc
@@ -6,7 +6,9 @@
-Isis' Wicket viewer has an About page that, by default, will provide a dump of the JARs that make up the webapp. This page will also show the manifest attributes of the WAR archive itself, if there are any. One of these attributes may also be used as the application version number.
+Isis' Wicket viewer has an About page that, by default, will provide a dump of the JARs that make up the webapp.
+This page will also show the manifest attributes of the WAR archive itself, if there are any.
+One of these attributes may also be used as the application version number.
== Screenshot
@@ -20,19 +22,17 @@ image::{_imagesdir}about-page/about-page.png[width="800px",link="{_imagesdir}abo
Note that this screenshot shows an earlier version of the xref:../ugvw/ugvw.adoc#[Wicket viewer] UI (specifically, pre 1.8.0).
====
-Note that the `Build-Time` attribute has been used as the version number. The Wicket viewer is hard-coded to search for specific attributes and use as the application version. In order, it searches for:
+Note that the `Build-Time` attribute has been used as the version number.
+The Wicket viewer is hard-coded to search for specific attributes and use as the application version.
+In order, it searches for:
* `Implementation-Version`
* `Build-Time`
If none of these are found, then no version is displayed.
-== Configuration
-[TIP]
-====
-This configuration is included within the xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
-====
+== Configuration
=== Adding attributes to the WAR's manifest
@@ -93,7 +93,9 @@ If you then build the webapp from the Maven command line (`mvn clean package`),
The manifest attributes are provided to the rest of the application by way of the Wicket viewer's integration with Google Guice.
-In your subclass of `IsisWicketApplication`, there is a method `newIsisWicketModule()`. In this method you need to bind an `InputStream` that will read the manifest attributes. This is all boilerplate so you can just copy-n-paste:
+In your subclass of `IsisWicketApplication`, there is a method `newIsisWicketModule()`.
+In this method you need to bind an `InputStream` that will read the manifest attributes.
+This is all boilerplate so you can just copy-n-paste:
[source,java]
----
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_file-based.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_file-based.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_file-based.adoc
index 4554f10..ae055de 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_file-based.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvw/_ugvw_layout_file-based.adoc
@@ -93,7 +93,9 @@ Most IDEs will automatically download the XSD schemas from the specified schema
=== Rows, full-width cols, and tabs
-The example layout consists of three rows: a row for the object/icon, a row containing a properties, and a row containing collections. In all three cases the row contains a single column spanning the full width of the page. For the property and collection rows, the column contains a tab group.
+The example layout consists of three rows: a row for the object/icon, a row containing a properties, and a row containing collections.
+In all three cases the row contains a single column spanning the full width of the page.
+For the property and collection rows, the column contains a tab group.
This corresponds to the following XML:
@@ -124,13 +126,15 @@ This corresponds to the following XML:
----
-You will notice that one of the ``col``umns has an ``unreferencedActions`` attribute, while one of the ``tabGroup``s has a similar ``unreferencedCollections`` attribute. This topic is discussed in more detail xref:../ugfun/ugfun.adoc#__ugvw_layout_file-based_unreferenced[below].
+You will notice that one of the ``col``umns has an ``unreferencedActions`` attribute, while one of the ``tabGroup``s has a similar ``unreferencedCollections`` attribute.
+This topic is discussed in more detail xref:../ugfun/ugfun.adoc#__ugvw_layout_file-based_unreferenced[below].
=== Fieldsets
-The first tab containing properties is divided into two columns, each of which holds a single fieldset of multiple properties. Those properties in turn can have associated actions.
+The first tab containing properties is divided into two columns, each of which holds a single fieldset of multiple properties.
+Those properties in turn can have associated actions.
This corresponds to the following XML:
@@ -163,9 +167,11 @@ This corresponds to the following XML:
The tab defines two columns, each span of 6 (meaning half the width of the page).
-In the first column there is a single fieldset. Notice how actions - such as `duplicate` and `delete` - can be associated with this fieldset directly, meaning that they should be rendered on the fieldset's top panel.
+In the first column there is a single fieldset.
+Notice how actions - such as `duplicate` and `delete` - can be associated with this fieldset directly, meaning that they should be rendered on the fieldset's top panel.
-Thereafter the fieldset lists the properties in order. Actions can be associated with properties too; here they are rendered underneath or to the right of the field.
+Thereafter the fieldset lists the properties in order.
+Actions can be associated with properties too; here they are rendered underneath or to the right of the field.
Note also the `unreferencedProperties` attribute for the fieldset; this topic is discussed in more detail xref:../ugfun/ugfun.adoc#__ugvw_layout_file-based_unreferenced[below].
@@ -217,18 +223,23 @@ The rules are:
* `unreferencedActions` attribute can be specified either on a column or on a fieldset. +
+
-It would normally be typical to use the column holding the `<domainObject/>` icon/title, that is as shown in the example. The unreferenced actions then appear as top-level actions for the domain object.
+It would normally be typical to use the column holding the `<domainObject/>` icon/title, that is as shown in the example.
+The unreferenced actions then appear as top-level actions for the domain object.
* `unreferencedCollections` attribute can be specified either on a column or on a tabgroup. +
+
-If specified on a column, then that column will contain each of the unreferenced collections, stacked one on top of the other. If specified on a tab group, then a separate tab will be created for each collection, with that tab containing only that single collection.
+If specified on a column, then that column will contain each of the unreferenced collections, stacked one on top of the other.
+If specified on a tab group, then a separate tab will be created for each collection, with that tab containing only that single collection.
* `unreferencedProperties` attribute can be specified only on a fieldset.
-The purpose of these attributes is to indicate where in the layout any unreferenced members should be rendered. Every grid _must_ nominate one region for each of these three member types, the reason being that to ensure that the layout can be used even if it is incomplete with respect to the object members inferred from the Java source code. This might be because the developer forgot to update the layout, or it might be because of a new mixin (property, collection or action) contributed to many objects.
+The purpose of these attributes is to indicate where in the layout any unreferenced members should be rendered.
+Every grid _must_ nominate one region for each of these three member types, the reason being that to ensure that the layout can be used even if it is incomplete with respect to the object members inferred from the Java source code.
+This might be because the developer forgot to update the layout, or it might be because of a new mixin (property, collection or action) contributed to many objects.
-The framework ensures that in any given grid exactly one region is specified for each of the three `unreferenced...` attributes. If the grid fails this validation, then a warning message will be displayed, and the invalid XML logged. The layout XML will then be ignored.
+The framework ensures that in any given grid exactly one region is specified for each of the three `unreferenced...` attributes.
+If the grid fails this validation, then a warning message will be displayed, and the invalid XML logged. The layout XML will then be ignored.
@@ -276,9 +287,8 @@ In the middle column the `notYetComplete` collection is rendered in "calendar" v
it is rendered in "table" view.
-It is also possible to reference object properties and actions more than once. This might be useful for a complex
-domain object with multiple tabs; certain properties or actions might appear on a summary tab (that shows the
-most commonly used info), but also on detail tabs.
+It is also possible to reference object properties and actions more than once.
+This might be useful for a complex domain object with multiple tabs; certain properties or actions might appear on a summary tab (that shows the most commonly used info), but also on detail tabs.
=== Custom CSS
@@ -337,7 +347,8 @@ from the top of the page slightly, using the following CSS:
== Migrating from earlier versions
-As noted earlier on, it is possible to download layout XML files using the xref:../rgsvc/rgsvc.adoc#_rgsvc_metadata-api_LayoutService[`LayoutService`] (exposed on the prototyping menu); this will download a ZIP file of layout XML files for all domain entities and view models. Alternatively the layout XML for a single domain object can be downloaded using the xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins_Object[mixin action] (contributed to every domain object).
+As noted earlier on, it is possible to download layout XML files using the xref:../rgsvc/rgsvc.adoc#_rgsvc_metadata-api_LayoutService[`LayoutService`] (exposed on the prototyping menu); this will download a ZIP file of layout XML files for all domain entities and view models.
+Alternatively the layout XML for a single domain object can be downloaded using the xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins_Object[mixin action] (contributed to every domain object).
There are four "styles":
@@ -347,10 +358,8 @@ There are four "styles":
* minimal
-Ignorig the "current" style (which merely downloads the currently cached layout), the other three styles allow the
-developer to choose how much metadata is to be specified in the XML, and how much (if any) will be obtained
-elsewhere, either from annotations in the metamodel or from an earlier `.layout.json` file if present. The table
-below summarises the choices:
+Ignorig the "current" style (which merely downloads the currently cached layout), the other three styles allow the developer to choose how much metadata is to be specified in the XML, and how much (if any) will be obtained elsewhere, either from annotations in the metamodel or from an earlier `.layout.json` file if present.
+The table below summarises the choices:
.Table caption
[cols="<.>,^.>,^.>,^.>", options="header"]
@@ -383,11 +392,15 @@ below summarises the choices:
As a developer, you therefore have a choice as to how you provide the metadata required for customised layouts:
-* if you want all layout metadata to be read from the `.layout.xml` file, then download the "complete" version, and copy the file alongside the domain class. You can then remove all `@MemberGroupLayout`, `@MemberOrder`, `@ActionLayout`, `@PropertyLayout` and `@CollectionLayout` annotations from the source code of the domain class.
+* if you want all layout metadata to be read from the `.layout.xml` file, then download the "complete" version, and copy the file alongside the domain class.
+You can then remove all `@MemberGroupLayout`, `@MemberOrder`, `@ActionLayout`, `@PropertyLayout` and `@CollectionLayout` annotations from the source code of the domain class.
-* if you want to use layout XML file to describe the grid (columns, tabs etc) and specify which object members are associated with those regions of the grid, then download the "normalized" version. You can then remove the `@MemberGroupLayout` and `@MemberOrder` annotations from the source code of the domain class, but retain the `@ActionLayout`, `@PropertyLayout` and `@CollectionLayout` annotations.
+* if you want to use layout XML file to describe the grid (columns, tabs etc) and specify which object members are associated with those regions of the grid, then download the "normalized" version.
+You can then remove the `@MemberGroupLayout` and `@MemberOrder` annotations from the source code of the domain class, but retain the `@ActionLayout`, `@PropertyLayout` and `@CollectionLayout` annotations.
-* if you want to use layout XML file ONLY to describe the grid, then download the "minimal" version. The grid regions will be empty in this version, and the framework will use the `@MemberOrder` annotation to bind object members to those regions. The only annotation that can be safely removed from the source code with this style is the `@MemberGroupLayout` annotation.
+* if you want to use layout XML file ONLY to describe the grid, then download the "minimal" version.
+The grid regions will be empty in this version, and the framework will use the `@MemberOrder` annotation to bind object members to those regions.
+The only annotation that can be safely removed from the source code with this style is the `@MemberGroupLayout` annotation.
Download either for a single domain object, or download all domain objects (entities and view models).
@@ -408,7 +421,8 @@ For more information about layouts, see:
== Required updates to the dom project's pom.xml
-Any `.layout.xml` files must be compiled and available in the classpath. Ensure the following is defined in the dom project's `pom.xml`:
+Any `.layout.xml` files must be compiled and available in the classpath.
+Ensure the following is defined in the dom project's `pom.xml`:
[source.xml]
----
@@ -430,4 +444,4 @@ Any `.layout.xml` files must be compiled and available in the classpath. Ensure
</resources>
----
-If using an Apache Isis xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype], then the POM is already correctly configured.
+If using an Apache Isis xref:../ugfun/ugfun.adoc#_ugfun_getting-started_helloworld-archetype[HelloWorld] xref:../ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp] archetypes, then the POM is already correctly configured.
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.10.0-to-1.11.0.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.10.0-to-1.11.0.adoc b/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.10.0-to-1.11.0.adoc
index 8b31d42..bc27945 100644
--- a/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.10.0-to-1.11.0.adoc
+++ b/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.10.0-to-1.11.0.adoc
@@ -5,22 +5,17 @@
:_imagesdir: images/
-Existing projects written against v1.10.0 should run against v1.11.0 with few if any changes. If you *do* encounter
-any difficulties then let us know via the xref:../support.adoc#[users mailing list], so we can support you and document
-issues here.
+Existing projects written against v1.10.0 should run against v1.11.0 with few if any changes.
+If you *do* encounter any difficulties then let us know via the xref:../support.adoc#[users mailing list], so we can support you and document issues here.
== Swagger UI
-The new xref:../guides/rgsvc/rgsvc.adoc#_rgsvc_metadata-api_SwaggerService[`SwaggerService`] allows link:http://swagger.io[Swagger] spec files
-to be generated from the Apache Isis metamodel. These can be downloaded directly through the `SwaggerResource`
-(mapped to `/restful/swagger/public` and `/restful/swagger/private`) as well as from the Wicket UI through the
-`SwaggerServiceMenu`.
+The new xref:../guides/rgsvc/rgsvc.adoc#_rgsvc_metadata-api_SwaggerService[`SwaggerService`] allows link:http://swagger.io[Swagger] spec files to be generated from the Apache Isis metamodel.
+These can be downloaded directly through the `SwaggerResource` (mapped to `/restful/swagger/public` and `/restful/swagger/private`) as well as from the Wicket UI through the `SwaggerServiceMenu`.
-In addition, the xref:../guides/ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] now bundles
- link:https://github.com/swagger-api/swagger-ui[Swagger UI], which documents the main features of the REST API and
- allows it to be explored.
+In addition, the xref:../guides/ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] now bundles link:https://github.com/swagger-api/swagger-ui[Swagger UI], which documents the main features of the REST API and allows it to be explored.
To enable this in your application, first update the `web.xml`:
@@ -57,27 +52,24 @@ To enable this in your application, first update the `web.xml`:
<2> issues a 401 status, but with the `WWW-Authenticate` challenge suppressed if requested from the Swagger UI
<3> provides access to the RESTful resource that generates the Swagger spec.
-There is also an HTML page to load the Swagger UI itself; this resides in `src/main/webapp/swagger-ui/index.html`. Copy the link:https://github.com/apache/isis/blob/master/example/application/simpleapp/webapp/src/main/webapp/swagger-ui/index.html[file from Apache Isis' repo], or from the app generated by the xref:../guides/ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
+There is also an HTML page to load the Swagger UI itself; this resides in `src/main/webapp/swagger-ui/index.html`.
+Copy the link:https://github.com/apache/isis/blob/master/example/application/simpleapp/webapp/src/main/webapp/swagger-ui/index.html[file from Apache Isis' repo], or from the app generated by the xref:../guides/ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
-The text of the simple app's `about/index.html` has also changed (the `<li`> for the `/restful` URL has been replaced with a `/swagger-ui` URL). If you use link:https://github.com/apache/isis/blob/master/example/application/simpleapp/webapp/src/main/webapp/about/index.html[this file], then update it.
+The text of the simple app's `about/index.html` has also changed (the `<li`> for the `/restful` URL has been replaced with a `/swagger-ui` URL).
+If you use link:https://github.com/apache/isis/blob/master/example/application/simpleapp/webapp/src/main/webapp/about/index.html[this file], then update it.
-If your application is bootstrapped using an `AppManifest` (recommended;
-xref:../guides/rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[here]) then the default implementation of the
-`SwaggerService` will automatically be discovered and registered. However, if you are still using the older
-`isis.properties` configuration file to explicitly register services then you will need to add in this service.
+If your application is bootstrapped using an `AppManifest` (recommended; xref:../guides/rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[here]) then the default implementation of the `SwaggerService` will automatically be discovered and registered.
+However, if you are still using the older `isis.properties` configuration file to explicitly register services then you will need to add in this service.
== `RoutingService`
-The new xref:../guides/rgsvc/rgsvc.adoc#_rgsvc_presentation-layer-spi_RoutingService[`RoutingService`] SPI service provides a plugin point to the
-xref:../guides/ugvw/ugvw.adoc#[Wicket viewer] so that a different object than that returned from an action invocation can be
-rendered.
+The new xref:../guides/rgsvc/rgsvc.adoc#_rgsvc_presentation-layer-spi_RoutingService[`RoutingService`] SPI service provides a plugin point to the xref:../guides/ugvw/ugvw.adoc#[Wicket viewer] so that a different object than that returned from an action invocation can be rendered.
-The framework provides a default implementation of this service that will - instead of a void or a `null` result -
-render the home page (as per the xref:../guides/rgant/rgant.adoc#_rgant_HomePage[`@HomePage`] annotation) if there is one. This
-is therefore a subtle change in the UI. If you wish to retain the original behaviour (to return the "no results" page
-instead), then you should implement your own no-op implementation of this service:
+The framework provides a default implementation of this service that will - instead of a void or a `null` result - render the home page (as per the xref:../guides/rgant/rgant.adoc#_rgant_HomePage[`@HomePage`] annotation) if there is one.
+This is therefore a subtle change in the UI.
+If you wish to retain the original behaviour (to return the "no results" page instead), then you should implement your own no-op implementation of this service:
[source,java]
----
@@ -92,11 +84,10 @@ public class IdentityRoutingService implements RoutingService {
== Wicket Viewer i18n
-The xref:../guides/ugvw/ugvw.adoc#[Wicket viewer] (its labels, buttons, messages etc) can now be internationalized using the
-xref:../guides/rgsvc/rgsvc.adoc#_rgsvc_presentation-layer-spi_TranslationService[`TranslationService`].
+The xref:../guides/ugvw/ugvw.adoc#[Wicket viewer] (its labels, buttons, messages etc) can now be internationalized using the xref:../guides/rgsvc/rgsvc.adoc#_rgsvc_presentation-layer-spi_TranslationService[`TranslationService`].
-To enable this, new ``msgId``s and corresponding translations must be added to the `translations.po` file. Full
-details of these ``msgId``s can be found in xref:../guides/ugbtb/ugbtb.adoc#__ugbtb_i18n_wicket-viewer[i18n] section of the "beyond the basics" guide.
+To enable this, new ``msgId``s and corresponding translations must be added to the `translations.po` file.
+Full details of these ``msgId``s can be found in xref:../guides/ugbtb/ugbtb.adoc#__ugbtb_i18n_wicket-viewer[i18n] section of the "beyond the basics" guide.
If no translations are available, then the fallback is to use the previous mechanism, ie Wicket's original resource bundles.
This feature can therefore be considered as optional.
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.11.0-to-1.12.0.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.11.0-to-1.12.0.adoc b/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.11.0-to-1.12.0.adoc
index 787a16a..a172a9a 100644
--- a/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.11.0-to-1.12.0.adoc
+++ b/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.11.0-to-1.12.0.adoc
@@ -6,31 +6,25 @@
-Existing projects written against v1.11.x should run against v1.12.0 with few if any changes. If you *do* encounter
-any difficulties then let us know via the xref:../support.adoc#[users mailing list], so we can support you and document
-issues here.
+Existing projects written against v1.11.x should run against v1.12.0 with few if any changes.
+If you *do* encounter any difficulties then let us know via the xref:../support.adoc#[users mailing list], so we can support you and document issues here.
== Dynamic XML Layouts
-The major new feature in 1.12.0 is xref:../guides/ugvw/ugvw.adoc#_ugvw_layout_file-based[dynamic XML layouts], providing
-much enhanced support for custom layouts.
+The major new feature in 1.12.0 is xref:../guides/ugvw/ugvw.adoc#_ugvw_layout_file-based[dynamic XML layouts], providing much enhanced support for custom layouts.
-The new `Xxx.layout.xml` file is optional; without it domain objects will
-continue to be rendered as before, using metadata from annotations (xref:../guides/rgant/rgant.adoc#_rgant-DomainObjectLayout[`@DomainObjectLayout`],
-xref:../guides/rgant/rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`], xref:../guides/rgant/rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`],
-xref:../guides/rgant/rgant.adoc#_rgant-ActionLayout[`@ActionLayout`], xref:../guides/rgant/rgant.adoc#_rgant-MemberOrder[`@MemberOrder`] and
-xref:../guides/rgant/rgant.adoc#_rgant-MemberGroupLayout[`@MemberGroupLayout`]), and also from any xref:../guides/ugvw/ugvw.adoc#_ugvw_layout_file-based[`Xxx.layout.json`]
-file that might already exist. There is therefore no requirement to move to the new more flexible XML-based layout.
+The new `Xxx.layout.xml` file is optional; without it domain objects will continue to be rendered as before, using metadata from annotations (xref:../guides/rgant/rgant.adoc#_rgant-DomainObjectLayout[`@DomainObjectLayout`], xref:../guides/rgant/rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`], xref:../guides/rgant/rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`], xref:../guides/rgant/rgant.adoc#_rgant-ActionLayout[`@ActionLayout`], xref:../guides/rgant/rgant.adoc#_rgant-MemberOrder[`@MemberOrder`] and xref:../guides/rgant/rgant.adoc#_rgant-MemberGroupLayout[`@MemberGroupLayout`]), and also from any xref:../guides/ugvw/ugvw.adoc#_ugvw_layout_file-based[`Xxx.layout.json`] file that might already exist.
+There is therefore no requirement to move to the new more flexible XML-based layout.
-If you do want to start using the new format, then you will find that 1.12.0 provides a mixin action (available in
-prototype mode only) called "download XML layout". This will allow you to download the current layout file for the
-object being rendered. This can then be saved alongside the class' Java source file. Once a `Xxx.layout.xml` file
-is present, any existing `Xxx.layout.json` file will be ignored; any annotations though will continue to be honoured.
+If you do want to start using the new format, then you will find that 1.12.0 provides a mixin action (available in prototype mode only) called "download XML layout".
+This will allow you to download the current layout file for the object being rendered.
+This can then be saved alongside the class' Java source file.
+Once a `Xxx.layout.xml` file is present, any existing `Xxx.layout.json` file will be ignored; any annotations though will continue to be honoured.
-If you wish to migrate all your domain objects to use XML layouts, this can be done using the "download layouts (XML)"
-(on the "Prototyping" menu), as a single zip file. This can then be unzipped into the `src/main/java` directory.
+If you wish to migrate all your domain objects to use XML layouts, this can be done using the "download layouts (XML)" (on the "Prototyping" menu), as a single zip file.
+This can then be unzipped into the `src/main/java` directory.
== Mixins
@@ -47,33 +41,26 @@ If you wish to migrate all your domain objects to use XML layouts, this can be d
These are in addition to the xref:../guides/rgcms/rgcms.adoc#__rgcms_classes_mixins_Persistable_downloadJdoMetadata[download JDO metadata] mixin action (prototype mode) provided in earlier versions of the framework.
-The properties are grouped in a "metadata" fieldset, and the mixin actions associated with that fieldset. If the
-domain object is a view model rather than an entity (that is, has no id or version) then the actions will instead be rendered
-as top-level actions.
+The properties are grouped in a "metadata" fieldset, and the mixin actions associated with that fieldset.
+If the domain object is a view model rather than an entity (that is, has no id or version) then the actions will instead be rendered as top-level actions.
-Most of these mixin object members are visible only in prototype mode, though some are visible in production mode and
-so potentially visible to end-users. If you wish to suppress these members from the view, you can either use xref:../guides/ugsec/ugsec.adoc#[security],
-or alternatively you can write xref:../guides/rgcms/rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[subscriber]s to veto the visibility
-of these members by subscribing to their respective domain events.
+Most of these mixin object members are visible only in prototype mode, though some are visible in production mode and so potentially visible to end-users.
+If you wish to suppress these members from the view, you can either use xref:../guides/ugsec/ugsec.adoc#[security], or alternatively you can write xref:../guides/rgcms/rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[subscriber]s to veto the visibility of these members by subscribing to their respective domain events.
== JAXB view models are editable
-All xref:../guides/rgant/rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`] view models are now implicitly editable. Therefore any
-view models that should be read-only should have editing attribute disabled using xref:../guides/rgant/rgant.adoc#_rgant-DomainObject_editing[`@DomainObject#editing()`] (or use a xref:../guides/rgcms/rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[subscriber] to veto editability).
-
+All xref:../guides/rgant/rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`] view models are now implicitly editable.
+Therefore any view models that should be read-only should have editing attribute disabled using xref:../guides/rgant/rgant.adoc#_rgant-DomainObject_editing[`@DomainObject#editing()`] (or use a xref:../guides/rgcms/rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[subscriber] to veto editability).
== `DomainObjectContainer` domain service
-The xref:../guides/rgsvc/rgsvc.adoc#_rgsvc_core-domain-api_DomainObjectContainer[`DomainObjectContainer`]domain service has been deprecated, with
-its methods moved to a new set of more fine-grained domain services, such as
-xref:../guides/rgsvc/rgsvc.adoc#_rgsvc_persistence-layer-api_RepositoryService[`RepositoryService`] and
+The xref:../guides/rgsvc/rgsvc.adoc#_rgsvc_core-domain-api_DomainObjectContainer[`DomainObjectContainer`]domain service has been deprecated, with its methods moved to a new set of more fine-grained domain services, such as xref:../guides/rgsvc/rgsvc.adoc#_rgsvc_persistence-layer-api_RepositoryService[`RepositoryService`] and
xref:../guides/rgsvc/rgsvc.adoc#_rgsvc_application-layer-api_MessageService[`MessageService`].
-The `DomainObjectContainer` service will continue to be supported until Apache Isis v2.0.0, but in the meantime, consider
-changing existing application code to use these new domain services.
+The `DomainObjectContainer` service will continue to be supported until Apache Isis v2.0.0, but in the meantime, consider changing existing application code to use these new domain services.
Please note that when migrating from _rgsvc_core-domain-api_DomainObjectContainer_object-persistence-api.adoc#_rgsvc_core-domain-api_DomainObjectContainer_object-persistence-api[`DomainObjectContainer#persist()`] to xref:../../guides/rgsvc/rgsvc.adoc#_rgsvc_persistence-layer-api_RepositoryService[`RepositoryService#persist()`], no exception will be thrown if the Domain Object is already persisted, so the behavior of xref:../guides/rgsvc/rgsvc.adoc#_rgsvc_persistence-layer-api_RepositoryService[`RepositoryService#persist()`] will be the same as that of xref:rgsvc.adoc#_rgsvc_core-domain-api_DomainObjectContainer_object-persistence-api[`DomainObjectContainer#persistIfNotAlready()`].
@@ -82,18 +69,14 @@ Please note that when migrating from _rgsvc_core-domain-api_DomainObjectContaine
== Removal of the `self-host` profile
The `self-host` profile has been removed from the xref:../guides/ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
-Instead, run the application using either the `org.apache.isis.WebServer` main class, or `mvn jetty:run`, or build the
-WAR and deploy to a servlet container such as Tomcat.
+Instead, run the application using either the `org.apache.isis.WebServer` main class, or `mvn jetty:run`, or build the WAR and deploy to a servlet container such as Tomcat.
== `isis.viewer.wicket.disableModalDialogs` removed
-The Apache Isis Wicket viewer uses a modal dialog for action parameters. Before this feature was implemented (prior
-to 1.4.0), action parameters were rendered on their own page. This property was provided to re-enable the old
-behaviour.
+The Apache Isis Wicket viewer uses a modal dialog for action parameters. Before this feature was implemented (prior to 1.4.0), action parameters were rendered on their own page. This property was provided to re-enable the old behaviour.
-The property has now been removed and this feature removed; actions parameters are always now always shown in a
- modal dialog.
+The property has now been removed and this feature removed; actions parameters are always now always shown in a modal dialog.
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.8.0-to-1.9.0_bootstrapping-using-AppManifest.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.8.0-to-1.9.0_bootstrapping-using-AppManifest.adoc b/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.8.0-to-1.9.0_bootstrapping-using-AppManifest.adoc
index 65ccd9d..2f8e642 100644
--- a/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.8.0-to-1.9.0_bootstrapping-using-AppManifest.adoc
+++ b/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.8.0-to-1.9.0_bootstrapping-using-AppManifest.adoc
@@ -8,7 +8,8 @@
Apache Isis 1.9.0 provides a simplified programmatic way of bootstrapping the application, that also unifies bootstrapping for integration tests.
-For now this new bootstrapping mechanism is optional (you don't have to change your code), but it may become mandatory in future releases. The xref:../guides/ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] has been updated to use this new mechanism.
+For now this new bootstrapping mechanism is optional (you don't have to change your code), but it may become mandatory in future releases.
+The xref:../guides/ugfun/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] has been updated to use this new mechanism.
The instructions below assume that your application is structured as per the simpleapp archetype. Adjust accordingly.
@@ -16,7 +17,8 @@ The instructions below assume that your application is structured as per the sim
== `myapp-dom` Module
-In your `myapp-dom` module (containing definitions of your persistent entities and domain services), create an empty class to represent the module. This should be at the root package for the domain, eg:
+In your `myapp-dom` module (containing definitions of your persistent entities and domain services), create an empty class to represent the module.
+This should be at the root package for the domain, eg:
[source,java]
----
@@ -80,7 +82,8 @@ Since `myapp-fixture` will reference `myapp-dom` there's no need for a direct re
</dependency>
----
-* if your application uses any of the (non-ASF) link:http://www.isisaddons.org[Isis Addons] modules, then add dependencies to these modules in the `pom.xml`. You should be able to copy-and-paste the dependencies from the `pom.xml` of your `myapp-webapp` module.
+* if your application uses any of the (non-ASF) link:http://www.isisaddons.org[Isis Addons] modules, then add dependencies to these modules in the `pom.xml`.
+You should be able to copy-and-paste the dependencies from the `pom.xml` of your `myapp-webapp` module.
Create a module class for the `myapp` module also:
@@ -118,7 +121,8 @@ public class MyAppAppManifest implements AppManifest {
public Map<String, String> getConfigurationProperties() { return null; }
}
----
-<1> the module classes, whose packages specify the existence of domain services and/or persistent entities. If your app uses (non-ASF) link:http://www.isisaddons.org[Isis Addons] modules, then include the module classes for these addons in `getModules()`. For example, the (non-ASF) http://github.com/isisaddons/isis-module-security[Isis addons' security] module provides the `org.isisaddons.module.security.SecurityModule` class.
+<1> the module classes, whose packages specify the existence of domain services and/or persistent entities. If your app uses (non-ASF) link:http://www.isisaddons.org[Isis Addons] modules, then include the module classes for these addons in `getModules()`.
+For example, the (non-ASF) http://github.com/isisaddons/isis-module-security[Isis addons' security] module provides the `org.isisaddons.module.security.SecurityModule` class.
<2> any additional services, as per `isis.services` configuration property.
@@ -128,7 +132,8 @@ For details of the usages of the other methods in this interface, see the xref:.
====
-If in your `myapp-dom` module you have application-level services and view models (services that depend on persistent domain entities but not the other way around), then we recommend that you move this code to the new `myapp-app` module. This makes the layering clearer, and avoids circular dependencies between application-layer vs domain-layer logic.
+If in your `myapp-dom` module you have application-level services and view models (services that depend on persistent domain entities but not the other way around), then we recommend that you move this code to the new `myapp-app` module.
+This makes the layering clearer, and avoids circular dependencies between application-layer vs domain-layer logic.
http://git-wip-us.apache.org/repos/asf/isis/blob/ddf0cc50/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.8.0-to-1.9.0_upgrading-to-dn4.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.8.0-to-1.9.0_upgrading-to-dn4.adoc b/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.8.0-to-1.9.0_upgrading-to-dn4.adoc
index 4252a6a..79daf9b 100644
--- a/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.8.0-to-1.9.0_upgrading-to-dn4.adoc
+++ b/adocs/documentation/src/main/asciidoc/migration-notes/_migration-notes_1.8.0-to-1.9.0_upgrading-to-dn4.adoc
@@ -204,14 +204,18 @@ isis.persistor.datanucleus.impl.datanucleus.schema.validateConstraints=true
[NOTE]
====
-Previously Apache Isis would automatically add the auto-create property if they were absent from `isis.properties`, set to "true". The framework does still add the property, but now sets it to "false". This is to prevent the framework from unexpectedly modifying a target database if the application was misconfigured and the auto-create property not defined.
+Previously Apache Isis would automatically add the auto-create property if they were absent from `isis.properties`, set to "true".
+The framework does still add the property, but now sets it to "false".
+This is to prevent the framework from unexpectedly modifying a target database if the application was misconfigured and the auto-create property not defined.
-The framework will also automatically add the auto-validate property. Previously this was set to "true" and it is _still_ set to "true"; there is no risk of the target database being modified as a result of this auto-validate property being defaulted by the framework.
+The framework will also automatically add the auto-validate property.
+Previously this was set to "true" and it is _still_ set to "true"; there is no risk of the target database being modified as a result of this auto-validate property being defaulted by the framework.
====
[IMPORTANT]
====
-Setting `autoCreateAll` to `true` is important to do when running with an in-memory database. If you don't do this then the tables will be created lazily anyway by DataNucleus, but in some circumstances this can lead to deadlocks.
+Setting `autoCreateAll` to `true` is important to do when running with an in-memory database.
+If you don't do this then the tables will be created lazily anyway by DataNucleus, but in some circumstances this can lead to deadlocks.
====
@@ -233,7 +237,10 @@ isis.persistor.datanucleus.impl.datanucleus.identifier.case=MixedCase
== Run `mvn clean` !
-Be careful to ensure that your classes are only enhanced by the DataNucleus 4 enhancer, and _not_ by the DataNucleus 3 enhancer. Or even, be careful that they are not doubly enhanced. One of our committers had this situation and it led to all sorts of bizarre issues. The solution, it turned out, was actually just to do a full `mvn clean`.
+Be careful to ensure that your classes are only enhanced by the DataNucleus 4 enhancer, and _not_ by the DataNucleus 3 enhancer.
+Or even, be careful that they are not doubly enhanced.
+One of our committers had this situation and it led to all sorts of bizarre issues.
+The solution, it turned out, was actually just to do a full `mvn clean`.
If you are struggling and suspect you may have misconfigured the enhancer plugin, then you can decompile the bytecode (eg in IntelliJ) and take a look: