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 2017/03/31 07:11:03 UTC
[27/51] [partial] isis git commit: ISIS-1521: reorganizes asciidoc
documentation, moves into subdirs (both guides and other pages)
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/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 d5daafe..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_ContentMappingService.adoc
+++ /dev/null
@@ -1,102 +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:rgfis.adoc#_rgfis_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:rgfis.adoc#_rgfis_spi_ContentNegotiationService[`ContentNegotiationService`] for further discussion.
-
-
-[NOTE]
-====
-Unlike most other domain services, the framework (that is, `ContentNegotiationService`) will check _all_ available
-implementations of `ContentMappingService` to convert the domain object to the requested media type, rather than merely
-the first implementation found; in other words it uses the chain-of-responsibility pattern. Services are checked
-in the ordering defined by xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`]).
-The mapped object used will be the first non-`null` result returned by an implementation.
-====
-
-
-
-== SPI
-
-The SPI defined by this service is:
-
-[source,java]
-----
-public interface ContentMappingService {
- Object map(Object object, // <1>
- List<MediaType> acceptableMediaTypes); // <2>
-}
-
-----
-<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
-
-
-In versions prior to `v1.12.0`, this interface resided in a different package, internal to the
-xref:ugvro.adoc[Restful Objects] viewer, and defined a slightly different signature that used an internal enum:
-
-[source,java]
-----
-public interface ContentMappingService {
- Object map(Object object,
- List<MediaType> acceptableMediaTypes,
- RepresentationType representationType); // <1>
-
-}
-
-----
-<1> enum representing the requested representation; only ever take a value of ``DOMAIN_OBJECT`` or ``ACTION_RESULT``.
-
-
-
-== 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 a (JAXB annotated) `ToDoItemDto`. The source code is:
-
-[source,java]
-----
-@DomainService(nature = NatureOfService.DOMAIN)
-public class ContentMappingServiceForToDoItem implements ContentMappingService {
- @Override
- public Object map(
- final Object object,
- final List<MediaType> acceptableMediaTypes) {
- if(object instanceof ToDoItem) {
- for (MediaType acceptableMediaType : acceptableMediaTypes) {
- final Map<String, String> parameters = acceptableMediaType.getParameters();
- final String className = parameters.get("x-ro-domain-type");
- if(className.eqausl(ToDoItemV1_1.class.getName())) {
- return newToDoItemV1_1((ToDoItem) object);
- }
- }
- }
- return null;
- }
- private ToDoItemV1_1 newToDoItemV1_1(final ToDoItem toDoItem) {
- final ToDoItemV1_1 dto = new ToDoItemV1_1();
- dto.setToDoItem(toDoItem);
- dto.setDescription(toDoItem.getDescription());
- ...
- return dto;
- }
- ...
-}
-----
-
-
-
-
-== Related Services
-
-This service is a companion to the default implementation of the xref:rgfis.adoc#_rgfis_spi_ContentNegotiationService[`ContentNegotiationService`].
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/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 bab1247..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
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
-
-
-== 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/2669a971/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 ff9309b..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/2669a971/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 c314d95..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_EventSerializer.adoc
+++ /dev/null
@@ -1,80 +0,0 @@
-[[_rgsvc_spi_EventSerializer]]
-= `EventSerializer` (deprecated)
-: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.
-
-[WARNING]
-====
-This service is deprecated, replaced with xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`].
-====
-
-See xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`] for further discussion.
-
-
-
-
-== SPI
-
-The SPI defined by this service is:
-
-[source,java]
-----
-@Deprecated
-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/2669a971/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 95faabf..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`.
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_FixtureScriptsSpecificationProvider.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_FixtureScriptsSpecificationProvider.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_FixtureScriptsSpecificationProvider.adoc
deleted file mode 100644
index 41613f4..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_FixtureScriptsSpecificationProvider.adoc
+++ /dev/null
@@ -1,76 +0,0 @@
-[[_rgsvc_spi_FixtureScriptsSpecificationProvider]]
-= `FixtureScriptsSpec'nProvider`
-: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 `FixtureScriptsSpecificationProvider` configures the
-xref:rgsvc.adoc#_rgsvc_api_FixtureScriptsDefault[`FixtureScriptsDefault`] domain service, providing the
-location to search for fixture scripts and other settings.
-
-The service is only used if the `FixtureScriptsDefault` service is instantiated as a fallback by the framework. If
-the application provides its own subclass of xref:rgcms.adoc#_rgcms_classes_super_FixtureScripts[`FixtureScripts`]
-superclass, then this provider service is not used.
-
-[TIP]
-====
-Of the two designs, we encourage you to implement this "provider" SPI rather than subclass `FixtureScripts`. The
-primary benefit (apart from decoupling responsibilities) is that it ensures that there is always an instance of
-`FixtureScripts` available for use.
-====
-
-
-
-== SPI
-
-The SPI defined by the service is:
-
-[source,java]
-----
-public interface FixtureScriptsSpecificationProvider {
- @Programmatic
- FixtureScriptsSpecification getSpecification();
-}
-----
-
-where `FixtureScriptsSpecification` exposes these values:
-
-[source,java]
-----
-public class FixtureScriptsSpecification {
- public String getPackagePrefix() { ... }
- public FixtureScripts.NonPersistedObjectsStrategy getNonPersistedObjectsStrategy() { ... }
- public FixtureScripts.MultipleExecutionStrategy getMultipleExecutionStrategy() { ... }
- public Class<? extends FixtureScript> getRunScriptDefaultScriptClass() { ... }
- public DropDownPolicy getRunScriptDropDownPolicy() { ... }
- public Class<? extends FixtureScript> getRecreateScriptClass() { ... }
- ...
-}
-----
-
-The class is immutable but it has a builder (obtained using `FixturescriptsSpecification.builder(...)`) for a fluent API.
-
-
-
-== Implementation
-
-The xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] has a simple implementation of this service:
-
-[source,java]
-----
-@DomainService(nature = NatureOfService.DOMAIN)
-public class DomainAppFixturesProvider implements FixtureScriptsSpecificationProvider {
- @Override
- public FixtureScriptsSpecification getSpecification() {
- return FixtureScriptsSpecification
- .builder(DomainAppFixturesProvider.class)
- .with(FixtureScripts.MultipleExecutionStrategy.EXECUTE)
- .withRunScriptDefault(RecreateSimpleObjects.class)
- .withRunScriptDropDown(FixtureScriptsSpecification.DropDownPolicy.CHOICES)
- .withRecreate(RecreateSimpleObjects.class)
- .build();
- }
-}
-----
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_GridLoaderService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_GridLoaderService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_GridLoaderService.adoc
deleted file mode 100644
index 5c0e1a6..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_GridLoaderService.adoc
+++ /dev/null
@@ -1,53 +0,0 @@
-[[_rgsvc_spi_GridLoaderService]]
-= `GridLoaderService`
-: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 `GridLoaderService` provides the ability to load the XML layout (grid) for a domain class.
-
-== SPI
-
-The SPI defined by this service is:
-
-[source,java]
-----
-public interface GridLoaderService {
- boolean supportsReloading(); // <1>
- void remove(Class<?> domainClass); // <2>
- boolean existsFor(Class<?> domainClass); // <3>
- Grid load(final Class<?> domainClass); // <4>
-}
-----
-<1> whether dynamic reloading of layouts is enabled. The default implementation enables reloading for prototyping, disables in production
-<2> support metamodel invalidation/rebuilding of spec, eg as called by this xref:rgcms.adoc#__rgcms_classes_mixins_Object_rebuildMetamodel[Object mixin] action.
-<3> whether any persisted layout metadata (eg a `.layout.xml` file) exists for this domain class.
-<4> returns a new instance of a xref:rgcms.adoc#__rgcms_classes_layout_component[`Grid`] for the specified domain class, eg as loaded from a `layout.xml` file. If none exists, will return null (and the calling xref:rgsvc.adoc#_rgsvc_spi_GridService[`GridService`] will use xref:rgsvc.adoc#_rgsvc_spi_GridSystemService[`GridSystemService`] to obtain a default grid for the domain class).
-
-
-
-== Implementation
-
-The framework provides a default implementation of this service, namely `GridLoaderServiceDefault`. This implementation
-loads the grid from its serialized representation as a `.layout.xml` file, loaded from the classpath.
-
-For example, the layout for a domain class `com.mycompany.myapp.Customer` would be loaded from `com/mycompany/myapp/Customer.layout.xml`.
-
-
-== 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 implementation of `GridLoaderService` is automatically registered and injected, and no further
- configuration is required.
-
-To use an alternative implementation, use
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
-
-
-== Related Services
-
-This service is used by xref:rgsvc.adoc#_rgsvc_spi_GridService[`GridService`].
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_GridService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_GridService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_GridService.adoc
deleted file mode 100644
index c9415df..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_GridService.adoc
+++ /dev/null
@@ -1,72 +0,0 @@
-[[_rgsvc_spi_GridService]]
-= `GridService`
-: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 `GridService` provides the ability to load the XML layout (grid) for a domain class. To do this it delegates:
-
-* to xref:rgsvc.adoc#_rgsvc_spi_GridLoaderService[`GridLoaderService`] to load a pre-existing layout for the domain class, if possible
-
-* to xref:rgsvc.adoc#_rgsvc_spi_GridSystemService[`GridSystemService`] to normalize the grid with respect to Apache
-Isis' internal metamodel, in other words to ensure that all of the domain objects' properties, collections and actions are associated with regions of the grid.
-
-Once a grid has been loaded for a domain class, this is cached internally by Apache Isis' internal meta model (in the
-`GridFacet` facet). If running in prototype mode, any subsequent changes to the XML will be detected and the grid rebuilt. This allows for dynamic reloading of layouts, providing a far faster feedback (eg if tweaking the UI while working with end-users). Dynamic reloading is disabled in production mode.
-
-== SPI
-
-The SPI defined by this service is:
-
-[source,java]
-----
-public interface GridService {
- boolean supportsReloading(); // <1>
- void remove(Class<?> domainClass); // <2>
- boolean existsFor(Class<?> domainClass); // <3>
- Grid load(final Class<?> domainClass); // <4>
- Grid defaultGridFor(Class<?> domainClass); // <5>
- Grid normalize(final Grid grid); // <6>
- Grid complete(Grid grid); // <7>
- Grid minimal(Grid grid); // <8>
-}
-----
-<1> whether dynamic reloading of layouts is enabled. The default implementation enables reloading for prototyping, disables in production
-<2> support metamodel invalidation/rebuilding of spec, eg as called by this xref:rgcms.adoc#__rgcms_classes_mixins_Object_rebuildMetamodel[Object mixin] action.
-<3> whether any persisted layout metadata (eg a `.layout.xml` file) exists for this domain class. Just delegates to corresponding method in xref:rgsvc.adoc#_rgsvc_spi_GridLoaderService[`GridLoaderService`].
-<4> returns a new instance of a xref:rgcms.adoc#__rgcms_classes_layout_component[`Grid`] for the specified domain class, eg as loaded from a `layout.xml` file. If none exists, will return null (and the calling xref:rgsvc.adoc#_rgsvc_spi_GridService[`GridService`] will use xref:rgsvc.adoc#_rgsvc_spi_GridSystemService[`GridSystemService`] to obtain a default grid for the domain class).
-<5> returns a default grid, eg two columns in ratio 4:8. Used when no existing grid layout exists for a domain class.
-<6> validates and normalizes a grid, modifying the grid so that all of the domain object's members (properties, collections, actions) are bound to regions of the grid. This is done using existing metadata, most notably that of the xref:rgant.adoc#_rgant-MemberOrder[`@MemberOrder`] annotation. Such a grid, if persisted as the layout XML file for the domain class, allows the `@MemberOrder` annotation to be removed from the source code of the domain class (but other annotations must be retained).
-<7> Takes a normalized grid and enriches it with additional metadata (taken from Apache Isis' internal metadata) that can be represented in the layout XML. Such a grid, if persisted as the layout XML file for the domain class, allows all layout annotations (xref:rgant.adoc#_rgant-ActionLayout[`@ActionLayout`], xref:rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`] and xref:rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`]) to be removed from the source code of the domain class.
-<8> Takes a normalized grid and strips out removes all members, leaving only the grid structure. Such a grid, if persisted as the layout XML file for the domain class, requires that the xref:rgant.adoc#_rgant-MemberOrder[`@MemberOrder`] annotation is retained in the source code of said class in order to bind members to the regions of the grid.
-
-The first four methods just delegate to the corresponding methods in xref:rgsvc.adoc#_rgsvc_spi_GridSystemService[`GridSystemService`], while the last four delegate to the corresponding method in xref:rgsvc.adoc#_rgsvc_spi_GridSystemService[`GridSystemService`]. The service inspects the ``Grid``'s concrete class to determine which actual `GridSystemService` instance to delegate to.
-
-
-== Implementation
-
-The framework provides a default implementation of this service, namely `GridServiceDefault`.
-
-
-== 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 implementation of `GridLoaderService` is automatically registered and injected, and no further
- configuration is required.
-
-To use an alternative implementation, use
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
-That said, there should be little reason to use a different implementation; if behaviour does need to be changed, it would also be possible to replace the implementation of either the `GridLoaderService` or the `GridSystemService`.
-
-
-
-== Related Services
-
-This service calls xref:rgsvc.adoc#_rgsvc_spi_GridLoaderService[`GridLoaderService`] and xref:rgsvc.adoc#_rgsvc_spi_GridSystemService[`GridSystemService`].
-
-This service is called by xref:rgsvc.adoc#_rgsvc_api_LayoutService[`LayoutService`], exposed in the UI through `LayoutServiceMenu` (to download the layout XML as a zip file for all domain objects) and the xref:rgcms.adoc#_rgcms_classes_mixins_Object[`downloadLayoutXml()`] mixin (to download the layout XML for a single domain
-object).
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_GridSystemService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_GridSystemService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_GridSystemService.adoc
deleted file mode 100644
index 325fa2b..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_GridSystemService.adoc
+++ /dev/null
@@ -1,75 +0,0 @@
-[[_rgsvc_spi_GridSystemService]]
-= `GridSystemService`
-: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 `GridSystemService` encapsulates a single layout grid system which can be used to customize the layout
-of domain objects. In particular this means being able to return a "normalized" form (validating and associating
-domain object members into the various regions of the grid) and in providing a default grid if there is no other
-metadata available.
-
-The framework provides a single such grid implementation, namely for Bootstrap3.
-
-[NOTE]
-====
-Unlike most other domain services, the framework will check _all_ available implementations of `GridSystemService` to
-obtain available grid systems, rather than merely the first implementation found; in other words it uses the
-chain-of-responsibility pattern. Services are called in the order defined by
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`]).
-
-Note though that each concrete implementation must also provide corresponding Wicket viewer components capable of
-interpreting the grid layout.
-====
-
-
-== SPI
-
-The SPI defined by this service is:
-
-[source,java]
-----
-public interface GridSystemService<G extends Grid> {
- Class<? extends Grid> gridImplementation(); // <1>
- String tns(); // <2>
- String schemaLocation(); // <3>
- Grid defaultGrid(Class<?> domainClass); // <4>
- void normalize(G grid, Class<?> domainClass); // <5>
- void complete(G grid, Class<?> domainClass); // <6>
- void minimal(G grid, Class<?> domainClass); // <7>
-}
-----
-<1> The concrete subclass of `Grid` supported by this implementation. As noted in the introduction, there can be multiple implementations of this service, but there can only be one implementation per concrete subclass. As is normal practice,
-the service with the lowest xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] takes precedence.
-<2> the target namespace for this grid system. This is used when generating the XML. The Bootstrap3 grid system provided by the framework returns the value `http://isis.apache.org/applib/layout/grid/bootstrap3`.
-<3> the schema location for the XSD. The Bootstrap3 grid system provided by the framework returns the value `http://isis.apache.org/applib/layout/grid/bootstrap3/bootstrap3.xsd`.
-<4> a default grid, eg two columns in ratio 4:8. Used when no existing grid layout exists for a domain class.
-<5> Validates and normalizes a grid, modifying the grid so that all of the domain object's members (properties, collections, actions) are bound to regions of the grid. This is done using existing metadata, most notably that of the xref:rgant.adoc#_rgant-MemberOrder[`@MemberOrder`] annotation. Such a grid, if persisted as the layout XML file for the domain class, allows the
- `@MemberOrder` annotation to be removed from the source code of the domain class (but other annotations must be retained).
-<6> Takes a normalized grid and enriches it with additional metadata (taken from Apache Isis' internal metadata) that can be represented in the layout XML. Such a grid, if persisted as the layout XML file for the domain class, allows all layout annotations (xref:rgant.adoc#_rgant-ActionLayout[`@ActionLayout`], xref:rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`] and xref:rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`]) to be removed from the source code of the domain class.
-<7> Takes a normalized grid and strips out removes all members, leaving only the grid structure. Such a grid, if persisted as the layout XML file for the domain class, requires that the xref:rgant.adoc#_rgant-MemberOrder[`@MemberOrder`] annotation is retained in the source code of said class in order to bind members to the regions of the grid.
-
-
-== Implementation
-
-The framework provides `GridSystemServiceBS3`, an implementation that encodes the bootstrap3 grid system. (The framework
-also provides xref:ugvw.adoc[Wicket viewer] components that are capable of interpreting and rendering this metadata).
-
-
-== 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
- Bootstrap3 default implementation of `GridSystemService` is automatically registered and injected, and no further
- configuration is required.
-
-To use an alternative implementation, use
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
-
-
-== Related Services
-
-This service is used by xref:rgsvc.adoc#_rgsvc_spi_GridService[`GridService`].
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_HintStore.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_HintStore.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_HintStore.adoc
deleted file mode 100644
index 62c56d5..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_HintStore.adoc
+++ /dev/null
@@ -1,64 +0,0 @@
-[[_rgsvc_spi_HintStore]]
-= `HintStore`
-: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 `HintStore` service defines an SPI for the xref:ugvw.adoc#[Wicket viewer] to store UI hints on a per-object basis.
-For example, the viewer remembers which tabs are selected, and for collections which view is selected (eg table or hidden),
-which page of a table to render, or whether "show all" (rows) is toggled.
-
-The default implementation of this service uses the HTTP session. The service is an SPI because the amount of data
-stored could potentially be quite large (for large numbers of users who use the app all day). An SPI makes it easy to
-plug in an alternative implementation that is more sophisticated than the default (eg implementing MRU/LRU queue, or
-using a NoSQL database, or simply to disabling the functionality altogether).
-
-
-== SPI
-
-The SPI of `HintStore` is:
-
-[source,java]
-----
-public interface HintStore {
- String get(final Bookmark bookmark, String hintKey); // <1>
- void set(final Bookmark bookmark, String hintKey, String value); // <2>
- void remove(final Bookmark bookmark, String hintKey); // <3>
- void removeAll(Bookmark bookmark); // <4>
- Set<String> findHintKeys(Bookmark bookmark); // <5>
-}
-----
-<1> obtain a hint (eg which tab to open) for a particular object. Object identity is represented by `Bookmark`, as
-per the xref:rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`], so that alternative implementations can easily serialize this state to a string.
-<2> set the state of a hint. (The value of) all hints are represented as strings.
-<3> remove a single hint for an object;
-<4> remove all hints
-<5> obtain all known hints for an object
-
-
-
-== Implementation
-
-The core framework provides a default implementation of this service (`org.apache.isis.viewer.wicket.viewer.services.HintStoreUsingWicketSession`).
-
-
-
-
-== 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 `HintStore` 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
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
-
-
-== Related Services
-
-The xref:ugvw.adoc[Wicket viewer] exposes the xref:rgcms.adoc#__rgcms_classes_mixins_Object_clearHints["clear hints"]
-mixin action that is for use by end-users of the application to clear any UI hints that have accumulated for a
-domain object.
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_LocaleProvider.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_LocaleProvider.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_LocaleProvider.adoc
deleted file mode 100644
index 45789fc..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_LocaleProvider.adoc
+++ /dev/null
@@ -1,70 +0,0 @@
-[[_rgsvc_spi_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 Apache Isis' support for i18n, being used by Isis' default implementation of xref:rgsvc.adoc#_rgsvc_spi_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 Apache Isis' i18n support, see xref:ugbtb.adoc#_ugbtb_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:rgant.adoc#_rgant-RequestScoped[`@RequestScoped`], however).
-
-
-
-
-== Implementation
-
-Isis' xref:ugvw.adoc#[Wicket viewer] provides an implementation of this service (`LocaleProviderWicket`) which leverages Apache Wicket APIs.
-
-[NOTE]
-====
-Currently there is no equivalent implementation for the xref:ugvro.adoc#[RestfulObjects viewer].
-====
-
-
-
-
-== 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]), __and__ that the
-xref:ugvw.adoc#[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.
-
-To use an alternative implementation, use
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
-in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
-
-
-
-
-== Related Services
-
-This service works in conjunction with xref:rgsvc.adoc#_rgsvc_spi_TranslationService[`TranslationService`] and xref:rgsvc.adoc#_rgsvc_spi_TranslationsResolver[`TranslationsResolver`] in order to provide i18n support.
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_PublisherService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_PublisherService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_PublisherService.adoc
deleted file mode 100644
index 41f257b..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_PublisherService.adoc
+++ /dev/null
@@ -1,165 +0,0 @@
-[[_rgsvc_spi_PublisherService]]
-= `PublisherService`
-: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 `PublisherService` API is intended for coarse-grained publish/subscribe for system-to-system interactions, from Apache Isis to some other system. Events that can be published are action invocations/property
-edits, and 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.
-
-An alternative use is for profiling: for each execution (action invocation/property edit) the framework captures
-metrics of the number of objects loaded or dirtied as the result of that execution. If the
-xref:rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`] is used to call other objects then the metrics are captured
-for each sub-execution. The framework provides a default implementation, `PublisherServiceLogging`, that will log
-these execution graphs (in XML form, per the xref:rgcms.adoc#_rgcms_schema-ixn["ixn" schema]) to an SLF4J logger.
-
-Only actions/properties/domain objects annotated for publishing (using
-xref:rgant.adoc#_rgant-Action_publishing[`@Action#publishing()`],
-xref:rgant.adoc#_rgant-Property_publishing[`@Property#publishing()`] or
-xref:rgant.adoc#_rgant-DomainObject_publishing[`@DomainObject#publishing()`]) are published.
-
-
-== SPI
-
-The SPI defined by the service is:
-
-[source,java]
-----
-public interface PublisherService {
- void publish(final Interaction.Execution<?, ?> execution); // <1>
- void publish(final PublishedObjects publishedObjects); // <2>
-}
-----
-<1> to publish an individual action invocation or property edit, as captured within an `Interaction.Execution`.
-<2> to publish a set of changed objects.
-
-Each `Interaction.Execution` has an owning `Interaction`; this is the same object obtainable from
-xref:rgsvc.adoc#_rgsvc_spi_InteractionContext[`InteractionContext`]. Implementations that publish member executions
-can use `Interaction.Execution#getDto()` method to return a DTO (as per the
-xref:rgcms.adoc#_rgcms_schema-ixn["ixn" schema]) which can be converted into a serializable XML representation using
-the `InteractionDtoUtils` utility class. The XML can either serialize a single execution, or can be a "deep"
- serialization of an execution and all sub-executions.
-
-The full API of `PublishedObjects` itself is:
-
-[source,java]
-----
-public interface PublishedObjects extends HasTransactionId, HasUsername {
- UUID getTransactionId(); // <1>
- String getUsername(); // <2>
- Timestamp getCompletedAt(); // <3>
- ChangesDto getDto(); // <4>
-
- int getNumberLoaded(); // <5>
- int getNumberCreated();
- int getNumberUpdated();
- int getNumberDeleted();
- int getNumberPropertiesModified();
-}
-----
-<1> inherited from `HasTransactionId`, correlates back to the unique identifier of the transaction in which these
-objects were changed.
-<2> inherited from `HasUsername`, is the user that initiated the transaction causing these objects to change
-<3> the time that this set of objects was collated (just before the completion of the transaction completes)..
-<4> returns a DTO (as per the xref:rgcms.adoc#_rgcms_schema-chg["chg" schema]) which can be converted into a
-serializable XML representation can be obtained using the `ChangesDtoUtils` utility class.
-<5> metrics as to the number of objects loaded, created, updated or deleted and the number of object properties modified (in other words the "size" or "weight" of the transaction).
-
-
-== Implementations
-
-The framework allows multiple implementations of this service to be registered; all will be called. The framework
-provides one implementation of its own, `PublisherServiceLogging` (in `o.a.i.applib.services.publish` package); this
-logs "deep" serializations to an SLF4J logger.
-
-For example, this can be configured to write to a separate log file by adding the following to `logging.properties`:
-
-[source,ini]
-----
-log4j.appender.PublisherServiceLogging=org.apache.log4j.FileAppender
-log4j.appender.PublisherServiceLogging.File=./logs/PublisherServiceLogging.log
-log4j.appender.PublisherServiceLogging.Append=false
-log4j.appender.PublisherServiceLogging.layout=org.apache.log4j.PatternLayout
-log4j.appender.PublisherServiceLogging.layout.ConversionPattern=%d{yyyy-MM-dd HH:mm:ss.SSS} %m%n
-
-log4j.logger.org.apache.isis.applib.services.publish.PublisherServiceLogging=DEBUG,PublisherServiceLogging
-log4j.additivity.org.apache.isis.applib.services.publish.PublisherServiceLogging=false
-----
-
-
-The (non-ASF) http://github.com/isisaddons/isis-module-publishmq[Isis addons' publishmq] module also provides an
-implementation (`o.ia.m.publishmq.dom.servicespi.PublishingServiceUsingActiveMq`). This implementation publishes each
-member execution as an event on an link:http://activemq.apache.org[ActiveMQ] message queue. It also persists each
-execution as a `PublishedEvent` entity, allowing the event to be republished if necessary. The implementation also
-provides the ability to log additional `StatusMessage` entities, correlated on the transactionId, useful for diagnosing
-and monitoring the activity of subscribers of said message queues.
-
-
-== Usage
-
-To indicate that an action invocation should be published, annotate it with the
-xref:rgant.adoc#_rgant-Action_publishing[`@Action#publishing()`] annotation.
-
-To indicate that an property edit should be published, annotate it with the
-xref:rgant.adoc#_rgant-Property_publishing[`@Property#publishing()`] annotation.
-
-To indicate that a changed object should be published is to annotate it with the
-xref:rgant.adoc#_rgant-DomainObject_publishing[`@DomainObject#publishing()`] annotation.
-
-
-
-== Registering the Services
-
-The (non-ASF) Isis addons' http://github.com/isisaddons/isis-module-publishmq[publishmq] module provides an
-implementation of this service. 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.
-
-The module also provide services that contribute to the UI. If contributions are not required in the UI, these can be
-suppressed either using security or by implementing a
-xref:ugbtb.adoc#_ugbtb_decoupling_vetoing-visibility[vetoing subscriber].
-
-
-
-
-== Related Services
-
-This service supports two main use cases:
-
-* coarse-grained publish/subscribe for system-to-system interactions, from Apache Isis to some other system. +
-+
-[NOTE]
-====
-The xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`] also supports this use case, but
-is deprecated: the `PublisherService` is intended as a replacement for `PublishingService`.
-====
-
-* profiling of interactions/transactions, eg to diagnose response/throughput issues.
-
-
-To support these use cases several other services are involved:
-
-* the xref:rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`] is used to obtain the `Interaction` from which
-the member executions are published.
-
-* the (internal) xref:rgfis.adoc#_rgfis_spi_ChangedObjectsServiceInternal[`ChangedObjectsServiceInternal`] domain
-service is used to obtain the set of objects modified throughout the transaction
-
-* the (internal) xref:rgfis.adoc#_rgfis_spi_PublisherServiceInternal[`PublisherServiceInternal`] domain service filters
-these down to those changed objects that are also published (as per
-xref:rgant.adoc#_rgant-DomainObject_publishing[`@DomainObject#publishing()`]) and delegates to the `PublisherService`.
-
-* the xref:rgsvc.adoc#_rgsvc_api_MetricsService[`MetricsService`] is used to obtain the objects that are loaded
-throughout the transaction; this info is used in order to instantiate the `PublishedObjects` object passed through to
-the `PublisherService`.
-
-The xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] differs from the `PublisherService` in that it is
-intended for fine-grained publish/subscribe for object-to-object interactions within an Apache 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. That said, it is possible to obtain a serialization of the action
-invocation/property edit causing the current event to be raised using
-xref:rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`] domain service.
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_PublishingService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_PublishingService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_PublishingService.adoc
deleted file mode 100644
index 5407434..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_PublishingService.adoc
+++ /dev/null
@@ -1,204 +0,0 @@
-[[_rgsvc_spi_PublishingService]]
-= `PublishingService` (deprecated)
-: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` API is intended for coarse-grained publish/subscribe for system-to-system interactions, from Apache 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.
-
-
-[WARNING]
-====
-As of `1.13.0` this service is deprecated, replaced with xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`].
-====
-
-
-
-== SPI
-
-The SPI defined by the service is:
-
-[source,java]
-----
-@Deprecated
-public interface PublishingService {
- public void publish(
- EventMetadata metadata, // <1>
- EventPayload payload); // <2>
- void setEventSerializer(EventSerializer eventSerializer); // <3>
-}
-----
-<1> standard metadata about the event, such as the user, the xref:rgcms.adoc#_rgcms_classes_mixins_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:rgsvc.adoc#_rgsvc_spi_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.PublishingService`) 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".
-
-The framework provides no default implementations of this service.
-
-
-
-== Usage
-
-To indicate that an action invocation should be published, annotate it with the xref:rgant.adoc#_rgant-Action_publishing[`@Action#publishing()`] annotation.
-
-To indicate that a changed object should be published is to annotate it with the xref:rgant.adoc#_rgant-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 Apache Isis to determine any information that has not been published.
-
-[NOTE]
-====
-The replacement xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`] does __not__ support the concept of "payload factories" (but is otherwise more flexible).
-====
-
-
-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]
-----
-@Deprecated
-public interface PublishingPayloadFactoryForAction {
- 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]
-----
-@Deprecated
-public interface PublishingPayloadFactoryForObject {
- 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
-
-There is no default implementation of this service provided by the core Apache Isis framework.
-
-The (non-ASF) Isis addons' http://github.com/isisaddons/isis-module-publishing[publishing] module provides an
-implementation of this service. 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.
-
-The module also provides services that contribute to the UI. If contributions are not required in the UI, these can be
-suppressed either using security or by implementing a
-xref:ugbtb.adoc#_ugbtb_decoupling_vetoing-visibility[vetoing subscriber].
-
-
-
-
-
-== Related Services
-
-The `PublishingService` is intended for coarse-grained publish/subscribe for system-to-system interactions, from
-Apache Isis to some other system. Here the only events published are those that action invocations (for actions
-annotated with xref:rgant.adoc#_rgant-Action_publishing[`@Action#publishing()`]) and of changed objects (for objects
-annotated with xref:rgant.adoc#_rgant-DomainObject_publishing[`@DomainObject#publishing()`].
-
-The xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`] is intended as a replacement for this service. The
-use case for `PublisherService` is the same: coarse-grained publishing of events for system-to-system interactions. It
-is in most respects more flexible though: events are published both for action invocations (annotated with
-xref:rgant.adoc#_rgant-Action_publishing[`@Action#publishing()`]) and also for property edits (annotated with
-xref:rgant.adoc#_rgant-Property_publishing[`@Property#publishing()`]. It also publishes changed objects (for objects
-annotated with xref:rgant.adoc#_rgant-DomainObject_publishing[`@DomainObject#publishing()`]). However, rather than
-publishing one event for every changed objects, it publishes a single event that identifies all objects created,
-updated or deleted.
-
-Another significant difference between `PublishingService` and `PublisherService` is in the content of the events
-themselves. While the former uses the xref:rgsvc.adoc#_rgsvc_api_MementoService[`MementoService`] to create an
-ad-hoc serialization of the action being invoked, the latter uses the xref:rgcms.adoc#_rgcms_schema[DTOs/XML schemas]
-as a formal specification of the nature of the interaction (action invocation, property edit or changed objects).
-
-The xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] meanwhile differs from both `PublishingService` and
-xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`] in that it is intended for fine-grained
-publish/subscribe for object-to-object interactions within an Apache 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. (That said, it is possible to obtain a serialization of the action invocation/property edit causing the
-current event to be raised using xref:rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`] domain service).
-
-
-== 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
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_RoutingService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_RoutingService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_RoutingService.adoc
deleted file mode 100644
index 7bc2527..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_RoutingService.adoc
+++ /dev/null
@@ -1,79 +0,0 @@
-[[_rgsvc_spi_RoutingService]]
-= `RoutingService`
-: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 `RoutingService` provides the ability to return (and therefore render) an alternative object from an action invocation.
-
-There are two primary use cases:
-
-* if an action returns an aggregate leaf (that is, a child object which has an owning parent), then the parent object can be
-returned instead. +
-+
-For example, an action returning `OrderItem` might instead render the owning `Order` object. It is the responsibility
-of the implementation to figure out what the "owning" object might be.
-
-* if an action returns `null` or is `void`, then return some other "useful" object. +
-+
-For example, return the home page (eg as defined by the xref:rgant.adoc#_rgant-HomePage[`@HomePage`] annotation).
-
-Currently the routing service is used only by the xref:ugvw.adoc#[Wicket viewer]; it is ignored by the xref:ugvro.adoc#[Restful Objects] viewer.
-
-
-[NOTE]
-====
-Unlike most other domain services, the framework will check _all_ available implementations of
-`RoutingService` to return a route, rather than the first implementation found; in other words it uses the
-chain-of-responsibility pattern. Services are called in the order defined by
-xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`]). The route used will be the
-result of the first implementation checked that declares that it can provide a route.
-====
-
-
-== SPI
-
-The SPI defined by this service is:
-
-[source,java]
-----
-public interface RoutingService {
- @Programmatic
- boolean canRoute(Object original); // <1>
- @Programmatic
- Object route(Object original); // <2>
-}
-----
-<1> whether this implementation recognizes and can "route" the object. The `route(...)` method is only called if this method returns `true`.
-<2> the object to use; this may be the same as the original object, some other object, or (indeed) `null`.
-
-
-
-
-== Implementation
-
-The framework provides a default implementation - `RoutingServiceDefault` - which will always return the original object provided, or the home page
-if a `null` or `void` was provided. It uses the xref:rgsvc.adoc#_rgsvc_api_HomePageProviderService[`HomePageProviderService`].
-
-There can be multiple implementations of `RoutingService` registered. These are checked in turn (chain of responsibility
-pattern), ordered according to xref:rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`]
-(as explained in the xref:rgsvc.adoc#__rgsvc_intro_overriding-the-services[introduction] to this guide).
-The route from the first service that returns `true` from its `canRoute(...)` method will be used.
-
-
-
-== 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 `RoutingService` service is automatically registered and injected (it is annotated with
-`@DomainService`) so no further configuration is required.
-
-
-
-== Related Services
-
-The default implementation of this service uses the
-xref:rgsvc.adoc#_rgsvc_api_HomePageProviderService[`HomePageProviderService`].
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_TableColumnOrderService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_TableColumnOrderService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_TableColumnOrderService.adoc
deleted file mode 100644
index 0d91f91..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_TableColumnOrderService.adoc
+++ /dev/null
@@ -1,49 +0,0 @@
-[[_rgsvc_spi_TableColumnOrderService]]
-= `TableColumnOrderService`
-: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 `TableColumnOrderService` provides the ability to reorder (or suppress) columns in both parented- and standalone tables.
-
-
-== SPI
-
-The SPI defined by this service is:
-
-[source,java]
-----
-public interface TableColumnOrderService {
- List<String> orderParented( // <1>
- Object parent,
- String collectionId,
- Class<?> collectionType,
- List<String> propertyIds);
- List<String> orderStandalone( // <2>
- Class<?> collectionType,
- List<String> propertyIds);
-}
-----
-<1> for the parent collection owned by the specified parent and collection Id, return the set of property ids in the same or other order.
-<2> for the standalone collection of the specified type, return the set of property ids in the same or other order, else return `null` if provides no reordering.
-
-There can be multiple implementations of `TableColumnOrderService` registered, ordered as per xref:rgant.adoc#_rgant_DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`].
-The ordering provided by the first such service that returns a non-`null` value will be used.
-If all provided implementations return `null`, then the framework will fallback to a default implementation.
-
-
-
-== Implementation
-
-The framework provides a fallback implementation of this service, namely `TableColumnOrderService.Default`.
-
-
-== 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 implementation of `TableColumnOrderService` is automatically registered and injected, and no further
- configuration is required.
-