http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_properties.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_properties.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_properties.adoc
deleted file mode 100644
index ecff327..0000000
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_class-structure_properties.adoc
+++ /dev/null
@@ -1,369 +0,0 @@
-[[_ugfun_class-structure_properties]]
-= Property
-: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/
-
-
-A property is an instance variable of a domain object, of a scalar type, that 
holds some state about either a 
xref:../ugfun/ugfun.adoc#__ugfun_class-structure_class-definition_entities[domain
 entity] or a 
xref:../ugfun/ugfun.adoc#__ugfun_class-structure_class-definition_view-models[view
 model].
-
-For example, a ``Customer``'s `firstName` would be a property, as would their 
`accountCreationDate` that they created their account.
-All properties have at least a "getter" method, and most properties have also 
a "setter" method (meaning that they are mutable).
-Properties that do _not_ have a setter method are derived properties, and so 
are not persisted.
-
-Formally speaking, a property is simply a regular JavaBean getter, returning a 
scalar value recognized by the framework.
-Most properties (those that are editable/modifiable) will also have a setter 
and (if persisted) a backing instance field.
-And most properties will also have a number of annotations:
-
-* Apache Isis defines its own set own `@Property` annotation for capturing 
domain semantics.
-It also provides a `@PropertyLayout` for UI hints (though the information in 
this annotation may instead be provided by a supplementary 
xref:../ugvw/ugvw.adoc#_ugvw_layout[`.layout.xml`] file
-
-* the properties of domain entities are often annotated with the 
JDO/DataNucleus `@javax.jdo.annotations.Column` annotation.
-For property references, there may be other annotations to indicate whether 
the reference is bidirectional.
-It's also possible (using annotations) to define a link table to hold foreign 
key columns.
-
-* for the properties of view models, then JAXB annotations such as 
`@javax.xml.bind.annotation.XmlElement` will be present
-
-Apache Isis recognises some of these annotations for JDO/DataNucleus and JAXB 
and infers some domain semantics from them (for example, the maximum allowable 
length of a string property).
-
-Since writing getter and setter methods adds quite a bit of boilerplate, it's 
common to use link:https://projectlombok.org/[Project Lombok] to code generate 
these methods at compile time (using Java's annotation processor) simply by 
adding the `@lombok.Getter` and `@lombok.Setter` annotations to the field.
-The 
xref:guides/ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp 
archetype] uses this approach.
-
-
-[[__ugfun_class-structure_properties_value-vs-reference-types]]
-== Value vs Reference Types
-
-Properties can be either a value type (strings, int, date and so on) or be a 
reference to another object (for example, an `Order` referencing the `Customer` 
that placed it).
-
-For example, to map a string value type:
-
-[source,java]
-----
-@lombok.Getter @lombok.Setter       // <1>
-private String notes;
-----
-<1> using link:https://projectlombok.org/[Project Lombok] annotations to 
reduce boilerplate
-
-You could also add the `@Property` annotation if you wished:
-
-[source,java]
-----
-@Property
-@lombok.Getter @lombok.Setter
-private String notes;
-----
-
-Although in this case it is not required (none of its attributes have been 
set).
-
-Or to map a reference type:
-
-[source,java]
-----
-@lombok.Getter @lombok.Setter
-private Customer customer;
-----
-
-It's ok for a 
xref:../ugfun/ugfun.adoc#__ugfun_class-structure_class-definition_entities[domain
 entity] to reference another domain entity, and for a 
xref:../ugfun/ugfun.adoc#__ugfun_class-structure_class-definition_view-models[view
 model] to reference both view model and domain entities.
-However, it isn't valid for a domain entity to hold a persisted reference to 
view model (DataNucleus will not know how to persist that view model).
-
-[NOTE]
-====
-For further details on mapping associations, see the JDO/DataNucleus 
documentation for 
link:http://www.datanucleus.org/products/accessplatform_4_1/jdo/orm/one_to_many.html[one-to-many]
 associations, 
link:http://www.datanucleus.org/products/accessplatform_4_1/jdo/orm/many_to_one.html[many-to-one]
 associations, 
link:http://www.datanucleus.org/products/accessplatform_4_1/jdo/orm/many_to_many.html[many-to-many]
 associations, and so on.
-====
-
-For domain entities, the annotations for mapping value types tend to be 
different for properties vs action parameters, because JDO annotations are only 
valid on properties.
-The table in the 
xref:../ugfun/ugfun.adoc#_ugfun_class-structure_properties-vs-parameters[Properties
 vs Parameters] section provides a handy reference of each.
-
-
-[[__ugfun_class-structure_properties_optional-properties]]
-== Optional Properties
-
-(For domain entities) JDO/DataNucleus' default is that a property is assumed 
to be mandatory if it is a primitive type (eg `int`, `boolean`), but optional 
if a reference type (eg `String`, `BigDecimal` etc).
-To override optionality in JDO/DataNucleus the `@Column(allowsNull="...")` 
annotations is used.
-
-Apache Isis on the other hand assumes that all properties (and action 
parameters, for that matter) are mandatory, not optional.
-These defaults can also be overridden using Apache Isis' own annotations, 
specifically `@Property(optionality=...)`, or (because it's much less verbose) 
using `@javax.annotation.Nullable`.
-
-These different defaults can lead to incompatibilities between the two 
frameworks.
-To counteract that, Apache Isis also recognizes and honours JDO's 
`@Column(allowsNull=...)`.
-
-For example, you can write:
-
-[source,java]
-----
-@javax.jdo.annotations.Column(allowsNull="true")
-@lombok.Getter @lombok.Setter
-private LocalDate date;
-----
-
-rather than the more verbose:
-
-[source,java]
-----
-@javax.jdo.annotations.Column(allowsNull="true")
-@Property(optionality=Optionality.OPTIONAL)
-@lombok.Getter @lombok.Setter
-private LocalDate date;
-----
-
-The framework will search for any incompatibilities in optionality (whether 
specified explicitly or defaulted implicitly) between Isis' defaults and 
DataNucleus, and refuse to boot if any are found (fail fast).
-
-[[__ugfun_class-structure_properties_editable-properties]]
-== Editable Properties
-
-Apache Isis provides the capability to allow individual properties to be 
modified.
-This is specified using the `@Property(editing=...)` attribute.
-
-For example:
-
-[source,java]
-----
-@Property(editing = Editing.ENABLED)
-@lombok.Getter @lombok.Setter
-private String notes;
-----
-
-If this is omitted then whether editing is enabled or disabled is defined 
globally, in the `isis.properties` configuration file; see 
xref:../rgcfg/rgcfg.adoc#__rgcfg_configuring-core_isis-objects-editing[reference
 configuration guide] for further details.
-
-
-[[__ugfun_class-structure_properties_ignoring-properties]]
-== Ignoring Properties
-
-By default Apache Isis will automatically render all properties in the 
xref:../ugvw/ugvw.adoc[UI] or in the xref:../ugvro/ugvro.adoc[REST API].
-To get Apache Isis to ignore a property (exclude it from its metamodel), 
annotate the getter using `@Programmatic`.
-
-Similarly, you can tell JDO/DataNucleus to ignore a property using the 
`@javax.jdo.annotations.NotPersistent` annotation.
-This is independent of Apache Isis; in other words that property will still be 
rendered in the UI (unless also annotated with `@Programmatic`).
-
-For view models, you can tell JAXB to ignore a property using the 
`@javax.xml.bind.annotation.XmlTransient` annotation.
-Again, this is independent of Apache Isis.
-
-
-[[__ugfun_class-structure_properties_derived-properties]]
-== Derived Properties
-
-Derived properties are those with a getter but no setter.
-Provided that the property has not been annotated with `@Programmatic`, these 
will still be rendered in the UI, but they will be read-only (not editable) and 
their state will not be persisted.
-
-Subtly different, it is also possible to have non-persisted but still editable 
properties.
-In this case you will need a getter and a setter, but with the getter 
annotated using `@NotPersistent`.
-The implementation of these getters and setters will most likely persist state 
using other properties (which might be hidden from view using `@Programmatic`).
-
-For example:
-
-[source,java]
-----
-@javax.jdo.annotations.NotPersistent
-@Property(editing=Editing.ENABLED)
-public String getAddress() { return addressService.toAddress( getLatLong() ); 
}             // <1>
-public void setAddress(String address) { 
setLatLong(addressService.toLatLong(address)); }
-
-@javax.jdo.annotations.Column
-private String latLong;
-@Programmatic
-public String getLatLong() { return latLong; }                                 
             // <2>
-public void setLatLong(String latLong) { this.latLong = latLong; }
-
-@javax.inject.Inject
-AddressService addressService;                                                 
             // <3>
-----
-<1> the representation of the address, in human readable form, eg "10 Downing 
Street, London, UK"
-<2> the lat/long representation of the address, eg "51.503363;-0.127625"
-<3> an injected service that can convert to/from address and latLong.
-
-
-
-[[__ugfun_class-structure_properties_datatypes]]
-== Data types
-
-This section shows specific considerations for various datatypes, in 
particular how to annotate them for DataNucleus mapping to the persistence 
object store.
-
-
-
-[[__ugfun_class-structure_properties_datatypes_strings]]
-=== ``String``s (Length)
-
-By default JDO/DataNucleus will map string properties to a `VARCHAR(255)`.
-To limit the length, use the `@Column(length=...)` annotation.
-
-For example:
-
-[source,java]
-----
-@javax.jdo.annotations.Column(length=50)
-@lombok.Getter @lombok.Setter
-private String firstName
-----
-
-This is a good example of a case where Apache Isis infers domain semantics 
from the JDO annotation.
-
-
-
-[[__ugfun_class-structure_properties_datatypes-joda-dates]]
-=== JODA Dates
-
-Isis' JDO objectstore bundles DataNucleus' 
http://www.datanucleus.org/documentation/products/plugins.html[built-in 
support] for Joda `LocalDate` and `LocalDateTime` datatypes, meaning that 
entity properties of these types will be persisted as appropriate data types in 
the database tables.
-
-It is, however, necessary to annotate your properties with 
`@javax.jdo.annotations.Persistent`, otherwise the data won't actually be 
persisted.
-See the link:http://db.apache.org/jdo/field_types.html[JDO docs] for more 
details on this.
-
-Moreover, these datatypes are _not_ in the default fetch group, meaning that 
JDO/DataNucleus will perform an additional `SELECT` query for each attribute.
-To avoid this extra query, the annotation should indicate that the property is 
in the default fetch group.
-
-For example, the `ToDoItem` (in the 
https://github.com/isisaddons/isis-app-todoapp[todoapp example app] (not ASF)) 
defines the `dueBy` property as follows:
-
-[source,java]
-----
-@javax.jdo.annotations.Persistent(defaultFetchGroup="true")
-@javax.jdo.annotations.Column(allowsNull="true")
-@Getter @Setter
-private LocalDate dueBy;
-----
-
-
-[[__ugfun_class-structure_properties_datatypes_bigdecimals]]
-=== ``BigDecimal``s (Precision)
-
-Working with `java.math.BigDecimal` properties takes a little care due to 
scale/precision issues.
-
-For example, suppose we have:
-
-[source,java]
-----
-@lombok.Getter @lombok.Setter
-private BigDecimal impact;
-----
-
-JDO/DataNucleus creates, at least with HSQL, the table with the field type as 
NUMERIC(19). No decimal digits are admitted. (Further details 
http://hsqldb.org/doc/2.0/guide/sqlgeneral-chapt.html#sgc_numeric_types[here]).
-
-What this implies is that, when a record is inserted, a log entry similar to 
this one appears:
-
-[source,java]
-----
-INSERT INTO ENTITY(..., IMPACT, ....) VALUES (...., 0.5, ....)
-----
-
-But when that same record is retrieved, the log will show that a value of "0" 
is returned, instead of 0.5.
-
-The solution is to explicitly add the scale to the field like this:
-
-[source,java]
-----
-@javax.jdo.annotations.Column(scale=2)
-@lombok.Getter @lombok.Setter
-private BigDecimal impact;
-----
-
-In addition, you should also set the scale of the `BigDecimal`, using 
`setScale(scale, roundingMode)`.
-
-More information can be found 
http://www.opentaps.org/docs/index.php/How_to_Use_Java_BigDecimal:_A_Tutorial[here]
 and 
http://www.tutorialspoint.com/java/math/bigdecimal_setscale_rm_roundingmode.htm[here].
-
-
-
-[[__ugfun_class-structure_properties_datatypes_blobs]]
-=== ``Blob``s
-
-Apache Isis configures JDO/DataNucleus so that the properties of type 
`org.apache.isis.applib.value.Blob` and `org.apache.isis.applib.value.Clob` can 
also be persisted.
-
-As for 
xref:../ugfun/ugfun.adoc#__ugfun_class-structure_properties_datatypes_joda-dates[Joda
 dates], this requires the `@javax.jdo.annotations.Persistent` annotation.
-However, whereas for dates one would always expect this value to be retrieved 
eagerly, for blobs and clobs it is not so clear cut.
-
-For example, in the `ToDoItem` class (of the 
https://github.com/isisaddons/isis-app-todoapp/blob/0333852ddd18ad67e3356fccf805aa442246790d/dom/src/main/java/todoapp/dom/todoitem/ToDoItem.java#L442[todoapp
 example app] (non-ASF) the `attachment` property is as follows:
-
-[source,java]
-----
-@javax.jdo.annotations.Persistent(defaultFetchGroup="false", columns = {
-    @javax.jdo.annotations.Column(name = "attachment_name"),
-    @javax.jdo.annotations.Column(name = "attachment_mimetype"),
-    @javax.jdo.annotations.Column(name = "attachment_bytes", jdbcType="BLOB", 
sqlType = "LONGVARBINARY")
-})
-@Property(
-        optionality = Optionality.OPTIONAL
-)
-@lombok.Getter @lombok.Setter
-private Blob attachment;
-----
-
-The three `@javax.jdo.annotations.Column` annotations are required because the 
mapping classes that Apache Isis provides 
(https://github.com/apache/isis/blob/isis-1.4.0/component/objectstore/jdo/jdo-datanucleus/src/main/java/org/apache/isis/objectstore/jdo/datanucleus/valuetypes/IsisBlobMapping.java#L59[IsisBlobMapping]
 and 
https://github.com/apache/isis/blob/isis-1.4.0/component/objectstore/jdo/jdo-datanucleus/src/main/java/org/apache/isis/objectstore/jdo/datanucleus/valuetypes/IsisClobMapping.java#L59[IsisClobMapping])
 map to 3 columns.
-(It is not an error to omit these `@Column` annotations, but without them the 
names of the table columns are simply suffixed `_0`, `_1`, `_2` etc.
-
-If the `Blob` is mandatory, then use:
-
-[source,java]
-----
-@javax.jdo.annotations.Persistent(defaultFetchGroup="false", columns = {
-    @javax.jdo.annotations.Column(name = "attachment_name", 
allowsNull="false"),
-    @javax.jdo.annotations.Column(name = "attachment_mimetype", 
allowsNull="false"),
-    @javax.jdo.annotations.Column(name = "attachment_bytes",
-                                  jdbcType="BLOB", sqlType = "LONGVARBINARY",
-                                  allowsNull="false")
-})
-@Property(
-    optionality = Optionality.MANDATORY
-)
-@lombok.Getter @lombok.Setter
-private Blob attachment;
-----
-
-[NOTE]
-====
-If specifying a `sqlType` of "LONGVARBINARY" does not work, try instead "BLOB".
-There can be differences in behaviour between JDBC drivers.
-====
-
-[[__ugfun_class-structure_properties_datatypes_clobs]]
-=== ``Clob``s
-
-
-Mapping `Clob`s works in a very similar way to 
xref:../ugfun/ugfun.adoc#__ugfun_class-structure_properties_datatypes_blobs[``Blob``]s,
 but the `jdbcType` and `sqlType` attributes will, respectively, be `CLOB` and 
`LONGVARCHAR`:
-
-[source,java]
-----
-@javax.jdo.annotations.Persistent(defaultFetchGroup="false", columns = {
-    @javax.jdo.annotations.Column(name = "attachment_name"),
-    @javax.jdo.annotations.Column(name = "attachment_mimetype"),
-    @javax.jdo.annotations.Column(name = "attachment_chars",
-                                  jdbcType="CLOB", sqlType = "LONGVARCHAR")
-})
-private Clob doc;
-@Property(
-    optionality = Optionality.OPTIONAL
-)
-public Clob getDoc() {
-    return doc;
-}
-public void setDoc(final Clob doc) {
-    this.doc = doc;
-}
-----
-
-[NOTE]
-====
-If specifying a `sqlType` of "LONGVARCHAR" does not work, try instead "CLOB".  
There can be differences in behaviour between JDBC drivers.
-====
-
-
-[[__ugfun_class-structure_properties_datatypes_mapping-to-varbinary-or-varchar]]
-=== Mapping to VARBINARY or VARCHAR
-
-Instead of mapping to a sqlType of `LONGVARBINARY` (or perhaps `BLOB`), you 
might instead decide to map to a `VARBINARY`.
-The difference is whether the binary data is held "on-row" or as a pointer 
"off-row"; with a `VARBINARY` the data is held on-row and so you will need to 
specify a length.
-
-For example:
-
-[source,java]
-----
-@javax.jdo.annotations.Column(name = "attachment_bytes", jdbcTypr="BLOB", 
sqlType = "VARBINARY", length=2048)
-----
-
-The same argument applies to `LONGVARCHAR` (or `CLOB`); you could instead map 
to a regular `VARCHAR`:
-
-[source,java]
-----
-@javax.jdo.annotations.Column(name = "attachment_chars", sqlType = "VARCHAR", 
length=2048)
-----
-Support and maximum allowed length will vary by database vendor.
-
-
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts.adoc 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts.adoc
index e9819a0..f7bc062 100644
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts.adoc
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts.adoc
@@ -12,12 +12,8 @@ We've also added some new insights and made sure the 
material we've used is rele
 
 include::_ugfun_core-concepts_philosophy.adoc[leveloffset=+1]
 include::_ugfun_core-concepts_principles.adoc[leveloffset=+1]
-
 include::_ugfun_core-concepts_apache-isis-vs.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]
+include::_ugfun_core-concepts_deployment-options.adoc[leveloffset=+1]
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_add-ons.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_add-ons.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_add-ons.adoc
deleted file mode 100644
index c13a4b2..0000000
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_add-ons.adoc
+++ /dev/null
@@ -1,54 +0,0 @@
-[[_ugfun_core-concepts_add-ons]]
-= Isis Add-ons & Incode Catalog
-: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 for Apache Isis, focusing either on specific technologies or 
in technical cross-cutting concerns.
-Some of these modules implement SPIs defined by the framework.
-
-The link:http://catalog.incode.org[Incode Catalog] website also provides a 
number of reusable modules, focusing on business logic for generic subdomains.
-
-This section surveys the functionality available.
-
-
-[WARNING]
-====
-Note that Isis Addons and Incode Catalog, although maintained by Apache Isis 
committers, are not part of the ASF.
-====
-
-
-
-The modules themselves fall into a number of broader groups:
-
-* modules that provide an implementations of SPI defined by Apache Isis +
-+
-where Apache Isis has hooks to use the service if defined by provides no 
implementations of its own. +
-+
-From the link:http://www.isisaddons.org[Isis Addons] website, the 
http://github.com/isisaddons/isis-module-command[command], 
http://github.com/isisaddons/isis-module-audit[auditer], 
http://github.com/isisaddons/isis-module-publishmq[publisher], 
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. +
-+
-From the link:http://www.isisaddons.org[Isis Addons] website, the 
http://github.com/isisaddons/isis-module-docx[docx], 
http://github.com/isisaddons/isis-module-excel[excel], 
http://github.com/isisaddons/isis-module-freemarker[freemarker], 
http://github.com/isisaddons/isis-module-pdfbox[pdfbox], 
http://github.com/isisaddons/isis-module-settings[settings], 
http://github.com/isisaddons/isis-module-servletapi[servletapi], 
http://github.com/isisaddons/isis-module-stringinterpolator[stringinterpolator] 
and http://github.com/isisaddons/isis-module-xdocreport[xdocreport] fall into 
this category. +
-+
-From the link:http://catalog.incode.org[Incode Catalog] website, the 
http://github.com/incodehq/incode-module-alias[alias], 
http://github.com/incodehq/incode-module-classification[classification], 
http://github.com/incodehq/incode-module-commchannel[commchannel], 
http://github.com/incodehq/incode-module-communications[communications], 
http://github.com/incodehq/incode-module-country[country], 
http://github.com/incodehq/incode-module-docfragment[docfragment],
-http://github.com/incodehq/incode-module-document[document] and 
http://github.com/incodehq/incode-module-document[note] modules fall into this 
category.
-
-* modules that provide standalone domain entities (and supporting services) 
for a particular subdomain +
-+
-From the link:http://www.isisaddons.org[Isis Addons] website, the 
http://github.com/isisaddons/isis-module-tags[tags] module falls into this 
category
-
-* modules that provide developer/testing utilities +
-+
-From the link:http://www.isisaddons.org[Isis Addons] website, the 
http://github.com/isisaddons/isis-module-fakedata[fakedata] module provides 
fakedata for unit- and integration testing +
-+
-From the link:http://catalog.incode.org[Incode Catalog] website, the 
http://github.com/incodehq/incode-module-fixturesupport[fixturesupport], 
http://github.com/incodehq/incode-module-integtestsupport[integtestsupport] and 
http://github.com/incodehq/incode-module-unittestsupport[unittestsupport] 
modules fall into this category.
-
-* modules that support runtime/integration support +
-+
-From the link:http://www.isisaddons.org[Isis Addons] website, 
link:http://github.com/isisaddons/isis-module-flywaydb[flywaydb] handle RDBMS 
schema migration, http://github.com/isisaddons/isis-module-quartz[quartz] 
provides scheduling of background jobs; and the 
http://github.com/isisaddons/isis-module-togglz[togglz] provides feature 
toggles.
-
-Each of the modules has a full README and demo application demonstrating their 
usage.  The sections below briefly outline the capabilities of these modules.

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs.adoc
index 8dea746..9bc1a6e 100644
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs.adoc
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs.adoc
@@ -7,7 +7,7 @@
 Many other frameworks promise rapid application development and provide 
automatically generated user interfaces, so how do they compare to Apache Isis?
 
 
-include::_ugfun_core-concepts_apache-isis-vs_mvc-server-side-frameworks.adoc[leveloffset=+1]
+include::_ugfun_core-concepts_apache-isis-vs_mvc-server-side.adoc[leveloffset=+1]
 include::_ugfun_core-concepts_apache-isis-vs_cqrs.adoc[leveloffset=+1]
 
include::_ugfun_core-concepts_apache-isis-vs_event-sourcing.adoc[leveloffset=+1]
 include::_ugfun_core-concepts_apache-isis-vs_metawidget.adoc[leveloffset=+1]

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_mvc-server-side-frameworks.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_mvc-server-side-frameworks.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_mvc-server-side-frameworks.adoc
deleted file mode 100644
index b806289..0000000
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_mvc-server-side-frameworks.adoc
+++ /dev/null
@@ -1,29 +0,0 @@
-[[_ugfun_core-concepts_apache-isis-vs_mvc-server-side-frameworks]]
-= vs MVC server-side frameworks
-: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/
-
-
-
-Some of most commonly used frameworks today are 
link:http://www.spring.io/[Spring MVC], link:http://rubyonrails.org/[Ruby on 
Rails] and link:http://www.grails.org[Grails], all of which implement one 
flavour or another of the server-side MVC pattern.
-The MVC 1.0 specification (originally scheduled for JavaEE 8 though since 
removed) is also similar.
-
-These frameworks all use the classic  *model-view-controller* ( _MVC_) pattern 
for web applications, with scaffolding, code-generation, and/or metaprogramming 
tools for the controllers and views, as well as convention over configuration 
to define how these components interact.
-The views provided out of the box by these frameworks tend to be simple  
_CRUD_-style interfaces.
-More sophisticated behavior is accomplished by customizing the generated 
controllers.
-
-The most obvious difference when developing an Apache Isis application is its 
deliberate lack of an explicit controller layer; non- _CRUD_ behavior is 
automatically made available in its generic object-oriented  _UI_s.
-More sophisticated UIs can be built either by 
xref:../ugvw/ugvw.adoc#_ugvw_extending[extending Apache Isis' Wicket viewer] or 
by writing a bespoke UI leveraging the REST (hypermedia) API automatically 
exposed by xref:../ugvro/ugvro.adoc#[Isis' Restful Objects viewer].
-Other frameworks can also be used to implement REST APIs, of course, but 
generally they require a significant amount of development to get anywhere near 
the level of sophistication provided automatically by Apache Isis' REST API.
-
-Although these frameworks all provide their own ecosystems of extensions, 
Apache Isis' equivalent link:http://www.isisaddons.org[Isis Addons] (non-ASF) 
tend to work at a higher-level of abstraction.
-For example, each of these frameworks will integrate with various security 
mechanism, but the http://github.com/isisaddons/isis-module-security[Isis 
addons' security module] provides a full subdomain of users, roles, features 
and permissions that can be plugged into any Isis application.
-Similarly, the http://github.com/isisaddons/isis-module-command[Isis addons' 
command] and http://github.com/isisaddons/isis-module-audit[Isis addons' audit] 
modules in combination provide a support for auditing and traceability that can 
also be used for out of the box profiling.
-Again, these addons can be plugged into any Isis app.
-
-In terms of testing support, each of these other frameworks provide mechanisms 
to allow the webapp to be tested from within a JUnit test harness.
-Apache Isis' support is similar.
-Where Apache Isis differs though is that it enables end-to-end testing without 
the need for slow and fragile Selenium tests.
-Instead, Apache Isis provides a 
"xref:../ugtst/ugtst.adoc#_ugtst_integ-test-support_wrapper-factory[WrapperFactory]"
 domain service that allows the generic UI provided to in essence be simulated.
-On a more pragmatic level, the 
http://github.com/isisaddons/isis-module-fakedata[Isis addons' fakedata] module 
does "what it says on the tin", allowing both unit- and integration-tests to 
focus on the salient data and fake out the rest.

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_mvc-server-side.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_mvc-server-side.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_mvc-server-side.adoc
new file mode 100644
index 0000000..ae4f1b6
--- /dev/null
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_mvc-server-side.adoc
@@ -0,0 +1,29 @@
+[[_ugfun_core-concepts_apache-isis-vs_mvc-server-side]]
+= vs MVC server-side
+: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/
+
+
+
+Some of most commonly used frameworks today are 
link:http://www.spring.io/[Spring MVC], link:http://rubyonrails.org/[Ruby on 
Rails] and link:http://www.grails.org[Grails], all of which implement one 
flavour or another of the server-side MVC pattern.
+The MVC 1.0 specification (originally scheduled for JavaEE 8 though since 
removed) is also similar.
+
+These frameworks all use the classic  *model-view-controller* ( _MVC_) pattern 
for web applications, with scaffolding, code-generation, and/or metaprogramming 
tools for the controllers and views, as well as convention over configuration 
to define how these components interact.
+The views provided out of the box by these frameworks tend to be simple  
_CRUD_-style interfaces.
+More sophisticated behavior is accomplished by customizing the generated 
controllers.
+
+The most obvious difference when developing an Apache Isis application is its 
deliberate lack of an explicit controller layer; non- _CRUD_ behavior is 
automatically made available in its generic object-oriented  _UI_s.
+More sophisticated UIs can be built either by 
xref:../ugvw/ugvw.adoc#_ugvw_extending[extending Apache Isis' Wicket viewer] or 
by writing a bespoke UI leveraging the REST (hypermedia) API automatically 
exposed by xref:../ugvro/ugvro.adoc#[Isis' Restful Objects viewer].
+Other frameworks can also be used to implement REST APIs, of course, but 
generally they require a significant amount of development to get anywhere near 
the level of sophistication provided automatically by Apache Isis' REST API.
+
+Although these frameworks all provide their own ecosystems of extensions, 
Apache Isis' equivalent link:http://www.isisaddons.org[Isis Addons] (non-ASF) 
tend to work at a higher-level of abstraction.
+For example, each of these frameworks will integrate with various security 
mechanism, but the http://github.com/isisaddons/isis-module-security[Isis 
addons' security module] provides a full subdomain of users, roles, features 
and permissions that can be plugged into any Isis application.
+Similarly, the http://github.com/isisaddons/isis-module-command[Isis addons' 
command] and http://github.com/isisaddons/isis-module-audit[Isis addons' audit] 
modules in combination provide a support for auditing and traceability that can 
also be used for out of the box profiling.
+Again, these addons can be plugged into any Isis app.
+
+In terms of testing support, each of these other frameworks provide mechanisms 
to allow the webapp to be tested from within a JUnit test harness.
+Apache Isis' support is similar.
+Where Apache Isis differs though is that it enables end-to-end testing without 
the need for slow and fragile Selenium tests.
+Instead, Apache Isis provides a 
"xref:../ugtst/ugtst.adoc#_ugtst_integ-test-support_wrapper-factory[WrapperFactory]"
 domain service that allows the generic UI provided to in essence be simulated.
+On a more pragmatic level, the 
http://github.com/isisaddons/isis-module-fakedata[Isis addons' fakedata] module 
does "what it says on the tin", allowing both unit- and integration-tests to 
focus on the salient data and fake out the rest.

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_building-blocks.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_building-blocks.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_building-blocks.adoc
deleted file mode 100644
index fb106f2..0000000
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_building-blocks.adoc
+++ /dev/null
@@ -1,314 +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.xml`).
-
-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/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:../ugvw/ugvw.adoc#_ugvw_layout[layout hints], such as 
`Customer.layout.xml`.
-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.
-====
-
-
-
-[[__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/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/ugvw.adoc#[Wicket 
viewer] or xref:../ugvro/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/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/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/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: FIXME
-
-`@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: FIXME
-
-
-For more information, see 
xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_contributions[this topic on 
contribution]s, and xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_mixins[this 
topic on mixin]s.
-
-
-
-[[__ugfun_core-concepts_building-blocks_domain-events]]
-== Domain Events
-
-NOTE: FIXME; see xref:../rgcms/rgcms.adoc#_rgcms_classes_domainevent[domain 
event] classes.
-
-
-
-=== UI Events
-
-NOTE: FIXME; see xref:../rgcms/rgcms.adoc#_rgcms_classes_uievent[UI event] 
classes.
-
-
-
-
-[[__ugfun_core-concepts_building-blocks_oid]]
-== OIDs
-
-As well as defining a 
xref:../ugfun/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/rgsvc.adoc#_rgsvc_spi_AuditerService[`AuditerService`] or 
xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`] (the 
latter deprecated);
-
-* similarly within implementations of 
xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] to persist 
`Command`
-objects
-
-* similarly within implementations of 
xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`]
-to persist published action invocations
-
-* and of course both the xref:../ugvro/ugvro.adoc#[RestfulObjects viewer] and
-xref:../ugvw/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/rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`].
-Deep links meanwhile can be obtained from the 
xref:../rgant/rgant.adoc#_rgant-DeepLinkService[`@DeepLinkService`].
-
-OIDs can also be converted into XML format, useful for integration scenarios.
-The xref:../rgcms/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: FIXME
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_deployment-options.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_deployment-options.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_deployment-options.adoc
new file mode 100644
index 0000000..82ea368
--- /dev/null
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_deployment-options.adoc
@@ -0,0 +1,93 @@
+[[_ugfun_core-concepts_deployment-options]]
+= Deployment Options
+: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 is a mature platform suitable for production deployment, with its 
"sweet spot" being line-of-business enterprise applications.
+So if you're looking to develop that sort of application, we certainly hope 
you'll seriously evaluate it.
+
+But there are other ways that you can make Apache Isis work for you; in this 
section we explore a few of them.
+
+
+
+== Deploy to production
+
+Let's start though with the default use case for Apache Isis: building 
line-of-business enterprise applications, on top of its Wicket viewer.
+
+Apache Wicket, and therefore Apache Isis in this configuration, is a stateful 
architecture.
+As a platform it is certainly capable of supporting user bases of several 
thousand (with perhaps one or two hundred concurrent); however it isn't an 
architecture that you should try to scale up to tens of thousands of concurrent 
users.
+
+The UI generated by the Wicket viewer is well suited to many line-of-business 
apps, but it's also worth knowing that (with a little knowledge of the Wicket 
APIs) it relatively straightforward to extend.
+As described in 
xref:../ugfun/ugfun.adoc#_ugfun_available-domain-services_isis-addons[Isis 
addons] chapter, the viewer already has integrations with 
https://github.com/isisaddons/isis-wicket-gmap3[google maps], 
https://github.com/isisaddons/isis-wicket-fullcalendar2[a full calendar] and an 
https://github.com/isisaddons/isis-wicket-excel[export to Excel] component.
+We are also aware of integrations with SVG images (for floor maps of shopping 
center) and of custom widgets displaying a catalogue (text and images) of 
medical diseases.
+
+Deploying on Apache Isis means that the framework also manages object 
persistence.
+For many line-of-business applications this will mean using a relational 
database.
+It is also possible (courtesy of its integratinon with 
link:http://www.datanucleus.org[DataNucleus]) to deploy an Isis app to a NoSQL 
store such as Neo4J or MongoDB; and it is also possible to deploy to cloud 
platforms such as link:https://cloud.google.com/appengine/docs[Google App 
Engine (GAE)].
+
+
+
+== Prototyping
+
+Even if you don't intend to deploy your application on top of Apache Isis, 
there can be a lot of value in using Apache Isis for prototyping.
+Because all you need do to get an app running is write domain objects, you can 
very quickly explore a domain object model and validate ideas with a domain 
expert.
+
+By focusing just on the domain, you'll also find that you start to develop a 
ubiquitous language - a set of terms and concepts that the entire team 
(business and technologists alike) have a shared understanding.
+
+Once you've sketched out your domain model, you can then "start-over" using 
your preferred platform.
+
+
+
+
+
+== Deploy on your own platform
+
+The programming model defined by Apache Isis deliberately minimizes the 
dependencies on the rest of the framework.
+In fact, the only hard dependency that the domain model classes have on Apache 
Isis is through the `org.apache.isis.applib` classes, mostly to pick up 
annotations such as `@Disabled`.
+So, if you have used Apache Isis for prototyping (discussed above), then note 
that it's quite feasible to take your domain model a the basis of your actual 
development effort; Apache Isis' annotations and programming conventions will 
help ensure that any subtle semantics you might have captured in your 
prototyping are not lost.
+
+If you go this route, your deployment platform will of course need to provide 
similar capabilities to Apache Isis.
+In particular, you'll need to figure out a way to inject domain services into 
domain entities (eg using a JPA listener), and you'll also need to reimplement 
any domain services you have used that Apache Isis provides "out-of-the-box" 
(eg xref:../rgsvc/rgsvc.adoc#_rgsvc_api_QueryResultsCache[`QueryResultsCache`] 
domain service).
+
+
+
+
+
+== Deploy the REST API
+
+REST (Representation State Transfer) is an architectural style for building 
highly scalable distributed systems, using the same principles as the World 
Wide Web.
+Many commercial web APIs (twitter, facebook, Amazon) are implemented as either 
pure REST APIs or some approximation therein.
+
+The http://restfulobjects.org[Restful Objects specification] defines a means 
by a domain object model can be exposed as RESTful resources using JSON 
representations over HTTP.
+Apache Isis' xref:../ugvro/ugvro.adoc#[RestfulObjects viewer] is an 
implementation of that spec, making any Apache Isis domain object automatically 
available via REST.
+
+There are a number of use cases for deploying Isis as a REST API, including:
+
+* to allow a custom UI to be built against the RESTful API +
++
+For example, using Angular or some other RIA technology such as Flex, JavaFX, 
Silverlight
+
+* to enable integration between systems +
++
+REST is designed to be machine-readable, and so is an excellent choice for 
synchronous data interchange scenarios.
+
+* as a ready-made API for migrating data from one legacy system to its 
replacement.
+
+As for the auto-generated webapps, the framework manages object persistence.
+It is perfectly possible to deploy the REST API alongside an auto-generated 
webapp; both work from the same domain object model.
+
+
+
+
+
+== Implement your own viewer
+
+Isis' architecture was always designed to support multiple viewers; and indeed 
Apache Isis out-of-the-box supports two: the Wicket viewer, and the Restful 
Objects viewer (or three, if one includes the Wrapper Factory).
+
+While we mustn't understate the effort involved here, it is feasible to 
implement your own viewers too.
+Indeed, one of Apache Isis' committers does indeed have a (closed source) 
viewer, based on http://www.wavemaker.com/[Wavemaker].
+
+

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_framework-provided-services.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_framework-provided-services.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_framework-provided-services.adoc
deleted file mode 100644
index 3eeaac0..0000000
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_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 behaviour.
-In these cases there is (usually) no default implementation; it is up to the 
application to provide an implementation.
-
-
-General purpose:
-
-* 
xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DomainObjectContainer[`DomainObjectContainer`];
 mostly deprecated, replaced by:
-** xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ClockService[`ClockService`]
-** 
xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ConfigurationService[`ConfigurationService`]
-** xref:../rgsvc/rgsvc.adoc#_rgsvc_api_MessageService[`MessageService`]
-** xref:../rgsvc/rgsvc.adoc#_rgsvc_api_RepositoryService[`RepositoryService`]
-** xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ServiceRegistry[`ServiceRegistry`]
-** xref:../rgsvc/rgsvc.adoc#_rgsvc_api_TitleService[`TitleService`]
-** xref:../rgsvc/rgsvc.adoc#_rgsvc_api_UserService[`UserService`]
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_IsisJdoSupport[`IsisJdoSupport`]
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_WrapperFactory[`WrapperFactory`]
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`]
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EmailService[`EmailService`]
-
-Commands/Interactions/Background/Auditing/Publishing/Profiling:
-
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_CommandContext[`CommandContext`] (SPI)
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] (SPI)
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_InteractionContext[`InteractionContext`] 
(SPI)
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`] (SPI) 
(deprecated)
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_AuditerService[`AuditerService`] (SPI)
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BackgroundService[`BackgroundService`]
-* 
xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_BackgroundCommandService[`BackgroundCommandService`]
 (SPI)
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`] 
(SPI) (deprecated)
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublisherService[`PublishererService`] 
(SPI)
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_MetricsService[`MetricsService`]
-
-
-Information Sharing:
-
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_Scratchpad[`Scratchpad`]
-* 
xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ActionInvocationContext[`ActionInvocationContext`]
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_QueryResultsCache[`QueryResultsCache`]
-
-UserManagement:
-
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_UserProfileService[`UserProfileService`] 
(SPI)
-* 
xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_UserRegistrationService[`UserRegistrationService`]
 (SPI)
-* 
xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_EmailNotificationService[`EmailNotificationService`]
 (SPI)
-
-Bookmarks and Mementos:
-
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`]
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_MementoService[`MementoService`]
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_DeepLinkService[`DeepLinkService`]
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_JaxbService[`JaxbService`]
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_XmlSnapshotService[`XmlSnapshotService`]
-
-Layout and UI Management:
-
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_GridLoaderService[`GridLoaderService`] 
(SPI)
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_GridService[`GridService`] (SPI)
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_GridSystemService[`GridSystemService`] 
(SPI)
-* 
xref:../rgsvc/rgsvc.adoc#_rgsvc_api_HomePageProviderService[`HomePageProviderService`]
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_HintStore[`HintStore`] (SPI)
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_LayoutService[`LayoutService`]
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_RoutingService[`RoutingService`] (SPI)
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_UrlEncodingService[`UrlEncodingService`] 
(SPI)
-
-REST Support:
-
-* 
xref:../rgsvc/rgsvc.adoc#_rgsvc_api_AcceptHeaderService[`AcceptHeaderService`]
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_SwaggerService[`SwaggerService`]
-* 
xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`]
 (SPI)
-
-Metamodel:
-
-* 
xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ApplicationFeatureRepository[`ApplicationFeatureRepository`]
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_MetamodelService[`MetamodelService`]
-
-Other API:
-
-* 
xref:../rgsvc/rgsvc.adoc#_rgsvc_api_FixtureScriptsDefault[`FixtureScriptsDefault`]
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_GuiceBeanProvider[`GuiceBeanProvider`]
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_SudoService[`SudoService`]
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_api_TransactionService[`TransactionService`]
-
-Other SPI:
-
-* 
xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ClassDiscoveryService[`ClassDiscoveryService`]
 (SPI)
-* 
xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ErrorReportingService[`ErrorReportingService`]
 (SPI)
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_EventSerializer[`EventSerializer`] (SPI)
-* 
xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ExceptionRecognizer[`ExceptionRecognizer`] 
(SPI)
-* 
xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_FixtureScriptsSpecificationProvider[`FixtureScriptsSpecificationProvider`]
 (SPI)
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_LocaleProvider[`LocaleProvider`] (SPI)
-* xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_TranslationService[`TranslationService`] 
(SPI)
-* 
xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_TranslationsResolver[`TranslationsResolver`]
 (SPI)
-* 
xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_TranslationsResolver[`TranslationsResolver`]
 (SPI)
-
-
-A full list of services can be found in the 
xref:../rgsvc/rgsvc.adoc#_rgsvc[Domain Services] reference guide.
-

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_other-deployment-options.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_other-deployment-options.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_other-deployment-options.adoc
deleted file mode 100644
index 049b883..0000000
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_other-deployment-options.adoc
+++ /dev/null
@@ -1,81 +0,0 @@
-[[_ugfun_core-concepts_other-deployment-options]]
-= Other Deployment Options
-: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 is a mature platform suitable for production deployment, with its 
"sweet spot" being line-of-business enterprise applications.  So if you're 
looking to develop that sort of application, we certainly hope you'll seriously 
evaluate it.
-
-But there are other ways that you can make Apache Isis work for you; in this 
chapter we explore a few of them.
-
-
-
-== Deploy to production
-
-Let's start though with the default use case for Apache Isis: building 
line-of-business enterprise applications, on top of its Wicket viewer.
-
-Apache Wicket, and therefore Apache Isis in this configuration, is a stateful 
architecture.  As a platform it is certainly capable of supporting user bases 
of several thousand (with perhaps one or two hundred concurrent); however it 
isn't an architecture that you should try to scale up to tens of thousands of 
concurrent users.
-
-The UI UI generated by the Wicket viewer is well suited to many 
line-of-business apps, but it's also worth knowing that (with a little 
knowledge of the Wicket APIs) it relatively straightforward to extend.  As 
described in xref:../ugfun/ugfun.adoc#_ugfun_core-concepts_add-ons[Isis addons] 
chapter, the viewer already has integrations with 
https://github.com/isisaddons/isis-wicket-gmap3[google maps], 
https://github.com/isisaddons/isis-wicket-fullcalendar2[a full calendar] and an 
https://github.com/isisaddons/isis-wicket-excel[export to Excel] component.  We 
are also aware of integrations with SVG images (for floor maps of shopping 
center) and of custom widgets displaying a catalogue (text and images) of 
medical diseases.
-
-Deploying on Apache Isis means that the framework also manages object 
persistence.  For many line-of-business applications this will mean using a 
relational database.  It is also possible (courtesy of its integratinon with 
link:http://www.datanucleus.org[DataNucleus]) to deploy an Isis app to a NoSQL 
store such as Neo4J or MongoDB; and it is also possible to deploy to cloud 
platforms such as link:https://cloud.google.com/appengine/docs[Google App 
Engine (GAE)].
-
-
-
-== Use for prototyping
-
-Even if you don't intend to deploy your application on top of Apache Isis, 
there can be a lot of value in using Apache Isis for prototyping.  Because all 
you need do to get an app running is write domain objects, you can very quickly 
explore a domain object model and validate ideas with a domain expert.
-
-By focusing just on the domain, you'll also find that you start to develop a 
ubiquitous language - a set of terms and concepts that the entire team 
(business and technologists alike) have a shared understanding.
-
-Once you've sketched out your domain model, you can then "start-over" using 
your preferred platform.
-
-
-
-
-
-== Deploy on your own platform
-
-The programming model defined by Apache Isis deliberately minimizes the 
dependencies on the rest of the framework. In fact, the only hard dependency 
that the domain model classes have on Apache Isis is through the 
`org.apache.isis.applib` classes, mostly to pick up annotations such as 
`@Disabled`.
-So, if you have used Apache Isis for prototyping (discussed above), then note 
that it's quite feasible to take your domain model a the basis of your actual 
development effort; Apache Isis' annotations and programming conventions will 
help ensure that any subtle semantics you might have captured in your 
prototyping are not lost.
-
-If you go this route, your deployment platform will of course need to provide 
similar capabilities to Apache Isis.  In particular, you'll need to figure out 
a way to inject domain services into domain entities (eg using a JPA listener), 
and you'll also need to reimplement any domain services you have used that 
Apache Isis provides "out-of-the-box" (eg 
xref:../rgsvc/rgsvc.adoc#_rgsvc_api_QueryResultsCache[`QueryResultsCache`] 
domain service).
-
-
-
-
-
-== Deploy the REST API
-
-REST (Representation State Transfer) is an architectural style for building 
highly scalable distributed systems, using the same principles as the World 
Wide Web. Many commercial web APIs (twitter, facebook, Amazon) are implemented 
as either pure REST APIs or some approximation therein.
-
-The http://restfulobjects.org[Restful Objects specification] defines a means 
by a domain object model can be exposed as RESTful resources using JSON 
representations over HTTP. Apache Isis' 
xref:../ugvro/ugvro.adoc#[RestfulObjects viewer] is an implementation of that 
spec, making any Apache Isis domain object automatically available via REST.
-
-There are a number of use cases for deploying Isis as a REST API, including:
-
-* to allow a custom UI to be built against the RESTful API +
-+
-For example, using Angular or some other RIA technology such as Flex, JavaFX, 
Silverlight
-
-* to enable integration between systems +
-+
-REST is designed to be machine-readable, and so is an excellent choice for 
synchronous data interchange scenarios.
-
-* as a ready-made API for migrating data from one legacy system to its 
replacement.
-
-
-As for the auto-generated webapps, the framework manages object persistence. 
It is perfectly possible to deploy the REST API alongside an auto-generated 
webapp; both work from the same domain object model.
-
-
-
-
-
-== Implement your own viewer
-
-Isis' architecture was always designed to support multiple viewers; and indeed 
Apache Isis out-of-the-box supports two: the Wicket viewer, and the Restful 
Objects viewer (or three, if one includes the Wrapper Factory).
-
-While we mustn't understate the effort involved here, it is feasible to 
implement your own viewers too.  Indeed, one of Apache Isis' committers does 
indeed have a (closed source) viewer, based on 
http://www.wavemaker.com/[Wavemaker].
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology.adoc
deleted file mode 100644
index 580f084..0000000
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology.adoc
+++ /dev/null
@@ -1,45 +0,0 @@
-[[_ugfun_domain-class-ontology]]
-= Domain Class Ontology
-: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 supports recognises four main types of domain classes:
-
-* xref:../ugfun/ugfun.adoc#_ugfun_domain-class-ontology_domain-entities[domain 
entities] - domain objects persisted to the database using JDO/DataNucleus; for 
example `Customer`
-
-* xref:../ugfun/ugfun.adoc#_ugfun_domain-class-ontology_domain-services[domain 
services] - generally singletons, automatically injected, and providing various 
functionality; for example `CustomerRepository`
-
-* xref:../ugfun/ugfun.adoc#_ugfun_domain-class-ontology_view-models[view 
models] - domain objects that are a projection of some state held by the 
database, in support a particular use case; for example `CustomerDashboard` (to 
pull together commonly accessed information about a customer).
-
-* xref:../ugfun/ugfun.adoc#_ugfun_domain-class-ontology_mixins[mixins] - allow 
functionality to be "contributed" in the UI by one module to another object, 
similar to traits or extension methods provided in some programming languages.
-This is an important capability to help keep large applications decoupled.
-
-Domain classes are generally recognized using annotations.
-Apache Isis defines its own set of annotations, while entities are annotated 
using JDO/DataNucleus (though XML can also be used if required).
-JAXB can also be used for view models.
-Apache Isis recognizes some of the JDO and JAXB annotations and infers domain 
semantics from these annotations.
-
-You can generally recognize an Apache Isis domain class because it will be 
probably be annotated using `@DomainObject` and `@DomainService`.
-The framework also defines supplementary annotations, `@DomainObjectLayout` 
and `@DomainServiceLayout`.
-These provide hints relating to the layout of the domain object in the user 
interface.
-(Alternatively, these UI hints can be defined in a supplementary 
xref:../ugvw/ugvw.adoc#_ugvw_layout[`.layout.xml`] file.
-
-We use Maven modules as a way to group related domain objects together; we can 
then reason about all the classes in that module as a single unit.
-By convention there will be a single top-level package corresponding to the 
module.
-
-For example, the (non-ASF) 
link:https://github.com/incodehq/incode-module-document[Document module] (part 
of the link:http://catalog.incode.org[Incode Catalog]) has a top-level package 
of `org.incode.module.document`.
-Within the module there may be various subpackages, but its the module defines 
the namespace.
-
-In the same way that the Java module act as a namespace for domain objects, 
it's good practice to map domain entities to their own (database) schemas.
-
-
-
-include::_ugfun_domain-class-ontology_domain-entities.adoc[leveloffset=+1]
-include::_ugfun_domain-class-ontology_domain-services.adoc[leveloffset=+1]
-include::_ugfun_domain-class-ontology_view-models.adoc[leveloffset=+1]
-include::_ugfun_domain-class-ontology_mixins.adoc[leveloffset=+1]
-
-

http://git-wip-us.apache.org/repos/asf/isis/blob/2f2714cc/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_domain-entities.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_domain-entities.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_domain-entities.adoc
deleted file mode 100644
index ce399e3..0000000
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_domain-entities.adoc
+++ /dev/null
@@ -1,86 +0,0 @@
-[[_ugfun_domain-class-ontology_domain-entities]]
-= Domain Entities
-: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/
-
-
-
-Entities are persistent domain objects, with their persistence handled by 
JDO/DataNucleus.
-As such, they are mapped to a persistent object store, typically an RDBMS, 
with DataNucleus taking care of both lazy loading and also the persisting of 
modified ("dirty") objects.
-
-Domain entities are generally decorated with both DataNucleus and Apache Isis 
annotations.
-The following is typical:
-
-[source,java]
-----
-@javax.jdo.annotations.PersistenceCapable(                                     
 // <1>
-        identityType=IdentityType.DATASTORE,                                   
 // <2>
-        schema = "simple",                                                     
 // <3>
-        table = "SimpleObject"
-)
-@javax.jdo.annotations.DatastoreIdentity(                                      
 // <4>
-        strategy=javax.jdo.annotations.IdGeneratorStrategy.IDENTITY,
-        column="id"
-)
-@javax.jdo.annotations.Version(                                                
 // <5>
-        strategy= VersionStrategy.DATE_TIME,
-        column="version"
-)
-@javax.jdo.annotations.Queries({
-        @javax.jdo.annotations.Query(                                          
 // <6>
-                name = "findByName",
-                value = "SELECT "
-                        + "FROM domainapp.modules.simple.dom.impl.SimpleObject 
"
-                        + "WHERE name.indexOf(:name) >= 0 ")
-})
-@javax.jdo.annotations.Unique(name="SimpleObject_name_UNQ", members = 
{"name"}) // <7>
-@DomainObject(                                                                 
 // <8>
-        objectType = "simple.SimpleObject"
-)
-public class SimpleObject
-             implements Comparable<SimpleObject> {                             
 // <9>
-
-    public SimpleObject(final String name) {                                   
 // <10>
-        setName(name);
-    }
-
-    ...
-
-    @Override
-    public String toString() {
-        return ObjectContracts.toString(this, "name");                         
 // <11>
-    }
-    @Override
-    public int compareTo(final SimpleObject other) {
-        return ObjectContracts.compare(this, other, "name");                   
 // <9>
-    }
-}
-----
-<1> The `@PersistenceCapable` annotation indicates that this is an entity to 
DataNucleus.
-The DataNucleus enhancer acts on the bytecode of compiled entities, injecting 
lazy loading and dirty object tracking functionality.
-Enhanced entities end up also implementing the 
`javax.jdo.spi.PersistenceCapable` interface.
-<2> Indicates how identifiers for the entity are handled.
-Using `DATASTORE` means that a DataNucleus is responsible for assigning the 
value (rather than the application).
-<3> Specifies the RDBMS database schema and table name for this entity will 
reside.
-The schema should correspond with the module in which the entity resides.
-The table will default to the entity name if omitted.
-<4> For entities that are using `DATASTORE` identity, indicates how the id 
will be assigned.
-A common strategy is to allow the database to assign the id, for example using 
an identity column or a sequence.
-<5> The `@Version` annotation is useful for optimistic locking; the strategy 
indicates what to store in the `version` column.
-<6> The `@Query` annotation (usually several of them, nested within a 
`@Queries` annotation) defines queries using JDOQL.
-DataNucleus provides several APIs for defining queries, including entirely 
programmatic and type-safe APIs; but JDOQL is very similar to SQL and so easily 
learnt.
-<7> DataNucleus will automatically add a unique index to the primary surrogate 
id (discussed above), but additional alternative keys can be defined using the 
`@Unique` annotation.
-In the example above, the "name" property is assumed to be unique.
-<8> The `@DomainObject` annotation identifies the domain object to Apache Isis 
(not DataNucleus).
-It isn't necessary to include this annotation -- at least, not for entities -- 
but it is nevertheless recommended.
-In particular, its strongly recommended that the `objectType` (which acts like 
an alias to the concrete domain class) is specified; note that it corresponds 
to the schema/table for DataNucleus' `@PersistenceCapable` annotation.
-<9> Although not required, we strongly recommend that all entities are 
naturally `Comparable`.
-This then allows parent/child relationships to be defined using 
``SortedSet``s; RDBMS after all are set-oriented.
-The `ObjectContracts` utility class provided by Apache Isis makes it easy to 
implement the `compareTo()` method, but you can also just use an IDE to 
generate an implementation or roll your own.
-<10> Chances are that some of the properties of the entity will be mandatory, 
for example any properties that represent an alternate unique key to the entity.
-In regular Java programming we would represent this using a constructor that 
defines these mandatory properties, and in Apache Isis/DataNucleus we can 
likewise define such a constructor.
-When DataNucleus rehydrates domain entities from the database at runtime, it 
actually requires a no-arg constructor (it then sets all state reflectively).
-However, there is no need to provide such a no-arg constructor; it is added by 
the enhancer process.
-<11> The `ObjectContracts` utility class also provides assistance for 
`toString()`, useful when debugging in an IDE.
-

Reply via email to