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 2015/05/20 09:29:19 UTC
[2/8] isis git commit: ISIS-1133: using xref: instead of <<...>> for
cross-references.
http://git-wip-us.apache.org/repos/asf/isis/blob/477811d3/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved_aaa.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved_aaa.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved_aaa.adoc
index 744231c..7008e84 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved_aaa.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-methods_reserved_aaa.adoc
@@ -15,30 +15,30 @@ The table below lists the reserved methods that are recognized as part of Apache
|Method
|Description
-|<<__code_cssclass_code, `cssClass()`>>
+|xref:__code_cssclass_code[`cssClass()`]
|Provides a CSS class for this object, which is added as a style in the containing when rendering the object within a table, or to a containing when rendering the object on a page. In conjunction with css/application.css, can therefore provide custom styling of an object instance wherever it is rendered.
-See also <<__code_title_code, `title()`>> and <<__code_iconName_code, `iconName()`>>.
+See also xref:__code_title_code[`title()`] and xref:__code_iconName_code[`iconName()`].
-|<<__code_disable_code, `disable(...)`>>
+|xref:__code_disable_code[`disable(...)`]
|Disable all or some of an object's properties
-|<<__code_hide_code, `hide(...)`>>
+|xref:__code_hide_code[`hide(...)`]
|Hide all or some of an object's properties
-|<<__code_iconname_code, `iconName()`>>
+|xref:__code_iconname_code[`iconName()`]
|Provides the name of the image to render, usually alongside the title, to represent the object. If not provided, then the class name is used to locate an image.
-See also <<__code_title_code, `title()`>> and <<__code_cssClass_code, `cssClass()`>>
+See also xref:__code_title_code[`title()`] and xref:__code_cssClass_code[`cssClass()`]
-|<<__code_getid_code, `getId()`>>
+|xref:__code_getid_code[`getId()`]
|Provides an optional unique identifier of a service. +
If not provided, the service's fully-qualified class name is used.
-|<<__code_title_code, `title()`>>
+|xref:__code_title_code[`title()`]
|Provides a title for the object. +
-Alternatively, use the <<__code_title_code, `@Title`>> annotation. +
-See also `iconName()` and <<__code_cssClass_code, `cssClass()`>>
+Alternatively, use the xref:__code_title_code[`@Title`] annotation. +
+See also `iconName()` and xref:__code_cssClass_code[`cssClass()`]
-|<<__code_validate_code, `validate()`>>
+|xref:__code_validate_code[`validate()`]
|Validate the object's state prior to persisting.
|===
@@ -65,28 +65,28 @@ The lifecycle methods are:
|Method
|Description
-|<<__code_created_code, `created()`>>
-|called when an object has just been created using <<__code_newTransientInstance_code, `newTransientInstance()`>>
+|xref:__code_created_code[`created()`]
+|called when an object has just been created using xref:__code_newTransientInstance_code[`newTransientInstance()`]
-|<<__code_loaded_code, `loaded()`>>
+|xref:__code_loaded_code[`loaded()`]
|called when a (persistent) object has just been loaded from the object store.
-|<<__code_persisted_code, `persisted()`>>
+|xref:__code_persisted_code[`persisted()`]
|called when object has just been persisted from the object store.
-|<<__code_persisting_code, `persisting()`>>
+|xref:__code_persisting_code[`persisting()`]
|called when a (not-yet-persistent) object is just about to be persisted from the object store
-|<<__code_removed_code, `removed()`>>
+|xref:__code_removed_code[`removed()`]
|called when a (persistent) object has just been persisted from the object store
-|<<__code_removing_code, `removing()`>>
+|xref:__code_removing_code[`removing()`]
|called when a (persistent) object is just about to be deleted from the object store
-|<<__code_updated_code, `updated()`>>
+|xref:__code_updated_code[`updated()`]
|called when a (persistent) object has just been updated in the object store
-|<<__code_updating_code, `updating()`>>
+|xref:__code_updating_code[`updating()`]
|called when a (persistent) object is just about to be updated in the object store
|===
@@ -103,7 +103,7 @@ Some lifecycle methods have been deprecated:
|Notes
|`deleted()`
-|Replaced by <<__code_removed_code, `removed()`>>
+|Replaced by xref:__code_removed_code[`removed()`]
|`deleting()`
|Replaced by removing()`
@@ -119,7 +119,7 @@ This method is never called.
|Replaced by persisted()`
|`saving()`
-|Replaced by <<__code_persisting_code, `persisting()`>>
+|Replaced by xref:__code_persisting_code[`persisting()`]
|===
http://git-wip-us.apache.org/repos/asf/isis/blob/477811d3/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services.adoc
index 161baf2..aa1102b 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services.adoc
@@ -6,9 +6,9 @@
Apache Isis includes an extensive number of domain services for your domain objects to use; simply define the service as an annotated field and Isis will inject the service into your object. These services' API are all defined in Isis' applib (`o.a.i.core:isis-core-applib` module); this minimizes the coupling between your code and Isis. It also allows you to easily mock out these services in your unit tests.
-Some of the services defined in the applib are intended to be used (primarily) not by your domain objects but instead by Isis itself. A good example of this is the <<__code_auditingservice3_code, `AuditingService3`>> service; if an implementation is present then Isis will call that service in order to record audit log entries. If no implementation is available then Isis will carry on regardless.
+Some of the services defined in the applib are intended to be used (primarily) not by your domain objects but instead by Isis itself. A good example of this is the xref:__code_auditingservice3_code[`AuditingService3`] service; if an implementation is present then Isis will call that service in order to record audit log entries. If no implementation is available then Isis will carry on regardless.
-Some domain services can be considered both API and SPI; a good example is the `EmailService` that is of direct use for domain objects wishing to send out emails, but is also used by the framework to support the user registration functionality supported by the <<_wicket_viewer, Wicket viewer>>. The same is true of the <<__code_eventbusservice_code, `EventBusService`>>; this can be used by domain objects to broadcast arbitrary events, but is also used by the framework to automatically emit events eg for `@Action(domainEvent=...)`. For these hybrid services we we have categorized the service as an "API" service.
+Some domain services can be considered both API and SPI; a good example is the `EmailService` that is of direct use for domain objects wishing to send out emails, but is also used by the framework to support the user registration functionality supported by the xref:_wicket_viewer[Wicket viewer]. The same is true of the xref:__code_eventbusservice_code[`EventBusService`]; this can be used by domain objects to broadcast arbitrary events, but is also used by the framework to automatically emit events eg for `@Action(domainEvent=...)`. For these hybrid services we we have categorized the service as an "API" service.
include::_ug_reference-services_api.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/477811d3/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services_spi_aaa.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services_spi_aaa.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services_spi_aaa.adoc
index fa3baef..02dab2e 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services_spi_aaa.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services_spi_aaa.adoc
@@ -162,7 +162,7 @@ Key:
* `o.ia.m` is an abbreviation for `org.isisaddons.module`
-All domain services are automatically registered (annotated with <<__code_domainservice_code, `@DomainService`>>) except:
+All domain services are automatically registered (annotated with xref:__code_domainservice_code[`@DomainService`]) except:
http://git-wip-us.apache.org/repos/asf/isis/blob/477811d3/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer.adoc
index e7c62cf..9dfe2a2 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer.adoc
@@ -18,7 +18,7 @@ include::_ug_restfulobjects-viewer_hints-and-tips.adoc[leveloffset=+1]
== Extending the viewer
-Discussed in <<_extending_the_restful_viewer, Extending the Restful viewer>>.
+Discussed in xref:_extending_the_restful_viewer[Extending the Restful viewer].
http://git-wip-us.apache.org/repos/asf/isis/blob/477811d3/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration_properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration_properties.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration_properties.adoc
index 546a4fa..1f5a7b7 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration_properties.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration_properties.adoc
@@ -28,12 +28,12 @@ Also, be aware enabling these settings makes the representations with respect to
|`isis.viewer.restfulobjects.` +
`honorUiHints`
| `true`,`false` (`_false_`)
-| See <<_honor_ui_hints, discussion>>, below.
+| See xref:_honor_ui_hints[discussion], below.
|`isis.viewer.restfulobjects.` +
`suppressDescribedByLinks`
| `true`,`false` (`_false_`)
-.6+| See <<_suppressing_elements_of_the_representation, discussion>>, below.
+.6+| See xref:_suppressing_elements_of_the_representation[discussion], below.
|`isis.viewer.restfulobjects.` +
`suppressUpdateLink`
@@ -58,7 +58,7 @@ Also, be aware enabling these settings makes the representations with respect to
|`isis.viewer.restfulobjects.` +
`objectPropertyValuesOnly`
| `true`,`false` (`_false_`)
-| See <<_simplified_object_representation, discussion>>, below.
+| See xref:_simplified_object_representation[discussion], below.
|===
@@ -113,7 +113,7 @@ The defaults for all of these is false, meaning that the hypermedia/metadata is
In the future we might extend this per-request. Raise/vote on a JIRA ticket if you require this feature.
====
-If an even simpler representations (of objects) are required, see <<_simplified_object_representation, simplified object representation>>, immediately below. And if the above isn't flexible and you need complete control over all representations see the section on <<_extending_the_restful_viewer, Extending the Restful viewer>> in the <<Extending>> chapter.
+If an even simpler representations (of objects) are required, see xref:_simplified_object_representation[simplified object representation], immediately below. And if the above isn't flexible and you need complete control over all representations see the section on xref:_extending_the_restful_viewer[Extending the Restful viewer] in the <<Extending>> chapter.
@@ -122,7 +122,7 @@ If an even simpler representations (of objects) are required, see <<_simplified_
The representations specified by the http://restfulobjects.org[Restful Object spec] are very rich in hypermedia
controls and metadata, intended to support a wide variety of possible REST clients.
-As described <<_suppressing_elements_of_the_representations, above>>, it is possible to suppress various elements of these representations. Even then, though, the representations may be too complex for some bespoke REST clients that require a very "flat" object representation.
+As described xref:_suppressing_elements_of_the_representations[above], it is possible to suppress various elements of these representations. Even then, though, the representations may be too complex for some bespoke REST clients that require a very "flat" object representation.
The Restful Objects viewer therefore supports generating a much simpler representation of objects using the following configuration property (typically added to `WEB-INF/viewer_restfulobjects.properties`):
@@ -178,4 +178,4 @@ This generates a representation such as:
In the future we might extend this per-request. Raise/vote on a JIRA ticket if you require this feature.
====
-If the above isn't flexible and you need complete control over all representations see the section on <<_extending_the_restful_viewer, Extending the Restful viewer>>.
+If the above isn't flexible and you need complete control over all representations see the section on xref:_extending_the_restful_viewer[Extending the Restful viewer].
http://git-wip-us.apache.org/repos/asf/isis/blob/477811d3/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_features.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_features.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_features.adoc
index 2f8f591..8c11541 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_features.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_features.adoc
@@ -15,7 +15,7 @@ The Restful Objects spec can be downloaded link:http://restfulobjects.org[here].
== Pretty printing
-The JSON representations generated by the Restful Objects viewer are in compact form if the <<_deployment_types, deployment type>> is SERVER (ie production), but will automatically be "pretty printed" (in other words indented) if the deployment type is PROTOTYPE.
+The JSON representations generated by the Restful Objects viewer are in compact form if the xref:_deployment_types[deployment type] is SERVER (ie production), but will automatically be "pretty printed" (in other words indented) if the deployment type is PROTOTYPE.
http://git-wip-us.apache.org/repos/asf/isis/blob/477811d3/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime.adoc
index 1e49c4a..354db5a 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime.adoc
@@ -8,7 +8,7 @@ Isis' own configuration properties are simple key-value pairs, typically held in
[NOTE]
====
-Configuration properties for the viewers can be found in the <<Wicket Viewer>> chapter and the <<Restful Objects Viewer>> chapter. Likewise, details of configuring security (Apache Shiro) can be found in the <<Security>> chapter.
+Configuration properties for the viewers can be found in the xref:Wicket Viewer>> chapter and the <<Restful Objects Viewer>> chapter. Likewise[details of configuring security (Apache Shiro) can be found in the <<Security] chapter.
Also, note that by default the configuration values are part of the built WAR file. Details on how to override these configuration properties externally for different environments can be found in the <<Deployment>> chapter.
====
http://git-wip-us.apache.org/repos/asf/isis/blob/477811d3/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuration-files.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuration-files.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuration-files.adoc
index c5ddffe..e070b52 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuration-files.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuration-files.adoc
@@ -10,9 +10,9 @@ The `WEBINF/isis.properties` file is always read and must exist.
In addition, the following other properties are searched for and if present also read:
-* `viewer_wicket.properties` - if the <<_wicket_viewer_2, Wicket UI (viewer)>> is in use
+* `viewer_wicket.properties` - if the xref:_wicket_viewer_2[Wicket UI (viewer)] is in use
-* `viewer_restfulobjects.properties` - if the <<_restful_objects_viewer, Restful Objects REST API (viewer)>> is in use
+* `viewer_restfulobjects.properties` - if the xref:_restful_objects_viewer[Restful Objects REST API (viewer)] is in use
* `viewer.properties` - for any shared UI configuration
@@ -64,7 +64,7 @@ The `isis.properties` file has three configuration properties in particular that
The values "datanucleus", "shiro" etc are actually aliases for concrete implementations listed in Isis' `installer-registry.properties` file (in `isis-core-runtime.jar`). It is -- at least in theory -- possible to specify a fully qualified class name to replace any of these components. In practice only the two security APIs are actually simple enough for this to be viable.
====
-As for the viewers, these are specified indirectly by way of the filters and servlets in the `web.xml` file (discussed <<_configuring_the_webapp, below>>). However, the configuration of which viewers to initialize is declared through a context parameter:
+As for the viewers, these are specified indirectly by way of the filters and servlets in the `web.xml` file (discussed xref:_configuring_the_webapp[below]). However, the configuration of which viewers to initialize is declared through a context parameter:
[source,xml]
http://git-wip-us.apache.org/repos/asf/isis/blob/477811d3/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-core.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-core.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-core.adoc
index 99c5618..746c54d 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-core.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-core.adoc
@@ -5,7 +5,7 @@
This section lists the core/runtime configuration properties recognized by Apache Isis.
-Configuration properties for the JDO/DataNucleus objectstore can be found in the <<_configuring_datanucleus, Configuring DataNucleus>> section elsewhere in this chapter.
+Configuration properties for the JDO/DataNucleus objectstore can be found in the xref:_configuring_datanucleus[Configuring DataNucleus] section elsewhere in this chapter.
Configuration properties for the viewers can be found in the <<Wicket Viewer>> chapter and the <<Restful Objects Viewer>> chapter.
@@ -31,7 +31,7 @@ Configuration properties for the viewers can be found in the <<Wicket Viewer>> c
`translation.po.mode`
| `read`,`write`
|Whether to force the `TranslationService` into either read or write mode. +
-See <<_i18n, i18n support>> to learn more about the translation service.
+See xref:_i18n[i18n support] to learn more about the translation service.
|`isis.persistor.` +
`disableConcurrencyChecking`
@@ -42,35 +42,35 @@ See <<_i18n, i18n support>> to learn more about the translation service.
`cssClassFa.patterns`
|regex:fa-icon,regex2:fa-icon2,...
|Comma separated list of key:value pairs, where the key is a regex matching action names (eg `create.*`) and the value is a link:fortawesome.github.io/Font-Awesome/icons/[font-awesome] icon name (eg `fa-plus`) to be applied (as per `@CssClassFa()`) to all action members matching the regex. +
-See <<_user-guide_how-tos_ui-hints_action-icons-and-css, UI hints>> for more details.
+See xref:_user-guide_how-tos_ui-hints_action-icons-and-css[UI hints] for more details.
|`isis.reflector.facet.` +
`cssClass.patterns`
|regex:css1,regex2:css2,...
|Comma separated list of key:value pairs, where the key is a regex matching action names (eg `delete.*`) and the value is a link:http://getbootstrap.com/css/[Bootstrap] CSS button class (eg `btn-warning) to be applied (as per `@CssClass()`) to all action members matching the regex. +
-See <<_user-guide_how-tos_ui-hints_action-icons-and-css, UI hints>> for more details.
+See xref:_user-guide_how-tos_ui-hints_action-icons-and-css[UI hints] for more details.
|`isis.reflector.facets`
|`FQCN`
|Fully qualified class names of a custom implementation of `ProgrammingModel` interface.
-See <<_finetuning, finetuning the programming model>> for more details.
+See xref:_finetuning[finetuning the programming model] for more details.
|`isis.reflector.facets.` +
`include`
|`FQCN`,`FQCN2`,...
|Fully qualified class names of (new, custom) facet factory classes to be included to the programming model. +
-See <<_finetuning, finetuning the programming model>> for more details.
+See xref:_finetuning[finetuning the programming model] for more details.
|`isis.reflector.facets.` +
`exclude`
|`FQCN`,`FQCN2`,...
|Fully qualified class names of (existing, built-in) facet factory classes to be included to the programming model. +
-See <<_finetuning, finetuning the programming model>> for more details.
+See xref:_finetuning[finetuning the programming model] for more details.
|`isis.reflector.validator`
|`FQCN`
|Custom implementation of `MetaModelValidator` (in the `org.apache.isis.core.metamodel.specloader.validator` package) +
-See <<_custom_validator, Custom Validator>> to learn more.
+See xref:_custom_validator[Custom Validator] to learn more.
|`isis.reflector.validator.` +
`allowDeprecated`
@@ -80,8 +80,8 @@ See <<_custom_validator, Custom Validator>> to learn more.
|`isis.reflector.` +
`layoutMetadataReaders`
|`FQCN`,`FQCN2`,...
-|Fully qualified class names of classes to be instantiated to read layout metadata, as used in for <<_dynamic_object_layout, dynamic layout>>s. +
-See <<_layout_metadata_reader, Layout Metadata Reader>> for more information.
+|Fully qualified class names of classes to be instantiated to read layout metadata, as used in for xref:_dynamic_object_layout[dynamic layout]s. +
+See xref:_layout_metadata_reader[Layout Metadata Reader] for more information.
|===
http://git-wip-us.apache.org/repos/asf/isis/blob/477811d3/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus.adoc
index 67eb300..d2dec84 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus.adoc
@@ -7,7 +7,7 @@ Apache Isis programmatically configures DataNucleus; any Isis properties with th
DataNucleus will for itself also and read the `META-INF/persistence.xml`; at a minimum this defines the name of the "persistence unit". n theory it could also hold mappings, though in 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 <<_overriding_jdo_annotations, Overriding JDO Annotatons>> for further discussion.
+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:_overriding_jdo_annotations[Overriding JDO Annotatons] for further discussion.
include::_ug_runtime_configuring-datanucleus_properties.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/477811d3/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_disabling-persistence-by-reachability.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_disabling-persistence-by-reachability.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_disabling-persistence-by-reachability.adoc
index 5c0b109..b38bb92 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_disabling-persistence-by-reachability.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_disabling-persistence-by-reachability.adoc
@@ -22,7 +22,7 @@ We therefore recommend that you disable persistence-by-reachability by adding th
isis.persistor.datanucleus.impl.datanucleus.persistenceByReachabilityAtCommit=false
----
-This change has been made to the <<_simpleapp_archetype, SimpleApp Archetype>>
+This change has been made to the xref:_simpleapp_archetype[SimpleApp archetype]
If you do disable this feature, then you will (of course) need to ensure that you explicitly persist all entities using the `DomainObjectContainer#persist(.)` or `DomainObjectContainer#persistIfNotAlready(.)` methods.
http://git-wip-us.apache.org/repos/asf/isis/blob/477811d3/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_eagerly-registering-entities.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_eagerly-registering-entities.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_eagerly-registering-entities.adoc
index 3748ac3..33561c6 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_eagerly-registering-entities.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_eagerly-registering-entities.adoc
@@ -26,7 +26,7 @@ The value of this property can be a comma-separated list (if there is more than
== Integration Testing
-The `IsisConfigurationForJdoIntegTests`, recommended for use in <<_integration_testing, Integration Testing>> provides the `#addRegisterEntitiesPackagePrefix()` method to set up this configuration property:
+The `IsisConfigurationForJdoIntegTests`, recommended for use in xref:_integration_testing[Integration Testing] provides the `#addRegisterEntitiesPackagePrefix()` method to set up this configuration property:
[source,java]
.Integration test bootstrapping
http://git-wip-us.apache.org/repos/asf/isis/blob/477811d3/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_properties.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_properties.adoc
index a76fa6a..af63f75 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_properties.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuring-datanucleus_properties.adoc
@@ -22,7 +22,7 @@ These configuration properties are typically stored in `WEB-INF/persistor_datanu
`RegisterEntities.packagePrefix`
| fully qualified package names (CSV)
| of class names; specifies the entities early rather than allow DataNucleus to find the entities lazily. Strongly recommended (subtle issues can sometimes arise if lazy discovery is used).
-Further <<_registering_entity_types, discussion below>>.
+Further xref:_registering_entity_types[discussion below].
|`isis.persistor.datanucleus.` +
`PublishingService.serializedForm`
@@ -51,7 +51,7 @@ Further <<_registering_entity_types, discussion below>>.
`datanucleus.persistenceByReachabilityAtCommit`
|`false`
|We recommend this setting is disabled. +
-Further <<_disabling_persistence_by_reachability, discussion below>>.
+Further xref:_disabling_persistence_by_reachability[discussion below].
|===
http://git-wip-us.apache.org/repos/asf/isis/blob/477811d3/adocs/documentation/src/main/asciidoc/user-guide/_ug_security.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security.adoc
index b5983ad..b88673d 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security.adoc
@@ -14,7 +14,7 @@ Isis has two levels of permissions. _Read_ permission means that the user can v
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 <<_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:_simpleapp_archetype[SimpleApp archetype] is 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. Isis in turn extends this with its `IsisLdapRealm`, which provides more flexibility for both group/role and role/permissions management.
@@ -25,7 +25,7 @@ In addition to Isis' Shiro-based implementation of its authentication and author
[NOTE]
.What about auditing?
====
-A further aspect of security is auditing: recording what data was modified by which user. Apache Isis does define two service APIs -- <<_command_service, `CommandService`>> and <<_auditing_service, `AuditingService`>> -- that provide hooks to track which actions (commands) are invoked, and what data was modified as a result (auditing).
+A further aspect of security is auditing: recording what data was modified by which user. Apache Isis does define two service APIs -- xref:_command_service[`CommandService`] and xref:_auditing_service[`AuditingService`] -- that provide hooks to track which actions (commands) are invoked, and what data was modified as a result (auditing).
Isis does not itself provide any in-built implementations of these APIs, but there are implementations within http://isisaddons.org[Isis Addons] (non-ASF), namely the http://github.com/isisaddons/isis-module-command}[Isis addons' command] module and the http://github.com/isisaddons/isis-module-auditing}[Isis addons' auditing] module.
====
http://git-wip-us.apache.org/repos/asf/isis/blob/477811d3/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_api-for-applications.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_api-for-applications.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_api-for-applications.adoc
index 5655fe2..33cdd19 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_api-for-applications.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_api-for-applications.adoc
@@ -12,7 +12,7 @@ Still, on very rare occasion you may have a need, in which case you can either u
== Using Isis` `DomainObjectContainer`
-The <<_domain_object_container, `DomainObjectContainer`>> service exposes the following API:
+The xref:_domain_object_container[`DomainObjectContainer`] service exposes the following API:
[source,java]
----
http://git-wip-us.apache.org/repos/asf/isis/blob/477811d3/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_configuring-isis-to-use-shiro.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_configuring-isis-to-use-shiro.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_configuring-isis-to-use-shiro.adoc
index 1515608..12f919d 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_configuring-isis-to-use-shiro.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_configuring-isis-to-use-shiro.adoc
@@ -8,7 +8,7 @@ Apache Isis' security mechanism is configurable, specifying an `Authenticator` a
[TIP]
====
-The <<_simpleapp_archetype, SimpleApp archetype>> is pre-configured to use Apache Shiro, so much of what follows is set up already.
+The xref:_simpleapp_archetype[SimpleApp archetype] is pre-configured to use Apache Shiro, so much of what follows is set up already.
====
== Specifying Shiro as the security mechanism
http://git-wip-us.apache.org/repos/asf/isis/blob/477811d3/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-ini-realm.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-ini-realm.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-ini-realm.adoc
index a1bad63..21289a4 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-ini-realm.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-ini-realm.adoc
@@ -6,7 +6,7 @@
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 <<_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 the xref:_simpleapp_archetype[SimpleApp archetype] is configured to use this realm.
The diagram below shows the Isis and components involved:
@@ -104,7 +104,7 @@ com.mycompany.myapp # ditto
[TIP]
====
-The format of the permissions string is configurable in Shiro, and Isis uses this to provide an extended wildcard format, described <<_enhanced_wildcard_permission, here>>.
+The format of the permissions string is configurable in Shiro, and Isis uses this to provide an extended wildcard format, described xref:_enhanced_wildcard_permission[here].
====
http://git-wip-us.apache.org/repos/asf/isis/blob/477811d3/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-isis-enhanced-wildcard-permission.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-isis-enhanced-wildcard-permission.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-isis-enhanced-wildcard-permission.adoc
index d94372d..5b21d0a 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-isis-enhanced-wildcard-permission.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_shiro-isis-enhanced-wildcard-permission.adoc
@@ -4,7 +4,7 @@
:_imagesdir: images/
-If using the text-based <<_shiro_ini_realm, `IniRealm`>> or <<_isis_ldap_realm, Isis' LDAP realm>>, then note that Shiro also allows the string representation of the permissions to be mapped (resolved) to alternative `Permission` instances. Isis provides its own `IsisPermission` which introduces the concept of a "veto".
+If using the text-based xref:_shiro_ini_realm[`IniRealm`] or xref:_isis_ldap_realm[Isis' LDAP realm], then note that Shiro also allows the string representation of the permissions to be mapped (resolved) to alternative `Permission` instances. Isis provides its own `IsisPermission` which introduces the concept of a "veto".
A vetoing permission is one that prevents access to a feature, rather than grants it. This is useful in some situations where most users have access to most features, and only a small number of features are particularly sensitive. The configuration can therefore be set up to grant fairly broad-brush permissions and then veto permission for the sensitive features for those users that do not have access.
http://git-wip-us.apache.org/repos/asf/isis/blob/477811d3/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_usage-by-isis-viewers.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_usage-by-isis-viewers.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_usage-by-isis-viewers.adoc
index 667adde..8aac375 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_usage-by-isis-viewers.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security_usage-by-isis-viewers.adoc
@@ -5,7 +5,7 @@
-By and large the security mechanisms within Isis are transparent to the rest of the framework (the <<_wicket_viewer, Wicket Viewer>> and <<_restful_objects_viewer, Restful viewer>>, and the overall <<_runtime, runtime>>).
+By and large the security mechanisms within Isis are transparent to the rest of the framework (the xref:_wicket_viewer[Wicket Viewer] and xref:_restful_objects_viewer[Restful viewer], and the overall xref:_runtime[runtime]).
That said, it is the responsibility of the viewers to ensure that there is a viewers to ensure that for each request there is a valid user session present. The sections below explain how this works.
@@ -14,7 +14,7 @@ That said, it is the responsibility of the viewers to ensure that there is a vie
== Wicket Viewer
-The <<_wicket_viewer, Wicket viewer>> defines a relatively small number of pages (by which we mean subclasses of link:http://ci.apache.org/projects/wicket/apidocs/6.0.x/org/apache/wicket/markup/html/WebPage.html[`org.apache.wicket.markup.html.WebPage`]):
+The xref:_wicket_viewer[Wicket viewer] defines a relatively small number of pages (by which we mean subclasses of link:http://ci.apache.org/projects/wicket/apidocs/6.0.x/org/apache/wicket/markup/html/WebPage.html[`org.apache.wicket.markup.html.WebPage`]):
* about page
* action prompt page
@@ -36,7 +36,7 @@ which means that they can only be accessed by a user with an authenticated sessi
[TIP]
====
-The sign-in page to render is pluggable; see <<_custom_pages, extensions chapter>> for details.
+The sign-in page to render is pluggable; see xref:_custom_pages[extensions chapter] for details.
====
In the sign-in page the viewer calls to the Isis Authenticator API, and obtains back a user/role. It also adds in its special reserved role (per the annotation above) and then continues on to whichever page the user was attempting to access (usually the home page).
@@ -48,14 +48,14 @@ Similarly, for those object members that _are_ visible, the viewer also checks i
=== User-registration
-As well as providing a sign-in screen, the Wicket viewer also provides the ability for <<_user_registration, users to self-register>>. By and large this operates outside of Isis' security mechanisms; indeed the various pages (sign-up, sign-up verification, password reset) are all rendered _without_ there being any current user session. These pages all "reach inside" Isis framework using a mechanism similar to <<_headless_access>> in order to actually do their stuff.
+As well as providing a sign-in screen, the Wicket viewer also provides the ability for xref:_user_registration[users to self-register]. By and large this operates outside of Isis' security mechanisms; indeed the various pages (sign-up, sign-up verification, password reset) are all rendered _without_ there being any current user session. These pages all "reach inside" Isis framework using a mechanism similar to <<_headless_access>> in order to actually do their stuff.
[TIP]
====
-The sign-in verification page to render is pluggable; see <<_custom_pages, extensions chapter>> for details.
+The sign-in verification page to render is pluggable; see xref:_custom_pages[extensions chapter] for details.
====
-User registration is only available if the <<_user_registration_service, `UserRegistrationService`>> is configured; this is used by the framework to actually create new instances of the user as accessed by the corresponding (Shiro) realm.
+User registration is only available if the xref:_user_registration_service[`UserRegistrationService`] is configured; this is used by the framework to actually create new instances of the user as accessed by the corresponding (Shiro) realm.
Because Shiro realms are pluggable, the Isis framework does not provide default implementations of this service. However, if you are using the http://github.com/isisaddons/isis-module-security}[Isis addons' security] module (non-ASF), then this module _does_ provide an implementation (that, as you might expect, creates new "user" domain entities).
@@ -65,7 +65,7 @@ If you are using an LDAP realm and want to enable user-self registration then yo
== Restful Objects Viewer
-Unlike the Wicket viewer, the <<_restful_objects_viewer, Restful Objects viewer>> does _not_ provide any sort of login page; rather it provides a pluggable authentication strategy, delegated to by the `IsisSessionFilter` filter defined in `web.xml`. The authentication strategy is responsible for ensuring that a session is available for the REST resource.
+Unlike the Wicket viewer, the xref:_restful_objects_viewer[Restful Objects viewer] does _not_ provide any sort of login page; rather it provides a pluggable authentication strategy, delegated to by the `IsisSessionFilter` filter defined in `web.xml`. The authentication strategy is responsible for ensuring that a session is available for the REST resource.
The API of `AuthenticationSessionStrategy` is simply:
http://git-wip-us.apache.org/repos/asf/isis/blob/477811d3/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_key-classes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_key-classes.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_key-classes.adoc
index 9244f6e..38de5d1 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_key-classes.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_key-classes.adoc
@@ -8,7 +8,7 @@
There are some key framework classes that make up the spec support; these are discussed below.
-NOTE: some of these are also used by Isis' <<_integration_test_support, Integration Test support>>.
+NOTE: some of these are also used by Isis' xref:_integration_test_support[Integration Test support].
http://git-wip-us.apache.org/repos/asf/isis/blob/477811d3/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_maven-configuration.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_maven-configuration.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_maven-configuration.adoc
index 88bbc7f..396c1a4 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_maven-configuration.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_maven-configuration.adoc
@@ -6,7 +6,7 @@
-Apache Isis' BDD spec support is automatically configured if you use the <<_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:_simpleapp_archetype[SimpleApp archetype]. To set it up manually, update the `pom.xml` of your domain object model module:
[source,xml]
----
http://git-wip-us.apache.org/repos/asf/isis/blob/477811d3/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_writing-a-bdd-spec.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_writing-a-bdd-spec.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_writing-a-bdd-spec.adoc
index 5cdc050..c86bb09 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_writing-a-bdd-spec.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_bdd-spec-support_writing-a-bdd-spec.adoc
@@ -20,10 +20,10 @@ For example, given a feature that involves `Customer` and `Order`, have the step
+
The `glue` attribute of the Cucumber-JVM JUnit runner eallows you to indicate which package(s) should be recursively searched to find any glue.
-* a system initializer class. You can reuse the system initializer from any integration tests (as described in <<_integration_test_support, Integration Test Support>>, bootstrapping section).
+* a system initializer class. You can reuse the system initializer from any integration tests (as described in xref:_integration_test_support[Integration Test Support], bootstrapping section).
-Here's an example of a feature from the <<_simpleapp_archetype, SimpleApp archetype>>:
+Here's an example of a feature from the xref:_simpleapp_archetype[SimpleApp archetype]:
[source]
----
@@ -48,7 +48,7 @@ Apache Isis does also support running BDD specs in unit test mode; by annotating
To support unit testing scope 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 <<_simpleapp_archetype, SimpleApp archetype>>. For those who do require faster-executing test suite, it's worthwhile knowing that 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:_simpleapp_archetype[SimpleApp archetype]. For those who do require faster-executing test suite, it's worthwhile knowing that Isis can support this.
====
@@ -71,7 +71,7 @@ public class RunSpecs {
}
----
-The JSON formatter allows integration with enhanced reports, for example as provided by http://www.masterthought.net/section/cucumber-reporting[Masterthought.net] (screenshots at end of page). (Commented out) configuration for this is provided in the <<_simpleapp_archetype, SimpleApp archetype>>.
+The JSON formatter allows integration with enhanced reports, for example as provided by http://www.masterthought.net/section/cucumber-reporting[Masterthought.net] (screenshots at end of page). (Commented out) configuration for this is provided in the xref:_simpleapp_archetype[SimpleApp archetype].
The bootstrapping of Isis can be moved into a `BootstrappingGlue` step definition:
http://git-wip-us.apache.org/repos/asf/isis/blob/477811d3/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_fixture-scripts_api-and-usage.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_fixture-scripts_api-and-usage.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_fixture-scripts_api-and-usage.adoc
index b2d1ba2..86b0ed4 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_fixture-scripts_api-and-usage.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_fixture-scripts_api-and-usage.adoc
@@ -14,7 +14,7 @@ Let's look at `FixtureScripts` domain service in more detail first.
== `FixtureScripts`
-In your code you subclass `FixtureScripts` domain service primarily just to specify which package to search for. For example, here's the service that's generated by the <<_simpleapp_archetype, SimpleApp archetype>>:
+In your code you subclass `FixtureScripts` domain service primarily just to specify which package to search for. For example, here's the service that's generated by the xref:_simpleapp_archetype[SimpleApp archetype]:
[source,java]
----
@@ -77,7 +77,7 @@ If you had defined many fixture scripts then a drop-down might become unwieldy,
----
-You are free, of course, to add additional "convenience" actions into it if you wish for the most commonly used/demo'd setups ; you'll find that the <<_simpleapp_archetype, SimpleApp archetype>> adds this additional action:
+You are free, of course, to add additional "convenience" actions into it if you wish for the most commonly used/demo'd setups ; you'll find that the xref:_simpleapp_archetype[SimpleApp archetype] adds this additional action:
[source,java]
----
@@ -100,7 +100,7 @@ Let's now look at the `FixtureScript` class, where there's a bit more going on.
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 <<_simpleapp_archetype, SimpleApp archetype>>:
+Here's the `RecreateSimpleObjects` fixture script from the xref:_simpleapp_archetype[SimpleApp archetype]:
[source,java]
----
@@ -197,7 +197,7 @@ public class SimpleObjectCreate extends FixtureScript { // <1>
<3> output property: the created simple object
<4> the mandatory execute(...) API
<5> the `checkParam(...)` (inherited from `FixtureScript`) will check that the "name" property has been populated (using Java's Reflection API) and throw an exception if not
-<6> wrap the injected `SimpleObjects` domain service (using the <<_wrapper_factory, `WrapperFactory`>>) to simulate interaction through the UI...
+<6> wrap the injected `SimpleObjects` domain service (using the xref:_wrapper_factory[`WrapperFactory`]) to simulate interaction through the UI...
<7> .. and actually create the object using the "create" business action of that service
<8> add the resulting object to the execution context; this makes the object available to access if run from the UI
<9> inject the domain service into the fixture script
@@ -212,7 +212,7 @@ public class SimpleObjectCreate extends FixtureScript { // <1>
Fixture scripts can be called from integration tests just the same way that fixture scripts can call one another.
-For example, here's an integration test from the <<_simpleapp_archetype, SimpleApp archetype>>:
+For example, here's an integration test from the xref:_simpleapp_archetype[SimpleApp archetype]:
[source,java]
----
@@ -255,7 +255,7 @@ public class SimpleObjectIntegTest extends SimpleAppIntegTest {
There are lots of ways to organize fixture scripts, but we've used them as either:
-* a fairly flat style, eg as in the <<_simpleapp_archetype, SimpleApp archetype>>, also as in the http://github.com/isisaddons/isis-app-todoapp}[Isis addons' todoapp];
+* a fairly flat style, eg as in the xref:_simpleapp_archetype[SimpleApp archetype], also as in the http://github.com/isisaddons/isis-app-todoapp}[Isis addons' todoapp];
* 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].
@@ -275,9 +275,9 @@ With the composite style, we rely on each fixture script to set up its own prere
image::{_imagesdir}testing/fixture-scripts/composite.png[width="550px",link="_imagesdir}testing/fixture-scripts/composite.png"]
-Back in the earlier <<_fixturescripts, `FixtureScripts`>> 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 xref:_fixturescripts[`FixtureScripts`] 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 <<_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).
+As already noted , the app generated by the xref:_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.
http://git-wip-us.apache.org/repos/asf/isis/blob/477811d3/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_bootstrapping.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_bootstrapping.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_bootstrapping.adoc
index c987e58..5db4c63 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_bootstrapping.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_bootstrapping.adoc
@@ -15,7 +15,7 @@ Since the integration tests don't depend on the `webapp` module, it's necessary
We hope to simplify the way this works in future versions of Isis.
====
-The example code in this section is taken from the app generated by the <<_simpleapp_archetype, SimpleApp archetype>>.
+The example code in this section is taken from the app generated by the xref:_simpleapp_archetype[SimpleApp archetype].
@@ -48,7 +48,7 @@ private static class SimpleAppSystemBuilder extends IsisSystemForTest.Builder {
<1> subclass the framework-provided `IsisSystemForTest.Builder`.
<2> equivalent to `isis.persistor=datanucleus` in `isis.properties`
<3> specify the `isis.services` key in `isis.properties` (where "domainapp" is the base package for all classes within the app)
-<4> `IsisConfigurationForJdoIntegTests` has pre-canned configuration for using an in-memory HSQLDB and other standard settings; more on this <<_isisconfigurationforjdointegtests, below>>.
+<4> `IsisConfigurationForJdoIntegTests` has pre-canned configuration for using an in-memory HSQLDB and other standard settings; more on this xref:_isisconfigurationforjdointegtests[below].
<5> equivalent to `isis.persistor.datanucleus.RegisterEntities.packagePrefix` key (typically in `persistor_datanucleus.properties`
@@ -185,7 +185,7 @@ public abstract class SimpleAppIntegTest {
----
<1> ensure that logging messages don't get swallowed
<2> initialize the Isis runtime
-<3> primarily exists to support the writing of <<_bdd_spec_support, BDD specifications>>, but also enables finer-grained management of sessions/transactions (discussed below).
+<3> primarily exists to support the writing of xref:_bdd_spec_support[BDD specifications], but also enables finer-grained management of sessions/transactions (discussed below).
@@ -220,7 +220,7 @@ Although not mandatory, this provides a number of helper/convenience methods and
<1> ensures an Isis session/transaction running for each test
<2> sets up a JMock context (using Isis' extension to JMock as described in <<JMock Extensions>>
<3> standard JUnit rule for writing tests that throw exceptions
-<4> to capture messages that require translation, as described in <<_i18n_support, i18 support>>.
+<4> to capture messages that require translation, as described in xref:_i18n_support[i18 support].
All of these rules could be inlined in your own base class; as we say, they are a convenience.
http://git-wip-us.apache.org/repos/asf/isis/blob/477811d3/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_maven-configuration.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_maven-configuration.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_maven-configuration.adoc
index 609c52b..ddbff67 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_maven-configuration.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_maven-configuration.adoc
@@ -4,7 +4,7 @@
:_imagesdir: images/
-Apache Isis' integration test support is automatically configured if you use the <<_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:_simpleapp_archetype[SimpleApp archetype]. To set it up manually, update the `pom.xml` of your domain object model module:
[source]
----
http://git-wip-us.apache.org/repos/asf/isis/blob/477811d3/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_typical-usage.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_typical-usage.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_typical-usage.adoc
index 1f2dd0b..4e634a2 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_typical-usage.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_typical-usage.adoc
@@ -57,7 +57,7 @@ public class ToDoItemIntegTest extends AbstractToDoIntegTest {
...
}
----
-<1> the <<_fixture_scripts, `FixtureScripts`>> domain service is injected, providing us with the ability to run fixture scripts
+<1> the xref:_fixture_scripts[`FixtureScripts`] domain service is injected, providing us with the ability to run fixture scripts
<2> likewise, an instance of the `ToDoItems` domain service is injected. We'll use this to lookup...
<3> the object under test, held as a field
<4> the fixture script for this test; it deletes all existing todo items (for the current user only) and then recreates them
http://git-wip-us.apache.org/repos/asf/isis/blob/477811d3/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_wrapper-factory.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_wrapper-factory.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_wrapper-factory.adoc
index e1f0d74..6faec56 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_wrapper-factory.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_integ-test-support_wrapper-factory.adoc
@@ -85,7 +85,7 @@ If there is a supporting `addTo...()` or `removeFrom...()` method, then these ca
+
[NOTE]
====
-In this respect the wrapper is more functional than the <<_wicket_viewer, Wicket viewer>> (which does not expose the ability to mutate collections directly).
+In this respect the wrapper is more functional than the xref:_wicket_viewer[Wicket viewer] (which does not expose the ability to mutate collections directly).
====
* for *_object actions_* the test can call the action method itself.
@@ -144,7 +144,7 @@ public void subscriberReceivesEvents() throws Exception {
then(evHolder[0].getIdentifier().getMemberName()).isEqualTo("completed");
}
----
-<1> inject <<__code_EventBusService_code, `EventBusService`>> into this test
+<1> inject xref:__code_EventBusService_code[`EventBusService`] into this test
<2> holder for subscriber to capture event to
<3> subscriber's callback, using the guava subscriber syntax
<4> invoking the domain object using the wrapper
http://git-wip-us.apache.org/repos/asf/isis/blob/477811d3/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_overview.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_overview.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_overview.adoc
index 790c8bc..d61c0e3 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_overview.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_overview.adoc
@@ -51,7 +51,7 @@ When we talk about integration tests/specs here, we mean tests that exercise the
For most other frameworks that would require having to test the application in a very heavy weight/fragile fashion using a tool such as link:http://seleniumhq.org[Selenium], driving a web browser to navigate . In this regard though, Isis has a significant trick up its sleeve. Because Isis implements the naked objects pattern, it means that the UI is generated automatically from the UI. This therefore allows for other implementations of the UI.
-The <<_wrapper_factory, `WrapperFactory`>> domain service allows a test to wrap domain objects and thus to interact with said objects "as if" through the UI:
+The xref:_wrapper_factory[`WrapperFactory`] domain service allows a test to wrap domain objects and thus to interact with said objects "as if" through the UI:
image::{_imagesdir}testing/integ-tests.png[width="700px"]
@@ -124,7 +124,7 @@ In the previous section we discussed using given/when/then as a form of organizi
For integration tests though it can be difficult to keep the "given" short; there could be a lot of prerequisite data that needs to exist before you can actually exercise your system. Moreover, however we do set up that data, but we also want to do so in a way that is resilient to the system changing over time.
-The solution that Isis provides is a domain service called <<_fixture_scripts, Fixture Scripts>>, that defines a pattern and supporting classes to help ensure that the "data setup" for your tests are reusable and maintainable over time.
+The solution that Isis provides is a domain service called xref:_fixture_scripts[Fixture Scripts], that defines a pattern and supporting classes to help ensure that the "data setup" for your tests are reusable and maintainable over time.
http://git-wip-us.apache.org/repos/asf/isis/blob/477811d3/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_unit-test-support_maven-configuration.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_unit-test-support_maven-configuration.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_unit-test-support_maven-configuration.adoc
index 26f00ed..5ed8f63 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_unit-test-support_maven-configuration.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_testing_unit-test-support_maven-configuration.adoc
@@ -4,7 +4,7 @@
:_imagesdir: images/
-Apache Isis' unit test support is automatically configured if you use the <<_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:_simpleapp_archetype[SimpleApp archetype]. To set it up manually, update the `pom.xml` of your domain object model module:
[source,xml]
----
http://git-wip-us.apache.org/repos/asf/isis/blob/477811d3/adocs/documentation/src/main/asciidoc/user-guide/_ug_troubleshooting_enabling-logging.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_troubleshooting_enabling-logging.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_troubleshooting_enabling-logging.adoc
index 533273c..0443cc2 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_troubleshooting_enabling-logging.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_troubleshooting_enabling-logging.adoc
@@ -17,7 +17,7 @@ As per the http://www.datanucleus.org/products/accessplatform/logging.html[DN lo
Configure log4jdbc JDBC rather than the vanilla driver (see `WEB-INF/persistor_datanucleus.properties`) and configure log4j logging (see `WEB-INF/logging.properties`).
-There are examples of both in the <<_simpleapp_archetype, SimpleApp archetype>>.
+There are examples of both in the xref:_simpleapp_archetype[SimpleApp archetype].
== In the Database
http://git-wip-us.apache.org/repos/asf/isis/blob/477811d3/adocs/documentation/src/main/asciidoc/user-guide/_ug_tutorials_pet-clinic.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_tutorials_pet-clinic.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_tutorials_pet-clinic.adoc
index bc33af6..cb941d5 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_tutorials_pet-clinic.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_tutorials_pet-clinic.adoc
@@ -4,7 +4,7 @@
:_imagesdir: images/
-This is a step-by-step tutorial to build up a simple "petclinic" application, starting from the <<_simpleapp_archetype, SimpleApp archetype>>.
+This is a step-by-step tutorial to build up a simple "petclinic" application, starting from the xref:_simpleapp_archetype[SimpleApp archetype].
It consists of just three domain classes:
@@ -165,7 +165,7 @@ Go back to the splash screen, and quit the app. Note that the database runs in-m
== Dev environment
-Set up <<_setting_up_a_development_environment, an IDE>> and import the project to be able to run and debug the app.
+Set up xref:_setting_up_a_development_environment[an IDE] and import the project to be able to run and debug the app.
Then set up a launch configuration so that you can run the app from within the IDE. To save having to run the fixtures
every time, specify the following system properties: