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 2021/02/07 14:53:27 UTC
[isis] 03/12: ISIS-2444: reverses accidental edit of 'members' ->
'pathsToInclude'
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch ISIS-2444
in repository https://gitbox.apache.org/repos/asf/isis.git
commit 6a006ba7366a275ed7e81cac04aafd4d7d26f1ba
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Sat Feb 6 14:28:19 2021 +0000
ISIS-2444: reverses accidental edit of 'members' -> 'pathsToInclude'
This must have happened a few weeks back when working on the XmlSnapshotService
---
.../modules/ROOT/pages/cutting-a-release.adoc | 2 +-
.../modules/ROOT/pages/key-generation.adoc | 4 ++--
.../comguide/modules/ROOT/pages/pmc-notes.adoc | 10 ++++-----
.../ROOT/pages/post-release-successful.adoc | 4 ++--
.../ROOT/pages/post-release-unsuccessful.adoc | 2 +-
.../modules/ROOT/pages/verifying-releases.adoc | 6 ++---
.../pages/what-is-apache-isis/screencasts.adoc | 2 +-
.../pages/2020/2.0.0-M3/migrating-to-2.0.0.adoc | 2 +-
.../modules/ROOT/pages/2020/2.0.0-M5/mignotes.adoc | 4 ++--
.../modules/intellij/pages/hints-and-tips.adoc | 4 ++--
.../hooks/introductory_notes.adoc | 26 ++++++++++++++++++++++
.../AcceptHeaderService/hooks/usage_notes.adoc | 26 ++++++++++++++++++++++
.../pages/AcceptHeaderService/implementation.adoc | 8 +++++++
.../hooks/see_also.adoc | 26 ++++++++++++++++++++++
.../implementation.adoc | 5 +++++
.../BookmarkService/hooks/introductory_notes.adoc | 5 +++++
.../pages/BookmarkService/hooks/see_also.adoc | 13 +++++++++++
.../pages/BookmarkService/hooks/usage_notes.adoc | 26 ++++++++++++++++++++++
.../ClockService/hooks/introductory_notes.adoc | 13 +++++++++++
.../pages/ClockService/hooks/see_also.adoc | 4 ++++
.../pages/ClockService/hooks/usage_notes.adoc | 0
.../hooks/usage_notes.adoc | 17 ++++++++++++++
.../CommandExecutorService/hooks/usage_notes.adoc | 4 ++++
.../XmlSnapshotService/hooks/implementation.adoc | 5 +++++
24 files changed, 198 insertions(+), 20 deletions(-)
diff --git a/antora/components/comguide/modules/ROOT/pages/cutting-a-release.adoc b/antora/components/comguide/modules/ROOT/pages/cutting-a-release.adoc
index 4f47ec9..edda475 100644
--- a/antora/components/comguide/modules/ROOT/pages/cutting-a-release.adoc
+++ b/antora/components/comguide/modules/ROOT/pages/cutting-a-release.adoc
@@ -540,7 +540,7 @@ Wait a minute or two; the site should be available at link:https://isis.staged.a
Once the artifacts have been uploaded, you can call a vote.
-In all cases, votes last for 72 hours and require a +3 (binding) vote from pathsToInclude.
+In all cases, votes last for 72 hours and require a +3 (binding) vote from members.
=== Start voting thread on dev mailing list
diff --git a/antora/components/comguide/modules/ROOT/pages/key-generation.adoc b/antora/components/comguide/modules/ROOT/pages/key-generation.adoc
index d560307..2ea766a 100644
--- a/antora/components/comguide/modules/ROOT/pages/key-generation.adoc
+++ b/antora/components/comguide/modules/ROOT/pages/key-generation.adoc
@@ -9,7 +9,7 @@
-In order that a contributor can make a release it is necessary for them to have generated a key and had that key recognized by other pathsToInclude of the Apache Software Foundation.
+In order that a contributor can make a release it is necessary for them to have generated a key and had that key recognized by other members of the Apache Software Foundation.
For further background information on this topic, see the http://www.apache.org/dev/release-signing.html[release signing page] and the http://www.apache.org/dev/openpgp.html#generate-key[openpgp page] on the Apache wiki.
@@ -540,7 +540,7 @@ Log onto `id.apache.org` and ensure that the finger print of your public key is
== Attend Key Signing Party (Apache web of trust)
-It is strongly advised that the contributor attend a key signing party at an Apache event, in order that other Apache committers/pathsToInclude can in person verify their identity against the key.
+It is strongly advised that the contributor attend a key signing party at an Apache event, in order that other Apache committers/members can in person verify their identity against the key.
The process for this is described http://www.apache.org/dev/release-signing.html#key-signing-party[here] and http://wiki.apache.org/apachecon/PgpKeySigning[here].
== Update Maven Settings file (`~/.m2/settings.xml`)
diff --git a/antora/components/comguide/modules/ROOT/pages/pmc-notes.adoc b/antora/components/comguide/modules/ROOT/pages/pmc-notes.adoc
index b1d1333..637158c 100644
--- a/antora/components/comguide/modules/ROOT/pages/pmc-notes.adoc
+++ b/antora/components/comguide/modules/ROOT/pages/pmc-notes.adoc
@@ -13,7 +13,7 @@ More information about PMCs can be found link:http://www.apache.org/dev/pmc.html
In Apache Isis, every committer is a member of the PMC.
-This page contains some general notes on maintenance activities required by PMC pathsToInclude.
+This page contains some general notes on maintenance activities required by PMC members.
== Prereqs
@@ -34,9 +34,9 @@ To set up ssh in the first place, take a look at https://www.apache.org/dev/new-
== New Committer/PMC member
-Currently we don't distinguish between committers and PMC pathsToInclude: every committer is automatically invited to also be a member of the PMC.
+Currently we don't distinguish between committers and PMC members: every committer is automatically invited to also be a member of the PMC.
-Further notes on the steps for new PMC pathsToInclude can be found http://www.apache.org/dev/pmc.html#newpmc[here].
+Further notes on the steps for new PMC members can be found http://www.apache.org/dev/pmc.html#newpmc[here].
=== Start a vote thread on private@
@@ -179,10 +179,10 @@ with body:
The Apache Isis PMC has voted Joe Bloggs as a committer and also member of the PMC. <1>
Voting thread:
-https://mail-search.apache.org/pathsToInclude/private-arch/isis-private/xxx <1>
+https://mail-search.apache.org/members/private-arch/isis-private/xxx <1>
Results announcement:
-https://mail-search.apache.org/pathsToInclude/private-arch/isis-private/xxx <1>
+https://mail-search.apache.org/members/private-arch/isis-private/xxx <1>
The committee-info.txt file has been updated, as have the LDAP groups (modify_unix_group.pl, modify_committee.pl).
----
diff --git a/antora/components/comguide/modules/ROOT/pages/post-release-successful.adoc b/antora/components/comguide/modules/ROOT/pages/post-release-successful.adoc
index a4f3865..0afdf84 100644
--- a/antora/components/comguide/modules/ROOT/pages/post-release-successful.adoc
+++ b/antora/components/comguide/modules/ROOT/pages/post-release-successful.adoc
@@ -7,11 +7,11 @@ The release process consists of:
* the release manager xref:comguide:ROOT:cutting-a-release.adoc[cutting the release]
-* pathsToInclude of the Apache Isis PMC xref:comguide:ROOT:verifying-releases.adoc[verifying] and voting on the release
+* members of the Apache Isis PMC xref:comguide:ROOT:verifying-releases.adoc[verifying] and voting on the release
* the release manager performing post-release tasks, for either a successful or an xref:comguide:ROOT:post-release-unsuccessful.adoc[unsuccessful] vote (former documented below)
-For a vote to succeed, there must be +3 votes from PMC pathsToInclude, and the vote must have been open at least 72 hours.
+For a vote to succeed, there must be +3 votes from PMC members, and the vote must have been open at least 72 hours.
If there are not +3 votes after this time then it is perfectly permissible to keep the vote open longer.
This section describes the steps to perform if the vote has been successful.
diff --git a/antora/components/comguide/modules/ROOT/pages/post-release-unsuccessful.adoc b/antora/components/comguide/modules/ROOT/pages/post-release-unsuccessful.adoc
index 6e528ca..5281897 100644
--- a/antora/components/comguide/modules/ROOT/pages/post-release-unsuccessful.adoc
+++ b/antora/components/comguide/modules/ROOT/pages/post-release-unsuccessful.adoc
@@ -6,7 +6,7 @@
The release process consists of:
* the release manager xref:comguide:ROOT:cutting-a-release.adoc[cutting the release]
-* pathsToInclude of the Apache Isis PMC xref:comguide:ROOT:verifying-releases.adoc[verifying] and voting on the release
+* members of the Apache Isis PMC xref:comguide:ROOT:verifying-releases.adoc[verifying] and voting on the release
* the release manager performing post-release tasks, for either a xref:comguide:ROOT:post-release-successful.adoc[successful] or an unsuccessful vote (latter documented below).
If the vote did not succeed (did not achieve +3 votes after 72 hours and/or is unlikely to do so), then the vote should be closed and the following steps performed.
diff --git a/antora/components/comguide/modules/ROOT/pages/verifying-releases.adoc b/antora/components/comguide/modules/ROOT/pages/verifying-releases.adoc
index 444c400..43ddafa 100644
--- a/antora/components/comguide/modules/ROOT/pages/verifying-releases.adoc
+++ b/antora/components/comguide/modules/ROOT/pages/verifying-releases.adoc
@@ -9,15 +9,15 @@
The release process consists of:
* the release manager xref:comguide:ROOT:cutting-a-release.adoc[cutting the release]
-* pathsToInclude of the Apache Isis PMC verifying and voting on the release (documented below)
+* members of the Apache Isis PMC verifying and voting on the release (documented below)
* the release manager performing post-release tasks, for either a xref:comguide:ROOT:post-release-successful.adoc[successful] or an xref:comguide:ROOT:post-release-unsuccessful.adoc[unsuccessful] vote.
-This section describes some guidance on what a voter (pathsToInclude of the Apache Isis PMC and anyone else who wishes) is expected to do before casting their vote in order to verify a release.
+This section describes some guidance on what a voter (members of the Apache Isis PMC and anyone else who wishes) is expected to do before casting their vote in order to verify a release.
== Background
Whenever a release manager announces a vote on a release (as per the [release process]) on the xref:docs:support:mailing-list.adoc#mailing-lists[dev mailing list], it is the responsibility of the project's PMC to cast their vote on the release.
-Anyone else can also vote, but only pathsToInclude of the Apache Isis PMC's vote are binding.
+Anyone else can also vote, but only members of the Apache Isis PMC's vote are binding.
Per this http://www.apache.org/dev/release.html[ASF documentation], the legal requirements for an ASF release are:
diff --git a/antora/components/docs/modules/ROOT/pages/what-is-apache-isis/screencasts.adoc b/antora/components/docs/modules/ROOT/pages/what-is-apache-isis/screencasts.adoc
index f5ef431..3b7ef2d 100644
--- a/antora/components/docs/modules/ROOT/pages/what-is-apache-isis/screencasts.adoc
+++ b/antora/components/docs/modules/ROOT/pages/what-is-apache-isis/screencasts.adoc
@@ -91,7 +91,7 @@ Using xref:testing:fixtures:about.adoc[fixture scripts] to initialize the databa
|link:https://www.youtube.com/watch?v=dXtmxmYxa30[006^] +
-Implementing xref:userguide:fun:business-rules.adoc[business rules]for domain object pathsToInclude, using supporting methods ("see it, use it, do it")
+Implementing xref:userguide:fun:business-rules.adoc[business rules]for domain object members, using supporting methods ("see it, use it, do it")
|x||||||||||
|link:https://www.youtube.com/watch?v=imHfxQGUgV8[007^] +
diff --git a/antora/components/relnotes/modules/ROOT/pages/2020/2.0.0-M3/migrating-to-2.0.0.adoc b/antora/components/relnotes/modules/ROOT/pages/2020/2.0.0-M3/migrating-to-2.0.0.adoc
index ebaad84..9c18943 100644
--- a/antora/components/relnotes/modules/ROOT/pages/2020/2.0.0-M3/migrating-to-2.0.0.adoc
+++ b/antora/components/relnotes/modules/ROOT/pages/2020/2.0.0-M3/migrating-to-2.0.0.adoc
@@ -727,7 +727,7 @@ isis.value-types. +
=== Annotations
Collections are no longer editable.
-The `@Collection#editing()` and `@Collection#editingDisabledReason()` pathsToInclude have been removed.
+The `@Collection#editing()` and `@Collection#editingDisabledReason()` members have been removed.
=== No longer any archetypes
diff --git a/antora/components/relnotes/modules/ROOT/pages/2020/2.0.0-M5/mignotes.adoc b/antora/components/relnotes/modules/ROOT/pages/2020/2.0.0-M5/mignotes.adoc
index e8bb639..e21bacc 100644
--- a/antora/components/relnotes/modules/ROOT/pages/2020/2.0.0-M5/mignotes.adoc
+++ b/antora/components/relnotes/modules/ROOT/pages/2020/2.0.0-M5/mignotes.adoc
@@ -28,7 +28,7 @@ isis.core.metaModel.validator.mixins-only=true // <.>
----
<.> `@DomainService(natureOfService=VIEW/REST)` is now solely used for UI menu action providers and REST end-points.
There is no longer the need to validate uses of `natureOfService=DOMAIN` as this option was removed.
-<.> Support for services that contribute pathsToInclude to other `DomainObjects` was removed. Use `Mixins` instead.
+<.> Support for services that contribute members to other `DomainObjects` was removed. Use `Mixins` instead.
See the former java-doc for hints on how to migrate the previous options.
@@ -92,7 +92,7 @@ VIEW_CONTRIBUTIONS_ONLY,
spring.datasource.platform=h2
spring.datasource.url=jdbc:h2:mem:...
----
-configure Datanucleus settings using
+configure Datanucleus settings using
[source]
----
datanucleus. ...
diff --git a/antora/components/setupguide/modules/intellij/pages/hints-and-tips.adoc b/antora/components/setupguide/modules/intellij/pages/hints-and-tips.adoc
index 8469c95..0206d77 100644
--- a/antora/components/setupguide/modules/intellij/pages/hints-and-tips.adoc
+++ b/antora/components/setupguide/modules/intellij/pages/hints-and-tips.adoc
@@ -49,8 +49,8 @@ Navigating around:
* find superclasses/interface/declaration: `ctrl-B`
Viewing the structure (ie outline) of a class
-* `ctrl-F12` will pop-up a dialog showing all pathsToInclude
-** hit `ctrl-F12` again to also see inherited pathsToInclude
+* `ctrl-F12` will pop-up a dialog showing all members
+** hit `ctrl-F12` again to also see inherited members
== Editing
diff --git a/api/applib/src/main/adoc/modules/applib-svc/pages/AcceptHeaderService/hooks/introductory_notes.adoc b/api/applib/src/main/adoc/modules/applib-svc/pages/AcceptHeaderService/hooks/introductory_notes.adoc
new file mode 100644
index 0000000..3d8ef4b
--- /dev/null
+++ b/api/applib/src/main/adoc/modules/applib-svc/pages/AcceptHeaderService/hooks/introductory_notes.adoc
@@ -0,0 +1,26 @@
+
+: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 ag [...]
+:page-partial:
+
+
+The intended use of this service is where there are multiple concurrent versions of a REST API, for backward compatibility of existing clients.
+The `AcceptHeaderService` allows the responsibility for content negotiation (determining which version of the REST API is to be used) to be performed by logic in the domain objects themselves.
+
+The diagram below illustrated this:
+
+image::reference-services-api/acceptheaderservice.png[width="700px"]
+
+The REST request is submitted to a domain service with a xref:refguide:applib-ant:DomainService.adoc#nature[nature] of `VIEW_REST_ONLY` (`MyRestApi` in the diagram).
+This uses the `AcceptHeaderService` to obtain the values of the HTTP `Accept` header.
+Based on this it delegates to the appropriate underlying domain service (with a nature of `DOMAIN` so that they are not exposed in the REST API at all).
+
+[TIP]
+====
+The service does not define any conventions as to the format of the media types.
+The option is to use the media type's type/subtype, eg `application/vnd.myrestapi-v1+json`; an alternative is to use a media type parameter as a hint, eg `application/json;x-my-rest-api-version=1` (where `x-my-rest-api-version` is the media type parameter).
+
+The Restful Objects specification does this something similar with its own `x-ro-domain-type` media type parameter; this is used by the xref:refguide:applib-svc:ContentMappingService.adoc[`ContentMappingService`] to determine how to map domain objects to view models/DTOs.
+====
+
+
+
diff --git a/api/applib/src/main/adoc/modules/applib-svc/pages/AcceptHeaderService/hooks/usage_notes.adoc b/api/applib/src/main/adoc/modules/applib-svc/pages/AcceptHeaderService/hooks/usage_notes.adoc
new file mode 100644
index 0000000..3d8ef4b
--- /dev/null
+++ b/api/applib/src/main/adoc/modules/applib-svc/pages/AcceptHeaderService/hooks/usage_notes.adoc
@@ -0,0 +1,26 @@
+
+: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 ag [...]
+:page-partial:
+
+
+The intended use of this service is where there are multiple concurrent versions of a REST API, for backward compatibility of existing clients.
+The `AcceptHeaderService` allows the responsibility for content negotiation (determining which version of the REST API is to be used) to be performed by logic in the domain objects themselves.
+
+The diagram below illustrated this:
+
+image::reference-services-api/acceptheaderservice.png[width="700px"]
+
+The REST request is submitted to a domain service with a xref:refguide:applib-ant:DomainService.adoc#nature[nature] of `VIEW_REST_ONLY` (`MyRestApi` in the diagram).
+This uses the `AcceptHeaderService` to obtain the values of the HTTP `Accept` header.
+Based on this it delegates to the appropriate underlying domain service (with a nature of `DOMAIN` so that they are not exposed in the REST API at all).
+
+[TIP]
+====
+The service does not define any conventions as to the format of the media types.
+The option is to use the media type's type/subtype, eg `application/vnd.myrestapi-v1+json`; an alternative is to use a media type parameter as a hint, eg `application/json;x-my-rest-api-version=1` (where `x-my-rest-api-version` is the media type parameter).
+
+The Restful Objects specification does this something similar with its own `x-ro-domain-type` media type parameter; this is used by the xref:refguide:applib-svc:ContentMappingService.adoc[`ContentMappingService`] to determine how to map domain objects to view models/DTOs.
+====
+
+
+
diff --git a/api/applib/src/main/adoc/modules/applib-svc/pages/AcceptHeaderService/implementation.adoc b/api/applib/src/main/adoc/modules/applib-svc/pages/AcceptHeaderService/implementation.adoc
new file mode 100644
index 0000000..e53b262
--- /dev/null
+++ b/api/applib/src/main/adoc/modules/applib-svc/pages/AcceptHeaderService/implementation.adoc
@@ -0,0 +1,8 @@
+
+: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 ag [...]
+
+
+
+The xref:vro:ROOT:about.adoc[Restful Objects] viewer provides an implementation of this API, `o.a.i.viewer.restfulobjects.rendering.service.acceptheader.AcceptHeaderServiceForRest`.
+
+
diff --git a/api/applib/src/main/adoc/modules/applib-svc/pages/ApplicationFeatureRepository/hooks/see_also.adoc b/api/applib/src/main/adoc/modules/applib-svc/pages/ApplicationFeatureRepository/hooks/see_also.adoc
new file mode 100644
index 0000000..3d8ef4b
--- /dev/null
+++ b/api/applib/src/main/adoc/modules/applib-svc/pages/ApplicationFeatureRepository/hooks/see_also.adoc
@@ -0,0 +1,26 @@
+
+: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 ag [...]
+:page-partial:
+
+
+The intended use of this service is where there are multiple concurrent versions of a REST API, for backward compatibility of existing clients.
+The `AcceptHeaderService` allows the responsibility for content negotiation (determining which version of the REST API is to be used) to be performed by logic in the domain objects themselves.
+
+The diagram below illustrated this:
+
+image::reference-services-api/acceptheaderservice.png[width="700px"]
+
+The REST request is submitted to a domain service with a xref:refguide:applib-ant:DomainService.adoc#nature[nature] of `VIEW_REST_ONLY` (`MyRestApi` in the diagram).
+This uses the `AcceptHeaderService` to obtain the values of the HTTP `Accept` header.
+Based on this it delegates to the appropriate underlying domain service (with a nature of `DOMAIN` so that they are not exposed in the REST API at all).
+
+[TIP]
+====
+The service does not define any conventions as to the format of the media types.
+The option is to use the media type's type/subtype, eg `application/vnd.myrestapi-v1+json`; an alternative is to use a media type parameter as a hint, eg `application/json;x-my-rest-api-version=1` (where `x-my-rest-api-version` is the media type parameter).
+
+The Restful Objects specification does this something similar with its own `x-ro-domain-type` media type parameter; this is used by the xref:refguide:applib-svc:ContentMappingService.adoc[`ContentMappingService`] to determine how to map domain objects to view models/DTOs.
+====
+
+
+
diff --git a/api/applib/src/main/adoc/modules/applib-svc/pages/ApplicationFeatureRepository/implementation.adoc b/api/applib/src/main/adoc/modules/applib-svc/pages/ApplicationFeatureRepository/implementation.adoc
new file mode 100644
index 0000000..e4852a7
--- /dev/null
+++ b/api/applib/src/main/adoc/modules/applib-svc/pages/ApplicationFeatureRepository/implementation.adoc
@@ -0,0 +1,5 @@
+
+: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 ag [...]
+
+
+
diff --git a/api/applib/src/main/adoc/modules/applib-svc/pages/BookmarkService/hooks/introductory_notes.adoc b/api/applib/src/main/adoc/modules/applib-svc/pages/BookmarkService/hooks/introductory_notes.adoc
new file mode 100644
index 0000000..e4852a7
--- /dev/null
+++ b/api/applib/src/main/adoc/modules/applib-svc/pages/BookmarkService/hooks/introductory_notes.adoc
@@ -0,0 +1,5 @@
+
+: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 ag [...]
+
+
+
diff --git a/api/applib/src/main/adoc/modules/applib-svc/pages/BookmarkService/hooks/see_also.adoc b/api/applib/src/main/adoc/modules/applib-svc/pages/BookmarkService/hooks/see_also.adoc
new file mode 100644
index 0000000..c256f6d
--- /dev/null
+++ b/api/applib/src/main/adoc/modules/applib-svc/pages/BookmarkService/hooks/see_also.adoc
@@ -0,0 +1,13 @@
+
+: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 ag [...]
+
+
+For example, a `Customer` object with an xref:refguide:applib-ant:DomainObject.adoc#objectType[object type] of "custmgmt.Customer" and an id of 123
+would correspond to a xref:BookmarkService.adoc#bookmark[`Bookmark`] with a string representation of "custmgmt.Customer|123".
+
+Bookmarks are useful to store a reference to an arbitrary object, although be aware that there is no referential integrity.
+
+Several of the extension libraries use bookmarks.
+For example the xref:refguide:applib-svc:AuditerService.adoc[`AuditerService`] uses bookmarks to identify the object that is being modified.
+
+Serialized form of bookmarks also appear within xref:refguide:schema:about.adoc[schema] instances, for example as used by xref:refguide:applib-svc:CommandServiceInternal.adoc[`CommandService`] and the xref:refguide:applib-svc:ExecutionSubscriber.adoc[`PublisherService`].
diff --git a/api/applib/src/main/adoc/modules/applib-svc/pages/BookmarkService/hooks/usage_notes.adoc b/api/applib/src/main/adoc/modules/applib-svc/pages/BookmarkService/hooks/usage_notes.adoc
new file mode 100644
index 0000000..3d8ef4b
--- /dev/null
+++ b/api/applib/src/main/adoc/modules/applib-svc/pages/BookmarkService/hooks/usage_notes.adoc
@@ -0,0 +1,26 @@
+
+: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 ag [...]
+:page-partial:
+
+
+The intended use of this service is where there are multiple concurrent versions of a REST API, for backward compatibility of existing clients.
+The `AcceptHeaderService` allows the responsibility for content negotiation (determining which version of the REST API is to be used) to be performed by logic in the domain objects themselves.
+
+The diagram below illustrated this:
+
+image::reference-services-api/acceptheaderservice.png[width="700px"]
+
+The REST request is submitted to a domain service with a xref:refguide:applib-ant:DomainService.adoc#nature[nature] of `VIEW_REST_ONLY` (`MyRestApi` in the diagram).
+This uses the `AcceptHeaderService` to obtain the values of the HTTP `Accept` header.
+Based on this it delegates to the appropriate underlying domain service (with a nature of `DOMAIN` so that they are not exposed in the REST API at all).
+
+[TIP]
+====
+The service does not define any conventions as to the format of the media types.
+The option is to use the media type's type/subtype, eg `application/vnd.myrestapi-v1+json`; an alternative is to use a media type parameter as a hint, eg `application/json;x-my-rest-api-version=1` (where `x-my-rest-api-version` is the media type parameter).
+
+The Restful Objects specification does this something similar with its own `x-ro-domain-type` media type parameter; this is used by the xref:refguide:applib-svc:ContentMappingService.adoc[`ContentMappingService`] to determine how to map domain objects to view models/DTOs.
+====
+
+
+
diff --git a/api/applib/src/main/adoc/modules/applib-svc/pages/ClockService/hooks/introductory_notes.adoc b/api/applib/src/main/adoc/modules/applib-svc/pages/ClockService/hooks/introductory_notes.adoc
new file mode 100644
index 0000000..c256f6d
--- /dev/null
+++ b/api/applib/src/main/adoc/modules/applib-svc/pages/ClockService/hooks/introductory_notes.adoc
@@ -0,0 +1,13 @@
+
+: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 ag [...]
+
+
+For example, a `Customer` object with an xref:refguide:applib-ant:DomainObject.adoc#objectType[object type] of "custmgmt.Customer" and an id of 123
+would correspond to a xref:BookmarkService.adoc#bookmark[`Bookmark`] with a string representation of "custmgmt.Customer|123".
+
+Bookmarks are useful to store a reference to an arbitrary object, although be aware that there is no referential integrity.
+
+Several of the extension libraries use bookmarks.
+For example the xref:refguide:applib-svc:AuditerService.adoc[`AuditerService`] uses bookmarks to identify the object that is being modified.
+
+Serialized form of bookmarks also appear within xref:refguide:schema:about.adoc[schema] instances, for example as used by xref:refguide:applib-svc:CommandServiceInternal.adoc[`CommandService`] and the xref:refguide:applib-svc:ExecutionSubscriber.adoc[`PublisherService`].
diff --git a/api/applib/src/main/adoc/modules/applib-svc/pages/ClockService/hooks/see_also.adoc b/api/applib/src/main/adoc/modules/applib-svc/pages/ClockService/hooks/see_also.adoc
new file mode 100644
index 0000000..21f4ba4
--- /dev/null
+++ b/api/applib/src/main/adoc/modules/applib-svc/pages/ClockService/hooks/see_also.adoc
@@ -0,0 +1,4 @@
+
+: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 ag [...]
+
+
diff --git a/api/applib/src/main/adoc/modules/applib-svc/pages/ClockService/hooks/usage_notes.adoc b/api/applib/src/main/adoc/modules/applib-svc/pages/ClockService/hooks/usage_notes.adoc
new file mode 100644
index 0000000..e69de29
diff --git a/api/applib/src/main/adoc/modules/applib-svc/pages/CommandDtoProcessorService/hooks/usage_notes.adoc b/api/applib/src/main/adoc/modules/applib-svc/pages/CommandDtoProcessorService/hooks/usage_notes.adoc
new file mode 100644
index 0000000..3db7848
--- /dev/null
+++ b/api/applib/src/main/adoc/modules/applib-svc/pages/CommandDtoProcessorService/hooks/usage_notes.adoc
@@ -0,0 +1,17 @@
+
+: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 ag [...]
+
+
+
+
+Most applications deal with dates and times in one way or another.
+For example, if an `Order` is placed, then the `Customer` may have 30 days to pay the `Invoice`, otherwise a penalty may be levied.
+
+However, such date/time related functionality can quickly complicate automated testing: "today+30" will be a different value every time the test is run.
+
+Even disregarding testing, there may be a requirement to ensure that date/times are obtained from an NNTP server (rather than the system PC).
+While instantiating a `java.util.Date` to current the current time is painless enough, we would not want complex technical logic for querying an NNTP server spread around domain logic code.
+
+Therefore it's common to provide a domain service whose responsibility is to provide the current time.
+This service can be injected into any domain object (and can be mocked out for unit testing).
+Apache Isis provides such a facade through the `ClockService`.
diff --git a/api/applib/src/main/adoc/modules/applib-svc/pages/CommandExecutorService/hooks/usage_notes.adoc b/api/applib/src/main/adoc/modules/applib-svc/pages/CommandExecutorService/hooks/usage_notes.adoc
new file mode 100644
index 0000000..21f4ba4
--- /dev/null
+++ b/api/applib/src/main/adoc/modules/applib-svc/pages/CommandExecutorService/hooks/usage_notes.adoc
@@ -0,0 +1,4 @@
+
+: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 ag [...]
+
+
diff --git a/api/applib/src/main/adoc/modules/applib-svc/pages/XmlSnapshotService/hooks/implementation.adoc b/api/applib/src/main/adoc/modules/applib-svc/pages/XmlSnapshotService/hooks/implementation.adoc
new file mode 100644
index 0000000..e4852a7
--- /dev/null
+++ b/api/applib/src/main/adoc/modules/applib-svc/pages/XmlSnapshotService/hooks/implementation.adoc
@@ -0,0 +1,5 @@
+
+: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 ag [...]
+
+
+