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:55 UTC
[29/29] isis git commit: ISIS-1133: fixing references,
breaking out annotation pages for each attribute (for more consistent
cross-referencing).
ISIS-1133: fixing references, breaking out annotation pages for each attribute (for more consistent cross-referencing).
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/2af3ad9a
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/2af3ad9a
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/2af3ad9a
Branch: refs/heads/ISIS-1133
Commit: 2af3ad9a710da996863d26cb57110303961ad59f
Parents: 7db616e
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Wed May 27 16:11:56 2015 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Thu May 28 14:00:28 2015 +0100
----------------------------------------------------------------------
.../asciidoc/user-guide/__/ClockService.adoc | 65 --
.../__/background-command-service.adoc | 115 ----
.../user-guide/__/background-service.adoc | 265 --------
.../user-guide/__/bookmark-service.adoc | 48 --
.../user-guide/__/bulk-interaction.adoc | 84 ---
.../asciidoc/user-guide/__/command-context.adoc | 213 -------
.../asciidoc/user-guide/__/command-service.adoc | 87 ---
.../user-guide/__/deep-link-service.adoc | 39 --
.../__/developer-utilities-service.adoc | 72 ---
.../__/email-notification-service.adoc | 63 --
.../asciidoc/user-guide/__/email-service.adoc | 81 ---
.../user-guide/__/event-bus-service.adoc | 210 -------
.../user-guide/__/exception-recognizers.adoc | 131 ----
.../asciidoc/user-guide/__/memento-service.adoc | 93 ---
.../user-guide/__/publishing-service.adoc | 231 -------
.../user-guide/__/query-results-cache.adoc | 109 ----
.../main/asciidoc/user-guide/__/scratchpad.adoc | 100 ---
.../user-guide/__/settings-services.adoc | 78 ---
.../asciidoc/user-guide/__/sudo-service.adoc | 40 --
.../user-guide/__/user-profile-service.adoc | 66 --
.../__/user-registration-service.adoc | 56 --
.../asciidoc/user-guide/__/wrapper-factory.adoc | 127 ----
.../user-guide/__/xmlsnapshot-service.adoc | 168 -----
.../_ug_appendices_release-notes.adoc | 2 +-
...ug_extending_wicket-viewer_custom-pages.adoc | 4 +-
..._ug_getting-started_simpleapp-archetype.adoc | 6 +-
.../user-guide/_ug_headless-access.adoc | 2 +-
.../user-guide/_ug_how-tos_class-structure.adoc | 2 +-
.../_ug_how-tos_class-structure_actions.adoc | 2 +-
...ow-tos_class-structure_class-definition.adoc | 2 +-
..._ug_how-tos_class-structure_collections.adoc | 2 +-
.../_ug_how-tos_class-structure_properties.adoc | 2 +-
...how-tos_ui-hints_names-and-descriptions.adoc | 2 +-
...ow-tos_ui-hints_object-titles-and-icons.adoc | 8 +-
.../user-guide/_ug_isis-addons-modules.adoc | 28 +-
..._ug_isis-addons-modules_devutils-module.adoc | 72 +++
..._ug_isis-addons-modules_settings-module.adoc | 82 +++
.../_ug_more-advanced_assembling.adoc | 56 +-
...d_assembling_overriding-jdo-annotations.adoc | 55 ++
...-advanced_assembling_vetoing-visibility.adoc | 9 +
.../_ug_more-advanced_decoupling.adoc | 2 +-
..._ug_more-advanced_decoupling_db-schemas.adoc | 2 +-
.../user-guide/_ug_more-advanced_i18n.adoc | 12 +-
...g_more-advanced_transactions-and-errors.adoc | 2 +-
...ug_reference-annotations_aaa_deprecated.adoc | 4 +-
.../_ug_reference-annotations_aaa_jee.adoc | 8 +-
.../_ug_reference-annotations_aaa_main.adoc | 30 +-
.../_ug_reference-annotations_aaa_other.adoc | 16 +-
...ug_reference-annotations_manpage-Action.adoc | 543 +---------------
...erence-annotations_manpage-ActionLayout.adoc | 546 +---------------
...ations_manpage-ActionLayout_bookmarking.adoc | 78 +++
...ions_manpage-ActionLayout_contributedAs.adoc | 49 ++
...notations_manpage-ActionLayout_cssClass.adoc | 73 +++
...tations_manpage-ActionLayout_cssClassFa.adoc | 93 +++
...ations_manpage-ActionLayout_describedAs.adoc | 28 +
...annotations_manpage-ActionLayout_hidden.adoc | 128 ++++
...-annotations_manpage-ActionLayout_named.adoc | 42 ++
...ence-annotations_manpage-Action_command.adoc | 132 ++++
...-annotations_manpage-Action_domainEvent.adoc | 166 +++++
...rence-annotations_manpage-Action_hidden.adoc | 38 ++
...nce-annotations_manpage-Action_invokeOn.adoc | 65 ++
...e-annotations_manpage-Action_publishing.adoc | 57 ++
...e-annotations_manpage-Action_restrictTo.adoc | 34 +
...ce-annotations_manpage-Action_semantics.adoc | 38 ++
...rence-annotations_manpage-Action_typeOf.adoc | 29 +
...eference-annotations_manpage-Collection.adoc | 488 +--------------
...ce-annotations_manpage-CollectionLayout.adoc | 448 +------------
...tions_manpage-CollectionLayout_cssClass.adoc | 77 +++
...ns_manpage-CollectionLayout_describedAs.adoc | 31 +
...tations_manpage-CollectionLayout_hidden.adoc | 132 ++++
...otations_manpage-CollectionLayout_named.adoc | 58 ++
...otations_manpage-CollectionLayout_paged.adoc | 51 ++
...tations_manpage-CollectionLayout_render.adoc | 49 ++
...tions_manpage-CollectionLayout_sortedBy.adoc | 53 ++
...otations_manpage-Collection_domainEvent.adoc | 168 +++++
...-annotations_manpage-Collection_editing.adoc | 130 ++++
...e-annotations_manpage-Collection_hidden.adoc | 129 ++++
...tations_manpage-Collection_notPersisted.adoc | 34 +
...e-annotations_manpage-Collection_typeOf.adoc | 33 +
...erence-annotations_manpage-DomainObject.adoc | 351 +----------
...-annotations_manpage-DomainObjectLayout.adoc | 399 +-----------
..._manpage-DomainObjectLayout_bookmarking.adoc | 69 +++
...ons_manpage-DomainObjectLayout_cssClass.adoc | 75 +++
...s_manpage-DomainObjectLayout_cssClassFa.adoc | 101 +++
..._manpage-DomainObjectLayout_describedAs.adoc | 29 +
...ations_manpage-DomainObjectLayout_named.adoc | 42 ++
...ations_manpage-DomainObjectLayout_paged.adoc | 48 ++
...tions_manpage-DomainObjectLayout_plural.adoc | 26 +
...notations_manpage-DomainObject_auditing.adoc | 41 ++
...tions_manpage-DomainObject_autoComplete.adoc | 49 ++
...nnotations_manpage-DomainObject_bounded.adoc | 36 ++
...nnotations_manpage-DomainObject_editing.adoc | 177 ++++++
...tations_manpage-DomainObject_objectType.adoc | 31 +
...tations_manpage-DomainObject_publishing.adoc | 21 +
...rence-annotations_manpage-DomainService.adoc | 77 +--
...annotations_manpage-DomainServiceLayout.adoc | 64 +-
...ons_manpage-DomainServiceLayout_menuBar.adoc | 15 +
...s_manpage-DomainServiceLayout_menuOrder.adoc | 12 +
...tions_manpage-DomainServiceLayout_named.adoc | 37 ++
...nnotations_manpage-DomainService_nature.adoc | 74 +++
...ons_manpage-DomainService_repositoryFor.adoc | 10 +
..._reference-annotations_manpage-HomePage.adoc | 2 +-
...ference-annotations_manpage-MemberOrder.adoc | 4 +-
...reference-annotations_manpage-MinLength.adoc | 2 +-
...reference-annotations_manpage-Parameter.adoc | 275 +-------
...nce-annotations_manpage-ParameterLayout.adoc | 328 +---------
...ations_manpage-ParameterLayout_cssClass.adoc | 49 ++
...ons_manpage-ParameterLayout_describedAs.adoc | 43 ++
...s_manpage-ParameterLayout_labelPosition.adoc | 16 +
...tions_manpage-ParameterLayout_multiLine.adoc | 83 +++
...notations_manpage-ParameterLayout_named.adoc | 49 ++
...age-ParameterLayout_renderedAsDayBefore.adoc | 37 ++
...s_manpage-ParameterLayout_typicalLength.adoc | 31 +
...annotations_manpage-Parameter_maxLength.adoc | 33 +
...annotations_manpage-Parameter_minLength.adoc | 35 ++
...notations_manpage-Parameter_mustSatisfy.adoc | 42 ++
...notations_manpage-Parameter_optionality.adoc | 48 ++
...nce-annotations_manpage-Parameter_regex.adoc | 40 ++
...erence-annotations_manpage-Programmatic.adoc | 2 +-
..._reference-annotations_manpage-Property.adoc | 621 +------------------
...ence-annotations_manpage-PropertyLayout.adoc | 468 +-------------
...tations_manpage-PropertyLayout_cssClass.adoc | 64 ++
...ions_manpage-PropertyLayout_describedAs.adoc | 27 +
...notations_manpage-PropertyLayout_hidden.adoc | 118 ++++
...ns_manpage-PropertyLayout_labelPosition.adoc | 9 +
...ations_manpage-PropertyLayout_multiLine.adoc | 86 +++
...nnotations_manpage-PropertyLayout_named.adoc | 49 ++
...page-PropertyLayout_renderedAsDayBefore.adoc | 30 +
...ns_manpage-PropertyLayout_typicalLength.adoc | 28 +
...nnotations_manpage-Property_domainEvent.adoc | 163 +++++
...ce-annotations_manpage-Property_editing.adoc | 123 ++++
...nce-annotations_manpage-Property_hidden.adoc | 130 ++++
...-annotations_manpage-Property_maxLength.adoc | 26 +
...nnotations_manpage-Property_mustSatisfy.adoc | 37 ++
...notations_manpage-Property_notPersisted.adoc | 38 ++
...nnotations_manpage-Property_optionality.adoc | 42 ++
...ence-annotations_manpage-Property_regex.adoc | 52 ++
...nce-annotations_manpage-ViewModelLayout.adoc | 295 +--------
...ations_manpage-ViewModelLayout_cssClass.adoc | 57 ++
...ions_manpage-ViewModelLayout_cssClassFa.adoc | 98 +++
...ons_manpage-ViewModelLayout_describedAs.adoc | 28 +
...notations_manpage-ViewModelLayout_named.adoc | 41 ++
...notations_manpage-ViewModelLayout_paged.adoc | 44 ++
...otations_manpage-ViewModelLayout_plural.adoc | 21 +
.../user-guide/_ug_reference-classes_super.adoc | 102 ++-
...ses_super_manpage-AbstractDomainService.adoc | 9 +
...nce-classes_super_manpage-FixtureScript.adoc | 9 +
.../_ug_reference-methods_prefixes_aaa.adoc | 52 +-
.../_ug_reference-methods_reserved_aaa.adoc | 44 +-
.../_ug_reference-services-api_aaa.adoc | 93 +--
...-services-api_manpage-BackgroundService.adoc | 265 ++++++++
...ce-services-api_manpage-BookmarkService.adoc | 48 ++
...ices-api_manpage-BulkInteractionContext.adoc | 93 +++
...rence-services-api_manpage-ClockService.adoc | 65 ++
...nce-services-api_manpage-CommandContext.adoc | 213 +++++++
...ce-services-api_manpage-DeepLinkService.adoc | 39 ++
...rence-services-api_manpage-EmailService.adoc | 82 +++
...ce-services-api_manpage-EventBusService.adoc | 212 +++++++
...nce-services-api_manpage-MementoService.adoc | 94 +++
...-services-api_manpage-QueryResultsCache.adoc | 110 ++++
...ference-services-api_manpage-ScratchPad.adoc | 100 +++
...erence-services-api_manpage-SudoService.adoc | 41 ++
...nce-services-api_manpage-WrapperFactory.adoc | 133 ++++
...services-api_manpage-XmlSnapshotService.adoc | 128 ++++
.../user-guide/_ug_reference-services-spi.adoc | 6 +-
.../_ug_reference-services-spi_aaa.adoc | 18 +-
...es-spi_manpage-BackgroundCommandService.adoc | 115 ++++
...nce-services-spi_manpage-CommandService.adoc | 89 +++
...es-spi_manpage-EmailNotificationService.adoc | 63 ++
...ervices-spi_manpage-ExceptionRecognizer.adoc | 132 ++++
...-services-spi_manpage-PublishingService.adoc | 233 +++++++
...services-spi_manpage-UserProfileService.adoc | 67 ++
...ces-spi_manpage-UserRegistrationService.adoc | 57 ++
.../user-guide/_ug_restfulobjects-viewer.adoc | 2 +-
...objects-viewer_configuration-properties.adoc | 8 +-
...erties_simplified-object-representation.adoc | 4 +-
...uration-properties_suppressing-elements.adoc | 2 +-
.../_ug_restfulobjects-viewer_features.adoc | 2 +-
.../main/asciidoc/user-guide/_ug_runtime.adoc | 2 +-
.../_ug_runtime_configuration-files.adoc | 11 +-
...me_configuration-files_deployment-types.adoc | 14 +
.../_ug_runtime_configuring-core.adoc | 20 +-
.../_ug_runtime_configuring-datanucleus.adoc | 6 +-
...atanucleus_eagerly-registering-entities.adoc | 2 +-
...time_configuring-datanucleus_properties.adoc | 4 +-
.../main/asciidoc/user-guide/_ug_security.adoc | 2 +-
.../_ug_security_api-for-applications.adoc | 2 +-
.../_ug_security_shiro-ini-realm.adoc | 2 +-
...shiro-isis-enhanced-wildcard-permission.adoc | 2 +-
.../_ug_security_usage-by-isis-viewers.adoc | 10 +-
.../asciidoc/user-guide/_ug_testing_aaa.adoc | 4 +-
...ug_testing_bdd-spec-support_key-classes.adoc | 2 +-
...ing_bdd-spec-support_writing-a-bdd-spec.adoc | 2 +-
...g_testing_fixture-scripts_api-and-usage.adoc | 4 +-
...esting_integ-test-support_bootstrapping.adoc | 6 +-
...esting_integ-test-support_typical-usage.adoc | 2 +-
...ting_integ-test-support_wrapper-factory.adoc | 4 +-
.../user-guide/_ug_tutorials_pet-clinic.adoc | 2 +-
...tutorials_stop-scaffolding-start-coding.adoc | 36 +-
199 files changed, 7863 insertions(+), 7577 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/adocs/documentation/src/main/asciidoc/user-guide/__/ClockService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/__/ClockService.adoc b/adocs/documentation/src/main/asciidoc/user-guide/__/ClockService.adoc
deleted file mode 100644
index 97ca2e7..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/__/ClockService.adoc
+++ /dev/null
@@ -1,65 +0,0 @@
-title: Clock Service
-
-Most applications deal with dates and times in one way or another. For example, if an `Order` is placed, then the `Customer` may have 30 days to pay the Invoice, otherwise a penalty may be levied. However, this can complicate automated testing: "today+30" will be a different date every time the test is run.
-
-Even disregarding testing, there may be a requirement to ensure that date/times are obtained from an NNTP server (rather than the system PC). While instantiating a `java.util.Date` to current the current time is painless enough, we would not want complex technical logic for querying an NNTP server spread around domain logic code.
-
-Therefore it's common to provide a domain service whose responsibility is to provide the current time. This service can be injected into any domain object (and can be mocked out for unit testing). Isis provides such a facade through the `ClockService`.
-
-== API & Implementation
-
-The API defined by `ClockService` is:
-
-[source]
-----
-public class ClockService {
- public LocalDate now() { ... }
- public LocalDateTime nowAsLocalDateTime() { ... }
- public DateTime nowAsDateTime() { ... }
- public Timestamp nowAsJavaSqlTimestamp() { ... }
- public long nowAsMillis() { ... }
-}
-----
-
-In fact, this is a concrete class and therefore constitutes the default implementation:
-
-* `org.apache.isis.applib.services.clock.ClockService`
-
-The time provided by this default implementation is based on the system clock.
-
-== Registering the Service
-
-The `ClockService` class is automatically registered (it is annotated with `@DomainService`) so no further configuration is required.
-
-== Alternative Implementations
-
-The default implementation delegates in fact to a singleton class that is also in the applib, namely `org.apache.isis.applib.clock.Clock`. Because the framework itself uses this singleton, a little care must be exercised in configuring the framework to use an alternative implementation.
-
-Specifically, the first call to the `ClockService` (or to `Clock.getTime()` directly) will lazily instantiate the singleton, specifically `SystemClock` (a subclass of `Clock`). As its name suggests, this default implementation simply delegates to the system's internal clock. Once instantiated, the object registers itself as the singleton for the class such that any other attempt to instantiate some other (subclass of) `Clock` is ignored.
-
-Setting up a different implementation therefore requires eagerly instantiating a different subclass of `Clock`. This is most easily accomplished by defining the `Clock` subclass as a nested inner class of a custom`ClockService` implementation. For example:
-
-[source]
-----
-public class NntpClockService extends ClockService {
- private static class NntpClock extends Clock {
- protected long time() {
- ... NNTP stuff here ...
- }
- }
- public NntpClockService() {
- new NntpClock();
- }
-}
-----
-
-You can then register this service in the usual way within `isis.properties`:
-
-[source]
-----
-isis.services=...,\
- com.mycompany.myapp.NntpClockService,\
- ...
-----
-
-Because this is a subclass of `ClockService` it will be used instead of the default implementation.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/adocs/documentation/src/main/asciidoc/user-guide/__/background-command-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/__/background-command-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/__/background-command-service.adoc
deleted file mode 100644
index a14f896..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/__/background-command-service.adoc
+++ /dev/null
@@ -1,115 +0,0 @@
-Title: Background Command Service (isis-module-command-jdo)
-
-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/__/background-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/__/background-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/__/background-service.adoc
deleted file mode 100644
index 6feb715..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/__/background-service.adoc
+++ /dev/null
@@ -1,265 +0,0 @@
-Title: Background Service
-
-The `BackgroundService`, and its companion `BackgroundCommandService`, enable action invocations to be persisted such that they may be invoked in the background.
-
-The `BackgroundService` is responsible for capturing a memento representing the action invocation, and persisting it. The default `BackgroundServiceDefault` implementation (provided by isis-core) uses (a private copy of) link:./memento-service.html[MementoService], and then delegates the persistence of the memento to an appropriate implementation of the companion `BackgroundCommandService`. One such implementation is `isis-module-command-jdo`'s link:./background-command-service.html[BackgroundCommandServiceJdo].
-
-The persisting of commands is only half the story; there needs to be a separate process to read the commands and execute them. The `BackgroundCommandExecution` abstract class (discussed link:#BackgroundCommandExecution[below] provides infrastructure to do this; the concrete
-implementation of this class depends on the configured `BackgroundCommandService` (in order to query for the persisted (background) `Command`s.
-
-== BackgroundService
-
-The `BackgroundService` is the entry point for domain classes wishing to perform actions asynchronously. This can be done in a typesafe way; the (default implementation of) `BackgroundService` actually uses a proxy wrapper around the target so that it can capture the action to invoke and its arguments, and then persist them rather than execute them.
-
-=== API & Implementation
-
-Returns a proxy around the object which is then used to obtain the signature of the action to be invoked in the background.
-
-[source]
-----
-public interface BackgroundService {
-
- @Programmatic
- <T> T execute(final T object);
-}
-----
-
-The default implementation is provided by core:
-
-* `org.apache.isis.core.runtime.services.background.BackgroundServiceDefault`
-
-=== Usage
-
-Using the `BackgroundService` is very straight-forward. For example:
-
-[source]
-----
-public void submitCustomerInvoices() {
- for(Customer customer: customerRepository.findCustomersToInvoice()) {
- backgroundService.execute(customer).submitInvoice();
- }
- container.informUser("Calculating...");
-}
-----
-
-Will create a bunch of background commands executing the `submitInvoice()` action for each of the customers returned from the customer repository.
-
-The action method invoked must be part of the Isis metamodel, which is to say it must be public, accept only scalar arguments, and must not be annotated with `@Programmatic` or `@Ignore`. However, it may be annotated with `@Hidden`, and it will still be invoked.
-
-In fact, when invoked by the background service, no business rules (hidden, disabled, validation) are enforced; the action method must take responsibility for performing appropriate validation and error checking.
-
-=== End-user experience
-
-For the end-user, executing an action that delegates work off to the `BackgroundService` raises the problem of how does the user know the work is complete?
-
-One option is for the background jobs to take responsibility to notify the user themselves. In the above example, this would be the `submitInvoice()` method called upon each customer. One could imagine more complex designs where only the final command executed notifies the user.
-
-However, an alternative is to rely on the fact that the `BackgroundService` will automatically hint that the `Command` representing the original interaction (to `submitCustomerInvoices()` in the example above) should be persisted. This will be available if the related `CommandContext` and `CommandService` domain services are configured, and the `CommandService` supports persistent commands. You can read more about `CommandContext` and `CommandService` link:./command-context.html[here].
-
-Thus, the original action can run a query to obtain it corresponding `Command`, and return this to the user. The child `Command`s created by the `BackgroundService` will then be associated with it.
-
-We could therefore refactor the method as follows:
-
-[source]
-----
-public Command submitCustomerInvoices() {
- for(Customer customer: customerRepository.findCustomersToInvoice()) {
- backgroundService.execute(customer).submitInvoice();
- }
- return commandContext.getCommand();
-}
-----
-
-where `commandContext` field is the injected `CommandContext` domain service.
-
-== Related Services
-
-This service is closely related to the link:./command-context.html[CommandContext] and also that service's supporting link:./command-service.html[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. The latter is analogous to the way in which the `BackgroundCommandService` persists the child background `Command`s.
-
-The implementations of `CommandService` and `BackgroundCommandService` go together; typically both parent `Command`s and child background `Command`s will be persisted in the same way. The `isis-module-command-jdo` module provides implementations of both (see link:../../components/objectstores/jdo/services/command-service-jdo.html[CommandServiceJdo] and link:../../components/objectstores/jdo/services/background-command-service-jdo.html[BackgroundCommandServiceJdo]).
-
-== BackgroundCommandExecution abstract class
-
-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 suitable concrete implementation.
-
-== Quartz Scheduler Configuration
-
-The last part of the puzzle is to actually run this class. These could be run in a batch job overnight, or run continually by, say, the http://quartz-scheduler.org[Quartz] scheduler. For the latter case, we want to define a Quartz cron job that will inherit the `execute(...)` method of `BackgroundCommandExecution` (inherited from _its_ superclass, `AbstractIsisSessionTemplate`).
-
-If using the `isis-module-command-jdo`, then the following does the trick:
-
-[source]
-----
-import org.apache.isis.objectstore.jdo.service.BackgroundCommandExecutionFromBackgroundCommandServiceJdo;
-
-public class BackgroundCommandExecutionQuartzJob extends AbstractIsisQuartzJob {
-
- public BackgroundCommandExecutionQuartzJob() {
- super(new BackgroundCommandExecutionFromBackgroundCommandServiceJdo());
- }
-}
-----
-
-where `AbstractIsisQuartzJob` is the following boilerplate:
-
-[source]
-----
-import org.quartz.Job;
-import org.quartz.JobExecutionContext;
-import org.quartz.JobExecutionException;
-...
-public class AbstractIsisQuartzJob implements Job {
-
- public static enum ConcurrentInstancesPolicy {
- SINGLE_INSTANCE_ONLY,
- MULTIPLE_INSTANCES
- }
-
- private final AbstractIsisSessionTemplate isisRunnable;
-
- private final ConcurrentInstancesPolicy concurrentInstancesPolicy;
- private boolean executing;
-
- public AbstractIsisQuartzJob(AbstractIsisSessionTemplate isisRunnable) {
- this(isisRunnable, ConcurrentInstancesPolicy.SINGLE_INSTANCE_ONLY);
- }
- public AbstractIsisQuartzJob(
- AbstractIsisSessionTemplate isisRunnable,
- ConcurrentInstancesPolicy concurrentInstancesPolicy) {
- this.isisRunnable = isisRunnable;
- this.concurrentInstancesPolicy = concurrentInstancesPolicy;
- }
-
- // //////////////////////////////////////
-
- public void execute(final JobExecutionContext context)
- throws JobExecutionException {
- final AuthenticationSession authSession = newAuthSession(context);
- try {
- if(concurrentInstancesPolicy == ConcurrentInstancesPolicy.SINGLE_INSTANCE_ONLY &&
- executing) {
- return;
- }
- executing = true;
-
- isisRunnable.execute(authSession, context);
- } finally {
- executing = false;
- }
- }
-
- AuthenticationSession newAuthSession(JobExecutionContext context) {
- String user = getKey(context, SchedulerConstants.USER_KEY);
- String rolesStr = getKey(context, SchedulerConstants.ROLES_KEY);
- String[] roles = Iterables.toArray(
- Splitter.on(",").split(rolesStr), String.class);
- return new SimpleSession(user, roles);
- }
-
- String getKey(JobExecutionContext context, String key) {
- return context.getMergedJobDataMap().getString(key);
- }
-}
-----
-
-This can be configured to run using Quartz' `quartz-config.xml` file:
-
-[source]
-----
-<?xml version="1.0" encoding="UTF-8"?>
-<job-scheduling-data
- xmlns="http://www.quartz-scheduler.org/xml/JobSchedulingData"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://www.quartz-scheduler.org/xml/JobSchedulingData
-http://www.quartz-scheduler.org/xml/job_scheduling_data_1_8.xsd"
- version="1.8">
-
- <schedule>
- <job>
- <name>BackgroundCommandExecutionJob</name>
- <group>Isis</group>
- <description>
- Poll and execute any background actions persisted by the BackgroundActionServiceJdo domain service
- </description>
- <job-class>webapp.scheduler.BackgroundCommandExecutionQuartzJob</job-class>
- <job-data-map>
- <entry>
- <key>webapp.scheduler.user</key>
- <value>scheduler_user</value>
- </entry>
- <entry>
- <key>webapp.scheduler.roles</key>
- <value>admin_role</value>
- </entry>
- </job-data-map>
- </job>
-
- <trigger>
- <cron>
- <name>BackgroundCommandExecutionJobEveryTenSeconds</name>
- <job-name>BackgroundCommandExecutionJob</job-name>
- <job-group>Isis</job-group>
- <cron-expression>0/10 * * * * ?</cron-expression>
- </cron>
- </trigger>
- </schedule>
-</job-scheduling-data>
-----
-
-The remaining two pieces of configuration are the `quartz.properties` file:
-
-[source]
-----
-org.quartz.scheduler.instanceName = SchedulerQuartzConfigXml
-org.quartz.threadPool.threadCount = 1
-org.quartz.jobStore.class = org.quartz.simpl.RAMJobStore
-org.quartz.plugin.jobInitializer.class =org.quartz.plugins.xml.XMLSchedulingDataProcessorPlugin
-org.quartz.plugin.jobInitializer.fileNames = webapp/scheduler/quartz-config.xml
-org.quartz.plugin.jobInitializer.failOnFileNotFound = true
-----
-
-and the entry in `web.xml` for the Quartz servlet:
-
-[source]
-----
-<servlet>
- <servlet-name>QuartzInitializer</servlet-name>
- <servlet-class>org.quartz.ee.servlet.QuartzInitializerServlet</servlet-class>
- <init-param>
- <param-name>config-file</param-name>
- <param-value>webapp/scheduler/quartz.properties</param-value>
- </init-param>
- <init-param>
- <param-name>shutdown-on-unload</param-name>
- <param-value>true</param-value>
- </init-param>
- <init-param>
- <param-name>start-scheduler-on-load</param-name>
- <param-value>true</param-value>
- </init-param>
- <load-on-startup>1</load-on-startup>
- </servlet>
-----
-
-== Registering the Services
-
-Assuming that the `configuration-and-annotation` services installer is configured:
-
-[source]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then Isis' core implementation of `BackgroundService` will be automatically registered and injected into your entities/services.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/adocs/documentation/src/main/asciidoc/user-guide/__/bookmark-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/__/bookmark-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/__/bookmark-service.adoc
deleted file mode 100644
index 1fa7851..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/__/bookmark-service.adoc
+++ /dev/null
@@ -1,48 +0,0 @@
-Title: Bookmark Service
-
-The `BookmarkService` provides the ability to obtain a serializable `org.apache.isis.applib.bookmarks.Bookmark` for any (persisted) domain object, and to lookup domain objects given a `Bookmark`.
-
-This is a good way of storing a reference to an arbitrary object (a polymorphic relationship). The downside is that there is no way for the objectstore (eg JDO objectstore) to enforce any kind of referental integrity.
-
-== API
-
-The API defined by `BookmarkService` is:
-
-[source]
-----
-public interface BookmarkService {
-
- @NotInServiceMenu
- Object lookup(BookmarkHolder bookmarkHolder);
-
- @Programmatic
- Object lookup(Bookmark bookmark);
-
- @Programmatic
- <T> T lookup(Bookmark bookmark, Class<T> requiredType);
-
- @Programmatic
- Bookmark bookmarkFor(Object domainObject);
-
- @Programmatic
- Bookmark bookmarkFor(Class<?> cls, String identifier);
-}
-----
-
-If a domain class implements the `org.apache.isis.applib.bookmarks.BookmarkHolder` interface then the `BookmarkService` will appear as a contributed action. Otherwise the service is hidden from view, intended to be injected into domain objects as a supporting domain service.
-
-== Usage within the framework
-
-Bookmarks are used by the link:./background-service.html[BackgroundCommandService], which uses a bookmark to capture the target object on which an action will be invoked subsequently.
-
-Bookmarks are also used by the link:./publishing-service.html[PublishingService] and the link:./auditing-service.html[AuditingService].
-
-== Implementations
-
-The core framework provides a default implementation of this API:
-
-* `org.apache.isis.core.metamodel.services.bookmarks.BookmarkServiceDefault`
-
-== Register the Service
-
-The `BookmarkServiceDefault` is automatically registered with the framework (it is annotated with `@DomainService`) so there is no need to explicitly register the 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/__/bulk-interaction.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/__/bulk-interaction.adoc b/adocs/documentation/src/main/asciidoc/user-guide/__/bulk-interaction.adoc
deleted file mode 100644
index cd40cd9..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/__/bulk-interaction.adoc
+++ /dev/null
@@ -1,84 +0,0 @@
-Title: Bulk Interaction
-
-The `Bulk.InteractionContext` domain service is a link:../../more-advanced-topics/how-to-09-020-How-to-write-a-typical-domain-service.html[request-scoped] service intended to support the implementation of link:../recognized-annotations/Bulk.html[@Bulk] actions. That is, when a bulk action is invoked over a collection of objects, each object instance "knows where it is" in the collection. In essence, the `Bulk.InteractionContext` service acts a little like an iterator.
-
-=== API
-
-The API defined by the service is:
-
-[source]
-----
-@RequestScoped
-public static class InteractionContext {
-
- public static enum InvokedAs { BULK, REGULAR }
-
- public InvokedAs getInvokedAs() { ... }
-
- public List<Object> getDomainObjects() { ... }
- public int getSize() { ... }
- public int getIndex() { ... }
- public boolean isFirst() { ... }
- public boolean isLast() { ... }
-}
-----
-
-where:
-
-* `getInvokedAs()` tells the domain object whether this particular action invocation is being performed as a
- bulk action (against each domain object in a list of domain objects) or merely as a regular action (against
- a single domain object).
-* `getDomainObjects())` returns the list of domain objects which are being acted upon
-* `getIndex()` is the 0-based index to the object being acted upon.
-
-=== Usage
-
-For bulk actions that are void or that return null, Isis will return to the list once executed. But for bulk
-actions that are non-void, Isis will render the returned object/value from the last object invoked (and simply
-discards the object/value of all actions except the last).
-
-One idiom is for the domain objects to also use the link:./scratchpad.html[Scratchpad] service to share information,
-for example to aggregate values. The `Bulk.InteractionContext#isLast()` method can then be used to determine if
-all the information has been gathered, and then do something with it (eg derive variance across a range of values,
-render a graph etc).
-
-More prosaically, the `Bulk.InteractionContext` can be used to ensure that the bulk action behaves appropriately
-depending on whether it is called in bulk mode or regular mode. Here's a snippet of code from the bulk action in
-the Isis addon example https://github.com/isisaddons/isis-app-todoapp/[todoapp] (not ASF):
-
-[source]
-----
-@Bulk
-public ToDoItem completed() {
- setComplete(true);
- ...
-
- // if invoked as a regular action, return this object;
- // otherwise (if invoked as bulk), return null (so go back to the list)
- return bulkInteractionContext.getInvokedAs() == InvokedAs.REGULAR? this: null;
-}
-----
-
-=== Registering the Service
-
-The `Bulk.InteractionContext` class is automatically registered (it is annotated with `@DomainService`) so no further configuration is required.
-
-=== Unit testing support
-
-The `Bulk.InteractionContext` class also has a couple of static factory
-methods intended to support unit testing:
-
-[source]
-----
-public static InteractionContext regularAction(Object domainObject) {
- return new InteractionContext(InvokedAs.REGULAR, Collections.singletonList(domainObject));
-}
-
-public static InteractionContext bulkAction(Object... domainObjects) {
- return bulkAction(Arrays.asList(domainObjects));
-}
-
-public static InteractionContext bulkAction(List<Object> domainObjects) {
- return new InteractionContext(InvokedAs.BULK, domainObjects);
-}
-----
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/adocs/documentation/src/main/asciidoc/user-guide/__/command-context.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/__/command-context.adoc b/adocs/documentation/src/main/asciidoc/user-guide/__/command-context.adoc
deleted file mode 100644
index 5e7e661..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/__/command-context.adoc
+++ /dev/null
@@ -1,213 +0,0 @@
-Title: CommandContext
-
-The `CommandContext` service is a link:../../more-advanced-topics/how-to-09-020-How-to-write-a-typical-domain-service.html[request-scoped] service that reifies the invocation of an action on a domain object into an object itself. This reified information is encapsulated within the `Command` object.
-
-By default, the `Command` is held in-memory only; once the action invocation has completed, the `Command` object is gone. The optional
- supporting `CommandService` enables the implementation of `Command` to be pluggable. With an appropriate implementation (eg as provided by the `isis-command-module-jdo`'s link:./command-service.html[CommandServiceJdo]) the `Command` may then 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
-
-Assuming that the `CommandService` supports persistent `Command`s, 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 `CommandContext` request-scoped service defines the following very simple API:
-
-[source]
-----
-@RequestScoped
-public class CommandContext {
-
- @Programmatic
- public Command getCommand() { ... }
-}
-----
-
-where `Command` is defined in turn as:
-
-[source]
-----
-public interface Command extends HasTransactionId {
-
- public abstract String getUser();
- public abstract Timestamp getTimestamp();
-
- public abstract Bookmark getTarget();
- public abstract String getMemberIdentifier();
- public abstract String getTargetClass();
- public abstract String getTargetAction();
- public String getArguments();
- public String getMemento();
-
- public ExecuteIn getExecuteIn();
- public Executor getExecutor();
- public Persistence getPersistence();
- public boolean isPersistHint();
-
- public abstract Timestamp getStartedAt();
- public abstract Timestamp getCompletedAt();
- public Command getParent();
-
- public Bookmark getResult();
- public String getException();
-
-}
-----
-
-and where `Command` has the members:
-
-* `getUser()` - is the user that initiated the action.
-* `getTimestamp()` - the date/time at which this action was created.
-* `getTarget()` - bookmark of the target object (entity or service) on which this action was performed
-* `getMemberIdentifier()` - holds a string representation of the invoked action
-* `getTargetClass()` - a human-friendly description of the class of the target object
-* `getTargetAction()` - a human-friendly name of the action invoked on the target object
-* `getArguments()` - a human-friendly description of the arguments with which the action was invoked
-* `getMemento()` - a formal (XML or similar) specification of the action to invoke/being invoked
-* `getExecuteIn()` - whether this command is executed in the foreground or background
-* `getExecutor()` - the (current) executor of this command, either user, or background service, or other (eg redirect after post).
-* `getPersistence()`- the policy controlling whether this command should ultimately be persisted (either "persisted", "if hinted", or "not persisted")
-* `isPersistHint()` - whether that the command should be persisted, if persistence policy is "if hinted".
-* `getStartedAt()` - the date/time at which this action started (same as `timestamp` property for foreground commands)
-* `getCompletedAt()` - the date/time at which this action completed.
-* `getParent()` - for actions created through the `BackgroundService`, captures the parent action
-* `getResult()` - bookmark to object returned by action, if any
-* `getException()` - exception stack trace if action threw exception
-
-== Implementation
-
-==== CommandContext
-
-The `CommandContext` implementation is part of the core framework (isis-core), in fact is a concrete class in the applib:
-
-* `org.apache.isis.applib.services.command.CommandContext`
-
-==== CommandService (for persistent `Command`s)
-
-The `CommandService` interface - which acts as the factory for different `Command` implementations - is pluggable. The link:command-service.html[isis-module-command-jdo] implementation persists `Command`s to an RDBMS.
-
-== Usage
-
-==== Explicitly treating an action as a command
-
-The typical way to indicate that an action should be treated as a command is to annotate it with the link:../recognized-annotations/Command.html[@Command] annotation, for example:
-
-[source]
-----
-public class ToDoItem ... {
-
- @Command
- public ToDoItem completed() { ... }
-
-}
-----
-
-The annotation can also be used to specify whether the command should be performed in the background, for example:
-
-[source]
-----
-public class ToDoItem ... {
-
- @Command(executeIn=ExecuteIn.BACKGROUND)
- public ToDoItem scheduleImplicitly() {
- completeSlowly(3000);
- return this;
- }
-}
-----
-
-When a background command is invoked, the user is returned the command object itself (to provide a handle to the command being invoked).
-
-This requires that an implementation of `CommandService` that persists the commands (such as `isis-module-command-jdo`'s `CommandService` link:./command-service.html[implementation]) is configured. It also requires that a scheduler is configured to execute the background commands, see link:./background-command-service.html[BackgroundCommandService]).
-
-==== Making commands the default
-
-As an alternative to annotating every action with `@Command`, alternatively this can be configured as the default.
-
-To treat every action as a command, add the following to `isis.properties`:
-
-[source]
-----
-isis.services.command.actions=all
-----
-
-For some applications it may be required to record (as commands) only those actions that update objects; in other words queries and searches can be ignored. Put another way, only actions annotated (with link:../recognized-annotations/ActionSemantics.html[@ActionSemantics]) as IDEMPOTENT or NON_IDEMPOTENT should be treated as commands. In this case, use:
-
-[source]
-----
-isis.services.command.actions=ignoreQueryOnly
-----
-
-To prevent an action from being treated as a command (even if globally enabled), use the `@Command` annotation with the `disabled` attribute:
-
-[source]
-----
-@Command(disabled=true)
-public void notACommand() { ... }
-----
-
-To disable globally, use:
-
-[source]
-----
-isis.services.command.actions=none
-----
-
-If the key is not present in `isis.properties`, then commands are disabled by default.
-
-==== Interacting with the services
-
-Typically the domain objects have little need to interact with the `CommandContext` and `Command` directly; what is more useful is that these are persisted in support of the various use cases identified above.
-
-One case however where a domain object might want to obtain the `Command` is to determine whether it has been invoked in the foreground, or in the background. It can do this using the `getExecutedIn()` method:
-
-[source]
-----
-ExecutedIn executedIn = commandContext.getCommand().getExecutedIn();
-----
-
-If run in the background, it might then notify the user (eg by email) if all work is done.
-
-This leads us onto a related point, distinguishng the effective user vs the real user. When running in the foreground, the current user can be obtained from the `DomainObjectContainer`, using:
-
-[source]
-----
-String user = container.getUser().getName();
-----
-
-If running in the background, however, then the current user will be the credentials of the background process, for example as run by a Quartz scheduler job.
-
-The domain object can still obtain the original ("effective") user that caused the job to be created, using:
-
-[source]
-----
-String user = commandContext.getCommand().getUser();
-----
-
-== Registering the Services
-
-Assuming that the `configuration-and-annotation` services installer is configured:
-
-[source]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then the `CommandContext` service is automatically registered and injected into your entities/services; no further configuration is required.
-
-== Related Services
-
-As discussed above, the supporting link:./command-service.html[CommandService] enables `Command` objects to be persisted. Other related services are the link:./background-service.html[BackgroundService] and link:./background-service.html[BackgroundCommandService]). For `BackgroundService` captures commands for execution in the background, while the [BackgroundCommandService] persists such commands for 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/__/command-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/__/command-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/__/command-service.adoc
deleted file mode 100644
index 9aad39c..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/__/command-service.adoc
+++ /dev/null
@@ -1,87 +0,0 @@
-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/__/deep-link-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/__/deep-link-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/__/deep-link-service.adoc
deleted file mode 100644
index 6f6c81f..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/__/deep-link-service.adoc
+++ /dev/null
@@ -1,39 +0,0 @@
-Title: Deep Link Service (1.8.0)
-
-The `DeepLinkService` provides the ability to obtain a `java.net.URI` that links to a representation of any (persisted) domain entity or
-view model.
-
-The framework currently provides a single implementation for accessing the representation provided by the Wicket viewer.
-
-== API
-
-The API defined by `DeepLinkService` is:
-
-[source]
-----
-public interface DeepLinkService {
-
- /**
- * Creates a URI that can be used to obtain a representation of the provided domain object in one of the
- * Isis viewers.
- */
- URI deepLinkFor(Object domainObject);
-}
-----
-
-== Implementations
-
-== Usage within the framework
-
-At the time of writing there is no usage within the core framework, though this service is (planned to be) used by
-some of the http://www.isisaddons.org[Isis addons].
-
-== Implementations
-
-The Wicket viewer core framework provides a default implementation of this API:
-
-* `org.apache.isis.viewer.wicket.viewer.services.DeepLinkServiceWicket`
-
-== Register the Service
-
-The `DeepLinkServiceWicket` is automatically registered with the framework (it is annotated with `@DomainService`) so there is no need to explicitly register the 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/__/developer-utilities-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/__/developer-utilities-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/__/developer-utilities-service.adoc
deleted file mode 100644
index 900f22f..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/__/developer-utilities-service.adoc
+++ /dev/null
@@ -1,72 +0,0 @@
-Title: Developer Utilities Service
-
-{note
-In 1.6.0 this implementation was released as part of _org.apache.isis.core:isis-module-devutils-jdo:1.6.0_ and was also released as an http://github.com/isisaddons/isis-module-devutils[Isis addon] module. *In 1.7.0+ only the http://github.com/isisaddons/isis-module-devutils[Isis addon] implementation is released.*
-}
-
-The `DeveloperUtilitiesService` service provides a number of development-time utilities, mostly related to accessing/interacting with the Isis metamodel. These are visible in the UI, either as menu actions or as contributed actions. All actions are annotated with link:../recognized-annotations/Prototype-deprecated.html[@Prototype], so are suppressed in link:../deployment-type.html[production mode].
-
-=== API
-
-The API defined by `DeveloperUtilitiesService` (some annotations omitted) is:
-
-[source]
-----
-public interface DeveloperUtilitiesService {
-
- public Clob downloadMetaModel();
-
- public Blob downloadLayouts();
-
- public void refreshServices();
-
- @NotInServiceMenu
- public Clob downloadLayout(Object domainObject);
-
- @Deprecated // as of 1.4.0
- @Hidden // as of 1.4.0
- @NotInServiceMenu
- public Object refreshLayout(Object domainObject);
-}
-----
-
-where:
-
-*
-
-`downloadMetaModel()` allows the developer to download a CSV spreadsheet of the Isis metamodel.
-
-The developer can then review the metadata that has Isis has captured about each domain type: for example whether a business rule (hide/disable/validate) has been implemented for each member (also indicating the implementation)
-
-*
-
-`downloadLayouts()` allows the developer can download a ZIP file of `Xxx.layout.json` files for each domain type in the Isis metamodel.
-
-This is useful if converting a domain model to use link:../../components/viewers/wicket/dynamic-layouts.html[dynamic layouts].
-
-*
-
-`downloadLayout()` (contributed action) allows the developer can download the `Xxx.layout.json` for an individual object
-
-*
-
-`refreshServices()` allows the developer to rebuild the Isis metamodel of all domain services. This is particularly useful for picking up changes to link:../../more-advanced-topics/how-to-01-062-How-to-decouple-dependencies-using-contributions.html[contributed actions]
-
-The `refreshLayout()` (which rebuild the Isis metamodel of the current object so that the UI refreshes) has been deprecated and hidden; the link:../../components/viewers/wicket/about.html[Wicket viewer]) (when running in prototype mode) now automatically does this does this.
-
-=== Implementations
-
-The core framework provides a default implementation of this API:
-
-* `org.apache.isis.core.metamodel.services.devutils.DeveloperUtilitiesServiceDefault`
-
-=== Register the Service
-
-The service is registered, like any other, in `isis.properties`:
-
-[source]
-----
-isis.services=...,\
- org.apache.isis.core.metamodel.services.devutils.DeveloperUtilitiesServiceDefault,\
- ...
-----
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/adocs/documentation/src/main/asciidoc/user-guide/__/email-notification-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/__/email-notification-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/__/email-notification-service.adoc
deleted file mode 100644
index b8b168b..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/__/email-notification-service.adoc
+++ /dev/null
@@ -1,63 +0,0 @@
-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/__/email-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/__/email-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/__/email-service.adoc
deleted file mode 100644
index abb5fd8..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/__/email-service.adoc
+++ /dev/null
@@ -1,81 +0,0 @@
-Title: Email Service (1.8.0)
-
-The email service provides the ability to send emails to one or more recipients. The framework also provides a default implementation that sends email as an HTML message, using an external SMTP provider.
-
-== API
-
-The API for the service is:
-
-[source]
-----
-public interface EmailService {
-
- @PostConstruct
- @Programmatic
- public void init() ;
-
- @Programmatic
- boolean send(List<String> to, List<String> cc, List<String> bcc, String subject, String body, DataSource... attachments);
-
- @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 main API to send the email (and optional attachments)
-* `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 (`EmailServiceDefault`) that sends email as an HTML message, using an external SMTP provider.
-
-To use this service the following properties must be configured:
-
-* `isis.service.email.sender.address`
-* `isis.service.email.sender.password`
-
-and these properties may optionally be configured (each has a default):
-
-* `isis.service.email.sender.hostname` (defaults to "smtp.gmail.com" if not specified)
-* `isis.service.email.port` (defaults to "587" if not specified)
-* `isis.service.email.tls.enabled` (defaults to "true" if not specified)
-
-These configuration properties can be specified either in `isis.properties` or in an link:../externalized-configuration.html[external configuration file].
-
-If prototyping (that is, running the app using `org.apache.isis.WebServer`), the configuration properties can also be specified as system properties. For example, if you create a test email account on gmail, you can configure the service using:
-
-[source]
-----
--Disis.service.email.sender.address=xxx@gmail.com -Disis.service.email.sender.password=yyy
-----
-
-where "xxx" is the gmail user account and "yyy" is its password
-
-== Alternative Implementations
-
-If you wish to write an alternative implementation, be aware that it should process the message body as HTML (as opposed to plain text or any other format).
-
-Also, note that (unlike most Isis domain services) the implementation is also instantiated and injected by Google Guice. This is because `EmailService` 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 email service is used by the `EmailNotificationService`, see link:./email-notification-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/__/event-bus-service.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/__/event-bus-service.adoc b/adocs/documentation/src/main/asciidoc/user-guide/__/event-bus-service.adoc
deleted file mode 100644
index 25c150d..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/__/event-bus-service.adoc
+++ /dev/null
@@ -1,210 +0,0 @@
-Title: Event Bus Service
-
-The `EventBusService` is a wrapper for a https://code.google.com/p/guava-libraries/[Guava] https://code.google.com/p/guava-libraries/wiki/EventBusExplained[`EventBus`], allowing arbitrary events to be posted and subscribed to (within the Isis runtime). The primary use case is for decoupling interactions from one module/package/namespace and another.
-
-The framework also provides an implementation of this service (`EventBusServiceJdo`), and this is automatically registered (it is annotated with `@DomainService`).
-
-Domain events are raised automatically whenever any domain object is interacted with. Domain events can also be raised programmatically if required (though there is rarely any need to do so).
-
-Only domain services should be registered as subscribers; not domain entities. Domain services are guaranteed to be instantiated and resident in memory, whereas the same is not true of domain entities.
-
-The typical implementation of a domain service subscriber is to identify the impacted entities, load them using a repository query, and then to delegate to the event to them.
-
-== Publishing
-
-=== Automatically published events
-
-Domain events are raised automatically whenever an object member (property, collection or action) is interacted with. Specifically:
-
-* when an object member is to be viewed, an event is fired; subscribers can veto (meaning that the member is hidden)
-* when an object member is to be enabled, the same event instance is fired; subscribers can veto (meaning that the member is disabled, ie cannot be edited/invoked)
-* when an object member is being validated, then a new event instance is fired; subscribers can veto (meaning that the candidate values/action arguments are rejected)
-* when an object member is about to be changed, then the same event instance is fired; subscribers can perform pre-execution operations
-* when an object member has been changed, then the same event instance is fired; subscribers can perform post-execution operations
-
-If a subscriber throws an exception in the first three steps, then the interaction is vetoed. If a subscriber throws an exception in the last two steps, then the transaction is aborted.
-
-The event class that is raised can be specified using an annotation:
-
-*
-
-as of 1.8.0, using:
-
-** `@Property(domainEvent=...)`
-** `@Collection(domainEvent=...)`
-** `@Action(domainEvent=...)`
-*
-
-as of 1.7.0 (but deprecated in 1.8.0), using :
-
-** `@PropertyInteraction`
-** `@CollectionInteraction`
-** `@ActionInteraction`
-*
-
-as of 1.6.0 (but deprecated in 1.8.0), using :
-
-** `@PostsPropertyChangedEvent`
-** `@PostsCollectionAddedToEvent`/`@PostsCollectionRemovedFromEvent`
-** `@PostsActionInvokedEvent`
-
-For example, in the Isis addons example https://github.com/isisaddons/isis-app-todoapp/[todoapp] (not ASF) a custom event is raised when an item is completed:
-
-[source]
-----
-public static class CompletedEvent extends AbstractActionDomainEvent {
- private static final long serialVersionUID = 1L;
- public CompletedEvent(
- final ToDoItem source,
- final Identifier identifier,
- final Object... arguments) {
- super("completed", source, identifier, arguments);
- }
-}
-
- @Action(
- domainEvent =CompletedEvent.class,
- ...
- )
- public ToDoItem completed() { ... }
-----
-
-Subscribers can therefore subscribe to these subclasses, in effect filtering out only the events that are of interest.
-
-=== Explicitly publishing events
-
-The publishing API defined by `EventBusService` is:
-
-[source]
-----
-public abstract class EventBusService {
- public void post(Object event) { ... }
- ...
-}
-----
-
-where
-
-* `post(Object)` posts the event onto event bus (it is simply a wrapper that delegates to `EventBus#post(Object)`)
-
-== Subscribing
-
-The subscribing API defined by `EventBusService` is:
-
-[source]
-----
-public abstract class EventBusService {
- public void post(Object event) { ... }
- ...
-}
-----
-
-where:
-* `register(Object)` registers the object with the event bus (it is simply a wrapper that delegates to `EventBus#register(Object)`)
-* `unregister(Object)` unregisters the object with the event bus (it is simply a wrapper that delegates to `EventBus#unregister(Object)`)
-
-The are for domain services to call to register themselves with the event bus. This should be done in the
-
-As of 1.8.0, the `register` and `unregister` methods should be called in the `@PostConstruct` and `@PreDestroy` lifecycle methods:
-
-[source]
-----
-@DomainService
-public class MySubscribingDomainService {
-
- ...
-
- @Programmatic
- @PostConstruct
- public void postConstruct() {
- eventBusService.register(this);
- }
- @Programmatic
- @PreDestroy
- public void preDestroy() {
- eventBusService.unregister(this);
- }
-
- @javax.inject.Inject
- private EventBusService eventBusService;
-}
-----
-
-This works for both application-scoped and request-scoped (`@RequestScoped`) domain services.
-
-In 1.7.0, the registration should be done when the `EventBusService` is injected into it:
-
-[source]
-----
-@DomainService
-public class MySubscribingDomainService {
-
- ...
-
- private EventBusService eventBusService;
- public void injectEventBusService(final EventBusService eventBusService) {
- this.eventBusService = eventBusService;
- eventBusService.register(this);
- }
-}
-----
-
-=== Callbacks
-
-The actual callbacks of events is done by annotating a method on the class (that is, the usual Guava programming model).
-
-For example, the subscriber in the todoapp for completed todo items would use the following callback:
-
-[source]
-----
-@Programmatic
-@Subscribe
-public void on(final ToDoItem.CompletedEvent ev) { ... }
-----
-
-As a slightly more interesting example, suppose in a library domain that a `LibraryMember` wants to leave the library. A letter should be sent out detailing any books that they still have out on loan:
-
-In the `LibraryMember` class, we publish the event:
-
-[source]
-----
-public class LibraryMember {
- ...
- @Action(domainEvent=LibraryMemberLeaveEvent.class)
- public void leave() {
- ...
- }
- ...
-}
-----
-
-Meanwhile, in the `BookRepository` domain service, we subscribe to the event and act upon it:
-
-[source]
-----
-public class BookRepository {
-
- @com.google.common.eventbus.Subscribe
- @Programmatic
- public void onLibraryMemberLeaving(LibraryMemberLeaveEvent e) {
- LibraryMember lm = e.getLibraryMember();
- List<Book> lentBooks = findBooksOnLoanFor(lm);
- if(!lentBooks.isEmpty()) {
- sendLetter(lm, lentBooks);
- }
- }
- ...
-}
-----
-
-This design allows the `libraryMember` module to be decoupled from the `book` module.
-
-== Implementation and Registration
-
-Isis provides the `org.apache.isis.objectstore.jdo.datanucleus.service.eventbus.EventBusServiceJdo` as a default implementation of the `EventBusService` API. The `EventBusServiceJdo` class is automatically registered (it is annotated with `@DomainService`) so no further configuration is required.
-
-== Related Services
-
-The `EventBusService` 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).
-
-The link:publishing-service.html[PublishingService] meanwhile 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`].
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/2af3ad9a/adocs/documentation/src/main/asciidoc/user-guide/__/exception-recognizers.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/__/exception-recognizers.adoc b/adocs/documentation/src/main/asciidoc/user-guide/__/exception-recognizers.adoc
deleted file mode 100644
index c7407f9..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/__/exception-recognizers.adoc
+++ /dev/null
@@ -1,131 +0,0 @@
-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