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 2015/11/17 21:49:06 UTC
[3/4] isis git commit: ISIS-1250: custom MessageBodyWriter for
x-ro-domain-type Accept requests;
remove the configuration option for ignoring/including Isis common schemas;
move Dto role interface to own package; updating docs
ISIS-1250: custom MessageBodyWriter for x-ro-domain-type Accept requests; remove the configuration option for ignoring/including Isis common schemas; move Dto role interface to own package; updating docs
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/19cdaaba
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/19cdaaba
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/19cdaaba
Branch: refs/heads/master
Commit: 19cdaabaaee8baab203f49cdcf2d3cffe37f73f0
Parents: a8c48a2
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Sun Nov 15 21:37:23 2015 +0000
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Tue Nov 17 09:10:49 2015 +0000
----------------------------------------------------------------------
adocs/documentation/Gemfile.lock | 3 -
.../_migration-notes_1.10.0-to-1.11.0.adoc | 31 ++++
.../main/asciidoc/guides/_rg_annotations.adoc | 6 +-
.../asciidoc/guides/_rg_annotations_aaa.adoc | 1 +
.../guides/_rg_annotations_aaa_jee.adoc | 14 ++
.../_rg_annotations_manpage-XmlRootElement.adoc | 89 ++++++++++
...annotations_manpage-XmlValueTypeAdapter.adoc | 10 ++
.../main/asciidoc/guides/_rg_classes_roles.adoc | 1 +
.../guides/_rg_classes_roles_manpage-Dto.adoc | 58 +++++++
.../main/asciidoc/guides/_rg_schema-aim.adoc | 8 +
.../main/asciidoc/guides/_rg_schema-common.adoc | 8 +
...ilities-ActionInvocationMementoDtoUtils.adoc | 47 ++++++
.../asciidoc/guides/_rg_schema-utilities.adoc | 14 ++
.../src/main/asciidoc/guides/_rg_schema.adoc | 12 ++
.../main/asciidoc/guides/_rg_services-api.adoc | 10 ++
...ces-api_manpage-ActionInvocationContext.adoc | 13 +-
..._services-api_manpage-BackgroundService.adoc | 13 +-
...rg_services-api_manpage-BookmarkService.adoc | 14 +-
.../_rg_services-api_manpage-ClockService.adoc | 14 +-
..._rg_services-api_manpage-CommandContext.adoc | 14 +-
...rg_services-api_manpage-DeepLinkService.adoc | 14 +-
...vices-api_manpage-DomainObjectContainer.adoc | 10 +-
.../_rg_services-api_manpage-EmailService.adoc | 16 +-
...rg_services-api_manpage-EventBusService.adoc | 14 +-
..._services-api_manpage-GuiceBeanProvider.adoc | 12 +-
..._rg_services-api_manpage-IsisJdoSupport.adoc | 13 +-
.../_rg_services-api_manpage-JaxbService.adoc | 67 ++++++++
..._rg_services-api_manpage-MementoService.adoc | 13 +-
...g_services-api_manpage-MetamodelService.adoc | 13 +-
..._services-api_manpage-QueryResultsCache.adoc | 14 +-
.../_rg_services-api_manpage-Scratchpad.adoc | 14 +-
.../_rg_services-api_manpage-SudoService.adoc | 18 +-
..._rg_services-api_manpage-WrapperFactory.adoc | 13 +-
...services-api_manpage-XmlSnapshotService.adoc | 17 +-
.../main/asciidoc/guides/_rg_services-spi.adoc | 11 ++
...rg_services-spi_manpage-AuditingService.adoc | 14 +-
...es-spi_manpage-BackgroundCommandService.adoc | 17 +-
...vices-spi_manpage-ClassDiscoveryService.adoc | 14 +-
..._rg_services-spi_manpage-CommandService.adoc | 18 +-
...vices-spi_manpage-ContentMappingService.adoc | 5 +-
...s-spi_manpage-ContentNegotiationService.adoc | 14 +-
...es-spi_manpage-EmailNotificationService.adoc | 16 +-
...vices-spi_manpage-ErrorReportingService.adoc | 7 +-
...rg_services-spi_manpage-EventSerializer.adoc | 19 ++-
...ervices-spi_manpage-ExceptionRecognizer.adoc | 13 +-
...age-FixtureScriptsSpecificationProvider.adoc | 12 +-
..._rg_services-spi_manpage-LocaleProvider.adoc | 14 +-
..._services-spi_manpage-PublishingService.adoc | 46 ++++-
...vices-spi_manpage-RepresentationService.adoc | 12 +-
...services-spi_manpage-TranslationService.adoc | 12 +-
...rvices-spi_manpage-TranslationsResolver.adoc | 11 +-
...services-spi_manpage-UrlEncodingService.adoc | 37 ++++
...services-spi_manpage-UserProfileService.adoc | 5 +-
...ces-spi_manpage-UserRegistrationService.adoc | 30 +++-
.../src/main/asciidoc/guides/rg.adoc | 1 +
.../src/main/asciidoc/migration-notes.adoc | 1 +
.../org/apache/isis/applib/AppManifest.java | 1 +
.../apache/isis/applib/services/dto/Dto.java | 21 +++
.../applib/services/dto/Dto_downloadXml.java | 67 ++++++++
.../applib/services/dto/Dto_downloadXsd.java | 119 +++++++++++++
.../apache/isis/applib/services/dto/Util.java | 33 ++++
.../apache/isis/applib/services/jaxb/Dto.java | 21 ---
.../applib/services/jaxb/Dto_downloadXml.java | 69 --------
.../applib/services/jaxb/Dto_downloadXsd.java | 118 -------------
.../isis/applib/services/jaxb/JaxbService.java | 33 +++-
.../apache/isis/applib/services/jaxb/Util.java | 33 ----
.../urlencoding/UrlEncodingService.java | 21 +--
.../UrlEncodingServiceUsingBaseEncoding.java | 57 +++++++
.../services/jaxb/JaxbServiceDefault.java | 167 -------------------
.../util/CatalogingSchemaOutputResolver.java | 83 ---------
.../jaxb/util/StreamResultWithWriter.java | 45 -----
.../jaxb/CatalogingSchemaOutputResolver.java | 85 ++++++++++
.../services/jaxb/JaxbServiceDefault.java | 142 ++++++++++++++++
.../services/jaxb/StreamResultWithWriter.java | 45 +++++
.../utils/ActionInvocationMementoDtoUtils.java | 10 +-
.../jaxbadapters/PersistentEntityAdapter.java | 6 +-
.../server/RestfulObjectsApplication.java | 3 +
.../conneg/RestfulObjectsMessageBodyWriter.java | 68 ++++++++
78 files changed, 1384 insertions(+), 820 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/19cdaaba/adocs/documentation/Gemfile.lock
----------------------------------------------------------------------
diff --git a/adocs/documentation/Gemfile.lock b/adocs/documentation/Gemfile.lock
index 808cd9a..6a495d9 100644
--- a/adocs/documentation/Gemfile.lock
+++ b/adocs/documentation/Gemfile.lock
@@ -43,6 +43,3 @@ DEPENDENCIES
tilt
wdm (>= 0.1.0)
webrick
-
-BUNDLED WITH
- 1.10.6
http://git-wip-us.apache.org/repos/asf/isis/blob/19cdaaba/adocs/documentation/src/main/asciidoc/_migration-notes_1.10.0-to-1.11.0.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/_migration-notes_1.10.0-to-1.11.0.adoc b/adocs/documentation/src/main/asciidoc/_migration-notes_1.10.0-to-1.11.0.adoc
new file mode 100644
index 0000000..1df35a8
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/_migration-notes_1.10.0-to-1.11.0.adoc
@@ -0,0 +1,31 @@
+[[_migration-notes_1.10.0-to-1.11.0]]
+= From v1.10.0 to 1.11.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 agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+Existing projects written against v1.10.0 should run against v1.11.0 with few if any changes. If you *do* encounter
+any difficulties then let us know via the link:support.html[users mailing list], so we can support you and document
+issues here.
+
+
+[NOTE]
+====
+At the time of writing `1.11.0` has not been released; these notes relate to `1.11.0-SNAPSHOT`.
+====
+
+
+== JAXB view models
+
+This version recognizes classes annotated with xref:rg.adoc#_rg_annotations_manpage-XmlRootElement[`@XmlRootElement`]
+as view models. These are serialized out into XML and converted into URL.
+
+The xref:rg.adoc#_rg_services-api_manpage-JaxbService[`JaxbService`] is responsible for performing the XML conversion.
+The default implementation is located in the `org.apache.isis.core:isis-core-schema` module, specifically under the
+`org.apache.isis.core.schema.services` package.
+
+If your application is bootstrapped using an `AppManifest` (recommended; ee
+xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[here]) then the `JaxbService` will automatically be discovered and
+ registered. However, if you are still using the older `isis.properties` configuration file to explicitly register
+ services then you will need to add in this service.
http://git-wip-us.apache.org/repos/asf/isis/blob/19cdaaba/adocs/documentation/src/main/asciidoc/guides/_rg_annotations.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations.adoc
index 213df78..f25d39d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations.adoc
@@ -55,8 +55,10 @@ include::_rg_annotations_manpage-Property.adoc[leveloffset=+1]
include::_rg_annotations_manpage-PropertyLayout.adoc[leveloffset=+1]
include::_rg_annotations_manpage-RequestScoped.adoc[leveloffset=+1]
include::_rg_annotations_manpage-Title.adoc[leveloffset=+1]
-include::_rg_annotations_manpage-Viewmodel.adoc[leveloffset=+1]
-include::_rg_annotations_manpage-ViewmodelLayout.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-ViewModel.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-ViewModelLayout.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-XmlRootElement.adoc[leveloffset=+1]
+include::_rg_annotations_manpage-XmlValueTypeAdapter.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/19cdaaba/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa.adoc
index dda6a8a..4ef658d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa.adoc
@@ -11,6 +11,7 @@ include::_rg_annotations_aaa_main.adoc[leveloffset=+1]
include::_rg_annotations_aaa_other.adoc[leveloffset=+1]
include::_rg_annotations_aaa_jdo.adoc[leveloffset=+1]
include::_rg_annotations_aaa_jee.adoc[leveloffset=+1]
+include::_rg_annotations_aaa_jaxb.adoc[leveloffset=+1]
include::_rg_annotations_aaa_deprecated.adoc[leveloffset=+1]
include::_rg_annotations_aaa_partial.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/19cdaaba/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa_jee.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa_jee.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa_jee.adoc
index 646079d..7753e93 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa_jee.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_aaa_jee.adoc
@@ -52,6 +52,20 @@ The table below lists the JEE annotations currently recognized. Expect to see m
|Domain
|
+|xref:rg.adoc#_rg_annotations_manpage-RequestScoped[`javax.xml.bind` +
+`.annotation` +
+`XmlRootElement`]
+|JAXB annotation indicating the XML root element when serialized to XML; also used by the framework for view models (whose memento is the XML), often also acting as a DTO.
+|Application
+|
+
+|xref:rg.adoc#_rg_annotations_manpage-XmlValueTypeAdapter[`javax.xml.bind` +
+`.annotation` +
+`XmlValueTypeAdapter`]
+|JAXB annotation defining how to serialize an entity. Used in conjunction with the (framework provided) `PersientEntityAdapter` class to serialize persistent entities into a canonical OID (equivalent to the `Bookmark` provided by the xref:rg.adoc#_rg_services-api_manpage-BookmarkService[`BookmarkService`]).
+|Domain
+|
+
|===
http://git-wip-us.apache.org/repos/asf/isis/blob/19cdaaba/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-XmlRootElement.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-XmlRootElement.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-XmlRootElement.adoc
new file mode 100644
index 0000000..241b419
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-XmlRootElement.adoc
@@ -0,0 +1,89 @@
+[[_rg_annotations_manpage-XmlRootElement]]
+= `@XmlRootElement` (`jaxb`) (`1.11.0-SNAPSHOT`)
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+The `@XmlRootElement` annotation (`1.11.0-SNAPSHOT`) provides an alternative way to define a view model, in particular
+one intended to act as a DTO for use within xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer], or which
+contains arbitrarily complex state.
+
+A view model is a non-persisted domain object whose state is converted to/from a string memento. In the case of a
+JAXB-annotated object this memento is its XML representation. JAXB generally requires that the root element of the
+XML representation is annotated with `@XmlRootElement`. Apache Isis makes this a mandatory requirement.
+
+In comparison to using either the xref:rg.adoc#_rg_classes_super_manpage-ViewModel[`ViewModel`] interface or the
+xref:rg.adoc#_rg_annotations_manpage-ViewModel[`@ViewModel`] annotation, using `@XmlRootElement` has a couple of
+significant advantages:
+
+* the view model can be used as a "canonical" DTO, for example when accessing data using the
+xref:ug.adoc#_ug_restfulobjects-viewer[RestfulObjects viewer] in combination with the
+xref:rg.adoc#_rg_services-spi_manpage-ContentMappingService[`ContentMappingService`]. +
++
+This provides a stable and
+versioned API to access data in XML format using whatever client-side technology may be appropriate.
+
+* the XML graph can be as deep as required, in particular it can contain collections of other objects. +
++
+In contrast, if the `@ViewModel` annotation is used then only the state of the properties (not collections) is captured.
+If using `ViewModel` interface then arbitrary state (including that of collections), however the programmer must write
+all the code by hand
+
+The main disadvantages of using JAXB-annotated view models is that any referenced persistent entity must be annotated
+with the xref:rg.adoc#_rg_annotations_manpage-XmlValueTypeAdapter[`@XmlValueTypeAdapter`], using the
+framework-provided `PersistentEntityAdapter`. This adapter converts any references to such domain entities into the
+`<oid-dto>` element as defined by the Apache Isis xref:rg.adoc#_rg_schema-common[common schema].
+
+[TIP]
+====
+The memento string for view models is converted into a form compatible with use within a URL. This is performed by the
+xref:rg.adoc#_rg_services-spi_manpage-UrlEncodingService[`UrlEncodingService`], the default implementation of which
+simply encodes to base 64. If the view model XML graph is too large to be serialized to a string, then an alternative
+implementation (eg which maps XML strings to a GUID, say) can be configured using the technique described in
+xref:rg.adoc#_ug_how-tos_replacing-default-service-implementations[here] in the user guide.
+====
+
+
+== Example
+
+This example is taken from the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp]:
+
+[source,java]
+----
+@XmlAccessorType(XmlAccessType.FIELD) // <1>
+@XmlType(
+ namespace = "http://viewmodels.app.todoapp/v1/todoitem", // <2>
+ propOrder = { // <3>
+ "toDoItem",
+ "description",
+ "cost",
+ "similarItems"
+ }
+)
+@XmlRootElement(name = "toDoItemDto") // <4>
+public class ToDoItemDto implements Dto {
+
+ @XmlElement(required = true) // <5>
+ protected ToDoItem toDoItem; // <6>
+
+ @XmlElement(required = true)
+ protected String description;
+
+ protected BigDecimal cost;
+
+ @XmlElementWrapper // <7>
+ @XmlElement(name = "todoItem") // <8>
+ protected List<ToDoItem> similarItems = Lists.newArrayList();
+
+ // getters and setters omitted
+}
+----
+<1> optional; whether JAXB-serialization reads fields directly (as here) else uses getters/setters
+<2> specify the XML schema namespace to which this element type belongs
+<3> all properties in the class must be listed; (they can be ignored using `@XmlTransient`)
+<4> mandatory, identifies this class as a view model and defines the root element for JAXB serialization
+<5> optional; JAXB metadata can specify such attributes as required/optional
+<6> reference to a persistent entity (`ToDoItem`). Further discussion below.
+<7> collections must be wrapped in `XmlElementWraper`.
+<8> collections should specify the name of the elements within the collection
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/19cdaaba/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-XmlValueTypeAdapter.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-XmlValueTypeAdapter.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-XmlValueTypeAdapter.adoc
new file mode 100644
index 0000000..69709df
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_annotations_manpage-XmlValueTypeAdapter.adoc
@@ -0,0 +1,10 @@
+[[_rg_annotations_manpage-XmlRootElement]]
+= `@XmlValueTypeAdapter` (`jaxb`) (`1.11.0-SNAPSHOT`)
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+The `@XmlValueTypeAdapter` annotation (`1.11.0-SNAPSHOT`) is not recognized directly by the framework, but should be used to annotate any persistent domain entities that are referenced from view models annotated with xref:rg.adoc#_rg_annotations_manpage-XmlRootElement[`@XmlRootElement`].
+
+NOTE: TODO
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/19cdaaba/adocs/documentation/src/main/asciidoc/guides/_rg_classes_roles.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_roles.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_roles.adoc
index b90cd7b..138c3d2 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_roles.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_roles.adoc
@@ -12,4 +12,5 @@ The interfaces listed in this chapter are role interfaces; they define a contrac
include::_rg_classes_roles_manpage-HoldsUpdatedAt.adoc[leveloffset=+1]
include::_rg_classes_roles_manpage-HoldsUpdatedBy.adoc[leveloffset=+1]
include::_rg_classes_roles_manpage-Timestampable.adoc[leveloffset=+1]
+include::_rg_classes_roles_manpage-Dto.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/19cdaaba/adocs/documentation/src/main/asciidoc/guides/_rg_classes_roles_manpage-Dto.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_roles_manpage-Dto.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_roles_manpage-Dto.adoc
new file mode 100644
index 0000000..bd62e5c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_roles_manpage-Dto.adoc
@@ -0,0 +1,58 @@
+[[_rg_classes_mixins_Dto]]
+= `Dto` (`1.11.0-SNAPSHOT`)
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+The `Dto` role interface (`1.11.0-SNAPSHOT`) is intended to be implemented by JAXB-annotated view models, that is, annotated using
+xref:rg.adoc#_rg_annotations_manpage-XmlRootElement[`@XmlRootElement`]. It enables the ability to download the XML and
+XSD schema of those objects using two mixins, `Dto_downloadXml` and `Dto_downloadXsd`.
+
+The interface is just a marker interface (with no members), and is defined as:
+
+[source,java]
+----
+public interface Dto {
+}
+----
+
+The `Dto_downloadXml` mixin defines the following action:
+
+[source,java]
+----
+@Mixin
+public class Dto_downloadXml {
+ public Dto_downloadXml(final Dto dto) { ... } // <1>
+ public Object downloadXml(final String fileName) { ... } // <2>
+ ...
+}
+----
+<1> provided as an action to any class that (trivially) implements the `Dto` interface
+<2> in fact, the method is called "$$". This is converted to "download Xml", based on the mixin's name
+
+This will return the XML text wrapped up in a xref:rg.adoc#_rg_classes_value-types_manpage-Clob[`Clob`].
+
+The `Dto_downloadXsd` mixin is similar:
+
+[source,java]
+----
+@Mixin
+public class Dto_downloadXsd {
+ public Dto_downloadXsd(final Dto dto) { ... } // <1>
+ public Object downloadXsd(final String fileName) { ... } // <2>
+}
+----
+<1> provided as an action to any class that (trivially) implements the `Dto` interface
+<2> in fact, the method is called "$$". This is converted to "download Xsd", based on the mixin's name
+
+If the domain object's JAXB annotations reference only a single XSD schema then this will return that XML text as
+a xref:rg.adoc#_rg_classes_value-types_manpage-Clob[`Clob`] of that XSD. If there are multiple XSD schemas referenced
+then the action will return a zip of those schemas, wrapped up in a
+xref:rg.adoc#_rg_classes_value-types_manpage-Blob[`Blob`].
+
+
+== Related Services
+
+The `Dto_downloadXml` and `Dto_downloadXsd` delegate to the
+xref:rg.adoc#_rg_services-api_manpage-JaxbService[`JaxbService`] to actually generate the XML/XSD.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/19cdaaba/adocs/documentation/src/main/asciidoc/guides/_rg_schema-aim.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_schema-aim.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_schema-aim.adoc
new file mode 100644
index 0000000..d898b7e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_schema-aim.adoc
@@ -0,0 +1,8 @@
+[[_rg_schema-aim]]
+= Action Invocation Memento
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+NOTE: TODO
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/19cdaaba/adocs/documentation/src/main/asciidoc/guides/_rg_schema-common.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_schema-common.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_schema-common.adoc
new file mode 100644
index 0000000..4e6d6cd
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_schema-common.adoc
@@ -0,0 +1,8 @@
+[[_rg_schema-common]]
+= Common Schema
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+NOTE: TODO
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/19cdaaba/adocs/documentation/src/main/asciidoc/guides/_rg_schema-utilities-ActionInvocationMementoDtoUtils.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_schema-utilities-ActionInvocationMementoDtoUtils.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_schema-utilities-ActionInvocationMementoDtoUtils.adoc
new file mode 100644
index 0000000..a9d2609
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_schema-utilities-ActionInvocationMementoDtoUtils.adoc
@@ -0,0 +1,47 @@
+[[_rg_schema-utilities-ActionInvocationMementoDtoUtils]]
+= `ActionInvocationMementoDtoUtils`
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+NOTE: TODO
+
+`ActionInvocationMementoDtoUtils`
+
+
+[source,java]
+----
+public class ActionInvocationMementoDtoUtils {
+ public static ActionInvocationMementoDto newDto() { ... } // <1>
+ public static void setMetadata( ... ) { ... }
+ public static boolean addArgValue( ... ) { ... }
+ public static void addArgReference( ... ) { ... }
+ public static boolean addReturnValue( ... ) { ... }
+ public static void addReturnReference( ... ) { ... }
+
+ public static int getNumberOfParameters(final ActionInvocationMementoDto aim) { ... } // <2>
+ public static List<ParamDto> getParameters(final ActionInvocationMementoDto aim) { ... }
+ public static List<String> getParameterNames(final ActionInvocationMementoDto aim) { ... }
+ public static List<ValueType> getParameterTypes(final ActionInvocationMementoDto aim) { ... }
+ public static ParamDto getParameter(final ActionInvocationMementoDto aim, final int paramNum) { ... } // <3>
+ public static ValueDto getParameterValue(final ActionInvocationMementoDto aim, final int paramNum) { ... }
+ public static String getParameterName(final ActionInvocationMementoDto aim, final int paramNum) { ... }
+ public static ValueType getParameterType(final ActionInvocationMementoDto aim, final int paramNum) { ... }
+ public static boolean isNull(final ActionInvocationMementoDto aim, int paramNum) { ... }
+
+ public static <T> T getArg(final ActionInvocationMementoDto aim, int paramNum, Class<T> cls) { ... } // <3>
+
+ public static ActionInvocationMementoDto fromXml(Reader reader) { ... } // <4>
+ public static ActionInvocationMementoDto fromXml(
+ final Class<?> contextClass,
+ final String resourceName,
+ final Charset charset) throws IOException { ... }
+ public static String toXml(final ActionInvocationMementoDto aim) { ... }
+ public static void toXml(final ActionInvocationMementoDto aim, final Writer writer) { ... }
+}
+----
+<1> not API; for the Apache Isis framework itself to create and initialize DTOs representing action invocations
+<2> API, obtaining metadata about the action invocation
+<3> API, obtaining the argument value for a particular parameter of the action invocation
+<4> marshall the DTO to/from XML
http://git-wip-us.apache.org/repos/asf/isis/blob/19cdaaba/adocs/documentation/src/main/asciidoc/guides/_rg_schema-utilities.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_schema-utilities.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_schema-utilities.adoc
new file mode 100644
index 0000000..a696fbf
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_schema-utilities.adoc
@@ -0,0 +1,14 @@
+[[_rg_schema-utilities]]
+= Utilities
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+NOTE: TODO
+
+In addition to defining the schemas themselves, Apache Isis also provides some simple helper classes, under the
+`org.apache.isis.schema.utils` package.
+
+
+include::_rg_schema-utilities-ActionInvocationMementoDtoUtils.adoc[leveloffset=+1]
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/19cdaaba/adocs/documentation/src/main/asciidoc/guides/_rg_schema.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_schema.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_schema.adoc
new file mode 100644
index 0000000..e8ce6c2
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_schema.adoc
@@ -0,0 +1,12 @@
+[[_rg_schema]]
+= Schema
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+NOTE: TODO
+
+include::_rg_schema-common.adoc[leveloffset=+1]
+include::_rg_schema-aim.adoc[leveloffset=+1]
+include::_rg_schema-utilities.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/19cdaaba/adocs/documentation/src/main/asciidoc/guides/_rg_services-api.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api.adoc
index ae95d98..f496223 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api.adoc
@@ -160,6 +160,16 @@ SpecificationProvider`].
|
+|xref:rg.adoc#_rg_services-api_manpage-JaxbService[`o.a.i.applib.` +
+`services.jaxb` +
+`JaxbService`]
+|Marshal and unmarshal JAXB-annotated view models to/from XML.
+|`JaxbServiceDefault` +
+``o.a.i.core`` +
+``isis-core-schema``
+|`1.11.0-SNAPSHOT`.
+
+
|xref:rg.adoc#_rg_services-api_manpage-MementoService[`o.a.i.applib.` +
`services.memento` +
`MementoService`]
http://git-wip-us.apache.org/repos/asf/isis/blob/19cdaaba/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-ActionInvocationContext.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-ActionInvocationContext.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-ActionInvocationContext.adoc
index 55fab20..c52348d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-ActionInvocationContext.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-ActionInvocationContext.adoc
@@ -65,14 +65,13 @@ public class ToDoItem ... {
== Registering the Service
Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]):
+`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' default
+implementation of `ActionInvocationContext` class is automatically registered (it is annotated with `@DomainService`)
+so no further configuration is required.
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then Isis' default implementation of `ActionInvocationContext` class is automatically registered (it is annotated with `@DomainService`) so no further configuration is required.
+To use an alternative implementation, use
+xref:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
http://git-wip-us.apache.org/repos/asf/isis/blob/19cdaaba/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-BackgroundService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-BackgroundService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-BackgroundService.adoc
index ddcbea6..c59ef95 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-BackgroundService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-BackgroundService.adoc
@@ -94,14 +94,13 @@ The user would be returned a domain object representing their action invocation.
== Registering the Services
Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]):
+`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+implementation of `BackgroundService` is automatically registered (it is annotated with `@DomainService`) so no
+further configuration is required.
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then Apache Isis' core implementation of `BackgroundService` is automatically registered (it is annotated with `@DomainService`) so no further configuration is required.
+To use an alternative implementation, use
+xref:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
http://git-wip-us.apache.org/repos/asf/isis/blob/19cdaaba/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-BookmarkService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-BookmarkService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-BookmarkService.adoc
index 0db6e9d..87305af 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-BookmarkService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-BookmarkService.adoc
@@ -105,14 +105,12 @@ Bookmarks are also used by the (non-ASF) http://github.com/isisaddons/isis-modul
== Registering the Service
Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]):
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then Apache Isis' core implementation of `BookmarkService` is automatically registered (it is annotated with `@DomainService`) so no further configuration is required.
+`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+implementation of `BookmarkService` is automatically registered (it is annotated with `@DomainService`) so no further
+configuration is required.
+To use an alternative implementation, use
+xref:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
http://git-wip-us.apache.org/repos/asf/isis/blob/19cdaaba/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-ClockService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-ClockService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-ClockService.adoc
index 8582730..5bd309d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-ClockService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-ClockService.adoc
@@ -93,13 +93,9 @@ public class NntpClockServiceInitializer {
== Registering the Service
Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]):
+`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+implementation of `ClockService` is automatically registered (it is annotated with `@DomainService`) so no further
+configuration is required.
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then Apache Isis' core implementation of `ClockService` is automatically registered (it is annotated with `@DomainService`) so no further configuration is required.
-
-If you want to use a different implementation of `Clock`, eg delegating to NNTP, then do _not_ register directly, but instead subclass from `o.a.i.applib.clock.Clock` singleton (as described in the section above).
+If you want to use a different implementation of `Clock`, eg delegating to NNTP, then do _not_ register directly, but
+instead subclass from `o.a.i.applib.clock.Clock` singleton (as described in the section above).
http://git-wip-us.apache.org/repos/asf/isis/blob/19cdaaba/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-CommandContext.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-CommandContext.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-CommandContext.adoc
index cc770e1..c9008f0 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-CommandContext.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-CommandContext.adoc
@@ -197,15 +197,13 @@ String user = commandContext.getCommand().getUser();
== Registering the Services
Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]):
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then Apache Isis' core implementation of `CommandContext` service is automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
+`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+implementation of `CommandContext` service is automatically registered and injected (it is annotated with
+`@DomainService`) so no further configuration is required.
+To use an alternative implementation, use
+xref:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
http://git-wip-us.apache.org/repos/asf/isis/blob/19cdaaba/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DeepLinkService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DeepLinkService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DeepLinkService.adoc
index 651b89e..1dd9f89 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DeepLinkService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DeepLinkService.adoc
@@ -47,12 +47,10 @@ The Wicket viewer core framework provides a default implementation of this API:
== Registering the Services
Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]):
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-and that the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] is being used then an implementation of `DeepLinkService` is automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
+`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]), _and_ that the
+xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] is being used, then an implementation of `DeepLinkService` is
+automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
+To use an alternative implementation, use
+xref:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
http://git-wip-us.apache.org/repos/asf/isis/blob/19cdaaba/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer.adoc
index c0820de..f75f72e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-DomainObjectContainer.adoc
@@ -34,11 +34,7 @@ include::_rg_services-api_manpage-DomainObjectContainer_services-api.adoc[levelo
== Registering the Service
Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]):
+`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+implementation of `DomainObjectContainer` service is automatically registered and injected (it is annotated with
+`@DomainService`) so no further configuration is required.
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then Apache Isis' core implementation of `DomainObjectContainer` service is automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
http://git-wip-us.apache.org/repos/asf/isis/blob/19cdaaba/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-EmailService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-EmailService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-EmailService.adoc
index d714628..cd1b9ea 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-EmailService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-EmailService.adoc
@@ -81,17 +81,13 @@ To ensure that your alternative implementation takes the place of the default im
== Registering the Services
Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]):
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then Apache Isis' core implementation of `EmailService` service is automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
-
-If you have written an alternative implementation, then register your implementation in `isis.properties` under the "isis.services" key and it will be used instead.
+`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+implementation of `EmailService` service is automatically registered and injected (it is annotated with
+`@DomainService`) so no further configuration is required.
+To use an alternative implementation, use
+xref:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
== Related Services
http://git-wip-us.apache.org/repos/asf/isis/blob/19cdaaba/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-EventBusService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-EventBusService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-EventBusService.adoc
index 3639e9b..e62aa1d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-EventBusService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-EventBusService.adoc
@@ -387,15 +387,13 @@ Late registration refers to the idea that a domain service can register itself w
== Registering the Services
Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]):
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then Apache Isis' core implementation of `EventBusService` service is automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
+`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+implementation of `EventBusService` service is automatically registered and injected (it is annotated with
+`@DomainService`) so no further configuration is required.
+To use an alternative implementation, use
+xref:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
http://git-wip-us.apache.org/repos/asf/isis/blob/19cdaaba/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-GuiceBeanProvider.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-GuiceBeanProvider.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-GuiceBeanProvider.adoc
index 1cf5e47..729588c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-GuiceBeanProvider.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-GuiceBeanProvider.adoc
@@ -80,12 +80,12 @@ should return "ToDo App".
== Registering the Services
Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]):
+`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]), _and_ that the
+xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] is being used, then an implementation of `GuiceBeanProvider` is
+automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
+To use an alternative implementation, use
+xref:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
-and that the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] is being used then an implementation of `GuiceBeanProvider` is automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
http://git-wip-us.apache.org/repos/asf/isis/blob/19cdaaba/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-IsisJdoSupport.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-IsisJdoSupport.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-IsisJdoSupport.adoc
index d2ef76c..74056d4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-IsisJdoSupport.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-IsisJdoSupport.adoc
@@ -267,11 +267,10 @@ public List<Order> findOrders(...) {
== Registering the Services
Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]):
+`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+implementation of `IsisJdoSupport` service is automatically registered and injected (it is annotated with
+`@DomainService`) so no further configuration is required.
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then Apache Isis' core implementation of `IsisJdoSupport` service is automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
+To use an alternative implementation, use
+xref:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
http://git-wip-us.apache.org/repos/asf/isis/blob/19cdaaba/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-JaxbService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-JaxbService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-JaxbService.adoc
new file mode 100644
index 0000000..61f0d3a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-JaxbService.adoc
@@ -0,0 +1,67 @@
+[[_rg_services-api_manpage-JaxbService]]
+= `JaxbService` (`1.11.0-SNAPSHOT`)
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../
+:_imagesdir: images/
+
+
+
+The `JaxbService` (`1.11.0-SNAPSHOT`) allows instances of JAXB-annotated classes to be marshalled to XML and
+unmarshalled from XML back into domain objects.
+
+
+
+
+
+[[_rg_services-api_manpage-JaxbService_api-and-implementation]]
+== API & Implementation
+
+The API defined by `JaxbService` is:
+
+[source,java]
+----
+public interface JaxbService {
+ @Programmatic
+ <T> T fromXml(Class<T> domainClass, String xml); // <1>
+ @Programmatic
+ public String toXml(final Object domainObject); // <2>
+ public enum IsisSchemas { // <3>
+ INCLUDE, IGNORE
+ }
+ @Programmatic
+ public Map<String, String> toXsd(final Object domainObject, final IsisSchemas isSchemas);} // <4>
+----
+<1> unmarshalls the XML into an instance of the class.
+<2> marshalls the domain object into XML
+<3> whether to include or exclude the Isis schemas in the generated map of XSDs. Discussed further below.
+<4> generates a map of each of the schemas referenced; the key is the schema namespace, the value is the XML of the schema itself.
+
+With respect to the `IsisSchemas` enum: a JAXB-annotated domain object will live in its own XSD namespace and may
+reference multiple other XSD schemas. In particular, many JAXB domain objects will reference the
+link:http://isis.apache.org/schema[common Isis schemas] (for example the `OidDto` class that represents a reference to
+a persistent entity). The enum indicates whether these schemas should be included or excluded from the map.
+
+Isis provides a default implementation of the service, `o.a.i.schema.services.jaxb.JaxbServiceDefault`.
+
+
+
+== Usage within the framework
+
+This service is provided as a convenience for applications, but is also used internally by the framework to
+xref:rg.adoc#_rg_annotations_manpage-XmlRootElement[`@XmlRootElement`]-annotated
+xref:ug.adoc#_ug_more-advanced_view-models[view models]. The functionality to download XML and XSD schemas is also
+exposed in the UI through mixins to xref:rg.adoc#_rg_classes_roles_manpage-Dto[`Dto`] interface.
+
+
+
+== Registering the Service
+
+Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
+`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+implementation of `JaxbService` service is automatically registered and injected (it is annotated with `@DomainService`)
+so no further configuration is required.
+
+To use an alternative implementation, use
+xref:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
+
http://git-wip-us.apache.org/repos/asf/isis/blob/19cdaaba/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-MementoService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-MementoService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-MementoService.adoc
index 21c35ed..ab06525 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-MementoService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-MementoService.adoc
@@ -122,11 +122,10 @@ The memento service is used by the xref:rg.adoc#_rg_services-api_manpage-Command
== Registering the Service
Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]):
+`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+implementation of `MementoService` service is automatically registered and injected (it is annotated with
+`@DomainService`) so no further configuration is required.
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then Apache Isis' core implementation of `MementoService` service is automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
+To use an alternative implementation, use
+xref:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
http://git-wip-us.apache.org/repos/asf/isis/blob/19cdaaba/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-MetamodelService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-MetamodelService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-MetamodelService.adoc
index 82984ac..b65e42e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-MetamodelService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-MetamodelService.adoc
@@ -33,11 +33,10 @@ public interface MetaModelService {
== Registering the Service
Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]):
+`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+implementation of `MetamodelService` service is automatically registered and injected (it is annotated with
+`@DomainService`) so no further configuration is required.
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then Apache Isis' core implementation of `MetamodelService` service is automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
+To use an alternative implementation, use
+xref:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
http://git-wip-us.apache.org/repos/asf/isis/blob/19cdaaba/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-QueryResultsCache.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-QueryResultsCache.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-QueryResultsCache.adoc
index d4ab535..0e698da 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-QueryResultsCache.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-QueryResultsCache.adoc
@@ -111,15 +111,13 @@ This refactoring will be worthwhile provided that enough of the orders being pro
== Registering the Service
Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]):
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then Apache Isis' core implementation of `QueryResultsCache` service is automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
+`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+implementation of `QueryResultsCache` service is automatically registered and injected (it is annotated with
+`@DomainService`) so no further configuration is required.
+To use an alternative implementation, use
+xref:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
http://git-wip-us.apache.org/repos/asf/isis/blob/19cdaaba/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-Scratchpad.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-Scratchpad.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-Scratchpad.adoc
index d108fe1..5906cd0 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-Scratchpad.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-Scratchpad.adoc
@@ -109,15 +109,13 @@ If using the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer], the `ToDoItemBulkUpd
== Registering the Service
Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]):
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then Apache Isis' core implementation of `Scratchpad` service is automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
+`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+implementation of `Scratchpad` service is automatically registered and injected (it is annotated with `@DomainService`)
+so no further configuration is required.
+To use an alternative implementation, use
+xref:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
http://git-wip-us.apache.org/repos/asf/isis/blob/19cdaaba/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-SudoService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-SudoService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-SudoService.adoc
index 31ef7b4..79c39c9 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-SudoService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-SudoService.adoc
@@ -28,9 +28,10 @@ public interface SudoService {
}
----
-which will run the provided block of code (a `Runnable` or a `Callable`) in a way such that calls to `DomainObjectContainer#getUser()` will return the specified user (and roles, if specified)
+which will run the provided block of code (a `Runnable` or a `Callable`) in a way such that calls to
+`DomainObjectContainer#getUser()` will return the specified user (and roles, if specified)
-The core framework provides a default implementation of this service (`o.a.i.core.runtime.services.sudo.SudoServiceDefault`)
+The core framework provides a default implementation of this service (`o.a.i.core.runtime.services.sudo.SudoServiceDefault`).
@@ -59,11 +60,10 @@ protected void execute(final ExecutionContext ec) {
== Registering the Service
Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]):
+`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+implementation of `SudoService` service is automatically registered and injected (it is annotated with
+`@DomainService`) so no further configuration is required.
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then Apache Isis' core implementation of `SudoService` service is automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
+To use an alternative implementation, use
+xref:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
http://git-wip-us.apache.org/repos/asf/isis/blob/19cdaaba/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-WrapperFactory.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-WrapperFactory.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-WrapperFactory.adoc
index be30257..bd1cf7c 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-WrapperFactory.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-WrapperFactory.adoc
@@ -153,11 +153,10 @@ The original intent of this API was to enable test transcripts to be captured (i
== Registering the Service
Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]):
+`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+implementation of `WrapperFactory` service is automatically registered and injected (it is annotated with
+`@DomainService`) so no further configuration is required.
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then Apache Isis' core implementation of `WrapperFactory` service is automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
+To use an alternative implementation, use
+xref:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
http://git-wip-us.apache.org/repos/asf/isis/blob/19cdaaba/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-XmlSnapshotService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-XmlSnapshotService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-XmlSnapshotService.adoc
index 79fe2f8..a8e0da1 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-XmlSnapshotService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-XmlSnapshotService.adoc
@@ -194,14 +194,14 @@ public interface XmlSnapshotService {
== Registering the Service
Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]):
+`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+implementation of `XmlSnapshotService` service is automatically registered and injected (it is annotated with
+`@DomainService`) so no further configuration is required.
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
+To use an alternative implementation, use
+xref:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
-then Apache Isis' core implementation of `XmlSnapshotService` service is automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
== Related Services
@@ -210,6 +210,11 @@ The xref:rg.adoc#_rg_services-api_manpage-BookmarkService[`BookmarkService`] pro
The xref:rg.adoc#_rg_services-api_manpage-MementoService[`MementoService`] also provides a mechanism for generating string representations of domain objects.
+The xref:rg.adoc#_rg_services-api_manpage-JaxbService[`JaxbService`] (`1.11.0-SNAPSHOT`) is a simple wrapper around
+standard JAXB functionality for generating both XMLs and XSDs from JAXB-annotated classes. Note that (as of
+`1.11.0-SNAPSHOT`) there is built-in support for JAXB classes (ie annotated with
+xref:rg.adoc#_rg_annotations_manpage-XmlRootElement[`@XmlRootElement`]) to be used as view models.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/19cdaaba/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi.adoc
index b0575ec..76c89a6 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi.adoc
@@ -178,6 +178,17 @@ depends on: +
|
+|xref:rg.adoc#_rg_services-spi_manpage-UrlEncodingService[`o.a.i.applib.` +
+`services.urlencoding` +
+`UrlEncodingService`]
+|Converts strings into a form safe for use within a URL. Used to convert view models mementos into usable URL form.
+
+|`UrlEncodingServiceUsingBaseEncoding` +
+``o.a.i.applib`` +
+``isis-core-applib``
+|
+
+
|xref:rg.adoc#_rg_services-spi_manpage-UserProfileService[`o.a.i.applib.` +
`services.userprof` +
`UserProfileService`]
http://git-wip-us.apache.org/repos/asf/isis/blob/19cdaaba/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-AuditingService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-AuditingService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-AuditingService.adoc
index 5956bc0..464c25b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-AuditingService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-AuditingService.adoc
@@ -63,15 +63,15 @@ The typical way to indicate that an object should be audited is to annotate it w
== Registering the Services
-Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]):
+The (non-ASF) http://github.com/isisaddons/isis-module-audit[Isis addons' audit] module provides an implementation of
+this service (`AuditingService`), and also provides a number of related domain services (`AuditingServiceMenu`,
+`AuditingServiceRepository` and `AuditingServiceContributions`).
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
+Assuming that an `AppManifest` is being used to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app])
+then this can be activated by updating the `pom.xml` and updating the `AppManifest#getModules()` method.
-then adding the (non-ASF) http://github.com/isisaddons/isis-module-audit[Isis addons' audit] module to the classpath will automatically register the `AuditingService`, `AuditingServiceMenu`, `AuditingServiceRepository` and `AuditingServiceContributions` services. If menu items or contributions are not required in the UI, these can be suppressed either using security or by implementing a xref:ug.adoc#_ug_more-advanced_decoupling_vetoing-visibility[vetoing subscriber].
+If menu items or contributions are not required in the UI, these can be suppressed either using security or by
+implementing a xref:ug.adoc#_ug_more-advanced_decoupling_vetoing-visibility[vetoing subscriber].
http://git-wip-us.apache.org/repos/asf/isis/blob/19cdaaba/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-BackgroundCommandService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-BackgroundCommandService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-BackgroundCommandService.adoc
index a69b540..b759fc9 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-BackgroundCommandService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-BackgroundCommandService.adoc
@@ -103,17 +103,18 @@ The imperative approach involves explicitly calling the xref:rg.adoc#_rg_service
== Registering the Services
-Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]):
+The (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module provides an implementation
+of this service (`BackgroundCommandService`), and also provides a number of related domain services
+(`BackgroundCommandServiceJdo`, `BackgroundCommandJdoRepository` and `BackgroundCommandServiceJdoContributions`). This
+module also provides service implementations of the
+xref:rg.adoc#_rg_services-spi_manpage-CommandService[`CommandService`].
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
+Assuming that an `AppManifest` is being used to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app])
+then this can be activated by updating the `pom.xml` and updating the `AppManifest#getModules()` method.
-then adding the (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module to the classpath will automatically register the `BackgroundCommandServiceJdo`, `BackgroundCommandJdoRepository` and `BackgroundCommandServiceJdoContributions` services. If contributions are not required in the UI, these can be suppressed either using security or by implementing a xref:ug.adoc#_ug_more-advanced_decoupling_vetoing-visibility[vetoing subscriber].
+If contributions are not required in the UI, these can be suppressed either using security or by implementing a
+xref:ug.adoc#_ug_more-advanced_decoupling_vetoing-visibility[vetoing subscriber].
-Note that this module also provides service implementations of the xref:rg.adoc#_rg_services-spi_manpage-CommandService[`CommandService`].
http://git-wip-us.apache.org/repos/asf/isis/blob/19cdaaba/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-ClassDiscoveryService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-ClassDiscoveryService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-ClassDiscoveryService.adoc
index b7330ba..2aea1ea 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-ClassDiscoveryService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-ClassDiscoveryService.adoc
@@ -71,14 +71,12 @@ Other usages of the `ClassDiscoveryService` are likely to work in a similar way,
== Registering the Services
Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]):
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then Apache Isis' core implementation of `ClassDiscoveryService2` service is automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
+`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' core
+implementation of `ClassDiscoveryService2` service is automatically registered and injected (it is annotated with
+`@DomainService`) so no further configuration is required.
+To use an alternative implementation, use
+xref:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
http://git-wip-us.apache.org/repos/asf/isis/blob/19cdaaba/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-CommandService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-CommandService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-CommandService.adoc
index 4551a2e..fd07d4d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-CommandService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-CommandService.adoc
@@ -70,18 +70,18 @@ The typical way to indicate that an action should be reified into a `Command` is
== Registering the Services
-Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]):
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
+The (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module provides an implementation
+of this service (`CommandService`), and also provides a number of related domain services
+(`CommandJdoRepository` and `CommandServiceJdoContributions`). This
+module also provides service implementations of the
+xref:rg.adoc#_rg_services-spi_manpage-CommandService[`BackgroundCommandService`].
+Assuming that an `AppManifest` is being used to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app])
+then this can be activated by updating the `pom.xml` and updating the `AppManifest#getModules()` method.
-then adding the (non-ASF) http://github.com/isisaddons/isis-module-command[Isis addons' command] module to the classpath will automatically register the `CommandServiceJdo`, `CommandJdoRepository` and `CommandServiceJdoContributions` services. If contributions are not required in the UI, these can be suppressed either using security or by implementing a xref:ug.adoc#_ug_more-advanced_decoupling_vetoing-visibility[vetoing subscriber].
+If contributions are not required in the UI, these can be suppressed either using security or by implementing a
+xref:ug.adoc#_ug_more-advanced_decoupling_vetoing-visibility[vetoing subscriber].
-Note that this module also provides service implementations of the xref:rg.adoc#_rg_services-spi_manpage-BackgroundCommandService[`BackgroundCommandService`].
http://git-wip-us.apache.org/repos/asf/isis/blob/19cdaaba/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-ContentMappingService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-ContentMappingService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-ContentMappingService.adoc
index 86d3229..ad38b2f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-ContentMappingService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-ContentMappingService.adoc
@@ -41,7 +41,9 @@ This is an "internal" SPI, meaning that it uses types that are not part of the I
== Implementations
-No default implementations are provided by Apache Isis framework itself. However, the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] includes a sample implementation to convert its `ToDoItem` entity into a `ToDoItemDto` (JAXB annotated and derived from an XSD). This uses the link:http://orika-mapper.github.io/orika-docs/intro.html[Orika] mapping library.
+No default implementations are provided by Apache Isis framework itself. However, the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] includes a sample implementation to convert its `ToDoItem`
+entity into (two different versions of) a `ToDoItemDto` (JAXB annotated). This uses the
+link:http://orika-mapper.github.io/orika-docs/intro.html[Orika] mapping library.
The source code is:
@@ -81,7 +83,6 @@ public class CustomContentMappingService implements ContentMappingService {
}
return null;
}
-
@javax.inject.Inject
private BookmarkService bookmarkService;
}
http://git-wip-us.apache.org/repos/asf/isis/blob/19cdaaba/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-ContentNegotiationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-ContentNegotiationService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-ContentNegotiationService.adoc
index 7d6dd49..17972e8 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-ContentNegotiationService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-ContentNegotiationService.adoc
@@ -187,15 +187,13 @@ If the property is not set, then the default depends on the xref:rg.adoc#_rg_run
== Registering the Services
Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]):
-
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then Isis' default implementation of `ContentNegotiationService` service is automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
+`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' default
+implementation of `ContentNegotiationService` service is automatically registered and injected (it is annotated with
+`@DomainService`) so no further configuration is required.
+To use an alternative implementation, use
+xref:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
http://git-wip-us.apache.org/repos/asf/isis/blob/19cdaaba/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-EmailNotificationService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-EmailNotificationService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-EmailNotificationService.adoc
index 7de4c70..ba199b0 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-EmailNotificationService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-spi_manpage-EmailNotificationService.adoc
@@ -39,7 +39,8 @@ If `isConfigured()` returns false then it is _not_ valid to call `send(...)` (an
== Implementation
-The framework provides a default implementation, `o.a.i.core.runtime.services.userreg.EmailNotificationServiceDefault` that constructs the emails to send.
+The framework provides a default implementation, `o.a.i.core.runtime.services.userreg.EmailNotificationServiceDefault`
+that constructs the emails to send.
@@ -63,14 +64,13 @@ To ensure that your alternative implementation takes the place of the default im
== Registering the Service
Assuming that the `configuration-and-annotation` services installer is configured (implicit if using the
-`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]):
+`AppManifest` to xref:rg.adoc#_rg_classes_AppManifest-bootstrapping[bootstrap the app]) then Apache Isis' default
+implementation of `EmailNotificationService` service is automatically registered and injected (it is annotated with
+`@DomainService`) so no further configuration is required.
-[source,ini]
-----
-isis.services-installer=configuration-and-annotation
-----
-
-then Isis' default implementation of `EmailNotificationService` service is automatically registered and injected (it is annotated with `@DomainService`) so no further configuration is required.
+To use an alternative implementation, use
+xref:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] (as explained
+further in this xref:ug.adoc#_ug_how-tos_replacing-default-service-implementations["how to"] tip).
== Related Services