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:52 UTC
[08/12] isis git commit: ISIS-1195: more on introductory sections
ISIS-1195: more on introductory sections
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/2498f828
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/2498f828
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/2498f828
Branch: refs/heads/master
Commit: 2498f8284c58a797b193f8b4d7dc9357450b8583
Parents: 1dad19b
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Mon Nov 2 15:14:16 2015 +0000
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Mon Nov 2 15:14:16 2015 +0000
----------------------------------------------------------------------
.../_ug_core-concepts_building-blocks.adoc | 98 ++++++++++++++++----
...oncepts_philosophy_domain-driven-design.adoc | 2 +-
..._core-concepts_philosophy_how-eases-ddd.adoc | 6 +-
...ncepts_philosophy_naked-objects-pattern.adoc | 2 +-
4 files changed, 87 insertions(+), 21 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/2498f828/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 3c6589d..d7c95d0 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
@@ -43,12 +43,12 @@ 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
+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
+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.
@@ -58,26 +58,28 @@ significant: it allows business logic to be implemented in the domain entities,
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
+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'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.
+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: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,
+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.
@@ -86,18 +88,58 @@ The diagram below summarizes the various types of domain object:
image::{_imagesdir}core-concepts/building-blocks/types-of-domain-object.png[width="860px",link="{_imagesdir}core-concepts/building-blocks/types-of-domain-object.png"]
-The Apache Isis programming model offers some equivalent ways
+The Apache Isis programming model uses annotations to distinguish these object types:
+* *view models* are annotated either with `@DomainObject(nature=VIEW_MODEL)` or using `@ViewModel`. Which is used is
+a matter of personal preference. +
++
+It is also possible to implement the `ViewModel` interface, for finer-grained control.
+
+* *domain entities* that are persisted to the database (as the vast majority will) are annotated with
+`@DomainObject(nature=ENTITY)`. In addition such domain entities are annotated with the JDO/DataNucleus annotation of
+`@javax.jdo.annotations.PersistenceCapable`. +
++
+In addition, if a domain entity is a proxy for state managed in an external system, or merely for some state held
+in-memory, then `@DomainObject(nature=EXTERNAL_ENTITY)` or `@DomainObject(nature=INMEMORY_ENTITY)` can be used.
+
+* *mixins* are annotated either with `@DomainObject(nature=MIXIN)` or using `@Mixin`. As for view models, which is
+used is a matter of personal preference.
+
+* finally, *domain services*` are annotated with `@DomainService(nature=...)` where the nature is either
+`VIEW_MENU_ONLY` (for domain services whose actions appear on the top-level menu bars), or `VIEW_CONTRIBUTIONS_ONLY`
+(for domain services whose actions are contributed to entities or view models), or `DOMAIN` (for domain services whose
+functionality is simply for other domain objects to invoke programmatically).
++
+It is also possible to specify a nature of simply `VIEW`, this combining `VIEW_MENU_ONLY` and `VIEW_CONTRIBUTIONS_ONLY`.
+This is in fact the default, useful for initial prototyping. A final nature is `VIEW_REST_ONLY` which is for domain
+services whose functionality is surfaced only by the xref:ug.adoc#_ug_restfulobjects-viewer[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.
-... todo
[[_ug_core-concepts_building-blocks_objects-members]]
-## Object 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
+Every domain object in Apache Isis consists of (at most) three types of members:
-NOTE: TODO
+* properties, such as a `Customer`'s `firstName
+
+* collections, such as a `Customer`'s `orders` collection of ``Order``s
+
+* actions, such as a `Customer'`s `placeOrder(...)` method.
+
+Some domain objects - specifically domain services and mixins - only have actions. In the case of contributing services
+and mixins these actions can (depending upon their semantics and signatures) be represented as derived properties or
+collections on the entity/view model to which they contribute/mix-in.
+
+
+=== Properties
+
+Properties follow the standard getter/setter pattern, with the return type being a scalar (a value object or another
+entity or view model).
For example, with:
@@ -113,7 +155,12 @@ public class Customer
the framework infers the `Customer` domain entity, which in turn has a `firstName` string _property_.
-Similarly, from:
+
+=== Collections
+
+Collections are also represented by a getter and setter, however the return type is a `Collection` or subtype.
+
+For example, with:
[source,java]
----
@@ -127,7 +174,20 @@ public class Customer
the framework infers the `orders` _collection_.
-Finally:
+[TIP]
+====
+The most commonly used collection type is `java.util.SortedSet`; entities are most commonly mapped to a relational
+database (ie a datastore with set semantics) and we recommend that all entities define a natural ordering so that when
+rendered in the UI they will be ordered "meaningfully" to the end-user.
+====
+
+
+=== Actions
+
+The third type of object member is actions. (To a first approximation), actions are all public methods that do not
+represent properties or collections.
+
+For example:
[source,java]
----
@@ -139,6 +199,12 @@ public class Customer
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.
+====
http://git-wip-us.apache.org/repos/asf/isis/blob/2498f828/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 c1cd8c3..c2c0146 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
@@ -56,7 +56,7 @@ Of the various methodologies that the IT industry has tried, many advocate the p
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.
http://git-wip-us.apache.org/repos/asf/isis/blob/2498f828/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_how-eases-ddd.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_how-eases-ddd.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_how-eases-ddd.adoc
index 29f342b..d2bba65 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_how-eases-ddd.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_how-eases-ddd.adoc
@@ -34,11 +34,11 @@ In Apache Isis, we have a very pure one-to-one correspondence between the domain
-== Abstract models are difficult to represent
+== Model must be understandable
If we are using code as the primary means of expressing the model, then we need to find a way to make this model understandable to the business.
-We could generate _UML_ diagrams and the like from code. That will work for some members of the business community, but not for everyone. Or we could generate a _PDF_ document from Javadoc comments, but comments aren't code and so the document may be inaccurate. Anyway, even if we do create such a document, not everyone will read it.
+We could generate UML diagrams and the like from code. That will work for some members of the business community, but not for everyone. Or we could generate a PDF document from Javadoc comments, but comments aren't code and so the document may be inaccurate. Anyway, even if we do create such a document, not everyone will read it.
A better way to represent the model is to show it in action as a working prototype. As we show in the xref:ug.adoc#_ug_getting-started[Getting Started] section, Apache Isis enables this with ease. Such prototypes bring the domain model to life, engaging the audience in a way that a piece of paper never can.
@@ -47,7 +47,7 @@ Moreover, with Apache Isis prototypes, the domain model will come shining throug
-== Layered architectures are easily compromised
+== Architecture must be robust
_DDD_ rightly requires that 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.
http://git-wip-us.apache.org/repos/asf/isis/blob/2498f828/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_naked-objects-pattern.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_naked-objects-pattern.adoc b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_naked-objects-pattern.adoc
index ba56bdd..70d6690 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_naked-objects-pattern.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ug_core-concepts_philosophy_naked-objects-pattern.adoc
@@ -9,7 +9,7 @@ Apache Isis implements the naked objects pattern, originally formulated by Richa
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>]
-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:[<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>]
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.