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/04/06 16:06:33 UTC
[isis] branch 2.0.0-M5 updated (6b0918d -> a4c68ab)
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a change to branch 2.0.0-M5
in repository https://gitbox.apache.org/repos/asf/isis.git.
from 6b0918d ISIS-2484: updated wicket viewer docs for v2
new d9cb1de ISIS-2484: updates docs for RO viewer
new a4c68ab ISIS-2484: cleaning up extension catalog a little
The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
...ntentMappingService_020-examples-and-usage.adoc | 4 +-
.../modules/ROOT/partials/component-nav.adoc | 3 +
extensions/adoc/modules/ROOT/pages/about.adoc | 50 +++++-
.../adoc/modules/ROOT/partials/component-nav.adoc | 22 ---
extensions/core/command-log/adoc/antora.yml | 2 +-
extensions/core/command-replay/adoc/antora.yml | 2 +-
extensions/core/command-replay/secondary/pom.xml | 6 +-
extensions/core/model-annotation/adoc/antora.yml | 2 +-
.../modules/ROOT/pages/usage-by-isis-viewers.adoc | 2 +-
.../adoc/modules/ROOT/partials/component-nav.adoc | 8 +-
viewers/restfulobjects/adoc/antora.yml | 4 +-
.../adoc/modules/ROOT/pages/about.adoc | 6 +-
.../ROOT/pages/configuration-properties.adoc | 195 ---------------------
...{architecture.adoc => content-negotiation.adoc} | 16 +-
.../apache-isis-v1-profile.adoc} | 6 +-
.../apache-isis-v2-profile.INCOMPLETE.adoc} | 0
.../other-representations.adoc | 18 +-
.../action-invocation.adoc | 2 +-
.../apache-isis-profile.adoc | 15 +-
.../configuration-properties.adoc | 2 +-
.../simplified-representations/domain-object.adoc | 14 +-
.../object-collection.adoc | 4 +-
.../adoc/modules/ROOT/pages/health-check.adoc | 68 -------
.../adoc/modules/ROOT/pages/hints-and-tips.adoc | 3 -
.../ROOT/pages/hints-and-tips/angular-tips.adoc | 68 -------
.../hints-and-tips/using-chrome-devtools.adoc | 8 -
.../adoc/modules/ROOT/pages/layout-resources.adoc | 11 +-
.../adoc/modules/ROOT/pages/other-resources.adoc | 7 -
.../adoc/modules/ROOT/pages/ro-spec.adoc | 39 ++---
.../adoc/modules/ROOT/pages/security.adoc | 7 +-
.../ROOT/pages/setup-and-configuration.adoc | 132 ++++++++++++++
.../adoc/modules/ROOT/partials/module-nav.adoc | 14 +-
.../ROOT/partials/security/user-registration.adoc | 159 -----------------
.../modules/ROOT/partials/security/web-xml.adoc | 96 ----------
.../modules/ROOT/partials/security/webmodule.adoc | 25 +++
.../webmodule/auth/AuthenticationStrategy.java | 10 +-
.../auth/AuthenticationStrategyAbstract.java | 18 +-
.../auth/AuthenticationStrategyBasicAuth.java | 18 +-
.../auth/AuthenticationStrategyDefault.java | 9 +-
viewers/wicket/adoc/antora.yml | 2 +-
viewers/wicket/adoc/modules/ROOT/pages/about.adoc | 2 +-
.../ROOT/pages/setup-and-configuration.adoc | 4 +-
42 files changed, 310 insertions(+), 773 deletions(-)
delete mode 100644 viewers/restfulobjects/adoc/modules/ROOT/pages/configuration-properties.adoc
rename viewers/restfulobjects/adoc/modules/ROOT/pages/{architecture.adoc => content-negotiation.adoc} (85%)
rename viewers/restfulobjects/adoc/modules/ROOT/pages/{simplified-representations.adoc => content-negotiation/apache-isis-v1-profile.adoc} (85%)
rename viewers/restfulobjects/adoc/modules/ROOT/pages/{simplified-representations-v2.adoc => content-negotiation/apache-isis-v2-profile.INCOMPLETE.adoc} (100%)
rename viewers/restfulobjects/adoc/modules/ROOT/pages/{simplified-representations => content-negotiation}/other-representations.adoc (73%)
rename viewers/restfulobjects/adoc/modules/ROOT/pages/{ => content-negotiation}/simplified-representations/action-invocation.adoc (95%)
rename viewers/restfulobjects/adoc/modules/ROOT/pages/{ => content-negotiation}/simplified-representations/apache-isis-profile.adoc (74%)
rename viewers/restfulobjects/adoc/modules/ROOT/pages/{ => content-negotiation}/simplified-representations/configuration-properties.adoc (94%)
rename viewers/restfulobjects/adoc/modules/ROOT/pages/{ => content-negotiation}/simplified-representations/domain-object.adoc (80%)
rename viewers/restfulobjects/adoc/modules/ROOT/pages/{ => content-negotiation}/simplified-representations/object-collection.adoc (88%)
delete mode 100644 viewers/restfulobjects/adoc/modules/ROOT/pages/health-check.adoc
delete mode 100644 viewers/restfulobjects/adoc/modules/ROOT/pages/hints-and-tips/angular-tips.adoc
delete mode 100644 viewers/restfulobjects/adoc/modules/ROOT/pages/hints-and-tips/using-chrome-devtools.adoc
delete mode 100644 viewers/restfulobjects/adoc/modules/ROOT/pages/other-resources.adoc
create mode 100644 viewers/restfulobjects/adoc/modules/ROOT/pages/setup-and-configuration.adoc
delete mode 100644 viewers/restfulobjects/adoc/modules/ROOT/partials/security/user-registration.adoc
delete mode 100644 viewers/restfulobjects/adoc/modules/ROOT/partials/security/web-xml.adoc
create mode 100644 viewers/restfulobjects/adoc/modules/ROOT/partials/security/webmodule.adoc
[isis] 01/02: ISIS-2484: updates docs for RO viewer
Posted by da...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch 2.0.0-M5
in repository https://gitbox.apache.org/repos/asf/isis.git
commit d9cb1de24ba6ac3cf7e92f4e61ca9c91586619e8
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Tue Apr 6 16:45:44 2021 +0100
ISIS-2484: updates docs for RO viewer
---
...ntentMappingService_020-examples-and-usage.adoc | 4 +-
.../modules/ROOT/pages/usage-by-isis-viewers.adoc | 2 +-
viewers/restfulobjects/adoc/antora.yml | 4 +-
.../adoc/modules/ROOT/pages/about.adoc | 6 +-
.../ROOT/pages/configuration-properties.adoc | 195 ---------------------
...{architecture.adoc => content-negotiation.adoc} | 16 +-
.../apache-isis-v1-profile.adoc} | 6 +-
.../apache-isis-v2-profile.INCOMPLETE.adoc} | 0
.../other-representations.adoc | 18 +-
.../action-invocation.adoc | 2 +-
.../apache-isis-profile.adoc | 15 +-
.../configuration-properties.adoc | 2 +-
.../simplified-representations/domain-object.adoc | 14 +-
.../object-collection.adoc | 4 +-
.../adoc/modules/ROOT/pages/health-check.adoc | 68 -------
.../adoc/modules/ROOT/pages/hints-and-tips.adoc | 3 -
.../ROOT/pages/hints-and-tips/angular-tips.adoc | 68 -------
.../hints-and-tips/using-chrome-devtools.adoc | 8 -
.../adoc/modules/ROOT/pages/layout-resources.adoc | 11 +-
.../adoc/modules/ROOT/pages/other-resources.adoc | 7 -
.../adoc/modules/ROOT/pages/ro-spec.adoc | 39 ++---
.../adoc/modules/ROOT/pages/security.adoc | 7 +-
.../ROOT/pages/setup-and-configuration.adoc | 132 ++++++++++++++
.../adoc/modules/ROOT/partials/module-nav.adoc | 14 +-
.../ROOT/partials/security/user-registration.adoc | 159 -----------------
.../modules/ROOT/partials/security/web-xml.adoc | 96 ----------
.../modules/ROOT/partials/security/webmodule.adoc | 25 +++
.../webmodule/auth/AuthenticationStrategy.java | 10 +-
.../auth/AuthenticationStrategyAbstract.java | 18 +-
.../auth/AuthenticationStrategyBasicAuth.java | 18 +-
.../auth/AuthenticationStrategyDefault.java | 9 +-
viewers/wicket/adoc/antora.yml | 2 +-
viewers/wicket/adoc/modules/ROOT/pages/about.adoc | 2 +-
.../ROOT/pages/setup-and-configuration.adoc | 4 +-
34 files changed, 258 insertions(+), 730 deletions(-)
diff --git a/antora/components/refguide-index/modules/applib/pages/index/services/conmap/hooks/ContentMappingService_020-examples-and-usage.adoc b/antora/components/refguide-index/modules/applib/pages/index/services/conmap/hooks/ContentMappingService_020-examples-and-usage.adoc
index 01e0670..e62326f 100644
--- a/antora/components/refguide-index/modules/applib/pages/index/services/conmap/hooks/ContentMappingService_020-examples-and-usage.adoc
+++ b/antora/components/refguide-index/modules/applib/pages/index/services/conmap/hooks/ContentMappingService_020-examples-and-usage.adoc
@@ -6,7 +6,7 @@
// TODO: v2: this is an SPI, so maybe restfulobjects should define an "spi" module for this.
-The `ContentMappingService` supports the (default implementation of the) internal xref:core:runtime-services:ContentNegotiationService.adoc[ContentNegotiationService] SPI enabling the xref:vro:ROOT:about.adoc[RestfulObjects viewer] to represent domain objects in some other format as specified by the HTTP `Accept` header.
+The `ContentMappingService` supports the (default implementation of the) internal xref:refguide:viewer:index/restfulobjects/rendering/service/conneg/ContentNegotiationService.adoc[ContentNegotiationService] SPI enabling the xref:vro:ROOT:about.adoc[RestfulObjects viewer] to represent domain objects in some other format as specified by the HTTP `Accept` header.
For its part, the (default implementation of the) `ContentNegotiationService` will check _all_ available implementations of `ContentMappingService` to convert the domain object to the requested media type, rather than merely the first implementation found; in other words it uses the link:https://en.wikipedia.org/wiki/Chain-of-responsibility_pattern[chain-of-responsibility] pattern.
Services are checked in the ordering defined by the Spring link:https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/core/annotation/Order.html[@Order] annotation.
@@ -15,6 +15,6 @@ The mapped object used will be the first non-`null` result returned by an implem
== Related Services
-This service is a companion to the default implementation of the xref:core:runtime-services:ContentNegotiationService.adoc[ContentNegotiationService].
+This service is a companion to the default implementation of the xref:refguide:viewer:index/restfulobjects/rendering/service/conneg/ContentNegotiationService.adoc[ContentNegotiationService].
The framework implementations of `ContentMappingService` use the xref:refguide:applib:index/services/metamodel/MetaModelService.adoc[MetaModelService] to lookup any custom implementations of `CommandDtoProcessor`.
diff --git a/security/adoc/modules/ROOT/pages/usage-by-isis-viewers.adoc b/security/adoc/modules/ROOT/pages/usage-by-isis-viewers.adoc
index 11ed436..6ffbf89 100644
--- a/security/adoc/modules/ROOT/pages/usage-by-isis-viewers.adoc
+++ b/security/adoc/modules/ROOT/pages/usage-by-isis-viewers.adoc
@@ -24,7 +24,7 @@ include::vw:ROOT:partial$security/user-registration.adoc[]
== Restful Objects Viewer
-include::vro:ROOT:partial$security/web-xml.adoc[]
+include::vro:ROOT:partial$security/webmodule.adoc[]
[[vro-user-registration]]
=== User-registration
diff --git a/viewers/restfulobjects/adoc/antora.yml b/viewers/restfulobjects/adoc/antora.yml
index d23c210..9fc0f24 100644
--- a/viewers/restfulobjects/adoc/antora.yml
+++ b/viewers/restfulobjects/adoc/antora.yml
@@ -16,9 +16,9 @@
# under the License.
name: vro
-title: "Restful Objects Viewer"
+title: "REST API (Restful Objects Viewer)"
version: 2.0.0-M5
start_page: ROOT:about.adoc
nav:
- modules/ROOT/nav.adoc
-- modules/security/nav.adoc
\ No newline at end of file
+- modules/security/nav.adoc
diff --git a/viewers/restfulobjects/adoc/modules/ROOT/pages/about.adoc b/viewers/restfulobjects/adoc/modules/ROOT/pages/about.adoc
index fbce180..fa38a4a 100644
--- a/viewers/restfulobjects/adoc/modules/ROOT/pages/about.adoc
+++ b/viewers/restfulobjects/adoc/modules/ROOT/pages/about.adoc
@@ -1,11 +1,7 @@
-= Restful Objects Viewer
+= REST API (Restful Objects Viewer)
: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-aliases: guides:ugvro:ugvro.adoc
-
-WARNING: TODO: this content has not yet been reviewed/updated for v2.0
-
Apache Isis' Restful Objects viewer is an implementation of the link:http://restfulobjects.org[Restful Objects spec], which defines a generic way to expose a domain model through a REST (or more precisely, hypermedia) API. Having a REST API opens up an Apache Isis domain model to a huge variety of applications, from bespoke single-page apps, through integration scenarios, through providing an API for bulk-upload/migration from an existing system.
diff --git a/viewers/restfulobjects/adoc/modules/ROOT/pages/configuration-properties.adoc b/viewers/restfulobjects/adoc/modules/ROOT/pages/configuration-properties.adoc
deleted file mode 100644
index 7624592..0000000
--- a/viewers/restfulobjects/adoc/modules/ROOT/pages/configuration-properties.adoc
+++ /dev/null
@@ -1,195 +0,0 @@
-= Configuration Properties
-
-: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 [...]
-
-WARNING: TODO: this content has not yet been reviewed/updated for v2.0
-
-The xref:refguide:config:about.adoc[Configuration Guide] includes a xref:refguide:config:sections/isis.viewer.restfulobjects.adoc[section] for the Restful Objects viewer.
-
-
-// TODO - v2 - detail on original config properties (not yet reviewed) currently commented out.
-
-//The Restful Objects viewer provides a couple of configuration option that extend/simplify/alter the representations generated from the Restful Objects specification.
-//
-//These configuration properties are typically stored in `WEB-INF/viewer_restfulobjects.properties`.
-//However, you can place all configuration properties into `WEB-INF/isis.properties` if you wish (the configuration properties from all config files are merged together).
-//
-//
-//== Standard
-//
-//The following configuration properties are supported:
-//
-//.Restful Objects Viewer Configuration Properties
-//[cols="2a,1,3", options="header"]
-//|===
-//|Property
-//|Value +
-//(_default value_)
-//|Description
-//
-//|`isis.viewer.restfulobjects.` +
-//`honorUiHints`
-//| `true`,`false` (`_false_`)
-//|A mechanism for reducing the number of round-trips by eagerly rendering collections; discussed xref:vro:ROOT:ro-spec.adoc#honor-ui-hints[here].
-//
-//|`isis.viewer.restfulobjects.` +
-//`strictAcceptChecking`
-//| `true`,`false` (`_false_`)
-//|Whether to strictly enforce the `Accept` header checking for the default RO-spec representations (by the
-//`ContentNegotiationServiceForRestfulObjectsV1_0` service). Will otherwise accept anything. +
-//
-//This is convenient because it allows the `Accept` header to be set to that of the
-//xref:vro:ROOT:simplified-representations.adoc[Apache Isis profile] for all resources, rather than simply the
-//handful of resources that supported that profile.
-//
-//|===
-//
-//In addition:
-//
-//[cols="2a,1,3a", options="header"]
-//|===
-//|Property
-//|Value +
-//(default value)
-//|Description
-//
-//|`isis.services.` +
-//`ContentNegotiation-` +
-//`ServiceXRoDomainType` +
-//.`prettyPrint`
-//| `true`,`false` +
-//(depends)
-//|If a domain object has been mapped to the specified JAXB `x-ro-domain-type`, then determines whether the result is pretty-printed or not. +
-//
-//If no configuration property is available, then the defaults is determined by the xref:refguide:config:about.adoc#deployment-types[deployment type]: production mode disables pretty printing, while prototype mode enables it.
-//
-//|===
-//
-//
-//
-//== Deprecated
-//
-//There are also a number of configuration properties that can be used to suppress or simplify the default RO-spec
-//representations.
-//
-//These configuration properties pre-date the support for the Apache Isis profile, and are limited by the fact that they are global configuration settings, so cannot be influenced on a request-by-request basis (as is the case with the `Accept` header used for the Apache Isis profile).
-//They have therefore been deprecated, and may be removed in the future.
-//
-//Nevertheless, those configuration properties are:
-//
-//.Deprecated Configuration Properties
-//[cols="2a,1,3", options="header"]
-//|===
-//|Property
-//|Value +
-//(_default value_)
-//|Description
-//
-//|`isis.viewer.restfulobjects.` +
-//`suppressDescribedByLinks`
-//| `true`,`false` (`_false_`)
-//|Suppresses the "describedby" links (on all representations)
-//
-//|`isis.viewer.restfulobjects.` +
-//`suppressUpdateLink`
-//| `true`,`false` (`_false_`)
-//|suppresses the "update" link (on object representation)
-//
-//|`isis.viewer.restfulobjects.` +
-//`suppressMemberId`
-//| `true`,`false` (`_false_`)
-//|suppresses the "id" json-prop for object members (on object representation and member detail representations)
-//
-//|`isis.viewer.restfulobjects.` +
-//`suppressMemberLinks`
-//| `true`,`false` (`_false_`)
-//|suppresses the "links" json-prop for object members (on the object representation and member detail representations)
-//
-//|`isis.viewer.restfulobjects.` +
-//`suppressMemberExtensions`
-//| `true`,`false` (`_false_`)
-//|suppresses the "extensions" json-prop for object members (on the object representation and member detail representations)
-//
-//|`isis.viewer.restfulobjects.` +
-//`suppressMemberDisabledReason`
-//| `true`,`false` (`_false_`)
-//|suppresses the "disabledReason" json-prop for object members (on the object representation and member detail representations)
-//
-//|`isis.viewer.restfulobjects.` +
-//`objectPropertyValuesOnly`
-//| `true`,`false` (`_false_`)
-//| See discussionp below.
-//|
-//
-//|===
-//
-//
-//For example, these configuration properties could all be added in the `WEB-INF/viewer_restfulobjects.properties`):
-//
-//[source,ini]
-//----
-//isis.viewer.restfulobjects.suppressDescribedByLinks=true
-//isis.viewer.restfulobjects.suppressUpdateLink=true
-//isis.viewer.restfulobjects.suppressMemberId=true
-//isis.viewer.restfulobjects.suppressMemberLinks=true
-//isis.viewer.restfulobjects.suppressMemberExtensions=true
-//isis.viewer.restfulobjects.suppressMemberDisabledReason=true
-//----
-//
-//
-//[NOTE]
-//====
-//If these configuration settings are set in conjunction with using the xref:vro:ROOT:simplified-representations.adoc#apache-isis-profile[Apache Isis profile], then the special `$$ro` property in the representations with reflect these settings.
-//====
-//
-//
-//
-//If the `objectPropertyValuesOnly` configuration property is set:
-//
-//[source,ini]
-//----
-//isis.viewer.restfulobjects.objectPropertyValuesOnly=true
-//----
-//
-//then this generates a representation such as:
-//
-//[source,javascript]
-//----
-//{
-// "title" : "Buy milk due by 2014-10-27",
-// "domainType" : "TODO",
-// "instanceId" : "0",
-// "members" : {
-// "description" : "Buy milk",
-// "category" : "Domestic",
-// "subcategory" : "Shopping",
-// "complete" : false,
-// "versionSequence" : 1,
-// "relativePriority" : 2,
-// "dueBy" : "2014-10-27",
-// "cost" : "0.75",
-// "notes" : null,
-// "attachment" : null,
-// "doc" : null
-// },
-// "links" : [
-// {
-// "rel" : "self",
-// "href" : "http://localhost:8080/restful/objects/TODO/0",
-// "method" : "GET",
-// "type" : "application/json;profile=\"urn:org.restfulobjects:repr-types/object\"",
-// "title" : "Buy milk due by 2014-10-27"
-// },
-// {
-// "rel" : "describedby",
-// "href" : "http://localhost:8080/restful/domain-types/TODO",
-// "method" : "GET",
-// "type" : "application/json;profile=\"urn:org.restfulobjects:repr-types/domain-type\""
-// }
-// ],
-// "extensions" : {
-// "oid" : "TODO:0"
-// },
-//}
-//----
-//
diff --git a/viewers/restfulobjects/adoc/modules/ROOT/pages/architecture.adoc b/viewers/restfulobjects/adoc/modules/ROOT/pages/content-negotiation.adoc
similarity index 85%
rename from viewers/restfulobjects/adoc/modules/ROOT/pages/architecture.adoc
rename to viewers/restfulobjects/adoc/modules/ROOT/pages/content-negotiation.adoc
index 52ca4f5..593f02c 100644
--- a/viewers/restfulobjects/adoc/modules/ROOT/pages/architecture.adoc
+++ b/viewers/restfulobjects/adoc/modules/ROOT/pages/content-negotiation.adoc
@@ -1,4 +1,4 @@
-= Architecture
+= Content Negotiation
: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 [...]
@@ -19,14 +19,14 @@ Instead you need to create some sort of stable facade over your domain entities,
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:userguide:fun:overview.adoc#view-models[view model].
-This is then surfaced over the RO viewer.
+This is then surfaced by 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:pjdo:ROOT:mapping-guide.adoc#mapping-to-a-view[mapping this] to a (read-only) entity.
+* a second option is to solve the problem at the persistence layer, by defining a (SQL) view in the database.
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.
+If the underlying tables change (as the result of a change in their corresponding domain entities) then the SQL 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.
+
@@ -47,19 +47,19 @@ image::restfulobjects/facade-choices.png[width="700px"]
Here we focus on implementing a facade at the viewer (presentation) layer:
-* xref:core:runtime-services:ContentNegotiationService.adoc[ContentNegotiationService]
+* xref:refguide:viewer:index/restfulobjects/rendering/service/conneg/ContentNegotiationService.adoc[ContentNegotiationService]
+
As noted above, there can be multiple implementations of the
-xref:core:runtime-services:ContentNegotiationService.adoc[ContentNegotiationService], each one handling a particular HTTP `Accept` header.
+xref:refguide:viewer:index/restfulobjects/rendering/service/conneg/ContentNegotiationService.adoc[ContentNegotiationService], each one handling a particular HTTP `Accept` header.
If the implementation does not recognize the value of the header, if can simply return `null`.
+
The framework provides a number of implementations; an implementation that handles the
-xref:vro:ROOT:simplified-representations.adoc[simplified representation] of the Apache Isis profile; an implementation that provides support for the `x-ro-domain-type` parameter, and a default/fallback implementation that returns the representations defined by the RO spec.
+xref:vro:ROOT:content-negotiation/apache-isis-v1-profile.adoc[simplified representation] of the Apache Isis profile; an implementation that provides support for the `x-ro-domain-type` parameter, and a default/fallback implementation that returns the representations defined by the RO spec.
* xref:refguide:applib:index/services/conmap/ContentMappingService.adoc[ContentMappingService]
+
The xref:refguide:applib:index/services/conmap/ContentMappingService.adoc[ContentMappingService] is used by the implementation of
-xref:core:runtime-services:ContentNegotiationService.adoc[ContentNegotiationService] that recognizes the `x-ro-domain-type`, its role being to transform a domain object (usually an entity) into some other form (usually a DTO), as specified by the `x-ro-domain-type` parameter.
+xref:refguide:viewer:index/restfulobjects/rendering/service/conneg/ContentNegotiationService.adoc[ContentNegotiationService] that recognizes the `x-ro-domain-type`, its role being to transform a domain object (usually an entity) into some other form (usually a DTO), as specified by the `x-ro-domain-type` parameter.
There can be many such implementations, each handling a different target domain type.
This diagram shows how these services collaborate:
diff --git a/viewers/restfulobjects/adoc/modules/ROOT/pages/simplified-representations.adoc b/viewers/restfulobjects/adoc/modules/ROOT/pages/content-negotiation/apache-isis-v1-profile.adoc
similarity index 85%
rename from viewers/restfulobjects/adoc/modules/ROOT/pages/simplified-representations.adoc
rename to viewers/restfulobjects/adoc/modules/ROOT/pages/content-negotiation/apache-isis-v1-profile.adoc
index d0a002d..e2e7f0e 100644
--- a/viewers/restfulobjects/adoc/modules/ROOT/pages/simplified-representations.adoc
+++ b/viewers/restfulobjects/adoc/modules/ROOT/pages/content-negotiation/apache-isis-v1-profile.adoc
@@ -3,9 +3,6 @@
: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 [...]
-WARNING: TODO: this content has not yet been reviewed/updated for v2.0.
-See also draft ... xref:vro:ROOT:simplified-representations-v2.adoc[Simplified Representations v2]
-
The representations defined by the RO spec are very rich and enable complex client-side applications to be built.
However, their sophistication can be an impediment to their use if one wishes to write a simple app using third-party components that expect to consume much simpler representations.
Examples of such tools are
@@ -15,7 +12,7 @@ link:https://github.com/mgcrea/angular-strap[Angular Strap].
Apache Isis also provides support for its own simplified representation for the most commonly-used representations.
This is implemented using the `ContentNegotiationService` described in the
-xref:vro:ROOT:architecture.adoc[architecture] chapter.
+xref:vro:ROOT:content-negotiation.adoc[architecture] chapter.
@@ -23,5 +20,4 @@ include::simplified-representations/apache-isis-profile.adoc[leveloffset=+1]
include::simplified-representations/domain-object.adoc[leveloffset=+1]
include::simplified-representations/object-collection.adoc[leveloffset=+1]
include::simplified-representations/action-invocation.adoc[leveloffset=+1]
-include::simplified-representations/other-representations.adoc[leveloffset=+1]
include::simplified-representations/configuration-properties.adoc[leveloffset=+1]
diff --git a/viewers/restfulobjects/adoc/modules/ROOT/pages/simplified-representations-v2.adoc b/viewers/restfulobjects/adoc/modules/ROOT/pages/content-negotiation/apache-isis-v2-profile.INCOMPLETE.adoc
similarity index 100%
rename from viewers/restfulobjects/adoc/modules/ROOT/pages/simplified-representations-v2.adoc
rename to viewers/restfulobjects/adoc/modules/ROOT/pages/content-negotiation/apache-isis-v2-profile.INCOMPLETE.adoc
diff --git a/viewers/restfulobjects/adoc/modules/ROOT/pages/simplified-representations/other-representations.adoc b/viewers/restfulobjects/adoc/modules/ROOT/pages/content-negotiation/other-representations.adoc
similarity index 73%
rename from viewers/restfulobjects/adoc/modules/ROOT/pages/simplified-representations/other-representations.adoc
rename to viewers/restfulobjects/adoc/modules/ROOT/pages/content-negotiation/other-representations.adoc
index 6aefdda..e30d7ad 100644
--- a/viewers/restfulobjects/adoc/modules/ROOT/pages/simplified-representations/other-representations.adoc
+++ b/viewers/restfulobjects/adoc/modules/ROOT/pages/content-negotiation/other-representations.adoc
@@ -5,11 +5,10 @@
-Sometimes though you may want to extend or change the representations generated. This might be because you want to
-write a RESTful client that uses a particular library (say a JavaScript library or web components) that can only handle representations in a certain form.
+Sometimes though you may want to extend or change the representations generated.
+This might be because you want to write a RESTful client that uses a particular library (say a JavaScript library or web components) that can only handle representations in a certain form.
-Or, you might want to have Apache Isis generate representations according to some other "standard", of which there are
-many:
+Or, you might want to have Apache Isis generate representations according to some other "standard", of which there are many:
* Mike Kelly's http://stateless.co/hal_specification.html[HAL] specification
* Mike Amundsen's http://amundsen.com/media-types/collection/[Collection+JSON] specification
@@ -24,13 +23,12 @@ A good discussion about the relative merits of several of these different hyperm
Or, of course, you may have your own internal specification that you wish to use.
Supporting any of these alternative representations can be achieved by providing a suitable implementation of
-`ContentNegotiationService`. The existing implementations (eg `ContentNegotiationServiceSimplified`) can be used as a
-starting point.
+`ContentNegotiationService`.
+The existing implementations can be used as a starting point.
-[NOTE]
+[CAUTION]
====
-These will, admittedly, need to access the internal APIs for the Apache Isis metamodel, and you should be aware that
-these are not formal API; they may change over time. That said, they are very stable and have not changed
-significantly over the last few years.
+Any custom implementations will need to access the internal APIs for the Apache Isis metamodel.
+You should be aware that these are not formal API.
====
diff --git a/viewers/restfulobjects/adoc/modules/ROOT/pages/simplified-representations/action-invocation.adoc b/viewers/restfulobjects/adoc/modules/ROOT/pages/content-negotiation/simplified-representations/action-invocation.adoc
similarity index 95%
rename from viewers/restfulobjects/adoc/modules/ROOT/pages/simplified-representations/action-invocation.adoc
rename to viewers/restfulobjects/adoc/modules/ROOT/pages/content-negotiation/simplified-representations/action-invocation.adoc
index bf5bcda..c9853b3 100644
--- a/viewers/restfulobjects/adoc/modules/ROOT/pages/simplified-representations/action-invocation.adoc
+++ b/viewers/restfulobjects/adoc/modules/ROOT/pages/content-negotiation/simplified-representations/action-invocation.adoc
@@ -5,7 +5,7 @@
-When an action is invoked, it can return a domain object, a list, a scalar, or return nothing.
+When an action is invoked (link:https://www.restfulobjects.org/spec/1.0/section-c/chapter-19.html[section 19]) it can return a domain object, a list, a scalar, or return nothing.
== Returning an Object
diff --git a/viewers/restfulobjects/adoc/modules/ROOT/pages/simplified-representations/apache-isis-profile.adoc b/viewers/restfulobjects/adoc/modules/ROOT/pages/content-negotiation/simplified-representations/apache-isis-profile.adoc
similarity index 74%
rename from viewers/restfulobjects/adoc/modules/ROOT/pages/simplified-representations/apache-isis-profile.adoc
rename to viewers/restfulobjects/adoc/modules/ROOT/pages/content-negotiation/simplified-representations/apache-isis-profile.adoc
index 363b497..a983d56 100644
--- a/viewers/restfulobjects/adoc/modules/ROOT/pages/simplified-representations/apache-isis-profile.adoc
+++ b/viewers/restfulobjects/adoc/modules/ROOT/pages/content-negotiation/simplified-representations/apache-isis-profile.adoc
@@ -6,31 +6,30 @@
-The RO spec uses the standard `Accept` header for content negotiation, and defines its own "profile" for the standard
-representations; these take the form:
+The RO spec uses the standard `Accept` header for content negotiation, and defines its own "profile" for the standard representations; these take the form:
[source]
----
Accept: application/json;profile="urn:org.restfulobjects:repr-types/xxx"
----
-where "xxx" varies by resource. The detail can be found in section 2.4.1 of the RO spec.
+where "xxx" varies by resource.
+The detail can be found in link:https://www.restfulobjects.org/spec/1.0/section-a/chapter-02.html#_2-4-1-representationtype-profile-parameter[section 2.4.1] of the RO spec.
-The Apache Isis viewer also defines its own "Isis" profile which enables the client to request simplified
-representations for the most frequently accessed resources. This is done by specifying an `Accept` header of:
+The Apache Isis viewer also defines its own "Isis" profile which enables the client to request simplified representations for the most frequently accessed resources.
+This is done by specifying an `Accept` header of:
[source]
----
Accept: application/json;profile="urn:org.apache.isis/v1"
----
-Not every resource supports this header, but the most commonly accessed ones do. In each case the server will set the
+Not every resource supports this header, but the most commonly accessed ones do.
+In each case the server will set the
`Content-Type` header so that the client knows how to process the representation.
The link:https://www.youtube.com/watch?v=HMSqapQDY_4[screencast] demonstrates the feature.
-
-
The sections below explain in a little more detail what is returned when this profile is activated.
diff --git a/viewers/restfulobjects/adoc/modules/ROOT/pages/simplified-representations/configuration-properties.adoc b/viewers/restfulobjects/adoc/modules/ROOT/pages/content-negotiation/simplified-representations/configuration-properties.adoc
similarity index 94%
rename from viewers/restfulobjects/adoc/modules/ROOT/pages/simplified-representations/configuration-properties.adoc
rename to viewers/restfulobjects/adoc/modules/ROOT/pages/content-negotiation/simplified-representations/configuration-properties.adoc
index af008dc..95db0fe 100644
--- a/viewers/restfulobjects/adoc/modules/ROOT/pages/simplified-representations/configuration-properties.adoc
+++ b/viewers/restfulobjects/adoc/modules/ROOT/pages/content-negotiation/simplified-representations/configuration-properties.adoc
@@ -12,6 +12,6 @@ are limited by the fact that they are global configuration settings, so cannot b
basis (as is the case with the `Accept` header used for the Apache Isis profile). They have therefore been
deprecated, and may be removed in the future.
-Details can be found in xref:vro:ROOT:configuration-properties.adoc#deprecated[here].
+Details can be found in xref:vro:ROOT:setup-and-configuration.adoc#deprecated[here].
diff --git a/viewers/restfulobjects/adoc/modules/ROOT/pages/simplified-representations/domain-object.adoc b/viewers/restfulobjects/adoc/modules/ROOT/pages/content-negotiation/simplified-representations/domain-object.adoc
similarity index 80%
rename from viewers/restfulobjects/adoc/modules/ROOT/pages/simplified-representations/domain-object.adoc
rename to viewers/restfulobjects/adoc/modules/ROOT/pages/content-negotiation/simplified-representations/domain-object.adoc
index e75a3c9..0ef99cf 100644
--- a/viewers/restfulobjects/adoc/modules/ROOT/pages/simplified-representations/domain-object.adoc
+++ b/viewers/restfulobjects/adoc/modules/ROOT/pages/content-negotiation/simplified-representations/domain-object.adoc
@@ -4,17 +4,15 @@
: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 [...]
+:dollar: $
+If a domain object resource (link:https://www.restfulobjects.org/spec/1.0/section-c/chapter-14.html[section 14]) is accessed with the Apache Isis profile, the resultant representation is a JSON object with simple key/value pairs for each property.
-If a domain object resource (section 14) is accessed with the Apache Isis profile, the resultant representation is a
-JSON object with simple key/value pairs for each property.
+The contents of any collections are also eagerly returned, consisting of an array of elements of each referenced object.
+Each such element contains key/value pairs of each property (in other words, a grid of data is returned).
+Each element also has a special `{dollar}{dollar}href` property (so that the client can easily navigate to a resource for that object) and a `{dollar}{dollar}title` property (to use as a label, eg the hyperlink text).
-The contents of any collections are also eagerly returned, consisting of an array of elements of each referenced
-object. Each such element contains key/value pairs of each property (in other words, a grid of data is returned).
-Each element also has a special `$$href` property (so that the client can easily navigate to a resource for that
-object) and a `$$title` property (to use as a label, eg the hyperlink text).
-
-In addition, the representation defined by the RO spec is also included, under a special `$$ro` property.
+In addition, the representation defined by the RO spec is also included, under a special `{dollar}{dollar}ro` property.
For example, in a todo app, accessing this resource:
diff --git a/viewers/restfulobjects/adoc/modules/ROOT/pages/simplified-representations/object-collection.adoc b/viewers/restfulobjects/adoc/modules/ROOT/pages/content-negotiation/simplified-representations/object-collection.adoc
similarity index 88%
rename from viewers/restfulobjects/adoc/modules/ROOT/pages/simplified-representations/object-collection.adoc
rename to viewers/restfulobjects/adoc/modules/ROOT/pages/content-negotiation/simplified-representations/object-collection.adoc
index 670e1f1..23d3e66 100644
--- a/viewers/restfulobjects/adoc/modules/ROOT/pages/simplified-representations/object-collection.adoc
+++ b/viewers/restfulobjects/adoc/modules/ROOT/pages/content-negotiation/simplified-representations/object-collection.adoc
@@ -5,9 +5,7 @@
-If a domain object collection (section 17) is accessed with this profile, then the resultant representation is as
-an array of elements of key/value for each referenced object, and again each element the containing the key/value
-pairs of the properties of that object (a grid, again). +
+If a domain object collection (link:https://www.restfulobjects.org/spec/1.0/section-c/chapter-17.html[section 17]) is accessed with this profile, then the resultant representation is as an array of elements of key/value for each referenced object, and again each element the containing the key/value pairs of the properties of that object (a grid, again).
In addition, the representation defined by the RO spec is also included, as a special object with a single `$$ro`
property.
diff --git a/viewers/restfulobjects/adoc/modules/ROOT/pages/health-check.adoc b/viewers/restfulobjects/adoc/modules/ROOT/pages/health-check.adoc
deleted file mode 100644
index 15b3475..0000000
--- a/viewers/restfulobjects/adoc/modules/ROOT/pages/health-check.adoc
+++ /dev/null
@@ -1,68 +0,0 @@
-= Health Check
-
-: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 [...]
-
-
-WARNING: TODO: this content has not yet been reviewed/updated for v2.0
-
-The xref:refguide:applib:index/services/health/HealthCheckService.adoc[HealthCheckService] SPI allows applications to provide an implementation of that service which can indicate the overall health of the application.
-The "health" is defined by the very simple `Health` class, where a non-null message indicates a problem, otherwise everything is ok:
-
-[source,java]
-----
-public class Health {
- public static Health ok() {
- return new Health(null);
- }
- public static Health error(String message) {
- return new Health(message);
- }
- ...
- public boolean getResult() { return message == null; }
- public String getMessage() { return message; }
-}
-----
-
-The Restful Objects viewer exposes this as `/health` REST endpoint:
-
-* If `HealthCheckService` has been implemented, then this will be called to obtain the `Health`.
-
-* If no implementation has been provided by the application, then an ok `Health` will be assumed.
-
-Either way, the viewer will serialize a `Health` object into JSON, with the mime type indicated as `application/json;profile="urn:org.restfulobjects:repr-types/health"`.
-
-Monitoring infrastructure or container orchestrators (such as Docker Swarm and Kubernetes) can then be configured to call this endpoint to check on the health of the application and take remedial action if not.
-
-== Session Management
-
-The Restful Objects viewer will execute the `HealthCheckService` using a hard-coded user and role:
-
-* the user name is: `__health`
-* the role is: `__health-role`
-
-This design means that there is no need to configure monitoring infrastructure with credentials or other such complexity; they can simply hit the health endpoint.
-
-Moreover (unless the `HealthCheckService` implementation uses the `WrapperFactory` to invoke actions), it shouldn't be needed to set up a security account for this user name.
-
-== REST API Mapping
-
-The `/restful/health` path must be specified as a "passThru" in `web.xml` so that no authentication challenge is issued.
-
-// TODO: v2: this has changed, because we now use `WebModule_Xxx` instead of `web.xml`, ie set this stuff up programmatically.
-
-[source,xml]
-.web.xml
-----
-<filter>
- <filter-name>IsisSessionFilterForRestfulObjects</filter-name>
- <filter-class>org.apache.isis.core.webapp.IsisSessionFilter</filter-class>
- ...
- <init-param>
- <param-name>passThru</param-name>
- <param-value>/restful/swagger,/restful/health</param-value>
- </init-param>
- ...
-</filter>
-----
-
-This is a comma separated list, so there may be other values also (for example `/restful/swagger`, as shown above).
diff --git a/viewers/restfulobjects/adoc/modules/ROOT/pages/hints-and-tips.adoc b/viewers/restfulobjects/adoc/modules/ROOT/pages/hints-and-tips.adoc
index 8691855..3661267 100644
--- a/viewers/restfulobjects/adoc/modules/ROOT/pages/hints-and-tips.adoc
+++ b/viewers/restfulobjects/adoc/modules/ROOT/pages/hints-and-tips.adoc
@@ -3,7 +3,6 @@
: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 [...]
-WARNING: TODO: this content has not yet been reviewed/updated for v2.0
This chapter provides some solutions for problems we've encountered ourselves or have been raised on the Apache Isis mailing lists.
@@ -12,8 +11,6 @@ Since the Restful Objects viewer is designed for computer programs to interact w
This section provides a few hints-and-tips to help you on your way.
-include::hints-and-tips/using-chrome-devtools.adoc[leveloffset=+1]
-include::hints-and-tips/angular-tips.adoc[leveloffset=+1]
include::hints-and-tips/pretty-printing.adoc[leveloffset=+1]
include::hints-and-tips/restful-image-property.adoc[leveloffset=+1]
include::hints-and-tips/view-model-as-parameter.adoc[leveloffset=+1]
diff --git a/viewers/restfulobjects/adoc/modules/ROOT/pages/hints-and-tips/angular-tips.adoc b/viewers/restfulobjects/adoc/modules/ROOT/pages/hints-and-tips/angular-tips.adoc
deleted file mode 100644
index b4fb220..0000000
--- a/viewers/restfulobjects/adoc/modules/ROOT/pages/hints-and-tips/angular-tips.adoc
+++ /dev/null
@@ -1,68 +0,0 @@
-[[angular-tips]]
-= Angular Tips
-
-: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 hypermedia API exposed by Apache Isis' Restful Objects viewer is intended be support both bespoke custom-written viewers as well as generic viewers. Indeed, we expect most clients consuming the API will be bespoke, not generic.
-
-This page captures one or two tips on using Angular to write such a bespoke client.
-
-
-== Invoking a GET link (eg invoking a query action)
-
-Suppose you have a `CustomerService` providing a `findCustomer` action:
-
-[source,java]
-----
-public class CustomerService {
- public String id() { return "customers"; }
- @Action(semantics=SemanticsOf.SAFE)
- public Customer findCustomer(
- @ParameterLayout(named="customerName")
- final String customerName) {
- ...
- }
-}
-----
-
-Restful Objects will expose this as action with the following link that looks something like:
-
-[source,javascript]
-----
-{
- "rel" : "urn:org.restfulobjects:rels/invoke",
- "href" : "http://localhost:8080/restful/services/customers/actions/findCustomer/invoke",
- "method" : "GET",
- "type" : "application/json;profile=\"urn:org.restfulobjects:repr-types/action-result\"",
- "arguments" : {
- "customerName" : {
- "value" : null
- }
- }
-}
-----
-
-You can then invoke this using Angular' `$resource` service as follows.
-
-[source,javascript]
-----
-var findCustomer = $resource("http://localhost:8080/restful/services/customers/actions/findCustomer/invoke?:queryString");
-var findCustomerArgs = {
- "customerName": {
- "value": "Fred"
- }
-};
-findCustomer.get({queryString: JSON.stringify(findCustomerArgs)}, function(data) { /* ... */ } )
-----
-
-Here the `:queryString` placeholder in the initial `$resource` constructor is expanded with a stringified version of the JSON object representing the args. Note how the `findCustomerArgs` is the same as the `"arguments"` attribute in the original link (with a value provided instead of `null`).
-
-
-== Invoking a PUT or POST link
-
-If the method is a PUT or a POST, then no `:queryString` placeholder is required in the URL, and the args are instead part of the body.
-
-Use `$resource.put(...)` or `$resource.post(...)` instead.
-
diff --git a/viewers/restfulobjects/adoc/modules/ROOT/pages/hints-and-tips/using-chrome-devtools.adoc b/viewers/restfulobjects/adoc/modules/ROOT/pages/hints-and-tips/using-chrome-devtools.adoc
deleted file mode 100644
index 62ab469..0000000
--- a/viewers/restfulobjects/adoc/modules/ROOT/pages/hints-and-tips/using-chrome-devtools.adoc
+++ /dev/null
@@ -1,8 +0,0 @@
-[[using-chrome-devtools]]
-= Using Chrome Dev Tools
-
-: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 [...]
-
-
-
-This link:https://www.youtube.com/watch?v=_-TOvVYWCHc[screencast] shows how to explore the Restful API using Chrome plugins/extensions, and how we use them to write end-2-end (TCK) tests for the Restful Objects viewer.
diff --git a/viewers/restfulobjects/adoc/modules/ROOT/pages/layout-resources.adoc b/viewers/restfulobjects/adoc/modules/ROOT/pages/layout-resources.adoc
index 2e81adb..c34737b 100644
--- a/viewers/restfulobjects/adoc/modules/ROOT/pages/layout-resources.adoc
+++ b/viewers/restfulobjects/adoc/modules/ROOT/pages/layout-resources.adoc
@@ -2,9 +2,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 [...]
-WARNING: TODO: this content has not yet been reviewed/updated for v2.0
-Apache Isis' Restful Objects viewer provides a number of additional resource endpoints that provide representations of the object layout (as per xref:refguide:applib:index/services/grid/GridService.adoc[GridService]) and of the menu layout (as per xref:refguide:applib:index/services/menu/MenuBarsService.adoc[MenuBarsService]).
+Apache Isis' Restful Objects viewer provides a number of additional resource endpoints (not defined in the xref:ro-spec.adoc[RO spec]) that provide representations of the object layout (as per xref:refguide:applib:index/services/grid/GridService.adoc[GridService]) and of the menu layout (as per xref:refguide:applib:index/services/menu/MenuBarsService.adoc[MenuBarsService]).
This chapter provides details of these resources, the link ``Rel``s to access them, and the resultant representations.
@@ -49,7 +48,7 @@ For example, the xref:docs:starters:helloworld.adoc[Hello World starter app] has
Note that exactly one `<mb3:menu>` must have the `unreferencedActions` flag set.
Any service actions that are not explicitly listed will be added to this menu.
-The representation returned by home page resource (section 5.2 of the RO spec v1.0) has been extended to provide a link to this resource:
+The representation returned by home page resource (link:https://www.restfulobjects.org/spec/1.0/section-b/chapter-05.html#5.2-representation[section 5.2 of the RO spec v1.0]) has been extended to provide a link to this resource:
[source,javascript]
----
@@ -106,7 +105,7 @@ This can also be obtained in JSON format in the usual way (by specifying an HTTP
== Domain Object Icon
-The representation returned by the domain object resource (section 14.4 of the RO spec v1.0) has been extended to provide a link to the icon image (`.png`) to use:
+The representation returned by the domain object resource (link:https://www.restfulobjects.org/spec/1.0/section-c/chapter-14.html#14.4-representation[section 14.4] of the RO spec v1.0) has been extended to provide a link to the icon image (`.png`) to use:
[source,javascript]
----
@@ -134,7 +133,7 @@ Typically this is the contents of the `Xxx.layout.xml` file (where `Xxx` is the
For example, in the xref:docs:starters:helloworld.adoc[Hello World starter app] the `HelloWorld` domain object has a layout defined by `HelloWorld.layout.xml`.
-The representation returned by the domain object resource (section 14.4 of the RO spec v1.0) has been extended to provide a link to this resource:
+The representation returned by the domain object resource (link:https://www.restfulobjects.org/spec/1.0/section-c/chapter-14.html#14.4-representation[section 14.4] of the RO spec v1.0) has been extended to provide a link to this resource:
[source,javascript]
----
@@ -225,7 +224,7 @@ This can also be obtained as JSON (using `Accept: application/json` HTTP header)
== Domain Type Layout
-The representation of the domain types resource (section 22.2 of RO spec v1.0) has also been extended to return the (type) layout:
+The representation of the domain types resource (link:https://www.restfulobjects.org/spec/1.0/section-d/chapter-22.html#22.2-representation[section 22.2] of RO spec v1.0) has also been extended to return the (type) layout:
[source,javascript]
----
diff --git a/viewers/restfulobjects/adoc/modules/ROOT/pages/other-resources.adoc b/viewers/restfulobjects/adoc/modules/ROOT/pages/other-resources.adoc
deleted file mode 100644
index 8aab42b..0000000
--- a/viewers/restfulobjects/adoc/modules/ROOT/pages/other-resources.adoc
+++ /dev/null
@@ -1,7 +0,0 @@
-= Other Resources
-
-: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-aliases: guides:ugvw:ugvw.adoc
-
-WARNING: TODO: document 3rd party tutorials and resources.
-
diff --git a/viewers/restfulobjects/adoc/modules/ROOT/pages/ro-spec.adoc b/viewers/restfulobjects/adoc/modules/ROOT/pages/ro-spec.adoc
index 43fb3fd..d7b7635 100644
--- a/viewers/restfulobjects/adoc/modules/ROOT/pages/ro-spec.adoc
+++ b/viewers/restfulobjects/adoc/modules/ROOT/pages/ro-spec.adoc
@@ -2,11 +2,10 @@
: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 [...]
-WARNING: TODO: this content has not yet been reviewed/updated for v2.0
The Restful Objects v1.0 specification defines a comprehensive hypermedia API, consisting of HTTP resources and corresponding JSON representations, for accessing and manipulating a domain object model.
-The Restful Objects spec can be downloaded from link:http://restfulobjects.org[here] as either a PDF or Word doc.
+The Restful Objects spec is available online at link:https://restfulobjects.org[https://restfulobjects.org].
== Goals of the Spec
@@ -41,17 +40,12 @@ image::restfulobjects/ro-spec-resources-and-representations.png[width="800px"]
The resource URLs are always well-defined, but Apache Isis' implementation allows for different representations to be returned, using content negotiation.
This is discussed further below.
-[NOTE]
-====
-In fact, there's nothing in Apache Isis to prevent you from defining your own REST controllers to provide custom resource URLs.
-One use case might be to support user registration/authentication, a topic out-of-scope of the RO spec itself.
-====
== Apache Isis' implementation
The Restful Objects viewer is Apache Isis' implementation of the Restful Objects spec.
It implements all the mandatory features of the specification.
-It also implements some of the optional capabilities (as defined in section 3 of the RO spec, and as represented in the version resource, section 8.1):
+It also implements some of the optional capabilities (as defined in link:https://www.restfulobjects.org/spec/1.0/section-a/chapter-03.html[section 3] of the RO spec, and as represented in the version resource, section 8.1):
[cols="1a,1a,1a",options="header"]
|===
@@ -86,16 +80,16 @@ It also implements some of the optional capabilities (as defined in section 3 of
== Extensions
-The Restful Objects viewer also implements some of the "future ideas" that are out of scope for the RO spec v1.0, but described in section 34, "ideas for future extensions".
+The Restful Objects viewer also implements some of the "future ideas" that are out of scope for the RO spec v1.0, but described in link:http://www.restfulobjects.org/spec/1.0/section-e/chapter-34.html[chapter 34], "ideas for future extensions".
-=== Content Negotiation (34.1)
+=== Content Negotiation
-Apache Isis provides two levels of support for content negotiation.
+Apache Isis provides two levels of support for content negotiation (section link:http://www.restfulobjects.org/spec/1.0/section-e/chapter-34.html#34.1-content-negotiation[34.1])
==== `x-ro-domain-type`
The first level is very similar to the "Domain Model Agnostic" approach sketched out in the RO spec.
-The client can send an `x-ro-domain-type` parameter for either domain object representations (section 14 of the spec) or action invocation results (section 19 of the spec).
+The client can send an `x-ro-domain-type` parameter for either domain object representations (link:http://www.restfulobjects.org/spec/1.0/section-c/chapter-14.html[section 14] of the spec) or action invocation results (link:http://www.restfulobjects.org/spec/1.0/section-c/chapter-19.html[section 19]).
This can be combined with either `application/json` or
`application/xml`.
@@ -107,7 +101,7 @@ Accept: application/xml;x-ro-domain-type="com.mycompany.viewmodels.v2.CustomerVi
----
The server will use the xref:refguide:applib:index/services/conmap/ContentMappingService.adoc[ContentMappingService] to attempt to transform the domain object into the requested `x-ro-domain-type`.
-The whole process is discussed in more detail in the xref:vro:ROOT:architecture.adoc[architecture] chapter.
+The whole process is discussed in more detail in the xref:vro:ROOT:content-negotiation.adoc[architecture] chapter.
==== Apache Isis profile
@@ -121,22 +115,20 @@ link:https://github.com/mgcrea/angular-strap[Angular Strap].
This support is discussed further in the xref:vro:ROOT:simplified-representations.adoc[simplified representations]
chapter.
-=== Minimizing Round-trips (34.4)
+=== Minimizing Round-trips
-The Restful Objects viewer supports the `x-ro-follow-links` query parameter in a way very similar to that suggested in the RO spec, the main point being to avoid the "N+1" problem of too many (slow) network calls.
+The Restful Objects viewer supports the `x-ro-follow-links` query parameter in a way very similar to that suggested in the RO spec (section link:https://www.restfulobjects.org/spec/1.0/section-e/chapter-34.html#34.4-minimizing-round-trips-(x-ro-follow-links)[34.4]), the main point being to avoid the "N+1" problem of too many (slow) network calls.
For example, using this feature one can load a grid of data in a single call.
(That said, the xref:vro:ROOT:simplified-representations.adoc[simplified representations]
supported by Restful Objects viewer also support this use case, albeit in way that deviates from the RO spec).
-This link:https://www.youtube.com/watch?v=hSKnqqBQ7Zo[screencast] demonstrates the Restful Object viewer's support for `x-ro-follow-links` parameter, using the link:http://github.com/apache/isis-app-kitchensink[Isis addons' kitchensink] app as the example, This app contains three entities, `Grandparent`, `Parent` and `ChildJdo` that define a hierarchy of 1:m relationships.
+For example, with an app containing three entities, `Grandparent`, `Parent` and `ChildJdo` that define a hierarchy of 1:m relationships, we could define the following queries:
-The queries that are shown in the screencast include:
-
-* show parent and its children (titles) +
+* show parent and its children (titles)
+
pass:[<pre>http://localhost:8080/restful/objects/PARENT/0?x-ro-follow-links=members[children\].value]
-* show parent and its children (full details) +
+* show parent and its children (full details)
+
pass:[<pre>http://localhost:8080/restful/objects/PARENT/0?x-ro-follow-links=members[children\].value.href]
@@ -154,11 +146,6 @@ By default the representations generated by Restful Objects ignore any Apache Is
In particular, if a collection is annotated then `Render(EAGERLY)` then the contents of the collection are _not_ eagerly embedded in the object representation.
However, this behaviour can be overridden globally using the
-xref:refguide:config:sections/isis.viewer.restfulobjects.adoc#isis.viewer.restfulobjects.honor-ui-hints[isis.viewer.restfulobjects.adoc#isis.viewer.restfulobjects.honor-ui-hints] configuration property:
-
-[source,ini]
-----
-isis.viewer.restfulobjects.adoc#isis.viewer.restfulobjects.honor-ui-hints=true
-----
+xref:refguide:config:sections/isis.viewer.restfulobjects.adoc#isis.viewer.restfulobjects.honor-ui-hints[isis.viewer.restfulobjects.honor-ui-hints] configuration property:
This means that standard Apache Isis annotations can be used as a simple way to obtain follow-links (driven from the server model, though, rather than the requesting client).
diff --git a/viewers/restfulobjects/adoc/modules/ROOT/pages/security.adoc b/viewers/restfulobjects/adoc/modules/ROOT/pages/security.adoc
index 3d6c2b6..44bbdee 100644
--- a/viewers/restfulobjects/adoc/modules/ROOT/pages/security.adoc
+++ b/viewers/restfulobjects/adoc/modules/ROOT/pages/security.adoc
@@ -2,10 +2,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 [...]
-WARNING: TODO: this content has not yet been reviewed/updated for v2.0
+include::vro:ROOT:partial$security/webmodule.adoc[]
-include::vro:ROOT:partial$security/web-xml.adoc[]
-
-== User-registration
-
-include::vro:ROOT:partial$security/user-registration.adoc[]
diff --git a/viewers/restfulobjects/adoc/modules/ROOT/pages/setup-and-configuration.adoc b/viewers/restfulobjects/adoc/modules/ROOT/pages/setup-and-configuration.adoc
new file mode 100644
index 0000000..202156c
--- /dev/null
+++ b/viewers/restfulobjects/adoc/modules/ROOT/pages/setup-and-configuration.adoc
@@ -0,0 +1,132 @@
+= Setup and Configuration
+
+: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 [...]
+
+
+This section describes how to include the Restful Objects viewer's module and set its configuration properties.
+
+
+== Maven pom.xml
+
+=== Dependency Management
+
+If your application inherits from the Apache Isis starter app (`org.apache.isis.app:isis-app-starter-parent` then that will define the version automatically:
+
+[source,xml,subs="attributes+"]
+.pom.xml
+----
+<parent>
+ <groupId>org.apache.isis.app</groupId>
+ <artifactId>isis-app-starter-parent</artifactId>
+ <version>{page-isisrel}</version>
+ <relativePath/>
+</parent>
+----
+
+Alternatively, import the core BOM.
+This is usually done in the top-level parent pom of your application:
+
+[source,xml,subs="attributes+"]
+.pom.xml
+----
+<dependencyManagement>
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.isis.core</groupId>
+ <artifactId>isis-core</artifactId>
+ <version>{page-isisrel}</version>
+ <version>2.0.0-SNAPSHOT</version>
+ <scope>import</scope>
+ <type>pom</type>
+ </dependency>
+ </dependencies>
+</dependencyManagement>
+----
+
+
+=== Dependency
+
+In the webapp module of your application, add the following dependency:
+
+[source,xml]
+.pom.xml
+----
+<dependencies>
+ <dependency>
+ <groupId>org.apache.isis.mavendeps</groupId>
+ <artifactId>isis-mavendeps-webapp</artifactId>
+ <type>pom</type>
+ </dependency>
+</dependencies>
+----
+
+
+== Update AppManifest
+
+In your application's `AppManifest` (top-level Spring `@Configuration` used to bootstrap the app), import the
+
+[source,java]
+.AppManifest.java
+----
+@Configuration
+@Import({
+ ...
+ IsisModuleViewerRestfulObjectsViewer.class,
+ ...
+})
+public class AppManifest {
+}
+----
+
+
+== Configuration Properties
+
+The xref:refguide:config:about.adoc[Configuration Guide] includes a xref:refguide:config:sections/isis.viewer.restfulobjects.adoc[section] for the Restful Objects viewer.
+
+
+=== Standard
+
+Standard configuration properties:
+
+* xref:refguide:config:sections/isis.viewer.restfulobjects.adoc#isis.viewer.restfulobjects.base-uri[isis.viewer.restfulobjects.base-uri]
+
+* xref:refguide:config:sections/isis.viewer.restfulobjects.adoc#isis.viewer.restfulobjects.authentication.strategy-class-name[isis.viewer.restfulobjects.authentication.strategy-class-name]
++
+Security is discussed in more detail xref:security.adoc[here].
+
+* xref:refguide:config:sections/isis.viewer.restfulobjects.adoc#isis.viewer.restfulobjects.strict-accept-checking[isis.viewer.restfulobjects.strict-accept-checking]
+
+* xref:refguide:config:sections/isis.viewer.restfulobjects.adoc#isis.viewer.restfulobjects.honor-ui-hints[isis.viewer.restfulobjects.honor-ui-hints]
+
+
+
+=== Deprecated
+
+These configuration properties that can be used to suppress or simplify the default RO-spec representations.
+
+These configuration properties pre-date the support for the link:content-negotiation/simplified-representations/[Apache Isis profile], and are limited by the fact that they are global configuration settings, so cannot be influenced on a request-by-request basis (as is the case with the `Accept` header used for the Apache Isis profile).
+They have therefore been deprecated, and may be removed in the future.
+
+Nevertheless, those configuration properties are:
+
+* xref:refguide:config:sections/isis.viewer.restfulobjects.adoc#isis.viewer.restfulobjects.suppress-described-by-links[isis.viewer.restfulobjects.suppress-described-by-links]
+
+* xref:refguide:config:sections/isis.viewer.restfulobjects.adoc#isis.viewer.restfulobjects.suppress-update-link[isis.viewer.restfulobjects.suppress-update-link]
+
+* xref:refguide:config:sections/isis.viewer.restfulobjects.adoc#isis.viewer.restfulobjects.suppress-member-id[isis.viewer.restfulobjects.suppress-member-id]
+
+* xref:refguide:config:sections/isis.viewer.restfulobjects.adoc#isis.viewer.restfulobjects.suppress-member-links[isis.viewer.restfulobjects.suppress-member-links]
+
+* xref:refguide:config:sections/isis.viewer.restfulobjects.adoc#isis.viewer.restfulobjects.suppress-member-extensions[isis.viewer.restfulobjects.suppress-member-extensions]
+
+* xref:refguide:config:sections/isis.viewer.restfulobjects.adoc#isis.viewer.restfulobjects.suppress-member-disabled-reason[isis.viewer.restfulobjects.suppress-member-disabled-reason]
+
+* xref:refguide:config:sections/isis.viewer.restfulobjects.adoc#isis.viewer.restfulobjects.object-property-values-only[isis.viewer.restfulobjects.object-property-values-only]
+
+
+[NOTE]
+====
+If these configuration settings are set in conjunction with using the xref:vro:ROOT:content-negotiation/apache-isis-v1-profile.adoc#apache-isis-profile[Apache Isis profile], then the special `$$ro` property in the representations with reflect these settings.
+====
+
+
diff --git a/viewers/restfulobjects/adoc/modules/ROOT/partials/module-nav.adoc b/viewers/restfulobjects/adoc/modules/ROOT/partials/module-nav.adoc
index 4060253..c4cd556 100644
--- a/viewers/restfulobjects/adoc/modules/ROOT/partials/module-nav.adoc
+++ b/viewers/restfulobjects/adoc/modules/ROOT/partials/module-nav.adoc
@@ -1,15 +1,13 @@
-
+* xref:vro:ROOT:setup-and-configuration.adoc[Setup and Configuration]
* xref:vro:ROOT:ro-spec.adoc[RO Spec]
-* xref:vro:ROOT:architecture.adoc[Architecture]
-* xref:vro:ROOT:layout-resources.adoc[Layout Resources]
-* xref:vro:ROOT:health-check.adoc[Health Check]
-* xref:vro:ROOT:simplified-representations.adoc[Simplified Representations]
-* xref:vro:ROOT:simplified-representations-v2.adoc[Simplified Representations v2]
-* xref:vro:ROOT:configuration-properties.adoc[Configuration Properties]
+* xref:vro:ROOT:content-negotiation.adoc[Content Negotiation]
+** xref:vro:ROOT:content-negotiation/apache-isis-v1-profile.adoc[Apache Isis v1 Profile]
+//** xref:vro:ROOT:content-negotiation/apache-isis-v2-profile.INCOMPLETE.adoc[Simplified Representations v2]
+** xref:vro:ROOT:content-negotiation/other-representations.adoc[Other Representations]
* xref:vro:ROOT:security.adoc[Security]
+* xref:vro:ROOT:layout-resources.adoc[Layout Resources]
* xref:vro:ROOT:hints-and-tips.adoc[Hints-n-Tips]
-* xref:vro:ROOT:other-resources.adoc[Other Resources]
diff --git a/viewers/restfulobjects/adoc/modules/ROOT/partials/security/user-registration.adoc b/viewers/restfulobjects/adoc/modules/ROOT/partials/security/user-registration.adoc
deleted file mode 100644
index 065383a..0000000
--- a/viewers/restfulobjects/adoc/modules/ROOT/partials/security/user-registration.adoc
+++ /dev/null
@@ -1,159 +0,0 @@
-
-: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:
-
-
-WARNING: TODO - v2 : this documentation has not yet been updated.
-
-Unlike the Wicket viewer, the xref:vro:ROOT:about.adoc[REST API (Restful Objects viewer)] does *not* provide any sort of login page; rather it provides a pluggable authentication strategy, delegated to by the `IsisSessionFilter` filter (set up by the framework's web bootstrapping).
-The authentication strategy is responsible for ensuring that a session is available for the REST resource.
-
-The API of `AuthenticationSessionStrategy` is simply:
-
-[source,java]
-----
-package org.apache.isis.core.webapp.auth;
-...
-public interface AuthenticationSessionStrategy {
- AuthenticationSession lookupValid( // <1>
- ServletRequest servletRequest,
- ServletResponse servletResponse);
- void bind( // <2>
- ServletRequest servletRequest,
- ServletResponse servletResponse,
- AuthenticationSession authSession);
-}
-
-----
-<1> returns a valid `AuthenticationSession` for the specified request, response
-<2> binds (associates the provided `AuthenticationSession`) to the request and response
-
-Here `AuthenticationSession` is Apache Isis' internal API that represents a signed-on user.
-
-The framework provides a number of simple strategies:
-
-* `AuthenticationStrategyBasicAuth` implements the HTTP basic auth protocol (the pop-up dialog box shown by the web browser)
-* `AuthenticationSessionStrategyHeader` that simply reads the user identity from an HTTP header
-* `AuthenticationSessionStrategyTrusted` that always logs in with a special "exploration" user
-
-As you can see, none of these should be considered production-quality.
-
-The strategy is configured in `web.xml`; for example:
-
-// TODO: v2: this has changed, I think, because we now use `WebModule_Xxx` instead of `web.xml`, ie set this stuff up programmatically.
-
-[source,xml]
-----
-<filter>
- <filter-name>IsisSessionFilterForRestfulObjects</filter-name>
- <filter-class>org.apache.isis.core.webapp.IsisSessionFilter</filter-class>
- <init-param>
- <param-name>authenticationSessionStrategy</param-name>
- <param-value> <!--1-->
- org.apache.isis.viewer.restfulobjects.server.authentication.AuthenticationStrategyBasicAuth
- </param-value>
- </init-param>
- <init-param>
- <param-name>whenNoSession</param-name>
- <param-value>auto</param-value> <!--2-->
- </init-param>
- <init-param>
- <param-name>passThru</param-name>
- <param-value>/restful/swagger</param-value> <!--3-->
- </init-param>
-</filter>
-----
-<1> configure basic auth strategy
-<2> what to do if no session was found; we use `auto` so as to issue a 401 status code with basic authentication challenge if the request originated from a web browser. (Prior to `1.11.0` this parameter was set either to `basicAuthChallenge` (which works when requested from web browser) or to `unauthorized` (which works when requested from a suitably coded custom JavaScript app).
-<3> which paths are allowed to be accessed directly, without a session. The `/restful/swagger` path provides access to the SwaggerResource that dynamically generates swagger schema definition files from the Apache Isis metamodel.
-
-
-
-The above filter must then be chained before the servlet that actually handles the REST requests:
-
-// TODO: v2: this has changed, I think, because we now use `WebModule_Xxx` instead of `web.xml`, ie set this stuff up programmatically.
-
-[source,xml]
-----
-<filter-mapping>
- <filter-name>IsisSessionFilterForRestfulObjects</filter-name>
- <servlet-name>RestfulObjectsRestEasyDispatcher</servlet-name>
-</filter-mapping>
-...
-<servlet>
- <servlet-name>RestfulObjectsRestEasyDispatcher</servlet-name>
- <servlet-class>org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher</servlet-class>
-</servlet>
-----
-
-[NOTE]
-====
-The above `web.xml` fragments do _not_ constitute the full configuration for the Restful Objects viewer, just those parts that pertain to security.
-====
-
-
-
-
-
-Isis currently does not have any out-of-the-box support for user-registration for applications using only the Restful viewer. However, in principal the pieces do exist to put together a solution.
-
-The general idea is similar to the design of the Wicket viewer; define some subsidiary resources that can operate _without_ a user session in place, and which "reach into" the framework using headless access in order to setup the user.
-
-[TIP]
-====
-An alternative approach, possibly less work and overall of more value, would be to implement `AuthenticationSessionStrategy` for oAuth, in other words allow users to use their existing Google or Facebook account.
-====
-
-The following steps sketch out the solution in a little more detail:
-
-* Define some new Restful resources (cf link:https://github.com/apache/isis/blob/master/core/viewer-restfulobjects-server/src/main/java/org/apache/isis/viewer/restfulobjects/server/resources/DomainObjectResourceServerside.java[DomainServiceResourceServerside] that correspond to sign-up/register page, eg `SignupResource` +
-+
-[source,java]
-----
-@Path("/signup")
-public class SignupResource {
- ...
-}
-----
-
-* Create a new subclass of `RestfulObjectsApplication`, eg "CustomRestfulObjectsApplication" and register your resources +
-+
-[source,java]
-----
-public class CustomRestfulObjectsApplication extends RestfulObjectsApplication {
- public CustomRestfulObjectsApplication() {
- addClass(SignupResource.class);
- }
-}
-----
-
-* Register your application class in `web.xml` instead of the default: +
-+
-// TODO: v2: this may have changed, because we now use `WebModule_Xxx` instead of `web.xml`, ie set this stuff up programmatically.
-+
-[source,xml]
-----
-<context-param>
- <param-name>javax.ws.rs.Application</param-name>
- <param-value>com.mycompany.myapp.CustomRestfulObjectsApplication</param-value>
-</context-param>
-----
-
-So far this is just standard javax.rs stuff.
-
-Next, we need to ensure that a client can hit your new resource *with* the Apache Isis runtime in place, but without there being an Apache Isis session. For that....
-
-* create a subclass of the `AuthenticationSessionStrategy` that automatically returns a dummy session if the resource being accessed is "/restful/signup", say. +
-+
-You could do this by subclassing `AuthenticationStrategyBasicAuth`, but then using code from `AuthenticationStrategyBasicAuth` to return an "exploration" (or better, "signup") session if accessing the "/restful/signup" resource.
-
-* in the `SignUpResource` resource, you can then do a lookup of the `UserRegistrationService` in order to allow the user to be created: +
-+
-[source,java]
-----
-final UserRegistrationService userRegistrationService =
- IsisContext.getPersistenceSession().getServicesInjector().lookupService(UserRegistrationService.class);
-userRegistrationService.registerUser(userDetails);
-----
-
-Obviously the methods exposed by the `SignupResource` are up to you; ultimately they need to be able to gather information to populate the `UserDetails` object as passed to the `UserRegistrationService`.
diff --git a/viewers/restfulobjects/adoc/modules/ROOT/partials/security/web-xml.adoc b/viewers/restfulobjects/adoc/modules/ROOT/partials/security/web-xml.adoc
deleted file mode 100644
index aaf1bdc..0000000
--- a/viewers/restfulobjects/adoc/modules/ROOT/partials/security/web-xml.adoc
+++ /dev/null
@@ -1,96 +0,0 @@
-
-: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:
-
-
-WARNING: TODO v2 - this documentation has not yet been updated.
-
-
-Unlike the Wicket viewer, the xref:vro:ROOT:about.adoc[REST API (Restful Objects viewer)] does *not* provide any sort of login page; rather it provides a pluggable authentication strategy, delegated to by the `IsisSessionFilter` filter (set up by the framework's web bootstrapping).
-The authentication strategy is responsible for ensuring that a session is available for the REST resource.
-
-The API of `AuthenticationSessionStrategy` is simply:
-
-[source,java]
-----
-package org.apache.isis.core.webapp.auth;
-...
-public interface AuthenticationSessionStrategy {
- AuthenticationSession lookupValid( // <1>
- ServletRequest servletRequest,
- ServletResponse servletResponse);
- void bind( // <2>
- ServletRequest servletRequest,
- ServletResponse servletResponse,
- AuthenticationSession authSession);
-}
-
-----
-<1> returns a valid `AuthenticationSession` for the specified request, response
-<2> binds (associates the provided `AuthenticationSession`) to the request and response
-
-Here `AuthenticationSession` is Apache Isis' internal API that represents a signed-on user.
-
-The framework provides a number of simple strategies:
-
-* `AuthenticationStrategyBasicAuth` implements the HTTP basic auth protocol (the pop-up dialog box shown by the web browser)
-* `AuthenticationSessionStrategyHeader` that simply reads the user identity from an HTTP header
-* `AuthenticationSessionStrategyTrusted` that always logs in with a special "exploration" user
-
-As you can see, none of these should be considered production-quality.
-
-The strategy is configured in `web.xml`; for example:
-
-// TODO: v2: this has changed, I think, because we now use `WebModule_Xxx` instead of `web.xml`, ie set this stuff up programmatically.
-
-[source,xml]
-----
-<filter>
- <filter-name>IsisSessionFilterForRestfulObjects</filter-name>
- <filter-class>org.apache.isis.core.webapp.IsisSessionFilter</filter-class>
- <init-param>
- <param-name>authenticationSessionStrategy</param-name>
- <param-value> <!--1-->
- org.apache.isis.viewer.restfulobjects.server.authentication.AuthenticationStrategyBasicAuth
- </param-value>
- </init-param>
- <init-param>
- <param-name>whenNoSession</param-name>
- <param-value>auto</param-value> <!--2-->
- </init-param>
- <init-param>
- <param-name>passThru</param-name>
- <param-value>/restful/swagger</param-value> <!--3-->
- </init-param>
-</filter>
-----
-<1> configure basic auth strategy
-<2> what to do if no session was found; we use `auto` so as to issue a 401 status code with basic authentication challenge if the request originated from a web browser. (Prior to `1.11.0` this parameter was set either to `basicAuthChallenge` (which works when requested from web browser) or to `unauthorized` (which works when requested from a suitably coded custom JavaScript app).
-<3> which paths are allowed to be accessed directly, without a session. The `/restful/swagger` path provides access to the SwaggerResource that dynamically generates swagger schema definition files from the Apache Isis metamodel.
-
-
-
-The above filter must then be chained before the servlet that actually handles the REST requests:
-
-// TODO: v2: this has changed, I think, because we now use `WebModule_Xxx` instead of `web.xml`, ie set this stuff up programmatically.
-
-[source,xml]
-----
-<filter-mapping>
- <filter-name>IsisSessionFilterForRestfulObjects</filter-name>
- <servlet-name>RestfulObjectsRestEasyDispatcher</servlet-name>
-</filter-mapping>
-...
-<servlet>
- <servlet-name>RestfulObjectsRestEasyDispatcher</servlet-name>
- <servlet-class>org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher</servlet-class>
-</servlet>
-----
-
-[NOTE]
-====
-The above `web.xml` fragments do _not_ constitute the full configuration for the Restful Objects viewer, just those parts that pertain to security.
-====
-
-
-
diff --git a/viewers/restfulobjects/adoc/modules/ROOT/partials/security/webmodule.adoc b/viewers/restfulobjects/adoc/modules/ROOT/partials/security/webmodule.adoc
new file mode 100644
index 0000000..7e27cdb
--- /dev/null
+++ b/viewers/restfulobjects/adoc/modules/ROOT/partials/security/webmodule.adoc
@@ -0,0 +1,25 @@
+
+: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 xref:vro:ROOT:about.adoc[REST API (Restful Objects viewer)] does *not* provide a login page.
+Instead it defines the authentication strategy SPI, delegated to by a filter.
+(For more detail on how this is wired together, see xref:refguide:viewer:index/restfulobjects/jaxrsresteasy4/webmodule/WebModuleJaxrsResteasy4.adoc[WebModuleJaxrsResteasy4].)
+
+The SPI is:
+
+* xref:refguide:viewer:index/restfulobjects/viewer/webmodule/auth/AuthenticationSessionStrategy.adoc[AuthenticationSessionStrategy]
+
+where xref:refguide:core:index/security/authentication/Authentication.adoc[Authentication] represents a signed-on user:
+
+
+The strategy is defined using this configuration property:
+
+* xref:refguide:config:sections/isis.viewer.restfulobjects.adoc#isis.viewer.restfulobjects.authentication.strategy-class-name[isis.viewer.restfulobjects.authentication.strategy-class-name]
+
+
+The framework currently provides only basic auth provided as a simple implementation, and this is the default.
+
+
+
diff --git a/viewers/restfulobjects/viewer/src/main/java/org/apache/isis/viewer/restfulobjects/viewer/webmodule/auth/AuthenticationStrategy.java b/viewers/restfulobjects/viewer/src/main/java/org/apache/isis/viewer/restfulobjects/viewer/webmodule/auth/AuthenticationStrategy.java
index 188445a..d73ec21 100644
--- a/viewers/restfulobjects/viewer/src/main/java/org/apache/isis/viewer/restfulobjects/viewer/webmodule/auth/AuthenticationStrategy.java
+++ b/viewers/restfulobjects/viewer/src/main/java/org/apache/isis/viewer/restfulobjects/viewer/webmodule/auth/AuthenticationStrategy.java
@@ -28,6 +28,8 @@ import org.apache.isis.core.security.authentication.manager.AuthenticationManage
/**
* Decouples the <code>IsisRestfulObjectsInteractionFilter</code> from the mechanism of obtaining the
* {@link Authentication}.
+ *
+ * @since 2.0 {@index}
*/
public interface AuthenticationStrategy {
@@ -36,7 +38,7 @@ public interface AuthenticationStrategy {
* @see AuthenticationManager#isSessionValid(Authentication)
*/
Authentication lookupValid(
- HttpServletRequest httpServletRequest,
+ HttpServletRequest httpServletRequest,
HttpServletResponse httpServletResponse);
/**
@@ -46,11 +48,11 @@ public interface AuthenticationStrategy {
* @param auth
*/
void bind(
- HttpServletRequest httpServletRequest,
- HttpServletResponse httpServletResponse,
+ HttpServletRequest httpServletRequest,
+ HttpServletResponse httpServletResponse,
Authentication auth);
void invalidate(
- HttpServletRequest httpServletRequest,
+ HttpServletRequest httpServletRequest,
HttpServletResponse httpServletResponse);
}
diff --git a/viewers/restfulobjects/viewer/src/main/java/org/apache/isis/viewer/restfulobjects/viewer/webmodule/auth/AuthenticationStrategyAbstract.java b/viewers/restfulobjects/viewer/src/main/java/org/apache/isis/viewer/restfulobjects/viewer/webmodule/auth/AuthenticationStrategyAbstract.java
index ff9ac66..711607b 100644
--- a/viewers/restfulobjects/viewer/src/main/java/org/apache/isis/viewer/restfulobjects/viewer/webmodule/auth/AuthenticationStrategyAbstract.java
+++ b/viewers/restfulobjects/viewer/src/main/java/org/apache/isis/viewer/restfulobjects/viewer/webmodule/auth/AuthenticationStrategyAbstract.java
@@ -27,16 +27,22 @@ import javax.servlet.http.HttpSession;
import org.springframework.web.context.support.WebApplicationContextUtils;
import org.apache.isis.commons.internal.exceptions._Exceptions;
+import org.apache.isis.core.security.authentication.Authentication;
import org.apache.isis.core.security.authentication.manager.AuthenticationManager;
import lombok.val;
+/**
+ * Convenience abstract implementation.
+ *
+ * @since 2.0 {@index}
+ */
public abstract class AuthenticationStrategyAbstract implements AuthenticationStrategy {
public static final int STATUS_UNAUTHORIZED = 401;
-
+
private AuthenticationManager authenticationManager;
-
+
protected AuthenticationManager getAuthenticationManager(ServletRequest servletRequest) {
if(authenticationManager==null) {
val servletContext = getServletContext(servletRequest);
@@ -58,14 +64,14 @@ public abstract class AuthenticationStrategyAbstract implements AuthenticationSt
return servletRequest.getServletContext();
}
-
+
@Override
public final void invalidate(
- final HttpServletRequest httpServletRequest,
+ final HttpServletRequest httpServletRequest,
final HttpServletResponse httpServletResponse) {
-
+
bind(httpServletRequest, httpServletResponse, null);
httpServletResponse.setStatus(STATUS_UNAUTHORIZED);
}
-
+
}
diff --git a/viewers/restfulobjects/viewer/src/main/java/org/apache/isis/viewer/restfulobjects/viewer/webmodule/auth/AuthenticationStrategyBasicAuth.java b/viewers/restfulobjects/viewer/src/main/java/org/apache/isis/viewer/restfulobjects/viewer/webmodule/auth/AuthenticationStrategyBasicAuth.java
index 3e5ad66..8b3ff3d 100644
--- a/viewers/restfulobjects/viewer/src/main/java/org/apache/isis/viewer/restfulobjects/viewer/webmodule/auth/AuthenticationStrategyBasicAuth.java
+++ b/viewers/restfulobjects/viewer/src/main/java/org/apache/isis/viewer/restfulobjects/viewer/webmodule/auth/AuthenticationStrategyBasicAuth.java
@@ -36,6 +36,8 @@ import lombok.val;
/**
* Implements the HTTP Basic Auth protocol; does not bind the
* {@link Authentication} onto the {@link HttpSession}.
+ *
+ * @since 2.0 {@index}
*/
public class AuthenticationStrategyBasicAuth extends AuthenticationStrategyAbstract {
@@ -46,17 +48,17 @@ public class AuthenticationStrategyBasicAuth extends AuthenticationStrategyAbstr
@Override
public Authentication lookupValid(
- final HttpServletRequest httpServletRequest,
+ final HttpServletRequest httpServletRequest,
final HttpServletResponse httpServletResponse) {
- // Basic auth should never create sessions!
+ // Basic auth should never create sessions!
// However, telling this Shiro here, is a fragile approach.
//TODO[2156] do this somewhere else (more coupled with shiro)
httpServletRequest.setAttribute(
- "org.apache.shiro.subject.support.DefaultSubjectContext.SESSION_CREATION_ENABLED",
+ "org.apache.shiro.subject.support.DefaultSubjectContext.SESSION_CREATION_ENABLED",
Boolean.FALSE);
-
+
val digest = getBasicAuthDigest(httpServletRequest);
if (digest == null) {
return null;
@@ -79,15 +81,15 @@ public class AuthenticationStrategyBasicAuth extends AuthenticationStrategyAbstr
@Override
public void bind(
- HttpServletRequest httpServletRequest,
+ HttpServletRequest httpServletRequest,
HttpServletResponse httpServletResponse,
Authentication auth) {
// TODO Auto-generated method stub
-
+
}
-
+
// -- HELPER
-
+
// value should be in the form:
// Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
private String getBasicAuthDigest(final HttpServletRequest httpServletRequest) {
diff --git a/viewers/restfulobjects/viewer/src/main/java/org/apache/isis/viewer/restfulobjects/viewer/webmodule/auth/AuthenticationStrategyDefault.java b/viewers/restfulobjects/viewer/src/main/java/org/apache/isis/viewer/restfulobjects/viewer/webmodule/auth/AuthenticationStrategyDefault.java
index e07c72c..d4afca3 100644
--- a/viewers/restfulobjects/viewer/src/main/java/org/apache/isis/viewer/restfulobjects/viewer/webmodule/auth/AuthenticationStrategyDefault.java
+++ b/viewers/restfulobjects/viewer/src/main/java/org/apache/isis/viewer/restfulobjects/viewer/webmodule/auth/AuthenticationStrategyDefault.java
@@ -38,7 +38,8 @@ import lombok.val;
* <li>it looks up from the {@link HttpSession} using the value
* {@link AuthenticationStrategyDefault#HTTP_SESSION_AUTHENTICATION_SESSION_KEY}</li>
* </ul>
- *
+ *
+ * @since 2.0 {@index}
*/
public class AuthenticationStrategyDefault extends AuthenticationStrategyAbstract {
@@ -46,14 +47,14 @@ public class AuthenticationStrategyDefault extends AuthenticationStrategyAbstrac
@Override
public Authentication lookupValid(
- final HttpServletRequest httpServletRequest,
+ final HttpServletRequest httpServletRequest,
final HttpServletResponse httpServletResponse) {
val authenticationManager = super.getAuthenticationManager(httpServletRequest);
val httpSession = getHttpSession(httpServletRequest);
// use previously authenticated session if available
- val authentication = (Authentication)
+ val authentication = (Authentication)
httpSession.getAttribute(HTTP_SESSION_AUTHENTICATION_SESSION_KEY);
if (authentication != null) {
val sessionValid = authenticationManager.isSessionValid(authentication);
@@ -70,7 +71,7 @@ public class AuthenticationStrategyDefault extends AuthenticationStrategyAbstrac
final HttpServletRequest httpServletRequest,
final HttpServletResponse httpServletResponse,
final Authentication authentication) {
-
+
val httpSession = getHttpSession(httpServletRequest);
if(authentication != null) {
httpSession.setAttribute(
diff --git a/viewers/wicket/adoc/antora.yml b/viewers/wicket/adoc/antora.yml
index 25f6903..3144e97 100644
--- a/viewers/wicket/adoc/antora.yml
+++ b/viewers/wicket/adoc/antora.yml
@@ -16,7 +16,7 @@
# under the License.
name: vw
-title: "Wicket Viewer"
+title: "Web UI (Wicket Viewer)"
version: 2.0.0-M5
start_page: ROOT:about.adoc
nav:
diff --git a/viewers/wicket/adoc/modules/ROOT/pages/about.adoc b/viewers/wicket/adoc/modules/ROOT/pages/about.adoc
index 89d2f27..2db2f4b 100644
--- a/viewers/wicket/adoc/modules/ROOT/pages/about.adoc
+++ b/viewers/wicket/adoc/modules/ROOT/pages/about.adoc
@@ -1,4 +1,4 @@
-= Wicket Viewer
+= Web UI (Wicket Viewer)
: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-aliases: guides:ugvw:ugvw.adoc
diff --git a/viewers/wicket/adoc/modules/ROOT/pages/setup-and-configuration.adoc b/viewers/wicket/adoc/modules/ROOT/pages/setup-and-configuration.adoc
index a95111a..aca56a6 100644
--- a/viewers/wicket/adoc/modules/ROOT/pages/setup-and-configuration.adoc
+++ b/viewers/wicket/adoc/modules/ROOT/pages/setup-and-configuration.adoc
@@ -3,7 +3,7 @@
: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 [...]
-This section describes how to include the Wicket module and set its configuration properties.
+This section describes how to include the Wicket viewer's module and set its configuration properties.
== Maven pom.xml
@@ -46,7 +46,7 @@ This is usually done in the top-level parent pom of your application:
=== Dependency
-In the webapp module, add the following dependency:
+In the webapp module of your application, add the following dependency:
[source,xml]
.pom.xml
[isis] 02/02: ISIS-2484: cleaning up extension catalog a little
Posted by da...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch 2.0.0-M5
in repository https://gitbox.apache.org/repos/asf/isis.git
commit a4c68abb59526ca52428190687add5228e7b655e
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Tue Apr 6 17:06:14 2021 +0100
ISIS-2484: cleaning up extension catalog a little
---
.../modules/ROOT/partials/component-nav.adoc | 3 ++
extensions/adoc/modules/ROOT/pages/about.adoc | 50 ++++++++++++++++++----
.../adoc/modules/ROOT/partials/component-nav.adoc | 22 ----------
extensions/core/command-log/adoc/antora.yml | 2 +-
extensions/core/command-replay/adoc/antora.yml | 2 +-
extensions/core/command-replay/secondary/pom.xml | 6 +--
extensions/core/model-annotation/adoc/antora.yml | 2 +-
.../adoc/modules/ROOT/partials/component-nav.adoc | 8 ++--
8 files changed, 52 insertions(+), 43 deletions(-)
diff --git a/antora/components/userguide/modules/ROOT/partials/component-nav.adoc b/antora/components/userguide/modules/ROOT/partials/component-nav.adoc
index 227dd73..1a5838f 100644
--- a/antora/components/userguide/modules/ROOT/partials/component-nav.adoc
+++ b/antora/components/userguide/modules/ROOT/partials/component-nav.adoc
@@ -3,7 +3,10 @@ include::userguide:btb:partial$module-nav.adoc[]
* Extensions
+include::userguide:command-log:partial$module-nav.adoc[]
+include::userguide:command-replay:partial$module-nav.adoc[]
include::userguide:flyway:partial$module-nav.adoc[]
+include::userguide:model-annotation:partial$module-nav.adoc[]
include::userguide:quartz:partial$module-nav.adoc[]
diff --git a/extensions/adoc/modules/ROOT/pages/about.adoc b/extensions/adoc/modules/ROOT/pages/about.adoc
index 01065c2..0565550 100644
--- a/extensions/adoc/modules/ROOT/pages/about.adoc
+++ b/extensions/adoc/modules/ROOT/pages/about.adoc
@@ -4,15 +4,47 @@
: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:
-This catalog lists a number of extensions to the framework.
-These typically are for use directly within by the domain application itself.
+Both the core framework and many of the framework components have a variety of optional extensions.
-For convenience, some of the extensions catalogued here are incorporated in other guides:
+This page catalogues all the available extensions, but they are incorporated into other guides:
-* in the xref:security:ROOT:about.adoc[security] guide, and the xref:vw:ROOT:about.adoc[Web UI (Wicket viewer)] guide).
-+
-These extensions extend the capability of those components, or provide alternative implementations
+[.nogrid]
+[cols="1a,1a",frame="none", grid="none", stripes="none"]
+|===
+
+
+|
+xref:userguide:fun:about.adoc[User Guide] +
+for core extensions:
+
+include::userguide:command-log:partial$module-nav.adoc[]
+include::userguide:command-replay:partial$module-nav.adoc[]
+include::userguide:flyway:partial$module-nav.adoc[]
+include::userguide:model-annotation:partial$module-nav.adoc[]
+include::userguide:quartz:partial$module-nav.adoc[]
+
+|
+xref:security::about.adoc[Security] extensions:
+
+include::security:session-log:partial$module-nav.adoc[]
+include::security:shiro-realm-ldap:partial$module-nav.adoc[]
+include::security:secman:partial$module-nav.adoc[]
+
+
+
+|xref:vro::about.adoc[Restful Objects] extensions:
+
+include::vro:cors:partial$module-nav.adoc[]
+
+
+|xref:vw::about.adoc[Wicket viewer] extensions:
+
+include::vw:exceldownload:partial$module-nav.adoc[]
+include::vw:fullcalendar:partial$module-nav.adoc[]
+include::vw:gmap3:partial$module-nav.adoc[]
+include::vw:pdfjs:partial$module-nav.adoc[]
+
+|===
+
+//* xref:testing:ROOT:about.adoc[Testing] extensions:
-* in the xref:testing:ROOT:about.adoc[testing] guide
-+
-The extensions here _are_ for use by the domain application, but only for testing or prototyping (eg fixtures) rather than in the business logic itself.
diff --git a/extensions/adoc/modules/ROOT/partials/component-nav.adoc b/extensions/adoc/modules/ROOT/partials/component-nav.adoc
index eb10ea6..4a1af0a 100644
--- a/extensions/adoc/modules/ROOT/partials/component-nav.adoc
+++ b/extensions/adoc/modules/ROOT/partials/component-nav.adoc
@@ -1,24 +1,2 @@
include::extensions:ROOT:partial$module-nav.adoc[]
-* Core
-
-include::security:session-log:partial$module-nav.adoc[]
-include::extensions:command-log:partial$module-nav.adoc[]
-include::extensions:command-replay:partial$module-nav.adoc[]
-include::userguide:flyway:partial$module-nav.adoc[]
-include::extensions:model-annotation:partial$module-nav.adoc[]
-
-* Security
-include::security:shiro-realm-ldap:partial$module-nav.adoc[]
-include::security:secman:partial$module-nav.adoc[]
-
-* Restful Objects Viewer
-
-include::vro:cors:partial$module-nav.adoc[]
-
-* Wicket Viewer
-
-include::vw:exceldownload:partial$module-nav.adoc[]
-include::vw:fullcalendar:partial$module-nav.adoc[]
-include::vw:gmap3:partial$module-nav.adoc[]
-include::vw:pdfjs:partial$module-nav.adoc[]
diff --git a/extensions/core/command-log/adoc/antora.yml b/extensions/core/command-log/adoc/antora.yml
index 2f3eff2..0baa972 100644
--- a/extensions/core/command-log/adoc/antora.yml
+++ b/extensions/core/command-log/adoc/antora.yml
@@ -15,5 +15,5 @@
# specific language governing permissions and limitations
# under the License.
-name: extensions
+name: userguide
version: 2.0.0-M5
diff --git a/extensions/core/command-replay/adoc/antora.yml b/extensions/core/command-replay/adoc/antora.yml
index 2f3eff2..0baa972 100644
--- a/extensions/core/command-replay/adoc/antora.yml
+++ b/extensions/core/command-replay/adoc/antora.yml
@@ -15,5 +15,5 @@
# specific language governing permissions and limitations
# under the License.
-name: extensions
+name: userguide
version: 2.0.0-M5
diff --git a/extensions/core/command-replay/secondary/pom.xml b/extensions/core/command-replay/secondary/pom.xml
index 2f31d1c..963d3d2 100644
--- a/extensions/core/command-replay/secondary/pom.xml
+++ b/extensions/core/command-replay/secondary/pom.xml
@@ -65,20 +65,18 @@
<artifactId>isis-mappings-jaxrsclient-impl</artifactId>
</dependency>
-<!--
<dependency>
<groupId>org.apache.isis.extensions</groupId>
<artifactId>isis-extensions-command-log-jdo</artifactId>
</dependency>
--->
<dependency>
<groupId>org.apache.isis.extensions</groupId>
<artifactId>isis-extensions-quartz-impl</artifactId>
</dependency>
-
+
<!-- TESTING -->
-
+
<dependency>
<groupId>org.apache.isis.core</groupId>
<artifactId>isis-core-internaltestsupport</artifactId>
diff --git a/extensions/core/model-annotation/adoc/antora.yml b/extensions/core/model-annotation/adoc/antora.yml
index 2f3eff2..0baa972 100644
--- a/extensions/core/model-annotation/adoc/antora.yml
+++ b/extensions/core/model-annotation/adoc/antora.yml
@@ -15,5 +15,5 @@
# specific language governing permissions and limitations
# under the License.
-name: extensions
+name: userguide
version: 2.0.0-M5
diff --git a/security/adoc/modules/ROOT/partials/component-nav.adoc b/security/adoc/modules/ROOT/partials/component-nav.adoc
index ffbabc4..280ee13 100644
--- a/security/adoc/modules/ROOT/partials/component-nav.adoc
+++ b/security/adoc/modules/ROOT/partials/component-nav.adoc
@@ -10,9 +10,7 @@ include::security:ROOT:partial$module-nav-end.adoc[]
* Extensions
-include::security:shiro-realm-ldap:partial$module-nav.adoc[]
+include::security:audit-trail:partial$module-nav.adoc[]
include::security:secman:partial$module-nav.adoc[]
-
-// commented out the libraries that have not yet been brought over from incode-platform
-//include::security:audit-trail:partial$module-nav.adoc[]
-//include::security:session-log:partial$module-nav.adoc[]
+include::security:session-log:partial$module-nav.adoc[]
+include::security:shiro-realm-ldap:partial$module-nav.adoc[]