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/12/22 11:21:35 UTC
[07/12] isis git commit: ISIS-1243: fixing naming of the domain
service API and SPI docs, also fix to asciidoc template.
http://git-wip-us.apache.org/repos/asf/isis/blob/46825ce1/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_XmlSnapshotService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_XmlSnapshotService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_XmlSnapshotService.adoc
deleted file mode 100644
index e6fce99..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-api_XmlSnapshotService.adoc
+++ /dev/null
@@ -1,220 +0,0 @@
-[[_rgsvc-api_XmlSnapshotService]]
-= `XmlSnapshotService`
-: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 `XmlSnapshotService` provides the capability to generate XML snapshots (and if required corresponding XSD schemas) based on graphs of domain objects.
-
-Typical use cases include creating mementos for business-focused auditing, such that a report could be generated as to which end-user performed a business action (perhaps for legal reasons). For one system that we know of, a digest of this snapshot of data is signed with the public encryption key so as to enforce non-repudiation.
-
-Another use case is to grab raw data such that it could be merged into a report template or communication.
-
-The service offers a basic API to create a snapshot of a single object, and an more flexible API that allows the size of the graph to be customized.
-
-The core framework provides an implementation of this service (`o.a.i.core.runtime.services.xmlsnapshot.XmlSnapshotServiceDefault`).
-
-
-
-== Standard API
-
-The (basic) API of `XmlSnapshotService` is:
-
-[source]
-----
-public interface XmlSnapshotService {
- public interface Snapshot {
- Document getXmlDocument();
- Document getXsdDocument();
- String getXmlDocumentAsString();
- String getXsdDocumentAsString();
- }
- @Programmatic
- public XmlSnapshotService.Snapshot snapshotFor(Object domainObject);
- ...
-}
-----
-
-
-The most straight-forward usage of this service is simply:
-
-[source,java]
-----
-XmlSnapshot snapshot = xmlsnapshotService.snapshotFor(customer);
-Element customerAsXml = snapshot.getXmlElement();
-----
-
-This will return an XML (document) element that contains the names and values of each of the customer's value properties, along with the titles of reference properties, and also the number of items in collections.
-
-
-As well as obtaining the XML snapshot, it is also possible to obtain an XSD schema that the XML snapshot conforms to.
-
-[source]
-----
-XmlSnapshot snapshot = ...;
-Element customerAsXml = snapshot.getXmlElement();
-Element customerXsd = snapshot.getXsdElement();
-----
-
-This can be useful for some tools. For example, link:http://www.altova.com/stylevision.html[Altova Stylevision] can use the XML and XSD to transform into reports. Please note that this link does not imply endorsement (nor even a recommendation that this is a good design).
-
-
-
-
-
-== Builder API
-
-The contents of the snapshot can be adjusted by including "paths" to other references or collections. To do this, the
-builder is used. The API for this is:
-
-[source,java]
-----
-public interface XmlSnapshotService {
- ...
- public interface Builder {
- void includePath(final String path);
- void includePathAndAnnotation(String path, String annotation);
- XmlSnapshotService.Snapshot build();
- }
- @Programmatic
- public XmlSnapshotService.Builder builderFor(Object domainObject);
-}
-----
-
-We start by obtaining a builder:
-
-[source,java]
-----
-XmlSnapshot.Builder builder = xmlsnapshotService.builderFor(customer);
-----
-
-Suppose now that we want the snapshot to also include details of the customer's address, where `address` in this case is a reference property to an instance of the `Address` class. We can "walk-the-graph" by including these references within the builder.
-
-[source,java]
-----
-builder.includePath("address");
-----
-
-We could then go further and include details of every order in the customer's `orders` collection, and details of every
-product of every order:
-
-[source,java]
-----
-builder.includePath("orders/product");
-----
-
-When all paths are included, then the builder can build the snapshot:
-
-[source,java]
-----
-XmlSnapshot snapshot = builder.build();
-Element customerAsXml = snapshot.getXmlElement();
-----
-
-All of this can be strung together in a fluent API:
-
-[source,java]
-----
-Element customerAsXml = xmlsnapshotService.builderFor(customer)
- .includePath("address")
- .includePath("orders/product")
- .build()
- .getXmlElement();
-----
-
-
-As you might imagine, the resultant XML document can get quite large very quickly with only a few "include"s.
-
-
-[NOTE]
-====
-If an XSD schema is beng generated (using `snapshot.getXsdElement()` then note that for the XSD to be correct, the object being snapshotted must have non-null values for the paths that are `include()`'d. If this isn't done then the XSD will not be correct reflect for another snapshotted object that does have non-null values.
-====
-
-
-
-
-== Automatic inclusions
-
-If the domain object being snapshotted implements the `SnapshottableWithInclusions` interace, then this moves the
-responsibility for determining what is included within the snapshot from the caller to the snapshottable object itself:
-
-[source]
-----
-public interface SnapshottableWithInclusions extends Snapshottable {
- List<String> snapshotInclusions();
-}
-----
-
-If necessary, both approaches can be combined.
-
-
-[TIP]
-====
-As an alternative to using `include()`, you might consider building a view model domain object which can reference only the relevant information required for the snapshot. For example, if only the 5 most recent Orders for a Customer were required, a `CustomerAndRecentOrders` view model could hold a collection of just those 5 ``Order``s. Typically such view models would implement `SnapshottableWithInclusions`.
-
-One reason for doing this is to provide a stable API between the domain model and whatever it is that might be consuming the XML. With a view model you can refactor the domain entities but still preserve a view model such that the XML is the same.
-====
-
-
-
-== Convenience API
-
-The `XmlSnapshotService` also provides some API for simply manipulating XML:
-
-[source]
-----
-public interface XmlSnapshotService {
- ...
- @Programmatic
- public Document asDocument(String xmlStr); // <1>
- @Programmatic
- public <T> T getChildElementValue( // <2>
- Element el, String tagname, Class<T> expectedCls);
- @Programmatic
- public Element getChildElement( // <3>
- Element el, String tagname);
- @Programmatic
- public String getChildTextValue(Element el); // <4>
-}
-----
-<1> is a convenience method to convert xml string back into a W3C Document
-<2> is a convenience method to extract the value of an XML element, based on its type.
-<3> is a convenience method to walk XML document.
-<4> is a convenience method to obtain value of child text node.
-
-
-
-
-
-
-
-== Registering the Service
-
-Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
-implementation of `XmlSnapshotService` service is automatically registered and injected (it is annotated with
-`@DomainService`) so no further configuration is required.
-
-To use an alternative implementation, use
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ugfun.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
-
-
-
-== Related Services
-
-The xref:rgsvc.adoc#_rgsvc-api_BookmarkService[`BookmarkService`] provides a mechanism for obtaining a string representations of a single domain object.
-
-The xref:rgsvc.adoc#_rgsvc-api_MementoService[`MementoService`] also provides a mechanism for generating string representations of domain objects.
-
-The xref:rgsvc.adoc#_rgsvc-api_JaxbService[`JaxbService`] (`1.11.0-SNAPSHOT`) is a simple wrapper around
-standard JAXB functionality for generating both XMLs and XSDs from JAXB-annotated classes. Note that (as of
-`1.11.0-SNAPSHOT`) there is built-in support for JAXB classes (ie annotated with
-xref:rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`]) to be used as view models.
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/46825ce1/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi.adoc
deleted file mode 100644
index 026909d..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi.adoc
+++ /dev/null
@@ -1,299 +0,0 @@
-[[_rgsvc-spi]]
-= 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:rgsvc.adoc#_rgsvc-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 Apache Isis itself rather than by your domain objects. A good example of this is the xref:rgsvc.adoc#_rgsvc-spi_AuditingService[`AuditingService`] service; if an implementation is present then Apache Isis will call that service in order to record audit log entries. If no implementation is available then Apache Isis will carry on regardless.
-
-Some domain services can be considered both API and SPI; a good example is the xref:rgsvc.adoc#_rgsvc-api_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:ugvw.adoc#_ugvw_features_user-registration[user registration] functionality supported by the xref:ugvw.adoc#[Wicket viewer]. The same is true of the xref:rgsvc.adoc#_rgsvc-api_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:rgant.adoc#_rgant-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:rgsvc.adoc#_rgsvc-spi_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:rgsvc.adoc#_rgsvc-spi_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:rgsvc.adoc#_rgsvc-spi_ClassDiscoveryService[`o.a.i.applib.` +
-`services.classdiscovery` +
-`ClassDiscoveryService`]
-|Mechanism to locate (from the classpath) classes with a specific annotation (eg xref:rgant.adoc#_rgant-DomainService[`@DomainService`])
-
-Subtypes of a given type (eg xref:rgcms.adoc#_rgcms_classes_super_FixtureScript[`FixtureScript`]).
-|`ClassDiscoveryService-` +
-`UsingReflections` +
-``o.a.i.core`` +
-``isis-core-applib``
-|requires `org.reflections:reflections` as Maven dependency
-
-
-|xref:rgsvc.adoc#_rgsvc-spi_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:rgsvc.adoc#_rgsvc-spi_EmailNotificationService[`o.a.i.applib.` +
-`services.userreg` +
-`EmailNotificationService`]
-|Notify a user during xref:rgsvc.adoc#_rgsvc-spi_UserRegistrationService[self-registration] of users.
-|`EmailNotificationService-` +
-`Default` +
-``o.a.i.core`` +
-``isis-core-runtime``
-|depends on: +
-a configured `EmailService`
-
-|xref:rgsvc.adoc#_rgsvc-spi_ErrorReportingService[`o.a.i.applib.` +
-`services.error` +
-`ErrorReportingService`]
-|Record details of an error occurring in the system (eg in an external incident recording system such as JIRA), and return a more friendly (jargon-free) message to display to the end user, with optional reference (eg `XXX-1234`).
-|(none)
-|
-
-|xref:rgsvc.adoc#_rgsvc-spi_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:rgsvc.adoc#_rgsvc-spi_PublishingService[`PublishingService`].
-|`RestfulObjects-` +
-`SpecEventSerializer` +
-``o.ia.m.publishing`` +
-``isis-module-publishing``
-|
-
-
-|xref:rgsvc.adoc#_rgsvc-spi_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:rgsvc.adoc#_rgsvc-spi_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:rgsvc.adoc#_rgsvc-spi_TranslationService[`TranslationService`].
-|`LocaleProviderWicket` +
-``o.a.i.viewer`` +
-``isis-viewer-wicket-impl``
-|
-
-|xref:rgsvc.adoc#_rgsvc-spi_FixtureScriptsSpecificationProvider[`o.a.i.applib.` +
-`services.fixturespec` +
-`FixtureScripts-` +
-`SpecificationProvider`]
-|Provides settings for xref:rgsvc.adoc#_rgsvc-api_FixtureScriptsDefault[`FixtureScriptsDefault`] fallback domain service for executing fixture scripts.
-|
-|
-
-|xref:rgsvc.adoc#_rgsvc-spi_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:rgsvc.adoc#_rgsvc-spi_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:rgsvc.adoc#_rgsvc-spi_LocaleProvider[`LocalProvider`].
-|`TranslationServicePo` +
-``o.a.i.core`` +
-``isis-core-runtime``
-|related services: `TranslationServicePoMenu` +
-depends on: +
-`TranslationsResolver`, `LocaleProvider`
-
-
-|xref:rgsvc.adoc#_rgsvc-spi_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:rgsvc.adoc#_rgsvc-spi_TranslationService[`TranslationService`]
-|`TranslationsResolverWicket` +
-``o.a.i.viewer`` +
-``isis-viewer-wicket-impl``
-|
-
-
-|xref:rgsvc.adoc#_rgsvc-spi_UrlEncodingService[`o.a.i.applib.` +
-`services.urlencoding` +
-`UrlEncodingService`]
-|Converts strings into a form safe for use within a URL. Used to convert view models mementos into usable URL form.
-
-|`UrlEncodingServiceUsingBaseEncoding` +
-``o.a.i.applib`` +
-``isis-core-applib``
-|
-
-
-|xref:rgsvc.adoc#_rgsvc-spi_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:rgsvc.adoc#_rgsvc-spi_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:rgant.adoc#_rgant-DomainService[`@DomainService`]. The one exception is xref:rgsvc.adoc#_rgsvc-spi_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:rgsvc.adoc#_rgsvc-spi_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:rgsvc.adoc#_rgsvc-spi_ContentNegotiationService[`o.a.i.v.ro.` +
-`rendering.service.conneg.` +
-`ContentNegotiationService`]
-|Encodes the algorithm that delegates to any registered xref:rgsvc.adoc#_rgsvc-spi_ContentMappingService[`ContentMappingService`]s.
-|`ContentNegotiationService-` +
-`XRoDomainType` +
-``o.a.i.core`` +
-`isis-core-viewer-restfulobjects-rendering`
-|
-
-
-|xref:rgsvc.adoc#_rgsvc-spi_RepresentationService[`o.a.i.v.ro.` +
-`rendering.service.` +
-`RepresentationService`]
-|Generates the representations, delegating to any registered xref:rgsvc.adoc#_rgsvc-spi_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::_rgsvc-spi_AuditingService.adoc[leveloffset=+1]
-include::_rgsvc-spi_BackgroundCommandService.adoc[leveloffset=+1]
-include::_rgsvc-spi_ClassDiscoveryService.adoc[leveloffset=+1]
-include::_rgsvc-spi_CommandService.adoc[leveloffset=+1]
-include::_rgsvc-spi_ContentMappingService.adoc[leveloffset=+1]
-include::_rgsvc-spi_ContentNegotiationService.adoc[leveloffset=+1]
-include::_rgsvc-spi_EmailNotificationService.adoc[leveloffset=+1]
-include::_rgsvc-spi_ErrorReportingService.adoc[leveloffset=+1]
-include::_rgsvc-spi_EventSerializer.adoc[leveloffset=+1]
-include::_rgsvc-spi_ExceptionRecognizer.adoc[leveloffset=+1]
-include::_rgsvc-spi_FixtureScriptsSpecificationProvider.adoc[leveloffset=+1]
-include::_rgsvc-spi_LocaleProvider.adoc[leveloffset=+1]
-include::_rgsvc-spi_PublishingService.adoc[leveloffset=+1]
-include::_rgsvc-spi_RepresentationService.adoc[leveloffset=+1]
-include::_rgsvc-spi_TranslationService.adoc[leveloffset=+1]
-include::_rgsvc-spi_TranslationsResolver.adoc[leveloffset=+1]
-include::_rgsvc-spi_UrlEncodingService.adoc[leveloffset=+1]
-include::_rgsvc-spi_UserProfileService.adoc[leveloffset=+1]
-include::_rgsvc-spi_UserRegistrationService.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/46825ce1/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_AuditingService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_AuditingService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_AuditingService.adoc
deleted file mode 100644
index c8d8a62..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_AuditingService.adoc
+++ /dev/null
@@ -1,85 +0,0 @@
-[[_rgsvc-spi_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:rgcms.adoc#_rgcms_classes_mixins_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:rgant.adoc#_rgant-DomainObject_auditing[`@DomainObject#auditing()`] annotation.
-
-
-
-
-== Registering the Services
-
-The (non-ASF) http://github.com/isisaddons/isis-module-audit[Isis addons' audit] module provides an implementation of
-this service (`AuditingService`), and also provides a number of related domain services (`AuditingServiceMenu`,
-`AuditingServiceRepository` and `AuditingServiceContributions`).
-
-Assuming that an `AppManifest` is being used to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app])
-then this can be activated by updating the `pom.xml` and updating the `AppManifest#getModules()` method.
-
-If menu items or contributions are not required in the UI, these can be suppressed either using security or by
-implementing a xref:ugbtb.adoc#_ugbtb_more-advanced_decoupling_vetoing-visibility[vetoing subscriber].
-
-
-
-== Related Services
-
-The auditing service works very well with the xref:rgsvc.adoc#_rgsvc-spi_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:rgsvc.adoc#_rgsvc-spi_PublishingService[`PublishingService`].
-
-All three of these services collaborate implicitly by way of the xref:rgcms.adoc#_rgcms_classes_mixins_HasTransactionId[`HasTransactionId`] interface.
-
http://git-wip-us.apache.org/repos/asf/isis/blob/46825ce1/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_BackgroundCommandService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_BackgroundCommandService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_BackgroundCommandService.adoc
deleted file mode 100644
index 45518b9..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_BackgroundCommandService.adoc
+++ /dev/null
@@ -1,131 +0,0 @@
-[[_rgsvc-spi_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:rgsvc.adoc#_rgsvc-api_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:rgsvc.adoc#_rgsvc-spi_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:rgsvc.adoc#_rgsvc-api_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:rgsvc.adoc#_rgsvc-api_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:ugbtb.adoc#_ugbtb_more-advanced_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:rgsvc.adoc#_rgsvc-api_BackgroundService[`BackgroundService`] page.
-====
-
-
-
-
-== Usage
-
-Background commands can be created either declaratively or imperatively.
-
-The declarative approach involves annotating an action using xref:rgant.adoc#_rgant-Action_command[`@Action#command()`] with `@Action#commandExecuteIn=CommandExecuteIn.BACKGROUND`.
-
-The imperative approach involves explicitly calling the xref:rgsvc.adoc#_rgsvc-api_BackgroundService[`BackgroundService`] from within domain object's action.
-
-
-
-
-== Registering the Services
-
-The (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module provides an implementation
-of this service (`BackgroundCommandService`), and also provides a number of related domain services
-(`BackgroundCommandServiceJdo`, `BackgroundCommandJdoRepository` and `BackgroundCommandServiceJdoContributions`). This
-module also provides service implementations of the
-xref:rgsvc.adoc#_rgsvc-spi_CommandService[`CommandService`].
-
-Assuming that an `AppManifest` is being used to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app])
-then this can be activated by updating the `pom.xml` and updating the `AppManifest#getModules()` method.
-
-If contributions are not required in the UI, these can be suppressed either using security or by implementing a
-xref:ugbtb.adoc#_ugbtb_more-advanced_decoupling_vetoing-visibility[vetoing subscriber].
-
-
-
-
-
-== Related Services
-
-As discussed above, this service supports the xref:rgsvc.adoc#_rgsvc-api_BackgroundService[`BackgroundService`] , persisting `Command`s such that they can be executed in the background.
-
-There is also a tie-up with the xref:rgsvc.adoc#_rgsvc-api_CommandContext[`CommandContext`] and its supporting xref:rgsvc.adoc#_rgsvc-spi_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/46825ce1/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ClassDiscoveryService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ClassDiscoveryService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ClassDiscoveryService.adoc
deleted file mode 100644
index 5d328aa..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ClassDiscoveryService.adoc
+++ /dev/null
@@ -1,82 +0,0 @@
-[[_rgsvc-spi_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:rgcms.adoc#_rgcms_classes_super_FixtureScripts[`FixtureScripts`] service to automatically locate any xref:rgcms.adoc#_rgcms_classes_super_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:rgant.adoc#_rgant-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. As of 1.9.0, the usage of the service has been
-centralized such that the packages to be scanned are located from the xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`]'s `#getModules()` method.
-
-For example, the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype]'s app manifest includes:
-
-[source,java]
-----
-public class DomainAppAppManifest implements AppManifest {
- @Override
- public List<Class<?>> getModules() {
- return Arrays.asList(
- DomainAppDomainModule.class, // domain (entities and repositories)
- DomainAppFixtureModule.class, // fixtures
- DomainAppAppModule.class // home page service etc
- );
- }
- ...
-}
-----
-
-where the three module classes in effect define three different package prefixes to search under (for domain services, fixture scripts and persistent entities).
-
-Other usages of the `ClassDiscoveryService` 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 (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
-implementation of `ClassDiscoveryService2` service is automatically registered and injected (it is annotated with
-`@DomainService`) so no further configuration is required.
-
-To use an alternative implementation, use
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ugfun.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/46825ce1/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_CommandService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_CommandService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_CommandService.adoc
deleted file mode 100644
index b62629b..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_CommandService.adoc
+++ /dev/null
@@ -1,100 +0,0 @@
-[[_rgsvc-spi_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:rgsvc.adoc#_rgsvc-api_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:rgsvc.adoc#_rgsvc-api_BackgroundService[`BackgroundService`]
-* if xref:rgsvc.adoc#_rgsvc-spi_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:rgcms.adoc#_rgcms_classes_mixins_HasTransactionId[`transactionId`]
-* if xref:rgsvc.adoc#_rgsvc-spi_PublishingService[publishing] is configured, they provide better traceability as the `Command` is also correlated with any published events, again through the unique xref:rgcms.adoc#_rgcms_classes_mixins_HasTransactionId[`transactionId`]
-* the associated xref:rgant.adoc#_rgant-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:ugvw.adoc#[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:rgsvc.adoc#_rgsvc-api_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:rgant.adoc#_rgant-Action_command[`@Action#command()`].
-
-
-
-
-== Registering the Services
-
-The (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module provides an implementation
-of this service (`CommandService`), and also provides a number of related domain services
-(`CommandJdoRepository` and `CommandServiceJdoContributions`). This
-module also provides service implementations of the
-xref:rgsvc.adoc#_rgsvc-spi_CommandService[`BackgroundCommandService`].
-
-Assuming that an `AppManifest` is being used to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app])
-then this can be activated by updating the `pom.xml` and updating the `AppManifest#getModules()` method.
-
-If contributions are not required in the UI, these can be suppressed either using security or by implementing a
-xref:ugbtb.adoc#_ugbtb_more-advanced_decoupling_vetoing-visibility[vetoing subscriber].
-
-
-
-
-== Related Services
-
-As discussed above, this service supports the xref:rgsvc.adoc#_rgsvc-api_CommandContext[`CommandContext`], providing the ability for `Command` objects to be
-persisted. This is closely related to the xref:rgsvc.adoc#_rgsvc-spi_BackgroundCommandService[`BackgroundCommandService`]that allows the xref:rgsvc.adoc#_rgsvc-api_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:rgsvc.adoc#_rgsvc-spi_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:rgsvc.adoc#_rgsvc-spi_PublishingService[`PublishingService`].
-
-All three of these services collaborate implicitly by way of the xref:rgcms.adoc#_rgcms_classes_mixins_HasTransactionId[`HasTransactionId`] interface.
-
http://git-wip-us.apache.org/repos/asf/isis/blob/46825ce1/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ContentMappingService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ContentMappingService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ContentMappingService.adoc
deleted file mode 100644
index 1b30f39..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ContentMappingService.adoc
+++ /dev/null
@@ -1,107 +0,0 @@
-[[_rgsvc-spi_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:rgsvc.adoc#_rgsvc-spi_ContentNegotiationService[`ContentNegotiationService`] allowing the xref:ugvro.adoc#[RestfulObjects viewer] to allow domain objects to be transformed into some other format as specified by the HTTP `Accept` header.
-
-See xref:rgsvc.adoc#_rgsvc-spi_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 Apache 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 (two different versions of) a `ToDoItemDto` (JAXB annotated). 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:rgsvc.adoc#_rgsvc-api_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:rgsvc.adoc#_rgsvc-spi_ContentNegotiationService[`ContentNegotiationService`].
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/46825ce1/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ContentNegotiationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ContentNegotiationService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ContentNegotiationService.adoc
deleted file mode 100644
index f624c1e..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ContentNegotiationService.adoc
+++ /dev/null
@@ -1,204 +0,0 @@
-[[_rgsvc-spi_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:ugvro.adoc#[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 Apache Isis xref:ugbtb.adoc#_ugbtb_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:ugbtb.adoc#_ugbtb_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 Apache 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:rgsvc.adoc#_rgsvc-spi_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:rgsvc.adoc#_rgsvc-spi_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"]
-
-
-
-
-[_rgsvc-spi_ContentNegotiationService_Configuration]]
-== Configuration
-
-The default `ContentNegotiationServiceXRoDomainType` implementation provides a xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] which controls whether a mapped domain object is pretty-printed (formatted, indented) or not:
-
-[source,ini]
-----
-isis.services.ContentNegotiationServiceXRoDomainType.prettyPrint=true
-----
-
-If the property is not set, then the default depends on the xref:rgcfg.adoc#_rgcfg_deployment-types[deployment type]; production mode will disable pretty printing, while prototyping mode will enable it.
-
-
-
-
-
-== Registering the Services
-
-Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' default
-implementation of `ContentNegotiationService` service is automatically registered and injected (it is annotated with
-`@DomainService`) so no further configuration is required.
-
-To use an alternative implementation, use
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ugfun.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
-
-
-
-== Related Services
-
-The default implementation of `ContentNegotiationService` delegates to xref:rgsvc.adoc#_rgsvc-spi_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:rgsvc.adoc#_rgsvc-spi_RepresentationService[`RepresentationService`].
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/46825ce1/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_EmailNotificationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_EmailNotificationService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_EmailNotificationService.adoc
deleted file mode 100644
index 1ab854b..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_EmailNotificationService.adoc
+++ /dev/null
@@ -1,81 +0,0 @@
-[[_rgsvc-spi_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:ugvw.adoc#_ugvw_features_user-registration[user registration] (self sign-up) features of the xref:ugvw.adoc#[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:rgsvc.adoc#_rgsvc-spi_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:rgsvc.adoc#_rgsvc-api_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 Apache Isis domain services) the implementation is also instantiated and injected by Google Guice. This is because `EmailNotificationService` is used as part of the xref:ugvw.adoc#_ugvw_features_user-registration[user registration] functionality and is used by Wicket pages that are accessed outside of the usual Apache 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 Apache 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 (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' default
-implementation of `EmailNotificationService` service is automatically registered and injected (it is annotated with
-`@DomainService`) so no further configuration is required.
-
-To use an alternative implementation, use
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-further in this xref:ugfun.adoc#_ugfun_how-tos_replacing-default-service-implementations["how to"] tip).
-
-
-== Related Services
-
-As noted elsewhere, the default implementation of this service uses xref:rgsvc.adoc#_rgsvc-api_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:rgsvc.adoc#_rgsvc-spi_UserRegistrationService[`UserRegistrationService`].
-
http://git-wip-us.apache.org/repos/asf/isis/blob/46825ce1/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ErrorReportingService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ErrorReportingService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ErrorReportingService.adoc
deleted file mode 100644
index 32573ea..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ErrorReportingService.adoc
+++ /dev/null
@@ -1,106 +0,0 @@
-[[_rgsvc-spi_ErrorReportingService]]
-= `ErrorReportingService`
-: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 `ErrorReportingService` service is an optional SPI that providies the ability to record any errors/exceptions that
- might occur in the application into an external incident recording system (such as JIRA). The service also allows
- a user-friendly (jargon-free) error message to be returned and rendered to the end-user, along with an optional
- incident reference (eg a JIRA issue `XXX-1234`).
-
-
-
-== SPI
-
-The SPI defined by this service is:
-
-[source,java]
-----
-public interface ErrorReportingService {
- Ticket reportError(ErrorDetails errorDetails);
-}
-----
-
-where `ErrorDetails` provided to the service is:
-
-[source,java]
-----
-public class ErrorDetails {
- public String getMainMessage() { ... } // <1>
- public boolean isRecognized() { ... } // <2>
- public boolean isAuthorizationCause() { ... } // <3>
- public List<String> getStackTraceDetailList() { // <4>
-}
-----
-<1> the main message to be displayed to the end-user. The service is responsible for translating this into the language of the end-user (it can use xref:rgsvc.adoc#_rgsvc-spi_LocaleProvider[`LocaleProvider`] if required).
-<2> whether this message has already been recognized by an xref:rgsvc.adoc#_rgsvc-spi_ExceptionRecognizer[`ExceptionRecognizer`] service. Generally this converts potentially non-recoverable (fatal) exceptions into recoverable exceptions (warnings) as well providing an alternative mechanism for generating user-friendly error messages.
-<3> whether the cause of the exception was due to a lack of privileges. In such cases the UI restricts the information shown to the end-user, to avoid leaking potentially sensitive information
-<4> the stack trace of the exception, including the trace of any exceptions in the causal chain. These technical details are hidden from the user and only shown for non-recoverable exceptions.
-
-
-and `Ticket` (returned by the service) has the constructor:
-
-[source,java]
-----
-public class Ticket implements Serializable {
- public Ticket(
- final String reference, // <1>
- final String userMessage, // <2>
- final String details) { ... } // <3>
-}
-----
-<1> is a unique identifier that the end-user can use to track any follow-up from this error. For example, an
-implementation might automatically log an issue in a bug tracking system such as JIRA, in which case the reference would
-probably be the JIRA issue number <tt>XXX-1234</tt>.
-<2> a short, jargon-free message to display to the end-user.
-<3> is optional additional details to show. For example, these might include text on how to recover from the error, or
- workarounds, or just further details on contacting the help desk if the issue is severe and requires immediate
- attention.
-
-
-
-
-== Implementation
-
-The (non-ASF) http://github.com/isisaddons/isis-app-kitchensink[Isis addons' kitchensink] app provides an example
-implementation:
-
-[source,java]
-----
-@DomainService( nature = NatureOfService.DOMAIN )
-public class KitchensinkErrorReportingService implements ErrorReportingService {
- private int ticketNumber = 1;
- @Override
- public Ticket reportError(final ErrorDetails errorDetails) {
- return new Ticket(
- nextTicketReference(),
- "The Kitchen sink app is sorry to report that: " + errorDetails.getMainMessage(),
- "These are additional details for the end-user to read.\n"
- + "This content should be able to span many lines.\n"
- + "More detail.\n"
- + "Some suggested work-arounds.\n"
- + "Details of how to contact help desk.\n"
- + "And so on");
- }
- String nextTicketReference() {
- return "" + ticketNumber++;
- }
-}
-----
-
-which is rendered as:
-
-image::{_imagesdir}reference-services-spi/ErrorReportingService/kitchensink-example.png[width="860px",link="{_imagesdir}reference-services-spi/ErrorReportingService/kitchensink-example.png"]
-
-
-
-
-== Registering the Services
-
-There is no default implementation of this service. To register your own implementation (and assuming that an
-`AppManifest` is being used to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]), then just
-ensure that the implementation is on the classpath and the module containing the implementation is returned in
-`AppManifest#getModules()`.
-
http://git-wip-us.apache.org/repos/asf/isis/blob/46825ce1/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_EventSerializer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_EventSerializer.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_EventSerializer.adoc
deleted file mode 100644
index 7ffe90f..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_EventSerializer.adoc
+++ /dev/null
@@ -1,74 +0,0 @@
-[[_rgsvc-spi_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:rgsvc.adoc#_rgsvc-spi_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:rgsvc.adoc#_rgsvc-spi_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:rgcms.adoc#_rgcms_classes_mixins_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
-
-There is no default implementation of this service provided by the core Apache Isis framework.
-
-The (non-ASF) http://github.com/isisaddons/isis-module-publishing[Isis addons' publishing] module provides an
-implementation of this service (`RestfulObjectsSpecEventSerializer`) that serializes action invocations and published
-objects into a format based on the Restful Objects specification. It also (as you might imagine) provides an
-implementation of the xref:rgsvc.adoc#_rgsvc-spi_PublishingService[`PublishingService`].
-
-Assuming that an `AppManifest` is being used to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app])
-then this can be activated by updating the `pom.xml` and updating the `AppManifest#getModules()` method.
-
-
-
-== Related Services
-
-This service is intended (though not mandated) to be used by implementations of xref:rgsvc.adoc#_rgsvc-spi_PublishingService[`PublishingService`]. The (non-ASF) http://github.com/isisaddons/isis-module-publishing[Isis addons' publishing] module does use it (though the (non-ASF)
-http://github.com/isisaddons/isis-module-publishmq[Isis addons' publishmq] module does not).
-
http://git-wip-us.apache.org/repos/asf/isis/blob/46825ce1/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ExceptionRecognizer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ExceptionRecognizer.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ExceptionRecognizer.adoc
deleted file mode 100644
index 200b11f..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc-spi_ExceptionRecognizer.adoc
+++ /dev/null
@@ -1,119 +0,0 @@
-[[_rgsvc-spi_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 Apache Isis `ObjectNotFoundException` is raised. Both the viewers interprets this correctly (the xref:ugvw.adoc#[Wicket viewer] as a suitable error page, the xref:ugvro.adoc#[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 Apache 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 Apache 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 (implicit if using the
-`AppManifest` to xref:rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[bootstrap the app]) 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.
-====
-
-If the JDO exception recognizers are not required (rather unlikely), then they can be disabled en-masse using the xref:rgcfg.adoc#_rgcfg_configuring-core[configuration property] `isis.services.ExceptionRecognizerCompositeForJdoObjectStore.disable`.
-