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/06/16 07:41:56 UTC
[08/45] isis git commit: ISIS-1133: breaking out reference guide and
devenv guide;
moving appendices' release notes and migration notes to other docs;
improving the documentation page.
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
deleted file mode 100644
index 79284df..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi.adoc
+++ /dev/null
@@ -1,270 +0,0 @@
-[[_ug_reference-services-spi]]
-= Reference: Domain Services SPI
-: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/
-
-
-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)] chapter.
-
-There are other domain services that constitute not an API but an SPI; if present they are used by Isis itself rather than by your domain objects. A good example of this is the xref:_ug_reference-services-spi_manpage-AuditingService[`AuditingService`] 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 xref:_ug_reference-services-api_manpage-EmailService[`EmailService`] that is of direct use for domain objects wishing to send out emails, but is also used by the framework to support the xref:_ug_wicket-viewer_features_user-registration[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 for xref:_ug_reference-annotations_manpage-Action_domainEvent[`@Action#domainEvent()`] etc.
-
-For these hybrid services we have categorized the service as an "API" service. This chapter therefore contains only the strictly SPI services.
-
-
-The table below lists the SPIs that are defined in the Isis applib (`o.a.i.core:isis-core-applib` module).
-
-
-.Applib SPI Services
-[cols="2,4a,1,1", options="header"]
-|===
-
-
-|SPI
-|Description
-|Implementation
-|Notes
-
-
-|xref:_ug_reference-services-spi_manpage-AuditingService[`o.a.i.applib.` +
-`services.audit` +
-`AuditingService3`]
-|Create an audit record for every changed property of every changed object within a transaction.
-|`AuditingService` +
-``o.ia.m.audit`` +
-``isis-module-audit``
-|related services:
-`AuditingService-` +
-`Contributions`,
-`AuditingService-` +
-`Repository`
-
-|xref:_ug_reference-services-spi_manpage-BackgroundCommandService[`o.a.i.applib.` +
-`services.background` +
-`BackgroundCommandService`]
-|Persisted a memento of an action invocation such that it can be executed asynchronously ("in the background") eg by a scheduler.
-|`BackgroundCommandServiceJdo` +
-``o.ia.m.command`` +
-``isis-module-command``
-|related services:
-`BackgroundCommandService-` +
-`JdoContributions`,
-`BackgroundCommandService-` +
-`JdoRepository`
-
-
-|xref:_ug_reference-services-spi_manpage-ClassDiscoveryService[`o.a.i.applib.` +
-`services.classdiscovery` +
-`ClassDiscoveryService`]
-|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:_ug_reference-classes_super_manpage-FixtureScript[`FixtureScript`]).
-|`ClassDiscoveryService-` +
-`UsingReflections` +
-``o.a.i.core`` +
-``isis-core-applib``
-|requires `org.reflections:reflections` as Maven dependency
-
-
-|xref:_ug_reference-services-spi_manpage-CommandService[`o.a.i.applib.` +
-`services.command.spi` +
-`CommandService`]
-|Service to act as a factory and repository (create and save) of command instances, ie representations of an action invocation. Used for command/auditing and background services.
-|`CommandServiceJdo` +
-``o.ia.m.command`` +
-``isis-module-command``
-|related services: +
-`CommandService-` ++
-`JdoContributions`,
-`CommandService-` ++
-`JdoRepository`
-
-
-|xref:_ug_reference-services-spi_manpage-EmailNotificationService[`o.a.i.applib.` +
-`services.userreg` +
-`EmailNotificationService`]
-|Notify a user during xref:_ug_reference-services-spi_manpage-UserRegistrationService[self-registration] of users.
-|`EmailNotificationService-` +
-`Default` +
-``o.a.i.core`` +
-``isis-core-runtime``
-|depends on: +
-a configured `EmailService`
-
-|xref:_ug_reference-services-spi_manpage-EventSerializer[`o.a.i.applib.` +
-`services.publish` +
-`EventSerializer`]
-|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`` +
-``isis-module-publishing``
-|
-
-
-|xref:_ug_reference-services-spi_manpage-ExceptionRecognizer[`o.a.i.applib.` +
-`services.exceprecog` +
-`ExceptionRecognizer2`]
-|Convert certain exceptions (eg foreign or unique key violation in the database) into a format that can be rendered to the end-user.
-|`ExceptionRecognizer-` +
-`CompositeFor-` +
-`JdoObjectStore` +
-``o.a.i.core`` +
-``isis-core-applib``
-|Extensible using composite pattern if required
-
-
-|xref:_ug_reference-services-spi_manpage-LocaleProvider[`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:_ug_reference-services-spi_manpage-TranslationService[`TranslationService`].
-|`LocaleProviderWicket` +
-``o.a.i.viewer`` +
-``isis-viewer-wicket-impl``
-|
-
-|xref:_ug_reference-services-spi_manpage-PublishingService[`o.a.i.applib.` +
-`services.publish` +
-`PublishingService`]
-|Publish any action invocations and changed objects, typically for interchange with an external system in a different bounded context.
-|`PublishingService` +
-``o.ia.m.publishing`` +
-``isis-module-publishing``
-|related services:
-`PublishingService-` ++
-`Contributions`,
-`PublishingService-` ++
-`Repository`. +
-depends on: +
-`EventSerializer`
-
-
-|xref:_ug_reference-services-spi_manpage-TranslationService[`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:_ug_reference-services-spi_manpage-LocaleProvider[`LocalProvider`].
-|`TranslationServicePo` +
-``o.a.i.core`` +
-``isis-core-runtime``
-|related services: `TranslationServicePoMenu` +
-depends on: +
-`TranslationsResolver`, `LocaleProvider`
-
-
-|xref:_ug_reference-services-spi_manpage-TranslationsResolver[`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:_ug_reference-services-spi_manpage-TranslationService[`TranslationService`]
-|`TranslationsResolverWicket` +
-``o.a.i.viewer`` +
-``isis-viewer-wicket-impl``
-|
-
-
-|xref:_ug_reference-services-spi_manpage-UserProfileService[`o.a.i.applib.` +
-`services.userprof` +
-`UserProfileService`]
-|Obtain an alternative (usually enriched/customized) name for the current user, to render in the UI.
-|
-|
-
-|xref:_ug_reference-services-spi_manpage-UserRegistrationService[`o.a.i.applib.` +
-`services.userreg` +
-`UserRegistrationService`]
-|Create a new user account with the configured security mechanism.
-|`SecurityModule-` +
-`AppUserRegistrationService` +
-``o.ia.m.security`` +
-``isis-module-security``
-|depends (implicitly) on: +
-a configured `EmailService`
-
-
-|===
-
-
-Key:
-
-* `o.a.i` is an abbreviation for `org.apache.isis`
-* `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:_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).
-
-
-
-
-There are also some "internal" SPI services whose definitions depend on the internals of the framework (rather than the applib).
-
-[WARNING]
-====
-We do not guarantee that link:http://semver.org[semantic versioning] will be honoured for these APIs.
-====
-
-
-
-."Internal" SPI Services
-[cols="3,3,2,2a", options="header"]
-|===
-
-|SPI
-|Maven Module +
-Impl'n (g: a:)
-|Implementation
-|Notes
-
-
-|xref:_ug_reference-services-spi_manpage-ContentMappingService[`o.a.i.v.ro.` +
-`rendering.service.conneg.` +
-`ContentMappingService`]
-|(Attempt to) map the returned data into the representation required by the client's HTTP `Accept` header.
-|
-|No default implementation.
-
-|xref:_ug_reference-services-spi_manpage-ContentNegotiationService[`o.a.i.v.ro.` +
-`rendering.service.conneg.` +
-`ContentNegotiationService`]
-|Encodes the algorithm that delegates to any registered xref:_ug_reference-services-spi_manpage-ContentMappingService[`ContentMappingService`]s.
-|`ContentNegotiationService-` +
-`XRoDomainType` +
-``o.a.i.core`` +
-`isis-core-viewer-restfulobjects-rendering`
-|
-
-
-|xref:_ug_reference-services-spi_manpage-RepresentationService[`o.a.i.v.ro.` +
-`rendering.service.` +
-`RepresentationService`]
-|Generates the representations, delegating to any registered xref:_ug_reference-services-spi_manpage-ContentNegotiationService[`ContentNegotiationService`]s.
-|`RepresentationService-` +
-`ForRestfulObjects` +
-``o.a.i.core`` +
-`isis-core-viewer-restfulobjects-rendering`
-|
-
-
-|===
-
-Key:
-
-* `o.a.i.v.ro` is an abbreviation for `org.apache.isis.viewer.restfulobjects`
-
-
-include::_ug_reference-services-spi_manpage-AuditingService.adoc[leveloffset=+1]
-include::_ug_reference-services-spi_manpage-BackgroundCommandService.adoc[leveloffset=+1]
-include::_ug_reference-services-spi_manpage-ClassDiscoveryService.adoc[leveloffset=+1]
-include::_ug_reference-services-spi_manpage-CommandService.adoc[leveloffset=+1]
-include::_ug_reference-services-spi_manpage-ContentMappingService.adoc[leveloffset=+1]
-include::_ug_reference-services-spi_manpage-ContentNegotiationService.adoc[leveloffset=+1]
-include::_ug_reference-services-spi_manpage-EmailNotificationService.adoc[leveloffset=+1]
-include::_ug_reference-services-spi_manpage-EventSerializer.adoc[leveloffset=+1]
-include::_ug_reference-services-spi_manpage-ExceptionRecognizer.adoc[leveloffset=+1]
-include::_ug_reference-services-spi_manpage-LocaleProvider.adoc[leveloffset=+1]
-include::_ug_reference-services-spi_manpage-PublishingService.adoc[leveloffset=+1]
-include::_ug_reference-services-spi_manpage-RepresentationService.adoc[leveloffset=+1]
-include::_ug_reference-services-spi_manpage-TranslationService.adoc[leveloffset=+1]
-include::_ug_reference-services-spi_manpage-TranslationsResolver.adoc[leveloffset=+1]
-include::_ug_reference-services-spi_manpage-UserProfileService.adoc[leveloffset=+1]
-include::_ug_reference-services-spi_manpage-UserRegistrationService.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-AuditingService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-AuditingService.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-AuditingService.adoc
deleted file mode 100644
index d281e30..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-AuditingService.adoc
+++ /dev/null
@@ -1,84 +0,0 @@
-[[_ug_reference-services-spi_manpage-AuditingService]]
-= `AuditingService3`
-: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/
-
-
-
-
-The `AuditingService3` auditing service provides a simple mechanism to capture changes to data. It is called for each property that has changed on any domain object, as a set of pre- and post-values.
-
-[NOTE]
-====
-In case you are wondering what happened to `AuditingService` and `AuditingService2`, these were earlier versions of the SPI that have since been deprecated and removed.
-====
-
-
-== SPI
-
-The SPI for the service is:
-
-[source,java]
-----
-public interface AuditingService3 {
-
- @Programmatic
- public void audit(
- final UUID transactionId, String targetClassName, final Bookmark target,
- String memberIdentifier, final String propertyName,
- final String preValue, final String postValue,
- final String user, final java.sql.Timestamp timestamp);
- }
-----
-
-The framework will call this for each and every domain object property that is modified within a transaction.
-
-
-
-== Implementation
-
-The most full-featured available implementation is the (non-ASF) http://github.com/isisaddons/isis-module-audit[Isis addons' Audit module]. This creates an audit records for each changed property (ie every time that `AuditingService3#audit(...)` is called. The implementation is `org.isisaddons.module.audit.dom.AuditingService`.
-
-The module also provides:
-
-* `AuditingServiceMenu` service which provides actions to search for ``AuditEntry``s, underneath an 'Activity' menu on the secondary menu bar.
-
-* `AuditingServiceRepository` service to to search for persisted `AuditEntry``s. None of its actions are visible in the user interface (they are all `@Programmatic`).
-
-* `AuditingServiceContributions` which contrbutes collections to the xref:_ug_reference-classes_mixins_manpage-HasTransactionId[ `HasTransactionId`] interface. This will therefore display all audit entries that occurred in a given transaction, in other words whenever a command, a published event or another audit entry is displayed.
-
-
-
-If you just want to debug (writing to stderr), you can instead configure `o.a.i.applib.services.audit.AuditingService3$Stderr`
-
-
-
-== Usage
-
-The typical way to indicate that an object should be audited is to annotate it with the xref:_ug_reference-annotations_manpage-DomainObject_auditing[`@DomainObject#auditing()`] annotation.
-
-
-
-
-== Registering the Services
-
-Assuming that the `configuration-and-annotation` services installer is configured:
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then adding the (non-ASF) http://github.com/isisaddons/isis-module-audit[Isis addons' audit] module to the classpath will automatically register the `AuditingService`, `AuditingServiceMenu`, `AuditingServiceRepository` and `AuditingServiceContributions` services. If menu items or contributions are not required in the UI, these can be suppressed either using security or by implementing a xref:_ug_more-advanced_decoupling_vetoing-visibility[vetoing subscriber].
-
-
-
-== Related Services
-
-The auditing service works very well with the xref:_ug_reference-services-spi_manpage-CommandService[`CommandService`]. The `CommandService` captures the _cause_ of an interaction (an action was invoked, a property was edited), while the `AuditingService3` captures the _effect_ of that interaction in terms of changed state.
-
-You may also want to configure the xref:_ug_reference-services-spi_manpage-PublishingService[`PublishingService`].
-
-All three of these services collaborate implicitly by way of the xref:_ug_reference-classes_mixins_manpage-HasTransactionId[`HasTransactionId`] interface.
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
deleted file mode 100644
index 76bb0ef..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-BackgroundCommandService.adoc
+++ /dev/null
@@ -1,129 +0,0 @@
-[[_ug_reference-services-spi_manpage-BackgroundCommandService]]
-= `BackgroundCommandService`
-: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/
-
-
-
-The `BackgroundCommandService` (SPI) service supports the xref:_ug_reference-services-api_manpage-BackgroundService[`BackgroundService`] (API) service, 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 xref:_ug_reference-services-spi_manpage-BackgroundCommandService[`BackgroundCommandService`] `BackgroundCommandService` to actually persist it.
-
-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 xref:_ug_reference-services-api_manpage-BackgroundService_BackgroundCommandExecution[`BackgroundCommandExecution`] provides a mechanism to execute such commands. This can be considered an API, albeit "internal" because the implementation relies on internals of the framework.
-
-
-
-== SPI
-
-The SPI of the `BackgroundCommandService` is:
-
-[source,java]
-----
-public interface BackgroundCommandService {
- void schedule(
- ActionInvocationMemento aim, // <1>
- Command parentCommand, // <2>
- String targetClassName,
- String targetActionName,
- String targetArgs);
-
-}
-----
-<1> is a wrapper around a xref:_ug_reference-services-api_manpage-MementoService[`MementoService`]'s `Memento`, capturing the details of the action invocation to be retained (eg persisted to a database) so that it can be executed at a later time
-<2> reference to the parent `Command` requesting the action be performed as a background command. This allows information such as the initiating user to be obtained.
-
-The API of `ActionInvocationMemento` in turn is:
-
-[source,java]
-----
-public class ActionInvocationMemento {
- public String getActionId() { ... }
- public String getTargetClassName() { ... }
- public String getTargetActionName() { ... }
- public Bookmark getTarget() { ... }
- public int getNumArgs() { ... }
- public Class<?> getArgType(int num) throws ClassNotFoundException { ... }
- public <T> T getArg(int num, Class<T> type) { ... }
-
- public String asMementoString() { ... } // <1>
-}
-----
-<1> lets the `BackgroundCommandService` implementation convert the action invocation into a simple string.
-
-
-
-== "Internal" SPI
-
-The `BackgroundCommandExecution` (in isis-core) is an abstract template class for xref:_ug_headless-access_AbstractIsisSessionTemplate[headless access], that defines an abstract hook method to obtain background `Command`s to be executed:
-
-[source,java]
-----
-public abstract class BackgroundCommandExecution
- extends AbstractIsisSessionTemplate {
- ...
- protected abstract List<? extends Command> findBackgroundCommandsToExecute();
- ...
-}
-----
-
-The developer is required to implement this hook method in a subclass.
-
-
-
-
-== Implementation
-
-The (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module provides an implementation (`org.isisaddons.module.command.dom.BackgroundCommandServiceJdo`) that persists ``Command``s using the JDO/DataNucleus object store. It further provides a number of supporting services:
-
-* `org.isisaddons.module.command.dom.BackgroundCommandServiceJdoRepository` is a repository to search for persisted background ``Command``s
-
-* `org.isisaddons.module.command.dom.BackgroundCommandServiceJdoContributions` contributes actions for searching for persisted child and sibling ``Command``s.
-
-The module also provides a concrete subclass of `BackgroundCommandExecution` that knows how to query for persisted (background) `Command`s such that they can be executed by a scheduler.
-
-[TIP]
-====
-Details of setting up the Quartz scheduler to actually execute these persisted commands can be found on the xref:_ug_reference-services-api_manpage-BackgroundService[`BackgroundService`] page.
-====
-
-
-
-
-== Usage
-
-Background commands can be created either declaratively or imperatively.
-
-The declarative approach involves annotating an action using xref:_ug_reference-annotations_manpage-Action_command[`@Action#command()`] with `@Action#commandExecuteIn=CommandExecuteIn.BACKGROUND`.
-
-The imperative approach involves explicitly calling the xref:_ug_reference-services-api_manpage-BackgroundService[`BackgroundService`] from within domain object's action.
-
-
-
-
-== Registering the Services
-
-Assuming that the `configuration-and-annotation` services installer is configured:
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then adding the (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module to the classpath will automatically register the `BackgroundCommandServiceJdo`, `BackgroundCommandJdoRepository` and `BackgroundCommandServiceJdoContributions` services. If contributions are not required in the UI, these can be suppressed either using security or by implementing a xref:_ug_more-advanced_decoupling_vetoing-visibility[vetoing subscriber].
-
-Note that this module also provides service implementations of the xref:_ug_reference-services-spi_manpage-CommandService[`CommandService`].
-
-
-
-
-== Related Services
-
-As discussed above, this service supports the xref:_ug_reference-services-api_manpage-BackgroundService[`BackgroundService`] , persisting `Command`s such that they can be executed in the background.
-
-There is also a tie-up with the xref:_ug_reference-services-api_manpage-CommandContext[`CommandContext`] and its supporting xref:_ug_reference-services-spi_manpage-CommandService[`CommandService`] domain 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 (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module.).
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-ClassDiscoveryService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-ClassDiscoveryService.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-ClassDiscoveryService.adoc
deleted file mode 100644
index e8c43fa..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-ClassDiscoveryService.adoc
+++ /dev/null
@@ -1,81 +0,0 @@
-[[_ug_reference-services-spi_manpage-ClassDiscoveryService]]
-= `ClassDiscoveryService`
-: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/
-
-
-
-The `ClassDiscovery` service is used to automatically discover subclasses of any given type on the classpath. The primary use case is to support "convention-over-configuration" designs that work with a minimum of configuration.
-
-This service is used by the xref:_ug_reference-classes_super_manpage-FixtureScripts[`FixtureScripts`] service to automatically locate any xref:_ug_reference-classes_super_manpage-FixtureScript[`FixtureScript`] implementations.
-
-
-
-== SPI
-
-The SPI defined by the service is:
-
-[source,java]
-----
-public interface ClassDiscoveryService2 {
- @Programmatic
- <T> Set<Class<? extends T>> findSubTypesOfClasses(Class<T> type, String packagePrefix);
- @Deprecated
- @Programmatic
- <T> Set<Class<? extends T>> findSubTypesOfClasses(Class<T> type); // <1>
-}
-----
-<1> no longer used
-
-
-
-== Implementation
-
-Isis provides an implementation of this service, namely `o.a.i.applib.services.classdiscovery.ClassDiscoveryServiceUsingReflections`.
-
-[NOTE]
-====
-This implementation is also used to discover domain services annotated with xref:_ug_reference-annotations_manpage-DomainService[`@DomainService`]. Currently this logic uses the implementation directly, so is not pluggable. However, the entire `ServicesInstaller`
-====
-
-
-
-== Usage
-
-The usage will vary depending upon the conventions of the design. In the case of fixture scripts, the convention is to implement scripts by subclassing xref:_ug_reference-classes_super_manpage-FixtureScript[`FixtureScript`], and to specify the package prefix in the constructor for xref:_ug_reference-classes_super_manpage-FixtureScripts[`FixtureScripts`].
-
-For example, the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] has its fixture scripts in the `todoapp.fixture` package. the `ToDoAppFixturesService` (its subclass of xref:_ug_reference-classes_super_manpage-FixtureScripts[`FixtureScripts`] is in the same package, so its constructor is:
-
-[source,java]
-----
-package todoapp.fixture;
-...
-@DomainService(nature = NatureOfService.VIEW_MENU_ONLY)
-public class ToDoAppFixturesService extends FixtureScripts {
- public ToDoAppFixturesService() {
- super(
- ToDoAppFixturesService.class.getPackage().getName(), // <1>
- MultipleExecutionStrategy.EXECUTE);
- }
- ...
-}
-----
-<1> specify the package prefix to search under for fixture scripts
-
-Other designs using this service are likely to work in a similar way, requiring some sort of scope to be specified.
-
-
-== Registering the Services
-
-Assuming that the `configuration-and-annotation` services installer is configured:
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then Isis' core implementation of `ClassDiscoveryService2` service is automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
deleted file mode 100644
index 6ece1eb..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-CommandService.adoc
+++ /dev/null
@@ -1,99 +0,0 @@
-[[_ug_reference-services-spi_manpage-CommandService]]
-= `CommandService`
-: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/
-
-
-
-The `CommandService` service supports the xref:_ug_reference-services-api_manpage-CommandContext[`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 xref:_ug_reference-services-api_manpage-BackgroundService[`BackgroundService`]
-* if xref:_ug_reference-services-spi_manpage-AuditingService[auditing] is configured, they provide better audit information, since the `Command` (the 'cause' of an action) can be correlated to the audit records (the "effect" of the action) by way of the xref:_ug_reference-classes_mixins_manpage-HasTransactionId[`transactionId`]
-* if xref:_ug_reference-services-spi_manpage-PublishingService[publishing] is configured, they provide better traceability as the `Command` is also correlated with any published events, again through the unique xref:_ug_reference-classes_mixins_manpage-HasTransactionId[`transactionId`]
-* the associated xref:_ug_reference-annotations_manpage-Action_command[`@Action#command()`] annotation attribute 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.
-
-
-
-The screencast below 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.
-
-
-
-video::tqXUZkPB3EI[youtube,width="560px",height="315px"]
-
-[NOTE]
-====
-Note that this screencast shows an earlier version of the xref:_ug_wicket-viewer[Wicket viewer] UI (specifically, pre 1.8.0).
-====
-
-
-== SPI
-
-The `CommandService` service defines the following very simple API:
-
-[source,java]
-----
-public interface CommandService {
- @Programmatic
- Command create();
- @Programmatic
- void startTransaction(Command command, final UUID transactionId);
- @Programmatic
- void complete(Command command);
- @Programmatic
- boolean persistIfPossible(Command command);
-}
-----
-
-where `Command` is defined as defined by the xref:_ug_reference-services-api_manpage-CommandContext[`CommandContext`] service.
-
-
-== Implementation
-
-The (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module provides an implementation (`org.isisaddons.module.command.dom.CommandServiceJdo`) that persists ``Command``s using the JDO/DataNucleus object store. It further provides a number of supporting services:
-
-* `org.isisaddons.module.command.dom.CommandServiceJdoRepository` is a repository to search for persisted ``Command``s
-
-* `org.isisaddons.module.command.dom.CommandServiceJdoContributions` contributes actions for searching for persisted child and sibling ``Command``s.
-
-
-
-== Usage
-
-The typical way to indicate that an action should be reified into a `Command` is by annotating the action using xref:_ug_reference-annotations_manpage-Action_command[`@Action#command()`].
-
-
-
-
-== Registering the Services
-
-Assuming that the `configuration-and-annotation` services installer is configured:
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-
-then adding the (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module to the classpath will automatically register the `CommandServiceJdo`, `CommandJdoRepository` and `CommandServiceJdoContributions` services. If contributions are not required in the UI, these can be suppressed either using security or by implementing a xref:_ug_more-advanced_decoupling_vetoing-visibility[vetoing subscriber].
-
-Note that this module also provides service implementations of the xref:_ug_reference-services-spi_manpage-BackgroundCommandService[`BackgroundCommandService`].
-
-
-
-== Related Services
-
-As discussed above, this service supports the xref:_ug_reference-services-api_manpage-CommandContext[`CommandContext`], providing the ability for `Command` objects to be
-persisted. This is closely related to the xref:_ug_reference-services-spi_manpage-BackgroundCommandService[`BackgroundCommandService`]that allows the xref:_ug_reference-services-api_manpage-BackgroundService[`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.
-
-The services provided by this module combines very well with the xref:_ug_reference-services-spi_manpage-AuditingService[`AuditingService`]. The `CommandService` captures the _cause_ of an interaction (an action was invoked, a property was edited), while the `AuditingService3` captures the _effect_ of that interaction in terms of changed state.
-
-You may also want to configure the xref:_ug_reference-services-spi_manpage-PublishingService[`PublishingService`].
-
-All three of these services collaborate implicitly by way of the xref:_ug_reference-classes_mixins_manpage-HasTransactionId[`HasTransactionId`] interface.
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-ContentMappingService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-ContentMappingService.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-ContentMappingService.adoc
deleted file mode 100644
index 1aa87f8..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-ContentMappingService.adoc
+++ /dev/null
@@ -1,106 +0,0 @@
-[[_ug_reference-services-spi_manpage-ContentMappingService]]
-= `ContentMappingService`
-: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/
-
-
-
-The `ContentMappingService` supports the (default implementation of the) xref:_ug_reference-services-spi_manpage-ContentNegotiationService[`ContentNegotiationService`] allowing the xref:_ug_restfulobjects-viewer[RestfulObjects viewer] to allow domain objects to be transformed into some other format as specified by the HTTP `Accept` header.
-
-See xref:_ug_reference-services-spi_manpage-ContentNegotiationService[`ContentNegotiationService`] for further discussion.
-
-
-
-
-== SPI
-
-The SPI defined by this service is:
-
-[source,java]
-----
-public interface ContentMappingService {
- @Programmatic
- Object map(Object object, // <1>
- List<MediaType> acceptableMediaTypes, // <2>
- RepresentationType representationType); // <3>
-
-}
-
-----
-<1> typically the input is a domain object (whose structure might change over time), and the output is a DTO (whose structure is guaranteed to be preserved over time)
-<2> as per the caller's HTTP `Accept` header
-<3> the representation type required (as per the link:http://restfulobjects.org[Restful Objects spec]).
-
-
-[WARNING]
-====
-This is an "internal" SPI, meaning that it uses types that are not part of the Isis applib. We do not guarantee that link:http://semver.org[semantic versioning] will be honoured for these APIs.
-====
-
-
-== Implementations
-
-No default implementations are provided by Isis framework itself. However, the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] includes a sample implementation to convert its `ToDoItem` entity into a `ToDoItemDto` (JAXB annotated and derived from an XSD). This uses the link:http://orika-mapper.github.io/orika-docs/intro.html[Orika] mapping library.
-
-The source code is:
-
-[source,java]
-----
-@DomainService(nature = NatureOfService.DOMAIN)
-public class CustomContentMappingService implements ContentMappingService {
- private MapperFactory mapperFactory; // <1>
- @Programmatic
- @PostConstruct
- public void init() {
- mapperFactory = new DefaultMapperFactory.Builder().build();
- mapperFactory.registerClassMap(
- mapperFactory.classMap(ToDoItem.class, ToDoItemDto.class) // <2>
- .byDefault() // <3>
- .toClassMap());
- mapperFactory.registerClassMap(
- mapperFactory.classMap(Bookmark.class, OidDto.class) // <4>
- .field("identifier", "objectIdentifier") // <5>
- .byDefault() // all other fields are compatible // <6>
- .toClassMap());
- }
- @Programmatic
- @Override // <7>
- public Object map(
- final Object object,
- final List<MediaType> acceptableMediaTypes,
- final RepresentationType representationType) {
- if(object instanceof ToDoItem) {
- final Bookmark bookmark = bookmarkService.bookmarkFor(object);
- final ToDoItemDto dto =
- mapperFactory.getMapperFacade().map(object, ToDoItemDto.class); // <8>
- final OidDto oidDto =
- mapperFactory.getMapperFacade().map(bookmark, OidDto.class); // <9>
- dto.setOid(oidDto); // <10>
- return dto;
- }
- return null;
- }
-
- @javax.inject.Inject
- private BookmarkService bookmarkService;
-}
-----
-<1> registry of known mappings
-<2> how to map `ToDoItem` to `ToDoItemDto` ...
-<3> ... all properties have same name in both source and destination types
-<4> how to map `Bookmark` to `OidDto` ...
-<5> ... this property has a different name
-<6> ... all other properties have same name
-<7> the main API to implement. This implementation ignores the `acceptableMediaTypes` and `representationType`
-<8> map the domain object to the DTO
-<9> and map its oid (by way of the xref:_ug_reference-services-api_manpage-BookmarkService[`BookmarkService`]
-<10> and perform some additional manual wiring (because domain objects don't _know_ their Oids).
-
-You'll notice that the implementation doesn't actually use the `acceptableMediaTypes` and `representationType` parameters. That's because the calling `ContentNegotiationServiceXRoDomainType` will double check that the returned object is of the correct type (as defined by the `x-ro-domain-type` parameter of the HTTP `Accept` header). Since this (example) todoapp only offers a single mapping, there's therefore no need to for the mapping service to check further.
-
-
-
-== Related Services
-
-This service is a companion to the default implementation of the xref:_ug_reference-services-spi_manpage-ContentNegotiationService[`ContentNegotiationService`].
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-ContentNegotiationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-ContentNegotiationService.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-ContentNegotiationService.adoc
deleted file mode 100644
index 8ef6a2b..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-ContentNegotiationService.adoc
+++ /dev/null
@@ -1,189 +0,0 @@
-[[_ug_reference-services-spi_manpage-ContentNegotiationService]]
-= `ContentNegotiationService`
-: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/
-
-
-
-The `ContentNegotiationService` is a plug-in point for the xref:_ug_restfulobjects-viewer[RestfulObjects viewer] so that it can generate representations according to HTTP `Accept` header of the request. This idea is discussed in section 34.1 of the link:http://restfulobjects.org[Restful Objects spec] v1.0.
-
-The principal motivation is to allow more flexible representations to be generated for REST clients that (perhaps through their use of a certain Javascript library, say) expect, or at least works best with, a certain style of representation.
-
-Another use case is to support "third party" REST clients over which you have no control. In this scenario you _must not_ naively expose entities through the RO viewer, because over time those entities will inevitably evolve and change their structure. If the entities were exposed directly then those REST clients will break.
-
-Instead you need to create some sort of stable facade over your domain entities, one which you will preserve even if the domain entities change. There are three ways in which you can do this:
-
-* first is to solve the problem at the domain layer by defining a regular Isis xref:_ug_more-advanced_view-models[view model]. This is then surfaced over the RO viewer. +
-+
-If the underlying entities change, then care must be taken to ensure that structure of the view model nevertheless is unchanged.
-
-* a second option is to solve the problem at the persistence layer, but defining a (SQL) view in the database and then xref:_ug_more-advanced_mapping-rdbms-views[mapping this] to a (read-only) entity. Again this is surfaced by the RO viewer. +
-+
-If the underlying tables change (as the result of a change in their corresponding domain entities) then once more the view must be refactored so that it still presents the same structure.
-
-* our third option is to solve the problem at the presentation layer, using the `ContentNegotiationService` described in this section. +
-+
-The `ContentNegotiationService` is responsible for inspecting the HTTP `Accept` header, and use this to select the correct representation to render. +
-+
-The Isis framework provides a default implementation of `ContentNegotiationService` which inspects the "x-ro-domaintype" component of the HTTP `Accept` header. If present, this implementation will delegate to the companion xref:_ug_reference-services-spi_manpage-ContentMappingService[`ContentMappingService`] service, if configured. +
-+
-A typical implementation of `ContentMappingService` will convert the domain object into some sort of DTO (data transfer object) as specified by the "x-ro-domaintype". If this DTO is annotated with JAXB or Jackson mappings, then the RO viewer (courtesy of the underlying link:http://resteasy.jboss.org/[RestEasy] framework) can serialize these directly +
-+
-What all that means is that, if the underlying entities change, we are required to update the mappings in the `ContentMappingService` to map to the same DTOs.
-
-This diagram illustrates the three options available:
-
-image::{_imagesdir}reference-services-spi/ContentNegotiationService/facade-choices.png[width="700px",link="{_imagesdir}reference-services-spi/ContentNegotiationService/facade-choices.png"]
-
-
-
-
-== SPI
-
-The SPI defined by this service is:
-
-[source,java]
-----
-public interface ContentNegotiationService {
- @Programmatic
- Response.ResponseBuilder buildResponse( // <1>
- RepresentationService.Context2 renderContext2,
- ObjectAdapter objectAdapter);
- @Programmatic
- Response.ResponseBuilder buildResponse( // <2>
- RepresentationService.Context2 renderContext2,
- ObjectAndProperty objectAndProperty);
- @Programmatic
- Response.ResponseBuilder buildResponse( // <3>
- RepresentationService.Context2 renderContext2,
- ObjectAndCollection objectAndCollection);
- @Programmatic
- Response.ResponseBuilder buildResponse( // <4>
- RepresentationService.Context2 renderContext2,
- ObjectAndAction objectAndAction);
- @Programmatic
- Response.ResponseBuilder buildResponse( // <5>
- RepresentationService.Context2 renderContext2,
- ObjectAndActionInvocation objectAndActionInvocation);
-}
-----
-<1> representation of a single object, as per section 14.4 of the RO spec, v1.0
-<2> representation of a single property of an object, as per section 16.4 of the RO spec v1.0
-<3> representation of a single collection of an object, as per section 17.5 of the RO spec v1.0
-<4> representation of a single action (prompt) of an object, as per section 18.2 of the RO spec v1.0
-<5> representation of the results of a single action invocation, as per section 19.5 of the RO spec v1.0
-
-These methods provide:
-
-* a `RepresentationService.Context2` which provides access to request-specific context (eg HTTP headers), session-specific context (eg authentication) and global context (eg configuration settings)
-
-* an object representing the information to be rendered +
-+
-eg `ObjectAdapter`, `ObjectAndProperty`, `ObjectAndCollection` etc
-
-In all cases, returning `null` will result in the regular RO spec representation being returned.
-
-
-[WARNING]
-====
-This is an "internal" SPI, meaning that it uses types that are not part of the Isis applib. We do not guarantee that link:http://semver.org[semantic versioning] will be honoured for these APIs.
-====
-
-
-
-== Implementation
-
-`ContentNegotiationServiceAbstract` (in `o.a.i.v.ro.rendering.service.conneg`) provides a no-op implementation of the SPI, along with supporting methods:
-
-[source,java]
-----
-public abstract class ContentNegotiationServiceAbstract implements ContentNegotiationService {
- ...
- protected Object objectOf(final ObjectAdapter objectAdapter) { ... }
- protected Object returnedObjectOf(ObjectAndActionInvocation objectAndActionInvocation) { ... }
-
- protected Class<?> loadClass(String cls) { ... }
-
- protected void ensureJaxbAnnotated(Class<?> domainType) { ... }
- protected void ensureDomainObjectAssignable(
- String xRoDomainType, Class<?> domainType, Object domainObject) { ... }
-}
-----
-
-As discussed in the introduction, the framework also provides a default implementation, `o.a.i.v.ro.rendering.service.conneg.ContentNegotiationServiceXRoDomainType`. This handles content negotiation for two of the possible representations, object representations and for action result representations:
-
-* For object representations it will handle requests with HTTP `Accept` headers of the form:
-** `application/json;profile=urn:org.restfulobjects:repr-types/object;x-ro-domain-type=...`
-** `application/xml;profile=urn:org.restfulobjects:repr-types/object;x-ro-domain-type=...`
-
-* for action result representations it will similarly handle requests with HTTP `Accept` headers of the form:
-** `application/json;profile=urn:org.restfulobjects:repr-types/action-result;x-ro-domain-type=...` +
-** `application/xml;profile=urn:org.restfulobjects:repr-types/action-result;x-ro-domain-type=...`
-
-
-The value of the `x-ro-domain-type` parameter corresponds to the DTO to be mapped into by the xref:_ug_reference-services-spi_manpage-ContentMappingService[`ContentMappingService`].
-
-If the DTO is annotated with JAXB, then also note that the runtime type must be annotated with the JAXB `javax.xml.bind.annotation.XmlRootElement` so that RestEasy is able to unambiguously serialize it.
-
-
-
-
-== Usage
-
-You can find an example of all these services in the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp]. This defines a `ToDoItemDto` class that is JAXB annotated (it is in fact generated from an XSD).
-
-The example app also includes an implementation of `ContentMappingService` that maps `todoapp.dom.module.todoitem.ToDoItem` entities to `todoapp.dto.module.todoitem.ToDoItemDto` classes.
-
-A REST client can therefore request a DTO representation of an entity by invoking
-
-[source]
-----
-http://localhost:8080/restful/objects/TODO/0
-----
-
-with an `Accept` header of:
-
-[source]
-----
-application/xml;profile=urn:org.restfulobjects:repr-types/object;x-ro-domain-type=todoapp.dto.module.todoitem.ToDoItemDto
-----
-
-will result in an XML serialization of that class:
-
-image::{_imagesdir}reference-services-spi/ContentNegotiationService/accept-xml.png[width="700px",link="{_imagesdir}reference-services-spi/ContentNegotiationService/accept-xml.png"]
-
-
-while similarly hitting the same URL with an `Accept` header of:
-
-[source]
-----
-application/json;profile=urn:org.restfulobjects:repr-types/object;x-ro-domain-type=todoapp.dto.module.todoitem.ToDoItemDto
-----
-
-will result in the JSON serialization of that class:
-
-image::{_imagesdir}reference-services-spi/ContentNegotiationService/accept-json.png[width="700px",link="{_imagesdir}reference-services-spi/ContentNegotiationService/accept-json.png"]
-
-
-
-
-== Registering the Services
-
-Assuming that the `configuration-and-annotation` services installer is configured:
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then Isis' default implementation of `ContentNegotiationService` service is automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
-
-
-
-
-== Related Services
-
-The default implementation of `ContentNegotiationService` delegates to xref:_ug_reference-services-spi_manpage-ContentMappingService[`ContentMappingService`] (if present) to convert domain entities into a stable form (eg DTO).
-
-The `ContentNegotiationService` is itself called by the (default implementation of) xref:_ug_reference-services-spi_manpage-RepresentationService[`RepresentationService`].
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
deleted file mode 100644
index ec2be22..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-EmailNotificationService.adoc
+++ /dev/null
@@ -1,80 +0,0 @@
-[[_ug_reference-services-spi_manpage-EmailNotificationService]]
-= `EmailNotificationService`
-: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/
-
-
-
-The `EmailNotificationService` supports the xref:_ug_wicket-viewer_features_user-registration[user registration] (self sign-up) features of the xref:_ug_wicket-viewer[Wicket viewer] 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 xref:_ug_reference-services-spi_manpage-UserRegistrationService[`UserRegistrationService`]) 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 `UserRegistrationService`).
-
-The role of this service in all of this is to format and send out emails for the initial registration, or for password resets.
-
-The default implementation of this service uses the xref:_ug_reference-services-api_manpage-EmailService[`EmailService`], which must be configured in order for user registration to be enabled.
-
-
-== SPI
-
-The SPI defined by this service is:
-
-[source,java]
-----
-public interface EmailNotificationService extends Serializable {
- @Programmatic
- boolean send(EmailRegistrationEvent ev); // <1>
- @Programmatic
- boolean send(PasswordResetEvent ev); // <2>
- @Programmatic
- boolean isConfigured(); // <3>
-}
-----
-<1> sends an email to verify an email address as part of the initial user registration
-<2> sends an email to reset a password for an already-registered user
-<3> 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
-
-The framework provides a default implementation, `o.a.i.core.runtime.services.userreg.EmailNotificationServiceDefault` that constructs the emails to send.
-
-
-
-=== Alternative Implementations
-
-The text of these email templates is hard-coded as resources, in other words baked into the core jar files. If you need to use different text then you can of course always write and register your own implementation to be used instead of Isis' default.
-
-If you have configured an alternative email service implementation, it should process the message body as HTML.
-
-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 xref:_ug_wicket-viewer_features_user-registration[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`.
-
-
-
-== Registering the Service
-
-Assuming that the `configuration-and-annotation` services installer is configured:
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then Isis' default implementation of `EmailNotificationService` service is automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
-
-
-== Related Services
-
-As noted elsewhere, the default implementation of this service uses xref:_ug_reference-services-api_manpage-EmailService[`EmailService`]. This service has no specific configuration properties but does require that the `EmailService` has been configured.
-
-Conversely, this service is used by (Isis' default implementation of) xref:_ug_reference-services-spi_manpage-UserRegistrationService[`UserRegistrationService`].
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-EventSerializer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-EventSerializer.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-EventSerializer.adoc
deleted file mode 100644
index 4e7facc..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-EventSerializer.adoc
+++ /dev/null
@@ -1,72 +0,0 @@
-[[_ug_reference-services-spi_manpage-EventSerializer]]
-= `EventSerializer`
-: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/
-
-
-The `EmailSerializer` service is a supporting service intended for use by (any implementation of) xref:_ug_reference-services-spi_manpage-PublishingService[`PublishingService`]. Its responsibility is to combine the `EventMetadata` and the `EventPayload` into some serialized form (such as JSON, XML or a string) that can then be published.
-
-See xref:_ug_reference-services-spi_manpage-PublishingService[`PublishingService`] for further discussion.
-
-
-
-
-== SPI
-
-The SPI defined by this service is:
-
-[source,java]
-----
-public interface EventSerializer {
- Object serialize( // <1>
- EventMetadata metadata, // <2>
- EventPayload payload); // <3>
-}
-----
-<1> returns an object for maximum flexibility, which is then handed off to the `PublishingService`.
-<2> standard metadata about the event, such as the user, the xref:_ug_reference-classes_mixins_manpage-HasTransactionId[`transactionId`], date/time etc
-<3> for published actions, will generally be an `EventPayloadForActionInvocation` (or subclass thereof); for published objects, will generally be an `EventPayloadForObjectChanged` (or subclass thereof)
-
-It's important to make sure that the publishing service implementation is able to handle the serialized form. Strings are a good lowest common denominator, but in some cases a type-safe equivalent, such as a w3c DOM `Document` or JSON node might be passed instead.
-
-
-
-
-
-== Implementation
-
-The (non-ASF) http://github.com/isisaddons/isis-module-publishing[Isis addons' publishing] module provides an implementation (`org.isisaddons.module.publishing.dom.eventserializer.RestfulObjectsSpecEventSerializer`) that represents the event payload using the representation defined by the link:http://restfulobjects.org[Restful Objects spec] of (transient) objects, grafting on the metadata as additional JSON nodes.
-
-For example, this is the JSON generated on an action invocation:
-
-.JSON representation of a published action invocation
-image::{_imagesdir}reference-services-spi/EventSerializer/action-invocation-published-to-stderr.png[width="750px",link="{_imagesdir}reference-services-spi/EventSerializer/action-invocation-published-to-stderr.png"]
-
-while this is the object change JSON:
-
-.JSON representation of a published changed object
-image::{_imagesdir}reference-services-spi/EventSerializer/changed-object-published-to-stderr.png[width="750px",link="{_imagesdir}reference-services-spi/EventSerializer/changed-object-published-to-stderr.png"]
-
-You could if you wish change the representation by registering your own implementation of this API in `isis.properties`:
-
-
-
-
-
-== Registering the Services
-
-Assuming that the `configuration-and-annotation` services installer is configured:
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then adding the (non-ASF) http://github.com/isisaddons/isis-module-publishing[Isis addons' publishing] module to the classpath will automatically register the `RestfulObjectsSpecEventSerializer` implementation (and also the module's `PublishingService` implementation).
-
-
-
-== Related Services
-
-This service is intended (though not mandated) to be used by implementations of xref:_ug_reference-services-spi_manpage-PublishingService[`PublishingService`].
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
deleted file mode 100644
index 8a30b60..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-ExceptionRecognizer.adoc
+++ /dev/null
@@ -1,123 +0,0 @@
-[[_ug_reference-services-spi_manpage-ExceptionRecognizer]]
-= `ExceptionRecognizer`
-: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/
-
-
-The `ExceptionRecognizer` service provides the mechanism for both the domain programmer and also for components to be able to recognize and handle certain exceptions that may be thrown by the system. Rather than display an obscure error to the end-user, the application can instead display a user-friendly message.
-
-For example, the JDO/DataNucleus Objectstore provides a set of recognizers to recognize and handle SQL constraint exceptions such as uniqueness violations. These can then be rendered back to the user as expected errors, rather than fatal stacktraces.
-
-It is also possible to provide additional implementations, registered in `isis.properties`. Unlike other services, where any service registered in `isis.properties` replaces any default implementations, in the case of this service all implementations registered are "consulted" to see if they recognize an exception (the chain-of-responsibility pattern).
-
-
-
-
-== SPI
-
-The SPI defined by this service is:
-
-[source,java]
-----
-public interface ExceptionRecognizer2 ... {
- public enum Category { // <1>
- ...
- }
- public static class Recognition { // <2>
- private Category category;
- private String reason;
- ...
- }
- @Programmatic
- public Recognition recognize2(Throwable ex); // <3>
-
- @Deprecated
- @Programmatic
- public String recognize(Throwable ex); // <4>
-
-}
-----
-<1> an enumeration of varies categories of exceptions that are recognised
-<2> represents the fact that an exception has been recognized as has been converted into a user-friendy message, and has been categorized
-<3> the main API, to attempt to recognize an exception
-<4> deprecated API which converted exceptions into strings (reasons), ie without any categorization. This is no longer called.
-
-
-The categories are:
-
-[source,java]
-----
-public interface ExceptionRecognizer2 ... {
- public enum Category {
- CONSTRAINT_VIOLATION, // <1>
- NOT_FOUND, // <2>
- CONCURRENCY, // <3>
- CLIENT_ERROR, // <4>
- SERVER_ERROR, // <5>
- OTHER // <6>
- }
- ...
-}
-
-----
-<1> a violation of some declarative constraint (eg uniqueness or referential integrity) was detected.
-<2> the object to be acted upon cannot be found (404)
-<3> a concurrency exception, in other words some other user has changed this object.
-<4> recognized, but for some other reason... 40x error
-<5> 50x error
-<6> recognized, but uncategorized (typically: a recognizer of the original `ExceptionRecognizer` API).
-
-
-In essence, if an exception is recognized then it is also categorized. This lets the viewer act accordingly. For example, if an exception is raised from the loading of an individual object, then this is passed by the registered ``ExceptionRecognizer``s. If any of these recognize the exception as representing a not-found exception, then an Isis `ObjectNotFoundException` is raised. Both the viewers interprets this correctly (the xref:_ug_wicket-viewer[Wicket viewer] as a suitable error page, the xref:_ug_restfulobjects-viewer[Restful Objects viewer] as a 404 status return code).
-
-
-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.
-
-
-
-
-== Implementation
-
-The framework provides two default implementations:
-
-* `o.a.i.core.metamodel.services.container.DomainObjectContainerDefault` provided by Isis core is itself an `ExceptionRecognizer`, and will handle ``ConcurrencyException``s. It will also handle any application exceptions raised by the system (subclasses of `o.a.i.applib.RecoverableException`).
-
-* `o.a.i.objectstore.jdo.applib.service.exceprecog.ExceptionRecognizerCompositeForJdoObjectStore` bundles up a number of more fine-grained implementations:
-** `ExceptionRecognizerForSQLIntegrityConstraintViolationUniqueOrIndexException`
-** `ExceptionRecognizerForJDOObjectNotFoundException`
-** `ExceptionRecognizerForJDODataStoreException`
-
-
-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 create a fine-grained implementation of `ExceptionRecognizer2` for the particular error message (there are some convenience implementations of the interface that you can subclass from if required) and register in `isis.properties`.
-
-
-
-
-== Registering the Services
-
-
-Assuming that the `configuration-and-annotation` services installer is configured:
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then the default implementations provided by the framework (`DomainObjectContainerDefault` and `ExceptionRecognizerCompositeForJdoObjectStore`) will be registered.
-
-In addition, you can register any further exception recognizers in `isis.properties`:
-
-[source,ini]
-----
-isis.services=...,\
- com.mycompany.myapp.MyExceptionRecognizer,\
- ...
-----
-
-[NOTE]
-====
-Prior to 1.9.0, the `ExceptionRecognizerCompositeForJdoObjectStore` also required manual registration:
-
-====
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-LocaleProvider.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-LocaleProvider.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-LocaleProvider.adoc
deleted file mode 100644
index 9ce21a5..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-LocaleProvider.adoc
+++ /dev/null
@@ -1,71 +0,0 @@
-[[_ug_reference-services-spi_manpage-LocaleProvider]]
-= `LocaleProvider`
-: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/
-
-
-
-The `LocaleProvider` service is one of the services that work together to implement Isis' support for i18n, being used by Isis' default implementation of xref:_ug_reference-services-spi_manpage-TranslationService[`TranslationService`].
-
-The role of the service itself is simply to return the `Locale` of the current user.
-
-
-[NOTE]
-====
-For the "big picture" and further details on Isis' i18n support, see xref:_ug_more-advanced_i18n[here].
-====
-
-
-
-== SPI
-
-The SPI defined by this service is:
-
-[source,java]
-----
-public interface LocaleProvider {
- @Programmatic
- Locale getLocale();
-}
-----
-
-This is notionally request-scoped, returning the `Locale` of the current user; _not_ that of the server. (Note that the implementation is not required to actually be xref:_ug_reference-annotations_manpage-RequestScoped[`@RequestScoped`], however).
-
-
-
-
-== Implementation
-
-Isis' xref:_ug_wicket-viewer[Wicket viewer] provides an implementation of this service (`LocaleProviderWicket`) which leverages Apache Wicket APIs.
-
-[NOTE]
-====
-Currently there is no equivalent implementation for the xref:_ug_restfulobjects-viewer[RestfulObjects viewer].
-====
-
-
-
-
-== Registering the Services
-
-Assuming that the `configuration-and-annotation` services installer is configured:
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-and that the xref:_ug_wicket-viewer[Wicket viewer] is being used then an implementation of `LocaleProvider` is automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
-
-
-
-
-
-== Related Services
-
-This service works in conjunction with xref:_ug_reference-services-spi_manpage-TranslationService[`TranslationService`] and xref:_ug_reference-services-spi_manpage-TranslationsResolver[`TranslationsResolver`] in order to provide i18n support.
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/9c5dafab/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
deleted file mode 100644
index 9cb2229..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_ug_reference-services-spi_manpage-PublishingService.adoc
+++ /dev/null
@@ -1,163 +0,0 @@
-[[_ug_reference-services-spi_manpage-PublishingService]]
-= `PublishingService`
-: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/
-
-
-
-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 and of changed objects. A typical use case is to publish onto a pub/sub bus such as link:http://activemq.apache.org/[ActiveMQ] with link:http://camel.apache.org[Camel] to keep other systems up to date.
-
-
-
-== SPI
-
-The SPI defined by the service is:
-
-[source,java]
-----
-public interface PublishingService {
- public void publish(
- EventMetadata metadata, // <1>
- EventPayload payload); // <2>
- @Deprecated
- @Programmatic
- void setEventSerializer(EventSerializer eventSerializer); // <3>
-}
-----
-<1> standard metadata about the event, such as the user, the xref:_ug_reference-classes_mixins_manpage-HasTransactionId[`transactionId`], date/time etc
-<2> for published actions, an `EventPayloadForActionInvocation` (or subclass thereof); for published objects, an `EventPayloadForObjectChanged` (or subclass thereof)
-<3> injects in the xref:_ug_reference-services-spi_manpage-EventSerializer[`EventSerializer`] service. This is deprecated because not every implementation is required to use an `EventSerializer` so its inclusion within the SPI of `PublishingService` was in retrospect a mistake.
-
-
-Typically implementations will use the injected `EventSerializer` to convert the metadata and payload into a form to be published:
-
-[source,java]
-----
-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.
-
-
-
-== Implementation
-
-The (non-ASF) http://github.com/isisaddons/isis-module-publishing[Isis addons' publishing] module provides an implementation (`org.isisaddons.module.publishing.dom.org.apache.isis.applib.services.publish`) that persists each event as a `PublishedEvent` entity. This holds the serialized form of the event metadata and payload as translated into a string by the injected `EventSerializer`. The module also provides its own implementation of `EventSerializer`, namely `RestfulObjectsSpecEventSerializer`, which represents the event payload using the representation defined by the link:http://restfulobjects.org[Restful Objects spec] of (transient) objects, grafting on the metadata as additional JSON nodes.
-
-The `PublishedEvent` entity also has a `state` field taking the values either "QUEUED" or "PROCESSED". The intention here is that an event bus can poll this table to grab pending events and dispatch them to downstream systems. When ``PublishedEvent``s are persisted initially they always take the value "QUEUED".
-
-
-
-
-== Usage
-
-To indicate that an action invocation should be published, annotate it with the xref:_ug_reference-annotations_manpage-Action_publishing[`@Action#publishing()`] annotation.
-
-To indicate that a changed object should be published is to annotate it with the xref:_ug_reference-annotations_manpage-DomainObject_publishing[`@DomainObject#publishing()`] annotation.
-
-
-It is also possible to "fine-tune" the `EventPayload` using the `#publishingFactory()` attribute (for both annotations). By default 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 any information about 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.
-
-Although the representations (if using the Restful Object serializer and Restful Objects viewer) does include hrefs for the objects, this nevertheless requires an additional network call to obtain this information).
-
-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, we implement the `PublishingPayloadFactoryForAction` (in `o.a.i.applib.annotation`):
-
-[source,java]
-----
-public interface PublishingPayloadFactoryForAction {
- @Programmatic
- public EventPayload payloadFor(
- Identifier actionIdentifier,
- Object target,
- List<Object> arguments,
- Object result);
-}
-}
-----
-The `EventPayloadForActionInvocation` abstract class (in the Isis applib) should be used as the base class for the object instance returned from `payLoadFor(...)`.
-
-For objects, the interface to implement is `PublishingPayloadFactoryForObject`:
-
-[source,java]
-----
-public interface PublishingPayloadFactoryForObject {
-
- @Programmatic
- public EventPayload payloadFor(
- Object changedObject,
- PublishingChangeKind publishingChangeKind); // <1>
-}
-----
-<1> an enum taking the values `CREATE`, `UPDATE`, `DELETE`
-
-Similarly, the `EventPayloadForObjectChanged` abstract class should be used as the base class for the object returned from `payLoadFor(...)`.
-
-For example, the following will eagerly include a `ToDoItem`'s `description` property whenever it is changed:
-
-[source,java]
-----
-@DomainObject(publishingPayloadFactory=ToDoItemPayloadFactory.class)
-public class ToDoItem {
- ...
-}
-----
-
-where `ToDoItemPayloadFactory` is defined as:
-
-[source,java]
-----
-public class ToDoItemChangedPayloadFactory implements PublishingPayloadFactoryForObject {
- 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, PublishingChangeKind kind) {
- return new ToDoItemPayload((ToDoItem) changedObject);
- }
-}
-----
-
-
-
-
-== Registering the Services
-
-Assuming that the `configuration-and-annotation` services installer is configured:
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then adding the (non-ASF) http://github.com/isisaddons/isis-module-publishing[Isis addons' publishing] module to the classpath will automatically register the `PublishingService` implementation (and also the module's `RestfulObjectsSpecEventSerializer` implementation).
-
-
-
-
-== 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 xref:_ug_reference-annotations_manpage-Action_publishing[`@Action#publishing()`]) and of changed objects (for objects annotated with xref:_ug_reference-annotations_manpage-DomainObject_publishing[`@DomainObject#publishing()`].
-
-The xref:_ug_reference-services-api_manpage-EventBusService[`EventBusService`] meanwhile is intended for fine-grained publish/subscribe for object-to-object interactions within an Isis domain object model. The event propagation is strictly in-memory, and there are no restrictions on the object acting as the event (it need not be serializable, for example).
-
-All three of these services collaborate implicitly by way of the xref:_ug_reference-classes_mixins_manpage-HasTransactionId[`HasTransactionId`] interface.
-
-
-
-
-== Design Notes
-
-The following class diagram shows how the above components fit together:
-
-image::{_imagesdir}reference-services-spi/PublishingService/yuml.me-23db58a4.png[width="800px",link="{_imagesdir}reference-services-spi/PublishingService/yuml.me-23db58a4.png"]
-
-This yuml.me diagram was generated at http://yuml.me/edit/23db58a4[yuml.me].
\ No newline at end of file