You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2017/03/31 07:10:59 UTC
[23/51] [partial] isis git commit: ISIS-1521: reorganizes asciidoc
documentation, moves into subdirs (both guides and other pages)
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugbtb_view-models_jaxb.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_view-models_jaxb.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_view-models_jaxb.adoc
deleted file mode 100644
index 16d15ae..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_view-models_jaxb.adoc
+++ /dev/null
@@ -1,415 +0,0 @@
-[[_ugbtb_view-models_jaxb]]
-= JAXB-annotated DTOs
-: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/
-
-
-
-As noted in the xref:ugbtb.adoc#_ugbtb_view-models_use-cases[introduction], view models can also be defined using JAXB annotations.
-The serialized form of these view models is therefore XML, which also enables these view models
-to act as DTOs.
-
-In case it's not obvious, these DTOs are still usable as "regular" view models; they will render in the xref:ugvw.adoc#[Wicket viewer] just like any other.
-In fact, these JAXB-annotated view models are in many regards the most powerful of all the various ways of writing view models:
-
-* their entire state (collections as well as properties) is automatically managed from interaction to interaction. +
-+
-In contrast, using xref:rgant.adoc#_rgant-ViewModel[`@ViewModel`] (or its xref:rgant.adoc#_rgant-DomainObject_nature[`@DomainObject#nature()`] equivalent) will only manage the state of properties, but not collections.
-And if using the xref:rgcms.adoc#_rgcms_classes_super_ViewModel[`ViewModel`] interface, then the programmer must write all the state management (lots of boilerplate).
-
-* JAXB-annotated view models are editable.
-
-The examples in this section uses the DTO for `ToDoItem`, taken from the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp].
-This DTO is defined as follows:
-
-[source,java]
-----
-package todoapp.app.viewmodels.todoitem.v1; // <1>
-@XmlRootElement(name = "toDoItemDto") // <2>
-@XmlType(
- propOrder = { // <3>
- "majorVersion", "minorVersion",
- "description", "category", ...
- "toDoItem", "similarItems"
- }
-)
-@DomainObjectLayout(
- titleUiEvent = TitleUiEvent.Doop.class // <4>
-)
-public class ToDoItemV1_1 implements Dto { // <5>
- @XmlElement(required = true, defaultValue = "1") // <6>
- public final String getMajorVersion() { return "1"; }
- @XmlElement(required = true, defaultValue = "1") // <7>
- public String getMinorVersion() { return "1"; }
-
- @XmlElement(required = true) // <8>
- @Getter @Setter
- protected String description;
- @XmlElement(required = true)
- @Getter @Setter
- protected String category;
- ...
-
- @Getter @Setter // <9>
- protected ToDoItem toDoItem;
- @XmlElementWrapper // <10>
- @XmlElement(name = "todoItem")
- @Getter @Setter
- protected List<ToDoItem> similarItems = Lists.newArrayList();
-}
-----
-<1> package name encodes major version; see discussion on xref:ugbtb.adoc#__ugbtb_view-models_jaxb_versioning[versioning]
-<2> identifies this class as a view model and defines the root element for JAXB serialization
-<3> all properties in the class must be listed; (they can be ignored using `@XmlTransient`)
-<4> demonstrating use of UI events for a subscriber to provide the DTO's title; see xref:rgant.adoc#_rgant-DomainObjectLayout_titleUiEvent[`@DomainObjectLayout#titleUiEvent()`].
-<5> class name encodes (major and) minor version; see discussion on xref:ugbtb.adoc#__ugbtb_view-models_jaxb_versioning[versioning]
-<6> again, see discussion on xref:ugbtb.adoc#__ugbtb_view-models_jaxb_versioning[versioning]
-<7> again, see discussion on xref:ugbtb.adoc#__ugbtb_view-models_jaxb_versioning[versioning]
-<8> simple scalar properties
-<9> reference to a persistent entity; discussed xref:ugbtb.adoc#__ugbtb_view-models_jaxb_referencing-domain-entities[below]
-<10> reference to a collection of persistent entities; again discussed xref:ugbtb.adoc#__ugbtb_view-models_jaxb_referencing-domain-entities[below]
-
-
-
-[[__ugbtb_view-models_jaxb_referencing-domain-entities]]
-== Referencing Domain Entities
-
-It's quite common for view models to be "backed by" (be projections of) some underlying domain entity.
-The `ToDoItemDto` we've been using as the example in this section is an example: there is an underlying `ToDoItem` entity.
-
-It wouldn't make sense to serialize out the state of a persistent entity: the point of a DTO is to act as a facade on top of the entity so that the implementation details (of the entity's structure) don't leak out to the consumer.
-However, the identity of the underlying entity can be well defined; Apache Isis defines the xref:rgcms.adoc#_rgcms_schema-common[Common schema] which defines the `<oid-dto>` element (and corresponding `OidDto` class): the object's type and its identifier.
-This is basically a formal XML equivalent to the `Bookmark` object obtained from the xref:rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`].
-
-There is only one requirement to make this work: every referenced domain entity must be annotated with xref:rgant.adoc#_rgant-XmlJavaTypeAdapter[`@XmlJavaTypeAdapter`], specifying the framework-provided `PersistentEntityAdapter.class`.
-This class is similar to the `BookmarkService`: it knows how to create an `OidDto` from an object reference.
-
-Thus, in our view model we can legitimately write:
-
-[source,java]
-----
-package todoapp.app.viewmodels.todoitem.v1;
-...
-public class ToDoItemV1_1 implements Dto {
- ...
- @Getter @Setter
- protected ToDoItem toDoItem;
-}
-----
-
-All we need to do is remember to add that `@XmlJavaTypeAdapter` annotation to the referenced entity:
-
-[source,java]
-----
-@XmlJavaTypeAdapter(PersistentEntityAdapter.class)
-public class ToDoItem ... {
- ...
-}
-----
-
-
-It's also possible for a DTO to hold collections of objects.
-These can be of any type, either simple properties, or references to other objects.
-The only bit of boilerplate that is required is the `@XmlElementWrapper` annotation.
-This instructs JAXB to create an XML element (based on the field name) to contain each of the elements.
-(If this is omitted then the contents of the collection are at the same level as the properties; almost certainly not what is required).
-
-For example, the DTO also contains:
-
-[source,java]
-----
-package todoapp.app.viewmodels.todoitem.v1;
-...
-public class ToDoItemV1_1 implements Dto {
- ...
- @XmlElementWrapper
- @XmlElement(name = "todoItem")
- @Getter @Setter
- protected List<ToDoItem> similarItems = Lists.newArrayList();
-}
-----
-
-
-There's nothing to prevent a JAXB DTO from containing rich graphs of data, parent containing children containing children.
-Be aware though that all of this state will become the DTO's memento, ultimately converted into a URL-safe form, by way of the xref:rgsvc.adoc#_rgsvc_spi_UrlEncodingService[`UrlEncodingService`].
-
-There are limits to the lengths of URLs, however.
-Therefore the DTO should not include state that can easily be derived from other information.
-If the URL does exceed limits, then provide a custom implementation of xref:rgsvc.adoc#_rgsvc_spi_UrlEncodingService[`UrlEncodingService`] to handle the memento string in some other fashion (eg substituting it with a GUID, with the memento cached somehow on the server).
-
-
-
-
-
-[[__ugbtb_view-models_jaxb_versioning]]
-== Versioning
-
-The whole point of using DTOs (in Apache Isis, at least) is to define a formal contact between two inter-operating but independent applications.
-Since the only thing we can predicate about the future with any certainty is that it one or both of these applications will change, we should version DTOs from the get-go.
-This allows us to make changes going forward without unnecessarily breaking existing consumers of the data.
-
-[NOTE]
-====
-There are several ways that versioning might be accomplished; we base our guidelines on this link:http://www.xfront.com/Versioning.pdf[article] taken from Roger Costello's blog, well worth a read.
-====
-
-We can distinguish two types of changes:
-
-* backwardly compatible changes
-* breaking changes.
-
-We can immediately say that the XSD namespace should change only when there is a major/breaking change, if following link:http://semver.org[semantic versioning] that means when we bump the major version number v1, v2, etc.
-
-XML namespaces correspond (when using JAXB) to Java packages.
-We should therefore place our DTOs in a package that contains only the major number; this package will eventually contain a range of DTOs that are intended to be backwardly compatible with one another.
-The package should also have a `package-info.java`; it is this that declares the XSD namespace:
-
-[source,java]
-----
-@javax.xml.bind.annotation.XmlSchema(
- namespace = "http://viewmodels.app.todoapp/todoitem/v1/Dto.xsd", // <1>
- xmlns = {
- @javax.xml.bind.annotation.XmlNs(
- namespaceURI = "http://isis.apache.org/schema/common",
- prefix = "com"
- )
- },
- elementFormDefault = javax.xml.bind.annotation.XmlNsForm.QUALIFIED
-)
-package todoapp.app.viewmodels.todoitem.v1; // <2>
-----
-<1> the namespace URI, used by the DTO residing in this package.
-<2> the package in which the DTO resides. Note that this contains only the major version.
-
-Although there is no requirement for the namespace URI to correspond to a physical URL, it should be unique.
-This usually means including a company domain name within the string.
-
-As noted above, this package will contain multiple DTO classes all with the same namespace; these represent a set of minor versions of the DTO, each subsequent one intended to be backwardly compatible with the previous.
-Since these DTO classes will all be in the same package (as per the xref:ugbtb.adoc#__ugbtb_view-models_jaxb_using-packages-to-version[advice above]), the class should therefore include the minor version name:
-
-[source,java]
-----
-package todoapp.app.viewmodels.todoitem.v1; // <1>
-...
-public class ToDoItemV1_1 implements Dto { // <2>
- ...
-}
-----
-<1> package contains the major version only
-<2> DTO class contains the (major and) minor version
-
-
-We also recommend that each DTO instance should also specify the version of the XSD schema that it is logically compatible with.
-Probably most consumers will not persist the DTOs; they will be processed and then discarded.
-However, it would be wrong to assume that is the case in all cases; some consumers might choose to persist the DTO (eg for replay at some later state).
-
-Thus:
-
-[source,java]
-----
-public class ToDoItemV1_1 implements Dto {
- @XmlElement(required = true, defaultValue = "1")
- public final String getMajorVersion() { return "1"; } // <1>
- @XmlElement(required = true, defaultValue = "1")
- public String getMinorVersion() { return "1"; } // <2>
- ...
-}
-----
-<1> returns the major version (in sync with the package)
-<2> returns the minor version (in sync with the class name)
-
-These methods always return a hard-coded literal.
-Any instances serialized from these classes will implicitly "declare" the (major and) minor version of the schema with which they are compatible.
-If a consumer has a minimum version that it requires, it can therefore inspect the XML instance itself to determine if it is able to consume said XML.
-
-If a new (minor) version of a DTO is required, then we recommend copying-and-pasting the previous version, eg:
-
-[source,java]
-----
-public class ToDoItemV1_2 implements Dto {
- @XmlElement(required = true, defaultValue = "1")
- public final String getMajorVersion() { return "1"; }
- @XmlElement(required = true, defaultValue = "2")
- public String getMinorVersion() { return "2"; }
- ...
-}
-----
-
-Obviously, only changes made must be backward compatible, eg new members must be optional.
-
-Alternatively, you might also consider simply editing the source file, ie renaming the class and bumping up the value returned by `getMinorVersion()`.
-
-We also _don't_ recommend using inheritance (ie `ToDoItemV1_2` should not inherit from `ToDoItemV1_1`; this creates unnecessary complexity downstream if generating XSDs and DTOs for the downstream consumer.
-
-
-[[__ugbtb_view-models_jaxb_generating-xsds-and-dtos]]
-== Generating XSDs and DTOs
-
-In the section xref:ugbtb.adoc#__ugbtb_view-models_jaxb_referencing-domain-entities[above] it was explained how a view model DTO can transparent reference any "backing" entities; these references are converted to internal object identifiers.
-
-However, if the consumer of the XML is another Java process (eg running within an Apache Camel route), then you might be tempted/expect to be able to use the same DTO within that Java process.
-After a little thought though you'll realize that (duh!) of course you cannot; the consumer runs in a different process space, and will not have references to those containing entities.
-
-There are therefore two options:
-
-* either choose not to have the view model DTO reference any persistent entities, and simply limit the DTO to simple scalars. +
-+
-Such a DTO will then be usable in both the Apache Isis app (to generate the original XML) and in the consumer.
-The xref:rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`] can be used to obtain the object identifiers
-
-* alternatively, generate a different DTO for the consumer from the XSD of the view model DTO.
-
-The (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] uses the second approach; generating the XSD and consumer's DTO is mostly just boilerplate `pom.xml` file.
-In the todoapp this can be found in the `todoapp-xsd` Maven module, whose `pom.xml` is structured as two profiles:
-
-[source,xml]
-----
-<project ... >
- <artifactId>todoapp-xsd</artifactId>
- <dependencies>
- <dependency>
- <groupId>${project.groupId}</groupId>
- <artifactId>todoapp-app</artifactId>
- </dependency>
- </dependencies>
- <profiles>
- <profile>
- <id>isis-xsd</id>
- <activation>
- <property>
- <name>!skip.isis-xsd</name>
- </property>
- </activation>
- ...
- </profile>
- <profile>
- <id>xjc</id>
- <activation>
- <property>
- <name>!skip.xjc</name>
- </property>
- </activation>
- ...
- </profile>
- </profiles>
-</project>
-----
-
-The `isis-xsd` profile generates the XSD using the xref:rgmvn.adoc#_rgmvn_xsd[`xsd` goal] of Isis' maven plugin:
-
-[source,xml]
-----
-<build>
- <plugins>
- <plugin>
- <groupId>org.apache.isis.tool</groupId>
- <artifactId>isis-maven-plugin</artifactId>
- <version>${isis.version}</version>
- <configuration>
- <appManifest>todoapp.dom.ToDoAppDomManifest</appManifest>
- <jaxbClasses>
- <jaxbClass>todoapp.app.viewmodels.todoitem.v1.ToDoItemV1_1</jaxbClass>
- </jaxbClasses>
- <separate>false</separate>
- <commonSchemas>false</commonSchemas>
- </configuration>
- <dependencies>
- <dependency>
- <groupId>${project.groupId}</groupId>
- <artifactId>todoapp-dom</artifactId>
- <version>${project.version}</version>
- </dependency>
- <dependency>
- <groupId>com.google.guava</groupId>
- <artifactId>guava</artifactId>
- <version>16.0.1</version>
- </dependency>
- </dependencies>
- <executions>
- <execution>
- <phase>generate-sources</phase>
- <goals>
- <goal>xsd</goal>
- </goals>
- </execution>
- </executions>
- </plugin>
- <plugin>
- <artifactId>maven-assembly-plugin</artifactId>
- <version>2.5.3</version>
- <configuration>
- <descriptor>src/assembly/dep.xml</descriptor>
- </configuration>
- <executions>
- <execution>
- <id>create-archive</id>
- <phase>package</phase>
- <goals>
- <goal>single</goal>
- </goals>
- </execution>
- </executions>
- </plugin>
- </plugins>
-</build>
-----
-
-The `todoapp.dom.ToDoAppDomManifest` is a cut-down version of the app manifest that identifies only the `dom` domain services.
-
-The `xjc` profile, meanwhile, uses the `maven-jaxb2-plugin` (a wrapper around the `schemagen` JDK tool) to generate a DTO from the XSD generated by the preceding profile:
-
-[source,xml]
-----
-<build>
- <plugins>
- <plugin>
- <groupId>org.jvnet.jaxb2.maven2</groupId>
- <artifactId>maven-jaxb2-plugin</artifactId>
- <version>0.12.3</version>
- <executions>
- <execution>
- <id>xjc-generate</id>
- <phase>generate-sources</phase>
- <goals>
- <goal>generate</goal>
- </goals>
- </execution>
- </executions>
- <configuration>
- <removeOldOutput>true</removeOldOutput>
- <schemaDirectory>
- target/generated-resources/isis-xsd/viewmodels.app.todoapp
- </schemaDirectory>
- <schemaIncludes>
- <schemaInclude>todoitem/v1/Dto.xsd</schemaInclude>
- </schemaIncludes>
- <bindingDirectory>src/main/resources</bindingDirectory>
- <bindingIncludes>
- <bindingInclude>binding.xml</bindingInclude>
- </bindingIncludes>
- <catalog>src/main/resources/catalog.xml</catalog>
- </configuration>
- </plugin>
- <plugin>
- <groupId>org.codehaus.mojo</groupId>
- <artifactId>build-helper-maven-plugin</artifactId>
- <version>1.9.1</version>
- <executions>
- <execution>
- <id>add-source</id>
- <phase>generate-sources</phase>
- <goals>
- <goal>add-source</goal>
- </goals>
- <configuration>
- <sources>
- <source>target/generated-sources/xjc</source>
- </sources>
- </configuration>
- </execution>
- </executions>
- </plugin>
- </plugins>
-</build>
-----
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugbtb_view-models_programming-model.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_view-models_programming-model.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_view-models_programming-model.adoc
deleted file mode 100644
index 11be3f0..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_view-models_programming-model.adoc
+++ /dev/null
@@ -1,87 +0,0 @@
-[[_ugbtb_view-models_programming-model]]
-= Programming Model
-: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/
-
-
-
-So much for the theory; how should view models be implemented? Fundamentally all view models' state is serialized into
-a string memento; this memento is then held by the client (browser) in the form of a URL. As you might imagine, this
-URL can become quite long, but Apache Isis offers a mechanism (the xref:rgsvc.adoc#_rgsvc_spi_UrlEncodingService[`UrlEncodingService`]) if it exceeds the maximum length for a URL
-(2083 characters). Also, of course, this string memento must only contain characters that it is valid for use within
-a URL.
-
-While the underlying technique is the same irrespective of use case, the programming model provides various ways of
-defining a view model so that the original intent is not lost. They are:
-
-.View model programming model
-[cols="1a,4a,2a", options="header"]
-|===
-
-| Use case
-| Code
-| Description
-
-
-| External entity
-|[source,java]
-----
-@DomainObject(nature=Nature.EXTERNAL_ENTITY)
-public class CustomerRecordOnSAP { ... }
-----
-|Annotated with xref:rgant.adoc#_rgant-DomainObject_nature[`@DomainObject#nature()`] and a nature of `EXTERNAL_ENTITY`, with memento derived automatically from the properties of the domain object. Collections are ignored, as are any properties annotated as xref:rgant.adoc#_rgant-Property_notPersisted[not persisted].
-
-| In-memory entity
-|[source,java]
-----
-@DomainObject(nature=Nature.INMEMORY_ENTITY)
-public class Log4JAppender { ... }
-----
-|As preceding, but using a nature of `INMEMORY_ENTITY`.
-
-|Application view model
-|[source,java]
-----
-@DomainObject(nature=Nature.VIEW_MODEL)
-public class Dashboard { ... }
-----
-|As preceding, but using a nature of `VIEW_MODEL`.
-
-|Application view model
-|
-[source,java]
-----
-@ViewModel
-public class Dashboard { ... }
-----
-
-|Annotated with xref:rgant.adoc#_rgant-ViewModel[`@ViewModel`] annotation (effectively just an alias)' memento is as preceding: from "persisted" properties, collections ignored
-
-|Application view model
-|
-[source,java]
-----
-public class ExcelUploadManager implements ViewModel {
- public String viewModelMemento() { ... }
- public void viewModelInit(String memento) { ... }
-}
-|Implement xref:rgcms.adoc#_rgcms_classes_super_ViewModel[`ViewModel`] interface. The memento is as defined by the
-interface's methods: the programmer has full control (but also full responsibility) for the string memento.
-
-|DTO
-|
-[source,java]
-----
-@XmlRootElement("customer")
-public class CustomerDto { ... }
-----
-|Annotate using JAXB xref:rgant.adoc#_rgant-XmlRootElement[`@XmlRootElement`] annotation. Memento
-derived automatically by serializing the XML graph as implied by the JAXB annotations. Note that (unlike `@ViewModel`
-et al) this state _can_ include collections.
-|===
-
-JAXB-annotated DTOs are discussed in more detail immediately xref:rg.adoc#_ugbtb_view-models_jaxb[below].
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugbtb_view-models_use-cases.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_view-models_use-cases.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_view-models_use-cases.adoc
deleted file mode 100644
index 2da1e5d..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_view-models_use-cases.adoc
+++ /dev/null
@@ -1,160 +0,0 @@
-[[_ugbtb_view-models_use-cases]]
-= Use Cases
-: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/
-
-
-When developing an Apache Isis application you will most likely start off with the persistent domain entities:
-`Customer`, `Order`, `Product`, and so on. For some applications this may well suffice. However, if the application
-needs to integrate with other systems, or if the application needs to support reasonably complex business processes, then you may need to look beyond just domain entities. This section explores these use cases.
-
-[[__ugbtb_view-models_use-cases_externally-managed-entities]]
-== Externally-managed entities
-
-Sometimes the entities that make up your application are persisted not in the local JDO/DataNucleus database
-but reside in some other system, for example accessible only through a SOAP web service. Logically that data
-might still be considered a domain entity and we might want to associate behaviour with it, however it cannot be
-modelled as a domain entity if only because JDO/DataNucleus doesn't know about the entity nor how to retrieve or
-update it.
-
-There are a couple of ways around this: we could either replicate the data somehow from the external system into the
- Isis-managed database (in which case it is once again just another domain entity), or we could set up a stub/proxy for
- the externally managed entity. This proxy would hold the reference to the externally-managed domain entity (eg an
- external id), as well as the "smarts" to know how to interact with that entity (by making SOAP web service calls etc).
-
-The stub/proxy is a type of view model: a view - if you like - onto the domain entity managed by the external system.
-
-[NOTE]
-====
-DataNucleus does in fact define its own link:http://www.datanucleus.org/documentation/extensions/store_manager.html[Store Manager] extension point, so an alternative architecture would be to implement this interface such that DataNucleus
-could make the calls to the external system; these externally-persisted domain entities would therefore be modelled as regular `@PersistenceCapable` entities after all. For entities not persisted externally the implementation would delegate down to the default RDBMS-specific `StoreManager` provided by DataNucleus itself.
-
-An implementation that supported only reading from an external entity ought to be comparatively straight-forward, but
-implementing one that also supported updating external entities would need to carefully consider error conditions if the
-external system is unavailable; distributed transactions are most likely difficult/impossible to implement (and not
-desirable in any case).
-====
-
-
-[[__ugbtb_view-models_use-cases_in-memory-entities]]
-== In-memory entities
-
-As a variation on the above, sometimes there are domain objects that are, conceptually at least entities, but whose
-state is not actually persisted anywhere, merely held in-memory (eg in a hash).
-
-A simple example might be read-only configuration data that is read from a config file (eg log4j appender
-definitions) but thereafter is presented in the UI just like any other entity.
-
-
-[[__ugbtb_view-models_use-cases_application-layer-view-models]]
-== Application-layer view models
-
-Domain entities (whether locally persisted using JDO/DataNucleus or managed externally) are the bread-and-butter of Apache Isis applications: the focus after all, should be on the business domain concepts and ensuring that they are
-solid. Generally those domain entities will make sense to the business domain experts: they form the _ubiquitous language_ of the domain. These domain entities are part of the domain layer.
-
-That said, it may not always be practical to expect end-users of the application to interact solely with those domain
-entities. For example, it may be useful to show a dashboard of the most significant data in the system to a user,
-often pulling in and aggregating information from multiple points of the app. Obtaining this information by hand (by
- querying the respective services/repositories) would be tedious and slow; far better to have a dashboard do the job for
- the end user.
-
-A dashboard object is a model of the most relevant state to the end-user, in other words it is (quite literally) a view
- model. It is not a persisted entity, instead it belongs to the application layer.
-
-A view model need not merely aggregate data; it could also provide actions of its own. Most likely these actions will
-be queries and will always ultimately just delegate down to the appropriate domain-layer service/repository. But in
-some cases such view model actions might also modify state of underlying domain entities.
-
-Another common use for view models is to help co-ordinate complex business processes; for example to perform a
-quarterly invoicing run, or to upload annual interest rates from an Excel spreadsheet. In these cases the view model
-might have some state of its own, but in most cases that state does not need to be persisted per se.
-
-.Desire Lines
-****
-One way to think of application view models is as modelling the "desire line": the commonly-trod path
-that end-users must follow to get from point A to point B as quickly as possible.
-
-To explain: there are link:http://ask.metafilter.com/62599/Where-the-sidewalk-ends[documented]
-link:https://sivers.org/walkways[examples]
-link:http://www.softpanorama.org/People/Wall/larry_wall_articles_and_interviews.shtml[that] architects of university
-campus will only add in paths some while after the campus buildings are complete: let the pedestrians figure out the
-routes they want to take. The name we like best for this idea is "desire lines", though it has also been called
-a "desire path", "paving the path" or "paving the sidewalk".
-
-What that means is you should add view models _after_ having built up the domain layer, rather than before. These view
-models pave that commonly-trod path, automating the steps that the end-user would otherwise have to do by hand.
-
-It takes a little practice though, because even when building the domain layer "first", you should still bear in mind
-what the use cases are that those domain entities are trying to support. You certainly _shouldn't_ try to build out a
-domain layer that could support every conceivable use case before starting to think about view models.
-
-Instead, you should iterate. Identify the use case/story/end-user objective that you will deliver value to the
-business. Then build out the minimum domain entities to support that use case (refining the xref:ugfun.adoc#__ugfun_core-concepts_philosophy_domain-driven-design_ubiquitous-language[ubiquitous language] as you
-go). Then, identify if there any view models that could be introduced which would simplify the end-user interactions
-with the system (perhaps automating several related use cases together).
-****
-
-[[__ugbtb_view-models_use-cases_dtos]]
-== DTOs
-
-DTOs (data transfer objects) are simple classes that (according to link:https://en.wikipedia.org/wiki/Data_transfer_object[wikipedia]) "carry data between processes".
-
-If those two processes are parts of the same overall application (the same team builds and deploys both server and
-client) then there's generally no need to define a DTO; just access the entities using Apache Isis'
-xref:ugvro.adoc#[RestfulObjects viewer].
-
-On the other hand, if the client consuming the DTO is a different application -- by which we mean developed/deployed by
-a different (possible third-party) team -- then the DTOs act as a formal contract between the provider and the consumer.
-In such cases, exposing domain entities over xref:ugvro.adoc#[RestfulObjects] would be
-"A Bad Thing"(TM) because the consumer would in effect have access to implementation details that could then not be
-easily changed by the producer.
-
-To support this use case, a view model can be defined such that it can act as a DTO. This is done by annotating the
-class using JAXB annotations; this allows the consumer to obtain the DTO in XML format along with a corresponding
-XSD schema describing the structure of that XML. A discussion of how that might be done using an ESB such as
-link:http://camel.apache.org[Apache Camel(TM)] follows xref:ugbtb.adoc#__ugbtb_view-models_use-cases_dtos_consumers[below].
-
-In case it's not obvious, these DTOs are still usable as "regular" view models; they will render in the xref:ugvw.adoc#[Wicket viewer] just like any other. In fact (as the xref:ugbtb.adoc#_ugbtb_view-models_programming-model[programming model] section below makes clear), these JAXB-annotated view models are in many regards the most powerful of all the alternative ways of writing view models.
-
-
-It's also worth noting that it is also possible to download the XML (or XSD) straight from the UI, useful during development.
-The view model simply needs to implement the xref:rgcms.adoc#_rgcms_classes_mixins_Dto[`Dto`] marker interface; the
-framework has xref:rgcms.adoc#_rgcms_classes_mixins_Dto[mixins] that contribute the download actions to the view model.
-
-
-[[__ugbtb_view-models_use-cases_dtos_consumers]]
-=== DTO Consumers
-
-The actual consumers of DTOs will generally obtain the XML of the view models either by requesting the XML directly,
-eg using the xref:ugvro.adoc#[RestfulObjects viewer], or may have the XML sent to them asynchronously using an ESB
-such as Apache Camel.
-
-In the former case, the consumer requests the DTO by calling the REST API with the appropriate HTTP `Accept` header.
-An appropriate implementation of xref:rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`] can then be
-used to return the appropriate DTO (as XML).
-
-For the latter case, one design is simply for the application to instantiate the view model, then call the
-xref:rgsvc.adoc#_rgsvc_api_JaxbService[`JaxbService`] to obtain its corresponding XML. This can then be published onto
-the ESB, for example using an http://activemq.apache.org[Apache ActiveMQ (TM)] queue.
-
-However, rather than try to push all the data that might be needed by any of these external systems in a single XML event
- (which would require anticipating all the requirements, likely a hopeless task), a better design is to publish only
- the fact that something of note has changed - ie, that an action on a domain object has been invoked - and then let the consumers call back to obtain other information if required. This can once again be done by calling the REST API with
- an appropriate HTTP `Accept` header.
-
-[TIP]
-====
-This is an example of the link:https://leanpub.com/camel-design-patterns[VETRO pattern] (validate, enrich, transform, route, operate). In our case we focus on the validation (to determine the nature of the inbound message, ie which action was
-invoked), and the enrich (callback to obtain a DTO with additional information required by the consumer).
-====
-
-The (non-ASF) http://github.com/isisaddons/isis-module-publishmq[Isis addons' publishmq] module provides an out-of-the-box solution of this design. It provides an implementation of the xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`],
-but which simply publishes instances of xref:rgcms.adoc#_rgcms_schema-aim[`ActionInvocationMemento`] to an ActiveMQ
-queue. Camel (or similar) can then be hooked up to consume these events from this queue, and use a processor to
-parse the action memento to determine what has changed on the source system. Thereafter, a subsequent Camel processor
-can then call back to the source - via the xref:ugvro.adoc[Restful Objects viewer] - to enrich the message with
-additional details using a DTO.
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugbtb_web-xml.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_web-xml.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_web-xml.adoc
deleted file mode 100644
index 05a698b..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_web-xml.adoc
+++ /dev/null
@@ -1,504 +0,0 @@
-[[_ugbtb_web-xml]]
-= `web.xml`
-: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/
-
-
-
-Apache Isis provides two different viewers, the xref:ugvw.adoc#[Wicket viewer] and the xref:ugvro.adoc#[RestfulObjects viewer]. You can deploy both of these concurrently, or deploy just the Wicket viewer, or deploy just the Restful Objects viewer. The configuration in `web.xml` varies accordingly, both in terms of the servlet context listeners, filters and servlets.
-
-If you are using Apache Isis' integration with Apache Shiro (for security) then this also needs configuring in `web.xml`. See the xref:ugsec.adoc#_ugsec_configuring-isis-to-use-shiro[security chapter] for full details on this topic.
-
-The servlets and filters are mapped to three main pipelines:
-
-* `/wicket` - the Wicket viewer UI
-* `/restful` - the Restful Objects resources (REST API)
-* other paths, also static resources (such as `.png`, `.css`)
-
-With the following key:
-
-image::{_imagesdir}runtime/web-xml/key.png[width="800px",link="{_imagesdir}runtime/web-xml/key.png"]
-
-the diagram below shows the components to be configured if deploying both the Wicket viewer and Restful Objects viewer:
-
-image::{_imagesdir}runtime/web-xml/wicket-and-ro.png[width="800px",link="{_imagesdir}runtime/web-xml/wicket-and-ro.png"]
-
-Here the Wicket viewer is responsible for the main bootstrapping of Apache Isis itself, in other words the shared (global) metadata; this is done by the `IsisWicketApplication` class (extending the `WicketApplication` Wicket API). This class is also responsible for Apache Isis' own session and transaction management.
-
-The Restful Objects viewer - being a JAX-RS application implemented using the RestEasy framework - requires the `RestEasyBootstrapper` servlet context listener. It is this context listener that also sets up the `RestfulObjectsApplication`, which is then delegated to by the RestEasy `HttpServletDispatcher`. This pipeline uses the `IsisSessionFilter` and `IsisTransactionFilterForRestfulObjects` to perform the session and transaction management before it hits the RestEasy servlet.
-
-If only the Wicket viewer is deployed, then the diagram is more or less the same: the RestEasy servlet, context listener and supporting filters are simply removed:
-
-image::{_imagesdir}runtime/web-xml/wicket-only.png[width="800px",link="{_imagesdir}runtime/web-xml/wicket-only.png"]
-
-Finally, if only the Restful Objects viewer is deployed, then things change a little more subtly. Here, the Wicket filter is no longer needed. In its place, though the `IsisWebAppBootstrapper` context listener is required: this is responsible for seting up the shared (global) metadata.
-
-image::{_imagesdir}runtime/web-xml/ro-only.png[width="800px",link="{_imagesdir}runtime/web-xml/ro-only.png"]
-
-The following sections detail these various listeners, filters and servlets in more detail.
-
-
-
-[[__ugbtb_web-xml_servlet-context-listeners]]
-== Servlet Context Listeners
-
-Servlet context listeners are used to perform initialization on application startup. Both Shiro (if configured as the security mechanism) and RestEasy (for the Restful Objects viewer) require their own context listener. In addition, if the Wicket viewer is _not_ being used, then additional Apache Isis-specific listener is required for bootstrapping of the Apache Isis framework itself.
-
-
-=== `EnvironmentLoaderListener` (Shiro)
-
-Bootstrap listener to startup and shutdown the web application's Shiro `WebEnvironment` at startup and shutdown respectively.
-
-Its definition is:
-
-[source,xml]
-----
-<listener>
- <listener-class>org.apache.shiro.web.env.EnvironmentLoaderListener</listener-class>
-</listener>
-----
-
-
-
-=== `IsisWebAppBootstrapper`
-
-The `IsisWebAppBootstrapper` servlet context listener bootstraps the shared (global) metadata for the Apache Isis framework. This listener is not required (indeed must not be configured) if the Wicket viewer is in use.
-
-Its definition is:
-
-[source,xml]
-----
-<listener>
- <listener-class>org.apache.isis.core.webapp.IsisWebAppBootstrapper</listener-class>
-</listener>
-----
-
-Its context parameters are:
-
-[source,xml]
-----
-<context-param>
- <param-name>deploymentType</param-name>
- <param-value>SERVER_PROTOTYPE</param-value>
-</context-param>
-<context-param>
- <param-name>isis.viewers</param-name>
- <param-value>restfulobjects</param-value>
-</context-param>
-----
-
-
-=== `ResteasyBootstrap` (RestEasy)
-
-The `ResteasyBootstrap` servlet context listener initializes the RestEasy runtime, specifying that classes (namely, those specified in Isis' `RestfulObjectsApplication`) to be exposed as REST resources. It is required if the Restful Objects viewer is to be deployed.
-
-Its definition is:
-
-[source,xml]
-----
-<listener>
- <listener-class>org.jboss.resteasy.plugins.server.servlet.ResteasyBootstrap</listener-class>
-</listener>
-----
-
-There are two relevant context parameters:
-
-[source,xml]
-----
-<context-param>
- <param-name>javax.ws.rs.Application</param-name> <!--1-->
- <param-value>org.apache.isis.viewer.restfulobjects.server.RestfulObjectsApplication</param-value>
-</context-param>
-<context-param>
- <param-name>resteasy.servlet.mapping.prefix</param-name>
- <param-value>/restful/</param-value> <!--2-->
-</context-param>
-----
-<1> used by RestEasy to determine the JAX-RS resources and other related configuration
-<2> should correspond to the filter mapping of the `HttpServletDispatcher` servlet
-
-
-
-[[__ugbtb_web-xml_servlets]]
-== Servlets
-
-Servlets process HTTP requests and return corresponding responses.
-
-
-=== `HttpServletDispatcher` (RestEasy)
-
-This servlet is provided by the RestEasy framework, and does the dispatching to the resources defined by Apache Isis' `RestfulObjectsApplication` (see above).
-
-Its definition is:
-
-[source,xml]
-----
-<servlet>
- <servlet-name>RestfulObjectsRestEasyDispatcher</servlet-name>
- <servlet-class>org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher</servlet-class>
-</servlet>
-----
-
-Its mapping is:
-
-[source,xml]
-----
-<servlet-mapping>
- <servlet-name>RestfulObjectsRestEasyDispatcher</servlet-name>
- <url-pattern>/restful/*</url-pattern>
-</servlet-mapping>
-----
-
-
-=== `ResourceServlet`
-
-The `ResourceServlet` loads and services static content either from the filesystem or from the classpath, each with an appropriate mime type.
-
-Static content here means request paths ending in `.js`, `.css`, `.html`, `.png`, `.jpg`, `.jpeg` and `gif`.
-
-
-Its definition is:
-
-[source,xml]
-----
-<servlet>
- <servlet-name>Resource</servlet-name>
- <servlet-class>org.apache.isis.core.webapp.content.ResourceServlet</servlet-class>
-</servlet>
-----
-
-Its mapping is:
-
-[source,xml]
-----
-<servlet-mapping>
- <servlet-name>Resource</servlet-name>
- <url-pattern>*.css</url-pattern>
-</servlet-mapping>
-<servlet-mapping>
- <servlet-name>Resource</servlet-name>
- <url-pattern>*.png</url-pattern>
-</servlet-mapping>
-<servlet-mapping>
- <servlet-name>Resource</servlet-name>
- <url-pattern>*.jpg</url-pattern>
-</servlet-mapping>
-<servlet-mapping>
- <servlet-name>Resource</servlet-name>
- <url-pattern>*.jpeg</url-pattern>
-</servlet-mapping>
-<servlet-mapping>
- <servlet-name>Resource</servlet-name>
- <url-pattern>*.gif</url-pattern>
-</servlet-mapping>
-<servlet-mapping>
- <servlet-name>Resource</servlet-name>
- <url-pattern>*.svg</url-pattern>
-</servlet-mapping>
-<servlet-mapping>
- <servlet-name>Resource</servlet-name>
- <url-pattern>*.js</url-pattern>
-</servlet-mapping>
-<servlet-mapping>
- <servlet-name>Resource</servlet-name>
- <url-pattern>*.html</url-pattern>
-</servlet-mapping>
-<servlet-mapping>
- <servlet-name>Resource</servlet-name>
- <url-pattern>*.swf</url-pattern>
-</servlet-mapping>
-----
-
-
-
-
-[[__ugbtb_web-xml_filters]]
-== Filters
-
-The order in which filters appear in `web.xml` matters: first to last they define a pipeline. This is shown in the
-above diagrams, and the subsections also list the in the same order that they should appear in your `web.xml`.
-
-
-=== `ShiroFilter` (Shiro)
-
-Shiro filter that sets up a Shiro security manager for the request, obtained from the Shiro `WebEnvironment` set up
-by the Shiro `EnvironmentLoaderListener` (discussed above).
-
-Its definition is:
-
-[source,xml]
-----
-<filter>
- <filter-name>ShiroFilter</filter-name>
- <filter-class>org.apache.shiro.web.servlet.ShiroFilter</filter-class>
-</filter>
-----
-
-Its mapping is:
-
-[source,xml]
-----
-<filter-mapping>
- <filter-name>ShiroFilter</filter-name>
- <url-pattern>/*</url-pattern>
-</filter-mapping>
-----
-
-
-=== `IsisLogOnExceptionFilter`
-
-The `IsisLogOnExceptionFilter` filter simply logs the URL of any request that causes an exception to be thrown, then
-re-propagates the exception. The use case is simply to ensure that all exceptions are logged (against the
-`IsisLogOnExceptionFilter` slf4j appender).
-
-Its definition is:
-
-[source,xml]
-----
-<filter>
- <filter-name>IsisLogOnExceptionFilter</filter-name>
- <filter-class>org.apache.isis.core.webapp.diagnostics.IsisLogOnExceptionFilter</filter-class>
-</filter>
-----
-
-
-Its mapping is:
-
-[source,xml]
-----
-<filter-mapping>
- <filter-name>IsisLogOnExceptionFilter</filter-name>
- <url-pattern>/wicket/*</url-pattern>
-</filter-mapping>
-<filter-mapping>
- <filter-name>IsisLogOnExceptionFilter</filter-name>
- <url-pattern>/restful/*</url-pattern>
-</filter-mapping>
-----
-
-
-
-=== `ResourceCachingFilter`
-
-The `ResourceCachingFilter` adds HTTP cache headers to specified resources, based on their pattern.
-
-Its definition is:
-
-[source,xml]
-----
-<filter>
- <filter-name>ResourceCachingFilter</filter-name>
- <filter-class>org.apache.isis.core.webapp.content.ResourceCachingFilter</filter-class>
- <init-param>
- <param-name>CacheTime</param-name> <!--1-->
- <param-value>86400</param-value>
- </init-param>
-</filter>
-----
-<1> cache time, in seconds
-
-Its mapping is:
-
-[source,xml]
-----
-<filter-mapping>
- <filter-name>ResourceCachingFilter</filter-name>
- <url-pattern>*.css</url-pattern>
-</filter-mapping>
-<filter-mapping>
- <filter-name>ResourceCachingFilter</filter-name>
- <url-pattern>*.png</url-pattern>
-</filter-mapping>
-<filter-mapping>
- <filter-name>ResourceCachingFilter</filter-name>
- <url-pattern>*.jpg</url-pattern>
-</filter-mapping>
-<filter-mapping>
- <filter-name>ResourceCachingFilter</filter-name>
- <url-pattern>*.jpeg</url-pattern>
-</filter-mapping>
-<filter-mapping>
- <filter-name>ResourceCachingFilter</filter-name>
- <url-pattern>*.gif</url-pattern>
-</filter-mapping>
-<filter-mapping>
- <filter-name>ResourceCachingFilter</filter-name>
- <url-pattern>*.svg</url-pattern>
-</filter-mapping>
-<filter-mapping>
- <filter-name>ResourceCachingFilter</filter-name>
- <url-pattern>*.html</url-pattern>
-</filter-mapping>
-<filter-mapping>
- <filter-name>ResourceCachingFilter</filter-name>
- <url-pattern>*.js</url-pattern>
-</filter-mapping>
-<filter-mapping>
- <filter-name>ResourceCachingFilter</filter-name>
- <url-pattern>*.swf</url-pattern>
-</filter-mapping>
-----
-
-
-=== `WicketFilter`
-
-The `WicketFilter` is responsible for initiating the handling of Wicket requests.
-
-Its definition is:
-
-[source,xml]
-----
-<filter>
- <filter-name>WicketFilter</filter-name>
- <filter-class>org.apache.wicket.protocol.http.WicketFilter</filter-class>
- <init-param>
- <param-name>applicationClassName</param-name> <!--1-->
- <param-value>domainapp.webapp.SimpleApplication</param-value>
- </init-param>
-</filter>
-----
-<1> specify the application (subclass of `IsisWicketApplication`) to use
-
-Its mapping is:
-
-[source,xml]
-----
-<filter-mapping>
- <filter-name>WicketFilter</filter-name>
- <url-pattern>/wicket/*</url-pattern>
-</filter-mapping>
-----
-
-This filter reads one context parameter:
-[source,xml]
-----
-<context-param>
- <param-name>configuration</param-name>
- <param-value>deployment</param-value> <!--1-->
-</context-param>
-----
-<1> alternatively set to "development"; see xref:rgcfg.adoc#_rgcfg_deployment-types[deployment types] for further discussion.
-
-
-=== `IsisSessionFilter`
-
-The `IsisSessionFilter` is responsible for the (persistence) session management; in effect a wrapper around DataNucleus' `PersistenceManager` object. It is only required for the Restful Objects viewer.
-
-[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> <!--1-->
- <param-value>
- org.apache.isis.viewer.restfulobjects.server.authentication.AuthenticationSessionStrategyBasicAuth
- </param-value>
- </init-param>
- <init-param>
- <param-name>whenNoSession</param-name> <!--2-->
- <param-value>basicAuthChallenge</param-value>
- </init-param>
- <init-param>
- <param-name>passThru</param-name> <!--3-->
- <param-value>/restful/swagger</param-value>
- </init-param>
- <!--
- <init-param>
- <param-name>restricted</param-name> <!--4-->
- <param-value>...</param-value>
- </init-param>
- <init-param>
- <param-name>redirectToOnException</param-name> <!--5-->
- <param-value>...</param-value>
- </init-param>
- -->
-</filter>
-----
-<1> pluggable strategy for determining what the authentication session (credentials) are of the request
-<2> what the servlet should do if no existing session was found. Usual values are either `unauthorized`, `basicAuthChallenge` or `auto`. Discussed in more detail below.
-<3> specify which URIs to ignore and simply passthru. Originally introduced to allow the `SwaggerSpec` resource (which does not require a session) to be invoked.
-<4> List of paths that are allowed through even if not authenticated. The servlets mapped to these paths are expected to be able to deal with there being no session. Typically they will be logon pages. See below for further details.
-<5> where to redirect to if an exception occurs.
-
-
-The `whenNoSession` parameter determines what the behaviour should be if no existing session can be found. There are a number of predetermined values available:
-
-* `unauthorized` will generates a 401 response
-* `basicAuthChallenge` will also generate a 401 response, and also issues a Basic Auth challenge using `WWW-Authenticate` response header
-* `auto` combines the `unauthorized` and `basicAuthChallenge` strategies: it will generate a 401 response, but only issues a Basic Auth challenge if it detects that the request originates from a web browser (ie that the HTTP `Accept` header is set to `text/html`). This means that custom Javascript apps can perform their authentication correctly, while the REST API can still be explored using the web browser (relying upon the web browser's in-built support for HTTP Basic Auth).
-* `continue`, in which case the request is allowed to continue but the destination expected to know that there will be no open session
-* `restricted`, which allows access to a restricted list of URLs, otherwise will redirect to the first of that list of URLs
-
-If accessing the REST API through a web browser, then normally `basicAuthChallenge` is appropriate; the browser will automatically display a simple prompt. If accessing the REST API through a custom Javascript app, then `unauthorized` is usually the one to use.
-
-This filter should be mapped to the `servlet-name` for the RestEasy `HttpServletDispatcher`; for example:
-
-[source,xml]
-----
-<filter-mapping>
- <filter-name>IsisSessionFilterForRestfulObjects</filter-name>
- <servlet-name>RestfulObjectsRestEasyDispatcher</servlet-name>
-</filter-mapping>
-----
-
-
-
-
-=== `IsisTransactionFilterForRestfulObjects`
-
-The `IsisTransactionFilterForRestfulObjects` filter simply ensures that a transaction is in progress for all
-calls routed to the xref:ugvro.adoc#[RestfulObjects viewer].
-
-Its definition is:
-
-[source,xml]
-----
-<filter>
- <filter-name>IsisTransactionFilterForRestfulObjects</filter-name>
- <filter-class>org.apache.isis.viewer.restfulobjects.server.webapp.IsisTransactionFilterForRestfulObjects</filter-class>
-</filter>
-----
-
-This filter should be mapped to the `servlet-name` for the RestEasy `HttpServletDispatcher`; for example:
-
-[source,xml]
-----
-<filter-mapping>
- <filter-name>IsisTransactionFilterForRestfulObjects</filter-name>
- <servlet-name>RestfulObjectsRestEasyDispatcher</servlet-name>
-</filter-mapping>
-----
-
-
-
-[[__ugbtb_web-xml_context-parameters]]
-== Configuration Files
-
-However Apache Isis is bootstrapped (using the `IsisWicketApplication` or using `IsisWebAppBootstrapper`), it will
-read a number of configuration files, such as `isis.properties`.
-
-By default these are read from `WEB-INF` directory. This can be overriden using the `isis.config.dir` context parameter:
-
-[source,xml]
-----
-<context-param>
- <param-name>isis.config.dir</param-name>
- <param-value>location of your config directory if fixed</param-value>
-</context-param>
-----
-
-Another context parameter, `isis.viewres` specifies which additional configuration files to search for (over and above
-the default ones of `isis.properties` et al):
-
-[source,xml]
-----
-<context-param>
- <param-name>isis.viewers</param-name>
- <param-value>wicket,restfulobjects</param-value>
-</context-param>
-----
-
-For example, this will cause `viewer_wicket.properties` and `viewer_restfulobjects.properties` to also be loaded.
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts.adoc
deleted file mode 100644
index 9c825e7..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts.adoc
+++ /dev/null
@@ -1,22 +0,0 @@
-[[_ugfun_core-concepts]]
-= Core Concepts
-: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/
-
-This introductory chapter should give you a good about what Apache Isis actually *is*: the fundamental ideas and principles that it builds upon, how it compares with other frameworks, what the fundamental building blocks are for actually writing an Isis application, and what services and features the framework provides for you to leverage in your own apps.
-
-[TIP]
-====
-Parts of this chapter have been adapted from Dan Haywood's 2009 book, 'Domain Driven Design using Naked Objects'. We've also added some new insights and made sure the material we've used is relevant to Apache Isis.
-====
-
-
-include::_ugfun_core-concepts_philosophy.adoc[leveloffset=+1]
-include::_ugfun_core-concepts_principles.adoc[leveloffset=+1]
-include::_ugfun_core-concepts_building-blocks.adoc[leveloffset=+1]
-include::_ugfun_core-concepts_framework-provided-services.adoc[leveloffset=+1]
-include::_ugfun_core-concepts_add-ons.adoc[leveloffset=+1]
-include::_ugfun_core-concepts_other-deployment-options.adoc[leveloffset=+1]
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_add-ons.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_add-ons.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_add-ons.adoc
deleted file mode 100644
index 8c031b5..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_add-ons.adoc
+++ /dev/null
@@ -1,35 +0,0 @@
-[[_ugfun_core-concepts_add-ons]]
-= Isis Add-ons
-: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 link:http://www.isisaddons.org[Isis Addons] website provides a number of reusable modules and other extensions for Apache Isis. This chapter focuses just on the modules, all of which have a name of the form `isis-module-xxx`.
-
-[WARNING]
-====
-Note that Isis addons, while maintained by Apache Isis committers, are not part of the ASF.
-====
-
-
-
-The modules themselves fall into four broad groups:
-
-* modules that provide an implementations of API defined by Apache Isis +
-+
-where Apache Isis has hooks to use the service if defined by provides no implementations of its own. The http://github.com/isisaddons/isis-module-command[command], http://github.com/isisaddons/isis-module-audit[auditing], http://github.com/isisaddons/isis-module-publishing[publishing], http://github.com/isisaddons/isis-module-security[security] and http://github.com/isisaddons/isis-module-sessionlogger[sessionlogger] modules fall into this category. Typically the domain objects themselves wouldn't interact with these services
-
-* modules that provide standalone domain services with their own API and implementation +
-+
-These are simply intended to be used by domain objects. The http://github.com/isisaddons/isis-module-docx[docx], http://github.com/isisaddons/isis-module-excel[excel], http://github.com/isisaddons/isis-module-settings[settings] and http://github.com/isisaddons/isis-module-stringinterpolator[stringinterpolator] fall into this category.
-
-* modules that provide standalone domain entities (and supporting services) for a particular subdomain +
-+
-The http://github.com/isisaddons/isis-module-tags[tags] module falls into this category
-
-* modules that provide developer utilities +
-+
-Not intended for use by either the framework or domain objects, but provide utilities that the developer themselves might use. The http://github.com/isisaddons/isis-module-devutils[devutils] module (not suprisingly) falls into this category
-
-Each of the modules has a full README and example application demonstrating their usage. The sections below briefly outline the capabilities of these modules.
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_building-blocks.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_building-blocks.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_building-blocks.adoc
deleted file mode 100644
index caa445c..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_building-blocks.adoc
+++ /dev/null
@@ -1,340 +0,0 @@
-[[_ugfun_core-concepts_building-blocks]]
-= Building Blocks
-: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/
-
-In this section we run through the main building blocks that make up an Apache Isis application.
-
-[[__ugfun_core-concepts_building-blocks_metamodel]]
-== A MetaModel
-
-At its core, Apache Isis is a metamodel that is built at runtime from the domain classes (eg `Customer.java`), along
-with optional supporting metadata (eg `Customer.layout.json`).
-
-The contents of this metamodel is inferred from the Java classes discovered on the classpath: the entities and
-supporting services, as well the members of those classes. The detail of the metamodel is generally explicit, usually
-represented by Java annotations such as `@Title` or `@Action`. Notably the metamodel is
-xref:ugbtb.adoc#_ugbtb_programming-model[extensible]; it is possible to teach Apache Isis new programming
-conventions/rules (and conversely to remove those that are built in).
-
-Most of the annotations recognized by the framework are defined by the Apache Isis framework itself. For example the
-`@Title` annotation - which identifies how the framework should derive a human-readable label for each rendered
-domain object - is part of the `org.apache.isis.applib.annotations` package. However the framework also recognizes
-certain other JEE annotations such as `@javax.inject.Inject` (used for dependency injection).
-
-The framework uses DataNucleus for its persistence mechanism. This is an ORM that implements the JDO and JPA APIs, and
-which can map domain objects either to an RDBMS or to various NoSQL objectstores such as MongoDB or Neo4J. Apache Isis
-recognizes a number of the JDO annotations such as `@javax.jdo.annotations.Column(allowsNull=...)`.
-
-In addition, the framework builds up the metamodel for each domain object using
-xref:ugfun.adoc#_ugfun_object-layout[layout hints], such as `Customer.layout.json`. These provide metadata such as
-grouping elements of the UI together, using multi-column layouts, and so on. The layout file can be modified while the
-application is still running, and are picked up automatically; a useful way to speed up feedback.
-
-[TIP]
-====
-At the time of writing Apache Isis only recognizes and supports the JDO API, though we expect JPA to be supported
-in the future. We also expect to generalize support for `.layout.json` to be able to read such metadata from other
-sources.
-====
-
-
-[[__ugfun_core-concepts_building-blocks_types-of-domain-objects]]
-== Type of Domain Objects
-
-Most domain objects that the end-user interacts with are *domain entities*, such as `Customer`, `Order`, `Product` and
-so on. These are persistent objects and which are mapped to a database (usually relational), using JDO/DataNucleus
-annotations. From the end-user's perspective the UI displays a single domain object per page; they can then inspect
-and modify its state, and navigate to related objects.
-
-The next type of domain object to discuss is *domain services*. These are (usually) singleton stateless services
-that provide additional functionality. The behaviour of these services is rendered in various ways, though the most
-obvious is as the menu actions on the top-level menu bars in the xref:ugvw.adoc#[Wicket viewer]'s UI.
-
-Domain objects can also delegate to domain services; domain services are automatically injected into every other domain
-object; this includes domain entities as well as other services. This injection of domain services into entities is
-significant: it allows business logic to be implemented in the domain entities, rather than have it "leach away" into
-supporting service layers. Said another way: it is the means by which Apache Isis helps you avoid the anaemic
-domain model anti-pattern.
-
-As well as domain entities - mapped to a datastore - Apache Isis also supports *view models*. End users interact with
-view models in the same way as a domain entity, indeed they are unlikely to distinguish one from the other. However
-view models are _not_ mapped to the underlying database, rather they represent some aggregation of state from one or
-more underlying entities. Their state is serialized and recreated from their internal identifier; this identifier is
-visible as the object's URL in the xref:ugvw.adoc#[Wicket viewer] or
-xref:ugvro.adoc#[RestfulObjects viewer].
-
-There's no need though for the view model to aggregate the state of regular domain entities. A view model could also
-be used as a proxy for some externally managed entity, accessed over a web service or REST API; it could even be a
-representation of state held in-memory (such as user preferences, for example).
-
-There are also several types of domain services. Most easily described are those domain services (discussed above)
-that are represented as the menu actions on top-level menu bars. Another variation are *contributed services* - domain
-services that contribute behaviour or (derived) state to entities/view models. Finally domain services may also
-simply provide additional non-UI functionality; an example being to perform an address geocoding lookup against the
-google-maps API.
-
-Also worth mentioning: domain services can also be either singletons (discussed above) or request-scoped; the latter
-being annotated with `@javax.enterprise.context.RequestScoped`. An example of the request-scoped service is the
-xref:rgsvc.adoc#_rgsvc_api_Scratchpad[`Scratchpad`] service, for sharing arbitrary data between multiple objects.
-
-The final type of domain object is the *mixin*. These are similar to contributed services in that they also contribute (or rather,
-mixin) both behaviour or (derived) state to entities/view models. However, they provide a more control over contributed services,
-with a cleaner programming model similar to traits found in other languages.
-
-The diagram below summarizes the various types of domain object:
-
-image::{_imagesdir}core-concepts/building-blocks/types-of-domain-object.png[width="860px",link="{_imagesdir}core-concepts/building-blocks/types-of-domain-object.png"]
-
-
-The Apache Isis programming model uses annotations to distinguish these object types:
-
-* *view models* are annotated either with `@DomainObject(nature=VIEW_MODEL)` or using `@ViewModel`. Which is used is
-a matter of personal preference. +
-+
-It is also possible to implement the `ViewModel` interface, for finer-grained control.
-
-* *domain entities* that are persisted to the database (as the vast majority will) are annotated with
-`@DomainObject(nature=ENTITY)`. In addition such domain entities are annotated with the JDO/DataNucleus annotation of
-`@javax.jdo.annotations.PersistenceCapable`. +
-+
-In addition, if a domain entity is a proxy for state managed in an external system, or merely for some state held
-in-memory, then `@DomainObject(nature=EXTERNAL_ENTITY)` or `@DomainObject(nature=INMEMORY_ENTITY)` can be used.
-
-* *mixins* are annotated either with `@DomainObject(nature=MIXIN)` or using `@Mixin`. As for view models, which is
-used is a matter of personal preference.
-
-* finally, *domain services*` are annotated with `@DomainService(nature=...)` where the nature is either
-`VIEW_MENU_ONLY` (for domain services whose actions appear on the top-level menu bars), or `VIEW_CONTRIBUTIONS_ONLY`
-(for domain services whose actions are contributed to entities or view models), or `DOMAIN` (for domain services whose
-functionality is simply for other domain objects to invoke programmatically).
-+
-It is also possible to specify a nature of simply `VIEW`, this combining `VIEW_MENU_ONLY` and `VIEW_CONTRIBUTIONS_ONLY`.
-This is in fact the default, useful for initial prototyping. A final nature is `VIEW_REST_ONLY` which is for domain
-services whose functionality is surfaced only by the xref:ugvro.adoc#[RestfulObjects viewer].
-
-Worth emphasising is that domain entities and view models hold state, whereas domain services are generally
-stateless. If a domain service does hold state (eg the `Scratchpad` service noted above) then it should be
-`@RequestScoped` so that this state is short-lived and usable only within a single request.
-
-
-
-[[__ugfun_core-concepts_building-blocks_objects-members]]
-== Object Members
-
-Every domain object in Apache Isis consists of (at most) three types of members:
-
-* properties, such as a `Customer`'s `firstName
-
-* collections, such as a `Customer`'s `orders` collection of ``Order``s
-
-* actions, such as a `Customer'`s `placeOrder(...)` method.
-
-Some domain objects - specifically domain services and mixins - only have actions. In the case of contributing services
-and mixins these actions can (depending upon their semantics and signatures) be represented as derived properties or
-collections on the entity/view model to which they contribute/mix-in.
-
-
-=== Properties
-
-Properties follow the standard getter/setter pattern, with the return type being a scalar (a value object or another
-entity or view model).
-
-For example, with:
-
-[source,java]
-----
-public class Customer
- private String firstName;
- public String getFirstName() { return firstName; }
- public void setFirstName(String firstName) { this.firstName = firstName; }
- ...
-}
-----
-
-the framework infers the `Customer` domain entity, which in turn has a `firstName` string _property_.
-
-
-=== Collections
-
-Collections are also represented by a getter and setter, however the return type is a `Collection` or subtype.
-
-For example, with:
-
-[source,java]
-----
-public class Customer
- private SortedSet<Order> orders = new TreeSet<Order>();
- public SortedSet<Order> getOrders() { return orders; }
- public void setOrders(SortedSet<Order> orders) { this.orders = orders; }
- ...
-}
-----
-
-the framework infers the `orders` _collection_.
-
-[TIP]
-====
-The most commonly used collection type is `java.util.SortedSet`; entities are most commonly mapped to a relational
-database (ie a datastore with set semantics) and we recommend that all entities define a natural ordering so that when
-rendered in the UI they will be ordered "meaningfully" to the end-user.
-====
-
-
-=== Actions
-
-The third type of object member is actions. (To a first approximation), actions are all public methods that do not
-represent properties or collections.
-
-For example:
-
-[source,java]
-----
-public class Customer
- public Customer placeOrder(Product p, int quantity) { ... }
- ...
-}
-----
-
-corresponds to the `placeOrder` _action_.
-
-[NOTE]
-====
-The above _is_ a simplification; the Apache Isis programming model also recognizes a number of other supporting methods
-each of which has its own prefix such as `hide`, `disable` or `validate`. These can be considered as "reserved words"
-in Apache Isis, and do _not_ correspond to actions even though they have public visibility.
-====
-
-
-
-== Entities vs View Models
-
-When developing an Apache Isis application you will most likely start off with the persistent domain entities:
-`Customer`, `Order`, `Product`, and so on. For some applications this may well suffice. However, if the application
-needs to integrate with other systems, or if the application needs to support reasonably complex business processes,
-then you may need to look beyond just domain entities.
-
-To support these use cases we support view models. In the same way that an (RDBMS) database view can aggregate and
-abstract from multiple underlying database tables, so a view model sits on top of one or many underlying entities.
-
-View models are not persisted, but nevertheless they can have behaviour (and titles, and icons) just like domain
-entities. Indeed, to a user of the system there is no particular distinction (again, in the same way that when using
-an RDBMS one can use database views and database tables pretty much interchangeably).
-
-View models generally tend to be associated with supporting a particular use case; logically they are part of the
-application layer, not part of the domain layer (where entities live).
-
-We introduce view models here because they do get mentioned quite often within the users and reference guide. However,
-we do consider them a more advanced topic; we generally recommend that you build your applications from the domain
-layer up, rather than from the view model down.
-
-For further discussion on view models, see xref:ugbtb.adoc#_ugbtb_view-models[this topic].
-
-
-
-
-[[__ugfun_core-concepts_building-blocks_domain-services]]
-== Domain Services
-
-Domain services consist of a set of logically grouped actions, and as such follow the same conventions as for entities. However, a service cannot have (persisted) properties, nor can it have (persisted) collections.
-
-Domain services are instantiated once and once only by the framework, and are used to centralize any domain logic that does not logically belong in a domain entity or value. Apache Isis will automatically inject services into every domain entity that requests them, and into each other.
-
-For convenience you can inherit from AbstractService or one of its subclasses, but this is not mandatory.
-
-
-=== Domain Services vs View Services
-
-NOTE: TODO
-
-`@DomainService(nature=...)`
-
-.Factories, Repositories and Services
-****
-A distinction is sometimes made between a factory (that creates object) and a repository (that is used to find existing objects). You will find them discussed separately in Evans' link:http://books.google.com/books/about/Domain_Driven_Design.html?id=hHBf4YxMnWMC[Domain Driven Design], for example.
-
-In Apache Isis these are all implemented as domain services. Indeed, it is quite common to have a domain service that acts as both a factory and a repository.
-****
-
-
-
-[[__ugfun_core-concepts_building-blocks_mixins-and-contributions]]
-== Mixins & Contributions
-
-NOTE: TODO
-
-
-For more information, see xref:ugbtb.adoc#_ugbtb_decoupling_contributions[this topic on contribution]s, and
-xref:ugbtb.adoc#_ugbtb_decoupling_mixins[this topic on mixin]s.
-
-
-
-[[__ugfun_core-concepts_building-blocks_domain-events]]
-== Domain Events
-
-NOTE: TODO; see xref:rgcms.adoc#_rgcms_classes_domainevent[domain event] classes.
-
-
-
-=== UI Events
-
-NOTE: TODO; see xref:rgcms.adoc#_rgcms_classes_uievent[UI event] classes.
-
-
-
-
-[[__ugfun_core-concepts_building-blocks_oid]]
-== OIDs
-
-As well as defining a xref:ugfun.adoc#__ugfun_core-concepts_building-blocks_metamodel[metamodel] of the structure (domain
-classes) of its domain objects, Apache Isis also manages the runtime instances of said domain objects.
-
-When a domain entity is recreated from the database, the framework keeps track of its identity through an "OID": an
-object identifier. Fundamentally this is a combination of its type (domain class), along with an identifier. You can think
-of it as its "primary key", except across all domain entity types.
-
-For portability and resilience, though, the object type is generally an alias for the actual domain class: thus
-"customers.CUS", say, rather than "com.mycompany.myapp.customers.Customer". This is derived from an annotation. The
-identifier meanwhile is always converted to a string.
-
-Although simple, the OID is an enormously powerful concept: it represents a URI to any domain object managed by
-a given Apache Isis application. With it, we have the ability to lookup any arbitrary domain objects.
-
-Some examples:
-
-* an OID allows sharing of information between users, eg as a deep link to be pasted into an email.
-
-* the information within an OID could be converted into a barcode, and stamped onto a PDF form. When the PDF is
-scanned by the mail room, the barcode could be read to attach the correspondence to the relevant domain object.
-
-* as a handle to any object in an audit record, as used by xref:rgsvc.adoc#_rgsvc_spi_AuditerService[`AuditerService`] or xref:rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`] (the latter deprecated);
-
-* similarly within implementations of xref:rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] to persist `Command`
-objects
-
-* similarly within implementations of xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`]
-to persist published action invocations
-
-* and of course both the xref:ugvro.adoc#[RestfulObjects viewer] and
-xref:ugvw.adoc#[Wicket viewer]
-use the oid tuple to look up, render and allow the user to interact with domain objects.
-
-Although the exact content of an OID should be considered opaque by domain objects, it is possible for domain objects
-to obtain OIDs. These are represented as `Bookmark`s, obtained from the
-xref:rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`]. Deep links meanwhile can be obtained from
-the xref:rgant.adoc#_rgant-DeepLinkService[`@DeepLinkService`].
-
-OIDs can also be converted into XML format, useful for integration scenarios. The
-xref:rgcms.adoc#_rgcms_schema-common[common schema] XSD defines the `oidDto` complex type for precisely this purpose.
-
-
-
-[[__ugfun_core-concepts_building-blocks_value-objects]]
-== Value Objects (Primitives)
-
-NOTE: TODO
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/2669a971/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_framework-provided-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_framework-provided-services.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_framework-provided-services.adoc
deleted file mode 100644
index df8aa73..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/_ugfun_core-concepts_framework-provided-services.adoc
+++ /dev/null
@@ -1,107 +0,0 @@
-[[_ugfun_core-concepts_framework-provided-services]]
-= Framework-provided Services
-:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-:_basedir: ../
-:_imagesdir: images/
-
-
-Most framework domain services are API: they exist to provide support functionality to the application's domain objects and services. In this case an implementation of the service will be available, either by Apache Isis itself or by Isis Addons (non ASF).
-
-Some framework domain services are SPI: they exist primarily so that the application can influence the framework's
-ehaviour. In these cases there is (usually) no default implementation; it is up to the application to provide an
-implementation.
-
-
-General purpose:
-
-* xref:rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`]; mostly deprecated, replaced by:
-** xref:rgsvc.adoc#_rgsvc_api_ClockService[`ClockService`]
-** xref:rgsvc.adoc#_rgsvc_api_ConfigurationService[`ConfigurationService`]
-** xref:rgsvc.adoc#_rgsvc_api_MessageService[`MessageService`]
-** xref:rgsvc.adoc#_rgsvc_api_RepositoryService[`RepositoryService`]
-** xref:rgsvc.adoc#_rgsvc_api_ServiceRegistry[`ServiceRegistry`]
-** xref:rgsvc.adoc#_rgsvc_api_TitleService[`TitleService`]
-** xref:rgsvc.adoc#_rgsvc_api_UserService[`UserService`]
-* xref:rgsvc.adoc#_rgsvc_api_IsisJdoSupport[`IsisJdoSupport`]
-* xref:rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`]
-* xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`]
-* xref:rgsvc.adoc#_rgsvc_api_EmailService[`EmailService`]
-
-Commands/Interactions/Background/Auditing/Publishing/Profiling:
-
-* xref:rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`] (SPI)
-* xref:rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] (SPI)
-* xref:rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`] (SPI)
-* xref:rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`] (SPI) (deprecated)
-* xref:rgsvc.adoc#_rgsvc_spi_AuditerService[`AuditerService`] (SPI)
-* xref:rgsvc.adoc#_rgsvc_api_BackgroundService[`BackgroundService`]
-* xref:rgsvc.adoc#_rgsvc_spi_BackgroundCommandService[`BackgroundCommandService`] (SPI)
-* xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`] (SPI) (deprecated)
-* xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublishererService`] (SPI)
-* xref:rgsvc.adoc#_rgsvc_api_MetricsService[`MetricsService`]
-
-
-Information Sharing:
-
-* xref:rgsvc.adoc#_rgsvc_api_Scratchpad[`Scratchpad`]
-* xref:rgsvc.adoc#_rgsvc_api_ActionInvocationContext[`ActionInvocationContext`]
-* xref:rgsvc.adoc#_rgsvc_api_QueryResultsCache[`QueryResultsCache`]
-
-UserManagement:
-
-* xref:rgsvc.adoc#_rgsvc_spi_UserProfileService[`UserProfileService`] (SPI)
-* xref:rgsvc.adoc#_rgsvc_spi_UserRegistrationService[`UserRegistrationService`] (SPI)
-* xref:rgsvc.adoc#_rgsvc_spi_EmailNotificationService[`EmailNotificationService`] (SPI)
-
-Bookmarks and Mementos:
-
-* xref:rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`]
-* xref:rgsvc.adoc#_rgsvc_api_MementoService[`MementoService`]
-* xref:rgsvc.adoc#_rgsvc_api_DeepLinkService[`DeepLinkService`]
-* xref:rgsvc.adoc#_rgsvc_api_JaxbService[`JaxbService`]
-* xref:rgsvc.adoc#_rgsvc_api_XmlSnapshotService[`XmlSnapshotService`]
-
-Layout and UI Management:
-
-* xref:rgsvc.adoc#_rgsvc_api_HomePageProviderService[`HomePageProviderService`]
-* xref:rgsvc.adoc#_rgsvc_api_LayoutService[`LayoutService`]
-* xref:rgsvc.adoc#_rgsvc_spi_GridLoaderService[`GridLoaderService`] (SPI)
-* xref:rgsvc.adoc#_rgsvc_spi_GridService[`GridService`] (SPI)
-* xref:rgsvc.adoc#_rgsvc_spi_GridSystemService[`GridSystemService`] (SPI)
-* xref:rgsvc.adoc#_rgsvc_spi_HintStore[`HintStore`] (SPI)
-* xref:rgsvc.adoc#_rgsvc_spi_RoutingService[`RoutingService`] (SPI)
-* xref:rgsvc.adoc#_rgsvc_spi_UrlEncodingService[`UrlEncodingService`] (SPI)
-
-REST Support:
-
-* xref:rgsvc.adoc#_rgsvc_api_AcceptHeaderService[`AcceptHeaderService`]
-* xref:rgsvc.adoc#_rgsvc_api_SwaggerService[`SwaggerService`]
-* xref:rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`] (SPI)
-
-Metamodel:
-
-* xref:rgsvc.adoc#_rgsvc_api_ApplicationFeatureRepository[`ApplicationFeatureRepository`]
-* xref:rgsvc.adoc#_rgsvc_api_MetamodelService[`MetamodelService`]
-
-Other API:
-
-* xref:rgsvc.adoc#_rgsvc_api_FixtureScriptsDefault[`FixtureScriptsDefault`]
-* xref:rgsvc.adoc#_rgsvc_api_GuiceBeanProvider[`GuiceBeanProvider`]
-* xref:rgsvc.adoc#_rgsvc_api_SudoService[`SudoService`]
-* xref:rgsvc.adoc#_rgsvc_api_TransactionService[`TransactionService`]
-
-Other SPI:
-
-* xref:rgsvc.adoc#_rgsvc_spi_ClassDiscoveryService[`ClassDiscoveryService`] (SPI)
-* xref:rgsvc.adoc#_rgsvc_spi_ErrorReportingService[`ErrorReportingService`] (SPI)
-* xref:rgsvc.adoc#_rgsvc_spi_EventSerializer[`EventSerializer`] (SPI)
-* xref:rgsvc.adoc#_rgsvc_spi_ExceptionRecognizer[`ExceptionRecognizer`] (SPI)
-* xref:rgsvc.adoc#_rgsvc_spi_FixtureScriptsSpecificationProvider[`FixtureScriptsSpecificationProvider`] (SPI)
-* xref:rgsvc.adoc#_rgsvc_spi_LocaleProvider[`LocaleProvider`] (SPI)
-* xref:rgsvc.adoc#_rgsvc_spi_TranslationService[`TranslationService`] (SPI)
-* xref:rgsvc.adoc#_rgsvc_spi_TranslationsResolver[`TranslationsResolver`] (SPI)
-* xref:rgsvc.adoc#_rgsvc_spi_TranslationsResolver[`TranslationsResolver`] (SPI)
-
-
-A full list of services can be found in the xref:rgsvc.adoc#_rgsvc[Domain Services] reference guide.
-