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/05/03 16:55:13 UTC
[1/4] isis git commit: ISIS-1133: adocs - hexagonal architecture and
similar.
Repository: isis
Updated Branches:
refs/heads/master 1f2866e04 -> ef1e765c8
ISIS-1133: adocs - hexagonal architecture and similar.
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/359e4afc
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/359e4afc
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/359e4afc
Branch: refs/heads/master
Commit: 359e4afc2e1753c3660496e51cf9dbbf4d952901
Parents: 1f2866e
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Sat May 2 13:33:55 2015 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Sat May 2 13:33:55 2015 +0100
----------------------------------------------------------------------
adocs/documentation/README.md | 2 +-
.../_/deploying-on-the-google-app-engine.adoc | 455 -------------------
.../_user-guide_core-concepts_philosophy.adoc | 323 ++++++-------
...core-concepts_principles_apache-isis-vs.adoc | 16 +-
.../hexagonal-architecture-addons.png | Bin 0 -> 128533 bytes
.../philosophy/hexagonal-architecture.png | Bin 0 -> 85844 bytes
.../philosophy/hexagonal-architecture.pptx | Bin 0 -> 263812 bytes
adocs/template/document.html.erb | 4 +
8 files changed, 156 insertions(+), 644 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/359e4afc/adocs/documentation/README.md
----------------------------------------------------------------------
diff --git a/adocs/documentation/README.md b/adocs/documentation/README.md
index 0e4a930..aa5f761 100644
--- a/adocs/documentation/README.md
+++ b/adocs/documentation/README.md
@@ -76,7 +76,7 @@ To build the documentation locally prior to release, use:
The site will be generated at `target/site/index.html`.
-You could then use a web server such as Python's SimpleHTTPServer to preview (so that all Javascript works correctly). However, instead we recommend using instant preview, described nex.
+You could then use a web server such as Python's SimpleHTTPServer to preview (so that all Javascript works correctly). However, instead we recommend using instant preview, described next.
Instant Rebuild (using Ruby)
http://git-wip-us.apache.org/repos/asf/isis/blob/359e4afc/adocs/documentation/src/main/asciidoc/user-guide/_/deploying-on-the-google-app-engine.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_/deploying-on-the-google-app-engine.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_/deploying-on-the-google-app-engine.adoc
deleted file mode 100644
index b74cbf9..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_/deploying-on-the-google-app-engine.adoc
+++ /dev/null
@@ -1,455 +0,0 @@
-Title: Deploying on the Google App Engine
-
-The Google App Engine (GAE) provides a JDO API, meaning that you can deploy Isis onto GAE using the JDO objectstore.
-
-However, GAE is not an RDBMS, and so there are some limitations that it imposes. This page gathers together various hints, tips and workarounds.
-
-=== Primary Keys and Owned/Unowned Relationships
-
-All entities must have a `@PrimaryKey`. Within GAE, the type of this key matters.
-
-For an entity to be an aggregate root, (ie a root of an GAE entity group), its key must be a `Long`, eg:
-
-Any collection that holds this entity type (eg `ToDoItem#dependencies` holding a collection of `ToDoItem`s) should then be annotated with `@Unowned` (a GAE annotation).
-
-If on the other hand you want the object to be owned (through a 1:m relationship somewhere) by some other root, then use a String:
-
-Note: if you store a relationship with a String key it means that the parent object _owns_ the child, any attempt to change the relationship raise and exception.
-
-=== Custom Types
-
-Currently Isis' `Blob` and `Clob` types and the JODA types (`LocalDate` et al) are _not_ supported in GAE.
-
-Instead, GAE defines a https://developers.google.com/appengine/docs/java/datastore/entities#Properties_and_Value_Types[fixed set of value types], including `BlobKey`. Members of the Isis community have this working, though I haven't seen the code.
-
-The above notwithstanding, Andy Jefferson at DataNucleus tells us:
-
-____
-
-GAE JDO/JPA does support _some_ type conversion, because looking at http://code.google.com/p/datanucleus-appengine/source/browse/trunk/src/com/google/appengine/datanucleus/StoreFieldManager.java#349[StoreFieldManager.java] for any field that is Object-based and not a relation nor Serialized it will call http://code.google.com/p/datanucleus-appengine/source/browse/trunk/src/com/google/appengine/datanucleus/TypeConversionUtils.java#736[TypeConverstionUtils.java] and that looks for a `TypeConverter` (specify `@Extension` with key of "type-converter-name" against a field and value as the `TypeConverter` class) and it should convert it. Similarly when getting the value from the datastore.
-
-____
-
-On further investigation, it seems that the GAE implementation performs a type check on a `SUPPORTED_TYPES` Java set, in `com.google.appengine.api.datastore.DataTypeUtils`:
-
-[source]
-----
-234 if (!supportedTypes.contains(value.getClass())) {
-235 throw new IllegalArgumentException(prefix + value.getClass().getName() + " is not a supported property type.");
-236 }
-----
-
-We still need to try out Andy's recipe, above.
-
-The GAE `BlobKey` issue has been solved; we hope to publish further details (possibly in a blog series).
-
-—-
-
-=== GAE compatible version of `ToDoItem.java`
-
-Is as follows:
-
-[source]
-----
-@javax.jdo.annotations.Queries( {
- @javax.jdo.annotations.Query(
- name="todo_all", language="JDOQL",
- value="SELECT FROM dom.todo.ToDoItem WHERE ownedBy == :ownedBy"),
- @javax.jdo.annotations.Query(
- name="todo_notYetComplete", language="JDOQL",
- value="SELECT FROM dom.todo.ToDoItem WHERE ownedBy == :ownedBy && complete == false"),
- @javax.jdo.annotations.Query(
- name="todo_complete", language="JDOQL",
- value="SELECT FROM dom.todo.ToDoItem WHERE ownedBy == :ownedBy && complete == true"),
- @javax.jdo.annotations.Query(
- name="todo_similarTo", language="JDOQL",
- value="SELECT FROM dom.todo.ToDoItem WHERE ownedBy == :ownedBy && category == :category"),
- @javax.jdo.annotations.Query(
- name="todo_autoComplete", language="JDOQL",
- value="SELECT FROM dom.todo.ToDoItem WHERE ownedBy == :ownedBy && description.startsWith(:description)")
-})
-@javax.jdo.annotations.Version(strategy= VersionStrategy.VERSION_NUMBER, column="VERSION")
-@ObjectType("TODO")
-@Auditable
-@AutoComplete(repository=ToDoItems.class, action="autoComplete")
-@MemberGroups({"General", "Detail"})
-@javax.jdo.annotations.PersistenceCapable
-public class ToDoItem implements Comparable<ToDoItem> {
-// @PrimaryKey
-// @Persistent(valueStrategy = javax.jdo.annotations.IdGeneratorStrategy.IDENTITY)
-// @Extension(vendorName="datanucleus", key="gae.encoded-pk", value="true")
-// private String key;
- @Persistent(valueStrategy=IdGeneratorStrategy.IDENTITY)
- @PrimaryKey
- private Long id;
-
- private static final long ONE_WEEK_IN_MILLIS = 7 * 24 * 60 * 60 * 1000L;
-
- public static enum Category {
- Professional, Domestic, Other;
- }
-
- // {{ Identification on the UI
- public String title() {
- final TitleBuffer buf = new TitleBuffer();
- buf.append(getDescription());
- if (isComplete()) {
- buf.append(" - Completed!");
- } else {
- if (getDueBy() != null) {
- SimpleDateFormat sdf = new SimpleDateFormat("dd-MM-yyyy");
- buf.append(" due by ", sdf.format(getDueBy()));
- }
- }
- return buf.toString();
- }
-
- // }}
-
- // {{ Description
- private String description;
-
- @RegEx(validation = "\\w[@&:\\-\\,\\.\\+ \\w]*")
- // words, spaces and selected punctuation
- @MemberOrder(sequence = "1")
- @DescribedAs("Enter the description")
- public String getDescription() {
- return description;
- }
-
- public void setDescription(final String description) {
- this.description = description;
- }
- // }}
-
- // {{ DueBy (property)
- private Date dueBy;
-
- @javax.jdo.annotations.Persistent
- @MemberOrder(name="Detail", sequence = "3")
- @Optional
- @DescribedAs("Enter the date")
- public Date getDueBy() {
- return dueBy;
- }
-
- public void setDueBy(final Date dueBy) {
- this.dueBy = dueBy;
- }
- public void clearDueBy() {
- setDueBy(null);
- }
- // proposed new value is validated before setting
- public String validateDueBy(final Date dueBy) {
- if (dueBy == null) {
- return null;
- }
- return isMoreThanOneWeekInPast(dueBy) ? "Due by date cannot be more than one week old" : null;
- }
- // }}
-
- // {{ Category
- private Category category;
-
- @MemberOrder(sequence = "2")
- @DescribedAs("Enter the category")
- public Category getCategory() {
- return category;
- }
-
- public void setCategory(final Category category) {
- this.category = category;
- }
- // }}
-
- // {{ OwnedBy (property)
- private String ownedBy;
-
- @Hidden
- // not shown in the UI
- public String getOwnedBy() {
- return ownedBy;
- }
-
- public void setOwnedBy(final String ownedBy) {
- this.ownedBy = ownedBy;
- }
-
- // }}
-
- // {{ Complete (property)
- private boolean complete;
-
- @Disabled
- // cannot be edited as a property
- @MemberOrder(sequence = "4")
- public boolean isComplete() {
- return complete;
- }
-
- public void setComplete(final boolean complete) {
- this.complete = complete;
- }
-
- // {{ Notes (property)
- private String notes;
-
- @Hidden(where=Where.ALL_TABLES)
- @Optional
- @MultiLine(numberOfLines=4)
- @MemberOrder(name="Detail", sequence = "6")
- public String getNotes() {
- return notes;
- }
-
- public void setNotes(final String notes) {
- this.notes = notes;
- }
- // }}
-
- // {{ Attachment (property)
- private BlobKey attachment;
-
- @Persistent
- @Optional
- @MemberOrder(name="Detail", sequence = "7")
- public BlobKey getAttachment() {
- return attachment;
- }
-
- public void setAttachment(final BlobKey attachment) {
- this.attachment = attachment;
- }
- // }}
-
- // {{ Version (derived property)
- @Hidden(where=Where.ALL_TABLES)
- @Disabled
- @MemberOrder(name="Detail", sequence = "99")
- @Named("Version")
- public Long getVersionSequence() {
- if(!(this instanceof PersistenceCapable)) {
- return null;
- }
- PersistenceCapable persistenceCapable = (PersistenceCapable) this;
- final Long version = (Long) JDOHelper.getVersion(persistenceCapable);
- return version;
- }
- public boolean hideVersionSequence() {
- return !(this instanceof PersistenceCapable);
- }
- // }}
-
- // {{ completed (action)
- @Bulk
- @MemberOrder(sequence = "1")
- public ToDoItem completed() {
- setComplete(true);
- return this;
- }
-
- // disable action dependent on state of object
- public String disableCompleted() {
- return complete ? "Already completed" : null;
- }
- // }}
-
- // {{ notYetCompleted (action)
- @MemberOrder(sequence = "2")
- public ToDoItem notYetCompleted() {
- setComplete(false);
- return this;
- }
-
- // disable action dependent on state of object
- public String disableNotYetCompleted() {
- return !complete ? "Not yet completed" : null;
- }
- // }}
-
- // {{ dependencies (Collection)
- @Unowned
- private List<ToDoItem> dependencies = new ArrayList<ToDoItem>();
-
- @Disabled
- @MemberOrder(sequence = "1")
- @Resolve(Type.EAGERLY)
- public List<ToDoItem> getDependencies() {
- return dependencies;
- }
-
- public void setDependencies(final List<ToDoItem> dependencies) {
- this.dependencies = dependencies;
- }
- // }}
-
- // {{ add (action)
- @MemberOrder(name="dependencies", sequence = "3")
- public ToDoItem add(final ToDoItem toDoItem) {
- getDependencies().add(toDoItem);
- return this;
- }
- public String validateAdd(final ToDoItem toDoItem) {
- if(getDependencies().contains(toDoItem)) {
- return "Already a dependency";
- }
- if(toDoItem == this) {
- return "Can't set up a dependency to self";
- }
- return null;
- }
- public List<ToDoItem> choices0Add() {
- return toDoItems.allToDos();
- }
-
- // }}
-
- // {{ remove (action)
- @MemberOrder(name="dependencies", sequence = "4")
- public ToDoItem remove(final ToDoItem toDoItem) {
- getDependencies().remove(toDoItem);
- return this;
- }
- public String disableRemove(final ToDoItem toDoItem) {
- return getDependencies().isEmpty()? "No dependencies to remove": null;
- }
- public String validateRemove(final ToDoItem toDoItem) {
- if(!getDependencies().contains(toDoItem)) {
- return "Not a dependency";
- }
- return null;
- }
- public List<ToDoItem> choices0Remove() {
- return getDependencies();
- }
- // }}
-
- // {{ clone (action)
- @Named("Clone")
- // the name of the action in the UI
- @MemberOrder(sequence = "3")
- // nb: method is not called "clone()" is inherited by java.lang.Object and
- // (a) has different semantics and (b) is in any case automatically ignored
- // by the framework
- public ToDoItem duplicate() {
- return toDoItems.newToDo(getDescription() + " - Copy", getCategory(), getDueBy());
- }
- // }}
-
- // {{ isDue (programmatic)
- @Programmatic
- // excluded from the framework's metamodel
- public boolean isDue() {
- if (getDueBy() == null) {
- return false;
- }
- return !isMoreThanOneWeekInPast(getDueBy());
- }
-
- // }}
-
- // {{ SimilarItems (derived collection)
- @MemberOrder(sequence = "5")
- @NotPersisted
- @Resolve(Type.EAGERLY)
- public List<ToDoItem> getSimilarItems() {
- return toDoItems.similarTo(this);
- }
-
- // }}
-
- // {{ compareTo (programmatic)
- /**
- * by complete flag, then due by date, then description
- */
- // exclude from the framework's metamodel
- @Override
- public int compareTo(final ToDoItem other) {
- if (isComplete() && !other.isComplete()) {
- return +1;
- }
- if (!isComplete() && other.isComplete()) {
- return -1;
- }
- if (getDueBy() == null && other.getDueBy() != null) {
- return +1;
- }
- if (getDueBy() != null && other.getDueBy() == null) {
- return -1;
- }
- if (getDueBy() == null && other.getDueBy() == null || getDueBy().equals(this.getDueBy())) {
- return getDescription().compareTo(other.getDescription());
- }
- return getDueBy().compareTo(getDueBy());
- }
- // }}
-
- // {{ helpers
- private static boolean isMoreThanOneWeekInPast(final Date dueBy) {
- return dueBy.getTime() < Clock.getTime() - ONE_WEEK_IN_MILLIS;
- }
-
- // }}
-
- // {{ filters (programmatic)
- @SuppressWarnings("unchecked")
- public static Filter<ToDoItem> thoseDue() {
- return Filters.and(Filters.not(thoseComplete()), new Filter<ToDoItem>() {
- @Override
- public boolean accept(final ToDoItem t) {
- return t.isDue();
- }
- });
- }
-
- public static Filter<ToDoItem> thoseComplete() {
- return new Filter<ToDoItem>() {
- @Override
- public boolean accept(final ToDoItem t) {
- return t.isComplete();
- }
- };
- }
-
- public static Filter<ToDoItem> thoseOwnedBy(final String currentUser) {
- return new Filter<ToDoItem>() {
- @Override
- public boolean accept(final ToDoItem toDoItem) {
- return Objects.equal(toDoItem.getOwnedBy(), currentUser);
- }
-
- };
- }
-
- public static Filter<ToDoItem> thoseSimilarTo(final ToDoItem toDoItem) {
- return new Filter<ToDoItem>() {
- @Override
- public boolean accept(final ToDoItem eachToDoItem) {
- return Objects.equal(toDoItem.getCategory(), eachToDoItem.getCategory()) &&
- Objects.equal(toDoItem.getOwnedBy(), eachToDoItem.getOwnedBy()) &&
- eachToDoItem != toDoItem;
- }
-
- };
- }
- // }}
-
- // {{ injected: DomainObjectContainer
- @SuppressWarnings("unused")
- private DomainObjectContainer container;
-
- public void setDomainObjectContainer(final DomainObjectContainer container) {
- this.container = container;
- }
- // }}
-
- // {{ injected: ToDoItems
- private ToDoItems toDoItems;
-
- public void setToDoItems(final ToDoItems toDoItems) {
- this.toDoItems = toDoItems;
- }
- // }}
-
-}
-----
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/359e4afc/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy.adoc
index bfd55ac..aa7804e 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy.adoc
@@ -7,190 +7,76 @@ This section describes some of the core ideas and architectural patterns upon wh
== Domain-Driven Design
-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.
+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.
There are two central ideas at the heart of domain-driven design.
-* the *_ubiquitous language_* is about getting the whole team (both domain experts
- and developers) to communicate more transparently using a domain model.
+* the *_ubiquitous language_* is about getting the whole team (both domain experts and developers) to communicate more transparently using a domain model.
-* Meanwhile, *_model-driven design_* is about capturing that model in a
- very straightforward manner in code.
+* Meanwhile, *_model-driven design_* is about capturing that model in a very straightforward manner in code.
Let's look at each in turn.
=== 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.
-
-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.
-
-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.
+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.
+
+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.
+
+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
****
-Build a common language between the domain experts and developers
-by using the concepts of the domain model as the primary means of
-communication. Use the terms in speech, in diagrams, in writing, and when
-presenting.
-
-If an idea cannot be expressed using this set of concepts, then go
-back and extend the model. Look for and remove ambiguities and
-inconsistencies.
+Build a common language between the domain experts and developers by using the concepts of the domain model as the primary means of communication. Use the terms in speech, in diagrams, in writing, and when presenting.
+
+If an idea cannot be expressed using this set of concepts, then go back and extend the model. Look for and remove ambiguities and inconsistencies.
****
+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.
+
+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"?
-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.
-
-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.
-
-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.
+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.
+
+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_).
-
-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. Oft quoted and still true is that 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.
+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.
+
+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.
.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.
+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 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.
-
-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.
+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.
+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. What this book is about is how Naked
-Objects eases that path by applying these central ideas of
-_DDD_ in a very concrete way. So, now would be a good time
-to see how.
+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.
@@ -199,52 +85,29 @@ to see how.
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:[<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.
+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>]
-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:[<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>]
-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:[<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>]
pass:[<div class="extended-quote-attribution"><p>]-- Richard Pawson
pass:[</p></div>]
-pass:[<div class="clear"><p>]
-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 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: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.
@@ -269,16 +132,40 @@ We compare Apache Isis' with MetaWidget <<_vs_metawidget,here>>.
+
+
== Hexagonal Architecture
-Originally described by Alistair Cockburn, the link:http://alistair.cockburn.us/Hexagonal+architecture[Hexagonal Architecture] ...
+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_*:.
[TIP]
====
The hexagonal architecture is also known as the link:http://c2.com/cgi/wiki?PortsAndAdaptersArchitecture:[Ports and Adapters] architecture or (less frequently) as the link:http://jeffreypalermo.com/blog/the-onion-architecture-part-1/[Onion] architecture.
====
+.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*. Isis' viewers act as user-side adapters and use the 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 Isis can be configured to persist using some other JDO implementation, for example Google App Engine.
+
+It's worth extending the hexagonal architecture to show where http://isisaddons.org[Isis Addons] (non-ASF) fit in:
+
+.The hexagonal architecture with Isis addons
+image::{_imagesdir}core-concepts/philosophy/hexagonal-architecture-addons.png[width="700px"]
+
+Here, we can see that the addons provide services both to the Isis framework (for example security, command and auditing) and also to the domain objects (eg tags, excel, settings). Of course, you can also write your own domain services as well, for example to interface with some external CMS system, say.
+
+
+
+
== Aspect Oriented
@@ -298,5 +185,73 @@ IMPORTANT: TODO ... Trygve Reenskaug
+== How Apache Isis eases DDD
+
+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>]
+
+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.
+
+With Apache Isis, though, the ubiquitous language evolves with scarcely any effort at all. For the business experts, the 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.
+
+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.
+
+
+=== Abstract Models Are Difficult to Represent
+
+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.
+
+A better way to represent the model is to show it in action as a working prototype. As we show in the <<_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.
+
+Moreover, with Apache Isis prototypes, the domain model will come shining through. If there are mistakes or misunderstandings in the domain model (inevitable when building any complex system), they will be obvious to all.
+
+
+=== Layered Architectures Are Expensive and Easily Compromised
+
+_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.
+
+.Layered Architecture
+****
+We partition a complex program into layers, with each layer 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.
+****
+
+However, there are two immediate issues. The first is rather obvious: custom coding each of those other layers is an expensive proposition. Picking up on the previous point, this in itself can put the kibosh on using prototyping to represent the model, even if we wanted to do so.
+
+The second issue is more subtle. It takes real skill to ensure the correct separation of concerns between these layers, if indeed you can get an agreement as to what those concerns actually are. Even with the best intentions, it's all too easy for custom-written layers to blur the boundaries and put (for example) validation in the user interface layer when it should belong to the domain layer. At the other extreme, it's quite possible for custom layers to distort or completely subvert the underlying domain model.
+
+Because of Apache Isis' generic _OOUI_s, there's no need to write the other layers of the architecture. Of course, this reduces the development cost. But more than that, there will be no leakage of concerns outside the domain model. All the validation logic *must* be in the domain model because there is nowhere else to put it.
+
+Moreover, although Apache Isis does provide a complete runtime framework, there is no direct coupling of your domain model to the framework. That means it is very possible to take your domain model prototyped in Naked Objects and then deploy it on some other _J(2)EE_ architecture, with a custom _UI_ if you want. Isis guarantees that your domain model is complete.
+
+
+=== Apache Isis extends the reach of DDD
+
+Domain-driven design is often positioned as being applicable only to complex domains; indeed, the subtitle of Evans book is *Tackling Complexity in the Heart of Software*. The corollary is that DDD is overkill for simpler domains. The trouble is that we immediately have to make a choice: is the domain complex enough to warrant a domain-driven approach?
+
+This goes back to the previous point, building and maintaining a *layered architecture*. It doesn't seem cost effective to go to all the effort of a DDD approach if the underlying domain is simple.
+
+However, with Apache Isis, we don't write these other layers, so we don't have to make a call on how complex our domain is. We can start working solely on our domain, even if we suspect it will be simple. If it is indeed a simple domain, then there's no hardship, but if unexpected subtleties arise, then we're in a good position to handle them.
+If you're just starting out writing domain-driven applications, then Apache Isis should significantly ease your journey into applying _DDD_. On the other hand, if you've used _DDD_ for a while, then you should find Isis a very useful new tool in your arsenal.
http://git-wip-us.apache.org/repos/asf/isis/blob/359e4afc/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_principles_apache-isis-vs.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_principles_apache-isis-vs.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_principles_apache-isis-vs.adoc
index 0084a9b..6290e10 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_principles_apache-isis-vs.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_principles_apache-isis-vs.adoc
@@ -3,13 +3,21 @@
:_basedir: ../
:_imagesdir: images/
-IMPORTANT: TODO
+Many other frameworks promise rapid application development and provide automatically generated user interfaces, so how
+do they compare to Apache Isis?
-## vs Spring
+## vs MVC server-side frameworks
-## vs JEE
+Some of most commonly used frameworks today are link:http://www.springframework.org/[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 <<_extending_the_viewer, extending Isis' Wicket viewer>> or by writing a bespoke UI leveraging the REST (hypermedia) API automatically exposed by <<_restful_objects_viewer, 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 Isis' REST API.
+
+Although these frameworks all provide their own ecosystems of extensions, Isis' equivalent http://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. Isis' support is similar. Where Isis differs though is that it enables end-to-end testing without the need for slow and fragile Selenium tests. Instead, Isis provides a "<<_using_the_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.
-## vs Grails
## vs Angular
http://git-wip-us.apache.org/repos/asf/isis/blob/359e4afc/adocs/documentation/src/main/asciidoc/user-guide/images/core-concepts/philosophy/hexagonal-architecture-addons.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/core-concepts/philosophy/hexagonal-architecture-addons.png b/adocs/documentation/src/main/asciidoc/user-guide/images/core-concepts/philosophy/hexagonal-architecture-addons.png
new file mode 100644
index 0000000..af32db1
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/user-guide/images/core-concepts/philosophy/hexagonal-architecture-addons.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/359e4afc/adocs/documentation/src/main/asciidoc/user-guide/images/core-concepts/philosophy/hexagonal-architecture.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/core-concepts/philosophy/hexagonal-architecture.png b/adocs/documentation/src/main/asciidoc/user-guide/images/core-concepts/philosophy/hexagonal-architecture.png
new file mode 100644
index 0000000..d8b28bd
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/user-guide/images/core-concepts/philosophy/hexagonal-architecture.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/359e4afc/adocs/documentation/src/main/asciidoc/user-guide/images/core-concepts/philosophy/hexagonal-architecture.pptx
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/core-concepts/philosophy/hexagonal-architecture.pptx b/adocs/documentation/src/main/asciidoc/user-guide/images/core-concepts/philosophy/hexagonal-architecture.pptx
new file mode 100644
index 0000000..3eb0aad
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/user-guide/images/core-concepts/philosophy/hexagonal-architecture.pptx differ
http://git-wip-us.apache.org/repos/asf/isis/blob/359e4afc/adocs/template/document.html.erb
----------------------------------------------------------------------
diff --git a/adocs/template/document.html.erb b/adocs/template/document.html.erb
index d482250..b23caee 100644
--- a/adocs/template/document.html.erb
+++ b/adocs/template/document.html.erb
@@ -168,6 +168,10 @@
width: 25em;
}
+ #doc-content a {
+ color: #210DDC;
+ }
+
h2 {
margin-top: 100px;
}
[2/4] isis git commit: ISIS-1133: more adocs (philosophy and
architecture section)
Posted by da...@apache.org.
http://git-wip-us.apache.org/repos/asf/isis/blob/b5ee5585/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy_hexagonal-architecture.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy_hexagonal-architecture.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy_hexagonal-architecture.adoc
new file mode 100644
index 0000000..47a05a1
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy_hexagonal-architecture.adoc
@@ -0,0 +1,28 @@
+= Hexagonal Architecture
+: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/
+
+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_*:.
+
+[TIP]
+====
+The hexagonal architecture is also known as the link:http://c2.com/cgi/wiki?PortsAndAdaptersArchitecture:[Ports and Adapters] architecture or (less frequently) as the link:http://jeffreypalermo.com/blog/the-onion-architecture-part-1/[Onion] architecture.
+====
+
+.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*. Isis' viewers act as user-side adapters and use the 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 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/b5ee5585/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy_how-eases-ddd.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy_how-eases-ddd.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy_how-eases-ddd.adoc
new file mode 100644
index 0000000..275c4fb
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy_how-eases-ddd.adoc
@@ -0,0 +1,73 @@
+= How Apache Isis eases DDD
+: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 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>]
+
+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.
+
+With Apache Isis, though, the ubiquitous language evolves with scarcely any effort at all. For the business experts, the 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.
+
+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.
+
+
+
+== Abstract models are difficult to represent
+
+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.
+
+A better way to represent the model is to show it in action as a working prototype. As we show in the <<_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.
+
+Moreover, with Apache Isis prototypes, the domain model will come shining through. If there are mistakes or misunderstandings in the domain model (inevitable when building any complex system), they will be obvious to all.
+
+
+
+
+== Layered architectures are easily compromised
+
+_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.
+
+However, there are two immediate issues. The first is rather obvious: custom coding each of those other layers is an expensive proposition. Picking up on the previous point, this in itself can put the kibosh on using prototyping to represent the model, even if we wanted to do so.
+
+The second issue is more subtle. It takes real skill to ensure the correct separation of concerns between these layers, if indeed you can get an agreement as to what those concerns actually are. Even with the best intentions, it's all too easy for custom-written layers to blur the boundaries and put (for example) validation in the user interface layer when it should belong to the domain layer. At the other extreme, it's quite possible for custom layers to distort or completely subvert the underlying domain model.
+
+Because of Apache Isis' generic __OOUI__s, there's no need to write the other layers of the architecture. Of course, this reduces the development cost. But more than that, there will be no leakage of concerns outside the domain model. All the validation logic *must* be in the domain model because there is nowhere else to put it.
+
+Moreover, although Apache Isis does provide a complete runtime framework, there is no direct coupling of your domain model to the framework. That means it is very possible to take your domain model prototyped in Naked Objects and then deploy it on some other _J(2)EE_ architecture, with a custom _UI_ if you want. Isis guarantees that your domain model is complete.
+
+
+
+
+== Extending the reach of DDD
+
+Domain-driven design is often positioned as being applicable only to complex domains; indeed, the subtitle of Evans book is "Tackling Complexity in the Heart of Software". The corollary is that DDD is overkill for simpler domains. The trouble is that we immediately have to make a choice: is the domain complex enough to warrant a domain-driven approach?
+
+This goes back to the previous point, building and maintaining a layered architecture. It doesn't seem cost effective to go to all the effort of a DDD approach if the underlying domain is simple.
+
+However, with Apache Isis, we don't write these other layers, so we don't have to make a call on how complex our domain is. We can start working solely on our domain, even if we suspect it will be simple. If it is indeed a simple domain, then there's no hardship, but if unexpected subtleties arise, then we're in a good position to handle them.
+
+If you're just starting out writing domain-driven applications, then Apache Isis should significantly ease your journey into applying _DDD_. On the other hand, if you've used _DDD_ for a while, then you should find Isis a very useful new tool in your arsenal.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/b5ee5585/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy_naked-objects-pattern.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy_naked-objects-pattern.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy_naked-objects-pattern.adoc
new file mode 100644
index 0000000..213781e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy_naked-objects-pattern.adoc
@@ -0,0 +1,54 @@
+= Naked Objects Pattern
+: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 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>]
+
+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.
+pass:[</p></div>]
+
+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>]
+
+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>]
+
+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 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: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 http://isisaddons.org[Isis Addons] (non-ASF) the http://github.com/isisaddons/isis-wicket-gmap3}[Isis addons' gmap3 modue] 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.
+====
+
+=== Object Interface Mapping
+
+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 <<_vs_metawidget,here>>.
+====
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/b5ee5585/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_decoupling.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_decoupling.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_decoupling.adoc
new file mode 100644
index 0000000..1d0d476
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_decoupling.adoc
@@ -0,0 +1,13 @@
+= Decoupling
+: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/
+
+IMPORTANT: TODO
+
+This chapter describes how to use Isis' features to ensure that your domain application remains decoupled.
+
+* event bus
+
+* contributed actions/properties/collections
+
http://git-wip-us.apache.org/repos/asf/isis/blob/b5ee5585/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_domain-services.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_domain-services.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_domain-services.adoc
index 1d36441..ef7e4ad 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_domain-services.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_how-tos_domain-services.adoc
@@ -12,3 +12,12 @@ IMPORTANT: TODO
IMPORTANT: TODO
+It's worth extending the <<_hexagonal_architecture, Hexagonal Architecture> to show where domain services -- and in particular the domain services provided by http://isisaddons.org[Isis Addons] (non-ASF) -- fit in:
+
+.The hexagonal architecture with Isis addons
+image::{_imagesdir}how-tos/domain-services/hexagonal-architecture-addons.png[width="700px"]
+
+Here, we can see that the addons provide services both to the Isis framework (for example security, command and auditing) and also - by way of dependency injection - to the domain objects (eg tags, excel, settings). Of course, you can also write your own domain services as well, for example to interface with some external CMS system, say.
+
+The Apache Isis framework also provides a number of in-built domain services.
+
http://git-wip-us.apache.org/repos/asf/isis/blob/b5ee5585/adocs/documentation/src/main/asciidoc/user-guide/images/core-concepts/philosophy/hexagonal-architecture-addons.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/core-concepts/philosophy/hexagonal-architecture-addons.png b/adocs/documentation/src/main/asciidoc/user-guide/images/core-concepts/philosophy/hexagonal-architecture-addons.png
deleted file mode 100644
index af32db1..0000000
Binary files a/adocs/documentation/src/main/asciidoc/user-guide/images/core-concepts/philosophy/hexagonal-architecture-addons.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/isis/blob/b5ee5585/adocs/documentation/src/main/asciidoc/user-guide/images/how-tos/domain-services/hexagonal-architecture-addons.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/how-tos/domain-services/hexagonal-architecture-addons.png b/adocs/documentation/src/main/asciidoc/user-guide/images/how-tos/domain-services/hexagonal-architecture-addons.png
new file mode 100644
index 0000000..af32db1
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/user-guide/images/how-tos/domain-services/hexagonal-architecture-addons.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/b5ee5585/adocs/documentation/src/main/asciidoc/user-guide/user-guide.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/user-guide.adoc b/adocs/documentation/src/main/asciidoc/user-guide/user-guide.adoc
index b5c63f0..a339d19 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/user-guide.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/user-guide.adoc
@@ -12,6 +12,8 @@ include::_user-guide_how-tos.adoc[leveloffset=+1]
include::_user-guide_reference.adoc[leveloffset=+1]
+include::_user-guide_decoupling.adoc[leveloffset=+1]
+
include::_user-guide_testing.adoc[leveloffset=+1]
include::_user-guide_wicket-viewer.adoc[leveloffset=+1]
[3/4] isis git commit: ISIS-1133: more adocs (philosophy and
architecture section)
Posted by da...@apache.org.
ISIS-1133: more adocs (philosophy and architecture section)
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/b5ee5585
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/b5ee5585
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/b5ee5585
Branch: refs/heads/master
Commit: b5ee5585a124133518d6e49a25eb3ac4a111fdf8
Parents: 359e4af
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Sun May 3 08:22:59 2015 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Sun May 3 08:22:59 2015 +0100
----------------------------------------------------------------------
.../asciidoc/user-guide/_/GettingStarted.adoc | 947 -------------------
.../_user-guide_core-concepts_philosophy.adoc | 249 +----
...user-guide_core-concepts_philosophy_aop.adoc | 31 +
...user-guide_core-concepts_philosophy_dci.adoc | 8 +
...oncepts_philosophy_domain-driven-design.adoc | 79 ++
...cepts_philosophy_hexagonal-architecture.adoc | 28 +
..._core-concepts_philosophy_how-eases-ddd.adoc | 73 ++
...ncepts_philosophy_naked-objects-pattern.adoc | 54 ++
.../user-guide/_user-guide_decoupling.adoc | 13 +
.../_user-guide_how-tos_domain-services.adoc | 9 +
.../hexagonal-architecture-addons.png | Bin 128533 -> 0 bytes
.../hexagonal-architecture-addons.png | Bin 0 -> 128533 bytes
.../main/asciidoc/user-guide/user-guide.adoc | 2 +
13 files changed, 303 insertions(+), 1190 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/b5ee5585/adocs/documentation/src/main/asciidoc/user-guide/_/GettingStarted.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_/GettingStarted.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_/GettingStarted.adoc
deleted file mode 100644
index 5194136..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_/GettingStarted.adoc
+++ /dev/null
@@ -1,947 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-
-<!DOCTYPE chapter SYSTEM "local/xml/markup.dtd">
-= Getting Started
-
-
-
-To stop himself from procrastinating in his work, the Greek orator Demosthenes
-would shave off half his beard. Too embarrassed to go outside and with
-nothing else to do, his work got done.
-
-We could learn a lesson or two from old Demosthenes. After all, we
-forever seem to be taking an old concept and inventing a new technology
-around it (always remembering to invent a new acronym, of course)---anything,
-it would seem, instead of getting down to the real work of solving business
-problems.
-
-Domain-driven design (hereafter _DDD_) puts the emphasis
-elsewhere, "tackling complexity in the heart of software." And Naked
-Objects---an open source Java framework---helps you build your business
-applications with ease. No beard shaving necessary, indeed.
-
-In this chapter, we're going to briefly describe the key ideas underlying
-_DDD_, identify some of the challenges of applying these
-ideas, and see for ourselves how Naked Objects makes our task that much
-easier.
-
-== Understanding Domain-Driven Design
-
-
-
-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 '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.
-
-So, let's start off by reviewing the essential ideas of
-_DDD_.
-
-
-== The Essentials of DDD
-
-
-
-There are two central ideas at the heart of domain-driven design. The
-*_ubiquitous language_* is about getting the whole team
-(both domain experts and developers) to communicate more transparently
-using a domain model. Meanwhile, *_model-driven design_*
-is about capturing that model in a very straightforward manner in code.
-Let's look at each in turn.
-
-=== Creating a 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.
-
-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.
-
-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.
-
-[TIP]
-=====
-
-In Extreme Programming, there is a similar idea called
-a *system of names*. But *ubiquitous language* is much more
-evocative.
-
-====
-
-
-
-==
-
-.Ubiquitous Language
-****
-
-Build a common language between the domain experts and developers
-by using the concepts of the domain model as the primary means of
-communication. Use the terms in speech, in diagrams, in writing, and when
-presenting.
-
-If an idea cannot be expressed using this set of concepts, then go
-back and extend the model. Look for and remove ambiguities and
-inconsistencies.
-
-****
-
-
-
-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.
-
-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.
-
-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.
-
-
-=== Model-Driven Design
-
-
-
-Of the various methodologies that the IT industry has tried, many
-advocate the production of separate analysis models and implementation
-models. A recent example is 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.
-
-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. Oft quoted and still true is that 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*.
-
-==
-
-.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.
-
-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 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.
-
-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. What this book is about is how Naked
-Objects eases that path by applying these central ideas of
-_DDD_ in a very concrete way. So, now would be a good time
-to see how.
-
-
-== Introducing Naked Objects
-
-
-
-*_Naked Objects_* is both an architectural pattern and a software
-framework. The pattern was originally conceived and articulated by Richard
-Pawson as a means of engaging business stakeholders and experts in
-developing more expressive domain-driven applications. Richard discusses this in more
-detail in the foreword.
-
-The framework, then, is an implementation of the pattern to help you
-rapidly prototype, develop, and deploy domain-driven applications:
-
-
-* *Rapid prototyping* comes from the fact that you can
-develop an application without spending any time writing user
-interface code or persistence code. This creates a very tight feedback
-loop with your domain experts.
-
-
-* The *development support* comes from the close
-integration with developer tools such as *_Eclipse_* (for coding),
-*_FitNesse_* (for testing), *_Maven_* (for building and packaging), and *_Hudson_*
-(for continuous integration).
-
-
-* The *deployment support* comes from Naked Objects'
-pluggable architecture allowing different viewers, persistence
-mechanisms, and security. In fact, the domain
-model has no runtime dependencies on the framework, so you can deploy
-your application on any Java-based enterprise architecture with any
-_UI_ you want.
-
-
-
-For more on the original philosophy that drove Naked Objects'
-development, see Richard Pawson and Robert Matthews' book, 'Naked Objects', and Richard's later PhD thesis.
-
-[TIP]
-=====
-
-link:http://www.nakedobjects.org/downloads/Pawson%20thesis.pdf[]
-
-====
-
-
-
-==
-
-.How Does Naked Objects Compare to Other Frameworks?
-****
-
-Many other frameworks promise rapid application
-development and provide automatically generated user interfaces, so how
-do they compare to Naked Objects?
-
-Some of most significant are *_Rails_* (for the Ruby programming
-language), *_Grails_* (Groovy), and *_Spring Roo_* (Java with AspectJ).
-
-[TIP]
-=====
-
-The frameworks mentioned here are hosted at
-link:http://rubyonrails.org/[], link:http://www.grails.org[],
-and link:http://www.springsource.org/roo[].
-
-====
-
-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.
-
-For many developers, the most obvious difference of Naked Objects 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 skinning Naked Objects (see <<chp.IWWF>>) or by using a newer viewer that supports
-easy customization (see <<chp.DTFR>>).
-
-Like all of these frameworks, Naked Objects can expose domain
-objects as a _RESTful_ web service. However, it has some other tricks you
-may not find in a typical _MVC_ framework:
-it supports client-server (rich-client) deployments as well as on the Web;
-it supports non- _RDBMS_ as well as
-_RDBMS_ object stores, with an in-memory object store
-for rapid prototyping; it supports domain-driven concepts such as
-values, repositories, and domain services; it supports agile scenario
-testing using FitNesse; and it puts the domain
-metamodel at the center, allowing the programming model to be
-redefined.
-****
-
-I could talk at length in a highly theoretical fashion about Naked
-Objects and how it relates to _DDD_ for the next thirty
-pages, but what we're going to do instead is see Naked Objects in
-action.
-
-
-== Naked Objects in About Five Minutes
-
-
-
-Throughout the book we're going to be using Naked Objects 4.0 for Java,
-an open source framework licensed under Apache License v2.
-
-[TIP]
-=====
-
-link:http://www.apache.org/licenses/LICENSE-2.0.html[]
-
-====
-
-All the other products we're going to use in this book are
-also open source with similar nonrestrictive licenses. Without further
-ado, let's get our development environment set up.
-
-[TIP]
-=====
-
-If you have any problems setting up or running the application,
-don't forget the book's forum as a place to get help.
-
-====
-
-
-
-
-=== Set Up the Development Environment
-
-
-
-Naked Objects is a Java framework, so we need Java 5 or higher
-installed along with an _IDE_. In this book I'm going
-to be using Eclipse 3.5: it's extremely capable and freely available.
-However, there's nothing stopping you from using some other _IDE_.
-
-In addition, we need to set up Maven, one of the most commonly used
-tools for building Java software.
-
-[TIP]
-=====
-
-Maven is hosted at link:http://maven.apache.org[].
-
-====
-
-Naked Objects provides a Maven archetype (a project
-template) to help get us started, and the case study we'll develop
-through the book builds on this archetype and so is also a Maven-based
-project. We won't be using particularly advanced features of Maven, but
-if you are interested in learning more, then take a look at 'Maven, The Definitive Guide'.
-
-We also need Maven support in our _IDE_ (or at least
-the ability to import Maven projects). In the case of Eclipse, this
-means installing a plug-in; if you're using an _IDE_
-other than Eclipse, then make sure it has equivalent Maven support. Both
-NetBeans 6.7 onward and IntelliJ IDEA 7.0 onward have out-of-the-box
-support, so there's plenty of choice.
-
-And finally, we also need to download the Naked Objects distribution
-itself. We don't need this for the Naked Objects
-_JAR_s---we'll get those courtesy of Maven---but the
-distribution does include a number of resources (such as icons) that we
-will need, along with an example application that we're going to try
-in the next section.
-
-So, do the following:
-
-
-* Install Java 5 or 6 from link:http://java.sun.com[]. Either
-the _JRE_ or the _JDK_ is fine. I used
-_JDK_ 1.5_014 for this book. Set the
-`JAVA_HOME` environment variable, and
-update the `PATH` to include
-`$JAVA_HOME/``bin`.
-
-
-* Download and install Maven 2.0.9 or higher, from
-link:http://maven.apache.org/download.html[]. The Maven website
-has instructions on installing Maven, but it basically amounts to
-extracting the _ZIP_, setting up the
-`M2_HOME` environment variable, and
-updating your `PATH` to pick up the
-`mvn.bat` or `mvn.sh` batch
-file.
-
-
-* Download and unzip Eclipse 3.5 or higher,
-link:http://www.eclipse.org/downloads[]. You can use either the
-standard distribution or the full-blown Java EE enterprise distribution.
-
-
-* Install the *m2eclipse* plug-ins into Eclipse, v0.9.7 or higher,
-link:http://m2eclipse.sonatype.org/update[]. This is an update
-site from which Eclipse can download and install the software. If
-you aren't an Eclipse regular, the incantation is: select the Help > Install
-New Software menu and then press the Add… button to add
-this site.
-
-
-* Download Naked Objects 4.0 from
-link:https://sourceforge.net/projects/nakedobjects/[]; the file
-you need is `nakedobjects-4.0.0-for-maven.zip`
-(or whichever is the latest release). Unzip this wherever you want;
-I'll refer to this location as `$NO_HOME` (though
-there's no need to set an environment variable).
-
-
-
-
-Included in the Naked Objects download are a number of Eclipse
-templates that we can use to quickly write short code fragments using
-Content Assist (that is,
-kbd:[Ctrl]+kbd:[Spacebar]). We won't need
-these until the next chapter, but now is a good time to set them up. So,
-start up Eclipse in a new workspace, select Window >
-Preferences > Java > Editor > Templates, and then select Import.
-Navigate to the
-`$NO_HOME/resources/ide/``eclipse/templates` directory,
-and select the `nakedobjects-templates.xml` file.
-Finally, hit OK.
-
-Note, by the way, that these templates are effectively stored in the
-workspace; if you use File > Switch Workspace, then you'll need to
-reimport the templates. For easy reference, all the templates are
-listed in <<apx.ET>>. When we get to using them, I'll also
-indicate some of the main ones to use in the text.
-
-OK, let's test our setup by importing and running a very simple
-claims-processing application written using Naked Objects.
-
-
-=== Import and Explore a Naked Objects Application
-
-
-
-With Eclipse still running, first make sure you are in the Java
-perspective (use Window > Open Perspective > Other > Java).
-Then, use File > Import > General > Maven Projects, and browse
-to `$NO_HOME/examples/``claims`. Hit Enter, and a set of
-Maven projects should be listed.
-
-==
-
-.The imported `dom` project
-
-image::images/eps/TheImportedDomProject.eps[]
-
-
-
-Now hit Finish, and you should be left with a parent project (no
-suffix) and five further child projects with various suffices. This is the
-standard way that we tend to organize Naked Objects applications:
-
-
-* The `dom` (domain object model) is where most of
-the action is, containing the domain classes that make up the
-application.
-
-
-* The `fixture` project contains fixtures that
-provide a working set of objects for demonstration purposes; we
-cover this in <<chp.RP>>.
-
-
-* The `service` project provides supporting
-services to the domain objects; we cover this mostly in <<chp.IIS>> and in <<chp.IWTD>>.
-
-
-* The `commandline` project is where we run the
-application from during development (throughout the book).
-
-
-* The `webapp` project allows us to deploy the
-application to a web container; we use this at the end of the book,
-in <<chp.DTFR>>.
-
-
-
-Open the `dom` project, as shown in <<sec.TheImportedDomProject>>. There should be three concrete
-classes: `Employee`, `Claim`,
-and `ClaimItem`. `Employee`s
-make `Claim`s, and `Claim`s
-are made up of `ClaimItem`s. In addition, there are
-some interfaces implemented by these domain classes
-(`Approver` and `Claimant`),
-as well as some repository interfaces
-(`EmployeeRepository` and
-`ClaimRepository`). These are used to look up
-`Employee`s and, um,
-`Claim`s; the implementations are in the
-`services` project.
-
-Poke around inside these domain classes. We are of course
-going to be covering how to write such classes in detail (starting in
-<<chp.ITDC>>), but for now it should at easy enough to see
-that an `Employee` has a
-`Name` and an
-`Approver` property:
-
-[source,java]
-----
-include::code/chapter01/Employee.java
-----
-
-==
-
-.The claims app in the DnD viewer
-
-image::images/eps/TheSampleAppInTheDndViewer.eps[]
-
-
-Now here's the thing: the domain model we've been looking at is the
-entire application. Fundamentally, writing a Naked Objects application
-means writing a domain model, and that's it.
-
-
-It's time to run the application, methinks.
-
-
-=== Run the Application
-
-
-
-Naked Objects is so called because it automatically displays the
-domain objects in an *_object-oriented user interface_*
-( _OOUI_). These _OOUI_s are also
-generic because they can display *any* domain object in a
-standardized fashion.
-
-Out of the box, Naked Objects ships with two main
-_OOUI_ viewers. The *_drag-n-drop_*
-( _DnD_) viewer is a rich client intended for
-client-side deployment, while the _HTML_ viewer is
-designed to host your application on the Web. Let's look at the
-_DnD_ viewer first.
-
-==
-
-.The claims app in the HTML viewer
-
-image::images/eps/TheSampleAppInTheHtmlViewer.eps[]
-
-
-In Eclipse, use Run > Run Configurations to bring up the generated
-launch configurations. Listed as a Java Application launch configuration
-should be `claims_exploration_dnd.launch` (defined
-in the `commandline` project). Select this, and then
-click Run. If using another _IDE_, all we are doing is
-running `org.nakedobjects.runtime.NakedObjects`
-with a command-line option of `--type exploration --viewer
-dnd`.
-
-All being well, the _DnD_ viewer should launch,
-showing the two repositories as icons. By right-clicking these icons,
-we can invoke actions on the repositories to retrieve objects. Once we
-have an object, we can use it to navigate to other referenced objects
-(click/double-click icons), right-click to invoke actions, and
-generally have a good old browse around. We can see the
-_DnD_ viewer in action in <<sec.TheSampleAppInTheDndViewer>>.
-
-
-OK, let's now run the same application using the
-_HTML_ viewer. Again, using Run > Run Configurations,
-this time select `claims_exploration_html.``launch`,
-and click Run. Again, if using another IDE, this is running the same
-class with flags of `--type exploration` and `--viewer
-html`.
-
-What Naked Objects will do is run the application on an embedded
-Jetty web server, listening on port 8080. If for some reason you need to
-use another port number, just edit the
-`nakedobjects.embedded-web-server.port`
-property in the
-`config/embedded-web-server.properties` file in the
-`commandline` project.
-
-Eclipse's console view should indicate that the server is up and
-running. Now start your favorite web browser, and go to
-link:http://localhost:8080/logon.app[]. You should be logged in
-automatically and then see links representing the two repositories;
-these are the _HTML_ equivalents of the icons in the
-_DnD_ desktop view. Click one of these, and then use
-the action links to navigate the application as before. We can see the
-_HTML_ viewer in action in <<sec.TheSampleAppInTheHtmlViewer>>.
-
-Try running the two viewers side-by-side. Although they look
-different, they both provide the same functionality, and that
-functionality is defined entirely by the domain classes.
-
-We're going to be using both of these viewers extensively throughout
-the book; they are, after all, the default viewers provided by Naked
-Objects. I should point out, though, that these aren't the only viewers
-available. In <<chp.DTFR>>, we'll see a number of other
-viewers either developed or in active development. It's also possible to
-use a custom interface; see <<chp.IWWF>>.
-
-
-Before our quick Naked Objects demo, I was asserting that putting
-_DDD_ ideas into practice isn't necessarily that easy
-but that Naked Objects eases the path. Now that you've seen Naked Objects "in
-the flesh" (so to speak!), let's see how.
-
-
-== How Naked Objects Helps with DDD
-
-
-
-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 Naked Objects
-helps address them.
-
-=== DDD Takes a Conscious Effort
-
-
-
-Here's what Evans says about *ubiquitous language*: "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."
-
-The word I want 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 Naked Objects, though, the *ubiquitous language*
-evolves with scarcely any effort at all. For the business experts, the
-Naked Objects 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.
-
-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 Naked Objects, 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.
-
-
-=== Abstract Models Are Difficult to Represent
-
-
-
-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.
-
-A better way to represent the model is to show it in action as a
-working prototype. As we've seen, Naked Objects 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.
-
-Moreover, with Naked Objects prototypes, the domain model will come
-shining through. If there are mistakes or misunderstandings in the
-domain model, they will be obvious to all.
-
-
-=== Layered Architectures Are Expensive and Easily
-Compromised
-
-
-
-==
-
-.Layered Architecture
-****
-
-We partition a complex program into layers, with each layer
-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.
-
-****
-
-
-
-_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.
-
-
-
-
-However, there are two immediate issues. The first is rather obvious:
-custom coding each of those other layers is an expensive proposition.
-Picking up on the previous point, this in itself can put the kibosh on
-using prototyping to represent the model, even if we wanted to do so.
-
-The second issue is more subtle. It takes real skill to ensure the
-correct separation of concerns between these layers, if indeed you can
-get an agreement as to what those concerns actually are. Even with the
-best intentions, it's all too easy for custom-written layers to blur the
-boundaries and put (for example) validation in the user interface layer
-when it should belong to the domain layer. At the other extreme, it's
-quite possible for custom layers to distort or completely subvert the
-underlying domain model.
-
-
-
-Because of Naked Objects' generic _OOUI_s, there's
-no need to write the other layers of the architecture. And as we've
-seen, this makes prototyping cheap. But more than that, there will be no
-leakage of concerns outside the domain model. All the validation logic
-*must* be in the domain model because there is
-nowhere else to put it.
-
-Moreover, although Naked Objects does provide a
-complete runtime framework, there is no direct coupling of your domain
-model to the framework. That means it is very possible to take
-your domain model prototyped in Naked Objects and then deploy it on
-some other _J(2)EE_ architecture, with a custom
-_UI_ if you want. Naked Objects guarantees that your
-domain model is complete.
-
-
-=== Naked Objects Extends the Reach of DDD
-
-
-
-Domain-driven design is often positioned as being applicable only to
-complex domains; indeed, the subtitle of Evans book is *Tackling
-Complexity in the Heart of Software*. The corollary is that DDD is
-overkill for simpler domains. The trouble is that we immediately have to
-make a choice: is the domain complex enough to warrant a domain-driven
-approach?
-
-This goes back to the previous point, building and maintaining a
-*layered architecture*. It doesn't seem cost effective to go to all the
-effort of a DDD approach if the underlying domain is simple.
-
-However, with Naked Objects, we don't write these other layers, so
-we don't have to make a call on how complex our domain is. We can
-start working solely on our domain, even if we suspect it will be
-simple. If it is indeed a simple domain, then there's no hardship, but if unexpected subtleties arise, then we're in a good position to
-handle them.
-
-
-If you're just starting out writing domain-driven applications, then
-Naked Objects should significantly ease your journey into applying
-_DDD_. On the other hand, if you've used
-_DDD_ for a while, then you should find Naked Objects a
-very useful new tool in your arsenal.
-
-In this chapter we've discussed DDD in the context of a layered
-architecture. We're going to finish off this chapter with a refinement
-of that idea, which moreover will act as a road map to the
-rest of the book.
-
-
-== The Big Picture
-
-
-
-A few years ago Alistair Cockburn reworked the traditional layered
-architecture diagram and came up with the
-*_hexagonal architecture_*, as shown in <<sec.HexagonalArchitecture>>.
-
-[TIP]
-=====
-
-link:http://alistair.cockburn.us/Hexagonal+architecture[].
-Another similar (same?) pattern is the onion architecture; see
-link:http://jeffreypalermo.com/blog/the-onion-architecture-part-3/[].
-
-====
-
-
-
-==
-
-.The *hexagonal architecture* emphasizes multiple implementations of
-the different layers.
-
-image::images/eps/HexagonalArchitecture.eps[]
-
-
-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.
-
-Naked Objects maps very nicely onto the *hexagonal architecture*. As
-shown in <<sec.HexagonalArchitectureForNakedObjects>>, most
-of the user-side adapters (that is, viewers) run in the same memory space
-as the domain layer and so (using Cockburn's terminology) access the
-domain layer through an in-memory port. However, rich client/desktop-based
-viewers such as the _DnD_ viewer can also access the
-domain layer using a remoting protocol port. Naked Objects also supports
-_RESTful_ web services, which I've drawn as
-an adapter, but one could also think of it as an implementation of a third
-port providing access to other non-Java on the user side. An inbound adapter from
-an *_enterprise service bus_* ( _ESB_)
-could also consume events from any other system in the enterprise.
-
-==
-
-.The *hexagonal architecture* for Naked Objects
-
-image::images/eps/HexagonalArchitectureForNakedObjects.eps[]
-
-
-For the data side, we are mostly concerned with persisting domain
-objects to some sort of object store; this is the persistence port. We
-might also invoke services; the implementation of these services is
-specific to the application. These could, for example, call out to an
-external web service. Alternatively, the service could be a generic
-mechanism to publish events asynchronously onto an ESB, removing any
-runtime dependency between our application and the external system.
-
-Doing double duty, <<sec.HexagonalArchitectureForNakedObjects>> is a road map for the book; as you might have guessed, the
-overlaid numbers correspond to the chapters where that component is
-discussed. As you would expect, much of the book (most of the chapters in
-Parts I and II) is focused on the domain model. The chapters in
-Part III focus more on the adapters (viewers and object stores) that
-interact with the domain model.
-
-
-== Coming Up Next
-
-
-
-In this chapter, we talked about the two central ideas of
-domain-driven design, that of the *ubiquitous language* and of
-a *model-driven design*. We also got our development
-environment up and running and used it to run our first Naked Objects
-application. We then looked at how Naked Objects addresses several issues
-that you might otherwise struggle with when applying
-_DDD_ and recast the traditional *layered architecture*
-instead as the *hexagonal architecture*.
-
-This is very much a learning-by-doing book. Throughout, we're going to
-be developing our own domain application as a single case study, so in
-the next chapter we're going to start at the beginning, identifying the
-main concepts of its domain. See you there.
-
-
-== Exercises
-
-
-
-In each chapter of the book there is an "Exercises" section like this,
-where I'll be asking you to implement the techniques covered in the
-chapter text.
-
-In addition to the case study in the main text, you might want to
-develop your own application alongside, something that's close to your
-heart. So, get your thinking hat on and decide what you'd like to implement
-as your first Naked Objects (and perhaps domain-driven design)
-application. In the next chapter's exercises, you'll be in a position to
-start implementing it.
-
http://git-wip-us.apache.org/repos/asf/isis/blob/b5ee5585/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy.adoc
index aa7804e..5825c02 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy.adoc
@@ -5,253 +5,16 @@
This section describes some of the core ideas and architectural patterns upon which Apache Isis builds.
-== Domain-Driven Design
+include::_user-guide_core-concepts_philosophy_domain-driven-design.adoc[leveloffset=+1]
-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.
+include::_user-guide_core-concepts_philosophy_naked-objects-pattern.adoc[leveloffset=+1]
-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.
+include::_user-guide_core-concepts_philosophy_hexagonal-architecture.adoc[leveloffset=+1]
-There are two central ideas at the heart of domain-driven design.
+include::_user-guide_core-concepts_philosophy_aop.adoc[leveloffset=+1]
-* the *_ubiquitous language_* is about getting the whole team (both domain experts and developers) to communicate more transparently using a domain model.
+// include::_user-guide_core-concepts_philosophy_dci.adoc[leveloffset=+1]
-* Meanwhile, *_model-driven design_* is about capturing that model in a very straightforward manner in code.
+include::_user-guide_core-concepts_philosophy_how-eases-ddd.adoc[leveloffset=+1]
-Let's look at each in turn.
-
-=== 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.
-
-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.
-
-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.
-
-
-.Ubiquitous Language
-****
-Build a common language between the domain experts and developers by using the concepts of the domain model as the primary means of communication. Use the terms in speech, in diagrams, in writing, and when presenting.
-
-If an idea cannot be expressed using this set of concepts, then go back and extend the model. Look for and remove ambiguities and inconsistencies.
-****
-
-
-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.
-
-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.
-
-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.
-
-
-=== 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_).
-
-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.
-
-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.
-
-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 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.
-
-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.
-
-
-
-
-== Naked Objects Pattern
-
-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>]
-
-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.
-pass:[</p></div>]
-
-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>]
-
-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>]
-
-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 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: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 http://isisaddons.org[Isis Addons] (non-ASF) the http://github.com/isisaddons/isis-wicket-gmap3}[Isis addons' gmap3 modue] 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.
-====
-
-=== Object Interface Mapping
-
-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 <<_vs_metawidget,here>>.
-====
-
-
-
-
-
-== Hexagonal Architecture
-
-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_*:.
-
-[TIP]
-====
-The hexagonal architecture is also known as the link:http://c2.com/cgi/wiki?PortsAndAdaptersArchitecture:[Ports and Adapters] architecture or (less frequently) as the link:http://jeffreypalermo.com/blog/the-onion-architecture-part-1/[Onion] architecture.
-====
-
-.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*. Isis' viewers act as user-side adapters and use the 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 Isis can be configured to persist using some other JDO implementation, for example Google App Engine.
-
-It's worth extending the hexagonal architecture to show where http://isisaddons.org[Isis Addons] (non-ASF) fit in:
-
-.The hexagonal architecture with Isis addons
-image::{_imagesdir}core-concepts/philosophy/hexagonal-architecture-addons.png[width="700px"]
-
-Here, we can see that the addons provide services both to the Isis framework (for example security, command and auditing) and also to the domain objects (eg tags, excel, settings). Of course, you can also write your own domain services as well, for example to interface with some external CMS system, say.
-
-
-
-
-
-== Aspect Oriented
-
-Although not implemented using an aspect-oriented language such as AspectJ, Isis takes considerable inspiration from AOP concepts.
-
-For example, the UI visualization automatically provided by Isis can be thought of (and is!) treating the UI as a cross-cutting concern.
-
-Isis' also has support for traits/mixins through its <<Contributions>>. This allows functionality from one class (a domain service) to be rendered as if it belongs to another (a domain object).
-
-
-* aspect-oriented design, such as traits/mix-ins (see <<Contributions>>) and interceptors and UI visualization as a cross-cutting concern
-
-
-== DCI
-
-IMPORTANT: TODO ... Trygve Reenskaug
-
-
-
-== How Apache Isis eases DDD
-
-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>]
-
-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.
-
-With Apache Isis, though, the ubiquitous language evolves with scarcely any effort at all. For the business experts, the 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.
-
-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.
-
-
-=== Abstract Models Are Difficult to Represent
-
-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.
-
-A better way to represent the model is to show it in action as a working prototype. As we show in the <<_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.
-
-Moreover, with Apache Isis prototypes, the domain model will come shining through. If there are mistakes or misunderstandings in the domain model (inevitable when building any complex system), they will be obvious to all.
-
-
-=== Layered Architectures Are Expensive and Easily Compromised
-
-_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.
-
-.Layered Architecture
-****
-We partition a complex program into layers, with each layer 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.
-****
-
-However, there are two immediate issues. The first is rather obvious: custom coding each of those other layers is an expensive proposition. Picking up on the previous point, this in itself can put the kibosh on using prototyping to represent the model, even if we wanted to do so.
-
-The second issue is more subtle. It takes real skill to ensure the correct separation of concerns between these layers, if indeed you can get an agreement as to what those concerns actually are. Even with the best intentions, it's all too easy for custom-written layers to blur the boundaries and put (for example) validation in the user interface layer when it should belong to the domain layer. At the other extreme, it's quite possible for custom layers to distort or completely subvert the underlying domain model.
-
-Because of Apache Isis' generic _OOUI_s, there's no need to write the other layers of the architecture. Of course, this reduces the development cost. But more than that, there will be no leakage of concerns outside the domain model. All the validation logic *must* be in the domain model because there is nowhere else to put it.
-
-Moreover, although Apache Isis does provide a complete runtime framework, there is no direct coupling of your domain model to the framework. That means it is very possible to take your domain model prototyped in Naked Objects and then deploy it on some other _J(2)EE_ architecture, with a custom _UI_ if you want. Isis guarantees that your domain model is complete.
-
-
-=== Apache Isis extends the reach of DDD
-
-Domain-driven design is often positioned as being applicable only to complex domains; indeed, the subtitle of Evans book is *Tackling Complexity in the Heart of Software*. The corollary is that DDD is overkill for simpler domains. The trouble is that we immediately have to make a choice: is the domain complex enough to warrant a domain-driven approach?
-
-This goes back to the previous point, building and maintaining a *layered architecture*. It doesn't seem cost effective to go to all the effort of a DDD approach if the underlying domain is simple.
-
-However, with Apache Isis, we don't write these other layers, so we don't have to make a call on how complex our domain is. We can start working solely on our domain, even if we suspect it will be simple. If it is indeed a simple domain, then there's no hardship, but if unexpected subtleties arise, then we're in a good position to handle them.
-
-If you're just starting out writing domain-driven applications, then Apache Isis should significantly ease your journey into applying _DDD_. On the other hand, if you've used _DDD_ for a while, then you should find Isis a very useful new tool in your arsenal.
http://git-wip-us.apache.org/repos/asf/isis/blob/b5ee5585/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy_aop.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy_aop.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy_aop.adoc
new file mode 100644
index 0000000..b3ccb0e
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy_aop.adoc
@@ -0,0 +1,31 @@
+= Aspect Oriented
+: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/
+
+
+Although not a book about object modelling, Evans' "Domain Driven Design" does use object orientation as its primary modelling tool; and many tend to think of <<_domain_driven_design,DDD>> as an updated treatise on good object modelling, in the same vein as Rebecca Wirf Brock's Responsibility Driven Design, say. Meanwhile the <<_naked_objects_pattern, naked objects pattern>> very much comes from an OO background (it even has 'object' in its name); and Richard Pawson lists Alan Kay as one of his idols.
+
+It's certainly true that to develop an Apache Isis application you will need to have good object oriented modelling skills. 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.
+
+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.
+
+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.
+
+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 <<_decoupling, Decoupling>> chapter. 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's description of the <<_naked_objects_pattern, naked objects pattern>> he talks about "behaviourally rich" objects, in other words where the business functionality encapsulated the data: OO as your mother taught you! But equally sometimes the behaviour and data structures change at different rates; the single responsibility pattern says we should only lump code together that changes at the same rate. 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 Isis' AOP support for mixins (contributions) see interceptors (the event bus) to ensure that your codebase remains maintainable.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/b5ee5585/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy_dci.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy_dci.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy_dci.adoc
new file mode 100644
index 0000000..eb54833
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy_dci.adoc
@@ -0,0 +1,8 @@
+= DCI
+: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/
+
+
+IMPORTANT: TODO ... Trygve Reenskaug
+
http://git-wip-us.apache.org/repos/asf/isis/blob/b5ee5585/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy_domain-driven-design.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy_domain-driven-design.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy_domain-driven-design.adoc
new file mode 100644
index 0000000..0eb7be6
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_philosophy_domain-driven-design.adoc
@@ -0,0 +1,79 @@
+= Domain-Driven Design
+: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/
+
+This section describes some of the core ideas and architectural patterns upon which Apache Isis builds.
+
+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.
+
+There are two central ideas at the heart of domain-driven design.
+
+* the *_ubiquitous language_* is about getting the whole team (both domain experts and developers) to communicate more transparently using a domain model.
+
+* Meanwhile, *_model-driven design_* is about capturing that model in a very straightforward manner in code.
+
+Let's look at each in turn.
+
+== 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.
+
+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.
+
+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.
+
+
+.Ubiquitous Language
+****
+Build a common language between the domain experts and developers by using the concepts of the domain model as the primary means of communication. Use the terms in speech, in diagrams, in writing, and when presenting.
+
+If an idea cannot be expressed using this set of concepts, then go back and extend the model. Look for and remove ambiguities and inconsistencies.
+****
+
+
+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.
+
+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.
+
+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.
+
+
+== 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_).
+
+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.
+
+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.
+
+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 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.
+
+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.
+
+
[4/4] isis git commit: ISIS-1133: more conversion of adocs
Posted by da...@apache.org.
ISIS-1133: more conversion of adocs
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/ef1e765c
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/ef1e765c
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/ef1e765c
Branch: refs/heads/master
Commit: ef1e765c840ef258f0ebe94f6874983422ceeab8
Parents: b5ee558
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Sun May 3 15:54:44 2015 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Sun May 3 15:54:44 2015 +0100
----------------------------------------------------------------------
.../user-guide/__/enabling-logging.adoc | 35 +++++++
.../user-guide/_user-guide_core-concepts.adoc | 2 +
.../_user-guide_core-concepts_add-ons.adoc | 7 ++
.../_user-guide_core-concepts_principles.adoc | 49 +---------
...de_core-concepts_principles_isis-itself.adoc | 46 +++++++++
...uide_core-concepts_principles_your-apps.adoc | 38 ++++++++
...uide_reference_configuration-properties.adoc | 65 +------------
...reference_configuration-properties_core.adoc | 32 +++++++
...tion-properties_datanucleus-objectstore.adoc | 44 +++++++++
...e_disabling-persistence-by-reachability.adoc | 93 +++++++++++++++++++
...bjectstore_eagerly-registering-entities.adoc | 25 +++++
...ration-properties_restfulobjects-viewer.adoc | 21 +++++
..._configuration-properties_wicket-viewer.adoc | 52 +++++++++++
.../user-guide/_user-guide_troubleshooting.adoc | 4 +-
...ide_troubleshooting_datanucleus-logging.adoc | 10 --
...-guide_troubleshooting_enabling-logging.adoc | 38 ++++++++
.../party-agreementrole-agreement.png | Bin 0 -> 10310 bytes
17 files changed, 445 insertions(+), 116 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/ef1e765c/adocs/documentation/src/main/asciidoc/user-guide/__/enabling-logging.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/__/enabling-logging.adoc b/adocs/documentation/src/main/asciidoc/user-guide/__/enabling-logging.adoc
new file mode 100644
index 0000000..0450236
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/__/enabling-logging.adoc
@@ -0,0 +1,35 @@
+Title: Enabling Logging
+
+Sometimes you just need to see what is going on. There are various ways in which logging can be enabled, here are some ideas.
+
+=== In Apache Isis
+
+Modify `WEB-INF/logging.properties` (a log4j config file)
+
+=== In DataNucleus
+
+As per the http://www.datanucleus.org/products/accessplatform/logging.html[DN logging page]
+
+=== 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 link:../../../intro/getting-started/simpleapp-archetype.html[simpleapp archetype].
+
+=== In the Database
+
+==== HSQLDB Logging
+
+Add `;sqllog=3` to the end of the JDBC URL.
+
+==== PostgreSQL Logging
+
+In `postgresql\9.2\data\postgresql.conf`:
+
+Will then log to `postgresql\9.2\data\pg_log` directory.
+
+Note that you must restart the service for this to be picked up.
+
+==== MS SQL Server Logging
+
+Use the excellent SQL Profiler tool.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/ef1e765c/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts.adoc
index ad2866c..b5a5833 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts.adoc
@@ -19,4 +19,6 @@ include::_user-guide_core-concepts_building-blocks.adoc[leveloffset=+1]
include::_user-guide_core-concepts_framework-provided-services.adoc[leveloffset=+1]
+include::_user-guide_core-concepts_add-ons.adoc[leveloffset=+1]
+
http://git-wip-us.apache.org/repos/asf/isis/blob/ef1e765c/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_add-ons.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_add-ons.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_add-ons.adoc
new file mode 100644
index 0000000..5b01d80
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_add-ons.adoc
@@ -0,0 +1,7 @@
+= Add-ons
+: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/
+
+IMPORTANT: TODO
+
http://git-wip-us.apache.org/repos/asf/isis/blob/ef1e765c/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_principles.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_principles.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_principles.adoc
index 541b9c1..543ec76 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_principles.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_principles.adoc
@@ -3,54 +3,15 @@
:_basedir: ../
:_imagesdir: images/
-This section describes some of the core principles and values that the framework aims to honour and support.
-
-
-== Decoupled (no "Big Ball of Mud")
-
-IMPORTANT: TODO ...
-
-Long-term Cost of ownership
-
-Using:
-
-* dependency injection of services
-* OO design techniques, eg dependency inversion principle
-* an in-memory event bus
-* applib
-
-
-== Honouring the Single Responsibility Principle
-
-=== Behaviourally Complete vs Contributions
-
-
-
-
-== Focuses on its Key Responsibilities
-
-* 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
-
-[NOTE]
-====
-... we're getting there...
-====
-
-
-
-== Full-stack but extensible
-
-IMPORTANT: TODO
-
-
+This section describes some of the core principles and values that the framework aims to honour and support.
-== Testable Applications
+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.
-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.
+The section concludes by contrasting the framework with some other open source frameworks commonly used.
+include::_user-guide_core-concepts_principles_your-apps.adoc[leveloffset=+1]
+include::_user-guide_core-concepts_principles_isis-itself.adoc[leveloffset=+1]
include::_user-guide_core-concepts_principles_apache-isis-vs.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/ef1e765c/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_principles_isis-itself.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_principles_isis-itself.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_principles_isis-itself.adoc
new file mode 100644
index 0000000..b48230c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_principles_isis-itself.adoc
@@ -0,0 +1,46 @@
+= Isis itself
+: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/
+
+
+This section discusses some of the principles and values we apply to the development of the Apache Isis framework itself.
+
+== Full-stack but Extensible
+
+IMPORTANT: TODO
+
+
+== Focuses on its USP
+
+IMPORTANT: TODO
+
+
+add-ons
+
+* 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 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/ef1e765c/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_principles_your-apps.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_principles_your-apps.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_principles_your-apps.adoc
new file mode 100644
index 0000000..fcfb767
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_core-concepts_principles_your-apps.adoc
@@ -0,0 +1,38 @@
+= 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/
+
+
+IMPORTANT: TODO
+
+== Decoupled
+
+IMPORTANT: TODO ...
+
+Long-term Cost of ownership
+
+Using:
+
+* 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
+
+IMPORTANT: TODO
+
+* behaviourally Complete vs Contributions
+
+
+== Testable
+
+IMPORTANT: 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.
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/ef1e765c/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties.adoc
index 22f5eaf..68788ed 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties.adoc
@@ -5,68 +5,13 @@
IMPORTANT: WIP...
-The table below lists the configuration properties recognized by Apache Isis.
+This section lists the configuration properties recognized by Apache Isis.
-.Configuration Properties
-[cols="2,1,3", options="header"]
-|===
-|Property
-|Value +
-(_default value_)
-|Description
+include::_user-guide_reference_configuration-properties_core.adoc[leveloffset=+1]
-|`isis.services`
-|`FQCN`,`FQCN2`,...
-|Fully qualified class names of classes to be instantiated as domain services. Each entry can be optionally prefixed by "n:" specifying the relative order on the menu (corresponds to `@DomainServiceLayout#menuOrder()`).
+include::_user-guide_reference_configuration-properties_wicket-viewer.adoc[leveloffset=+1]
-|`isis.services.` `container.disableAutoFlush`
-|`true`,`_false_`
-|Whether the `DomainObjectContainer` should automatically flush pending changes prior to querying (via `allMatches()`, `firstMatch()` and so on).
+include::_user-guide_reference_configuration-properties_restfulobjects-viewer.adoc[leveloffset=+1]
-|`isis.viewer.wicket.` `disableDependentChoiceAutoSelection`
-|`true`,`_false_`
-|For dependent choices (eg category/subcategory), whether the dependent choice should automatically select the first option, or instead should leave empty
-
-|`isis.viewer.wicket.` `suppressRememberMe`
-|`true`,`_false_`
-|
-
-|`isis.viewer.wicket.` `disableModalDialogs`
-|`true`,`_false_`
-|
-
-|`isis.viewer.wicket.` `stripWicketTags`
-|`true`,`false`
-| Whether to force Wicket tags to be stripped. The default is for them to be stripped in production (Isis' SERVER mode == Wicket DEPLOYMENT mode), but not stripped otherwise (Isis' DEPLOYMENT mode == Wicket DEVELOPMENT mode)
-
-|`isis.viewer.wicket.` `bookmarkedPages`
-| +ve int (`_15_`)
-| number of pages to bookmark
-
-
-|`isis.viewer.wicket.` `regularCase`
-| `true`,`_false_`
-| Ignored for 1.8.0+; in earlier versions forced regular case rather than title case in the UI
-
-|`isis.viewer.wicket.` `disableDependentChoiceAutoSelection`
-| `true`,`_false_`
-| For dependent choices, whether to automatically select the first dependent (eg subcategory) when the parameter on which it depends (category) changes.
-
-|`isis.persistor.datanucleus.impl.*`
-|
-| Passed through directly to Datanucleus (with prefix stripped)
-
-|`isis.persistor.datanucleus.` `RegisterEntities.packagePrefix`
-| fully qualified package names (CSV)
-| of class names; specifies the entities early rather than allow DataNucleus to find the entities lazily. Strongly recommended (subtle issues can sometimes arise if lazy discovery is used).
-
-|`isis.persistor.datanucleus.` `PublishingService.serializedForm`
-| zipped
-|
-
-|`isis.persistor.disableConcurrencyChecking`
-|`true`,`_false_`
-| Disables concurrency checking globally. Only intended for "emergency use" as a workaround while pending fix/patch to Isis itself.
-
-|===
+include::_user-guide_reference_configuration-properties_datanucleus-objectstore.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/ef1e765c/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties_core.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties_core.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties_core.adoc
new file mode 100644
index 0000000..d848f8d
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties_core.adoc
@@ -0,0 +1,32 @@
+= Core
+: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/
+
+IMPORTANT: WIP...
+
+.Core Configuration Properties
+[cols="2a,1,3a", options="header"]
+|===
+|Property
+|Value +
+(_default value_)
+|Description
+
+|`isis.services`
+|`FQCN`,`FQCN2`,...
+|Fully qualified class names of classes to be instantiated as domain services. Each entry can be optionally prefixed by "n:" specifying the relative order on the menu (corresponds to `@DomainServiceLayout#menuOrder()`).
+
+|`isis.services.` +
+`container.disableAutoFlush`
+|`true`,`_false_`
+|Whether the `DomainObjectContainer` should automatically flush pending changes prior to querying (via `allMatches()`, `firstMatch()` and so on).
+
+|`isis.persistor.` +
+`disableConcurrencyChecking`
+|`true`,`_false_`
+| Disables concurrency checking globally. Only intended for "emergency use" as a workaround while pending fix/patch to Isis itself. (Note that there is no "datanucleus" in the property).
+
+|===
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/ef1e765c/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties_datanucleus-objectstore.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties_datanucleus-objectstore.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties_datanucleus-objectstore.adoc
new file mode 100644
index 0000000..6db85ef
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties_datanucleus-objectstore.adoc
@@ -0,0 +1,44 @@
+= JDO/Datanucleus Objectstore
+: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/
+
+IMPORTANT: WIP...
+
+These configuration properties are typically stored in `WEB-INF/persistor_datanucleus.properties`. However, you can place all configuration properties into `WEB-INF/isis.properties` if you wish (the configuration properties from all config files are merged together).
+
+.JDO/DataNucleus Objectstore Configuration Properties
+[cols="2a,1,3a", options="header"]
+|===
+|Property
+|Value +
+(_default value_)
+|Description
+
+|`isis.persistor.datanucleus.` +
+`impl.*`
+|
+| Passed through directly to Datanucleus (with `isis.persistor.datanucleus.impl` prefix stripped)
+
+|`isis.persistor.datanucleus.impl` +
+`.datanucleus.persistenceByReachabilityAtCommit
+|false
+|We recommend this setting is disabled. +
+Further <<_disabling_persistence_by_reachability, discussion below>>.
+
+|`isis.persistor.datanucleus.` +
+`RegisterEntities.packagePrefix`
+| fully qualified package names (CSV)
+| of class names; specifies the entities early rather than allow DataNucleus to find the entities lazily. Strongly recommended (subtle issues can sometimes arise if lazy discovery is used).
+Further <<_registering_entity_types, discussion below>>.
+
+|`isis.persistor.datanucleus.` +
+`PublishingService.serializedForm`
+| zipped
+|
+
+|===
+
+include::_user-guide_reference_configuration-properties_datanucleus-objectstore_disabling-persistence-by-reachability.adoc[leveloffset=+1]
+
+include::_user-guide_reference_configuration-properties_datanucleus-objectstore_eagerly-registering-entities.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/ef1e765c/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties_datanucleus-objectstore_disabling-persistence-by-reachability.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties_datanucleus-objectstore_disabling-persistence-by-reachability.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties_datanucleus-objectstore_disabling-persistence-by-reachability.adoc
new file mode 100644
index 0000000..5c0b109
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties_datanucleus-objectstore_disabling-persistence-by-reachability.adoc
@@ -0,0 +1,93 @@
+= Disabling Persistence by Reachability
+: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/
+
+By default, JDO/DataNucleus supports the concept of http://www.datanucleus.org/products/datanucleus/jdo/orm/cascading.html[persistence-by-reachability]. That is, if
+a non-persistent entity is associated with an already-persistent entity, then DataNucleus will detect this and will automatically persist the associated object. Put another way: there is no need to call Isis' `DomainObjectContainer#persist(.)` or `DomainObjectContainer#persistIfNotAlready(.)` methods.
+
+However, convenient though this feature is, you may find that it causes performance issues.
+
+[WARNING]
+====
+DataNucleus' persistence-by-reachability may cause performance issues. We strongly recommend that you disable it.
+====
+
+One scenario in particular where this performance issues can arise is if your entities implement the `java.lang.Comparable` interface, and you have used Isis' link:../../../reference/Utility.html[ObjectContracts] utility. The issue here is that `ObjectContracts` implementation can cause DataNucleus to recursively rehydrate a larger number of associated entities. (More detail below).
+
+We therefore recommend that you disable persistence-by-reachability by adding the following to `persistor_datanucleus.properties`:
+
+[source,ini]
+----
+isis.persistor.datanucleus.impl.datanucleus.persistenceByReachabilityAtCommit=false
+----
+
+This change has been made to the <<_simpleapp_archetype, SimpleApp Archetype>>
+
+If you do disable this feature, then you will (of course) need to ensure that you explicitly persist all entities using the `DomainObjectContainer#persist(.)` or `DomainObjectContainer#persistIfNotAlready(.)` methods.
+
+== Explanation of the issue in more detail
+
+Consider the entities:
+
+image::{_imagesdir}reference/configuration-properties/datanucleus-objectstore/party-agreementrole-agreement.png[width="750px"]
+
+
+[TIP]
+====
+[source]
+.DSL (http://yuml.me/edit/b8681268[yuml.me/b8681268])
+----
+[Party|reference]<--->*[AgreementRole|startDate]
+[AgreementRole]*<-->[Agreement|reference]
+----
+====
+
+
+In the course of a transaction, the `Agreement` entity is loaded into memory (not necessarily modified), and then new ``AgreementRole``s are associated to it.
+
+All these entities implement `Comparable` using `ObjectContracts`, and the implementation of ``AgreementRole``'s (simplified) is:
+
+[source,java]
+----
+public class AgreementRole {
+ ...
+ public int compareTo(AgreementRole other) {
+ return ObjectContracts.compareTo(this, other, "agreement","startDate","party");
+ }
+}
+----
+
+while ``Agreement``'s is implemented as:
+
+[source,java]
+----
+public class Agreement {
+ ...
+ public int compareTo(Agreement other) {
+ return ObjectContracts.compareTo(this, other, "reference");
+ }
+}
+----
+
+and ``Party``'s is similarly implemented as:
+
+[source,java]
+----
+public class Party {
+ ...
+ public int compareTo(Party other) {
+ return ObjectContracts.compareTo(this, other, "reference");
+ }
+}
+----
+
+DataNucleus's persistence-by-reachability algorithm adds the `AgreementRole` instances into a `SortedSet`, which causes `AgreementRole#compareTo()` to fire:
+
+* the evaluation of the "agreement" property delegates back to the `Agreement`, whose own `Agreement#compareTo()` uses the scalar `reference` property. As the `Agreement` is already in-memory, this does not trigger any further database queries
+
+* the evaluation of the "startDate" property is just a scalar property of the `AgreementRole`, so will already in-memory
+
+* the evaluation of the "party" property delegates back to the `Party`, whose own `Party#compareTo()` requires the uses the scalar `reference` property. However, since the `Party` is not yet in-memory, using the `reference` property triggers a database query to "rehydrate" the `Party` instance.
+
+In other words, in figuring out whether `AgreementRole` requires the persistence-by-reachability algorithm to run, it causes the adjacent associated entity `Party` to also be retrieved.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/ef1e765c/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties_datanucleus-objectstore_eagerly-registering-entities.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties_datanucleus-objectstore_eagerly-registering-entities.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties_datanucleus-objectstore_eagerly-registering-entities.adoc
new file mode 100644
index 0000000..4275763
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties_datanucleus-objectstore_eagerly-registering-entities.adoc
@@ -0,0 +1,25 @@
+= Eagerly Registering Entity Types
+: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/
+
+[WARNING]
+====
+From 1.6.0+ this feature may be (partly?) broken; see https://issues.apache.org/jira/browse/ISIS-847[ISIS-847].
+====
+
+Both Apache Isis and DataNucleus have their own metamodels of the domain entities. Isis builds its metamodel by walking the graph of types from the services registered using `@DomainService` or explicitly registered in `isis.properties`. The JDO objectstore then takes these types and registers them with DataNucleus.
+
+In some cases, though, not every entity type is discoverable from the API of the service actions. This is especially the case if you have lots of subtypes (where the action method specifies only the supertype). In such cases the Isis and JDO metamodels is built lazily, when an instance of that (sub)type is first encountered.
+
+Isis is quite happy for the metamodel to be lazily created, and - to be fair - DataNucleus also works well in most cases. In some cases, though, we have found that the JDBC driver (eg HSQLDB) will deadlock if DataNucleus tries to submit some DDL (for a lazily discovered type) intermingled with DML (for updating).
+
+In any case, it's probably not good practice to have DataNucleus work this way. The `RegisterEntities` service can therefore be registered in order to do the eager registration. It searches for all `@PersistenceCapable` entities under specified package(s), and registers them all.
+
+
+== Specify the Package Prefix(es)
+
+In the `persistor_datanucleus.properties`, specify the package prefix(es) of your application, to provide a hint for finding the `@PersistenceCapable` classes.
+
+The value of this property can be a comma-separated list (if there is more than one package or Maven module that holds persistable entities).
+
http://git-wip-us.apache.org/repos/asf/isis/blob/ef1e765c/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties_restfulobjects-viewer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties_restfulobjects-viewer.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties_restfulobjects-viewer.adoc
new file mode 100644
index 0000000..a932663
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties_restfulobjects-viewer.adoc
@@ -0,0 +1,21 @@
+= RestfulObjects Viewer
+: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/
+
+IMPORTANT: WIP...
+
+These configuration properties are typically stored in `WEB-INF/viewer_restfulobjects.properties`. However, you can place all configuration properties into `WEB-INF/isis.properties` if you wish (the configuration properties from all config files are merged together).
+
+
+.RestfulObjects Viewer Configuration Properties
+[cols="2a,1,3", options="header"]
+|===
+|Property
+|Value +
+(_default value_)
+|Description
+
+|===
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/ef1e765c/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties_wicket-viewer.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties_wicket-viewer.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties_wicket-viewer.adoc
new file mode 100644
index 0000000..e613d3a
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_reference_configuration-properties_wicket-viewer.adoc
@@ -0,0 +1,52 @@
+= Wicket Viewer
+: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/
+
+IMPORTANT: WIP...
+
+These configuration properties are typically stored in `WEB-INF/viewer_wicket.properties`. However, you can place all configuration properties into `WEB-INF/isis.properties` if you wish (the configuration properties from all config files are merged together).
+
+
+.Wicket Viewer Configuration Properties
+[cols="2a,1,3", options="header"]
+|===
+|Property
+|Value +
+(_default value_)
+|Description
+
+|`isis.viewer.wicket.` +
+`suppressRememberMe`
+|`true`,`_false_`
+|
+
+|`isis.viewer.wicket.` +
+`disableModalDialogs`
+|`true`,`_false_`
+|
+
+|`isis.viewer.wicket.` +
+`stripWicketTags`
+|`true`,`false`
+| Whether to force Wicket tags to be stripped. +
+The default is for them to be stripped in production (Isis' SERVER mode == Wicket DEPLOYMENT mode), but not stripped otherwise (Isis' PROTOTYPE mode == Wicket DEVELOPMENT mode)
+
+|`isis.viewer.wicket.` +
+`bookmarkedPages`
+| +ve int (`_15_`)
+| number of pages to bookmark
+
+
+|`isis.viewer.wicket.` +
+`regularCase`
+| `true`,`_false_`
+| Ignored for 1.8.0+; in earlier versions forced regular case rather than title case in the UI
+
+|`isis.viewer.wicket.` `disableDependentChoiceAutoSelection`
+| `true`,`_false_`
+| For dependent choices, whether to automatically select the first dependent (eg subcategory) when the parameter on which it depends (category) changes.
+
+|===
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/ef1e765c/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_troubleshooting.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_troubleshooting.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_troubleshooting.adoc
index 5aa8cb0..fd42f26 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_troubleshooting.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_troubleshooting.adoc
@@ -5,9 +5,9 @@
IMPORTANT: TODO
-## JDO/DataNucleus Logging
+## Logging
-include::_user-guide_troubleshooting_datanucleus-logging.adoc[leveloffset=+1]
+include::_user-guide_troubleshooting_enabling-logging.adoc[leveloffset=+1]
http://git-wip-us.apache.org/repos/asf/isis/blob/ef1e765c/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_troubleshooting_datanucleus-logging.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_troubleshooting_datanucleus-logging.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_troubleshooting_datanucleus-logging.adoc
deleted file mode 100644
index b6023b0..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_troubleshooting_datanucleus-logging.adoc
+++ /dev/null
@@ -1,10 +0,0 @@
-= Trouble Shooting: DataNucleus Logging
-: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/
-
-IMPORTANT: TODO
-
-
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/ef1e765c/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_troubleshooting_enabling-logging.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_troubleshooting_enabling-logging.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_troubleshooting_enabling-logging.adoc
new file mode 100644
index 0000000..533273c
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_troubleshooting_enabling-logging.adoc
@@ -0,0 +1,38 @@
+= Enabling Logging
+: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/
+
+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
+
+Modify `WEB-INF/logging.properties` (a log4j config file)
+
+== In DataNucleus
+
+As per the http://www.datanucleus.org/products/accessplatform/logging.html[DN logging page]
+
+== 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 <<_simpleapp_archetype, SimpleApp archetype>>.
+
+== In the Database
+
+=== HSQLDB Logging
+
+Add `;sqllog=3` to the end of the JDBC URL.
+
+=== PostgreSQL Logging
+
+In `postgresql\9.2\data\postgresql.conf`:
+
+Will then log to `postgresql\9.2\data\pg_log` directory.
+
+Note that you must restart the service for this to be picked up.
+
+=== MS SQL Server Logging
+
+Use the excellent SQL Profiler tool.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/ef1e765c/adocs/documentation/src/main/asciidoc/user-guide/images/reference/configuration-properties/datanucleus-objectstore/party-agreementrole-agreement.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/reference/configuration-properties/datanucleus-objectstore/party-agreementrole-agreement.png b/adocs/documentation/src/main/asciidoc/user-guide/images/reference/configuration-properties/datanucleus-objectstore/party-agreementrole-agreement.png
new file mode 100644
index 0000000..67744c9
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/user-guide/images/reference/configuration-properties/datanucleus-objectstore/party-agreementrole-agreement.png differ