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/11 13:06:05 UTC
[1/3] isis git commit: ISIS-1521: sorts out top-level links;
removes some TODOs in ugfun.adoc
Repository: isis
Updated Branches:
refs/heads/master 4202292b9 -> cc0eadb2b
http://git-wip-us.apache.org/repos/asf/isis/blob/cc0eadb2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_your-apps.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_your-apps.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_your-apps.adoc
deleted file mode 100644
index c67674b..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_your-apps.adoc
+++ /dev/null
@@ -1,39 +0,0 @@
-[[_ugfun_core-concepts_principles_your-apps]]
-= Your Applications
-: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 primarily aimed at custom-built "enterprise" applications. The UI exposed by the xref:ugvw.adoc#[Wicket viewer] is intended to be usable by domain experts, typically end-users within the organization. The REST API exposed by the xref:ugvro.adoc#[RestfulObjects viewer] allows custom apps to be developed - eg using AngularJS or similar - for use by those requiring more guidance; typically end-users outside of the organization.
-
-But should your organization buy, or build? Buying packaged software makes sense for statutory requirements, such as payroll or general ledger, or document management/retrieval. But it makes much less sense to buy packaged software for the systems that support the core business: the software should fit the business, not the other way around.
-
-
-NOTE: TODO - flesh out the following:
-
-* Flexible, "just enough"
-
-* Decoupled
-
-* Long-term Cost of ownership
-
-** dependency injection of services
-** OO design techniques, eg dependency inversion principle
-** an in-memory event bus
-** applib
-
-** (no "Big Ball of Mud")
-
-* Honouring the Single Responsibility Principle
-** behaviourally Complete vs Contributions/Mixins
-
-* Testable +
-+
-While Apache Isis can be used (very effectively) for simple CRUD-style applications, it is also intended to be used for complex business domains. Ensuring that the business logic in
-such applications is correct means that the framework must (and does) provide robust testing support, both for developer-level unit testing and business-level (end-to-end) integration testing.
-
-* Reusable building blocks +
-+
-Isis addons, catalog.incode.org
-
http://git-wip-us.apache.org/repos/asf/isis/blob/cc0eadb2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_enabling-logging.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_enabling-logging.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_enabling-logging.adoc
index 42084d5..18e4a1f 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_enabling-logging.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_enabling-logging.adoc
@@ -4,7 +4,8 @@
:_basedir: ../../
:_imagesdir: images/
-Sometimes you just need to see what is going on. There are various ways in which logging can be enabled, here are the ones we tend to use.
+Sometimes you just need to see what is going on.
+There are various ways in which logging can be enabled, here are the ones we tend to use.
* In Apache Isis +
+
@@ -16,7 +17,8 @@ As per the http://www.datanucleus.org/products/accessplatform/logging.html[DN lo
* In the JDBC Driver +
+
-Configure `log4jdbc` JDBC rather than the vanilla driver (see `WEB-INF/persistor_datanucleus.properties`) and configure log4j logging (see `WEB-INF/logging.properties`). There are examples of both in the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
+Configure `log4jdbc` JDBC rather than the vanilla driver (see `WEB-INF/persistor_datanucleus.properties`) and configure log4j logging (see `WEB-INF/logging.properties`).
+There are examples of both in the xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype].
* In the database +
+
http://git-wip-us.apache.org/repos/asf/isis/blob/cc0eadb2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_enhance-only.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_enhance-only.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_enhance-only.adoc
index 4e831e8..4af2db6 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_enhance-only.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_enhance-only.adoc
@@ -14,4 +14,12 @@ Yes, you can; here's one way:
* Duplicate your run configuration for running the webapp
** the one where the main class is `org.apache.isis.WebServer`
** there's a button for this on the run configurations dialog.
-* then, on your copy change the main class to `org.apache.isis.Dummy`
\ No newline at end of file
+* then, on your copy change the main class to `org.apache.isis.Dummy`
+
+Or, you could just write a small shell script and run from the command line:
+
+[source,bash]
+.enhance.sh
+----
+mvn -pl dom datanucleus:enhance -o
+----
http://git-wip-us.apache.org/repos/asf/isis/blob/cc0eadb2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_how-run-fixtures-on-app-startup.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_how-run-fixtures-on-app-startup.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_how-run-fixtures-on-app-startup.adoc
index 13472da..9964d39 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_how-run-fixtures-on-app-startup.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_how-run-fixtures-on-app-startup.adoc
@@ -7,14 +7,18 @@
From this link:http://isis.markmail.org/thread/g6amfj2eyf2xfjbr[thread] on the Apache Isis users mailing list:
-* _my fixtures have grown into a couple of files the application needs to read in when it starts the first time
-(and possibly later on when the files content change). What is the right way to do this? Hook up into the webapp start? Use events?_
+* _my fixtures have grown into a couple of files the application needs to read in when it starts the first time (and possibly later on when the files content change).
+What is the right way to do this?
+Hook up into the webapp start?
+Use events?_
-The standard approach is to use xref:ugtst.adoc#_ugtst_fixture-scripts[fixture scripts]. These can be run in on start-up typically by being specified in the xref:rgcsm.adoc#_rgcsm_classes_AppManifest-bootstrapping[`AppManifest`], see for
+The standard approach is to use xref:ugtst.adoc#_ugtst_fixture-scripts[fixture scripts].
+These can be run in on start-up typically by being specified in the xref:rgcsm.adoc#_rgcsm_classes_AppManifest-bootstrapping[`AppManifest`], see for
example the xref:ug.adoc#_ug_getting-started_simpleapp-archetype[SimpleApp archetype].
Alternatively just set "isis.fixtures" and "isis.persistor.datanucleus.install-fixtures" properties.
-In terms of implementations, you might also want to check out the (non-ASF) http://github.com/isisaddons/isis-module-excel[Isis addons' excel] module, by using link:https://github.com/isisaddons/isis-module-excel/blob/master/dom/src/main/java/org/isisaddons/module/excel/dom/ExcelFixture.java[`ExcelFixture`] and overriding `ExcelFixtureRowHandler` (same package). An example can be found in this (non ASF) link:https://github.com/incodehq/contactapp[contactapp], see link:https://github.com/incodehq/contactapp/blob/master/backend/fixture/src/main/java/domainapp/fixture/scenarios/demo/ContactRowHandler.java[`ContactRowHandler`].
+In terms of implementations, you might also want to check out the (non-ASF) http://github.com/isisaddons/isis-module-excel[Isis addons' excel] module, by using link:https://github.com/isisaddons/isis-module-excel/blob/master/dom/src/main/java/org/isisaddons/module/excel/dom/ExcelFixture.java[`ExcelFixture`] and overriding `ExcelFixtureRowHandler` (same package).
+An example can be found in this (non ASF) link:https://github.com/incodehq/contactapp[contactapp], see link:https://github.com/incodehq/contactapp/blob/master/backend/fixture/src/main/java/domainapp/fixture/scenarios/demo/ContactRowHandler.java[`ContactRowHandler`].
http://git-wip-us.apache.org/repos/asf/isis/blob/cc0eadb2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_how-to-handle-void-and-null-results.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_how-to-handle-void-and-null-results.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_how-to-handle-void-and-null-results.adoc
index e73e61a..b57c453 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_how-to-handle-void-and-null-results.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_how-to-handle-void-and-null-results.adoc
@@ -8,24 +8,23 @@
From this link:http://isis.markmail.org/thread/yf7qdeiu3vrvk2ei[thread] on the Apache Isis users mailing list:
-* _When using a void action, let\u2019s say a remove action, the user is redirected to a
-page "no results". When clicking the back button in the browser the user sees
-"Object not found" (since you\u2019ve just deleted this object)._
+* _When using a `void` action, let\u2019s say a remove action, the user is redirected to a
+page "no results".
+When clicking the back button in the browser the user sees "Object not found" (since you\u2019ve just deleted this object)._
* _You can return a list for example to prevent the user from being redirect to a
"No results" page, but I think it\u2019s not the responsibility of the controllers in
the domain model._
* _A solution could be that wicket viewer goes back one page when
- encountering a deleted object. And refresh the current page when receiving a
- null response or invoking a void action. But how to implement this?_
+ encountering a deleted object.
+And refresh the current page when receiving a null response or invoking a void action.
+But how to implement this?_
-One way to implement this idea is to provide a custom implementation of the xref:rgsvc.adoc#_rgsvc_spi_RoutingService[`RoutingService`] SPI domain service. The default implementation will either return
-the current object (if not null), else the home page (as defined by xref:rgant.adoc#_rgant-HomePage[`@HomePage`]) if
-one exists.
+One way to implement this idea is to provide a custom implementation of the xref:rgsvc.adoc#_rgsvc_spi_RoutingService[`RoutingService`] SPI domain service.
+The default implementation will either return the current object (if not null), else the home page (as defined by xref:rgant.adoc#_rgant-HomePage[`@HomePage`]) if one exists.
-The following custom implementation refines this to use the breadcrumbs (available in the Wicket viewer) to return the
-first non-deleted domain object found in the list of breadcrumbs:
+The following custom implementation refines this to use the breadcrumbs (available in the Wicket viewer) to return the first non-deleted domain object found in the list of breadcrumbs:
[source,java]
----
http://git-wip-us.apache.org/repos/asf/isis/blob/cc0eadb2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_how-to-implement-a-spellchecker.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_how-to-implement-a-spellchecker.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_how-to-implement-a-spellchecker.adoc
index 543bcc4..1c48c0d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_how-to-implement-a-spellchecker.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_how-to-implement-a-spellchecker.adoc
@@ -23,8 +23,7 @@ You'll need some way to know which fields should be spell checked. Two ways spr
* either look at the domain event's identifier
-* or subclass the domain event (recommended anyway) and have those subclass events implement some sort of marker
-interface, eg a `SpellCheckEvent`.
+* or subclass the domain event (recommended anyway) and have those subclass events implement some sort of marker interface, eg a `SpellCheckEvent`.
And you'll (obviously) also need some sort of spell checker implementation to call.
http://git-wip-us.apache.org/repos/asf/isis/blob/cc0eadb2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_i18n-label-in-wicket-viewer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_i18n-label-in-wicket-viewer.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_i18n-label-in-wicket-viewer.adoc
index 60b3598..220c58b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_i18n-label-in-wicket-viewer.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_i18n-label-in-wicket-viewer.adoc
@@ -8,17 +8,19 @@
From link:http://isis.markmail.org/thread/ctppmtcbsf4iskzi[this thread] on the Apache Isis users mailing list:
-* _I am trying to internationalize the label descriptions of form actions, eg those in `ActionParametersFormPanel`. Referencing those via their message id inside a .po file didn't work either. Can this be done?_
+* _I am trying to internationalize the label descriptions of form actions, eg those in `ActionParametersFormPanel`.
+Referencing those via their message id inside a .po file didn't work either.
+Can this be done?_
-The above FAQ was raised against `1.10.0`. As of `1.11.0` (due to link:https://issues.apache.org/jira/browse/ISIS-1093[ISIS-1093]) it _is_ now possible to internationalize both the Wicket viewer's labels as well as the regular translations of the domain object metadata using the `.po` translation files as
-supported by the xref:rgsvc.adoc#_rgsvc_spi_TranslationService[`TranslationService`].
+The above FAQ was raised against `1.10.0`. As of `1.11.0` (due to link:https://issues.apache.org/jira/browse/ISIS-1093[ISIS-1093]) it _is_ now possible to internationalize both the Wicket viewer's labels as well as the regular translations of the domain object metadata using the `.po` translation files as supported by the xref:rgsvc.adoc#_rgsvc_spi_TranslationService[`TranslationService`].
Full details of the ``msgId``s that must be added to the `translations.po` file can be found in xref:guides/ugbtb.adoc#__ugbtb_i18n_wicket-viewer[i18n] section of the xref:ugbtb.adoc#[beyond the basics] guide.
-In prior releases (`1.10.0` and earlier) it was necessary to use link:https://ci.apache.org/projects/wicket/guide/6.x/guide/i18n.html#i18n_3[ Wicket's internationalization support], namely resource bundles. This is still supported (as a fallback):
+In prior releases (`1.10.0` and earlier) it was necessary to use link:https://ci.apache.org/projects/wicket/guide/6.x/guide/i18n.html#i18n_3[Wicket's internationalization support], namely resource bundles. This is still supported (as a fallback):
* create a directory structure inside the webapp resource folder following that pattern `org.apache.isis.viewer.wicket.ui.components.actions`
+
* Inside there create an equivalent `ActionParametersFormPanel_xx_XX.properties` or `ActionParametersFormPanel_xx.properties` file for the various locales that you want to support (eg `ActionParametersFormPanel_en_UK.properties`, `ActionParametersFormPanel_en_US.properties`, `ActionParametersFormPanel_de.properties` and so on).
http://git-wip-us.apache.org/repos/asf/isis/blob/cc0eadb2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_per-user-themes.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_per-user-themes.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_per-user-themes.adoc
index 91895ea..a9b34d4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_per-user-themes.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_per-user-themes.adoc
@@ -4,15 +4,18 @@
:_basedir: ../../
:_imagesdir: images/
+
From link:http://isis.markmail.org/thread/kb4442niwwbnghey[this thread] on the Apache Isis users mailing list:
-* _Is it possible to have each of our resellers (using our Isis application) use there own theme/branding with their own logo and colors? Would this also be possible for the login page, possibly depending on the used host name?_
+* _Is it possible to have each of our resellers (using our Isis application) use there own theme/branding with their own logo and colors?
+Would this also be possible for the login page, possibly depending on the used host name?_
Yes, you can do this, by installing a custom implementation of the Wicket Bootstrap's `ActiveThemeProvider`.
The http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp] (non-ASF) actually link:https://github.com/isisaddons/isis-app-todoapp/tree/61b8114a8e01dbb3c380b31cf09eaed456407570[does this], storing the info via the http://github.com/isisaddons/isis-module-settings[Isis addons' settings module] settings modules:
+
[source,java]
.IActiveThemeProvider implementation
----
@@ -24,10 +27,11 @@ public class UserSettingsThemeProvider implements ActiveThemeProvider {
final String themeName = IsisContext.doInSession(new Callable<String>() {
@Override
public String call() throws Exception {
- final Class<UserSettingsService> serviceClass = UserSettingsService.class;
- final UserSettingsService userSettingsService = lookupService(serviceClass);
+ final UserSettingsService userSettingsService =
+ lookupService(UserSettingsService.class);
final UserSetting activeTheme = userSettingsService.find(
- IsisContext.getAuthenticationSession().getUserName(), ACTIVE_THEME);
+ IsisContext.getAuthenticationSession().getUserName(),
+ ACTIVE_THEME);
return activeTheme != null ? activeTheme.valueAsString() : null;
}
});
@@ -40,11 +44,13 @@ public class UserSettingsThemeProvider implements ActiveThemeProvider {
IsisContext.doInSession(new Runnable() {
@Override
public void run() {
- final String currentUsrName = IsisContext.getAuthenticationSession().getUserName();
+ final String currentUsrName =
+ IsisContext.getAuthenticationSession().getUserName();
final UserSettingsServiceRW userSettingsService =
lookupService(UserSettingsServiceRW.class);
final UserSettingJdo activeTheme =
- (UserSettingJdo) userSettingsService.find(currentUsrName, ACTIVE_THEME);
+ (UserSettingJdo) userSettingsService.find(
+ currentUsrName, ACTIVE_THEME);
if(activeTheme != null) {
activeTheme.updateAsString(themeName);
} else {
http://git-wip-us.apache.org/repos/asf/isis/blob/cc0eadb2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_restful-image-property.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_restful-image-property.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_restful-image-property.adoc
index f7ed9b2..e5deed8 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_restful-image-property.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_restful-image-property.adoc
@@ -8,7 +8,9 @@
From this link:http://markmail.org/message/4kcu7sml4ufdsah3[thread] on the Apache Isis users mailing list:
* _I am trying to display an image in a JavaScript client app, the image comes from
- an Isis RO web service as a string, but it won't show. Is there something I should do to change the message?_
+ an Isis RO web service as a string, but it won't show.
+Is there something I should do to change the message?_
+
The RO viewer returns the image as a string, in the form:
http://git-wip-us.apache.org/repos/asf/isis/blob/cc0eadb2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_subtype-entity-not-fully-populated.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_subtype-entity-not-fully-populated.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_subtype-entity-not-fully-populated.adoc
index 920761b..5b02ae0 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_subtype-entity-not-fully-populated.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_faqs_subtype-entity-not-fully-populated.adoc
@@ -8,25 +8,25 @@
Taken from link:http://markmail.org/message/ovgai56uqgfgnrx7[this thread] on the Apache Isis users mailing list...
-If it seems that Apache Isis (or rather DataNucleus) isn't fully populating domain entities (ie leaving some properties
-as `null`), then check that your actions are not accessing the fields directly. Use getters instead. that is:
+If it seems that Apache Isis (or rather DataNucleus) isn't fully populating domain entities (ie leaving some properties as `null`), then check that your actions are not accessing the fields directly.
+Use getters instead.
+
[WARNING]
====
-Properties of domain entities should always be accessed using getters. The only code that should access to fields
-should be the getters themselves.
+Properties of domain entities should always be accessed using getters.
+The only code that should access to fields should be the getters themselves.
====
-Why so? Because DataNucleus will potentially lazy load some properties, but to do this it needs to know that the
-field is being requested. This is the purpose of the enhancement phase: the bytecode of the original getter method is
-actually wrapped in code that does the lazy loading checking. But hitting the field directly means that the lazy
-loading code does not run.
+Why so?
+Because DataNucleus will potentially lazy load some properties, but to do this it needs to know that the field is being requested.
+This is the purpose of the enhancement phase: the bytecode of the original getter method is actually wrapped in code that does the lazy loading checking.
+But hitting the field directly means that the lazy loading code does not run.
-This error can be subtle: sometimes "incorrect" code that accesses the fields will seem to work. But that will be
-because the field has been populated already, for whatever reason.
+This error can be subtle: sometimes "incorrect" code that accesses the fields will seem to work.
+But that will be because the field has been populated already, for whatever reason.
-One case where you will find the issue highlighted is for subtype tables that have been mapped using an inheritance
-strategy of `NEW_TABLE`, eg:
+One case where you will find the issue highlighted is for subtype tables that have been mapped using an inheritance strategy of `NEW_TABLE`, eg:
[source,java]
----
@@ -48,21 +48,13 @@ public class SubtypeEntity extends SupertypeEntity {
}
----
-This will generate two tables in the database, with the primary key of the supertype table propagated as a foreign key
-(also primary key) of the subtype table (sometimes called "table per type" strategy). This means that DataNucleus
-might retrieve data from only the supertype table, and the lazily load the subtype fields only as required. This is
-preferable to doing a left outer join from the super- to the subtype tables to retrieve data that might not be needed.
+This will generate two tables in the database, with the primary key of the supertype table propagated as a foreign key (also primary key) of the subtype table (sometimes called "table per type" strategy).
+This means that DataNucleus might retrieve data from only the supertype table, and the lazily load the subtype fields only as required.
+This is preferable to doing a left outer join from the super- to the subtype tables to retrieve data that might not be needed.
-On the other hand, if the `SUPERCLASS_TABLE` strategy (aka "table per hierarchy" or roll-up) or the `SUBCLASS_TABLE`
-strategy (roll-down) was used, then the problem is less likely to occur because DataNucleus would obtain all the data
-for any given instance from a single table.
+On the other hand, if the `SUPERCLASS_TABLE` strategy (aka "table per hierarchy" or roll-up) or the `SUBCLASS_TABLE` strategy (roll-down) was used, then the problem is less likely to occur because DataNucleus would obtain all the data for any given instance from a single table.
-Final note: references to other objects (either scalar references or in collections) in particular require that getters
-rather than fields to be used to obtain them: it's hopefully obvious that DataNucleus (like all ORMs) should not and
-will not resolve such references (otherwise, where to stop... and the whole database would be loaded into memory).
+Final note: references to other objects (either scalar references or in collections) in particular require that getters rather than fields to be used to obtain them: it's hopefully obvious that DataNucleus (like all ORMs) should not and will not resolve such references (otherwise, where to stop... and the whole database would be loaded into memory).
In summary, there's just one rule: *always use the getters, never the fields*.
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/cc0eadb2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started.adoc
index 07794e3..df03541 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_getting-started.adoc
@@ -7,13 +7,18 @@
-To get you up and running quickly, Apache Isis provides a xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] to setup a simple application as the basis of your own apps. This is deliberately very minimal so that you won't have to spend lots of time removing generated artifacts. On the other hand, it does set up a standard multi-module maven structure with unit- and integration tests pre-configured, as well as a webapp module so that you can easily run your app. We strongly recommend that you preserve this structure as you develop your own Isis application.
+To get you up and running quickly, Apache Isis provides a xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] to setup a simple application as the basis of your own apps.
+This is deliberately kept quite minimal so that you won't have to spend lots of time removing generated artifacts.
+On the other hand, it does set up a standard multi-module maven structure with unit- and integration tests pre-configured, as well as a webapp module so that you can easily run your app.
+We strongly recommend that you preserve this structure as you develop your own Isis application.
-In this chapter we also discuss the xref:ugfun.adoc#_ugfun_getting-started_datanucleus-enhancer[DataNucleus enhancer]. link:http://www.datanucleus.org/[DataNucleus] is the reference implementation of the JDO (Java data objects) spec, and Apache Isis integrates with DataNucleus as its persistence layer. The enhancer performs post-processing on the bytecode of your persistent domain entities, such that they can be persisted by Apache Isis' JDO/DataNucleus objectstore.
+In this chapter we also discuss the xref:ugfun.adoc#_ugfun_getting-started_datanucleus-enhancer[DataNucleus enhancer]. link:http://www.datanucleus.org/[DataNucleus] is the reference implementation of the JDO (Java data objects) spec, and Apache Isis integrates with DataNucleus as its persistence layer.
+The enhancer performs post-processing on the bytecode of your persistent domain entities, such that they can be persisted by Apache Isis' JDO/DataNucleus objectstore.
[NOTE]
====
-The xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] automatically configures the enhancer, so there's little you need to do at this stage. Even so we feel it's a good idea to be aware of this critical part of Apache Isis runtime; if the enhancer does not run, then you'll find the app fails to start with (what will seem like) quite an obscure exception message.
+The xref:ugfun.adoc#_ugfun_getting-started_simpleapp-archetype[SimpleApp archetype] automatically configures the enhancer, so there's little you need to do at this stage.
+Even so we feel it's a good idea to be aware of this critical part of Apache Isis runtime; if the enhancer does not run, then you'll find the app fails to start with (what will seem like) quite an obscure exception message.
====
@@ -26,11 +31,15 @@ Apache Isis is a Java based framework, so in terms of prerequisites, you'll need
* Java 7 or 8 JDK
* link:http://maven.apache.org[Apache Maven] 3.0.5 or later
-You'll probably also want to use an IDE; the Apache Isis committers use either IntelliJ or Eclipse; in the xref:dg.adoc#_dg_ide[Developers' Guide] we have detailed setup instructions for using these two IDEs. If you're a NetBeans user you should have no problems as it too has strong support for Maven.
+You'll probably also want to use an IDE; the Apache Isis committers use either IntelliJ or Eclipse; in the xref:dg.adoc#_dg_ide[Developers' Guide] we have detailed setup instructions for using these two IDEs.
+If you're a NetBeans user you should have no problems as it too has strong support for Maven.
-When building and running within an IDE, you'll also need to configure the Datanucleus enhancer. This is implemented as a Maven plugin, so in the case of IntelliJ, it's easy enough to run the enhancer as required. It should be just as straightforward for NetBeans too.
+When building and running within an IDE, you'll also need to configure the Datanucleus enhancer.
+This is implemented as a Maven plugin, so in the case of IntelliJ, it's easy enough to run the enhancer as required.
+It should be just as straightforward for NetBeans too.
-For Eclipse the maven integration story is a little less refined. All is not lost, however; DataNucleus also has an implementation of the enhancer as an Eclipse plugin, which usually works well enough.
+For Eclipse the maven integration story is a little less refined.
+All is not lost, however; DataNucleus also has an implementation of the enhancer as an Eclipse plugin, which usually works well enough.
include::_ugfun_getting-started_simpleapp-archetype.adoc[leveloffset=+1]
include::_ugfun_getting-started_datanucleus-enhancer.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/cc0eadb2/adocs/documentation/src/main/asciidoc/guides/ugfun/images/core-concepts/philosophy/build-vs-buy.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/core-concepts/philosophy/build-vs-buy.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/core-concepts/philosophy/build-vs-buy.png
new file mode 100644
index 0000000..f95ae93
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/core-concepts/philosophy/build-vs-buy.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/cc0eadb2/adocs/documentation/src/main/asciidoc/guides/ugfun/images/core-concepts/philosophy/build-vs-buy.pptx
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/core-concepts/philosophy/build-vs-buy.pptx b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/core-concepts/philosophy/build-vs-buy.pptx
new file mode 100644
index 0000000..3c2e9fe
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/core-concepts/philosophy/build-vs-buy.pptx differ
http://git-wip-us.apache.org/repos/asf/isis/blob/cc0eadb2/adocs/documentation/src/main/asciidoc/guides/ugfun/images/core-concepts/philosophy/decoupled-applications.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/core-concepts/philosophy/decoupled-applications.png b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/core-concepts/philosophy/decoupled-applications.png
new file mode 100644
index 0000000..2e45f1d
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/core-concepts/philosophy/decoupled-applications.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/cc0eadb2/adocs/documentation/src/main/asciidoc/guides/ugfun/images/core-concepts/philosophy/decoupled-applications.pptx
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/core-concepts/philosophy/decoupled-applications.pptx b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/core-concepts/philosophy/decoupled-applications.pptx
new file mode 100644
index 0000000..b93eca4
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/core-concepts/philosophy/decoupled-applications.pptx differ
http://git-wip-us.apache.org/repos/asf/isis/blob/cc0eadb2/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips.adoc b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips.adoc
index c231dd5..24ccb2e 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugvro/_ugvro_hints-and-tips.adoc
@@ -21,11 +21,11 @@ This link:https://www.youtube.com/watch?v=_-TOvVYWCHc[screencast] shows how to e
-== AngularJS Tips
+== Angular Tips
The hypermedia API exposed by Apache Isis' Restful Objects viewer is intended be support both bespoke custom-written viewers as well as generic viewers. Indeed, we expect most clients consuming the API will be bespoke, not generic.
-This page captures one or two tips on using AngularJS to write such a bespoke client.
+This page captures one or two tips on using Angular to write such a bespoke client.
=== Invoking a GET link (eg invoking a query action)
@@ -62,7 +62,7 @@ Restful Objects will expose this as action with the following link that looks so
}
----
-You can then invoke this using AngularJs' `$resource` service as follows.
+You can then invoke this using Angular' `$resource` service as follows.
[source,javascript]
----
http://git-wip-us.apache.org/repos/asf/isis/blob/cc0eadb2/adocs/documentation/src/main/asciidoc/js/app.js
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/js/app.js b/adocs/documentation/src/main/asciidoc/js/app.js
index 5dcb408..bcf3520 100644
--- a/adocs/documentation/src/main/asciidoc/js/app.js
+++ b/adocs/documentation/src/main/asciidoc/js/app.js
@@ -27,7 +27,7 @@ $('#search-form').submit(function(ev) {
} else {
$("#search-panel").addClass("active");
$("#search-panel a").attr("href", docname + "." + filetype)
-
+
for (var i = 0; i < Math.min(searchResults.length, 20); i++) {
var searchResult = searchResults[i];
http://git-wip-us.apache.org/repos/asf/isis/blob/cc0eadb2/adocs/template/document.html.erb
----------------------------------------------------------------------
diff --git a/adocs/template/document.html.erb b/adocs/template/document.html.erb
index 74d5739..7cb92c3 100644
--- a/adocs/template/document.html.erb
+++ b/adocs/template/document.html.erb
@@ -378,10 +378,10 @@
<!-- Left Nav Section -->
<ul class="left">
- <li><a href="documentation.html">Documentation</a></li>
- <li><a href="downloads.html">Downloads</a></li>
- <li><a href="help.html">Help</a></li>
- <li><a href="asf.html">@ASF</a></li>
+ <li><a href="<%= (attr :_basedir) %>documentation.html">Documentation</a></li>
+ <li><a href="<%= (attr :_basedir) %>downloads.html">Downloads</a></li>
+ <li><a href="<%= (attr :_basedir) %>help.html">Help</a></li>
+ <li><a href="<%= (attr :_basedir) %>asf.html">@ASF</a></li>
</ul>
[2/3] isis git commit: ISIS-1521: sorts out top-level links;
removes some TODOs in ugfun.adoc
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/cc0eadb2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_domain-driven-design.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_domain-driven-design.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_domain-driven-design.adoc
index 062f488..45411a4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_domain-driven-design.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_domain-driven-design.adoc
@@ -4,9 +4,13 @@
:_basedir: ../../
:_imagesdir: images/
-There's no doubt that we developers love the challenge of understanding and deploying complex technologies. But understanding the nuances and subtleties of the business domain itself is just as great a challenge, perhaps more so. If we devoted our efforts to understanding and addressing those subtleties, we could build better, cleaner, and more maintainable software that did a better job for our stakeholders. And there's no doubt that our stakeholders would thank us for it.
+There's no doubt that we developers love the challenge of understanding and deploying complex technologies.
+But understanding the nuances and subtleties of the business domain itself is just as great a challenge, perhaps more so.
+If we devoted our efforts to understanding and addressing those subtleties, we could build better, cleaner, and more maintainable software that did a better job for our stakeholders.
+And there's no doubt that our stakeholders would thank us for it.
-A couple of years back Eric Evans wrote his book link:http://www.amazon.co.uk/Domain-driven-Design-Tackling-Complexity-Software/dp/0321125215[Domain-Driven Design], which is well on its way to becoming a seminal work. In fact, most if not all of the ideas in Evans' book have been expressed before, but what he did was pull those ideas together to show how predominantly object-oriented techniques can be used to develop rich, deep, insightful, and ultimately useful business applications.
+A couple of years back Eric Evans wrote his book link:http://www.amazon.co.uk/Domain-driven-Design-Tackling-Complexity-Software/dp/0321125215[Domain-Driven Design], which is well on its way to becoming a seminal work.
+In fact, most if not all of the ideas in Evans' book have been expressed before, but what he did was pull those ideas together to show how predominantly object-oriented techniques can be used to develop rich, deep, insightful, and ultimately useful business applications.
There are two central ideas at the heart of domain-driven design.
@@ -16,18 +20,28 @@ There are two central ideas at the heart of domain-driven design.
Let's look at each in turn.
+
[[__ugfun_core-concepts_philosophy_domain-driven-design_ubiquitous-language]]
== Ubiquitous Language
-It's no secret that the IT industry is plagued by project failures. Too often systems take longer than intended to implement, and when finally implemented, they don't address the real requirements anyway.
+It's no secret that the IT industry is plagued by project failures.
+Too often systems take longer than intended to implement, and when finally implemented, they don't address the real requirements anyway.
-Over the years we in IT have tried various approaches to address this failing. Using waterfall methodologies, we've asked for requirements to be fully and precisely written down before starting on anything else. Or, using agile methodologies, we've realized that requirements are likely to change anyway and have sought to deliver systems incrementally using feedback loops to refine the implementation.
+Over the years we in IT have tried various approaches to address this failing.
+Using waterfall methodologies, we've asked for requirements to be fully and precisely written down before starting on anything else.
+Or, using agile methodologies, we've realized that requirements are likely to change anyway and have sought to deliver systems incrementally using feedback loops to refine the implementation.
-But let's not get distracted talking about methodologies. At the end of the day what really matters is communication between the domain experts (that is, the business) who need the system and the techies actually implementing it. If the two don't have and cannot evolve a shared understanding of what is required, then the chance of delivering a useful system will be next to nothing.
+But let's not get distracted talking about methodologies.
+At the end of the day what really matters is communication between the domain experts (that is, the business) who need the system and the techies actually implementing it.
+If the two don't have and cannot evolve a shared understanding of what is required, then the chance of delivering a useful system will be next to nothing.
-Bridging this gap is traditionally what business analysts are for; they act as interpreters between the domain experts and the developers. However, this still means there are two (or more) languages in use, making it difficult to verify that the system being built is correct. If the analyst mistranslates a requirement, then neither the domain expert nor the application developer will discover this until (at best) the application is first demonstrated or (much worse) an end user sounds the alarm once the application has been deployed into production.
+Bridging this gap is traditionally what business analysts are for; they act as interpreters between the domain experts and the developers.
+However, this still means there are two (or more) languages in use, making it difficult to verify that the system being built is correct.
+If the analyst mistranslates a requirement, then neither the domain expert nor the application developer will discover this until (at best) the application is first demonstrated or (much worse) an end user sounds the alarm once the application has been deployed into production.
-Rather than trying to translate between a business language and a technical language, with _DDD_ we aim to have the business and developers using the same terms for the same concepts in order to create a single *_domain model_*. This domain model identifies the relevant concepts of the domain, how they relate, and ultimately where the responsibilities are. This single domain model provides the vocabulary for the ubiquitous language for our system.
+Rather than trying to translate between a business language and a technical language, with _DDD_ we aim to have the business and developers using the same terms for the same concepts in order to create a single *_domain model_*.
+This domain model identifies the relevant concepts of the domain, how they relate, and ultimately where the responsibilities are.
+This single domain model provides the vocabulary for the ubiquitous language for our system.
.Ubiquitous Language
@@ -38,42 +52,69 @@ If an idea cannot be expressed using this set of concepts, then go back and exte
****
-Creating a ubiquitous language calls upon everyone involved in the system's development to express what they are doing through the vocabulary provided by the model. If this can't be done, then our model is incomplete. Finding the missing words deepens our understanding of the domain being modeled.
+Creating a ubiquitous language calls upon everyone involved in the system's development to express what they are doing through the vocabulary provided by the model.
+If this can't be done, then our model is incomplete. Finding the missing words deepens our understanding of the domain being modeled.
-This might sound like nothing more than me insisting that the developers shouldn't use jargon when talking to the business. Well, that's true enough, but it's not a one-way street. A *ubiquitous language* demands that the developers work hard to understand the problem domain, but it also demands that the business works hard in being *precise* in its naming and descriptions of those concepts. After all, ultimately the developers will have to express those concepts in a computer programming language.
+This might sound like nothing more than me insisting that the developers shouldn't use jargon when talking to the business.
+Well, that's true enough, but it's not a one-way street.
+A *ubiquitous language* demands that the developers work hard to understand the problem domain, but it also demands that the business works hard in being *precise* in its naming and descriptions of those concepts.
+After all, ultimately the developers will have to express those concepts in a computer programming language.
-Also, although here I'm talking about the "domain experts" as being a homogeneous group of people, often they may come from different branches of the business. Even if we weren't building a computer system, there's a lot of value in helping the domain experts standardize their own terminology. Is the marketing department's "prospect" the same as sales' "customer," and is that the same as an after-sales "contract"?
+Also, although here I'm talking about the "domain experts" as being a homogeneous group of people, often they may come from different branches of the business. Even if we weren't building a computer system, there's a lot of value in helping the domain experts standardize their own terminology.
+Is the marketing department's "prospect" the same as sales' "customer," and is that the same as an after-sales "contract"?
-The need for precision within the ubiquitous language also helps us scope the system. Most business processes evolve piecemeal and are often quite ill-defined. If the domain experts have a very good idea of what the business process should be, then that's a good candidate for automation, that is, including it in the scope of the system. But if the domain experts find it hard to agree, then it's probably best to leave it out. After all, human beings are rather more capable of dealing with fuzzy situations than computers.
+The need for precision within the ubiquitous language also helps us scope the system. Most business processes evolve piecemeal and are often quite ill-defined.
+If the domain experts have a very good idea of what the business process should be, then that's a good candidate for automation, that is, including it in the scope of the system.
+But if the domain experts find it hard to agree, then it's probably best to leave it out.
+After all, human beings are rather more capable of dealing with fuzzy situations than computers.
-So, if the development team (business and developers together) continually searches to build their ubiquitous language, then the domain model naturally becomes richer as the nuances of the domain are uncovered. At the same time, the knowledge of the business domain experts also deepens as edge conditions and contradictions that have previously been overlooked are explored.
+So, if the development team (business and developers together) continually searches to build their ubiquitous language, then the domain model naturally becomes richer as the nuances of the domain are uncovered.
+At the same time, the knowledge of the business domain experts also deepens as edge conditions and contradictions that have previously been overlooked are explored.
-We use the ubiquitous language to build up a domain model. But what do we do *with* that model? The answer to that is the second of our central ideas.
+We use the ubiquitous language to build up a domain model.
+But what do we do *with* that model? The answer to that is the second of our central ideas.
== Model-Driven Design
-Of the various methodologies that the IT industry has tried, many advocate the production of separate analysis models and implementation models. One example (from the mid 2000s) was that of the _OMG_'s Model-Driven Architecture ( _MDA_) initiative, with its platform-independent model (the _PIM_) and a platform-specific model (the _PSM_).
+Of the various methodologies that the IT industry has tried, many advocate the production of separate analysis models and implementation models.
+One example (from the mid 2000s) was that of the _OMG_'s Model-Driven Architecture ( _MDA_) initiative, with its platform-independent model (the _PIM_) and a platform-specific model (the _PSM_).
-Bah and humbug! If we use our ubiquitous language just to build up a high-level analysis model, then we will re-create the communication divide. The domain experts and business analysts will look only to the analysis model, and the developers will look only to the implementation model. Unless the mapping between the two is completely mechanical, inevitably the two will diverge.
+Bah and humbug!
+If we use our ubiquitous language just to build up a high-level analysis model, then we will re-create the communication divide.
+The domain experts and business analysts will look only to the analysis model, and the developers will look only to the implementation model. Unless the mapping between the two is completely mechanical, inevitably the two will diverge.
-What do we mean by *model* anyway? For some, the term will bring to mind UML class or sequence diagrams and the like. But this isn't a model; it's a visual *representation* of some aspect of a model. No, a domain model is a group of related concepts, identifying them, naming them, and defining how they relate. What is in the model depends on what our objective is. We're not looking to simply model everything that's out there in the real world. Instead, we want to take a relevant abstraction or simplification of it and then make it do something useful for us. A model is neither right nor wrong, just more or less useful.
+What do we mean by *model* anyway?
+For some, the term will bring to mind UML class or sequence diagrams and the like.
+But this isn't a model; it's a visual *representation* of some aspect of a model.
+No, a domain model is a group of related concepts, identifying them, naming them, and defining how they relate.
+What is in the model depends on what our objective is.
+We're not looking to simply model everything that's out there in the real world.
+Instead, we want to take a relevant abstraction or simplification of it and then make it do something useful for us.
+A model is neither right nor wrong, just more or less useful.
-For our ubiquitous language to have value, the domain model that encodes it must have a straightforward, literal representation to the design of the software, specifically to the implementation. Our software's design should be driven by this model; we should have a model-driven design.
+For our ubiquitous language to have value, the domain model that encodes it must have a straightforward, literal representation to the design of the software, specifically to the implementation.
+Our software's design should be driven by this model; we should have a model-driven design.
.Model-Driven Design
****
-There must be a straightforward and very literal way to represent the domain model in terms of software. The model should balance these two requirements: form the ubiquitous language of the development team and be representable in code.
+There must be a straightforward and very literal way to represent the domain model in terms of software.
+The model should balance these two requirements: form the ubiquitous language of the development team and be representable in code.
Changing the code means changing the model; refining the model requires a change to the code.
****
-Here also the word *design* might mislead; some might be thinking of design documents and design diagrams, or perhaps of user interface (UX) design. But by *design* we mean a way of organizing the domain concepts, which in turn leads to the way in which we organize their representation in code.
+Here also the word *design* might mislead; some might be thinking of design documents and design diagrams, or perhaps of user interface (UX) design.
+But by *design* we mean a way of organizing the domain concepts, which in turn leads to the way in which we organize their representation in code.
-Luckily, using *_object-oriented_* (_OO_) languages such as Java, this is relatively easy to do; _OO_ is based on a modeling paradigm anyway. We can express domain concepts using classes and interfaces, and we can express the relationships between those concepts using associations.
+Luckily, using *_object-oriented_* (_OO_) languages such as Java, this is relatively easy to do; _OO_ is based on a modeling paradigm anyway.
+We can express domain concepts using classes and interfaces, and we can express the relationships between those concepts using associations.
-So far so good. Or maybe, so far so much motherhood and apple pie. Understanding the _DDD_ concepts isn't the same as being able to apply them, and some of the _DDD_ ideas can be difficult to put into practice. Time to discuss the naked objects pattern and how it eases that path by applying these central ideas of _DDD_ in a very concrete way.
+So far so good.
+Or maybe, so far so much motherhood and apple pie.
+Understanding the _DDD_ concepts isn't the same as being able to apply them, and some of the _DDD_ ideas can be difficult to put into practice.
+Time to discuss the naked objects pattern and how it eases that path by applying these central ideas of _DDD_ in a very concrete way.
http://git-wip-us.apache.org/repos/asf/isis/blob/cc0eadb2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_hexagonal-architecture.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_hexagonal-architecture.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_hexagonal-architecture.adoc
index 74fc541..6a3afb4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_hexagonal-architecture.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_hexagonal-architecture.adoc
@@ -4,9 +4,16 @@
:_basedir: ../../
:_imagesdir: images/
-One of the patterns that Evans discusses in his book is that of a *layered architecture*. In it he describes why the domain model lives in its own layer within the architecture. The other layers of the application (usually presentation, application, and persistence) have their own responsibilities, and are completely separate. Each layer is cohesive and depending only on the layers below. In particular, we have a layer dedicated to the domain model. The code in this layer is unencumbered with the (mostly technical) responsibilities of the other layers and so can evolve to tackle complex domains as well as simple ones.
-This is a well-established pattern, almost a de-facto; there's very little debate that these responsibilities should be kept separate from each other. With Apache Isis the responsibility for presentation is a framework concern, the responsibility for the domain logic is implemented by the (your) application code.
+One of the patterns that Evans discusses in his book is that of a *layered architecture*.
+In it he describes why the domain model lives in its own layer within the architecture.
+The other layers of the application (usually presentation, application, and persistence) have their own responsibilities, and are completely separate.
+Each layer is cohesive and depending only on the layers below.
+In particular, we have a layer dedicated to the domain model.
+The code in this layer is unencumbered with the (mostly technical) responsibilities of the other layers and so can evolve to tackle complex domains as well as simple ones.
+
+This is a well-established pattern, almost a de-facto; there's very little debate that these responsibilities should be kept separate from each other.
+With Apache Isis the responsibility for presentation is a framework concern, the responsibility for the domain logic is implemented by the (your) application code.
A few years ago Alistair Cockburn reworked the traditional layered architecture diagram and came up with the *_hexagonal architecture_*:.
@@ -18,12 +25,18 @@ The hexagonal architecture is also known as the link:http://c2.com/cgi/wiki?Port
.The hexagonal architecture emphasizes multiple implementations of the different layers.
image::{_imagesdir}core-concepts/philosophy/hexagonal-architecture.png[width="700px"]
-What Cockburn is emphasizing is that there's usually more than one way *into* an application (what he called the *_user-side' ports_*) and more than one way *out of* an application too (the *_data-side ports_*). This is very similar to the concept of primary and secondary actors in use cases: a primary actor (often a human user but not always) is active and initiates an interaction, while a secondary actor (almost always an external system) is passive and waits to be interacted with.
-
-Associated with each port can be an *_adapter_* (in fact, Cockburn's alternative name for this architecture is *_ports and adapters_*). An adapter is a device (piece of software) that talks in the protocol (or _API_) of the port. Each port could have several adapters.
-
-Apache Isis maps very nicely onto the *hexagonal architecture*. Apache Isis' viewers act as user-side adapters and use the Apache Isis metamodel API as a port into the domain objects. For the data side, we are mostly concerned with persisting domain objects to some sort of object store. Here Apache Isis delegates most of the heavy lifting to ORM implementing the JDO API. Most of the time this will be DataNucleus configured to persist to an RDBMS, but DataNucleus can also support other object stores, for example Neo4J. Alternatively Apache Isis can be configured to persist using some other JDO implementation, for example Google App Engine.
+What Cockburn is emphasizing is that there's usually more than one way *into* an application (what he called the *_user-side' ports_*) and more than one way *out of* an application too (the *_data-side ports_*).
+This is very similar to the concept of primary and secondary actors in use cases: a primary actor (often a human user but not always) is active and initiates an interaction, while a secondary actor (almost always an external system) is passive and waits to be interacted with.
+Associated with each port can be an *_adapter_* (in fact, Cockburn's alternative name for this architecture is *_ports and adapters_*).
+An adapter is a device (piece of software) that talks in the protocol (or _API_) of the port.
+Each port could have several adapters.
+Apache Isis maps very nicely onto the *hexagonal architecture*.
+Apache Isis' viewers act as user-side adapters and use the Apache Isis metamodel API as a port into the domain objects.
+For the data side, we are mostly concerned with persisting domain objects to some sort of object store.
+Here Apache Isis delegates most of the heavy lifting to ORM implementing the JDO API.
+Most of the time this will be DataNucleus configured to persist to an RDBMS, but DataNucleus can also support other object stores, for example Neo4J.
+Alternatively Apache Isis can be configured to persist using some other JDO implementation, for example Google App Engine.
http://git-wip-us.apache.org/repos/asf/isis/blob/cc0eadb2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_how-eases-ddd.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_how-eases-ddd.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_how-eases-ddd.adoc
index 861fcbf..c5054e0 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_how-eases-ddd.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_how-eases-ddd.adoc
@@ -6,31 +6,44 @@
-The case for _DDD_ might be compelling, but that doesn't necessarily make it easy to do. Let's take a look at some of the
-challenges that _DDD_ throws up and see how Apache Isis (and its implementation of the naked objects pattern) helps address them.
+The case for _DDD_ might be compelling, but that doesn't necessarily make it easy to do.
+Let's take a look at some of the challenges that _DDD_ throws up and see how Apache Isis (and its implementation of the naked objects pattern) helps address them.
+
+
== DDD takes a conscious effort
Here's what Eric Evans says about ubiquitous language:
-pass:[<div class="extended-quote-first"><p>]With a conscious effort by the [development] team the domain model can provide the backbone for [the] common [ubiquitous] language...connecting team communication to the software implementation."
-pass:[</p></div>]
+____
+With a conscious effort by the [development] team the domain model can provide the backbone for [the] common [ubiquitous] language...connecting team communication to the software implementation.
+____
-pass:[<div class="extended-quote-attribution"><p>]-- Eric Evans
-pass:[</p></div>]
-The word to pick up on here is *conscious*. It takes a conscious effort by the entire team to develop the ubiquitous language. Everyone in the team must challenge the use of new or unfamiliar terms, must clarify concepts when used in a new context, and in general must be on the lookout for sloppy thinking. This takes willingness on the part of all involved, not to mention some practice.
+The word to pick up on here is *conscious*.
+It takes a _conscious_ effort by the entire team to develop the ubiquitous language.
+Everyone in the team must challenge the use of new or unfamiliar terms, must clarify concepts when used in a new context, and in general must be on the lookout for sloppy thinking.
+This takes willingness on the part of all involved, not to mention some practice.
-With Apache Isis, though, the ubiquitous language evolves with scarcely any effort at all. For the business experts, the Apache Isis viewers show the domain concepts they identify and the relationships between those concepts in a straightforward fashion. Meanwhile, the developers can devote themselves to encoding those domain concepts directly as domain classes. There's no technology to get distracted by; there is literally nothing else for the developers to work on.
+With Apache Isis, though, the ubiquitous language evolves with scarcely any effort at all.
+For the business experts, the Apache Isis viewers show the domain concepts they identify and the relationships between those concepts in a straightforward fashion.
+Meanwhile, the developers can devote themselves to encoding those domain concepts directly as domain classes.
+There's no technology to get distracted by; there is literally nothing else for the developers to work on.
== DDD must be grounded
-Employing a model-driven design isn't necessarily straightforward, and the development processes used by some organizations positively hinder it. It's not sufficient for the business analysts or architects to come up with some idealized representation of the business domain and then chuck it over the wall for the programmers to do their best with.
+Employing a model-driven design isn't necessarily straightforward, and the development processes used by some organizations positively hinder it.
+It's not sufficient for the business analysts or architects to come up with some idealized representation of the business domain and then chuck it over the wall for the programmers to do their best with.
-Instead, the concepts in the model must have a very literal representation in code. If we fail to do this, then we open up the communication divide, and our ubiquitous language is lost. There is literally no point having a domain model that cannot be represented in code. We cannot invent our ubiquitous language in a vacuum, and the developers must ensure that the model remains grounded in the doable.
+Instead, the concepts in the model must have a very literal representation in code.
+If we fail to do this, then we open up the communication divide, and our ubiquitous language is lost.
+There is literally no point having a domain model that cannot be represented in code.
+We cannot invent our ubiquitous language in a vacuum, and the developers must ensure that the model remains grounded in the doable.
-In Apache Isis, we have a very pure one-to-one correspondence between the domain concepts and its implementation. Domain concepts are represented as classes and interfaces, easily demonstrated back to the business. If the model is clumsy, then the application will be clumsy too, and so the team can work together to find a better implementable model.
+In Apache Isis, we have a very pure one-to-one correspondence between the domain concepts and its implementation.
+Domain concepts are represented as classes and interfaces, easily demonstrated back to the business.
+If the model is clumsy, then the application will be clumsy too, and so the team can work together to find a better implementable model.
http://git-wip-us.apache.org/repos/asf/isis/blob/cc0eadb2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_naked-objects-pattern.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_naked-objects-pattern.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_naked-objects-pattern.adoc
index 05f8575..11c7c99 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_naked-objects-pattern.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_naked-objects-pattern.adoc
@@ -4,38 +4,53 @@
:_basedir: ../../
:_imagesdir: images/
-Apache Isis implements the naked objects pattern, originally formulated by Richard Pawson. So who better than Richard to explain the origination of the idea?
+Apache Isis implements the naked objects pattern, originally formulated by Richard Pawson.
+So who better than Richard to explain the origination of the idea:
-pass:[<div class="extended-quote-first"><p>]The Naked Objects pattern arose, at least in part, from my own frustration at the lack of success of the domain-driven approach. Good examples were hard to find--as they are still.
-pass:[</p></div>]
+__________________________
+The Naked Objects pattern arose, at least in part, from my own frustration at the lack of success of the domain-driven approach.
+Good examples were hard to find -- as they are still.
-pass:[<div class="extended-quote"><p>]A common complaint from _DDD_ practitioners was that it was hard to gain enough commitment from business stakeholders, or even to engage them at all. My own experience suggested that it was nearly impossible to engage business managers with UML diagrams. It was much easier to engage them in rapid prototyping -- where they could see and interact with the results -- but most forms of rapid prototyping concentrate on the presentation layer, often at the expense of the underlying model and certainly at the expense of abstract thinking.
-pass:[</p></div>]
+A common complaint from _DDD_ practitioners was that it was hard to gain enough commitment from business stakeholders, or even to engage them at all.
+My own experience suggested that it was nearly impossible to engage business managers with UML diagrams.
+It was much easier to engage them in rapid prototyping -- where they could see and interact with the results -- but most forms of rapid prototyping concentrate on the presentation layer, often at the expense of the underlying model and certainly at the expense of abstract thinking.
-pass:[<div class="extended-quote"><p>]Even if you could engage the business sponsors sufficiently to design a domain model, by the time you'd finished developing the system on top of the domain model, most of its benefits had disappeared. It's all very well creating an agile domain object model, but if any change to that model also dictates the modification of one or more layers underneath it (dealing with persistence) and multiple layers on top (dealing with presentation), then that agility is practically worthless.
-pass:[</p></div>]
+Even if you could engage the business sponsors sufficiently to design a domain model, by the time you'd finished developing the system on top of the domain model, most of its benefits had disappeared.
+It's all very well creating an agile domain object model, but if any change to that model also dictates the modification of one or more layers underneath it (dealing with persistence) and multiple layers on top (dealing with presentation), then that agility is practically worthless.
-pass:[<div class="extended-quote"><p>]The other concern that gave rise to the birth of Naked Objects was how to make user interfaces of mainstream business systems more "expressive" -- how to make them feel more like using a drawing program or _CAD_ system. Most business systems are not at all expressive; they treat the user merely as a dumb *process-follower*, rather than as an empowered *problem-solver*. Even the so-called usability experts had little to say on the subject: try finding the word "empowerment" or any synonym thereof in the index of any book on usability. Research had demonstrated that the best way to achieve expressiveness was to create an object-oriented user interface (_OOUI_). In practice, though, __OOUI__s were notoriously hard to develop.
-pass:[</p></div>]
+The other concern that gave rise to the birth of Naked Objects was how to make user interfaces of mainstream business systems more "expressive" -- how to make them feel more like using a drawing program or _CAD_ system.
+Most business systems are not at all expressive; they treat the user merely as a dumb *process-follower*, rather than as an empowered *problem-solver*.
+Even the so-called usability experts had little to say on the subject: try finding the word "empowerment" or any synonym thereof in the index of any book on usability.
+Research had demonstrated that the best way to achieve expressiveness was to create an object-oriented user interface (_OOUI_).
+In practice, though, __OOUI__s were notoriously hard to develop.
-pass:[<div class="extended-quote"><p>]Sometime in the late 1990s, it dawned on me that if the domain model really did represent the "ubiquitous language" of the business and those domain objects were behaviorally rich (that is, business logic is encapsulated as methods on the domain objects rather than in procedural scripts on top of them), then the _UI_ could be nothing more than a reflection of the user interface. This would solve both of my concerns. It would make it easier to do domain-driven design, because one could instantly translate evolving domain modeling ideas into a working prototype. And it would deliver an expressive, object-oriented user interface for free. Thus was born the idea of Naked Objects.
-pass:[</p></div>]
+Sometime in the late 1990s, it dawned on me that if the domain model really did represent the "ubiquitous language" of the business and those domain objects were behaviorally rich (that is, business logic is encapsulated as methods on the domain objects rather than in procedural scripts on top of them), then the _UI_ could be nothing more than a reflection of the user interface. This would solve both of my concerns.
+It would make it easier to do domain-driven design, because one could instantly translate evolving domain modeling ideas into a working prototype.
+And it would deliver an expressive, object-oriented user interface for free.
+Thus was born the idea of Naked Objects.
+__________________________
-pass:[<div class="extended-quote-attribution"><p>]-- Richard Pawson
-pass:[</p></div>]
-You can learn much more about the pattern in the book, link:http://www.amazon.com/exec/obidos/ISBN=0470844205/[Naked Objects], also freely available to link:http://www.nakedobjects.org/book/[read online]. Richard co-wrote the book with one of Apache Isis' committers, Robert Matthews, who was in turn the author of the Naked Objects Framework for Java (the original codebase of of Apache Isis).
+You can learn much more about the pattern in the book, link:http://www.amazon.com/exec/obidos/ISBN=0470844205/[Naked Objects], also freely available to link:http://www.nakedobjects.org/book/[read online].
+Richard co-wrote the book with one of Apache Isis' committers, Robert Matthews, who was in turn the author of the Naked Objects Framework for Java (the original codebase of of Apache Isis).
You might also want to read Richard's link:resources/core-concepts/Pawson-Naked-Objects-thesis.pdf[PhD on the subject].
[TIP]
====
-One of the external examiners for Richard's PhD was link:http://en.wikipedia.org/wiki/Trygve_Reenskaug[Trygve Reenskaug], who originally formulated the MVC pattern at Xeroc PARC. In his paper, link:http://heim.ifi.uio.no/~trygver/2007/2007.02.13-babyUML.pdf[Baby UML], Reenskaug describes that when implemented the first MVC, "the conventional wisdom in the group was that objects should be visible and tangible, thus bridging the gap between the human brain and the abstract data within the computer." Sound familiar? It's interesting to speculate what might have been if this idea had been implemented back then in the late 70s.
-
-Reenskaug then goes on to say that "this simple and powerful idea failed because ... users were used to seeing [objects] from different perspectives. The visible and tangible object would get very complex if it should be able to show itself and be manipulated in many different ways."
-
-In Apache Isis the responsibility of rendering an object is not the object itself, it is the framework. Rather, the object inspects the object and uses that to decide how to render the object. This is also extensible. In the link:http://www.isisaddons.org[Isis Addons] (non-ASF) the http://github.com/isisaddons/isis-wicket-gmap3[Isis addons' gmap3] wicket extension renders any object with latitude/longitude on a map, while http://github.com/isisaddons/isis-wicket-fullcalendar2[Isis addons' fullcalendar2 wicket extension] renders any object with date(s) on a calendar.
+One of the external examiners for Richard's PhD was link:http://en.wikipedia.org/wiki/Trygve_Reenskaug[Trygve Reenskaug], who originally formulated the MVC pattern at Xeroc PARC.
+In his paper, link:http://heim.ifi.uio.no/~trygver/2007/2007.02.13-babyUML.pdf[Baby UML], Reenskaug describes that when implemented the first MVC, "the conventional wisdom in the group was that objects should be visible and tangible, thus bridging the gap between the human brain and the abstract data within the computer."
+Sound familiar?
+It's interesting to speculate what might have been if this idea had been implemented back then in the late 70s.
+
+Reenskaug then goes on to say that "this simple and powerful idea failed because ... users were used to seeing [objects] from different perspectives.
+The visible and tangible object would get very complex if it should be able to show itself and be manipulated in many different ways."
+
+In Apache Isis the responsibility of rendering an object is not the object itself, it is the framework.
+Rather, the object inspects the object and uses that to decide how to render the object.
+This is also extensible.
+In the link:http://www.isisaddons.org[Isis Addons] (non-ASF) the http://github.com/isisaddons/isis-wicket-gmap3[Isis addons' gmap3] wicket extension renders any object with latitude/longitude on a map, while http://github.com/isisaddons/isis-wicket-fullcalendar2[Isis addons' fullcalendar2 wicket extension] renders any object with date(s) on a calendar.
====
http://git-wip-us.apache.org/repos/asf/isis/blob/cc0eadb2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping.adoc
index 0c8de07..77c96f1 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping.adoc
@@ -5,14 +5,11 @@
:_imagesdir: images/
-Another -- more technical -- way to think about the naked objects pattern is as an _object interface mapper_, or `OIM`. We sometimes use this idea to explain naked objects to a bunch of developers.
+Another -- more technical -- way to think about the naked objects pattern is as an _object interface mapper_, or `OIM`.
+We sometimes use this idea to explain naked objects to a bunch of developers.
Just as an ORM (such as link:http://datanucleus.org[DataNucleus] or link:http://hibernate.org[Hibernate]) maps domain entities to a database, you can think of the naked objects pattern as representing the concept of mapping domain objects to a user interface.
-This is the way that the link:http://metawidget.org/[MetaWidget] team, in particular Richard Kennard, the primary contributor, likes to describe their tool. MetaWidget has a number of ideas in common with Apache Isis, specifically the runtime generation of a UI for domain objects. You can hear more from Kennard and others on this http://devchat.tv/js-jabber/150-jsj-oims[Javascript Jabber podcast].
-
-[NOTE]
-====
-We compare Apache Isis' with MetaWidget xref:ugfun.adoc#_ugfun_core-concepts_principles_apache-isis-vs_metawidget[here].
-====
-
+This is the way that the link:http://metawidget.org/[MetaWidget] team, in particular Richard Kennard, the primary contributor, likes to describe their tool.
+MetaWidget has a number of ideas in common with Apache Isis (we compare Apache Isis' with MetaWidget xref:ugfun.adoc#_ugfun_core-concepts_principles_apache-isis-vs_metawidget[here]), in particular the runtime generation of a UI for domain objects.
+You can hear more from Kennard and others on this http://devchat.tv/js-jabber/150-jsj-oims[Javascript Jabber podcast].
http://git-wip-us.apache.org/repos/asf/isis/blob/cc0eadb2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles.adoc
index 548d473..26794c4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles.adoc
@@ -5,12 +5,19 @@
:_imagesdir: images/
+
+Apache Isis is primarily aimed at custom-built "enterprise" applications.
+The UI provided by the xref:ugvw.adoc#[Wicket viewer] is intended to be usable by domain experts, typically end-users within the organization.
+The REST API exposed by the xref:ugvro.adoc#[RestfulObjects viewer] allows custom apps to be developed -- eg using Angular or similar -- for use by those requiring more guidance; typically end-users outside of the organization.
This section describes some of the core principles and values that the framework aims to honour and support.
-The first of these relate to how we believe your domain application should be written: it should be decoupled, testable and so on). Others relate to the implementation of the framework itself.
-The section concludes by contrasting the framework with some other open source frameworks commonly used.
-include::_ugfun_core-concepts_principles_your-apps.adoc[leveloffset=+1]
-include::_ugfun_core-concepts_principles_isis-itself.adoc[leveloffset=+1]
-include::_ugfun_core-concepts_principles_apache-isis-vs.adoc[leveloffset=+1]
+include::_ugfun_core-concepts_principles_build-not-buy.adoc[leveloffset=+1]
+include::_ugfun_core-concepts_principles_for-the-long-term.adoc[leveloffset=+1]
+
+// TODO: incomplete
+//include::_ugfun_core-concepts_principles_testable.adoc[leveloffset=+1]
+//include::_ugfun_core-concepts_principles_lego-blocks.adoc[leveloffset=+1]
+//include::_ugfun_core-concepts_principles_isis-itself.adoc[leveloffset=+1]
+
http://git-wip-us.apache.org/repos/asf/isis/blob/cc0eadb2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_apache-isis-vs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_apache-isis-vs.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_apache-isis-vs.adoc
deleted file mode 100644
index ab7c0b2..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_apache-isis-vs.adoc
+++ /dev/null
@@ -1,16 +0,0 @@
-[[_ugfun_core-concepts_principles_apache-isis-vs]]
-= Apache Isis vs ...
-: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/
-
-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_principles_apache-isis-vs_mvc-server-side-frameworks.adoc[leveloffset=+1]
-include::_ugfun_core-concepts_principles_apache-isis-vs_cqrs.adoc[leveloffset=+1]
-include::_ugfun_core-concepts_principles_apache-isis-vs_event-sourcing.adoc[leveloffset=+1]
-include::_ugfun_core-concepts_principles_apache-isis-vs_metawidget.adoc[leveloffset=+1]
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/cc0eadb2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_apache-isis-vs_cqrs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_apache-isis-vs_cqrs.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_apache-isis-vs_cqrs.adoc
deleted file mode 100644
index fc3b6fd..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_apache-isis-vs_cqrs.adoc
+++ /dev/null
@@ -1,28 +0,0 @@
-[[_ugfun_core-concepts_principles_apache-isis-vs_cqrs]]
-= vs CQRS
-: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 CQRS architectural pattern (it stands for "Command Query Responsbility Separation") is the idea that the domain objects that mutate the state of the system - to which commands are sent and which then execute - should be separated from the mechanism by which the state of the system is queried (rendered). The former are sometimes called the "write (domain) model", the latter the "read model".
-
-In the canonical version of this pattern there are separate datastores. The commands act upon a command/write datastore. The data in this datastore is then replicated in some way to the query/read datastore, usually denormalized or otherwise such that it is easy to query. CQRS advocates recommend using very simple (almost naive) technology for the query/read model; it should be a simple projection of the query datastore. Complexity instead lives elsewhere: business logic in the command/write model, and in the transformation logic betweeen the command/write and read/query datastores. In particular, there is no requirement for the two datastores to use the same technology: one might be an RDBMS while the other a NoSQL datastore or even datawarehouse.
-
-In most implementations the command and query datastores are _not_ updated in the same transaction; instead there is some sort of replication mechanism. This also means that the query datastore is eventually consistent rather than always consistent; there could be a lag of a few seconds before it is updated. This means in turn that CQRS implementations require mechanisms to cater for offline query datastores; usually some sort of event bus.
-
-The CQRS architecture's extreme separation of responsibilities can result in a lot of boilerplate. Any given domain concept, eg `Customer`, must be represented both in the command/write model and also in the query/read model. Each business operation upon the command model is reified as a command object, for example `PlaceOrderCommand`.
-
-Comparing CQRS to Apache Isis, the most obvious difference is that Apache Isis does not separate out a command/write model from a query/read model, and there is usually just a single datastore. But then again, having a separate read model just so that the querying is very straightforward is pointless with Apache Isis because, of course, Isis provides the UI "for free".
-
-There are other reasons though why a separate read model might make sense, such as to precompute particular queries, or against denormalized data. In these cases Apache Isis can often provide a reasonable alternative, namely to map domain entities against RDBMS views, either materialized views or dynamic. In such cases there is still only a single physical datastore, and so transactional integrity is retained.
-
-Or, the CQRS architecture can be more fully implemented with Apache Isis by introducing a separate read model, synchronized using the xref:rgsvc.adoc#_rgsvc_api_PublishingService[`PublishingService`], or using xref:rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[subscribers] on the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`]. One can then use xref:ugbtb.adoc#_ugbtb_view-models[view models] to surface the data in the external read datastore.
-
-With respect to commands, Apache Isis does of course support the xref:rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] which allows each business action to be reified into a `Command`. However, names are misleading here: Apache Isis' commands are relatively passive, merely recording the intent of the user to invoke some operation. In a CQRS architecture, though, commands take a more active role, locating and acting upon the domain objects. More significantly, in CQRS each command has its own class, such as `PlaceOrderCommand`, instantiated by the client and then executed. With Apache Isis, though, the end-user merely invokes the `placeOrder(...)` action upon the domain object; the framework itself creates the `Command` as a side-effect of this.
-
-In CQRS the commands correspond to the business logic that mutates the system. Whether this logic is part of the command class (`PlaceOrderCommand`) or whether that command delegates to methods on the domain object is an implementation detail; but it certainly is common for the business logic to be wholly within the command object and for the domain object to be merely a data holder of the data within the command/write datastore.
-
-In Apache Isis this same separation of business logic from the underlying data can be accomplished most straightforwardly using xref:ugbtb.adoc#_ugbtb_decoupling_mixins[mixins] or xref:ugfun.adoc#_ugfun_how-tos_contributed-members[contributions]. In the UI (surfaced by the xref:ugvw.adoc#[Wicket viewer]) or in the REST API (surfaced by the xref:ugvro.adoc#[RestfulObjects viewer]) the behaviour appears to reside on the domain object; however the behaviour actually resides on separate classes and is mixed in (like a trait) only at runtime.
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/cc0eadb2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_apache-isis-vs_event-sourcing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_apache-isis-vs_event-sourcing.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_apache-isis-vs_event-sourcing.adoc
deleted file mode 100644
index caa338f..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_apache-isis-vs_event-sourcing.adoc
+++ /dev/null
@@ -1,19 +0,0 @@
-[[_ugfun_core-concepts_principles_apache-isis-vs_event-sourcing]]
-= vs Event Sourcing
-: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:_ugfun_core-concepts_principles_apache-isis-vs_cqrs[CQRS architecture], discussed above, is often combined with _Event Sourcing_ pattern, though they are separate ideas.
-
-With event sourcing, each business operation emits a domain event (or possibly events) that allow other objects in the system to act accordingly. For example, if a customer places an order then this might emit the `OrderPlacedEvent`. Most significantly, the subscribers to these events can include the datastore itself; the state of the system is in effect a transaction log of every event that has occurred since "the beginning of time": it is sometimes called an event store. With CQRS, this event datastore corresponds to the command/write datastore (the query/read datastore is of course derived from the command datastore).
-
-Although it might seem counter-intuitive to be able store persistent state in this way (as a souped up "transaction log"), the reality is that with modern compute capabilities make it quite feasible to replay many 10s/100s of thousands of events in a second. And the architecture supports some interesting use cases; for example it becomes quite trivial to rewind the system back to some previous point in time.
-
-When combined with CQRS we see a command that triggers a business operation, and an event that results from it. So, a `PlaceOrderCommand` command can result in an `OrderPlacedEvent` event. A subscriber to this event might then generate a further command to act upon some other system (eg to dispatch the system). Note that the event might be dispatched and consumed in-process or alternatively this might occur out-of-process. If the latter, then the subscriber will operate within a separate transaction, meaning the usual eventual consistency concerns and also compensating actions if a rollback is required. CQRS/event sourcing advocates point out - correctly that this is just how things are in the "real world" too.
-
-In Apache Isis every business action (and indeed, property and collection) emits domain events through the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] , and can optionally also be published through the xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`]. The former are dispatched and consumed in-process and within the same transaction, and for this reason the xref:rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[subscribers] can also veto the events. The latter are intended for out-of-process consumption; the (non-ASF) http://github.com/isisaddons/isis-module-publishing[Isis addons' publishing] and http://github.com/isisaddons/isis-module-publishmq[Isis addons' publishmq] modules provide implementations for dispatching either through a RDBMS database table, or directly through to an link:http://camel.apache.org[ActiveMQ] message queue (eg wired up to link:http://camel.apache.org[Apache Camel] event bus).
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/cc0eadb2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_apache-isis-vs_metawidget.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_apache-isis-vs_metawidget.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_apache-isis-vs_metawidget.adoc
deleted file mode 100644
index dce3954..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_apache-isis-vs_metawidget.adoc
+++ /dev/null
@@ -1,16 +0,0 @@
-[[_ugfun_core-concepts_principles_apache-isis-vs_metawidget]]
-= vs MetaWidget
-: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/
-
-
-MetaWidget (mentioned xref:ugfun.adoc#_ugfun_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping[earlier] has a number of ideas in common with Apache Isis, specifically the runtime generation of a UI for domain objects. And like Apache Isis, MetaWidget builds its own metamodel of the domain objects and uses this to render the object.
-
-However, there is a difference in philosophy in that MW is not a full-stack framework and does not (in their words) try to "own the UI". Rather they support a huge variety of UI technologies and allow the domain object to be rendered in any of them.
-
-In contrast, Apache Isis is full-stack and does generate a complete UI; we then allow you to customize or extend this UI (as per the various link:http://www.isisaddons.org[Isis Addons] (non-ASF), and we also provide a full REST API through the xref:ugvro.adoc#[Restful Objects viewer]
-
-Also, it's worth noting that MetaWidget does have an elegant pipeline architecture, with APIs to allow even its metamodel to be replaced. It would be feasible and probably quite straightforward to use Apache Isis' own metamodel as an implementation of the MetaWidget API. This would allow MetaWidget to be able to render an Apache Isis domain application.
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/cc0eadb2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_apache-isis-vs_mvc-server-side-frameworks.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_apache-isis-vs_mvc-server-side-frameworks.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_apache-isis-vs_mvc-server-side-frameworks.adoc
deleted file mode 100644
index fbdf9f0..0000000
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_apache-isis-vs_mvc-server-side-frameworks.adoc
+++ /dev/null
@@ -1,19 +0,0 @@
-[[_ugfun_core-concepts_principles_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 (scheduled for JavaEE 8) 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.adoc#_ugvw_extending[extending Apache Isis' Wicket viewer] or by writing a bespoke UI leveraging the REST (hypermedia) API automatically exposed by xref: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.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/cc0eadb2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_build-not-buy.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_build-not-buy.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_build-not-buy.adoc
new file mode 100644
index 0000000..1bb8282
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_build-not-buy.adoc
@@ -0,0 +1,51 @@
+[[_ugfun_core-concepts_principles_build-not-buy]]
+= Why Build instead of Buy?
+: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/
+
+
+
+
+Buying packaged software makes sense for statutory requirements, such as payroll or general ledger, or document management/retrieval.
+But (we argue) it makes much less sense to buy packaged software for the systems that support the core business: the software should fit the business, not the other way around.
+
+Packaged software suffers from the problem of both having doing "too much" and "not enough":
+
+* it does "too much" because it will have features that are not required by your business.
+These extra unnecessary features make the system difficult to learn and use.;
+
+* but it may also do "too little" because there may be crucial functionality not supported by the software.
+
+The diagram below illustrates the dichotomy:
+
+.build-vs-buy
+image::{_imagesdir}core-concepts/philosophy/build-vs-buy.png[width="800px",link="{_imagesdir}core-concepts/philosophy/build-vs-buy.png"]
+
+What happens in this case is that end-users -- needing some sort of solution for their particular business problem -- will end up using unused fields to store the information they need.
+We end up with no correlation between the fields definitions and the values stored therein, sometimes with the datatypes not even matching.
+Any business rules pertaining to this extra data have to be enforced manually by the users, rather than by the system.
+The end result is a system even more complicated to learn and use, with the quality of the data held within it degrading as end users inevitably make mistakes in using it.
+
+There are other benefits too for building rather than buying.
+Packaged software is almost always sold with a support package, the cover of which can vary enormously.
+At one end of the spectrum the support package ("bronze", say) will amount to little more than the ability to raise bug reports and to receive maintenance patches.
+At the other end ("platinum"?), the support package might provide the ability to influence the direction of the development of the product, perhaps specific features missing by the business.
+
+Even so, the more widely used is the software package, the less chance of getting it changed.
+Does anyone reading this think they could get a new feature added (or removed) from Microsoft Word, for example?
+
+Here's another reason why you should build, and not buy, the software supporting your core business domain.
+Although most packaged software is customisable to a degree, there is always a limit to what can be customised.
+The consequence is that the business is forced to operate according to the way in which the software requires.
+
+This might be something as relatively innocuous as imposing its own terminology onto the business, meaning that the end-users must mentally translate concepts in order to use the software.
+But it might impose larger constraints on the business; some packaged software (we carefully mention no names) is quite notorious for this
+
+If your business is using the same software as your competitor, then obviously there's no competitive advantage to be gained.
+And if your competitor has well-crafted custom software, then your business will be at a competitive __dis__advantage.
+
+So, our philosophy is that custom software -- for your core business domain -- is the way to go.
+Let's now look more closely at the types of custom applications you can consider building with the framework.
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/cc0eadb2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_for-the-long-term.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_for-the-long-term.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_for-the-long-term.adoc
new file mode 100644
index 0000000..c53a18b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_for-the-long-term.adoc
@@ -0,0 +1,66 @@
+[[_ugfun_core-concepts_principles_for-the-long-term]]
+= For the long-term
+: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/
+
+
+
+Enterprise applications tend to stick around a long time; a business' core domains don't tend to change all that often.
+What this means in turn is that the application needs to be maintainable, so that it is as easy to modify and extend when it's 10 years old as when it was first written.
+
+That's a tall order for any application to meet, and realistically it _can_ only be met if the application is modular.
+Any application that lacks a coherent internal structure will ultimately degrade into an unmaintable "big ball of mud", and the development team's velocity/capacity to make changes will reduce accordingly.
+
+Apache Isis' architecture allows the internal structure to be maintained in two distinct ways.
+
+* first, the naked objects pattern acts as a "firewall", ensuring that any business logic in the domain layer doesn't leak out into the presentation layer (it can't, because the developer doesn't write any controllers/views).
+
+* second, the framework's provides various features (discussed in more detail below) to allow the different modules _within_ the domain layer to interact with each in a decoupled fashion.
+
+The diagram below illustrates this:
+
+.decoupled applications
+image::{_imagesdir}core-concepts/philosophy/decoupled-applications.png[width="800px",link="{_imagesdir}core-concepts/philosophy/decoupled-applications.png"]
+
+Here, the presentation layer (xref:ugvw.adoc#[Wicket UI] or xref:ugvro.adoc#[REST API]) is handled by the framework, while the developer focusses on just the domain layer.
+The framework encourages splitting this functionality into modules; each such module has its counterpart (typically tables within a given RDBMS database schema) within the persistence layer.
+
+This architecture means that it's impossible for business logic to leach out into the adjacent presentation layer because the developer doesn't (can't) write any code for presentation layer.
+We in effect have a "firewall" between the two layers.
+
+To support the business domain being split into separate modules, the framework provides various features, the most important of which are:
+
+* dependency injection of services +
++
+Both xref:rgsvc.adoc#[framework-defined domain services] and application-defined services (eg repositories and factories) are injected everywhere, using the regular xref:rgant.adoc#_rgant-Inject[`@javax.inject.Inject`] annotation.
+
+* mixins allow functionality defined in one module to appear (in the UI) to be provided by some other module. +
++
+For example, a _Document_ module might allow `Document` objects to be attached to any arbitrary domain object (such as `Order` or `Customer`) in other modules.
+A mixin would allow the UI for a `Customer` to also display these attached ``Document``s, even though the _Customer_ module would have no knowledge of/dependency on the _Workflow_ module.
+
+* internal event bus allows modules to influence other modules. +
++
+A good example is supporting what (in an RDBMS we would call) referential integrity.
+Suppose the _Customer_ module has a `Customer` object and a `EmailAddress` object, with a customer having a collection of email addresses.
+A _Communications_ module might then use those email addresses to create ``EmailCommunication``s. +
+ +
+If the _Customer_ module wants to delete an `EmailAddress` then the _Communications_ module will probably want to veto this because they are "in use" by those ``EmailCommunication``s.
+Or, it might conceivably perform a cascade delete of all associated communications.
+ Either way, the _Communications_ module receives an internal event representing the intention to delete the `EmailAddress`.
+ It can then act accordingly, either vetoing the interaction or performing the cascade delete.
+ The _Customer_ module for its part does not know anything about this other module.
+
+For those cases where a module needs to interact with other modules but does not know about their implementations, the module can either define its own link:https://en.wikipedia.org/wiki/Service_provider_interface[SPI] domain services or it can define custom domain events and fire them.
+This technique is also used extensively by the framework itself.
+ For example, the xref:rgsvc.adoc#_rgsvc_spi_AuditerService[`AuditerService`] SPI enables custom auditing, and the xref:rgsvc.adoc#_rgsvc_spi_PublisherService[`PublisherService`] SPI enables custom publishing
+
+When building a modular application, it's important to consider the logical layering of the modules: we don't need every module to be completely decoupled from every other.
+The most important requirement is that there are no cyclic dependencies, because otherwise we run the risk of the application degrading into a link:https://en.wikipedia.org/wiki/Big_ball_of_mud["big ball of mud"].
+OO design techniques such as the link:https://en.wikipedia.org/wiki/Dependency_inversion_principle[dependency inversion principle] can be used to any such
+
+[TIP]
+====
+For further discussion on modular monolith's, check out Dan Haywood's link:https://www.infoq.com/articles/monolith-defense-1[pair] of link:https://www.infoq.com/articles/monolith-defense-2[articles] on InfoQ.
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/cc0eadb2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_isis-itself.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_isis-itself.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_isis-itself.adoc
index c2b44fd..1846a7d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_isis-itself.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_isis-itself.adoc
@@ -7,41 +7,6 @@
This section discusses some of the principles and values we apply to the development of the Apache Isis framework itself.
-== Full-stack but Extensible
-
-NOTE: TODO
-
-
-== Focuses on its USP
-
-NOTE: TODO
-
-
-add-ons
-
-* Apache Isis is at heart a metamodel with runtime, and coordinates interations using an AOP set of principles
-* Apache Isis vs Isis Addons
-* Apache Isis vs Shiro vs DataNucleus
-
-
-
-... all code has legacy in it.... parts of the Isis codebase are well over a decade old; and back then a lot of the JEE technologies that we'd like to be using just didn't exist, so we had to invent the features we required ourselves.
-
-... also, Apache Isis today is more pragmatic than previously
-* a client/server solution, with AWT-based client
-* a HTML browser, Scimpi (JSF-like, but not using JSF), ...
-* security
-* objectstores
-
-We're working hard to remove duplication, reuse existing open source/JEE, and simplify.
-
-
-The areas of Apache Isis we consider mature are those that have been developed in support of real-world applications implemented by the committers. Foremost among these is Estatio.
-
-
-Focus on enterprise / line-of-business applications, for use by internal staff.
-
-* problem solvers, not process followers
-
-* view models
+include::_ugfun_core-concepts_principles_isis-itself_full-stack-but-extensible.adoc[leveloffset=+1]
+include::_ugfun_core-concepts_principles_isis-itself_focuses-on-its-usp.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/cc0eadb2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_isis-itself_focuses-on-its-usp.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_isis-itself_focuses-on-its-usp.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_isis-itself_focuses-on-its-usp.adoc
new file mode 100644
index 0000000..c454ba0
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_isis-itself_focuses-on-its-usp.adoc
@@ -0,0 +1,39 @@
+[[_ugfun_core-concepts_principles_isis-itself_focuses-on-its-usp]]
+= Focuses on its USP
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+
+NOTE: TODO
+
+
+add-ons
+
+* Apache Isis is at heart a metamodel with runtime, and coordinates interations using an AOP set of principles
+* Apache Isis vs Isis Addons
+* Apache Isis vs Shiro vs DataNucleus
+
+
+
+... all code has legacy in it.... parts of the Isis codebase are well over a decade old; and back then a lot of the JEE technologies that we'd like to be using just didn't exist, so we had to invent the features we required ourselves.
+
+... also, Apache Isis today is more pragmatic than previously
+* a client/server solution, with AWT-based client
+* a HTML browser, Scimpi (JSF-like, but not using JSF), ...
+* security
+* objectstores
+
+We're working hard to remove duplication, reuse existing open source/JEE, and simplify.
+
+
+The areas of Apache Isis we consider mature are those that have been developed in support of real-world applications implemented by the committers. Foremost among these is Estatio.
+
+
+Focus on enterprise / line-of-business applications, for use by internal staff.
+
+* problem solvers, not process followers
+
+* view models
+
http://git-wip-us.apache.org/repos/asf/isis/blob/cc0eadb2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_isis-itself_full-stack-but-extensible.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_isis-itself_full-stack-but-extensible.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_isis-itself_full-stack-but-extensible.adoc
new file mode 100644
index 0000000..e277575
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_isis-itself_full-stack-but-extensible.adoc
@@ -0,0 +1,12 @@
+[[_ugfun_core-concepts_principles_isis-itself_full-stack-but-extensible]]
+= Full-stack but Extensible
+:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+:_basedir: ../../
+:_imagesdir: images/
+
+
+
+
+NOTE: TODO
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/cc0eadb2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_lego-blocks.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_lego-blocks.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_lego-blocks.adoc
new file mode 100644
index 0000000..9e984a1
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_lego-blocks.adoc
@@ -0,0 +1,16 @@
+[[_ugfun_core-concepts_principles_lego-blocks]]
+= Lego 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/
+
+
+
+
+
+* Reusable building blocks +
++
+Isis addons, catalog.incode.org
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/cc0eadb2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_testable.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_testable.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_testable.adoc
new file mode 100644
index 0000000..23c806b
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_testable.adoc
@@ -0,0 +1,7 @@
+[[_ugfun_core-concepts_principles_testable]]
+= Testable
+: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/
+
+
[3/3] isis git commit: ISIS-1521: sorts out top-level links;
removes some TODOs in ugfun.adoc
Posted by da...@apache.org.
ISIS-1521: sorts out top-level links; removes some TODOs in ugfun.adoc
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/cc0eadb2
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/cc0eadb2
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/cc0eadb2
Branch: refs/heads/master
Commit: cc0eadb2beb0e769a939d47b2cf971b4b64434fa
Parents: 4202292
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Tue Apr 11 14:05:47 2017 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Tue Apr 11 14:05:47 2017 +0100
----------------------------------------------------------------------
adocs/documentation/preview-pdf.sh | 2 +-
.../asciidoc/guides/dg/_images/ditaa-demo.png | Bin 0 -> 5512 bytes
.../guides/dg/_images/graphviz-demo.png | Bin 0 -> 17255 bytes
.../guides/dg/_images/plantuml-demo.png | Bin 0 -> 6965 bytes
.../guides/ugfun/_ugfun_core-concepts.adoc | 9 +-
.../ugfun/_ugfun_core-concepts_add-ons.adoc | 5 +-
.../_ugfun_core-concepts_apache-isis-vs.adoc | 15 ++
...ugfun_core-concepts_apache-isis-vs_cqrs.adoc | 49 ++++
...-concepts_apache-isis-vs_event-sourcing.adoc | 29 +++
...core-concepts_apache-isis-vs_metawidget.adoc | 20 ++
...ache-isis-vs_mvc-server-side-frameworks.adoc | 29 +++
.../_ugfun_core-concepts_building-blocks.adoc | 230 ++++++++-----------
...re-concepts_framework-provided-services.adoc | 12 +-
..._core-concepts_other-deployment-options.adoc | 2 +-
.../ugfun/_ugfun_core-concepts_philosophy.adoc | 1 +
.../_ugfun_core-concepts_philosophy_aop.adoc | 63 +++--
...oncepts_philosophy_domain-driven-design.adoc | 83 +++++--
...cepts_philosophy_hexagonal-architecture.adoc | 27 ++-
..._core-concepts_philosophy_how-eases-ddd.adoc | 35 ++-
...ncepts_philosophy_naked-objects-pattern.adoc | 53 +++--
...bjects-pattern_object-interface-mapping.adoc | 13 +-
.../ugfun/_ugfun_core-concepts_principles.adoc | 17 +-
...core-concepts_principles_apache-isis-vs.adoc | 16 --
...concepts_principles_apache-isis-vs_cqrs.adoc | 28 ---
...rinciples_apache-isis-vs_event-sourcing.adoc | 19 --
...ts_principles_apache-isis-vs_metawidget.adoc | 16 --
...ache-isis-vs_mvc-server-side-frameworks.adoc | 19 --
..._core-concepts_principles_build-not-buy.adoc | 51 ++++
...e-concepts_principles_for-the-long-term.adoc | 66 ++++++
...un_core-concepts_principles_isis-itself.adoc | 39 +---
...inciples_isis-itself_focuses-on-its-usp.adoc | 39 ++++
...s_isis-itself_full-stack-but-extensible.adoc | 12 +
...un_core-concepts_principles_lego-blocks.adoc | 16 ++
...ugfun_core-concepts_principles_testable.adoc | 7 +
...gfun_core-concepts_principles_your-apps.adoc | 39 ----
.../ugfun/_ugfun_faqs_enabling-logging.adoc | 6 +-
.../guides/ugfun/_ugfun_faqs_enhance-only.adoc | 10 +-
...un_faqs_how-run-fixtures-on-app-startup.adoc | 12 +-
...aqs_how-to-handle-void-and-null-results.adoc | 19 +-
...un_faqs_how-to-implement-a-spellchecker.adoc | 3 +-
..._ugfun_faqs_i18n-label-in-wicket-viewer.adoc | 10 +-
.../ugfun/_ugfun_faqs_per-user-themes.adoc | 18 +-
.../_ugfun_faqs_restful-image-property.adoc | 4 +-
...faqs_subtype-entity-not-fully-populated.adoc | 42 ++--
.../guides/ugfun/_ugfun_getting-started.adoc | 21 +-
.../core-concepts/philosophy/build-vs-buy.png | Bin 0 -> 34337 bytes
.../core-concepts/philosophy/build-vs-buy.pptx | Bin 0 -> 63121 bytes
.../philosophy/decoupled-applications.png | Bin 0 -> 22512 bytes
.../philosophy/decoupled-applications.pptx | Bin 0 -> 63199 bytes
.../guides/ugvro/_ugvro_hints-and-tips.adoc | 6 +-
adocs/documentation/src/main/asciidoc/js/app.js | 2 +-
adocs/template/document.html.erb | 8 +-
52 files changed, 749 insertions(+), 473 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/cc0eadb2/adocs/documentation/preview-pdf.sh
----------------------------------------------------------------------
diff --git a/adocs/documentation/preview-pdf.sh b/adocs/documentation/preview-pdf.sh
index 618efcd..73ff28c 100644
--- a/adocs/documentation/preview-pdf.sh
+++ b/adocs/documentation/preview-pdf.sh
@@ -1,2 +1,2 @@
#!/usr/bin/env bash
-mvn compile -f pom.xml && mvn compile -o && python -m webbrowser -t http://localhost:4000 && pushd target/site && python -m http.server 4000 && popd
+mvn compile -o -f pom-pdf.xml && mvn compile -o && python -m webbrowser -t http://localhost:4000 && pushd target/site && python -m http.server 4000 && popd
http://git-wip-us.apache.org/repos/asf/isis/blob/cc0eadb2/adocs/documentation/src/main/asciidoc/guides/dg/_images/ditaa-demo.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_images/ditaa-demo.png b/adocs/documentation/src/main/asciidoc/guides/dg/_images/ditaa-demo.png
new file mode 100644
index 0000000..810c36a
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/_images/ditaa-demo.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/cc0eadb2/adocs/documentation/src/main/asciidoc/guides/dg/_images/graphviz-demo.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_images/graphviz-demo.png b/adocs/documentation/src/main/asciidoc/guides/dg/_images/graphviz-demo.png
new file mode 100644
index 0000000..527839e
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/_images/graphviz-demo.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/cc0eadb2/adocs/documentation/src/main/asciidoc/guides/dg/_images/plantuml-demo.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_images/plantuml-demo.png b/adocs/documentation/src/main/asciidoc/guides/dg/_images/plantuml-demo.png
new file mode 100644
index 0000000..e10ce69
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/dg/_images/plantuml-demo.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/cc0eadb2/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 e0204ce..e9819a0 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
@@ -6,14 +6,15 @@
This introductory chapter should give you a good about what Apache Isis actually *is*: the fundamental ideas and principles that it builds upon, how it compares with other frameworks, what the fundamental building blocks are for actually writing an Isis application, and what services and features the framework provides for you to leverage in your own apps.
-[TIP]
-====
-Parts of this chapter have been adapted from Dan Haywood's 2009 book, 'Domain Driven Design using Naked Objects'. We've also added some new insights and made sure the material we've used is relevant to Apache Isis.
-====
+Parts of this chapter have been adapted from Dan Haywood's 2009 book, 'Domain Driven Design using Naked Objects'.
+We've also added some new insights and made sure the material we've used is relevant to Apache Isis.
include::_ugfun_core-concepts_philosophy.adoc[leveloffset=+1]
include::_ugfun_core-concepts_principles.adoc[leveloffset=+1]
+
+include::_ugfun_core-concepts_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]
http://git-wip-us.apache.org/repos/asf/isis/blob/cc0eadb2/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
index a173af9..cfae890 100644
--- 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
@@ -5,11 +5,12 @@
:_imagesdir: images/
-The link:http://www.isisaddons.org[Isis Addons] website provides a number of reusable modules and other extensions for Apache Isis. This chapter focuses just on the modules, all of which have a name of the form `isis-module-xxx`.
+The link:http://www.isisaddons.org[Isis Addons] website provides a number of reusable modules and other extensions for Apache Isis.
+This chapter focuses just on the modules, all of which have a name of the form `isis-module-xxx`.
[WARNING]
====
-Note that Isis addons, while maintained by Apache Isis committers, are not part of the ASF.
+Note that Isis Addons, although maintained by Apache Isis committers, are not part of the ASF.
====
http://git-wip-us.apache.org/repos/asf/isis/blob/cc0eadb2/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
new file mode 100644
index 0000000..8dea746
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs.adoc
@@ -0,0 +1,15 @@
+[[_ugfun_core-concepts_apache-isis-vs]]
+= Apache Isis vs ...
+: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/
+
+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_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/cc0eadb2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_cqrs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_cqrs.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_cqrs.adoc
new file mode 100644
index 0000000..ea526e0
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_cqrs.adoc
@@ -0,0 +1,49 @@
+[[_ugfun_core-concepts_apache-isis-vs_cqrs]]
+= vs CQRS
+: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 CQRS architectural pattern (it stands for "Command Query Responsbility Separation") is the idea that the domain objects that mutate the state of the system - to which commands are sent and which then execute - should be separated from the mechanism by which the state of the system is queried (rendered).
+The former are sometimes called the "write (domain) model", the latter the "read model".
+
+In the canonical version of this pattern there are separate datastores.
+The commands act upon a command/write datastore.
+The data in this datastore is then replicated in some way to the query/read datastore, usually denormalized or otherwise such that it is easy to query.
+
+CQRS advocates recommend using very simple (almost naive) technology for the query/read model; it should be a simple projection of the query datastore.
+Complexity instead lives elsewhere: business logic in the command/write model, and in the transformation logic betweeen the command/write and read/query datastores.
+In particular, there is no requirement for the two datastores to use the same technology: one might be an RDBMS while the other a NoSQL datastore or even datawarehouse.
+
+In most implementations the command and query datastores are _not_ updated in the same transaction; instead there is some sort of replication mechanism.
+This also means that the query datastore is eventually consistent rather than always consistent; there could be a lag of a few seconds before it is updated.
+This means in turn that CQRS implementations require mechanisms to cater for offline query datastores; usually some sort of event bus.
+
+The CQRS architecture's extreme separation of responsibilities can result in a lot of boilerplate.
+Any given domain concept, eg `Customer`, must be represented both in the command/write model and also in the query/read model.
+Each business operation upon the command model is reified as a command object, for example `PlaceOrderCommand`.
+
+Comparing CQRS to Apache Isis, the most obvious difference is that Apache Isis does not separate out a command/write model from a query/read model, and there is usually just a single datastore.
+But then again, having a separate read model just so that the querying is very straightforward is pointless with Apache Isis because, of course, Isis provides the UI "for free".
+
+There are other reasons though why a separate read model might make sense, such as to precompute particular queries, or against denormalized data.
+In these cases Apache Isis can often provide a reasonable alternative, namely to map domain entities against RDBMS views, either materialized views or dynamic.
+In such cases there is still only a single physical datastore, and so transactional integrity is retained.
+
+Or, the CQRS architecture can be more fully implemented with Apache Isis by introducing a separate read model, synchronized using the xref:rgsvc.adoc#_rgsvc_api_PublishingService[`PublishingService`], or using xref:rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[subscribers] on the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`].
+One can then use xref:ugbtb.adoc#_ugbtb_view-models[view models] to surface the data in the external read datastore.
+
+With respect to commands, Apache Isis does of course support the xref:rgsvc.adoc#_rgsvc_spi_CommandService[`CommandService`] which allows each business action to be reified into a `Command`.
+However, names are misleading here: Apache Isis' commands are relatively passive, merely recording the intent of the user to invoke some operation.
+In a CQRS architecture, though, commands take a more active role, locating and acting upon the domain objects.
+More significantly, in CQRS each command has its own class, such as `PlaceOrderCommand`, instantiated by the client and then executed.
+With Apache Isis, though, the end-user merely invokes the `placeOrder(...)` action upon the domain object; the framework itself creates the `Command` as a side-effect of this.
+
+In CQRS the commands correspond to the business logic that mutates the system.
+Whether this logic is part of the command class (`PlaceOrderCommand`) or whether that command delegates to methods on the domain object is an implementation detail; but it certainly is common for the business logic to be wholly within the command object and for the domain object to be merely a data holder of the data within the command/write datastore.
+
+In Apache Isis this same separation of business logic from the underlying data can be accomplished most straightforwardly using xref:ugbtb.adoc#_ugbtb_decoupling_mixins[mixins] or xref:ugfun.adoc#_ugfun_how-tos_contributed-members[contributions].
+In the UI (surfaced by the xref:ugvw.adoc#[Wicket viewer]) or in the REST API (surfaced by the xref:ugvro.adoc#[RestfulObjects viewer]) the behaviour appears to reside on the domain object; however the behaviour actually resides on separate classes and is mixed in (like a trait) only at runtime.
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/cc0eadb2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_event-sourcing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_event-sourcing.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_event-sourcing.adoc
new file mode 100644
index 0000000..4b7fd58
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_event-sourcing.adoc
@@ -0,0 +1,29 @@
+[[_ugfun_core-concepts_apache-isis-vs_event-sourcing]]
+= vs Event Sourcing
+: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:_ugfun_core-concepts_principles_apache-isis-vs_cqrs[CQRS architecture], discussed above, is often combined with _Event Sourcing_ pattern, though they are separate ideas.
+
+With event sourcing, each business operation emits a domain event (or possibly events) that allow other objects in the system to act accordingly.
+For example, if a customer places an order then this might emit the `OrderPlacedEvent`.
+Most significantly, the subscribers to these events can include the datastore itself; the state of the system is in effect a transaction log of every event that has occurred since "the beginning of time": it is sometimes called an event store.
+With CQRS, this event datastore corresponds to the command/write datastore (the query/read datastore is of course derived from the command datastore).
+
+Although it might seem counter-intuitive to be able store persistent state in this way (as a souped up "transaction log"), the reality is that with modern compute capabilities make it quite feasible to replay many 10s/100s of thousands of events in a second.
+And the architecture supports some interesting use cases; for example it becomes quite trivial to rewind the system back to some previous point in time.
+
+When combined with CQRS we see a command that triggers a business operation, and an event that results from it.
+So, a `PlaceOrderCommand` command can result in an `OrderPlacedEvent` event. A subscriber to this event might then generate a further command to act upon some other system (eg to dispatch the system).
+Note that the event might be dispatched and consumed in-process or alternatively this might occur out-of-process.
+If the latter, then the subscriber will operate within a separate transaction, meaning the usual eventual consistency concerns and also compensating actions if a rollback is required.
+CQRS/event sourcing advocates point out -- correctly -- that this is just how things are in the "real world" too.
+
+In Apache Isis every business action (and indeed, property and collection) emits domain events through the xref:rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`], and can optionally also be published through the xref:rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`].
+The former are dispatched and consumed in-process and within the same transaction, and for this reason the xref:rgcms.adoc#_rgcms_classes_super_AbstractSubscriber[subscribers] can also veto the events.
+The latter are intended for out-of-process consumption; the (non-ASF) http://github.com/isisaddons/isis-module-publishing[Isis addons' publishing] and http://github.com/isisaddons/isis-module-publishmq[Isis addons' publishmq] modules provide implementations for dispatching either through a RDBMS database table, or directly through to an link:http://camel.apache.org[ActiveMQ] message queue (eg wired up to link:http://camel.apache.org[Apache Camel] event bus).
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/cc0eadb2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_metawidget.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_metawidget.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_metawidget.adoc
new file mode 100644
index 0000000..02fa963
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_metawidget.adoc
@@ -0,0 +1,20 @@
+[[_ugfun_core-concepts_apache-isis-vs_metawidget]]
+= vs MetaWidget
+: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/
+
+
+MetaWidget (mentioned xref:ugfun.adoc#_ugfun_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping[earlier] has a number of ideas in common with Apache Isis, specifically the runtime generation of a UI for domain objects.
+And like Apache Isis, MetaWidget builds its own metamodel of the domain objects and uses this to render the object.
+
+However, there is a difference in philosophy in that MW is not a full-stack framework and does not (in their words) try to "own the UI".
+Rather they support a huge variety of UI technologies and allow the domain object to be rendered in any of them.
+
+In contrast, Apache Isis is full-stack and does generate a complete UI; we then allow you to customize or extend this UI (as per the various link:http://www.isisaddons.org[Isis Addons] (non-ASF), and we also provide a full REST API through the xref:ugvro.adoc#[Restful Objects viewer]
+
+Also, it's worth noting that MetaWidget does have an elegant pipeline architecture, with APIs to allow even its metamodel to be replaced.
+It would be feasible and probably quite straightforward to use Apache Isis' own metamodel as an implementation of the MetaWidget API.
+This would allow MetaWidget to be able to render an Apache Isis domain application.
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/cc0eadb2/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
new file mode 100644
index 0000000..81933df
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_mvc-server-side-frameworks.adoc
@@ -0,0 +1,29 @@
+[[_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.adoc#_ugvw_extending[extending Apache Isis' Wicket viewer] or by writing a bespoke UI leveraging the REST (hypermedia) API automatically exposed by xref: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.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/cc0eadb2/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
index 7c0d7f2..a3680ad 100644
--- 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
@@ -9,79 +9,67 @@ In this section we run through the main building blocks that make up an Apache I
[[__ugfun_core-concepts_building-blocks_metamodel]]
== A MetaModel
-At its core, Apache Isis is a metamodel that is built at runtime from the domain classes (eg `Customer.java`), along
-with optional supporting metadata (eg `Customer.layout.json`).
+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.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).
+The contents of this metamodel is inferred from the Java classes discovered on the classpath: the entities and supporting services, as well the members of those classes.
+The detail of the metamodel is generally explicit, usually represented by Java annotations such as `@Title` or `@Action`.
+Notably the metamodel is xref:ugbtb.adoc#_ugbtb_programming-model[extensible]; it is possible to teach Apache Isis new programming conventions/rules (and conversely to remove those that are built in).
-Most of the annotations recognized by the framework are defined by the Apache Isis framework itself. For example the
-`@Title` annotation - which identifies how the framework should derive a human-readable label for each rendered
-domain object - is part of the `org.apache.isis.applib.annotations` package. However the framework also recognizes
-certain other JEE annotations such as `@javax.inject.Inject` (used for dependency injection).
+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=...)`.
+The framework uses DataNucleus for its persistence mechanism.
+This is an ORM that implements the JDO and JPA APIs, and which can map domain objects either to an RDBMS or to various NoSQL objectstores such as MongoDB or Neo4J.
+Apache Isis recognizes a number of the JDO annotations such as `@javax.jdo.annotations.Column(allowsNull=...)`.
In addition, the framework builds up the metamodel for each domain object using
-xref:ugfun.adoc#_ugfun_object-layout[layout hints], such as `Customer.layout.json`. These provide metadata such as
-grouping elements of the UI together, using multi-column layouts, and so on. The layout file can be modified while the
-application is still running, and are picked up automatically; a useful way to speed up feedback.
+xref:ugfun.adoc#_ugfun_object-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. We also expect to generalize support for `.layout.json` to be able to read such metadata from other
-sources.
+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.adoc#[Wicket viewer]'s UI.
-
-Domain objects can also delegate to domain services; domain services are automatically injected into every other domain
-object; this includes domain entities as well as other services. This injection of domain services into entities is
-significant: it allows business logic to be implemented in the domain entities, rather than have it "leach away" into
-supporting service layers. Said another way: it is the means by which Apache Isis helps you avoid the anaemic
-domain model anti-pattern.
-
-As well as domain entities - mapped to a datastore - Apache Isis also supports *view models*. End users interact with
-view models in the same way as a domain entity, indeed they are unlikely to distinguish one from the other. However
-view models are _not_ mapped to the underlying database, rather they represent some aggregation of state from one or
-more underlying entities. Their state is serialized and recreated from their internal identifier; this identifier is
-visible as the object's URL in the xref:ugvw.adoc#[Wicket viewer] or
-xref:ugvro.adoc#[RestfulObjects viewer].
-
-There's no need though for the view model to aggregate the state of regular domain entities. A view model could also
-be used as a proxy for some externally managed entity, accessed over a web service or REST API; it could even be a
-representation of state held in-memory (such as user preferences, for example).
-
-There are also several types of domain services. Most easily described are those domain services (discussed above)
-that are represented as the menu actions on top-level menu bars. Another variation are *contributed services* - domain
-services that contribute behaviour or (derived) state to entities/view models. Finally domain services may also
-simply provide additional non-UI functionality; an example being to perform an address geocoding lookup against the
-google-maps API.
-
-Also worth mentioning: domain services can also be either singletons (discussed above) or request-scoped; the latter
-being annotated with `@javax.enterprise.context.RequestScoped`. An example of the request-scoped service is the
-xref:rgsvc.adoc#_rgsvc_api_Scratchpad[`Scratchpad`] service, for sharing arbitrary data between multiple objects.
-
-The final type of domain object is the *mixin*. These are similar to contributed services in that they also contribute (or rather,
-mixin) both behaviour or (derived) state to entities/view models. However, they provide a more control over contributed services,
-with a cleaner programming model similar to traits found in other languages.
+Most domain objects that the end-user interacts with are *domain entities*, such as `Customer`, `Order`, `Product` and so on.
+These are persistent objects and which are mapped to a database (usually relational), using JDO/DataNucleus annotations.
+From the end-user's perspective the UI displays a single domain object per page; they can then inspect and modify its state, and navigate to related objects.
+
+The next type of domain object to discuss is *domain services*.
+These are (usually) singleton stateless services that provide additional functionality.
+The behaviour of these services is rendered in various ways, though the most obvious is as the menu actions on the top-level menu bars in the xref:ugvw.adoc#[Wicket viewer]'s UI.
+
+Domain objects can also delegate to domain services; domain services are automatically injected into every other domain object; this includes domain entities as well as other services.
+This injection of domain services into entities is significant: it allows business logic to be implemented in the domain entities, rather than have it "leach away" into
+supporting service layers.
+Said another way: it is the means by which Apache Isis helps you avoid the anaemic domain model anti-pattern.
+
+As well as domain entities -- mapped to a datastore -- Apache Isis also supports *view models*.
+End users interact with view models in the same way as a domain entity, indeed they are unlikely to distinguish one from the other.
+However view models are _not_ mapped to the underlying database, rather they represent some aggregation of state from one or more underlying entities.
+Their state is serialized and recreated from their internal identifier; this identifier is visible as the object's URL in the xref:ugvw.adoc#[Wicket viewer] or xref:ugvro.adoc#[RestfulObjects viewer].
+
+There's no need though for the view model to aggregate the state of regular domain entities.
+A view model could also be used as a proxy for some externally managed entity, accessed over a web service or REST API; it could even be a representation of state held in-memory (such as user preferences, for example).
+
+There are also several types of domain services.
+Most easily described are those domain services (discussed above) that are represented as the menu actions on top-level menu bars.
+Another variation are *contributed services*: domain services that contribute behaviour or (derived) state to entities/view models.
+Finally domain services may also simply provide additional non-UI functionality; an example being to perform an address geocoding lookup against the google-maps API.
+
+Also worth mentioning: domain services can also be either singletons (discussed above) or request-scoped; the latter being annotated with `@javax.enterprise.context.RequestScoped`.
+An example of the request-scoped service is the xref:rgsvc.adoc#_rgsvc_api_Scratchpad[`Scratchpad`] service, for sharing arbitrary data between multiple objects.
+
+The final type of domain object is the *mixin*.
+These are similar to contributed services in that they also contribute (or rather, mixin) both behaviour or (derived) state to entities/view models.
+However, they provide a more control over contributed services, with a cleaner programming model similar to traits found in other languages.
The diagram below summarizes the various types of domain object:
@@ -90,33 +78,29 @@ image::{_imagesdir}core-concepts/building-blocks/types-of-domain-object.png[widt
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. +
+* *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
+* *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.
+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.
+* *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
+* finally, *domain services*` are annotated with `@DomainService(nature=...)` where the nature is either `VIEW_MENU_ONLY` (for domain services whose actions appear on the top-level menu bars), or `VIEW_CONTRIBUTIONS_ONLY` (for domain services whose actions are contributed to entities or view models), or `DOMAIN` (for domain services whose
functionality is simply for other domain objects to invoke programmatically).
+
It is also possible to specify a nature of simply `VIEW`, this combining `VIEW_MENU_ONLY` and `VIEW_CONTRIBUTIONS_ONLY`.
-This is in fact the default, useful for initial prototyping. A final nature is `VIEW_REST_ONLY` which is for domain
-services whose functionality is surfaced only by the xref:ugvro.adoc#[RestfulObjects viewer].
+This is in fact the default, useful for initial prototyping.
+A final nature is `VIEW_REST_ONLY` which is for domain services whose functionality is surfaced only by the xref:ugvro.adoc#[RestfulObjects viewer].
-Worth emphasising is that domain entities and view models hold state, whereas domain services are generally
-stateless. If a domain service does hold state (eg the `Scratchpad` service noted above) then it should be
-`@RequestScoped` so that this state is short-lived and usable only within a single request.
+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.
@@ -131,15 +115,13 @@ Every domain object in Apache Isis consists of (at most) three types of members:
* 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.
+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).
+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:
@@ -176,16 +158,14 @@ 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.
+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.
+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:
@@ -201,33 +181,28 @@ 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.
+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.
+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.
+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 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).
+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.
+We introduce view models here because they do get mentioned quite often within the users and reference guide.
+However, we do consider them a more advanced topic; we generally recommend that you build your applications from the domain layer up, rather than from the view model down.
For further discussion on view models, see xref:ugbtb.adoc#_ugbtb_view-models[this topic].
@@ -237,9 +212,11 @@ For further discussion on view models, see xref:ugbtb.adoc#_ugbtb_view-models[th
[[__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 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.
+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.
@@ -252,9 +229,11 @@ NOTE: TODO
.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.
+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.
+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.
****
@@ -265,8 +244,7 @@ In Apache Isis these are all implemented as domain services. Indeed, it is quit
NOTE: TODO
-For more information, see xref:ugbtb.adoc#_ugbtb_decoupling_contributions[this topic on contribution]s, and
-xref:ugbtb.adoc#_ugbtb_decoupling_mixins[this topic on mixin]s.
+For more information, see xref:ugbtb.adoc#_ugbtb_decoupling_contributions[this topic on contribution]s, and xref:ugbtb.adoc#_ugbtb_decoupling_mixins[this topic on mixin]s.
@@ -287,26 +265,25 @@ NOTE: TODO; see xref:rgcms.adoc#_rgcms_classes_uievent[UI event] classes.
[[__ugfun_core-concepts_building-blocks_oid]]
== OIDs
-As well as defining a xref:ugfun.adoc#__ugfun_core-concepts_building-blocks_metamodel[metamodel] of the structure (domain
-classes) of its domain objects, Apache Isis also manages the runtime instances of said domain objects.
+As well as defining a xref:ugfun.adoc#__ugfun_core-concepts_building-blocks_metamodel[metamodel] of the structure (domain classes) of its domain objects, Apache Isis also manages the runtime instances of said domain objects.
-When a domain entity is recreated from the database, the framework keeps track of its identity through an "OID": an
-object identifier. Fundamentally this is a combination of its type (domain class), along with an identifier. You can think
-of it as its "primary key", except across all domain entity types.
+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.
+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.
+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.
+* the information within an OID could be converted into a barcode, and stamped onto a PDF form.
+When the PDF is scanned by the mail room, the barcode could be read to attach the correspondence to the relevant domain object.
* as a handle to any object in an audit record, as used by xref:rgsvc.adoc#_rgsvc_spi_AuditerService[`AuditerService`] or xref:rgsvc.adoc#_rgsvc_spi_AuditingService[`AuditingService`] (the latter deprecated);
@@ -320,13 +297,12 @@ to persist published action invocations
xref:ugvw.adoc#[Wicket viewer]
use the oid tuple to look up, render and allow the user to interact with domain objects.
-Although the exact content of an OID should be considered opaque by domain objects, it is possible for domain objects
-to obtain OIDs. These are represented as `Bookmark`s, obtained from the
-xref:rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`]. Deep links meanwhile can be obtained from
-the xref:rgant.adoc#_rgant-DeepLinkService[`@DeepLinkService`].
+Although the exact content of an OID should be considered opaque by domain objects, it is possible for domain objects to obtain OIDs.
+These are represented as `Bookmark`s, obtained from the xref:rgsvc.adoc#_rgsvc_api_BookmarkService[`BookmarkService`].
+Deep links meanwhile can be obtained from the xref:rgant.adoc#_rgant-DeepLinkService[`@DeepLinkService`].
-OIDs can also be converted into XML format, useful for integration scenarios. The
-xref:rgcms.adoc#_rgcms_schema-common[common schema] XSD defines the `oidDto` complex type for precisely this purpose.
+OIDs can also be converted into XML format, useful for integration scenarios.
+The xref:rgcms.adoc#_rgcms_schema-common[common schema] XSD defines the `oidDto` complex type for precisely this purpose.
@@ -336,5 +312,3 @@ xref:rgcms.adoc#_rgcms_schema-common[common schema] XSD defines the `oidDto` com
NOTE: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/cc0eadb2/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
index 73258b6..f4558b8 100644
--- 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
@@ -5,11 +5,11 @@
:_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).
+Most framework domain services are API: they exist to provide support functionality to the application's domain objects and services.
+In this case an implementation of the service will be available, either by Apache Isis itself or by Isis Addons (non ASF).
-Some framework domain services are SPI: they exist primarily so that the application can influence the framework's
-ehaviour. In these cases there is (usually) no default implementation; it is up to the application to provide an
-implementation.
+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:
@@ -63,12 +63,12 @@ Bookmarks and Mementos:
Layout and UI Management:
-* xref:rgsvc.adoc#_rgsvc_api_HomePageProviderService[`HomePageProviderService`]
-* xref:rgsvc.adoc#_rgsvc_api_LayoutService[`LayoutService`]
* xref:rgsvc.adoc#_rgsvc_spi_GridLoaderService[`GridLoaderService`] (SPI)
* xref:rgsvc.adoc#_rgsvc_spi_GridService[`GridService`] (SPI)
* xref:rgsvc.adoc#_rgsvc_spi_GridSystemService[`GridSystemService`] (SPI)
+* xref:rgsvc.adoc#_rgsvc_api_HomePageProviderService[`HomePageProviderService`]
* xref:rgsvc.adoc#_rgsvc_spi_HintStore[`HintStore`] (SPI)
+* xref:rgsvc.adoc#_rgsvc_api_LayoutService[`LayoutService`]
* xref:rgsvc.adoc#_rgsvc_spi_RoutingService[`RoutingService`] (SPI)
* xref:rgsvc.adoc#_rgsvc_spi_UrlEncodingService[`UrlEncodingService`] (SPI)
http://git-wip-us.apache.org/repos/asf/isis/blob/cc0eadb2/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
index d9d96b6..3aef8d4 100644
--- 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
@@ -57,7 +57,7 @@ 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 AngularJS or some other RIA technology such as Flex, JavaFX, Silverlight
+For example, using Angular or some other RIA technology such as Flex, JavaFX, Silverlight
* to enable integration between systems +
+
http://git-wip-us.apache.org/repos/asf/isis/blob/cc0eadb2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy.adoc
index 23a3224..d0bdf52 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy.adoc
@@ -14,6 +14,7 @@ include::_ugfun_core-concepts_philosophy_hexagonal-architecture.adoc[leveloffset
include::_ugfun_core-concepts_philosophy_aop.adoc[leveloffset=+1]
+// TODO
// include::_ugfun_core-concepts_philosophy_dci.adoc[leveloffset=+1]
include::_ugfun_core-concepts_philosophy_how-eases-ddd.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/cc0eadb2/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_aop.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_aop.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_aop.adoc
index 9c85456..db37fec 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_aop.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_aop.adoc
@@ -5,32 +5,61 @@
:_imagesdir: images/
-Although not a book about object modelling, Evans' "Domain Driven Design" does use object orientation as its primary modelling tool; while xref:ugfun.adoc#_ugfun_core-concepts_philosophy_naked-objects-pattern[naked objects pattern] very much comes from an OO background (it even has 'object' in its name); Richard Pawson lists Alan Kay as a key influence.
+Although not a book about object modelling, Evans' "Domain Driven Design" does use object orientation as its primary modelling tool; while xref:ugfun.adoc#_ugfun_core-concepts_philosophy_naked-objects-pattern[naked objects pattern] very much comes from an OO background (it even has 'object' in its name).
+Richard Pawson -- the originator of Naked Objects pattern -- lists Alan Kay as a key influence.
-It's certainly true that to develop an Apache Isis application you will need to have good object oriented modelling skills. But given that all the mainstream languages for developing business systems are object oriented (Java, C#, Ruby), that's not such a stretch.
+It's certainly true that to develop an Apache Isis application you will need to have good object oriented modelling skills.
+But given that all the mainstream languages for developing business systems are object oriented (Java, C#, Ruby), that's not such a stretch.
+
+However, what you'll also find as you write your applications is that in some ways an Isis application is more aspect-oriented than it is object oriented.
+Given that aspect-orientation -- as a programming paradigm at least -- hasn't caught on, that statement probably needs unpacking a little.
-However, what you'll also find as you write your applications is that in some ways an Isis application is more aspect-oriented than it is object oriented. Given that aspect-orientation -- as a programming paradigm at least -- hasn't caught on, that statement probably needs unpacking a little.
== AOP Concepts
-Aspect-orientation, then, is a different way of decomposing your application, by treating _cross-cutting concerns_ as a first-class citizen. The canonical (also rather boring) example of a cross-cutting concern is that of logging (or tracing) all method calls. An aspect can be written that will weave in some code (a logging statement) at specified points in the code).
+Aspect-orientation, then, is a different way of decomposing your application, by treating _cross-cutting concerns_ as a first-class citizen.
+The canonical (also rather boring) example of a cross-cutting concern is that of logging (or tracing) all method calls.
+An aspect can be written that will weave in some code (a logging statement) at specified points in the code).
+
+This idea sounds rather abstract, but what it really amounts to is the idea of interceptors.
+When one method calls another the AOP code is called in first.
+This is actually then one bit of AOP that is quite mainstream; DI containers such as Spring provide aspect orientation in supporting annotations such as `@Transactional` or `@Secured` to java beans.
-This idea sounds rather abstract, but what it really amounts to is the idea of interceptors. When one method calls another the AOP code is called in first. This is actually then one bit of AOP that is quite mainstream; DI containers such as Spring provide aspect orientation in supporting annotations such as `@Transactional` or `@Secured` to java beans.
+Another aspect (so to speak!) of aspect-oriented programming has found its way into other programming languages, that of a mix-in or trait.
+In languages such as Scala these mix-ins are specified statically as part of the inheritance hierarchy, whereas with AOP the binding of a trait to some other class/type is done without the class "knowing" that additional behaviour is being mixed-in to it.
-Another aspect (ahem!) of aspect-oriented programming has found its way into other programming languages, that of a mix-in or trait. In languages such as Scala these mix-ins are specified statically as part of the inheritance hierarchy, whereas with AOP the binding of a trait to some other class/type is done without the class "knowing" that additional behaviour is being mixed-in to it.
== Realization within Apache Isis
What has all this to do with Apache Isis, then?
-Well, a different way to think of the naked objects pattern is that the visualization of a domain object within a UI is a cross-cutting concern. By following certain very standard programming conventions that represent the _Apache Isis Programming Model_ (POJOs plus annotations), the framework is able to build a metamodel and from this can render your domain objects in a standard generic fashion. That's a rather more interesting cross-cutting concern than boring old logging!
-
-Isis also draws heavily on the AOP concept of interceptors. Whenever an object is rendered in the UI, it is filtered with respect to the user's permissions. That is, if a user is not authorized to either view or perhaps modify an object, then this is applied transparently by the framework. The http://github.com/isisaddons/isis-module-security[Isis addons' security] module, mentioned previously, provides a rich user/role/permissions subdomain to use out of the box; but you can integrate with a different security mechanism if you have one already.
-
-Another example of interceptors are the http://github.com/isisaddons/isis-module-command[Isis addons' command] and http://github.com/isisaddons/isis-module-audit[Isis addons' audit] modules. The command module captures every user interaction that modifies the state of the system (the "cause" of a change) while the audit module captures every change to every object (the "effect" of a change). Again, this is all transparent to the user.
-
-Apache Isis also has an internal event bus (you can switch between an underlying implementation of Gauva or Axon). A domain event is fired whenever an object is interacted with, and this allows any subscribers to influence the operation (or even veto it). This is a key mechanism in ensuring that Isis applications are maintainable, and we discuss it in depth in the section on xref:ugbtb.adoc#_ugbtb_decoupling[Decoupling]. But fundamentally its relying on this AOP concept of interceptors.
-
-Finally, Isis also a feature that is akin to AOP mix-ins. A "contributed action" is one that is implemented on a domain service but that appears to be a behaviour of rendered domain object. In other words, we can dissociate behaviour from data. That's not always the right thing to do of course. In Richard Pawson's description of the xref:ugfun.adoc#_ugfun_core-concepts_philosophy_naked-objects-pattern[naked objects pattern] he talks about "behaviourally rich" objects, in other words where the business functionality encapsulated the data. But on the other hand sometimes the behaviour and data structures change at different rates. The link:http://en.wikipedia.org/wiki/Single_responsibility_principle[single responsibility principle] says we should only lump code together that changes at the same rate. Apache Isis' support for contributions (not only contributed actions, but also contributed properties and contributed collections) enables this. And again, to loop back to the to
pic of this section, it's an AOP concept that being implemented by the framework.
-
-The nice thing about aspect orientation is that for the most part you can ignore these cross-cutting concerns and - at least initially at least - just focus on implementing your domain object. Later when your app starts to grow and you start to break it out into smaller modules, you can leverage Apache Isis' AOP support for (xref:ugbtb.adoc#_ugbtb_decoupling_mixins[mixins]), (xref:ugbtb.adoc#_ugbtb_decoupling_contributions[contributions]) and interceptors (the xref:ugbtb.adoc#_ugbtb_decoupling_event-bus[event bus]) to ensure that your codebase remains maintainable.
\ No newline at end of file
+Well, a different way to think of the naked objects pattern is that the visualization of a domain object within a UI is a cross-cutting concern.
+By following certain very standard programming conventions that represent the _Apache Isis Programming Model_ (POJOs plus annotations), the framework is able to build a metamodel and from this can render your domain objects in a standard generic fashion.
+That's a rather more interesting cross-cutting concern than boring old logging!
+
+Apache Isis also draws heavily on the AOP concept of interceptors.
+Whenever an object is rendered in the UI, it is filtered with respect to the user's permissions.
+That is, if a user is not authorized to either view or perhaps modify an object, then this is applied transparently by the framework.
+The link:http://github.com/isisaddons/isis-module-security[Isis addons' security] module, mentioned previously, provides a rich user/role/permissions subdomain to use out of the box; but you can integrate with a different security mechanism if you have one already.
+
+Another example of interceptors are the http://github.com/isisaddons/isis-module-command[Isis addons' command] and http://github.com/isisaddons/isis-module-audit[Isis addons' audit] modules.
+The command module captures every user interaction that modifies the state of the system (the "cause" of a change) while the audit module captures every change to every object (the "effect" of a change).
+Again, this is all transparent to the user.
+
+Apache Isis also has an internal event bus (you can switch between an underlying implementation of Gauva or Axon).
+A domain event is fired whenever an object is interacted with, and this allows any subscribers to influence the operation (or even veto it).
+This is a key mechanism in ensuring that Isis applications are maintainable, and we discuss it in depth in the section on xref:ugbtb.adoc#_ugbtb_decoupling[Decoupling].
+But fundamentally its relying on this AOP concept of interceptors.
+
+Finally, Isis also a feature that is akin to AOP mix-ins.
+A "contributed action" is one that is implemented on a domain service but that appears to be a behaviour of rendered domain object.
+In other words, we can dissociate behaviour from data.
+That's not always the right thing to do of course.
+In Richard Pawson's description of the xref:ugfun.adoc#_ugfun_core-concepts_philosophy_naked-objects-pattern[naked objects pattern] he talks about "behaviourally rich" objects, in other words where the business functionality encapsulated the data.
+But on the other hand sometimes the behaviour and data structures change at different rates.
+The link:http://en.wikipedia.org/wiki/Single_responsibility_principle[single responsibility principle] says we should only lump code together that changes at the same rate.
+Apache Isis' support for contributions (not only contributed actions, but also contributed properties and contributed collections) enables this.
+And again, to loop back to the topic of this section, it's an AOP concept that being implemented by the framework.
+
+The nice thing about aspect orientation is that for the most part you can ignore these cross-cutting concerns and - at least initially at least - just focus on implementing your domain object.
+Later when your app starts to grow and you start to break it out into smaller modules, you can leverage Apache Isis' AOP support for (xref:ugbtb.adoc#_ugbtb_decoupling_mixins[mixins]), (xref:ugbtb.adoc#_ugbtb_decoupling_contributions[contributions]) and interceptors (the xref:ugbtb.adoc#_ugbtb_decoupling_event-bus[event bus]) to ensure that your codebase remains maintainable.
\ No newline at end of file