You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2015/11/02 19:35:51 UTC
[07/12] isis git commit: ISIS-1195: updating docs (general
introductory articles)
ISIS-1195: updating docs (general introductory articles)
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/1dad19b9
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/1dad19b9
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/1dad19b9
Branch: refs/heads/master
Commit: 1dad19b989d55143bd212f85c55bba6b2133f853
Parents: 3693daa
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Mon Nov 2 10:03:35 2015 +0000
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Mon Nov 2 14:36:21 2015 +0000
----------------------------------------------------------------------
.../_ug_core-concepts_building-blocks.adoc | 150 ++++++++++++++++---
...oncepts_philosophy_domain-driven-design.adoc | 4 +-
...core-concepts_principles_apache-isis-vs.adoc | 24 +--
...concepts_principles_apache-isis-vs_cqrs.adoc | 28 ++++
...rinciples_apache-isis-vs_event-sourcing.adoc | 19 +++
.../_ug_core-concepts_principles_your-apps.adoc | 38 ++---
.../building-blocks/types-of-domain-object.png | Bin 0 -> 30851 bytes
.../building-blocks/types-of-domain-object.pptx | Bin 0 -> 64342 bytes
.../src/main/asciidoc/guides/ug.adoc | 19 +--
9 files changed, 210 insertions(+), 72 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/1dad19b9/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_building-blocks.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_building-blocks.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_building-blocks.adoc
index 180ab7c..3c6589d 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_building-blocks.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_building-blocks.adoc
@@ -4,36 +4,143 @@
:_basedir: ../
:_imagesdir: images/
-NOTE: TODO
+In this section we run through the main building blocks that make up an Apache Isis application.
-## A MetaModel with Explicit and Inferred Semantics
+[[_ug_core-concepts_building-blocks_metamodel]]
+## A MetaModel
-NOTE: TODO
+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`).
-* use of annotations
-** reuse JEE annotations where possible
-* layout hints are overridable, to avoid restarting the app/speed up feedback
+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:ug.adoc#_ug_extending_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).
-## Objects & Services
+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(allowNulls=...)`.
-NOTE: TODO
+In addition, the framework builds up the metamodel for each domain object using
+xref:rg.adoc#_rg_object-layout[layout hints], such as `Customer.layout.json`. These provide metadata such as
+grouping elements of the UI together, using multi-column layouts, and so on. The layout file can be modified while the
+application is still running, and are picked up automatically; a useful way to speed up feedback.
+
+[TIP]
+====
+At the time of writing Apache Isis only recognizes and supports the JDO API, though we expect JPA to be supported
+in the future. We also expect to generalize support for `.layout.json` to be able to read such metadata from other
+sources.
+====
+
+
+[[_ug_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:ug.adoc#_ug_wicket-viewer[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:ug.adoc#_ug_wicket-viewer[Wicket viewer] or
+xref:ug.adoc#_ug_restfulobjects-viewer[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 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:rg.adoc#_rg_services-api_manpage-Scratchpad[`Scratchpad`] service, for sharing arbitrary data between multiple objects.
+
+The final type of domain object is mixins. These are similar to contributed services in that they also contribute (or rather,
+mixin) both behaviour or (derived) state to entities/view models. However, they provide a more control over contributed services,
+with a cleaner programming model similar to traits found in other languages.
+
+The diagram below summarizes the various types of domain object:
+
+image::{_imagesdir}core-concepts/building-blocks/types-of-domain-object.png[width="860px",link="{_imagesdir}core-concepts/building-blocks/types-of-domain-object.png"]
-* domain model
-** domain objects
-*** domain entity
-*** view model
-** domain service
-** value type
-Anything else can be (should be) ignored by annotating with `@Programmatic`.
+The Apache Isis programming model offers some equivalent ways
+... todo
-## Properties, Collections and Actions
+
+[[_ug_core-concepts_building-blocks_objects-members]]
+## Object Members
+
+Every domain object in Apache Isis consists of these three types of members: properties, collections and actions. Some (eg domain services and mixins) only contain
NOTE: TODO
+For example, with:
+
+[source,java]
+----
+public class Customer
+ private String firstName;
+ public String getFirstName() { return firstName; }
+ public void setFirstName(String firstName) { this.firstName = firstName; }
+ ...
+}
+----
+
+the framework infers the `Customer` domain entity, which in turn has a `firstName` string _property_.
+
+Similarly, from:
+
+[source,java]
+----
+public class Customer
+ private SortedSet<Order> orders = new TreeSet<Order>();
+ public SortedSet<Order> getOrders() { return orders; }
+ public void setOrders(SortedSet<Order> orders) { this.orders = orders; }
+ ...
+}
+----
+
+the framework infers the `orders` _collection_.
+
+Finally:
+
+[source,java]
+----
+public class Customer
+ public Customer placeOrder(Product p, int quantity) { ... }
+ ...
+}
+----
+
+corresponds to the `placeOrder` _action_.
+
+
+
## Domain Entities vs View Models
@@ -43,6 +150,7 @@ NOTE: TODO
+[[_ug_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.
@@ -68,20 +176,22 @@ In Apache Isis these are all implemented as domain services. Indeed, it is quit
+[[_ug_core-concepts_building-blocks_value-objects]]
## Value Objects (Primitives)
NOTE: TODO
-## Contributions
+[[_ug_core-concepts_building-blocks_mixins-and-contributions]]
+## Mixins & Contributions
NOTE: TODO
-
-## Event Bus
+[[_ug_core-concepts_building-blocks_domain-events]]
+## Domain Events
NOTE: TODO
@@ -89,5 +199,3 @@ NOTE: TODO
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/1dad19b9/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_domain-driven-design.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_domain-driven-design.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_domain-driven-design.adoc
index e132bac..c1cd8c3 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_domain-driven-design.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_domain-driven-design.adoc
@@ -69,9 +69,9 @@ Changing the code means changing the model; refining the model requires a change
****
-Here also the word *design* might mislead; some might again be thinking of design documents and design diagrams. 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.
http://git-wip-us.apache.org/repos/asf/isis/blob/1dad19b9/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs.adoc
index aee2c40..bd8c2c0 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs.adoc
@@ -9,28 +9,8 @@ do they compare to Apache Isis?
include::_ug_core-concepts_principles_apache-isis-vs_mvc-server-side-frameworks.adoc[leveloffset=+1]
-
-
-
-== vs CQRS
-
-NOTE: TODO
-
-== vs Event Sourcing
-
-NOTE: TODO
-
-
-== vs Angular
-
-NOTE: TODO
-
-
-
+include::_ug_core-concepts_principles_apache-isis-vs_cqrs.adoc[leveloffset=+1]
+include::_ug_core-concepts_principles_apache-isis-vs_event-sourcing.adoc[leveloffset=+1]
include::_ug_core-concepts_principles_apache-isis-vs_metawidget.adoc[leveloffset=+1]
-
-== vs OpenXava
-
-NOTE: TODO
http://git-wip-us.apache.org/repos/asf/isis/blob/1dad19b9/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_cqrs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_cqrs.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_cqrs.adoc
new file mode 100644
index 0000000..ceed7a4
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_cqrs.adoc
@@ -0,0 +1,28 @@
+[[_ug_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:rg.adoc#_rg_services-api_manpage-PublishingService[`PublishingService`], or using xref:rg.adoc#_rg_classes_super_manpage-AbstractSubscriber[subscribers] on the xref:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`]. One can then use xref:ug.adoc#_ug_more-advanced_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:rg.adoc#_rg_services-spi_manpage-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:ug.adoc#_ug_more-advanced_decoupling_mixins[mixins] or xref:ug.adoc#_ug_how-tos_contributed-members[contributions]. In the UI (surfaced by the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer]) or in the REST API (surfaced by the xref:ug.adoc#_ug_restfulobjects-viewer[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/1dad19b9/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_event-sourcing.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_event-sourcing.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_event-sourcing.adoc
new file mode 100644
index 0000000..0b0f33c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_apache-isis-vs_event-sourcing.adoc
@@ -0,0 +1,19 @@
+[[_ug_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:_ug_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:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`] , and can optionally also be published through the xref:rg.adoc#_rg_services-spi_manpage-PublishingService[`PublishingService`]. The former are dispatched and consumed in-process and within the same transaction, and for this reason the xref:rg.adoc#_rg_classes_super_manpage-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/1dad19b9/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_your-apps.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_your-apps.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_your-apps.adoc
index 185c697..97d89e4 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_your-apps.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_principles_your-apps.adoc
@@ -5,33 +5,35 @@
:_imagesdir: images/
-NOTE: TODO
+Apache Isis is primarily aimed at custom-built "enterprise" applications. The UI exposed by the xref:ug.adoc#_ug_wicket-viewer[Wicket viewer] is intended to be usable by domain experts, typically end-users within the organization. The REST API exposed by the xref:ug.adoc#_ug_restfulobjects-viewer[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.
-== Decoupled
+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
-Long-term Cost of ownership
+NOTE: TODO - flesh out the following:
-Using:
+* Flexible, "just enough"
-* dependency injection of services
-* OO design techniques, eg dependency inversion principle
-* an in-memory event bus
-* applib
+* Decoupled
-* (no "Big Ball of Mud")
+* Long-term Cost of ownership
+** dependency injection of services
+** OO design techniques, eg dependency inversion principle
+** an in-memory event bus
+** applib
-== Honouring the Single Responsibility Principle
+** (no "Big Ball of Mud")
-NOTE: TODO - behaviourally Complete vs Contributions
+* 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.
-== Testable
-
-NOTE: TODO
-
-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/1dad19b9/adocs/documentation/src/main/asciidoc/guides/images/core-concepts/building-blocks/types-of-domain-object.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/core-concepts/building-blocks/types-of-domain-object.png b/adocs/documentation/src/main/asciidoc/guides/images/core-concepts/building-blocks/types-of-domain-object.png
new file mode 100644
index 0000000..1ec6e18
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/core-concepts/building-blocks/types-of-domain-object.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/1dad19b9/adocs/documentation/src/main/asciidoc/guides/images/core-concepts/building-blocks/types-of-domain-object.pptx
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/images/core-concepts/building-blocks/types-of-domain-object.pptx b/adocs/documentation/src/main/asciidoc/guides/images/core-concepts/building-blocks/types-of-domain-object.pptx
new file mode 100644
index 0000000..c0be2a5
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/guides/images/core-concepts/building-blocks/types-of-domain-object.pptx differ
http://git-wip-us.apache.org/repos/asf/isis/blob/1dad19b9/adocs/documentation/src/main/asciidoc/guides/ug.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/ug.adoc b/adocs/documentation/src/main/asciidoc/guides/ug.adoc
index ff5279c..4d1f4dc 100644
--- a/adocs/documentation/src/main/asciidoc/guides/ug.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/ug.adoc
@@ -21,18 +21,19 @@ The users' guide is _not_ intended as a reference manual; for that see the *xref
include::_ug_core-concepts.adoc[leveloffset=+1]
-include::_ug_getting-started.adoc[leveloffset=+1]
+//include::_ug_getting-started.adoc[leveloffset=+1]
include::_ug_how-tos.adoc[leveloffset=+1]
include::_ug_more-advanced.adoc[leveloffset=+1]
-include::_ug_wicket-viewer.adoc[leveloffset=+1]
-include::_ug_restfulobjects-viewer.adoc[leveloffset=+1]
-include::_ug_security.adoc[leveloffset=+1]
+//include::_ug_wicket-viewer.adoc[leveloffset=+1]
+//include::_ug_restfulobjects-viewer.adoc[leveloffset=+1]
+//include::_ug_security.adoc[leveloffset=+1]
+
+//include::_ug_testing.adoc[leveloffset=+1]
+//include::_ug_deployment.adoc[leveloffset=+1]
+//include::_ug_headless-access.adoc[leveloffset=+1]
+//include::_ug_extending.adoc[leveloffset=+1]
+//include::_ug_troubleshooting.adoc[leveloffset=+1]
-include::_ug_testing.adoc[leveloffset=+1]
-include::_ug_deployment.adoc[leveloffset=+1]
-include::_ug_headless-access.adoc[leveloffset=+1]
-include::_ug_extending.adoc[leveloffset=+1]
-include::_ug_troubleshooting.adoc[leveloffset=+1]