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 2016/05/15 17:11:19 UTC
[2/2] isis git commit: ISIS-1291: moved internal framework services
into its own guide
ISIS-1291: moved internal framework services into its own guide
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/0e5a55ab
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/0e5a55ab
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/0e5a55ab
Branch: refs/heads/master
Commit: 0e5a55abd0b81319f75341524e18235043a69520
Parents: e74c7a9
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Sun May 15 18:01:48 2016 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Sun May 15 18:01:48 2016 +0100
----------------------------------------------------------------------
.../src/main/asciidoc/documentation.adoc | 2 +-
.../guides/_rgfis_application-layer.adoc | 67 ++++++
.../guides/_rgfis_persistence-layer.adoc | 75 +++++++
.../guides/_rgfis_presentation-layer.adoc | 66 ++++++
.../_rgfis_spi_AuditingServiceInternal.adoc | 46 +++++
...rgfis_spi_ChangedObjectsServiceInternal.adoc | 69 +++++++
.../_rgfis_spi_CommandDtoServiceInternal.adoc | 62 ++++++
.../_rgfis_spi_ContentNegotiationService.adoc | 200 ++++++++++++++++++
...rgfis_spi_InteractionDtoServiceInternal.adoc | 44 ++++
.../_rgfis_spi_PublishingServiceInternal.adoc | 76 +++++++
.../_rgfis_spi_RepresentationService.adoc | 100 +++++++++
.../guides/_rgsvc_api_AcceptHeaderService.adoc | 2 +-
.../guides/_rgsvc_api_BackgroundService.adoc | 4 +-
.../guides/_rgsvc_api_MetricsService.adoc | 2 +-
.../_rgsvc_application-layer-internal-spi.adoc | 76 -------
.../src/main/asciidoc/guides/_rgsvc_intro.adoc | 13 +-
.../_rgsvc_persistence-layer-internal-spi.adoc | 83 --------
.../_rgsvc_presentation-layer-internal-spi.adoc | 70 -------
.../guides/_rgsvc_presentation-layer-spi.adoc | 3 -
.../_rgsvc_spi_AuditingServiceInternal.adoc | 46 -----
...rgsvc_spi_ChangedObjectsServiceInternal.adoc | 69 -------
.../_rgsvc_spi_CommandDtoServiceInternal.adoc | 60 ------
.../_rgsvc_spi_ContentMappingService.adoc | 6 +-
.../_rgsvc_spi_ContentNegotiationService.adoc | 204 -------------------
...rgsvc_spi_InteractionDtoServiceInternal.adoc | 42 ----
.../guides/_rgsvc_spi_PublisherService.adoc | 4 +-
.../_rgsvc_spi_PublishingServiceInternal.adoc | 76 -------
.../_rgsvc_spi_RepresentationService.adoc | 103 ----------
.../asciidoc/guides/_ugvro_architecture.adoc | 4 +-
.../src/main/asciidoc/guides/cgcom.adoc | 1 +
.../src/main/asciidoc/guides/dg.adoc | 1 +
.../src/main/asciidoc/guides/rgant.adoc | 1 +
.../src/main/asciidoc/guides/rgcfg.adoc | 1 +
.../src/main/asciidoc/guides/rgcms.adoc | 1 +
.../src/main/asciidoc/guides/rgfis.adoc | 55 +++++
.../src/main/asciidoc/guides/rgmvn.adoc | 1 +
.../src/main/asciidoc/guides/rgsvc.adoc | 4 +-
.../src/main/asciidoc/guides/ugbtb.adoc | 1 +
.../src/main/asciidoc/guides/ugfun.adoc | 1 +
.../src/main/asciidoc/guides/ugsec.adoc | 1 +
.../src/main/asciidoc/guides/ugtst.adoc | 1 +
.../src/main/asciidoc/guides/ugvro.adoc | 1 +
.../src/main/asciidoc/guides/ugvw.adoc | 9 +-
43 files changed, 897 insertions(+), 856 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/0e5a55ab/adocs/documentation/src/main/asciidoc/documentation.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/documentation.adoc b/adocs/documentation/src/main/asciidoc/documentation.adoc
index 00ac3ae..98f9aaa 100644
--- a/adocs/documentation/src/main/asciidoc/documentation.adoc
+++ b/adocs/documentation/src/main/asciidoc/documentation.adoc
@@ -74,7 +74,7 @@ pass:[<br/>]
* link:./guides/rgcfg.html[Configuration Properties^] image:{_imagesdir}PDF-50.png[width="20px" link="./guides/rgcfg.pdf"]
* link:./guides/rgcms.html[Classes, Methods and Schema^] image:{_imagesdir}PDF-50.png[width="20px" link="./guides/rgcms.pdf"]
* link:./guides/rgmvn.html[Apache Isis Maven plugin^] image:{_imagesdir}PDF-50.png[width="20px" link="./guides/rgmvn.pdf"]
-
+* link:./guides/rgfis.html[Framework Internal Services^] image:{_imagesdir}PDF-50.png[width="20px" link="./guides/fwsvc.pdf"]
http://git-wip-us.apache.org/repos/asf/isis/blob/0e5a55ab/adocs/documentation/src/main/asciidoc/guides/_rgfis_application-layer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgfis_application-layer.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgfis_application-layer.adoc
new file mode 100644
index 0000000..eeaaa77
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgfis_application-layer.adoc
@@ -0,0 +1,67 @@
+[[_rgfis_application-layer]]
+= Application Layer
+: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/
+
+
+
+These domain services are internal to the framework, controlling various aspects of the application layer.
+
+The table below summarizes the application layer internal SPIs defined by Apache Isis. It also lists their
+corresponding implementation, either a default implementation provided by Apache Isis itself, or provided by one of the
+(non-ASF) link:http://www.isisaddons.org[Isis Addons] modules.
+
+
+
+.Internal Services
+[cols="3,3,2,2a", options="header"]
+|===
+
+|SPI
+|Maven Module +
+Impl'n (g: a:)
+|Implementation
+|Notes
+
+
+
+|xref:rgfis.adoc#_rgfis_spi_CommandDtoServiceInternal[`o.a.i.c.m.s.command` +
+`CommandDtoServiceInternal`]
+|(`1.13.0-SNAPSHOT`) Creates memento of current action invocation, for use as a serializable XML reified command. The
+most notable usage of this is to allow the execution of the `Command` to be deferred to run in the background (via
+xref:rgant.adoc#_rgant-Action_command[`@Action#commandExecuteIn()`] or
+xref:rgant.adoc#_rgant-Property_command[`@Property#commandExecuteIn()`].
+|`CommandDtoService-` +
+`InternalServiceDefault` +
+``o.a.i.c.r.s.command`` +
+``isis-core-runtime``
+|
+
+
+|xref:rgfis.adoc#_rgfis_spi_InteractionDtoServiceInternal[`o.a.i.c.m.s.ixn` +
+`InteractionDtoServiceInternal`]
+|(`1.13.0-SNAPSHOT`) Creates DTO for the current execution of an action invocation or property edit, for use either as a reified command or for implementations of the xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`].
+|`CommandDtoService-` +
+`InternalServiceDefault` +
+``o.a.i.c.m.s.command`` +
+``isis-core-metamodel``
+|
+
+
+
+
+|===
+
+Key:
+
+* `o.a.i` is an abbreviation for `org.apache.isis`
+* `o.ia.m` is an abbreviation for `org.isisaddons.module`
+* `o.a.i.c.m.s` is an abbreviation for `org.apache.isis.core.metamodel.services`
+* `o.a.i.c.r.s` is an abbreviation for `org.apache.isis.core.runtime.services`
+
+
+
+
+include::_rgfis_spi_CommandDtoServiceInternal.adoc[leveloffset=+1]
+include::_rgfis_spi_InteractionDtoServiceInternal.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/0e5a55ab/adocs/documentation/src/main/asciidoc/guides/_rgfis_persistence-layer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgfis_persistence-layer.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgfis_persistence-layer.adoc
new file mode 100644
index 0000000..f1e0af9
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgfis_persistence-layer.adoc
@@ -0,0 +1,75 @@
+[[_rgfis_persistence-layer]]
+= Persistence Layer internal 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/
+
+
+
+These domain services are internal to the framework, controlling various aspects of the persistence layer.
+
+
+The table below summarizes the persistence layer internal SPIs defined by Apache Isis. It also lists their
+corresponding implementation, either a default implementation provided by Apache Isis itself, or provided by one of the
+(non-ASF) link:http://www.isisaddons.org[Isis Addons] modules.
+
+
+
+.Internal Services
+[cols="3,3,2,2a", options="header"]
+|===
+
+|SPI
+|Maven Module +
+Impl'n (g: a:)
+|Implementation
+|Notes
+
+
+
+|xref:rgfis.adoc#_rgfis_spi_AuditingServiceInternal[`o.a.i.c.r.s.auditing.` +
+`AuditingServiceInternal`]
+|(`1.13.0-SNAPSHOT`) Co-ordinates between
+xref:rgfis.adoc#_rgfis_spi_ChangedObjectsServiceInternal[`ChangedObjectsServiceInternal`] and
+xref:rgfis.adoc#_rgfis_spi_AuditingService[`AuditingService`].
+|concrete class.
+|
+
+
+|xref:rgfis.adoc#_rgfis_spi_ChangedObjectsServiceInternal[`o.a.i.c.r.s.changes.` +
+`ChangedObjectsServiceInternal`]
+|(`1.13.0-SNAPSHOT`) Request-scoped service holding objects enlisted into current transaction.
+|concrete class.
+|
+
+
+|xref:rgfis.adoc#_rgfis_spi_PublishingServiceInternal[`o.a.i.c.m.s.publishing.` +
+`PublishingServiceInternal`]
+|(`1.13.0-SNAPSHOT`) Co-ordinates between
+xref:rgfis.adoc#_rgfis_spi_ChangedObjectsServiceInternal[`ChangedObjectsServiceInternal`] and
+xref:rgsvc.adoc#_rgsvc_api_MetricsService[`MetricsService`] and the SPI services,
+xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`] and (deprecated)
+xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`].
+|`PublishingService-` +
+`InternalDefault` +
+`o.a.i.c.r.publishing` +
+`isis-core-runtime`
+|
+
+
+
+|===
+
+Key:
+
+* `o.a.i` is an abbreviation for `org.apache.isis`
+* `o.ia.m` is an abbreviation for `org.isisaddons.module`
+* `o.a.i.c.m.s` is an abbreviation for `org.apache.isis.core.metamodel.services`
+* `o.a.i.c.r.s` is an abbreviation for `org.apache.isis.core.runtime.services`
+
+
+
+
+include::_rgfis_spi_AuditingServiceInternal.adoc[leveloffset=+1]
+include::_rgfis_spi_ChangedObjectsServiceInternal.adoc[leveloffset=+1]
+include::_rgfis_spi_PublishingServiceInternal.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/0e5a55ab/adocs/documentation/src/main/asciidoc/guides/_rgfis_presentation-layer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgfis_presentation-layer.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgfis_presentation-layer.adoc
new file mode 100644
index 0000000..349042c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgfis_presentation-layer.adoc
@@ -0,0 +1,66 @@
+[[_rgfis_presentation-layer]]
+= Presentation Layer
+: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/
+
+
+
+These domain services are internal to the framework, controlling various aspects of the presentation layer.
+
+
+
+The table below summarizes the presentation layer internal SPIs defined by Apache Isis. It also lists their
+corresponding implementation, either a default implementation provided by Apache Isis itself, or provided by one of the
+(non-ASF) link:http://www.isisaddons.org[Isis Addons] modules.
+
+
+
+.Internal Services
+[cols="3,3,2,2a", options="header"]
+|===
+
+|SPI
+|Maven Module +
+Impl'n (g: a:)
+|Implementation
+|Notes
+
+
+|xref:rgfis.adoc#_rgfis_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:rgfis.adoc#_rgfis_spi_RepresentationService[`o.a.i.v.ro.` +
+`rendering.service.` +
+`RepresentationService`]
+|Generates the representations, delegating to any registered xref:rgfis.adoc#_rgfis_spi_ContentNegotiationService[`ContentNegotiationService`]s.
+|`RepresentationService-` +
+`ForRestfulObjects` +
+``o.a.i.core`` +
+`isis-core-viewer-restfulobjects-rendering`
+|
+
+
+|===
+
+Key:
+
+* `o.a.i` is an abbreviation for `org.apache.isis`
+* `o.ia.m` is an abbreviation for `org.isisaddons.module`
+* `o.a.i.c.m.s` is an abbreviation for `org.apache.isis.core.metamodel.services`
+* `o.a.i.c.r.s` is an abbreviation for `org.apache.isis.core.runtime.services`
+* `o.a.i.v.ro` is an abbreviation for `org.apache.isis.viewer.restfulobjects`
+
+
+
+
+include::_rgfis_spi_ContentNegotiationService.adoc[leveloffset=+1]
+include::_rgfis_spi_RepresentationService.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/0e5a55ab/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_AuditingServiceInternal.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_AuditingServiceInternal.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_AuditingServiceInternal.adoc
new file mode 100644
index 0000000..59538dd
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_AuditingServiceInternal.adoc
@@ -0,0 +1,46 @@
+[[_rgfis_spi_AuditingServiceInternal]]
+= `AuditingServiceInternal` (`1.13.0-SNAPSHOT`)
+: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 (internal) `AuditingServiceInternal` domain service (`1.13.0-SNAPSHOT`) acts as an internal facade to any
+configured xref:rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`]. It is responsible for obtaining the details
+of all changes to domain objects within an interaction, and then to call the configured `AuditingService` to actually
+create audit entries of those changes.
+
+The service is a no-op if there is no configured `AuditingService`.
+
+
+== SPI and Implementation
+
+The SPI of the service is:
+
+[source,java]
+----
+public class AuditingServiceInternal {
+ public boolean canAudit(); // <1>
+ public void audit(); // <2>
+}
+----
+<1> whether auditing is enabled; checks to see if any xref:rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`] has been configured.
+<2> uses the xref:rgfis.adoc#_rgfis_spi_ChangedObjectsServiceInternal[`ChangedObjectsServiceInternal`] to obtain details of the changed properties, then call the configured xref:rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`].
+
+The service implementation is `o.a.i.c.r.s.auditing.AuditingServiceInternal`.
+
+
+
+== 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 `AuditingServiceInternal` class is automatically registered (it is annotated with `@DomainService`)
+so no further configuration is required.
+
+
+== Related Classes
+
+The service delegates between the (internal) xref:rgfis.adoc#_rgfis_spi_ChangedObjectsServiceInternal[`ChangedObjectsServiceInternal`] domain service to the configured xref:rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`]. If no such `AuditingService` is configured, this service is in effect a no-op.
+
+The (internal) xref:rgfis.adoc#_rgfis_spi_PublishingServiceInternal[`PublishingServiceInternal`] performs a similar function for the xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`], also collating details of the changed objects from `ChangedObjectsServiceInternal`.
http://git-wip-us.apache.org/repos/asf/isis/blob/0e5a55ab/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_ChangedObjectsServiceInternal.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_ChangedObjectsServiceInternal.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_ChangedObjectsServiceInternal.adoc
new file mode 100644
index 0000000..534a2a9
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_ChangedObjectsServiceInternal.adoc
@@ -0,0 +1,69 @@
+[[_rgfis_spi_ChangedObjectsServiceInternal]]
+= `ChangedObjectsServiceInternal` (`1.13.0-SNAPSHOT`)
+: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 `ChangedObjectsServiceInternal` class (`1.13.0-SNAPSHOT`) is an (internal) request-scoped domain service that is
+responsible for collecting the details of all changes to domain objects within an interaction. This is then used by
+various other (internal) domain services, notably
+xref:rgfis.adoc#_rgfis_spi_AuditingServiceInternal[`AuditingServiceInternal`] and
+xref:rgfis.adoc#_rgfis_spi_PublishingServiceInternal[`PublishingServiceInternal`].
+
+
+
+== SPI and Implementation
+
+The SPI of the service is:
+
+[source,java]
+----
+@RequestScoped
+public class ChangedObjectsServiceInternal {
+ public void enlistCreated(final ObjectAdapter adapter); // <1>
+ public void enlistUpdating(final ObjectAdapter adapter);
+ public void enlistDeleting(final ObjectAdapter adapter);
+
+ public boolean hasChangedAdapters(); // <2>
+
+ public Map<ObjectAdapter, PublishedObject.ChangeKind> getChangeKindByEnlistedAdapter(); // <3>
+ public int numberObjectsDirtied();
+ public int numberObjectPropertiesModified();
+
+ public Set<Map.Entry<AdapterAndProperty, PreAndPostValues>> getChangedObjectProperties(); // <4>
+
+ public void clearChangedObjectProperties(); // <5>
+}
+----
+<1> Enlists an object that has just been created, updated or deleted, capturing the pre-modification values of the properties.
+<2> Used by the framework to determine whether to set the "persist hint" on the `Command` object (as per xref:rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`]).
+<3> Used by xref:rgfis.adoc#_rgfis_spi_PublishingServiceInternal[`PublishingServiceInternal`] to obtain details of and
+counters of all objects changed within the transaction.
+<4> Used by xref:rgfis.adoc#_rgfis_spi_AuditingServiceInternal[`AuditingServiceInternal`] to obtain all pairs of
+pre/post values of changed properties
+<5> Called by the framework to for clean up after auditing and publishing has completed.
+
+For enlisted objects, if just created, then a dummy value `"[NEW]"` is used for the pre-modification value; if just
+deleted, then a dummy value `"[DELETED]"` is used for the post-modification value. The post-modification values of
+properties are captured when the transaction commits.
+
+
+The service implementation is `o.a.i.c.r.s.changes.ChangedObjectsServiceInternal`.
+
+
+
+== 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 `ChangedObjectsServiceInternal` class is automatically registered (it is annotated with `@DomainService`)
+so no further configuration is required.
+
+
+
+== Related Classes
+
+Both the xref:rgfis.adoc#_rgfis_spi_AuditingServiceInternal[`AuditingServiceInternal`] and
+xref:rgfis.adoc#_rgfis_spi_PublishingServiceInternal[`PublishingServiceInternal`] (internal) domain services query
+this object.
http://git-wip-us.apache.org/repos/asf/isis/blob/0e5a55ab/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_CommandDtoServiceInternal.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_CommandDtoServiceInternal.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_CommandDtoServiceInternal.adoc
new file mode 100644
index 0000000..7561c57
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_CommandDtoServiceInternal.adoc
@@ -0,0 +1,62 @@
+[[_rgfis_spi_CommandDtoServiceInternal]]
+= `CommandDtoServiceInternal` (`1.13.0-SNAPSHOT`)
+: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 `CommandDtoServiceInternal` (`1.13.0-SNAPSHOT`) is responsible for creating an memento of the current action
+invocation or property edit, to store in the `Command` object (from
+xref:rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`]). This memento is a JAXB DTO being an instance of the
+xref:rgcms.adoc#_rgcms_schema-cmd["cmd" schema], so can be reified so that its execution can be deferred until later,
+as a xref:rgsvc.adoc#_rgsvc_spi_BackgroundCommandService[background command].
+
+
+
+== SPI & Implementation
+
+The SPI of the service is:
+
+[source,java]
+----
+public interface CommandDtoServiceInternal {
+ @Deprecated
+ ActionInvocationMemento asActionInvocationMemento( // <1>
+ Method m,
+ Object domainObject, Object[] args);
+ CommandDto asCommandDto( // <2>
+ List<ObjectAdapter> targetAdapters,
+ ObjectAction objectAction,
+ ObjectAdapter[] argAdapters);
+ CommandDto asCommandDto( // <3>
+ final List<ObjectAdapter> targetAdapters,
+ final OneToOneAssociation association,
+ final ObjectAdapter valueAdapterOrNull);
+ void addActionArgs( // <4>
+ final ObjectAction objectAction,
+ final ActionDto actionDto,
+ final ObjectAdapter[] argAdapters);
+ void addPropertyValue( // <5>
+ final OneToOneAssociation property,
+ final PropertyDto propertyDto,
+ final ObjectAdapter valueAdapter);
+}
+----
+<1> Note that this method (more precisely, `ActionInvocationMemento`) does __not__ support mixins.
+<2> Returns a JAXB DTO being an instance of the xref:rgcms.adoc#_rgcms_schema-cmd["cmd" schema] (hence convertible to
+XML) that represents the __intention__ to invoke an action on a target object (or possibly many targets, for
+bulk actions). If an action, it can also be either mixin action or a contributed action.
+<3> Returns a JAXB DTO that represents the intention to edit (set or clear) a property on a target (or possibly many
+targets, for symmetry with actions).
+<4> add the arguments of an action to an `ActionDto`. This is used when the command is actually executed (per xref:rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`]) to populate the parameters of the equivalent `ActionInvocationDto`.
+<5> add the new value argument of a property to a `PropertyDto`. This is used when the command is actually executed (per xref:rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`]) to set the the new value of the equivalent `PropertyEditDto`.
+
+
+The SPI is implemented by `o.a.i.c.r.s.command.CommandDtoServiceInternalServiceDefault`.
+
+
+== Related Services
+
+The design of this service is similar to that of
+xref:rgfis.adoc#_rgfis_spi_InteractionDtoServiceInternal[`InteractionDtoServiceInternal`], used to create the
+`MemberExecutionDto` (from the xref:rgcms.adoc#_rgcms_schema-ixn["ixn" schema]).
http://git-wip-us.apache.org/repos/asf/isis/blob/0e5a55ab/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_ContentNegotiationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_ContentNegotiationService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_ContentNegotiationService.adoc
new file mode 100644
index 0000000..d1d4a14
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_ContentNegotiationService.adoc
@@ -0,0 +1,200 @@
+[[_rgfis_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_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_other-techniques_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.
+
+
+
+
+
+== 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"]
+
+
+
+
+[_rgfis_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
+in the xref:rgsvc.adoc#_rgsvc_intro_overriding-the-services[introduction] to this guide).
+
+
+
+== 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:rgfis.adoc#_rgfis_spi_RepresentationService[`RepresentationService`].
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/0e5a55ab/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_InteractionDtoServiceInternal.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_InteractionDtoServiceInternal.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_InteractionDtoServiceInternal.adoc
new file mode 100644
index 0000000..39191e2
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_InteractionDtoServiceInternal.adoc
@@ -0,0 +1,44 @@
+[[_rgfis_spi_InteractionDtoServiceInternal]]
+= `InteractionDtoServiceInternal` (`1.13.0-SNAPSHOT`)
+: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 `InteractionDtoServiceInternal` internal domain service (`1.13.0-SNAPSHOT`) is used by the framework to create and update DTOs representing member executions, ie the invocation of an action or the editing of a property. The DTO is in all cases a subclass of `MemberExecutionDto`, from the xref:rgcms.adoc#_rgcms_schema-ixn["ixn" schema], and subsequently accessible from the `Interaction` object (per the xref:rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`] service).
+
+
+== SPI & Implementation
+
+The SPI of the service is:
+
+[source,java]
+----
+public interface InteractionDtoServiceInternal {
+ ActionInvocationDto asActionInvocationDto( // <1>
+ ObjectAction objectAction,
+ ObjectAdapter targetAdapter,
+ List<ObjectAdapter> argumentAdapters);
+ PropertyEditDto asPropertyEditDto( // <2>
+ OneToOneAssociation property,
+ ObjectAdapter targetAdapter,
+ ObjectAdapter newValueAdapterIfAny);
+ ActionInvocationDto updateResult( // <3>
+ ActionInvocationDto actionInvocationDto,
+ ObjectAction objectAction,
+ Object resultPojo);
+}
+----
+<1> called by the framework when invoking an action, to create a DTO capturing the details of the action invocation (target, arguments etc).
+<2> called by the framework when editing a property, to create a DTO (for the xref:rgcms.adoc#_rgcms_schema-ixn["ixn" schema]) capturing the details of the property edit (target, new value etc).
+<3> called by the framework to attach the result of an action invocation to the aforementioned DTO.
+
+The service is implemented by `o.a.i.core.runtime.services.ixn.InteractionDtoServiceInternalDefault`.
+
+
+== Related Services
+
+The design of this service is similar to that of
+xref:rgfis.adoc#_rgfis_spi_CommandDtoServiceInternal[`CommandDtoServiceInternal`], used to create the `CommandDto`
+(from the xref:rgcms.adoc#_rgcms_schema-cmd["cmd" schema]).
http://git-wip-us.apache.org/repos/asf/isis/blob/0e5a55ab/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_PublishingServiceInternal.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_PublishingServiceInternal.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_PublishingServiceInternal.adoc
new file mode 100644
index 0000000..0d45234
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_PublishingServiceInternal.adoc
@@ -0,0 +1,76 @@
+[[_rgfis_spi_PublishingServiceInternal]]
+= `PublishingServiceInternal` (`1.13.0-SNAPSHOT`)
+: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 (internal) `PublishingServiceInternal` domain service (`1.13.0-SNAPSHOT`) acts as an internal facade to any
+configured xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`] or (deprecated in `1.13.0-SNAPSHOT`)
+xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`] domain services.
+
+For published action invocations/ property edits, it provides an API for those member executions to call.
+
+For published objects, it provides an API for the framework to call at the end of the interaction; it obtains details
+of the changed objects (from the
+xref:rgfis.adoc#_rgfis_spi_ChangedObjectsServiceInternal[`ChangedObjectsServiceInternal`]) and filters them to just
+those objects that are to be published; these are then passed through to any configured `PublisherService` or
+`PublishingService` implementations.
+
+
+
+== SPI and Implementation
+
+The SPI of the service is:
+
+[source,java]
+----
+public class PublishingServiceInternal {
+ void publishAction(
+ Interaction.Execution execution, // <1>
+ ObjectAction objectAction, // <2>
+ IdentifiedHolder identifiedHolder,
+ ObjectAdapter targetAdapter,
+ List<ObjectAdapter> parameterAdapters,
+ ObjectAdapter resultAdapter);
+ void publishProperty( // <3>
+ Interaction.Execution execution);
+ void publishObjects(); // <4>
+}
+----
+<1> to publish an action invocation, as represented by the specified member `Execution` parameter and with the
+xref:rgant.adoc#_rgant-Action_publishing[`@Action#publishing()`] annotation attribute or equivalent, to any configured
+xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`]. The `Execution` object will be an instance of
+`ActionInvocation` (see xref:rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`] for details).
+<2> the remaining parameters are to support the publishing of the action to any configured
+xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`] services (deprecated in `1.13.0-SNAPSHOT`).
+<3> to publish a property edit, as as represented by the specified member `Execution` parameter and with the
+xref:rgant.adoc#_rgant-Property_publishing[`@Property#publishing()`] annotation attribute or equivalent, to any
+configured xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`]. The `Execution` object will be an instance
+of `PropertyEdit` (see xref:rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`] for details).
+<4> to publish all changed objects that are to be published (with the
+xref:rgant.adoc#_rgant-DomainObject_publishing[`@DomainObject#publishing()`] annotation attribute or equivalent).
+
+
+The service implementation is `o.a.i.c.m.s.publishing.PublishingServiceInternal`.
+
+
+
+== 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 `PublishingServiceInternal` class is automatically registered (it is annotated with `@DomainService`)
+so no further configuration is required.
+
+
+== Related Classes
+
+The service delegates between the (internal)
+xref:rgfis.adoc#_rgfis_spi_ChangedObjectsServiceInternal[`ChangedObjectsServiceInternal`] domain service to the
+configured xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`] and
+ xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`].
+
+The (internal) xref:rgfis.adoc#_rgfis_spi_AuditingServiceInternal[`AuditingServiceInternal`] performs a similar
+function for the xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`], also collating details of the
+changed objects from `ChangedObjectsServiceInternal`.
http://git-wip-us.apache.org/repos/asf/isis/blob/0e5a55ab/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_RepresentationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_RepresentationService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_RepresentationService.adoc
new file mode 100644
index 0000000..1f55c5f
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_RepresentationService.adoc
@@ -0,0 +1,100 @@
+[[_rgfis_spi_RepresentationService]]
+= `RepresentationService`
+: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 `RepresentationService` is the main plug-in point for the xref:ugvro.adoc#[RestfulObjects viewer] to generate representations.
+
+The default implementation generates representations according to the link:http://restfulobjects.org[Restful Objects spec] v1.0. However, it also delegates to the xref:rgfis.adoc#_rgfis_spi_ContentNegotiationService[`ContentNegotiationService`] which provides a mechanism for altering representations according to the HTTP `Accept` header.
+
+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.
+
+In all there are three domain services that can influence the representations generated: this service, xref:rgfis.adoc#_rgfis_spi_ContentNegotiationService[`ContentNegotiationService`]and the xref:rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`]. The diagram below shows how these collaborate:
+
+image::{_imagesdir}reference-services-spi/RepresentationService/service-collaborations.png[width="700px",link="{_imagesdir}reference-services-spi/RepresentationService/service-collaborations.png"]
+
+The `RepresentationServiceForRestfulObjects` is the default implementation of this service; likewise `ContentNegotiationServiceXRoDomainType` is the default implementation of the `ContentNegotiationService`. If you inspect the source code you'll see that the default implementation of this service's primary responsibility is to generate the default Restful Objects representations. Therefore, if you what you want to do is to generate a _different _representation then in many cases replacing either this service _or_ the `ContentNegotiationService` will be equivalent (you'll notice that their SPIs are very similar).
+
+
+== SPI
+
+The SPI defined by this service is:
+
+[source,java]
+----
+public interface RepresentationService {
+ @Programmatic
+ Response objectRepresentation( // <1>
+ Context rendererContext,
+ ObjectAdapter objectAdapter);
+ @Programmatic
+ Response propertyDetails( // <2>
+ Context rendererContext,
+ ObjectAndProperty objectAndProperty,
+ MemberReprMode memberReprMode);
+ @Programmatic
+ Response collectionDetails( // <3>
+ Context rendererContext,
+ ObjectAndCollection objectAndCollection,
+ MemberReprMode memberReprMode);
+ @Programmatic
+ Response actionPrompt( // <4>
+ Context rendererContext,
+ ObjectAndAction objectAndAction);
+ @Programmatic
+ Response actionResult( // <5>
+ Context rendererContext,
+ ObjectAndActionInvocation objectAndActionInvocation,
+ ActionResultReprRenderer.SelfLink selfLink);
+ public static interface Context extends RendererContext {
+ ObjectAdapterLinkTo getAdapterLinkTo();
+ }
+}
+----
+<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 `RendererContext` 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
+
+* for members, whether the representation is in read/write mode +
++
+ie `MemberReprMode`
+
+
+
+
+
+
+== Implementation
+
+As discussed in the introduction, the framework provides a default implementation, `o.a.i.v.ro.rendering.service.RepresentationServiceForRestfulObjects`. This delegates to xref:rgfis.adoc#_rgfis_spi_ContentNegotiationService[`ContentNegotiationService`] to generate an alternative representation; but if none is provided then it falls back on generating the representations as defined in the link:http://restfulobjects.org[Restful Objects spec] v1.0.
+
+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).
+
+
+== 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 `RepresentationService` service is automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
+
+
+
+
+== Related Services
+
+The default implementation delegates to xref:rgfis.adoc#_rgfis_spi_ContentNegotiationService[`ContentNegotiationService`], whose default implementation may delegate in turn to xref:rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`] (if present).
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/0e5a55ab/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_AcceptHeaderService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_AcceptHeaderService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_AcceptHeaderService.adoc
index 9e9a62c..a1dc7c5 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_AcceptHeaderService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_AcceptHeaderService.adoc
@@ -10,7 +10,7 @@ simply exposes the HTTP `Accept` header to the domain. Its intended use is to s
[NOTE]
====
-As an alternative to performing content negotiation within the domain classes, the xref:rgsvc.adoc#_rgsvc_spi_ContentNegotiationService[`ContentNegotiationService`] and
+As an alternative to performing content negotiation within the domain classes, the xref:rgfis.adoc#_rgfis_spi_ContentNegotiationService[`ContentNegotiationService`] and
xref:rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`] SPI domain services allow the framework to perform the content negotiation responsibility.
====
http://git-wip-us.apache.org/repos/asf/isis/blob/0e5a55ab/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_BackgroundService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_BackgroundService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_BackgroundService.adoc
index 694664f..92ec95d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_BackgroundService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_BackgroundService.adoc
@@ -14,7 +14,7 @@ The `BackgroundService2` is responsible for capturing a memento representing the
and persisting it rather than executing it directly.
The default `BackgroundServiceDefault` implementation works by using a proxy wrapper around the target so that it can
-capture the action to invoke and its arguments. (As of `1.13.0-SNAPSHOT`), this is done using xref:rgsvc.adoc#_rgsvc_spi_CommandDtoServiceInternal[`CommandDtoServiceInternal`] (in previous releases it used (a private copy of) xref:rgsvc.adoc#_rgsvc_api_MementoService[`MementoService`]).
+capture the action to invoke and its arguments. (As of `1.13.0-SNAPSHOT`), this is done using xref:rgfis.adoc#_rgfis_spi_CommandDtoServiceInternal[`CommandDtoServiceInternal`] (in previous releases it used (a private copy of) xref:rgsvc.adoc#_rgsvc_api_MementoService[`MementoService`]).
The persistence delegates the persistence of the memento to an appropriate implementation of the companion
`BackgroundCommandService2`. One such implementation of `BackgroundCommandService` is provided by (non-ASF)
@@ -126,7 +126,7 @@ The `CommandContext` service is responsible for providing a parent `Command` wit
The implementations of `CommandService` and `BackgroundCommandService` go together; typically both parent `Command`s and child background `Command`s will be persisted in the same way. The (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module provides implementations of both (see xref:rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] and xref:rgsvc.adoc#_rgsvc_spi_BackgroundCommandService[`BackgroundCommandService`]).
-The xref:rgsvc.adoc#_rgsvc_spi_CommandDtoServiceInternal[`CommandDtoServiceInternal`] (`1.13.0-SNAPSHOT`) is used to obtain
+The xref:rgfis.adoc#_rgfis_spi_CommandDtoServiceInternal[`CommandDtoServiceInternal`] (`1.13.0-SNAPSHOT`) is used to obtain
a memento of the command such that it can be persisted. (In earlier versions, xref:rgsvc.adoc#_rgsvc_api_MementoService[`MementoService`] was used for this purpose).
http://git-wip-us.apache.org/repos/asf/isis/blob/0e5a55ab/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_MetricsService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_MetricsService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_MetricsService.adoc
index 497b9aa..9eb6b7d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_MetricsService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_api_MetricsService.adoc
@@ -9,7 +9,7 @@
The `MetricsService` (`1.13.0-SNAPSHOT`) is a request-scoped domain service that hooks into the JDO/DataNucleus
ObjectStore to provide a number of counters relating to numbers of object loaded, dirtied etc.
-The service is used by the xref:rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`] domain service (to populate the DTO held by the `Interaction.Execution`) and also by the (internal) xref:rgsvc.adoc#_rgsvc_spi_PublishingServiceInternal[`PublishingServiceInternal`] domain service (to populate
+The service is used by the xref:rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`] domain service (to populate the DTO held by the `Interaction.Execution`) and also by the (internal) xref:rgfis.adoc#_rgfis_spi_PublishingServiceInternal[`PublishingServiceInternal`] domain service (to populate
the `PublishedObjects` class.
http://git-wip-us.apache.org/repos/asf/isis/blob/0e5a55ab/adocs/documentation/src/main/asciidoc/guides/_rgsvc_application-layer-internal-spi.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_application-layer-internal-spi.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_application-layer-internal-spi.adoc
deleted file mode 100644
index ff44729..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_application-layer-internal-spi.adoc
+++ /dev/null
@@ -1,76 +0,0 @@
-[[_rgsvc_application-layer-internal-spi]]
-= Application Layer internal 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/
-
-
-
-These domain services are internal to the framework, controlling various aspects of the application layer.
-
-[WARNING]
-====
-We do not guarantee that link:http://semver.org[semantic versioning] will be honoured for these SPIs.
-====
-
-
-The table below summarizes the application layer internal SPIs defined by Apache Isis. It also lists their
-corresponding implementation, either a default implementation provided by Apache Isis itself, or provided by one of the
-(non-ASF) link:http://www.isisaddons.org[Isis Addons] modules.
-
-
-
-."Internal" SPI Services
-[cols="3,3,2,2a", options="header"]
-|===
-
-|SPI
-|Maven Module +
-Impl'n (g: a:)
-|Implementation
-|Notes
-
-
-
-|xref:rgsvc.adoc#_rgsvc_api_CommandDtoServiceInternal[`o.a.i.c.` +
-`m.s.command` +
-`CommandDtoServiceInternal`]
-|(`1.13.0-SNAPSHOT`) Creates memento of current action invocation, for use as a serializable XML reified command. The
-most notable usage of this is to allow the execution of the `Command` to be deferred to run in the background (via
-xref:rgant.adoc#_rgant-Action_command[`@Action#commandExecuteIn()`] or
-xref:rgant.adoc#_rgant-Property_command[`@Property#commandExecuteIn()`].
-|`CommandDtoService-` +
-`InternalServiceDefault` +
-``o.a.i.c.r.s.command`` +
-``isis-core-runtime``
-|
-
-
-|xref:rgsvc.adoc#_rgsvc_api_InteractionDtoServiceInternal[`o.a.i.c.` +
-`m.s.ixn` +
-`InteractionDtoServiceInternal`]
-|(`1.13.0-SNAPSHOT`) Creates DTO for the current execution of an action invocation or property edit, for use either as a reified command or for implementations of the xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`].
-|`CommandDtoService-` +
-`InternalServiceDefault` +
-``o.a.i.c.m.s.command`` +
-``isis-core-metamodel``
-|
-
-
-
-
-|===
-
-Key:
-
-* `o.a.i` is an abbreviation for `org.apache.isis`
-* `o.ia.m` is an abbreviation for `org.isisaddons.module`
-* `o.a.i.c.m.s` is an abbreviation for `org.apache.isis.core.metamodel.services`
-* `o.a.i.c.r.s` is an abbreviation for `org.apache.isis.core.runtime.services`
-
-
-
-
-include::_rgsvc_spi_CommandDtoServiceInternal.adoc[leveloffset=+1]
-
-include::_rgsvc_spi_InteractionDtoServiceInternal.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/0e5a55ab/adocs/documentation/src/main/asciidoc/guides/_rgsvc_intro.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_intro.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_intro.adoc
index 726c417..c233b9c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_intro.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_intro.adoc
@@ -41,8 +41,9 @@ allowing you to easily mock out these services in your unit tests.
The framework also defines a number of "internal" services. These are not part of the framework's formal API, in that
-they use classes that are outside of the applib. These are documented here, but should be thought of as part of the
-internal design of the framework, and are liable to change from release to release.
+they use classes that are outside of the applib. These internal framework services should be thought of as part of the
+internal design of the framework, and are liable to change from release to release. The internal framework services
+are documented in the xref:rgfis.adoc#[Framework Internal Services] guide.
@@ -200,12 +201,12 @@ xref:rgant.adoc#_rgant-Property_domainEvent[`@Property#domainEvent()`]). +
(Note that susbcribers will also receive events for vetoing the action/property; this is not shown on the diagram).
* As each execution progresses, and objects that are modified are "enlisted" into the (internal)
-xref:rgsvc.adoc#_rgsvc_spi_ChangedObjectsServiceInternal[`ChangedObjectsServiceInternal`] domain service. Metrics as
+xref:rgfis.adoc#_rgfis_spi_ChangedObjectsServiceInternal[`ChangedObjectsServiceInternal`] domain service. Metrics as
to which objects are merely loaded into memory are also captured using the
xref:rgsvc.adoc#_rgsvc_api_MetricsService[`MetricsService`] (not shown on the diagram).
* At the end of each execution, details of that execution are published through the (internal)
-xref:rgsvc.adoc#_rgsvc_spi_PublisherServiceInternal[`PublisherServiceInternal`] domain service. This is only done for
+xref:rgfis.adoc#_rgfis_spi_PublisherServiceInternal[`PublisherServiceInternal`] domain service. This is only done for
actions/properties annotated appropriate (with xref:rgant.adoc#_rgant-Action_publishing[`@Action#publishing()`] or
xref:rgant.adoc#_rgant-Property_publishing[`@Property#publishing()`]). +
+
@@ -214,13 +215,13 @@ xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`] (deprecated) a
registered xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`]s (there may be more than one).
* At the end of all executions, details of all changed objects are published, again through the (internal)
-xref:rgsvc.adoc#_rgsvc_spi_PublisherServiceInternal[`PublisherServiceInternal`] to any registered `PublishingService`
+xref:rgfis.adoc#_rgfis_spi_PublisherServiceInternal[`PublisherServiceInternal`] to any registered `PublishingService`
or `PublisherService` implementations. Only domain objects specified to be published with
xref:rgant.adoc#_rgant-DomainObject_publishing[`@DomainObject#publishing()`] are published.
* Also at the end of all executions, details of all changed properties are passed to any registered
xref:rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`] by way of the (internal)
-xref:rgsvc.adoc#_rgsvc_spi_AuditingServiceInternal[`AuditingServiceInternal`] domain service.
+xref:rgfis.adoc#_rgfis_spi_AuditingServiceInternal[`AuditingServiceInternal`] domain service.
Implementations of xref:rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] can use the `Command#getMemento()`
method to obtain a XML equivalent of that `Command`, reified using the xref:rgcms.adoc#_rgcms_schema-cmd[`cmd.xsd`]
http://git-wip-us.apache.org/repos/asf/isis/blob/0e5a55ab/adocs/documentation/src/main/asciidoc/guides/_rgsvc_persistence-layer-internal-spi.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_persistence-layer-internal-spi.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_persistence-layer-internal-spi.adoc
deleted file mode 100644
index ce019a9..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_persistence-layer-internal-spi.adoc
+++ /dev/null
@@ -1,83 +0,0 @@
-[[_rgsvc_persistence-layer-internal-spi]]
-= Persistence Layer internal 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/
-
-
-
-These domain services are internal to the framework, controlling various aspects of the persistence layer.
-
-[WARNING]
-====
-We do not guarantee that link:http://semver.org[semantic versioning] will be honoured for these SPIs.
-====
-
-
-The table below summarizes the persistence layer internal SPIs defined by Apache Isis. It also lists their
-corresponding implementation, either a default implementation provided by Apache Isis itself, or provided by one of the
-(non-ASF) link:http://www.isisaddons.org[Isis Addons] modules.
-
-
-
-."Internal" SPI Services
-[cols="3,3,2,2a", options="header"]
-|===
-
-|SPI
-|Maven Module +
-Impl'n (g: a:)
-|Implementation
-|Notes
-
-
-
-|xref:rgsvc.adoc#_rgsvc_spi_AuditingServiceInternal[`o.a.i.c.` +
-`r.auditing.` +
-`AuditingServiceInternal`]
-|(`1.13.0-SNAPSHOT`) Co-ordinates between
-xref:rgsvc.adoc#_rgsvc_spi_ChangedObjectsServiceInternal[`ChangedObjectsServiceInternal`] and
-xref:rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`].
-|concrete class.
-|
-
-
-|xref:rgsvc.adoc#_rgsvc_spi_ChangedObjectsServiceInternal[`o.a.i.c.` +
-`r.changes.` +
-`ChangedObjectsServiceInternal`]
-|(`1.13.0-SNAPSHOT`) Request-scoped service holding objects enlisted into current transaction.
-|concrete class.
-|
-
-
-|xref:rgsvc.adoc#_rgsvc_spi_PublishingServiceInternal[`o.a.i.c.` +
-`m.s.publishing.` +
-`PublishingServiceInternal`]
-|(`1.13.0-SNAPSHOT`) Co-ordinates between
-xref:rgsvc.adoc#_rgsvc_spi_ChangedObjectsServiceInternal[`ChangedObjectsServiceInternal`] and
-xref:rgsvc.adoc#_rgsvc_api_MetricsService[`MetricsService`] and the SPI services,
-xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`] and (deprecated)
-xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`].
-|`PublishingService-` +
-`InternalDefault` +
-`o.a.i.c.r.publishing` +
-`isis-core-runtime`
-|
-
-
-
-|===
-
-Key:
-
-* `o.a.i` is an abbreviation for `org.apache.isis`
-* `o.ia.m` is an abbreviation for `org.isisaddons.module`
-* `o.a.i.c.m.s` is an abbreviation for `org.apache.isis.core.metamodel.services`
-* `o.a.i.c.r.s` is an abbreviation for `org.apache.isis.core.runtime.services`
-
-
-
-
-include::_rgsvc_spi_AuditingServiceInternal.adoc[leveloffset=+1]
-include::_rgsvc_spi_ChangedObjectsServiceInternal.adoc[leveloffset=+1]
-include::_rgsvc_spi_PublishingServiceInternal.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/0e5a55ab/adocs/documentation/src/main/asciidoc/guides/_rgsvc_presentation-layer-internal-spi.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_presentation-layer-internal-spi.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_presentation-layer-internal-spi.adoc
deleted file mode 100644
index 9e9d3c9..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_presentation-layer-internal-spi.adoc
+++ /dev/null
@@ -1,70 +0,0 @@
-[[_rgsvc_presentation-layer-internal-spi]]
-= Presentation Layer internal 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/
-
-
-
-These domain services are internal to the framework, controlling various aspects of the presentation layer.
-
-[WARNING]
-====
-We do not guarantee that link:http://semver.org[semantic versioning] will be honoured for these SPIs.
-====
-
-
-The table below summarizes the presentation layer internal SPIs defined by Apache Isis. It also lists their
-corresponding implementation, either a default implementation provided by Apache Isis itself, or provided by one of the
-(non-ASF) link:http://www.isisaddons.org[Isis Addons] modules.
-
-
-
-."Internal" SPI Services
-[cols="3,3,2,2a", options="header"]
-|===
-
-|SPI
-|Maven Module +
-Impl'n (g: a:)
-|Implementation
-|Notes
-
-
-|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` is an abbreviation for `org.apache.isis`
-* `o.ia.m` is an abbreviation for `org.isisaddons.module`
-* `o.a.i.c.m.s` is an abbreviation for `org.apache.isis.core.metamodel.services`
-* `o.a.i.c.r.s` is an abbreviation for `org.apache.isis.core.runtime.services`
-* `o.a.i.v.ro` is an abbreviation for `org.apache.isis.viewer.restfulobjects`
-
-
-
-
-include::_rgsvc_spi_ContentNegotiationService.adoc[leveloffset=+1]
-include::_rgsvc_spi_RepresentationService.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/0e5a55ab/adocs/documentation/src/main/asciidoc/guides/_rgsvc_presentation-layer-spi.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_presentation-layer-spi.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_presentation-layer-spi.adoc
index 8c8aedb..4c0ac73 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_presentation-layer-spi.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_presentation-layer-spi.adoc
@@ -183,9 +183,6 @@ Key:
-There are also a number of presentation layer SPIs that use internal classes. These can be found in the xref:rgsvc.adoc#_rgsvc_presentation-layer-internal-spi[next chapter].
-
-
include::_rgsvc_spi_ContentMappingService.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/0e5a55ab/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_AuditingServiceInternal.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_AuditingServiceInternal.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_AuditingServiceInternal.adoc
deleted file mode 100644
index ba7eaa0..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_AuditingServiceInternal.adoc
+++ /dev/null
@@ -1,46 +0,0 @@
-[[_rgsvc_spi_AuditingServiceInternal]]
-= `AuditingServiceInternal` (`1.13.0-SNAPSHOT`)
-: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 (internal) `AuditingServiceInternal` domain service (`1.13.0-SNAPSHOT`) acts as an internal facade to any
-configured xref:rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`]. It is responsible for obtaining the details
-of all changes to domain objects within an interaction, and then to call the configured `AuditingService` to actually
-create audit entries of those changes.
-
-The service is a no-op if there is no configured `AuditingService`.
-
-
-== SPI and Implementation
-
-The SPI of the service is:
-
-[source,java]
-----
-public class AuditingServiceInternal {
- public boolean canAudit(); // <1>
- public void audit(); // <2>
-}
-----
-<1> whether auditing is enabled; checks to see if any xref:rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`] has been configured.
-<2> uses the xref:rgsvc.adoc#_rgsvc_spi_ChangedObjectsServiceInternal[`ChangedObjectsServiceInternal`] to obtain details of the changed properties, then call the configured xref:rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`].
-
-The service implementation is `o.a.i.c.r.s.auditing.AuditingServiceInternal`.
-
-
-
-== 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 `AuditingServiceInternal` class is automatically registered (it is annotated with `@DomainService`)
-so no further configuration is required.
-
-
-== Related Classes
-
-The service delegates between the (internal) xref:rgsvc.adoc#_rgsvc_spi_ChangedObjectsServiceInternal[`ChangedObjectsServiceInternal`] domain service to the configured xref:rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`]. If no such `AuditingService` is configured, this service is in effect a no-op.
-
-The (internal) xref:rgsvc.adoc#_rgsvc_spi_PublishingServiceInternal[`PublishingServiceInternal`] performs a similar function for the xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`], also collating details of the changed objects from `ChangedObjectsServiceInternal`.
http://git-wip-us.apache.org/repos/asf/isis/blob/0e5a55ab/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_ChangedObjectsServiceInternal.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_ChangedObjectsServiceInternal.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_ChangedObjectsServiceInternal.adoc
deleted file mode 100644
index d701127..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_ChangedObjectsServiceInternal.adoc
+++ /dev/null
@@ -1,69 +0,0 @@
-[[_rgsvc_spi_ChangedObjectsServiceInternal]]
-= `ChangedObjectsServiceInternal` (`1.13.0-SNAPSHOT`)
-: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 `ChangedObjectsServiceInternal` class (`1.13.0-SNAPSHOT`) is an (internal) request-scoped domain service that is
-responsible for collecting the details of all changes to domain objects within an interaction. This is then used by
-various other (internal) domain services, notably
-xref:rgsvc.adoc#_rgsvc_spi_AuditingServiceInternal[`AuditingServiceInternal`] and
-xref:rgsvc.adoc#_rgsvc_spi_PublishingServiceInternal[`PublishingServiceInternal`].
-
-
-
-== SPI and Implementation
-
-The SPI of the service is:
-
-[source,java]
-----
-@RequestScoped
-public class ChangedObjectsServiceInternal {
- public void enlistCreated(final ObjectAdapter adapter); // <1>
- public void enlistUpdating(final ObjectAdapter adapter);
- public void enlistDeleting(final ObjectAdapter adapter);
-
- public boolean hasChangedAdapters(); // <2>
-
- public Map<ObjectAdapter, PublishedObject.ChangeKind> getChangeKindByEnlistedAdapter(); // <3>
- public int numberObjectsDirtied();
- public int numberObjectPropertiesModified();
-
- public Set<Map.Entry<AdapterAndProperty, PreAndPostValues>> getChangedObjectProperties(); // <4>
-
- public void clearChangedObjectProperties(); // <5>
-}
-----
-<1> Enlists an object that has just been created, updated or deleted, capturing the pre-modification values of the properties.
-<2> Used by the framework to determine whether to set the "persist hint" on the `Command` object (as per xref:rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`]).
-<3> Used by xref:rgsvc.adoc#_rgsvc_spi_PublishingServiceInternal[`PublishingServiceInternal`] to obtain details of and
-counters of all objects changed within the transaction.
-<4> Used by xref:rgsvc.adoc#_rgsvc_spi_AuditingServiceInternal[`AuditingServiceInternal`] to obtain all pairs of
-pre/post values of changed properties
-<5> Called by the framework to for clean up after auditing and publishing has completed.
-
-For enlisted objects, if just created, then a dummy value `"[NEW]"` is used for the pre-modification value; if just
-deleted, then a dummy value `"[DELETED]"` is used for the post-modification value. The post-modification values of
-properties are captured when the transaction commits.
-
-
-The service implementation is `o.a.i.c.r.s.changes.ChangedObjectsServiceInternal`.
-
-
-
-== 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 `ChangedObjectsServiceInternal` class is automatically registered (it is annotated with `@DomainService`)
-so no further configuration is required.
-
-
-
-== Related Classes
-
-Both the xref:rgsvc.adoc#_rgsvc_spi_AuditingServiceInternal[`AuditingServiceInternal`] and
-xref:rgsvc.adoc#_rgsvc_spi_PublishingServiceInternal[`PublishingServiceInternal`] (internal) domain services query
-this object.
http://git-wip-us.apache.org/repos/asf/isis/blob/0e5a55ab/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_CommandDtoServiceInternal.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_CommandDtoServiceInternal.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_CommandDtoServiceInternal.adoc
deleted file mode 100644
index c047752..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgsvc_spi_CommandDtoServiceInternal.adoc
+++ /dev/null
@@ -1,60 +0,0 @@
-[[_rgsvc_spi_CommandDtoServiceInternal]]
-= `CommandDtoServiceInternal` (`1.13.0-SNAPSHOT`)
-: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 `CommandDtoServiceInternal` (`1.13.0-SNAPSHOT`) is responsible for creating an memento of the current action
-invocation or property edit, to store in the `Command` object (from
-xref:rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`]). This memento is a JAXB DTO being an instance of the
-xref:rgcms.adoc#_rgcms_schema-cmd["cmd" schema], so can be reified so that its execution can be deferred until later,
-as a xref:rgsvc.adoc#_rgsvc_spi_BackgroundCommandService[background command].
-
-
-
-== SPI & Implementation
-
-The SPI of the service is:
-
-[source,java]
-----
-public interface CommandDtoServiceInternal {
- @Deprecated
- ActionInvocationMemento asActionInvocationMemento( // <1>
- Method m,
- Object domainObject, Object[] args);
- CommandDto asCommandDto( // <2>
- List<ObjectAdapter> targetAdapters,
- ObjectAction objectAction,
- ObjectAdapter[] argAdapters);
- CommandDto asCommandDto( // <3>
- final List<ObjectAdapter> targetAdapters,
- final OneToOneAssociation association,
- final ObjectAdapter valueAdapterOrNull);
- void addActionArgs( // <4>
- final ObjectAction objectAction,
- final ActionDto actionDto,
- final ObjectAdapter[] argAdapters);
- void addPropertyValue( // <5>
- final OneToOneAssociation property,
- final PropertyDto propertyDto,
- final ObjectAdapter valueAdapter);
-}
-----
-<1> Note that this method (more precisely, `ActionInvocationMemento`) does __not__ support mixins.
-<2> Returns a JAXB DTO being an instance of the xref:rgcms.adoc#_rgcms_schema-cmd["cmd" schema] (hence convertible to
-XML) that represents the __intention__ to invoke an action on a target object (or possibly many targets, for
-bulk actions). If an action, it can also be either mixin action or a contributed action.
-<3> Returns a JAXB DTO that represents the intention to edit (set or clear) a property on a target (or possibly many
-targets, for symmetry with actions).
-<4> add the arguments of an action to an `ActionDto`. This is used when the command is actually executed (per xref:rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`]) to populate the parameters of the equivalent `ActionInvocationDto`.
-<5> add the new value argument of a property to a `PropertyDto`. This is used when the command is actually executed (per xref:rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`]) to set the the new value of the equivalent `PropertyEditDto`.
-
-
-The SPI is implemented by `o.a.i.c.r.s.command.CommandDtoServiceInternalServiceDefault`.
-
-
-== Related Services
-
-The design of this service is similar to that of xref:rgsvc.adoc#_rgsvc_spi_InteractionDtoServiceInternal[`InteractionDtoServiceInternal`], used to create the `MemberExecutionDto` (from the xref:rgcms.adoc#_rgcms_schema-ixn["ixn" schema]).