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:09 UTC
[33/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/_rgcms_methods_reserved_validate.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_validate.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_validate.adoc
deleted file mode 100644
index a03ec54..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_methods_reserved_validate.adoc
+++ /dev/null
@@ -1,27 +0,0 @@
-[[_rgcms_methods_reserved_validate]]
-= `validate()`
-: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 `validate()` method is used to specify that invariants pertaining to an object's state are enforced.
-
-
-[WARNING]
-====
-(As of 1.8.0) there are known limitations with this functionality. Invariants are enforced when an object is initially created and when it is edited, however invariants are currently _not_ enforced if an action is invoked.
-====
-
-
-The signature of the method is:
-
-[source,java]
-----
-public String validate() { ... }
-----
-
-where the returned string is the reason that the invocation is vetoed.
-
-Note that Apache Isis' xref:ugbtb.adoc#_ugbtb_i18n[i18n support] extends this so that the returned reason can also be internationalized.
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-aim.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-aim.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-aim.adoc
deleted file mode 100644
index 7aeef8f..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-aim.adoc
+++ /dev/null
@@ -1,107 +0,0 @@
-[[_rgcms_schema-aim]]
-= Action Invocation Memento
-: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 "aim" schema defines the serialized form (or memento) of an action invocation.
-
-[WARNING]
-====
-This schema has been removed in `1.13.0`, replaced with xref:rgcms.adoc#_rgcms_schema-ixn[ixn.xsd] (for action
-invocations/property edits) and with xref:rgcms.adoc#_rgcms_schema-cmd[cmd.xsd] (commands, ie the __intention__ to
-invoke an action/edit a property).
-
-The remaining content on this page describes how `CommandContext` works up to v1.12.x. However, as of `1.13.0` the `CommandContext` uses its own `cmd.xsd` schema).
-====
-
-Action invocations are captured (in memory rather than in serialized form) when the end-user invokes the action
-"through" the UI, by way of the xref:rgsvc.adoc#_rgsvc_api_CommandContext[CommandContext] service. Using the
-`ActionInvocationMementoDtoUtils` utility class, a service can instantiate `ActionInvocationMementoDto` which can then
-be serialized to/from using the same `ActionInvocationMementoDtoUtils` class.
-
-[source,xml]
-----
-<?xml version="1.0" encoding="UTF-8"?>
-<xs:schema targetNamespace="http://isis.apache.org/schema/aim" <!--1-->
- elementFormDefault="qualified"
- xmlns:xs="http://www.w3.org/2001/XMLSchema"
- xmlns="http://isis.apache.org/schema/aim"
- xmlns:common="http://isis.apache.org/schema/common">
-
- <xs:import namespace="http://isis.apache.org/schema/common" <!--2-->
- schemaLocation="http://isis.apache.org/schema/common/common-1.0.xsd"/>
-
- <xs:element name="actionInvocationMementoDto"> <!--3-->
- <xs:complexType>
- <xs:sequence>
- <xs:element name="metadata">
- <xs:complexType>
- <xs:sequence>
- <xs:element name="transactionId" type="xs:string"/> <!--4-->
- <xs:element name="sequence" type="xs:int"/> <!--5-->
- <xs:element name="timestamp" type="xs:dateTime"/> <!--6-->
- <xs:element name="target" type="common:oidDto"/> <!--7-->
- <xs:element name="targetClass" type="xs:string"/> <!--8-->
- <xs:element name="targetAction" type="xs:string"/> <!--9-->
- <xs:element name="actionIdentifier" type="xs:string"/> <!--10-->
- <xs:element name="user" type="xs:string"/> <!--11-->
- <xs:element name="title" type="xs:string"/> <!--12-->
- </xs:sequence>
- </xs:complexType>
- </xs:element>
- <xs:element name="payload">
- <xs:complexType>
- <xs:sequence>
- <xs:element name="parameters"> <!--13-->
- <xs:complexType>
- <xs:sequence maxOccurs="unbounded">
- <xs:element name="param" type="paramDto"/>
- </xs:sequence>
- <xs:attribute name="num" use="required" type="xs:int"/>
- </xs:complexType>
- </xs:element>
- <xs:element name="return" type="common:valueDto" <!--14-->
- minOccurs="0" maxOccurs="1"/>
- </xs:sequence>
- </xs:complexType>
- </xs:element>
- </xs:sequence>
- </xs:complexType>
- </xs:element>
-
- <xs:complexType name="paramDto"> <!--15-->
- <xs:sequence>
- <xs:element name="value" type="common:valueDto"/> <!--16-->
- </xs:sequence>
- <xs:attribute name="parameterName" use="required" type="xs:string"/> <!--17-->
- <xs:attribute name="parameterType" use="required" type="common:valueType"/>
- <xs:attribute name="null" use="optional" type="xs:boolean"/>
- </xs:complexType>
-</xs:schema>
-----
-<1> the aim schema has a namespace URI of "http://isis.apache.org/schema/aim". Although URIs are not the same as URLs, you will find that the schemas are also downloadable from this location.
-<2> reuses the xref:rgcms.adoc#_rgcms_schema-common[common] schema
-<3> definition of the `actionInvocationMementoDto` complex type. This consists of metadata (the transaction identifier, the target object, the initiating user) and the payload (the action parameter/arguments, the return value if known).
-<4> the unique transaction Id (a guid) allocated by the framework for each and every transaction
-<5> a sequence number within the transaction. It is possible for there to be more than one action invocation to be
-<6> when the action was invoked
-<7> target object, as an OID (using `oidDto` from the xref:rgcms.adoc#_rgcms_schema-common[common] schema)
-<8> fully qualified class name of the target object, for information only
-<9> name of the action, for information only
-<10> Javadoc style unique identifier for the action.
-<11> User that invoked the action
-<12> title of the target object, for information only
-<13> Collection of parameter/arguments, defined in terms of the `paramDto` complex type (discussed just below)
-<14> The return value of the action, if known (and not void)
-<15> The `paramDto` defines both an action parameter and its corresponding argument values
-<16> The value of the parameter, in other words an argument value
-<17> Metadata about the parameter itself: its name, type, optionality.
-
-[NOTE]
-====
-As of `1.11.0` through `1.12.2` this schema is not used directly by the framework; in particular
-`Command#setMemento(...)` sets a similar but less formal XML structure. This may change in the future.
-====
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-chg.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-chg.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-chg.adoc
deleted file mode 100644
index 17f3ac1..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-chg.adoc
+++ /dev/null
@@ -1,97 +0,0 @@
-[[_rgcms_schema-chg]]
-= Changes
-: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 changes ("chg") schema defines the serialized form identifying which objects have been created,
-updated or deleted as the result of invoking an action or editing a property. It also captures a number of other
-metrics counts (number of objects loaded, number of object properties modified), useful for profiling.
-
-An instance of the DTO (corresponding to this schema) is used within the
-xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`] SPI, identifying changed objects that are to be
-published (as per xref:rgant.adoc#_rgant_DomainObject_publishing[`@DomainObject#publishing()`] or equivalent).
-
-
-== `changesDto`
-
-The `changesDto` root element is defined as:
-
-[source,xml]
-----
-<xs:schema targetNamespace="http://isis.apache.org/schema/chg" <!--1-->
- elementFormDefault="qualified"
- xmlns:xs="http://www.w3.org/2001/XMLSchema"
- xmlns="http://isis.apache.org/schema/chg"
- xmlns:com="http://isis.apache.org/schema/common">
-
- <xs:import namespace="http://isis.apache.org/schema/common" <!--2-->
- schemaLocation="../common/common-1.0.xsd"/>
-
- <xs:element name="changesDto"> <!--3-->
- <xs:complexType>
- <xs:sequence>
- <xs:element name="majorVersion" type="xs:string" <!--4-->
- minOccurs="0" maxOccurs="1" default="1"/>
- <xs:element name="minorVersion" type="xs:string"
- minOccurs="0" maxOccurs="1" default="0"/>
-
- <xs:element name="transactionId" type="xs:string"/> <!--5-->
- <xs:element name="sequence" type="xs:int"/> <!--6-->
- <xs:element name="completedAt" type="xs:dateTime" minOccurs="0" maxOccurs="1"/> <!--7-->
- <xs:element name="user" type="xs:string"/> <!--8-->
- <xs:element name="objects" type="objectsDto"/> <!--9-->
- </xs:sequence>
- </xs:complexType>
- </xs:element>
- ...
-</xs:schema>
-----
-<1> the changes schema has a namespace URI of "http://isis.apache.org/schema/chg". Although URIs are not the same as
-URLs, you will find that the schemas are also downloadable from this location.
-<2> uses complex types defined in the xref:rgcms.adoc#_rgcms_schema_common["common" schema].
-<3> definition of the `changesDto` root element. The corresponding XML will use this as its top-level element.
-<4> each instance of this schema indicates the version of the schema it is compatible with (following semantic versioning)
-<5> unique identifier for the transaction in which this interaction is being executed. The transaction Id is used to
-correlate back to the xref:rgcms.adoc#_rgcms_schema_command[command] that represented the intention to perform this
-execution, as well as to the xref:rgcms.adoc#_rgcms_schema_interaction[interaction] that executes said command.
-<6> uniquely identifies this set of changes within the interaction. Can be combined with `transactionId` to create a
-unique identifier (across all other changed object events and also any interaction executions) of this particular set
-of changed objects.
-<7> the date/time that the transaction that dirtied this objects completed
-<8> the user that executed the (top-level) action invocation/property edit.
-<9> identifies the objects that have changed.
-
-The `ChangesDto` DTO corresponding to the `changesDto` root element can be marshalled to/from XML using the
-`ChangesDtoUtils` class.
-
-
-
-== `objectsDto`
-
-The `objectsDto` complex type actually identifies the objects created, updated or deleted. It also captures additional
-metrics counters:
-
-[source,xml]
-----
-<xs:schema targetNamespace="http://isis.apache.org/schema/chg" ... >
- ...
- <xs:complexType name="objectsDto">
- <xs:sequence>
- <xs:element name="loaded" type="xs:int"/> <!--1-->
- <xs:element name="created" type="com:oidsDto"/> <!--2-->
- <xs:element name="updated" type="com:oidsDto"/>
- <xs:element name="deleted" type="com:oidsDto"/>
- <xs:element name="propertiesModified" type="xs:int"/> <!--3-->
- </xs:sequence>
- </xs:complexType>
-</xs:schema>
-----
-<1> the number of objects that were loaded, in total, by the interaction.
-<2> the identities of the objects that were, respectively, created, updated or deleted within the transaction.
-<3> the number of objects' properties changed, in total, by the interaction.
-
-The xref:rgcms.adoc#_rgcms_schema_ixn[interaction] schema also provides metrics on the number of objects loaded/changed,
-but is more granular, each figure relating to a single (sub-)execution within an interaction.
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-cmd.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-cmd.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-cmd.adoc
deleted file mode 100644
index 6eb3e63..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-cmd.adoc
+++ /dev/null
@@ -1,150 +0,0 @@
-[[_rgcms_schema-cmd]]
-= Command
-: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 command ("cmd") schema defines the serialized form of the __intention__ to invoke an action or to
-edit a property.
-
-[NOTE]
-====
-Mixin actions are represented as regular actions on the mixed-in object. In other words, the fact that the actual
-implementation of the action is defined by a mixin is an implementation detail only.
-====
-
-[[__rgcms_schema-cmd_commandDto]]
-== `commandDto`
-
-The `commandDto` root element is defined as:
-
-[source,xml]
-----
-<xs:schema targetNamespace="http://isis.apache.org/schema/cmd" <!--1-->
- elementFormDefault="qualified"
- xmlns:xs="http://www.w3.org/2001/XMLSchema"
- xmlns="http://isis.apache.org/schema/cmd"
- xmlns:com="http://isis.apache.org/schema/common">
-
- <xs:import namespace="http://isis.apache.org/schema/common" <!--2-->
- schemaLocation="../common/common-1.0.xsd"/>
-
- <xs:element name="commandDto"> <!--3-->
- <xs:complexType>
- <xs:sequence>
- <xs:element name="majorVersion" type="xs:string" <!--4-->
- minOccurs="1" maxOccurs="1" default="1"/>
- <xs:element name="minorVersion" type="xs:string"
- minOccurs="1" maxOccurs="1" default="1"/>
-
- <xs:element name="transactionId" type="xs:string"/> <!--5-->
- <xs:element name="user" type="xs:string"/> <!--6-->
- <xs:element name="targets" type="com:oidsDto"/> <!--7-->
- <xs:element name="member" type="memberDto"/> <!--8-->
- </xs:sequence>
- </xs:complexType>
- </xs:element>
- ...
-</xs:schema>
-----
-<1> the command schema has a namespace URI of "http://isis.apache.org/schema/cmd". Although URIs are not the same as
-URLs, you will find that the schemas are also downloadable from this location.
-<2> uses complex types defined in the xref:rgcms.adoc#_rgcms_schema_common["common" schema].
-<3> definition of the `commandDto` root element. The corresponding XML will use this as its top-level element.
-<4> each instance of this schema indicates the version of the schema it is compatible with (following semantic versioning)
-<5> unique identifier for the transaction in which this command is created. The transaction Id is used to correlate
-to the xref:rgcms.adoc#_rgcms_schema_interaction[interaction] that executes the command, and to any
-xref:rgcms.adoc#_rgcms_schema_changes[changes] to domain objects occurring as a side-effect of that interaction.
-<6> the name of the user who created the command (whose intention it is to invoke the action/edit the property).
-<7> the target object (or objects) to be invoked. As of `1.13.0`, a bulk action will create multiple commands,
-each with only a single target, but a future version of the framework may also support a single bulk command against
-this multiple targets (ie all-or-nothing).
-<8> the `memberDto`, defined below, the captures the action/property and arguments/new value.
-
-The `CommandDto` DTO corresponding to the `commandDto` root element can be marshalled to/from XML using the
-`CommandDtoUtils` class.
-
-
-[[__rgcms_schema-cmd_memberDto]]
-== `memberDto` and subtypes
-
-The `memberDto` complex type is an abstract type representing the intention to either invoke an action or to edit a
-property. The `actionDto` and `propertyDto` are the concrete subtypes:
-
-
-[source,xml]
-----
-<xs:schema targetNamespace="http://isis.apache.org/schema/cmd" ...>
- ...
- <xs:complexType name="memberDto" abstract="true"> <!--1-->
- <xs:sequence>
- <xs:element name="memberIdentifier" type="xs:string"/>
- </xs:sequence>
- <xs:attribute name="interactionType" type="com:interactionType"/> <!--2-->
- </xs:complexType>
-
- <xs:complexType name="actionDto"> <!--3-->
- <xs:complexContent>
- <xs:extension base="memberDto">
- <xs:sequence>
- <xs:element name="parameters" type="paramsDto"/>
- </xs:sequence>
- </xs:extension>
- </xs:complexContent>
- </xs:complexType>
-
- <xs:complexType name="propertyDto"> <!--4-->
- <xs:complexContent>
- <xs:extension base="memberDto">
- <xs:sequence>
- <xs:element name="newValue" type="com:valueWithTypeDto"/>
- </xs:sequence>
- </xs:extension>
- </xs:complexContent>
- </xs:complexType>
-</xs:schema>
-----
-<1> the `memberDto` is an abstract type. Its primary responsibility is simply to identify the member (action or
-property).
-<2> the `interactionType` attribute indicates whether the member is an action or a property.
-<3> the `actionDto` complex type captures the set of parameters (also including the argument values) with which to
-invoke the action. The `paramsDto` type is defined xref:rgcms.adoc#__rgcms_schema-cmd_ancillary[below].
-<4> the `propertyDto` complex type captures the new value (possibly `null`) to set the property to.
-
-
-Note also that there is a corresponding xref:rgcms.adoc#__rgcms_schema-ixn_memberExecutionDto[`memberExecutionDto`]
-complex type in the "ixn" schema that is for the actual execution (capturing metrics about its execution and also the
-return value if an action invocation).
-
-
-
-[[__rgcms_schema-cmd_ancillary]]
-== Ancillary types
-
-The schema also defines a small number of supporting types:
-
-[source,xml]
-----
-<xs:schema targetNamespace="http://isis.apache.org/schema/cmd" ...>
- ...
- <xs:complexType name="paramsDto"> <!--1-->
- <xs:sequence minOccurs="0" maxOccurs="unbounded">
- <xs:element name="parameter" type="paramDto"/>
- </xs:sequence>
- </xs:complexType>
-
- <xs:complexType name="paramDto"> <!--2-->
- <xs:complexContent>
- <xs:extension base="com:valueWithTypeDto">
- <xs:attribute name="name" use="required" type="xs:string"/>
- </xs:extension>
- </xs:complexContent>
- </xs:complexType>
-</xs:schema>
-----
-<1> the `paramsDto` is simply the list of parameter/arguments.
-<2> the `paramDto` complex type essentially combines a parameter with its corresponding argument: a named value that
-has a type. It extends the `valueWithTypeDto` complex type taken from the
-xref:rgcms.adoc#_rgcms_schema-common["common"] schema.
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-common.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-common.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-common.adoc
deleted file mode 100644
index 369f3e8..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-common.adoc
+++ /dev/null
@@ -1,191 +0,0 @@
-[[_rgcms_schema-common]]
-= Common Schema
-: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 "common" schema defines a number of complex types that are used by other higher-level schemas.
-
-
-[[__rgcms_schema-common_oidDto]]
-== `oidDto`
-
-The `oidDto` complex type captures an object's type and its identifier. This is basically a formal XML equivalent to
-the `Bookmark` object obtained from the xref:rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`].
-
-Although simple, this is an enormously powerful concept, in that it represents a URI to any domain object managed by
-a given Apache Isis application. With it, we have the ability to lookup any arbitrary object. Further discussion and
-examples can be found xref:ugfun.adoc#__ugfun_core-concepts_building-blocks_oid[here].
-
-The `oidDto` complex type is defined as:
-
-[source,xml]
-----
-<xs:schema targetNamespace="http://isis.apache.org/schema/common" <!--1-->
- elementFormDefault="qualified"
- xmlns="http://isis.apache.org/schema/common"
- xmlns:xs="http://www.w3.org/2001/XMLSchema">
-
- <xs:complexType name="oidDto"> <!--2-->
- <xs:sequence/>
- <xs:attribute name="type" type="xs:string"/> <!--3-->
- <xs:attribute name="id" type="xs:string"/> <!--4-->
- <xs:attribute name="objectState" type="bookmarkObjectState"/>
- </xs:complexType>
-
- <xs:simpleType name="bookmarkObjectState"> <!--5-->
- <xs:restriction base="xs:string">
- <xs:enumeration value="persistent"/>
- <xs:enumeration value="transient"/>
- <xs:enumeration value="viewModel"/>
- </xs:restriction>
- </xs:simpleType>
-
- <xs:complexType name="oidsDto"> <!--6-->
- <xs:sequence>
- <xs:element name="oid" type="oidDto" minOccurs="1" maxOccurs="unbounded"/>
- </xs:sequence>
- </xs:complexType>
- ...
-</xs:schema>
-----
-<1> the common schema has a namespace URI of "http://isis.apache.org/schema/common". Although URIs are not the same as
-URLs, you will find that the schemas are also downloadable from this location.
-<2> the `oidDto` complex type defines the unique identifier for any domain object: its type, and an identifier. The
-`objectState` attribute can usually be omitted (indicating a persistent object)
-<3> the object type, corresponding to either the
-xref:rgant.adoc#_rgant-DomainObject_objectType[`@DomainObject#objectType()`] attribute, or to the (JDO)
-xref:rgant.adoc#_rgant-PersistenceCapable[`@PersistenceCapable`] annotation (`schema` and/or `table`
-attributes), or to the (JDO) xref:rgant.adoc#_rgant-Discriminator[`@Discriminator`] annotation. If none
-is specified, then the fully qualified class name will be used.
-<4> the object identifier (aka primary key), converted to string form.
-<5> the `bookmarkObjectState` enumerates the possible persistence states of the referenced object. In previous versions
-of the schema the attribute was defaulted to "persistent"; the "persistent" state is assumed
-if the attribute is omitted.
-<6> Models a list of OIDs. This is used by the xref:rgcms.adoc#_rgcms_schema_cmd["cmd" schema] to represent the
-intention to perform a bulk actions (against a number of selected objects).
-
-In previous versions of the schema the object type and object identifers of `oidDto` were
-modelled as an element rather than an attribute. The element form can still be used, but is deprecated.
-
-The `oidDto` complex type is used in a number of places by the framework:
-
-* first, as a means of serializing JAXB view model/DTOs (annotated with
-xref:rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`]), that reference domain entities. +
-+
-These references are serialized instead into OIDs
-
-* second, as references to the target of a command representing the _intention_ to invoke an action or edit a property,
-as described by the xref:rgcms.adoc#_rgcms_schema-cmd["cmd" (command)] schema. +
-+
-They are also used to represent references to any action arguments/properties that take domain object entities/view models.
-
-* third, as references to the target of an interaction capturing the actual execution of an action invocation or
-property edit, as described by the xref:rgcms.adoc#_rgcms_schema-ixn["ixn" (interaction)] schema.
-
-
-[[__rgcms_schema-common_valueDto]]
-== `valueDto` etc
-
-The common schema also defines two types representing values: the `valueDto` complex type, the `valueType` simple type
-and the `valueWithTypeDto` complex type:
-
-[source,xml]
-----
-<xs:schema targetNamespace="http://isis.apache.org/schema/common" ... >
- ...
- <xs:complexType name="valueDto"> <!--1-->
- <xs:choice minOccurs="0" maxOccurs="1">
- <xs:element name="string" type="xs:string"/>
- <xs:element name="byte" type="xs:byte"/>
- <xs:element name="short" type="xs:short"/>
- ...
- <xs:element name="timestamp" type="xs:dateTime"/>
- <xs:element name="enum" type="enumDto"/>
- <xs:element name="reference" type="oidDto"/>
- </xs:choice>
- </xs:complexType>
-
- <xs:simpleType name="valueType"> <!--2-->
- <xs:restriction base="xs:string">
- <xs:enumeration value="string"/>
- <xs:enumeration value="byte"/>
- <xs:enumeration value="short"/>
- ...
- <xs:enumeration value="enum"/>
- <xs:enumeration value="reference"/>
- <xs:enumeration value="void"/> <!--3-->
- </xs:restriction>
- </xs:simpleType>
-
- <xs:complexType name="valueWithTypeDto"> <--4-->
- <xs:complexContent>
- <xs:extension base="valueDto">
- <xs:attribute name="type" use="required" type="valueType"/>
- <xs:attribute name="null" use="optional" type="xs:boolean"/>
- </xs:extension>
- </xs:complexContent>
- </xs:complexType>
- ...
-</xs:schema>
-----
-<1> Intended to hold any valid value, eg of an argument to an action or a new value of a property.
-<2> Enumerates the full set of types understood by the framework; note that these also include references to entities
-or view models, and to enums.
-<3> Not valid to be used as the parameter type of an action; can be used as its return type.
-<4> Inherits from `valueDto`, capturing both a value and its corresponding type. Used for the return value of action
-invocations, and for the new value in property edits.
-
-
-These type definitions are just building blocks, also used within the
-xref:rgcms.adoc#_rgcms_schema-aim[action iInvocation memento] schema. The first, `valueDto` is The second, `valueType`, enumerates the different types of vales, eg of a
-formal parameter to an action.
-
-
-
-[[__rgcms_schema-common_ancillary]]
-== Ancillary types
-
-The common schema also defines a number of ancillary types, used either by the common schema itself (see above) or by
-the xref:rgcms.adoc#_rgcms_schema_cmd["cmd"] and xref:rgcms.adoc#_rgcms_schema_ixn["ixn"] schemas.
-
-[source,xml]
-----
-<xs:schema targetNamespace="http://isis.apache.org/schema/common" ... >
- ...
- <xs:complexType name="enumDto"> <!--1-->
- <xs:sequence>
- <xs:element name="enumType" type="xs:string"/>
- <xs:element name="enumName" type="xs:string"/>
- </xs:sequence>
- </xs:complexType>
-
- <xs:complexType name="periodDto"> <!--2-->
- <xs:sequence>
- <xs:element name="startedAt" type="xs:dateTime"/>
- <xs:element name="completedAt" type="xs:dateTime"
- minOccurs="0" maxOccurs="1"/>
- </xs:sequence>
- </xs:complexType>
-
- <xs:complexType name="differenceDto"> <!--3-->
- <xs:sequence/>
- <xs:attribute name="before" type="xs:int"/>
- <xs:attribute name="after" type="xs:int"/>
- </xs:complexType>
-
- <xs:simpleType name="interactionType"> <!--4-->
- <xs:restriction base="xs:string">
- <xs:enumeration value="action_invocation" />
- <xs:enumeration value="property_edit" />
- </xs:restriction>
- </xs:simpleType>
-</xs:schema>
-----
-<1> Models an instance member of an enum (eg `Color.RED`).
-<2> Captures a period of time, eg for capturing metrics/timings.
-<3> Captures a pair of numbers representing a difference. Used for example to capture metrics (number objects modified before and after).
-<4> Whether this command/interaction with a member is invoking an action, or editing a property. Used by both the
-xref:rgcms.adoc#_rgcms_schema_cmd["cmd"] and xref:rgcms.adoc#_rgcms_schema_ixn["ixn"] schemas.
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-ixn.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-ixn.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-ixn.adoc
deleted file mode 100644
index 286e5f2..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema-ixn.adoc
+++ /dev/null
@@ -1,208 +0,0 @@
-[[_rgcms_schema-ixn]]
-= Interaction Execution
-: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 interaction ("ixn") schema defines the serialized form of an action invocation or a property
-edit. In fact, it actually defines a call-graph of such executions for those cases where the
-xref:rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`] is used to execute sub-actions/property edits.
-
-Each execution identifies the target object, the member to invoke, and the arguments. It also captures metrics about
-the execution, and the result of the execution (eg return value of an action invocation).
-
-[NOTE]
-====
-Mixin actions are represented as regular actions on the mixed-in object. In other words, the fact that the actual
-implementation of the action is defined by a mixin is an implementation detail only.
-====
-
-
-[[__rgcms_schema-ixn_interactionDto]]
-== `interactionDto`
-
-The `interactionDto` root element is defined as:
-
-[source,xml]
-----
-<xs:schema targetNamespace="http://isis.apache.org/schema/ixn" <!--1-->
- elementFormDefault="qualified"
- xmlns:xs="http://www.w3.org/2001/XMLSchema"
- xmlns="http://isis.apache.org/schema/ixn"
- xmlns:cmd="http://isis.apache.org/schema/cmd"
- xmlns:com="http://isis.apache.org/schema/common">
-
- <xs:import namespace="http://isis.apache.org/schema/common" <!--2-->
- schemaLocation="../common/common-1.0.xsd"/>
- <xs:import namespace="http://isis.apache.org/schema/cmd"
- schemaLocation="../cmd/cmd-1.0.xsd"/>
-
- <xs:element name="interactionDto"> <!--3-->
- <xs:complexType>
- <xs:sequence>
- <xs:element name="majorVersion" type="xs:string" <!--4-->
- minOccurs="0" maxOccurs="1" default="1"/>
- <xs:element name="minorVersion" type="xs:string"
- minOccurs="0" maxOccurs="1" default="0"/>
-
- <xs:element name="transactionId" type="xs:string"/> <!--5-->
- <xs:element name="execution" type="memberExecutionDto"/> <!--6-->
- </xs:sequence>
- </xs:complexType>
- </xs:element>
-
-</xs:schema>
-----
-<1> the interaction schema has a namespace URI of "http://isis.apache.org/schema/ixn". Although URIs are not the same as
-URLs, you will find that the schemas are also downloadable from this location.
-<2> uses complex types defined in the xref:rgcms.adoc#_rgcms_schema_common["common" schema] and also the
-xref:rgcms.adoc#_rgcms_schema_cmd["cmd" schema]
-<3> definition of the `interactionDto` root element. The corresponding XML will use this as its top-level element.
-<4> each instance of this schema indicates the version of the schema it is compatible with (following semantic versioning)
-<5> unique identifier for the transaction in which this interaction is being executed. The transaction Id is used to
-correlate back to the xref:rgcms.adoc#_rgcms_schema_command[command] that represented the intention to perform this
-execution, as well as to any xref:rgcms.adoc#_rgcms_schema_changes[changes] to domain objects that occur as a side-effect
-of the interaction.
-<6> the top-level `memberExecutionDto`, defined below, either an action invocation or edit of a property.
-
-The `InteractionDto` DTO corresponding to the `interactionDto` root element can be marshalled to/from XML using the
-`InteractionDtoUtils` class.
-
-
-
-[[__rgcms_schema-ixn_memberExecutionDto]]
-== `memberExecutionDto`
-
-The `memberExecutionDto` complex type is an abstract type representing either the invocation an action or the editing
-of a property. It corresponds to the xref:rgcms.adoc#__rgcms_schema-cmd_memberDto[`memberDto`] of the "cmd" schema;
-some elements are copied directly:
-
-[source,xml]
-----
-<xs:schema targetNamespace="http://isis.apache.org/schema/ixn" ... >
- ...
- <xs:complexType name="memberExecutionDto" abstract="true"> <!--1-->
- <xs:sequence>
- <xs:element name="sequence" type="xs:int"/> <!--2-->
- <xs:element name="target" type="com:oidDto"/> <!--3-->
- <xs:element name="memberIdentifier" type="xs:string"/> <!--4-->
- <xs:element name="user" type="xs:string"/> <!--5-->
- <xs:element name="title" type="xs:string"/> <!--6-->
- <xs:element name="metrics" type="metricsDto"/> <!--7-->
- <xs:element name="threw" type="exceptionDto" <!--8-->
- minOccurs="0" maxOccurs="1"/>
- <xs:element name="childExecutions" minOccurs="0" maxOccurs="1"> <!--9-->
- <xs:complexType>
- <xs:sequence>
- <xs:element name="execution" type="memberExecutionDto"
- minOccurs="0" maxOccurs="unbounded"/>
- </xs:sequence>
- </xs:complexType>
- </xs:element>
- </xs:sequence>
- <xs:attribute name="interactionType" type="com:interactionType"/> <!--10-->
- </xs:complexType>
- ...
-</xs:schema>
-----
-<1> the `memberExecutionDto` is an abstract type
-<2> uniquely identifies this execution within the transaction. Can be combined with `transactionId` to create a unique
-identifier (across all other interaction executions and also changed objects events) of this particular interaction
-execution.
-<3> the target object, corresponding to one of the elements of the `targets` element of the xref:rgcms.adoc#__rgcms_schema-cmd_memberDto[`memberDto`]
-<4> the member identifier; corresponds to `memberIdentifier` of the `member` element of the xref:rgcms.adoc#__rgcms_schema-cmd_memberDto[`memberDto`]
-<5> the user executing the action invocation/property edit; corresponds to the `user` element of the xref:rgcms.adoc#__rgcms_schema-cmd_memberDto[`memberDto`]
-<6> the current "human-friendly" title of the target object
-<7> the set of metrics captured for this execution, of type `metricsDto` defined xref:rgcms.adoc#__rgcms_schema-ixn_ancillary[below].
-<8> if the action invocation/property edit threw an exception, then this is captured here.
-<9> if any sub-actions or sub-edits were performed via the xref:rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`], then these are captured in the `childExecutions` element.
-<10> the `interactionType` attribute indicates whether the member is an action or a property (similar attribute exists for the "cmd" schema).
-
-
-The `actionInvocationDto` and `propertyEditDto` are the concrete subtypes:
-
-[source,xml]
-----
-<xs:schema targetNamespace="http://isis.apache.org/schema/ixn" ... >
- ...
- <xs:complexType name="actionInvocationDto"> <!--1-->
- <xs:complexContent>
- <xs:extension base="memberExecutionDto">
- <xs:sequence>
- <xs:element name="parameters" type="cmd:paramsDto"/> <!--2-->
- <xs:element name="returned" <!--3-->
- type="com:valueWithTypeDto"
- minOccurs="0" maxOccurs="1"/>
- </xs:sequence>
- </xs:extension>
- </xs:complexContent>
- </xs:complexType>
- ...
- <xs:complexType name="propertyEditDto"> <!--4-->
- <xs:complexContent>
- <xs:extension base="memberExecutionDto">
- <xs:sequence>
- <xs:element name="newValue" <!--5-->
- type="com:valueWithTypeDto"/>
- </xs:sequence>
- </xs:extension>
- </xs:complexContent>
- </xs:complexType>
- ...
-</xs:schema>
-----
-<1> the `actionInvocationDto` inherits from `memberExecutionDto`. It corresponds to the similar
-xref:rgcms.adoc#__rgcms_schema-cmd_memberDto[`actionDto`] complex type of the "cmd" schema
-<2> the `parameters` element captures the parameter and argument values; for the top-level execution it is a direct
-copy of the corresponding `parameters` element of the `actionDto` complex type of the "cmd" schema.
-<3> the `returned` element captures the returned value (if not void). It is not valid for both this element and the
-inherited `threw` element to both be populated.
-<4> the `propertyEditDto` inherits from `memberExecutionDto`. It corresponds to the similar
-xref:rgcms.adoc#__rgcms_schema-cmd_memberDto[`propertyDto`] complex type of the "cmd" schema
-<5> the `newValue` element captures the new value; for the top-level execution it is a direct
-copy of the corresponding `newValue` element of the `propertyDto` complex type of the "cmd" schema.
-
-
-[[__rgcms_schema-ixn_ancillary]]
-== Ancillary types
-
-The schema also defines a small number of supporting types:
-
-[source,xml]
-----
-<xs:schema targetNamespace="http://isis.apache.org/schema/ixn" ... >
- ...
- <xs:complexType name="metricsDto"> <!--1-->
- <xs:sequence>
- <xs:element name="timings" type="com:periodDto"/>
- <xs:element name="objectCounts" type="objectCountsDto"/>
- </xs:sequence>
- </xs:complexType>
-
- <xs:complexType name="objectCountsDto"> <!--2-->
- <xs:sequence>
- <xs:element name="loaded" type="com:differenceDto"/>
- <xs:element name="dirtied" type="com:differenceDto"/>
- </xs:sequence>
- </xs:complexType>
-
- <xs:complexType name="exceptionDto"/> <!--3-->
- <xs:sequence>
- <xs:element name="message" type="xs:string"/>
- <xs:element name="stackTrace" type="xs:string"/>
- <xs:element name="causedBy" type="exceptionDto" minOccurs="0" maxOccurs="1"/>
- </xs:sequence>
- </xs:complexType>
-</xs:schema>
-----
-<1> the `metricsDto` captures the time to perform an execution, and also the differences in various object counts.
-<2> the `objectCountsDto` complex type is the set of before/after differences, one for each execution; the framework
-tracks number of objects loaded (read from) the database and the number of objects dirtied (will need to be saved back
-to the database). Together these metrics give an idea of the "size" of this particular execution.
-<3> the `exceptionDto` complex type defines a structure for capturing the stack trace of any exception that might occur
-in the course of invoking an action or editing a property.
-
-The xref:rgcms.adoc#_rgcms_schema_changes[changes] schema also provides metrics on the number of objects loaded/changed,
-but relates to the entire interaction rather than just one (sub)execution of an interaction.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema.adoc
deleted file mode 100644
index 5a84631..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgcms_schema.adoc
+++ /dev/null
@@ -1,37 +0,0 @@
-[[_rgcms_schema]]
-= Schema
-: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/
-
-
-Most applications need to integrate with other apps in the enterprise. To facilitate such integration scenarios,
-Apache Isis defines a number of standard XSD schemas:
-
-
-* the xref:rgcms.adoc#_rgcms_schema-cmd[command] schema, which captures the __intention__ of a user
-to invoke an action or edit a property
-
-* the xref:rgcms.adoc#_rgcms_schema-ixn[interaction execution] schema, which captures the actual execution of an action invocation/property edit
-
-* the xref:rgcms.adoc#_rgcms_schema-chg[changes] schema, which captures which objects have been
-created, updated or deleted as the result of an execution of an action invocation/property edit
-
-* the xref:rgcms.adoc#_rgcms_schema-aim[action memento invocation] schema (deprecated in `1.13.0`, replaced by
-either "cmd" or "ixn"), which allows action invocations to be captured and reified.
-
-These each use XSD types defined by the xref:rgcms.adoc#_rgcms_schema-common[common schema] (most notably the `oidDto`
-complex type which identifies a domain object).
-
-The (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] and
-http://github.com/isisaddons/isis-module-publishmq[Isis addons' publishmq] modules uses these schemas to reify
-corresponding applib objects (`Command`, `Interaction.Execution` and `PublishedObjects`), either to persist or
-publishing using an link:http://activemq.apache.org[Apache ActiveMQ] message queue.
-
-The sections below discuss these schemas in more detail.
-
-include::_rgcms_schema-cmd.adoc[leveloffset=+1]
-include::_rgcms_schema-ixn.adoc[leveloffset=+1]
-include::_rgcms_schema-chg.adoc[leveloffset=+1]
-include::_rgcms_schema-aim.adoc[leveloffset=+1]
-include::_rgcms_schema-common.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/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
deleted file mode 100644
index 46d7e42..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgfis_application-layer.adoc
+++ /dev/null
@@ -1,87 +0,0 @@
-[[_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_AuthenticationSessionProvider[`o.a.i.core.commons.` +
-`authentication.` +
-`AuthenticationSessionProvider`]
-|Simply responsible for obtaining the current `AuthenticationSession` (the framework's internal representation of the currently logged-in user).
-|`AuthenticationSession-` +
-`ProviderDefault` +
-``isis-core-runtime``
-|Default implementation looks up from `IsisSessionFactory` singleton's thread-local
-
-
-|xref:rgfis.adoc#_rgfis_spi_CommandDtoServiceInternal[`o.a.i.c.m.s.command` +
-`CommandDtoServiceInternal`]
-|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` +
-``isis-core-runtime``
-|
-
-
-|xref:rgfis.adoc#_rgfis_spi_MessageBrokerServiceInternal[`o.a.i.c.m.s.msgbroker` +
-`MessageBrokerServiceInternal`]
-|A wrapper around xref:rgsvc.adoc#_rgsvc_api_MessageService[`MessageService`].
-|MessageBrokerService-` +
-`InternalDefault` +
-``isis-core-runtime``
-|This service does not provide any additional capabilities over `MessageService`, and will (most likely) be conflated with that service in the future.
-
-
-|xref:rgfis.adoc#_rgfis_spi_InteractionDtoServiceInternal[`o.a.i.c.m.s.ixn` +
-`InteractionDtoServiceInternal`]
-|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` +
-``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_AuthenticationSessionProvider.adoc[leveloffset=+1]
-include::_rgfis_spi_CommandDtoServiceInternal.adoc[leveloffset=+1]
-include::_rgfis_spi_MessageBrokerServiceInternal.adoc[leveloffset=+1]
-include::_rgfis_spi_InteractionDtoServiceInternal.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/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
deleted file mode 100644
index 1e268c0..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgfis_persistence-layer.adoc
+++ /dev/null
@@ -1,98 +0,0 @@
-[[_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`]
-|Co-ordinates between
-xref:rgfis.adoc#_rgfis_spi_ChangedObjectsServiceInternal[`ChangedObjectsServiceInternal`] and
-xref:rgfis.adoc#_rgfis_spi_AuditerService[`AuditerService`].
-|concrete class.
-|
-
-
-|xref:rgfis.adoc#_rgfis_spi_ChangedObjectsServiceInternal[`o.a.i.c.r.s.changes.` +
-`ChangedObjectsServiceInternal`]
-|Request-scoped service holding objects enlisted into current transaction.
-|concrete class.
-|
-
-
-|xref:rgfis.adoc#_rgfis_spi_PersistenceSessionServiceInternal[`o.a.i.c.m.s.` +
-`persistsession.` +
-`PersistenceSessionServiceInternal`]
-|Acts as a facade to the underlying JDO persistence session / database connection. As such it provides methods for
-querying and for persisting objects.
-|`PersistenceSessionService-` +
-`InternalDefault` +
-`isis-core-runtime`
-|
-
-
-|xref:rgfis.adoc#_rgfis_spi_PublishingServiceInternal[`o.a.i.c.m.s.publishing.` +
-`PublishingServiceInternal`]
-|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` +
-`isis-core-runtime`
-|
-
-
-|xref:rgfis.adoc#_rgfis_spi_TransactionStateProviderInternal[`o.a.i.c.m.s.` +
-`transtate.` +
-`TransactionStateProviderInternal`]
-|Simply provides the ability to check as to the state of the current transaction.
-|`TransactionStateProvider-` +
-`InternalDefault` +
-`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_PersistenceSessionServiceInternal.adoc[leveloffset=+1]
-include::_rgfis_spi_PublishingServiceInternal.adoc[leveloffset=+1]
-include::_rgfis_spi_TransactionStateProviderInternal.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/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
deleted file mode 100644
index 349042c..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgfis_presentation-layer.adoc
+++ /dev/null
@@ -1,66 +0,0 @@
-[[_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/2669a971/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
deleted file mode 100644
index f792fe1..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_AuditingServiceInternal.adoc
+++ /dev/null
@@ -1,54 +0,0 @@
-[[_rgfis_spi_AuditingServiceInternal]]
-= `AuditingServiceInternal`
-: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 acts as an internal facade to any
-configured xref:rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`] and
-xref:rgsvc.adoc#_rgsvc_spi_AuditerService[`AuditerService`] services. 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.
-
-[NOTE]
-====
-xref:rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`] is now deprecated, replaced by
-xref:rgsvc.adoc#_rgsvc_spi_AuditerService[`AuditerService`].
-====
-
-
-
-== SPI and Implementation
-
-The SPI of the service is:
-
-[source,java]
-----
-public class AuditingServiceInternal {
- public boolean canAudit(); // <1>
- public void audit(); // <2>
-}
-----
-<1> minor performance optimization as to whether any auditing services are actually enabled; checks to see if
-any xref:rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`] has been configured, also if any
-xref:rgsvc.adoc#_rgsvc_spi_AuditerService[`AuditService`] are enabled.
-<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/2669a971/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_AuthenticationSessionProvider.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_AuthenticationSessionProvider.adoc b/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_AuthenticationSessionProvider.adoc
deleted file mode 100644
index 496b58b..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_AuthenticationSessionProvider.adoc
+++ /dev/null
@@ -1,34 +0,0 @@
-[[_rgfis_spi_AuthenticationSessionProvider]]
-= `AuthenticationSessionProvider`
-: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) `AuthenticationSessionProvider` domain service is simply responsible for obtaining the `AuthenticationSession` (being the framework's internal representation of the currently logged in user).
-
-
-
-
-== SPI and Implementation
-
-The SPI of the service is:
-
-[source,java]
-----
-public interface AuthenticationSessionProvider {
- AuthenticationSession getAuthenticationSession();
-}
-----
-
-
-The framework provides a default implementation of the service, `AuthenticationSessionProviderDefault`, which looks up
-the current `AuthenticationSession` from `IsisSessionFactory` singleton service:
-
-[source,java]
-----
-isisSessionFactory.getCurrentSession().getAuthenticationSession();
-----
-
-
-If xref:rgsvc.adoc#_rgsvc_api_SudoService[`SudoService`] has been used to temporarily override the user and/or roles, then this service will report the overridden values.
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/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
deleted file mode 100644
index 2fbd98b..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_ChangedObjectsServiceInternal.adoc
+++ /dev/null
@@ -1,69 +0,0 @@
-[[_rgfis_spi_ChangedObjectsServiceInternal]]
-= `ChangedObjectsServiceInternal`
-: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 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/2669a971/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
deleted file mode 100644
index c9ae7c3..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_CommandDtoServiceInternal.adoc
+++ /dev/null
@@ -1,62 +0,0 @@
-[[_rgfis_spi_CommandDtoServiceInternal]]
-= `CommandDtoServiceInternal`
-: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` 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/2669a971/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
deleted file mode 100644
index 2cfdb60..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_rgfis_spi_ContentNegotiationService.adoc
+++ /dev/null
@@ -1,204 +0,0 @@
-[[_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 three implementations of `ContentNegotiationService` which inspects different elements of the HTTP `Accept` header. One of these implementations, `ContentNegotiationServiceXRoDomainType` will further delegate down to the companion xref:rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`] service (if configured/available), based on the value of the "x-ro-domain-type" parameter of the header. +
-+
-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 {
- Response.ResponseBuilder buildResponse( // <1>
- RepresentationService.Context2 renderContext2,
- ObjectAdapter objectAdapter);
- Response.ResponseBuilder buildResponse( // <2>
- RepresentationService.Context2 renderContext2,
- ObjectAndProperty objectAndProperty);
- Response.ResponseBuilder buildResponse( // <3>
- RepresentationService.Context2 renderContext2,
- ObjectAndCollection objectAndCollection);
- Response.ResponseBuilder buildResponse( // <4>
- RepresentationService.Context2 renderContext2,
- ObjectAndAction objectAndAction);
- 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 three implementation of this service, one of which is `o.a.i.v.ro.rendering.service.conneg.ContentNegotiationServiceXRoDomainType`. This implementation 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.
-
-The other two implementations of `ContentNegotiationService` are:
-
-* `ContentNegotiationServiceForRestfulObjectsV1_0` +
-+
-which returns representations according to the link:http://restfulobjects.org[Restful Objects] spec
-
-* `ContentNegotiationServiceOrgApacheIsisV1` +
-+
-which returns xref:ugvro.adoc#_ugvro_simplified-representations[simplified representations]
-
-
-
-== 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
-implementations of `ContentNegotiationService` service are 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