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/28 15:03:47 UTC
[21/29] isis git commit: ISIS-1133: fixing references,
breaking out annotation pages for each attribute (for more consistent
cross-referencing).
http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-XmlSnapshotService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-XmlSnapshotService.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-XmlSnapshotService.adoc
index 24c0326..e48f30e 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-XmlSnapshotService.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-api_manpage-XmlSnapshotService.adoc
@@ -7,3 +7,131 @@
IMPORTANT: TODO
+
+Title: Wrapper Factory
+
+The 'wrapper' factory provides the ability to enforce business rules for programmatic interactions between domain objects. For example, if the calling object attempts to modify an unmodifiable property on the target object, then an exception will be thrown. Said another way: interactions are performed "as if" they are through the viewer.
+
+This capability goes beyond enforcing the (imperative) constraints within the `hideXxx()`, `disableXxx()` and `validateXxx()` supporting methods; it also enforces (declarative) constraints such as those represented by annotations, eg `@MaxLength` or `@Regex`.
+
+This capability is frequently used within link:../../core/integtestsupport.html[integration tests], but can also be used in production code. (There are analogies that can be drawn here with the way that JEE beans can interact through an EJB local interface).
+
+=== In a little more detail
+
+The service works by returning a "wrapper" around a supplied domain object (a CGLIB proxy), and it is this wrapper that ensures hat the hide/disable/validate rules implies by the Isis programming model are enforced. The wrapper can be interacted with as follows:
+
+* a get method for properties or collections
+* a set method for properties
+* an addTo or removeFrom method for collections
+* any action
+
+Calling any of the above methods may result in a (subclass of) `InteractionException` if the object disallows it. For example, if a property is annotated with `@Hidden` then a `HiddenException` will be thrown. Similarly if an action has a `validateXxx()` method and the supplied arguments are invalid then an `InvalidException` will be thrown.
+
+In addition, the following methods may also be called:
+
+* the `title()` method
+* any `defaultXxx()` or `choicesXxx()` method
+
+An exception will be thrown if any other methods are thrown.
+
+=== API
+
+The `WrapperFactory` API is defined as follows:
+
+[source]
+----
+@Hidden
+public interface WrapperFactory {
+
+ public static enum ExecutionMode { EXECUTE, NO_EXECUTE }
+
+ public <T> T wrap(T domainObject);
+ public <T> T wrap(T domainObject, ExecutionMode mode);
+ public <T> T unwrap(T possibleWrappedDomainObject);
+
+ public <T> boolean isWrapper(T possibleWrappedDomainObject);
+
+ public List<InteractionListener> getListeners();
+ public boolean addInteractionListener(InteractionListener listener);
+ public boolean removeInteractionListener(InteractionListener listener);
+ public void notifyListeners(InteractionEvent ev);
+
+}
+----
+
+where:
+
+* `ExecutionMode` determines whether interactions with the wrapper are
+ actually passed onto the underlying domain object.
+* `wrap(...)` returns the wrapper around the underlying domain object (this
+ does nothing if the object has already been wrapped)
+* `unwrap(...)` returns the underlying domain object within the wrapper (this
+ does nothing if the object is not a wrapper)
+
+The API also provides the ability to register `InteractionListener`s with the
+wrapper.
+
+=== Usage
+
+The caller will typically obtain the target object (eg from some repository)
+and then use the injected `WrapperFactory` to wrap it before interacting
+with it.
+
+For example:
+
+[source]
+----
+public class CustomerAgent {
+
+ public void refundOrder(final Order order) {
+ final Order wrappedOrder = wrapperFactory.wrap(order);
+ try {
+ wrappedOrder.refund();
+ } catch(InteractionException ex) {
+ container.raiseError(ex.getMessage());
+ return;
+ }
+ }
+
+ ...
+ private WrapperFactory wrapperFactory; // injected
+ private DomainObjectContainer container; // injected
+}
+----
+
+Here the `Order`'s `refund()` action has various business logic. Rather than
+re-implement this logic, the `CustomerAgent` wraps the order in order to interact with it.
+
+=== Hints and Tips
+
+The link:./exception-recognizers.html[Exception Recognizers] provides the possibility
+to remove the boilerplate; any `InteractionException` could be automatically
+recognized and converted into a suitable message. The calling method could therefore
+simply propogate the exception:
+
+For example:
+
+[source]
+----
+public class CustomerAgent {
+
+ public void refundOrder(final Order order) throws InteractionException {
+ wrapperFactory.wrap(order).refund();
+ }
+
+ ...
+ private WrapperFactory wrapperFactory; // injected
+}
+----
+
+____
+
+At the time of writing Isis does not provide an out-of-the-box implementation
+of such an `ExceptionRecognizer`; but it should be simple enough to write one…
+
+____
+
+=== Automatically Available
+
+As of 1.6.0 this service is automatically on the classpath and registered; there is no need to configure in
+`isis.properties` or update your application's `pom.xml`.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi.adoc
index effdbea..078c175 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi.adoc
@@ -5,11 +5,11 @@
:_imagesdir: images/
-Apache Isis includes an extensive number of domain services for your domain objects to use; these are listed in xref:__a_id_chapter_a_reference_domain_services_(api)[Reference: Domain Services (API)]. But some of the services interfaces defined in the applib are intended to be used (primarily) not by your domain objects but instead by Isis itself.
+Apache Isis includes an extensive number of domain services for your domain objects to use; these are listed in xref:_ug_reference-services-api[Reference: Domain Services (API)]. But some of the services interfaces 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.
+A good example of this is the xref:_ug_reference-services-spi_manpage-AuditingService[`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 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 have categorized the service as an "API" service. This chapter therefore contains only the strictly SPI services.
+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:_ug_wicket-viewer[Wicket viewer]. The same is true of the xref:_ug_reference-services-api_manpage-EventBusService[`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 have categorized the service as an "API" service. This chapter therefore contains only the strictly SPI services.
include::_ug_reference-services-spi_aaa.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/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 f9623fd..7282936 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
@@ -52,9 +52,9 @@ IMPORTANT: TODO
|<<__code_classdiscoveryservice_code, `o.a.i.applib.` +
`services.classdiscovery` +
`ClassDiscoveryService`>>
-|Mechanism to locate (from the classpath) classes with a specific annotation (eg xref:__a_id_reference_annotations_manpage_a_code_domainservice_code[`@DomainService`])
+|Mechanism to locate (from the classpath) classes with a specific annotation (eg xref:_ug_reference-annotations_manpage-DomainService[`@DomainService`])
-Subtypes of a given type (eg xref:__a_id_reference_classes_super_manpage_a_code_fixturescript_code[`FixtureScript`]).
+Subtypes of a given type (eg xref:_ug_reference-classes_super_manpage-FixtureScript[`FixtureScript`]).
|`ClassDiscoveryService-` +
`UsingReflections` +
``o.a.i.core`` +
@@ -79,7 +79,7 @@ Subtypes of a given type (eg xref:__a_id_reference_classes_super_manpage_a_code_
|<<__code_emailnotificationservice_code, `o.a.i.applib.` +
`services.userreg` +
`EmailNotificationService`>>
-|Notify a user during xref:__a_id_reference_services_spi_manpage_a_code_userregistrationservice_code[self-registration] of users.
+|Notify a user during xref:_ug_reference-services-spi_manpage-UserRegistrationService[self-registration] of users.
|`EmailNotificationService-` +
`Default` +
``o.a.i.core`` +
@@ -90,7 +90,7 @@ a configured `EmailService`
|<<__code_eventserializer_code, `o.a.i.applib.` +
`services.publish` +
`EventSerializer`>>
-|Creates a representation of either an action invocation or a changed object being published through the xref:__a_id_reference_services_spi_manpage_a_code_publishingservice_code[`PublishingService`].
+|Creates a representation of either an action invocation or a changed object being published through the xref:_ug_reference-services-spi_manpage-PublishingService[`PublishingService`].
|`RestfulObjects-` +
`SpecEventSerializer` +
``o.ia.m.publishing`` +
@@ -113,7 +113,7 @@ a configured `EmailService`
|<<__code_localeprovider_code, `o.a.i.applib.` +
`services.i18n` +
`LocaleProvider`>>
-|Request-scoped service to return the locale of the current user, in support of i18n (ie so that the app's UI, messages and exceptions can be translated to the required locale by the xref:__a_id_reference_services_spi_manpage_a_code_translationservice_code[`TranslationService`].
+|Request-scoped service to return the locale of the current user, in support of i18n (ie so that the app's UI, messages and exceptions can be translated to the required locale by the xref:_ug_reference-services-spi_manpage-TranslationService[`TranslationService`].
|`LocaleProviderWicket` +
``o.a.i.viewer`` +
``isis-viewer-wicket-impl``
@@ -138,7 +138,7 @@ depends on: +
|<<__code_translationservice_code, `o.a.i.applib.` +
`services.i18n` +
`TranslationService`>>
-|Translate an app's UI, messages and exceptions for the current user (as per the locale provided by xref:__a_id_reference_services_spi_manpage_a_code_localprovider_code[`LocalProvider`].
+|Translate an app's UI, messages and exceptions for the current user (as per the locale provided by xref:_ug_reference-services-spi_manpage-LocaleProvider[`LocalProvider`].
|`TranslationServicePo` +
``o.a.i.core`` +
``isis-core-runtime``
@@ -150,7 +150,7 @@ depends on: +
|<<__code_translationsresolver_code, `o.a.i.applib.` +
`services.i18n` +
`TranslationsResolver`>>
-|Obtain translations for a particuar phrase and locale, in support of i18n (ie so that the app's UI, messages and exceptions can be translated to the required locale by the xref:__a_id_reference_services_spi_manpage_a_code_translationservice_code[`TranslationService`]
+|Obtain translations for a particuar phrase and locale, in support of i18n (ie so that the app's UI, messages and exceptions can be translated to the required locale by the xref:_ug_reference-services-spi_manpage-TranslationService[`TranslationService`]
|`TranslationsResolverWicket` +
``o.a.i.viewer`` +
``isis-viewer-wicket-impl``
@@ -185,7 +185,7 @@ Key:
* `o.ia.m` is an abbreviation for `org.isisaddons.module`
-Where an implementation is available (on the classpath) then it is always registered automatically (that is, they are all (with one exception) annotated with xref:__a_id_reference_annotations_manpage_a_code_domainservice_code[`@DomainService`]. The one exception is xref:__a_id_reference_services_spi_manpage_a_code_exceptionrecognizer_code[`ExceptionRecognizer`], which must be registered explicitly in `isis.properties`; this makes the service extensible (for new exceptions to be recognized).
+Where an implementation is available (on the classpath) then it is always registered automatically (that is, they are all (with one exception) annotated with xref:_ug_reference-annotations_manpage-DomainService[`@DomainService`]. The one exception is xref:_ug_reference-services-spi_manpage-ExceptionRecognizer[`ExceptionRecognizer`], which must be registered explicitly in `isis.properties`; this makes the service extensible (for new exceptions to be recognized).
@@ -222,7 +222,7 @@ Impl'n (g: a:)
|<<__code_contentnegotiationservice_code, `o.a.i.v.ro.` +
`rendering.service.conneg.` +
`ContentNegotiationService`>>
-|Encodes the algorithm that delegate to any registered xref:__a_id_reference_services_spi_manpage_a_code_contentmappingservice_code[`ContentMappingService`]s.
+|Encodes the algorithm that delegate to any registered xref:_ug_reference-services-spi_manpage-ContentMappingService[`ContentMappingService`]s.
|`ContentNegotiationService-` +
`XRoDomainType` +
``o.a.i.core`` +
http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-BackgroundCommandService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-BackgroundCommandService.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-BackgroundCommandService.adoc
index bcf7a2c..f51700a 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-BackgroundCommandService.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-BackgroundCommandService.adoc
@@ -11,3 +11,118 @@ IMPORTANT: TODO
For 1.7.0+, see the http://github.com/isisaddons/isis-module-command[Isis addons' Command module] (non-ASF).
+
+
+The `BackgroundCommandService` supports the link:./background-service.html[BackgroundService], persisting action invocations as commands such that they can subsequently be invoked in the background.
+
+The `BackgroundService` is responsible for capturing a memento representing the action invocation, and then hands off to the `BackgroundCommandService` to actually persist it. The `isis-module-command-jdo` module provides an implementation of `BackgroundCommandService` (link:../../components/objectstores/jdo/services/background-command-service-jdo.html[BackgroundCommandServiceJdo]) that persists to an RBMS entities.
+
+The persisting of commands is only half the story; there needs to be a separate process to read the commands and execute them. The abstract link:./background-service.html#BackgroundCommandExecution[BackgroundCommandExecution] provides a mechanism to do this; the `isis-module-command-jdo` provides a concrete subclass (`BackgroundCommandExecutionFromBackgroundCommandServiceJdo`) that knows how to query for persisted (background) `Command`s such that they can be executed by a scheduler.
+
+== BackgroundCommandService
+
+The `BackgroundCommandService` typically isn't called from domain classes, but it exists as a domain service so that it is pluggable into `BackgroundService`.
+
+=== API
+
+The API of the `BackgroundCommandService` is:
+
+[source]
+----
+public interface BackgroundCommandService {
+
+ public void schedule(
+ final ActionInvocationMemento aim,
+ final Command command,
+ final String targetClassName, final String targetActionName, final String targetArgs);
+
+}
+----
+
+where `ActionInvocationMemento` is a wrapper around a link:./memento-service.html[MementoService]'s `Memento`, capturing the details of an action invocation (for execution later on).
+
+For the record, the API of `ActionInvocationMemento` is:
+
+[source]
+----
+public class ActionInvocationMemento {
+
+ public String getActionId() { ... }
+ public String getTargetClassName() { ... }
+ public String getTargetActionName() { ... }
+ public Bookmark getTarget() { ... }
+ public int getNumArgs() { ... }
+ public Class<?> getArgType(final int num) throws ClassNotFoundException { ... }
+ public <T> T getArg(final int num, final Class<T> type) { ... }
+
+ public String asMementoString() { ... }
+}
+----
+
+The `asMementoString()` method therefore lets the `BackgroundCommandService` implementation convert the action invocation into a simple string.
+
+=== Implementation
+
+The `isis-module-command-jdo` module provides the link:../../components/objectstores/jdo/services/background-command-service-jdo.html[BackgroundCommandServiceJdo] implementation that persists `Command`s to an RDBMS.
+
+There is also a supporting repository to query persisted background `Command`s:
+
+* `org.apache.isis.objectstore.jdo.applib.service.background.BackgroundCommandServiceJdoRepository`
+
+In addition, there is a supporting contributions service that contributes actions for searching for persisted child and sibling `Command`s:
+
+* `org.apache.isis.objectstore.jdo.applib.service.background.BackgroundCommandServiceJdoContributions`
+
+=== Usage
+
+As noted above, this service isn't intended to be called from domain classes; rather it acts as a plug-in point to the default `BackgroundServiceDefault` service.
+
+== Related Services
+
+As discussed above, this service supports the link:./background-service.html[BackgroundService], persisting `Command`s such that they can be executed in the background.
+
+There is also a tie-up with the link:./command-context.html[CommandContext] and its supporting `CommandService` service. The `CommandContext` service is responsible for providing a parent `Command` with which the background `Command`s can then be associated as children, while the `CommandService` is responsible for persisting those parent `Command`s (analogous to the way in which the `BackgroundCommandService` persists the child background `Command`s). The `BackgroundCommandService` ensures that these background `Command`s are associated with the parent "foreground" `Command`.
+
+What that means is that the implementations of `CommandService` and `BackgroundCommandService` go together, hence both implemented in the `isis-module-command-jdo` module: (link:../../components/objectstores/jdo/services/command-service-jdo.html[CommandServiceJdo] and link:../../components/objectstores/jdo/services/background-command-service-jdo.html[BackgroundCommandServiceJdo]).
+
+== BackgroundCommandExecution concrete implementation
+
+The `BackgroundCommandExecution` (in isis-core) is an abstract template class provided by isis-core that defines an abstract hook method to obtain background `Command`s to be executed:
+
+[source]
+----
+public abstract class BackgroundCommandExecution
+ extends AbstractIsisSessionTemplate {
+ ...
+ protected abstract List<? extends Command> findBackgroundCommandsToExecute();
+ ...
+}
+----
+
+The developer is required to implement this hook method in a subclass.
+
+The `isis-module-command-jdo` module provides a concrete subclass that queries for commands persisted by its `BackgroundCommandServiceJdo`, namely:
+
+* `org.apache.isis.objectstore.jdo.service.BackgroundCommandExecutionFromBackgroundCommandServiceJdo`
+
+== Quartz Scheduler Configuration
+
+Details are provided on the link:./background-service.html[BackgroundService] page.
+
+== Registering the Services
+
+Assuming that the `configuration-and-annotation` services installer is configured:
+
+[source]
+----
+isis.services-installer=configuration-and-annotation
+----
+
+then the `BackgroundCommandServiceJdo` and `BackgroundCommandJdoRepository` services are automatically registered if the `isis-module-command-jdo` module is on the classpath. The `BackgroundCommandServiceJdoContributions` service (because it influences the user interface) must be explicitly registered:
+
+[source]
+----
+isis.services=...,\
+ org.apache.isis.objectstore.jdo.applib.service.background.BackgroundCommandServiceJdoContributions,\
+ ...
+----
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-CommandService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-CommandService.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-CommandService.adoc
index c08f1e1d..be2c214 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-CommandService.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-CommandService.adoc
@@ -10,3 +10,92 @@ IMPORTANT: TODO
== Isis Addons Implementation
For 1.7.0+, see the http://github.com/isisaddons/isis-module-command[Isis addons' Command module] (non-ASF).
+
+
+Title: CommandService (isis-module-command-jdo)
+
+The `CommandService` service supports the link:./command-context.html[CommandContext] service such that `Command` objects (that reify the invocation of an action on a domain object into an object) can be persisted.
+
+Persistent `Command`s support several use cases:
+
+* they enable profiling of the running application (which actions are invoked then most often, what is their response time)
+* they act as a parent to any background commands that might be invoked through the link:./background-service.html[BackgroundService]
+* if link:./auditing-service.html[auditing] is configured, they provide better audit informatio, since the `Command` (the 'cause' of an action) can be correlated to the audit records (the "effect" of the action) through the unique `transactionId` GUID
+* if link:./publishing-service.html[publishing] is configured, they provide better traceability as the `Command` is also correlated with any published events, again through the unique `transactionId` GUID
+* the associated link:../recognized-annotations/Command.html[@Command] annotation also allows action invocations to be performed in the background. In this case the act of invoking the action on an object instead returns the `Command` to the user.
+
+== <a name="screencast">Screencast</a>
+
+The screencast provides a run-through of the command (profiling) service, auditing service, publishing service. It also shows how commands can be run in the background either explicitly by scheduling through the background service or implicitly by way of a framework annotation.
+
+<iframe width="560" height="315" src="//www.youtube.com/embed/tqXUZkPB3EI" frameborder="0" allowfullscreen></iframe>
+
+== API
+
+The `CommandService` service defines the following very simple API:
+
+[source]
+----
+public interface CommandService {
+
+ @Programmatic
+ Command create();
+
+ @Programmatic
+ void startTransaction(final Command command, final UUID transactionId);
+
+ @Programmatic
+ void complete(final Command command);
+
+ @Programmatic
+ boolean persistIfPossible(Command command);
+
+ }
+----
+
+where `Command` is defined as defined by the link:./command-context.html[CommandContext] service.
+
+== Implementation
+
+==== CommandService (for persistent `Command`s)
+
+The `CommandService` interface (defined in the Isis applib) is implemented within `isis-module-command-jdo` by:
+
+* `org.apache.isis.objectstore.jdo.applib.service.command.CommandServiceJdo`
+
+There is also a supporting repository to query persisted `Command`s:
+
+* `org.apache.isis.objectstore.jdo.applib.service.command.CommandServiceJdoRepository`
+
+In addition, there is a supporting contributions service that contributes actions for searching for persisted `Command`s for any object:
+
+* `org.apache.isis.objectstore.jdo.applib.service.command.CommandServiceJdoContributions`
+
+== Usage
+
+== Registering the Services
+
+Assuming that the `configuration-and-annotation` services installer is configured:
+
+[source]
+----
+isis.services-installer=configuration-and-annotation
+----
+
+then the `CommandServiceJdo` and `CommandServiceJdoRepository` services are automatically registered if the `isis-module-command-jdo` module
+is on the classpath. The `CommandServiceJdoContributions` service (because it influences the user interface) must be explicitly
+registered:
+
+[source]
+----
+isis.services=...,\
+ org.apache.isis.objectstore.jdo.applib.service.command.CommandServiceJdoContributions,\
+ ...
+----
+
+== Related Services
+
+As discussed above, this service supports the link:./command-context.html[CommandContext], providing the ability for `Command` objects to be
+persisted. This is closely related to the link:./background-command-service.html[BackgroundCommandService] that allows the link:./background-service.html[BackgroundService]) to schedule commands for background/asynchronous execution.
+
+The implementations of `CommandService` and `BackgroundCommandService` are intended to go together, so that persistent parent `Command`s can be associated with their child background `Command`s.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-EmailNotificationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-EmailNotificationService.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-EmailNotificationService.adoc
index 351d115..83c21db 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-EmailNotificationService.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-EmailNotificationService.adoc
@@ -7,3 +7,66 @@
IMPORTANT: TODO
+Title: Email Notification Service (1.8.0)
+
+The email notification service supports the user registration process whereby a user can sign-up to access an application by providing a valid email address. The Wicket viewer will check whether an implementation of this service (and also the link:./user-registration-service.html[user registration service]) is available, and if so will (unless configured not to) expose a sign-up page where the user enters their email address. A verification email is sent using this service; the email includes a link back to the running application. The user then completes the registration process (choosing a user name, password and so on) and the Wicket viewer creates an account for them (using the aforementioned link:./user-registration-service.html[user registration service]).
+
+The framework provides both an API and a default implementation of this service. The implementation depends in turn on the link:./email-service.html[email service].
+
+== API
+
+The API for the service is:
+
+[source]
+----
+public interface EmailNotificationService extends Serializable {
+
+ @PostConstruct
+ @Programmatic
+ public void init() ;
+
+ @Programmatic
+ boolean send(EmailRegistrationEvent ev);
+
+ @Programmatic
+ boolean send(PasswordResetEvent ev);
+
+ @Programmatic
+ boolean isConfigured();
+}
+----
+
+where:
+
+* `init()` is always called by the framework, and allows the implementation to read configuration properties and initialize itself
+* `send(...)` is the API to send an email either to verify an email (as part of the initial user registration) or to reset a password for an already-registered user
+* `isConfigured()` determines whether the implementation was configured and initialized correctly.
+
+If `isConfigured()` returns false then it is NOT valid to call `send(...)` (and doing so will result in an `IllegalStateException` being thrown.
+
+== Implementation & Configuration
+
+The framework provides a default implementation (`EmailNotificationServiceDefault`) that delegates to the link:./email-service.html[email service] to send an (HTML) message. As such, it requires that the email service has been configured.
+
+If you have configured an alternative email service implementation, it should process the message body as HTML.
+
+== Alternative Implementations
+
+If you wish to write an alternative implementation of this service, note that (unlike most Isis domain services) the implementation is also instantiated and injected by Google Guice. This is because `EmailNotificationService` is used as part of the link:../../components/viewers/wicket/user-registration.html[user registration] functionality and is used by Wicket pages that are accessed outside of the usual Isis runtime.
+
+This implies a couple of additional constraints:
+
+* first, implementation class should also be annotated with `@com.google.inject.Singleton`
+* second, there may not be any Isis session running. (If necessary, one can be created on the fly using `IsisContext.doInSession(...)`)
+
+To ensure that your alternative implementation takes the place of the default implementation, register it explicitly in `isis.properties`.
+
+== Register the Service
+
+If using the default implementation of the `EmailService` then there is nothing to do because it is automatically registered (it is annotated with `@DomainService`).
+
+If you have written an alternative implementation, then register your implementation in `isis.properties` under the "isis.services" key.
+
+== Related Services
+
+The default implementation of the email service depends upon the `EmailService`, see link:./email-service.html[here].
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-ExceptionRecognizer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-ExceptionRecognizer.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-ExceptionRecognizer.adoc
index e9da760..3993feb 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-ExceptionRecognizer.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-ExceptionRecognizer.adoc
@@ -7,3 +7,135 @@
IMPORTANT: TODO
+
+Title: Exception Recognizers
+
+The `ExceptionRecognizer` API (in the `org.apache.isis.applib.services.exceprecog` package) provides the mechanism for
+both the domain programmer and also for components to be able to recognize and handle certain exceptions that may be
+thrown by the system.
+
+For example, the link:../../components/objectstores/jdo/about.html[JDO Objectstore] provides a set of recognizers to
+recognize and handle SQL constraint exceptions such as uniqueness violations. These can then be rendered back to the
+user as expected errors, rather than fatal stacktraces.
+
+== API
+
+The `ExceptionRecognizer` interface is defined as:
+
+[source]
+----
+public interface ExceptionRecognizer {
+ public String recognize(Throwable ex);
+}
+----
+
+If the implementation recognizes the exception then it returns a user-friendly message to be rendered (by the viewer)
+back to the user; otherwise it returns `null`. There is no need for the implementation to check for exception causes;
+the casual chain is unwrapped by Isis core and each exception in the chain will also be passed through to the
+recognizer (from most specific to least). The recognizer implementation can therefore be as fine-grained or as
+coarse-grained as it wishes.
+
+Typically implementations of `ExceptionRecognizer` are registered as services (in the `isis.properties` configuration
+file). More than one recognizer can be registered; all we be checked if an exception is thrown.
+
+== Extended API (1.8.0)
+
+The `ExceptionRecognizer2` interface extends the original `ExceptionRecognizer` interface, being defined as:
+
+[source]
+----
+public interface ExceptionRecognizer2 extends ExceptionRecognizer {
+
+ public enum Category {
+ CONSTRAINT_VIOLATION,
+ NOT_FOUND,
+ CONCURRENCY,
+ CLIENT_ERROR,
+ SERVER_ERROR,
+ OTHER
+ }
+
+ public static class Recognition {
+ private final Category category;
+ private final String reason;
+
+ public Recognition(Category category, String reason) {
+ this.category = category;
+ this.reason = reason;
+ }
+
+ public Category getCategory() { return category; }
+ public String getReason() { return reason; }
+ }
+
+ public Recognition recognize2(final Throwable ex);
+}
+----
+
+In essence, if an exception is recognized then it is also categorized. This lets the viewer act accordingly, for
+example to raise a 404 (see 'Support' discussion below).
+
+== Core Implementations
+
+The `DomainObjectContainer` provided by Isis core is itself an `ExceptionRecognizer`, and will handle
+`ConcurrencyException`s (raised by any objectstore). No configuration is required to enable this feature (neither can
+it be disabled).
+
+The JDO Objectstore (part of core) also provides a number of fine-grained implementations:
+
+* `ExceptionRecognizerForSQLIntegrityConstraintViolationUniqueOrIndexException`
+* `ExceptionRecognizerForJDOObjectNotFoundException`
+* `ExceptionRecognizerForJDODataStoreException`
+
+These are bundled up into a composite, `ExceptionRecognizerCompositeForJdoObjectStore`.
+
+== Registering the Default Implementation
+
+In most cases you should use the JDO Objectstore's `ExceptionRecognizerCompositeForJdoObjectStore` in your applicatio.
+This service has _not_ been annotated with `@DomainService` and so requires explicit registration in
+`WEB-INF/isis.properties`:
+
+[source]
+----
+isis.services=...,\
+ org.apache.isis.objectstore.jdo.applib.service.exceprecog.ExceptionRecognizerCompositeForJdoObjectStore,\
+ ...
+----
+
+For simple apps this may in fact be the only service registered in `isis.properties`.
+
+____
+
+Explicit registration is required primarily to offer maximum flexibility and control.
+
+____
+
+== Checking for additional exceptions.
+
+If you want to recognize and handle additional exceptions (for example to capture error messages specific to the
+JDBC driver you might be using), then the recommended approach is to:
+
+*
+
+create a fine-grained implementation of `ExceptionRecognizer` (or `ExceptionRecognizer2`) for the particular error
+message (there are some convenience implementations of the interface that you can subclass from if required)
+
+*
+
+register your implementation in `isis.properties`. More than one implementation of `ExceptionRecognizer` can be
+ registered; all we be checked if an exception is thrown.
+
+Alternatively, if you prefer to register just a single `ExceptionRecognizer` service class, you could create a
+composite implementation that bundles up your fine-grained implementation; see the above
+`ExceptionRecognizerCompositeForJdoObjectStore` for inspiration.
+
+== Support
+
+In 1.7.0, only the link:../../components/viewers/wicket/about.html[Wicket viewer] supported this API.
+
+In 1.8.0, some checking of exception recognizers has moved deeper into core, specifically the (JDO) objectstore.
+In particular, if an exception is raised from the loading of an individual object, then this is passed by the
+registered ExceptionRecognizers. If any of these recognize the exception as representing a not-found exception, then
+a Isis `ObjectNotFoundException` is raised. Both the viewers interprets this correctly (the
+link:../../components/viewers/wicket/about.html[Wicket viewer] as a suitable error page, the
+link:../../components/viewers/restfulobjects/about.html[Restful Objects] viewer as a 404 status return code.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-PublishingService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-PublishingService.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-PublishingService.adoc
index 5af3279..2c158cc 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-PublishingService.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-PublishingService.adoc
@@ -10,3 +10,236 @@ IMPORTANT: TODO
== Isis Addons Implementation
For 1.7.0+, see the http://github.com/isisaddons/isis-module-publishing[Isis addons' Publishing module] (non-ASF).
+
+
+Title: Publishing Service
+
+The Publishing Service enables Isis to publish both changes to domain objects, and also action invocations to third parties. A typical use case is to publish onto a pub/sub bus such as http://servicemix.apache.org/[ServiceMix] or http://activemq.apache.org/[ActiveMQ] to keep other systems up to date.
+
+Publishing requires at minimum two things:
+
+* domain classes annotated with `PublishedAction` or `PublishedObject`
+
+The former causes any invocations of an action to be published, the latter causes any changes to the object to be published. You can annotate with either or both.
+
+* an implementation of the `org.apache.isis.applib.services.publish.PublishingService` interface must be registered as a domain services
+
+This is done in the usual way, registering the service in the `isis.properties` config file
+
+Over and above this, the service does provide considerable flexibility for fine-tuning the serialized form and the contents (payload) of the event.
+
+____
+
+Publishing of action invocations is supported by all objectstores. Publishing of changed objects is currently only supported by the link:../../components/objectstores/jdo/about.html[JDO objectstore].
+
+____
+
+== Annotating the Domain Model
+
+To indicate that an action should be published, use the `PublishedAction` annotation. For example:
+
+Similarly, to indicate that any changes to an object should be published, use the `PublishedObject` annotation:
+
+Either or both of these annotations can be used.
+
+As described further down in this article, it is possible to fine-tune the payload. However, simply using the above annotations will suffice in many cases.
+
+== API
+
+The `PublishingService` interface is:
+
+[source]
+----
+public interface PublishingService {
+ public void publish(EventMetadata metadata, EventPayload payload);
+ void setEventSerializer(EventSerializer eventSerializer);
+}
+----
+
+Typically implementations will use the injected `EventSerializer` to convert the metadata and payload into a form to be published:
+
+[source]
+----
+public interface EventSerializer {
+ public Object serialize(EventMetadata metadata, EventPayload payload);
+}
+----
+
+The serialized form returned by `EventSerializer` must be in a form that the `PublishingService` implementation is able
+to handle. Strings are a good lowest common denominator, but (if custom implementations of both `EventSerializer` and
+`PublishingService` were in use) then it might also be some other type, for example an
+`org.w3c.dom.Document` or an `org.json.JSONObject` might be returned instead.
+
+=== Fine-tuning the payload
+
+The `EventPayload` that is serialized identifies the object(s) being interacted with or changed, and in the case of the
+action invocation provides details of the action arguments and result (if any) of that action. However, the payload
+does not (by default) include the new state of these objects. It is therefore the responsibility of the subscriber to
+call back to Isis to determine any information that has not been published.
+
+Doing this is comparatively straightforward if using the Restful Object serializer and Restful Objects viewer; the
+JSON provided includes hrefs to the objects.
+
+In some circumstances, then, it may make more sense to eagerly "push" information about the change to the subscriber
+by including that state within the payload.
+
+To accomplish this, an implementation of a "`PayloadFactory`" must be specified in the annotation. For actions,
+implement `@PublishedAction.PayloadFactory`:
+
+[source]
+----
+public @interface PublishedAction {
+ public interface PayloadFactory {
+ @Programmatic
+ public EventPayload payloadFor(
+ Identifier actionIdentifier,
+ Object target, List<Object> arguments, Object result);
+ }
+ Class<? extends PayloadFactory> value() default PayloadFactory.class;
+}
+----
+
+The `EventPayloadForActionInvocation` abstract class (in the Isis applib) can optionally be used as the base class for
+the object instance returned from `payLoadFor(...)`.
+
+For objects, the interface to implement is `@PublishedObject.PayloadFactory`:
+
+[source]
+----
+public @interface PublishedObject {
+
+ public enum ChangeKind {
+ CREATE,
+ UPDATE,
+ DELETE
+ }
+
+ public interface PayloadFactory {
+ @Programmatic
+ public EventPayload payloadFor(Object changedObject, ChangeKind kind);
+ }
+ Class<? extends PayloadFactory> value() default PayloadFactory.class;
+}
+----
+
+Similarly, the `EventPayloadForObjectChanged` abstract class may be used as the base class for the object returned from
+`payLoadFor(...)`.
+
+For example, the following will eagerly include the `ToDoItem`'s `description` property whenever it is changed:
+
+[source]
+----
+@PublishedObject(ToDoItemPayloadFactory.class)
+public class ToDoItem {
+ ...
+}
+----
+
+where `ToDoItemPayloadFactory` is defined as:
+
+[source]
+----
+public class ToDoItemChangedPayloadFactory implements PayloadFactory {
+ public static class ToDoItemPayload
+ extends EventPayloadForObjectChanged<ToDoItem> {
+
+ public ToDoItemPayload(ToDoItem changed) {
+ super(changed);
+ }
+
+ public String getDescription() {
+ return getChanged().getDescription();
+ }
+ }
+ @Override
+ public EventPayload payloadFor(Object changedObject, ChangeKind kind) {
+ return new ToDoItemPayload((ToDoItem) changedObject);
+ }
+}
+----
+
+== Default Implementations
+
+A simple implementation of `PublishingService` (which must be configured as a domain service) is available; it simply writes to stderr.
+
+The implementation is as follows:
+
+[source]
+----
+public interface PublishingService {
+...
+ public static class Stderr implements PublishingService {
+ private EventSerializer eventSerializer = new EventSerializer.Simple();
+ @Programmatic
+ @Override
+ public void publish(EventMetadata metadata, EventPayload payload) {
+ Object serializedEvent = eventSerializer.serialize(metadata, payload);
+ System.err.println(serializedEvent);
+ }
+
+ @Override
+ public void setEventSerializer(EventSerializer eventSerializer) {
+ this.eventSerializer = eventSerializer;
+ }
+ }
+ ...
+}
+----
+
+As can be seen, the above implementation in turn uses a default implementation of `EventSerializer`, which simply concatenates the metadata and payload together into a single string:
+
+[source]
+----
+public interface EventSerializer {
+ ...
+ public static class Simple implements EventSerializer {
+ @Programmatic
+ @Override
+ public Object serialize(EventMetadata metadata, EventPayload payload) {
+ return "PUBLISHED: \n metadata: " +
+ metadata.getGuid() + ":" +
+ metadata.getUser() + ":" +
+ metadata.getTimestamp() + ":" +
+ payloads:\n" + payload.toString();
+ }
+ }
+ ...
+}
+----
+
+The default `PublishingService` (or indeed any implementation) can be configured to run with a different `EventSerializer` by configuring the serializer implementation in the `isis.properties` file.
+
+==== Configuration
+
+To configure the above, add the following to `isis.properties`:
+
+[source]
+----
+isis.services=...,\
+ org.apache.isis.applib.services.publish.PublishingService$StdErr,\
+ ...
+----
+
+== Alternative Implementations
+
+An alternative implementation of the `PublishingService` is provided by the link:../../components/objectstores/jdo/services/publishing-service-jdo.html[JDO Objectstore]. This implementation persists the events to a table.
+
+An alternative implementation of the `EventSerializer` is provided by the link:../../components/viewers/restfulobjects/event-serializer-rospec.html[Restful Objects viewer]. This implementation serializes the payload using the conventions of the http://restfulobjects.org[Restful Objects spec].
+
+== Related Services
+
+The `PublishingService` is intended for coarse-grained publish/subscribe for system-to-system interactions, from Isis to some other system. Here the only events published are those that action invocations (for actions annotated with link:../recognized-annotations/PublishedAction.html[`@PublishedAction`]) and of changed objects (for objects annotated with link:../recognized-annotations/PublishedObject.html[@PublishedObject].
+
+The link:./event-bus-service.html[EventBusService] meanwhile is intended for fine-grained publish/subscribe for object-to-object interactions within an Isis domain object model. The event propogation is strictly in-memory, and there are no restrictions on the object acting as the event (it need not be serializable, for example).
+
+== Third-party integrations
+
+Dan Haywood's https://github.com/danhaywood/camel-isis-pubsubjdo[camel-isis-pubsubjdo] project up on github shows how to poll and process the persisted `PublishedEvent` table using http://camel.apache.org[Apache Camel].
+
+== Design Notes
+
+The following class diagram shows how the above components fit together:
+
+
+
+This yuml.me diagram was generated at http://yuml.me/edit/23db58a4[yuml.me] using the following description:
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-UserProfileService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-UserProfileService.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-UserProfileService.adoc
index f1c32d1..bde370a 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-UserProfileService.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-UserProfileService.adoc
@@ -7,3 +7,70 @@
IMPORTANT: TODO
+
+Title: User Profile Service (1.8.0)
+
+The user profile service API provides the ability for the domain application to return supplementary metadata about
+the current user. This information is used (by the Wicket viewer) to customize the appearance of the tertiary
+"Me" menu bar (top right). For example, rather than display the username, instead the user's first and last name
+could be displayed.
+
+Another use case is to allow the user to switch context in some fashion or other. This might be to emulate a
+sort of "sudo"-like function, or perhaps to focus on some particular set of data.
+
+____
+
+Currently this feature is not integrated with Isis' authentication mechanisms; the information provided is purely metadata provided for presentation purposes only.
+
+____
+
+== API
+
+The API for the service is:
+
+[source]
+----
+public interface UserProfileService {
+
+ @Programmatic
+ String userProfileName();
+}
+----
+
+where:
+
+* `userProfileName()` is used (in the Wicket viewer) as the menu name of the tertiary "Me" menu bar.
+
+If the method returns <tt>null</tt> or throws an exception then the framework will default to using the current user name.
+
+____
+
+In the future this API may be expanded; one obvious possibility is to return a profile photo or avatar URL.
+
+____
+
+== Screenshot
+
+The https://github.com/isisaddons/isis-app-todoapp[todoapp] (not ASF) provides a custom implementation that
+demonstrates the use of this service:
+
+<a href="images/user-profile-service.png"><img width="600px" src="images/user-profile-service.png"/></a>
+
+The implementation is very straight-forward:
+
+[source]
+----
+@DomainService
+public class CustomUserProfileService implements UserProfileService {
+
+ @Override
+ @Programmatic
+ public String userProfileName() {
+ return "Hi " + getAuthenticationSession().getUserName() + "!";
+ }
+
+ protected AuthenticationSession getAuthenticationSession() {
+ return IsisContext.getAuthenticationSession();
+ }
+}
+----
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-UserRegistrationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-UserRegistrationService.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-UserRegistrationService.adoc
index 9ab7f98..800ab5e 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-UserRegistrationService.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-UserRegistrationService.adoc
@@ -7,3 +7,60 @@
IMPORTANT: TODO
+
+Title: User Registration Service (1.8.0)
+
+The user registration service API provides the ability for users to sign-up to access an application by providing a valid email address. The Wicket viewer will check whether an implementation of this service (and also the link:./email-notification-service.html[email notification service]) is available, and if so will (unless configured not to) expose a sign-up page where the user enters their email address. A verification email is sent (using the aforementioned link:./email-notification-service.html[email notification service]) which includes a link back to the running application; this allows the user then to complete their registration process (choose user name, password and so on). When the user has provided the additional details, the Wicket viewer calls this service in order to create an account for them, and then logs the user on.
+
+The user registration API also includes the ability to reset password, again by sending a verification email to the provided email address.
+
+See link:../../components/viewers/wicket/user-registration.html[here] for more on the Wicket viewer's support.
+
+Domain objects may also use this service; it will be injected into domain object or other domain services in the usual way. (That said, we expect that such use cases will be comparatively rare; the primary use case is for the Wicket viewer's sign-up page).
+
+The core Isis framework itself defines only an API; there is no default implementation. Rather, the implementation will depend on the security mechanism being used. That said, if you have configured your app to use the http://github.com/isisaddons/isis-module-security[Isis addons security module], then note that the security module does provide an abstract implementation (`SecurityModuleAppUserRegistrationServiceAbstract`) of the user registration service. You will need to extend that service and provide implementation for the two abstract methods - `#getInitialRole()` and `#getAdditionalInitialRoles()`. This is needed so that the self-registered users are assigned automatically to your application role(s) and be able to use the application. Without any role such user will be able only to see/use the logout link of the application.
+Note: do not forget to register this service in isis.properties!
+An example of such implementation can be seen at isis-module-security's https://github.com/isisaddons/isis-module-security/blob/master/webapp/src/main/java/org/isisaddons/module/security/webapp/AppUserRegistrationService.java[demo application].
+
+== API
+
+The API for the service is:
+
+[source]
+----
+public interface UserRegistrationService {
+
+ @Programmatic
+ boolean usernameExists(String username);
+
+ @Programmatic
+ boolean emailExists(String emailAddress);
+
+ @Programmatic
+ void registerUser(String username, String password, String emailAddress);
+
+ @Programmatic
+ boolean updatePasswordByEmail(String emailAddress, String password);
+}
+----
+
+where:
+
+* `usernameExists()` checks if there is already a user with the specified username
+* `emailExists()` checks if there is already a user with the specified email address
+* `registerUser(...)` creates the user, with specified password and email address. The username nor email address must be unique (not being used by an existing user)
+* `updatePasswordByEmail()` allows the user to reset their password
+
+== Implementation
+
+There is no default implementation of the service provided by the core framework. However, the http://github.com/isisaddons/isis-module-security[Isis addons security module], provides an abstract implementation with almost all needed functionality. You may extend from it and provide the application role(s) for the self-registered users. *Note*: the custom implementation of this service should be registered manually in Isis!
+
+== Related Services
+
+The most common use case is to allow users to sign-up through Isis' Wicket viewer. Because the process requires email to be sent, the following services must be configured:
+
+* `EmailService` (as described link:./email-service.html[here]).
+* `EmailNotificationService` (as described link:./email-notification-service.html[here]).
+* `UserRegistrationService` (this service)
+
+The `EmailService` in particular requires additional configuration properties to specify the external SMTP service.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/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 53c894a..ffb6572 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
@@ -19,7 +19,7 @@ include::_ug_restfulobjects-viewer_hints-and-tips.adoc[leveloffset=+1]
== Extending the viewer
-Discussed in xref:_extending_the_restful_viewer[Extending the Restful viewer].
+Discussed in xref:_ug_extending_restfulobjects-viewer[Extending the Restful Objects viewer].
http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/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 6d9ec2d..81ff855 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
@@ -17,7 +17,7 @@ Also, be aware enabling these settings makes the representations with respect to
====
-.RestfulObjects Viewer Configuration Properties
+.Restful Objects Viewer Configuration Properties
[cols="2a,1,3", options="header"]
|===
|Property
@@ -28,12 +28,12 @@ Also, be aware enabling these settings makes the representations with respect to
|`isis.viewer.restfulobjects.` +
`honorUiHints`
| `true`,`false` (`_false_`)
-| See xref:_honor_ui_hints[discussion], below.
+| See xref:_ug_restfulobjects-viewer_configuration-properties_honor-ui-hints[discussion], below.
|`isis.viewer.restfulobjects.` +
`suppressDescribedByLinks`
| `true`,`false` (`_false_`)
-.6+| See xref:_suppressing_elements_of_the_representation[discussion], below.
+.6+| See xref:_ug_restfulobjects-viewer_configuration-properties_suppressing-elements[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 xref:_simplified_object_representation[discussion], below.
+| See xref:_ug_restfulobjects-viewer_configuration-properties_simplified-object[discussion], below.
|===
http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties_simplified-object-representation.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties_simplified-object-representation.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties_simplified-object-representation.adoc
index 120254a..e0b23d8 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties_simplified-object-representation.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties_simplified-object-representation.adoc
@@ -9,7 +9,7 @@
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 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.
+As described xref:_ug_restfulobjects-viewer_configuration-properties_suppressing-elements[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`):
@@ -65,4 +65,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 xref:_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:_ug_extending_restfulobjects-viewer[Extending the Restful Objects viewer].
http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties_suppressing-elements.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties_suppressing-elements.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties_suppressing-elements.adoc
index d87ed17..ff35c6b 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties_suppressing-elements.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_restfulobjects-viewer_configuration-properties_suppressing-elements.adoc
@@ -33,7 +33,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 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.
+If an even simpler representations (of objects) are required, see xref:_ug_restfulobjects-viewer_configuration-properties_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:_ug_extending_restfulobjects-viewer[Extending the Restful Objects viewer] in the <<Extending>> chapter.
http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/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 c485b68..6bca4bb 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
@@ -16,7 +16,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 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.
+The JSON representations generated by the Restful Objects viewer are in compact form if the xref:_ug_runtime_configuration-files_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/2af3ad9a/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 cf6f27a..2a2abc7 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime.adoc
@@ -9,7 +9,7 @@ Isis' own configuration properties are simple key-value pairs, typically held in
[NOTE]
====
-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.
+Configuration properties for the viewers can be found in the xref:_ug_wicket-viewer[Wicket Viewer] chapter and the <<Restful Objects Viewer>> chapter. Likewise[details of configuring security (Apache Shiro) can be found in the xref:_ug_security[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/2af3ad9a/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 2b7bbe7..fe430e2 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
@@ -11,9 +11,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 xref:_wicket_viewer_2[Wicket UI (viewer)] is in use
+* `viewer_wicket.properties` - if the xref:_ug_wicket-viewer[Wicket UI (viewer)] is in use
-* `viewer_restfulobjects.properties` - if the xref:_restful_objects_viewer[Restful Objects REST API (viewer)] is in use
+* `viewer_restfulobjects.properties` - if the xref:_ug_restfulobjects-viewer[Restful Objects REST API (viewer)] is in use
* `viewer.properties` - for any shared UI configuration
@@ -65,7 +65,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 xref:_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:_ug_runtime_web-xml[below]). However, the configuration of which viewers to initialize is declared through a context parameter:
[source,xml]
@@ -80,9 +80,6 @@ The net effect of this configuration is simply to ensure that the `viewer_wicket
-== Deployment Types
-
-IMPORTANT: TODO
-
+include::_ug_runtime_configuration-files_deployment-types.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuration-files_deployment-types.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuration-files_deployment-types.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuration-files_deployment-types.adoc
new file mode 100644
index 0000000..dadb64e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_runtime_configuration-files_deployment-types.adoc
@@ -0,0 +1,14 @@
+[[_ug_runtime_configuration-files_deployment-types]]
+= Deployment Types
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+
+
+IMPORTANT: TODO
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/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 5906257..315ba13 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
@@ -6,7 +6,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 xref:_configuring_datanucleus[Configuring DataNucleus] section elsewhere in this chapter.
+Configuration properties for the JDO/DataNucleus objectstore can be found in the xref:_ug_runtime_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.
@@ -32,17 +32,17 @@ 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 xref:_i18n[i18n support] to learn more about the translation service.
+See xref:_ug_more-advanced_i18n[i18n support] to learn more about the translation service.
|`isis.services.` +
`command.actions`
| `all`,`ignoreSafe`, `none` (`all`)
-|Whether actions should be automatically reified into commands (for actions annotated with xref:__a_id_reference_annotations_manpage_a_code_action_code[`@Action(command=CommandReification.AS_CONFIGURED)`]. `ignoreQueryOnly` is an alias for `ignoreSafe`.
+|Whether actions should be automatically reified into commands (for actions annotated with xref:_ug_reference-annotations_manpage-Action_command[`@Action(command=CommandReification.AS_CONFIGURED)`]. `ignoreQueryOnly` is an alias for `ignoreSafe`.
|`isis.services.` +
`publish.actions`
| `all`,`ignoreSafe`, `none` (`all`)
-|Whether actions should be automatically published (for actions annotated with xref:__a_id_reference_annotations_manpage_a_code_action_code[`@Action(publishing=Publishing.AS_CONFIGURED)`]. `ignoreQueryOnly` is an alias for `ignoreSafe`.
+|Whether actions should be automatically published (for actions annotated with xref:_ug_reference-annotations_manpage-Action_publishing[`@Action(publishing=Publishing.AS_CONFIGURED)`]. `ignoreQueryOnly` is an alias for `ignoreSafe`.
|`isis.persistor.` +
`disableConcurrencyChecking`
@@ -64,24 +64,24 @@ See xref:_user-guide_how-tos_ui-hints_action-icons-and-css[UI hints] for more de
|`isis.reflector.facets`
|`FQCN`
|Fully qualified class names of a custom implementation of `ProgrammingModel` interface.
-See xref:_finetuning[finetuning the programming model] for more details.
+See xref:_ug_extending_programming-model_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 xref:_finetuning[finetuning the programming model] for more details.
+See xref:_ug_extending_programming-model_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 xref:_finetuning[finetuning the programming model] for more details.
+See xref:_ug_extending_programming-model_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 xref:_custom_validator[Custom Validator] to learn more.
+See xref:_ug_extending_programming-model_custom-validator[Custom Validator] to learn more.
|`isis.reflector.validator.` +
`allowDeprecated`
@@ -91,8 +91,8 @@ See xref:_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 xref:_dynamic_object_layout[dynamic layout]s. +
-See xref:_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:_ug_wicket-viewer_layout_dynamic-object-layout[dynamic layout]s. +
+See xref:_ug_extending_programming-model_layout-metadata-reader[Layout Metadata Reader] for more information.
|===
http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/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 ab92674..f4c8779 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
@@ -8,15 +8,11 @@ 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 xref:_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:_ug_more-advanced_assembling_overriding-jdo-annotations[Overriding JDO Annotatons] for further discussion.
include::_ug_runtime_configuring-datanucleus_properties.adoc[leveloffset=+1]
-
include::_ug_runtime_configuring-datanucleus_persistence-xml.adoc[leveloffset=+1]
-
include::_ug_runtime_configuring-datanucleus_eagerly-registering-entities.adoc[leveloffset=+1]
-
include::_ug_runtime_configuring-datanucleus_disabling-persistence-by-reachability.adoc[leveloffset=+1]
-
include::_ug_runtime_configuring-datanucleus_using-jndi-data-source.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/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 3cacd6e..83834d6 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
@@ -27,7 +27,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 xref:_integration_testing[Integration Testing] provides the `#addRegisterEntitiesPackagePrefix()` method to set up this configuration property:
+The `IsisConfigurationForJdoIntegTests`, recommended for use in xref:_ug_testing_integ-test-support[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/2af3ad9a/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 f3337ea..1354fba 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
@@ -23,7 +23,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 xref:_registering_entity_types[discussion below].
+Further xref:_ug_runtime_configuring-datanucleus_eagerly-registering-entities[discussion below].
|`isis.persistor.datanucleus.` +
`PublishingService.serializedForm`
@@ -52,7 +52,7 @@ Further xref:_registering_entity_types[discussion below].
`datanucleus.persistenceByReachabilityAtCommit`
|`false`
|We recommend this setting is disabled. +
-Further xref:_disabling_persistence_by_reachability[discussion below].
+Further xref:_ug_runtime_configuring-datanucleus_disabling-persistence-by-reachability[discussion below].
|===
http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/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 db77766..02eeeb2 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_security.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_ug_security.adoc
@@ -26,7 +26,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 -- 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).
+A further aspect of security is auditing: recording what data was modified by which user. Apache Isis does define two service APIs -- xref:_ug_reference-services-spi_manpage-CommandService[`CommandService`] and xref:_ug_reference-services-spi_manpage-AuditingService[`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/2af3ad9a/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 85930a6..e594137 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
@@ -13,7 +13,7 @@ Still, on very rare occasion you may have a need, in which case you can either u
== Using Isis` `DomainObjectContainer`
-The xref:_domain_object_container[`DomainObjectContainer`] service exposes the following API:
+The xref:_ug_reference-services-api_manpage-DomainObjectContainer[`DomainObjectContainer`] service exposes the following API:
[source,java]
----
http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/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 9478ac4..b69f2c7 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
@@ -105,7 +105,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 xref:_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:_ug_security_shiro-isis-enhanced-wildcard-permission[here].
====
http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/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 84abfeb..948656e 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
@@ -5,7 +5,7 @@
:_imagesdir: images/
-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".
+If using the text-based xref:_ug_security_shiro-ini-realm[`IniRealm`] or xref:_ug_security_shiro-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.