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/04/17 10:32:35 UTC
[41/43] isis git commit: ISIS-1521: working on ugfun.adoc
http://git-wip-us.apache.org/repos/asf/isis/blob/f6f6a40b/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/f6f6a40b/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/f6f6a40b/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/f6f6a40b/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/f6f6a40b/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/f6f6a40b/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/f6f6a40b/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/f6f6a40b/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/f6f6a40b/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/f6f6a40b/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/f6f6a40b/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/f6f6a40b/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.
-