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 2018/01/03 14:48:47 UTC
[15/87] [abbrv] [partial] isis-site git commit: adds SNAPSHOT version
http://git-wip-us.apache.org/repos/asf/isis-site/blob/d215fa50/content/versions/SNAPSHOT/guides/ugfun/ugfun.html
----------------------------------------------------------------------
diff --git a/content/versions/SNAPSHOT/guides/ugfun/ugfun.html b/content/versions/SNAPSHOT/guides/ugfun/ugfun.html
new file mode 100644
index 0000000..d2f40d5
--- /dev/null
+++ b/content/versions/SNAPSHOT/guides/ugfun/ugfun.html
@@ -0,0 +1,8902 @@
+<!doctype html>
+<html>
+ <head>
+ <!--
+ 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.
+ -->
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+ <meta charset="utf-8">
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
+ <!-- No caching headers -->
+ <meta http-equiv="cache-control" content="no-cache">
+ <meta http-equiv="pragma" content="no-cache">
+ <meta http-equiv="expires" content="-1">
+ <title>Fundamentals</title>
+ <link rel="icon" type="image/png" href="../../images/isis-favicon.png">
+ <!--
+ Based on DataNucleus' template,
+ that was in turn based on an earlier version of Apache Isis' template,
+ that was in turn based on Apache Deltaspike's template.
+
+ This template uses
+ * Bootstrap v3.3.7 (https://getbootstrap.com/) for navbar.
+ * Bootstrap TOC plugin v0.4.1 (https://afeld.github.io/bootstrap-toc/)
+ for the table of contents.
+ * jQuery (necessary for Bootstrap's JavaScript plugins)
+ * Font-Awesome for some icons used by Asciidoctor
+
+ Also:
+ * Bootswatch "flatly" theme for Bootstrap (https://bootswatch.com/flatly).
+ * slick.js (carousel)
+ * add a link to all headers (home-grown, adapted from blog posts)
+ * integration of elasticlunr.js (home-grown, adapted from blog posts)
+ -->
+ <link href="https://cdnjs.cloudflare.com/ajax/libs/bootswatch/3.3.7/flatly/bootstrap.min.css" rel="stylesheet">
+ <link href="../../css/bootstrap-toc/0.4.1/bootstrap-toc.min.css" rel="stylesheet">
+ <link href="../../css/asciidoctor/foundation.css" rel="stylesheet">
+ <link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.3.0/css/font-awesome.min.css" rel="stylesheet">
+ <link href="../../css/slick/1.5.0/slick.css" rel="stylesheet">
+ <link href="../../css/slick/1.5.0/slick-theme.css" rel="stylesheet">
+ <link href="../../css/search-panel/search-panel.css" rel="stylesheet">
+ <link href="../../css/header-links/header-links.css" rel="stylesheet">
+ <link href="../../css/sticky-header/sticky-header.css" rel="stylesheet">
+ <link href="../../css/customisations.css" rel="stylesheet">
+ <!-- Coderay syntax formatter -->
+ <style type="text/css">
+ /* Stylesheet for CodeRay to match GitHub theme | MIT License | http://foundation.zurb.com */
+/*pre.CodeRay {background-color:#f7f7f8;}*/
+.CodeRay .line-numbers{border-right:1px solid #d8d8d8;padding:0 0.5em 0 .25em}
+.CodeRay span.line-numbers{display:inline-block;margin-right:.5em;color:rgba(0,0,0,.3)}
+.CodeRay .line-numbers strong{color:rgba(0,0,0,.4)}
+table.CodeRay{border-collapse:separate;border-spacing:0;margin-bottom:0;border:0;background:none}
+table.CodeRay td{vertical-align: top;line-height:1.45}
+table.CodeRay td.line-numbers{text-align:right}
+table.CodeRay td.line-numbers>pre{padding:0;color:rgba(0,0,0,.3)}
+table.CodeRay td.code{padding:0 0 0 .5em}
+table.CodeRay td.code>pre{padding:0}
+.CodeRay .debug{color:#fff !important;background:#000080 !important}
+.CodeRay .annotation{color:#007}
+.CodeRay .attribute-name{color:#000080}
+.CodeRay .attribute-value{color:#700}
+.CodeRay .binary{color:#509}
+.CodeRay .comment{color:#998;font-style:italic}
+.CodeRay .char{color:#04d}
+.CodeRay .char .content{color:#04d}
+.CodeRay .char .delimiter{color:#039}
+.CodeRay .class{color:#458;font-weight:bold}
+.CodeRay .complex{color:#a08}
+.CodeRay .constant,.CodeRay .predefined-constant{color:#008080}
+.CodeRay .color{color:#099}
+.CodeRay .class-variable{color:#369}
+.CodeRay .decorator{color:#b0b}
+.CodeRay .definition{color:#099}
+.CodeRay .delimiter{color:#000}
+.CodeRay .doc{color:#970}
+.CodeRay .doctype{color:#34b}
+.CodeRay .doc-string{color:#d42}
+.CodeRay .escape{color:#666}
+.CodeRay .entity{color:#800}
+.CodeRay .error{color:#808}
+.CodeRay .exception{color:inherit}
+.CodeRay .filename{color:#099}
+.CodeRay .function{color:#900;font-weight:bold}
+.CodeRay .global-variable{color:#008080}
+.CodeRay .hex{color:#058}
+.CodeRay .integer,.CodeRay .float{color:#099}
+.CodeRay .include{color:#555}
+.CodeRay .inline{color:#000}
+.CodeRay .inline .inline{background:#ccc}
+.CodeRay .inline .inline .inline{background:#bbb}
+.CodeRay .inline .inline-delimiter{color:#d14}
+.CodeRay .inline-delimiter{color:#d14}
+.CodeRay .important{color:#555;font-weight:bold}
+.CodeRay .interpreted{color:#b2b}
+.CodeRay .instance-variable{color:#008080}
+.CodeRay .label{color:#970}
+.CodeRay .local-variable{color:#963}
+.CodeRay .octal{color:#40e}
+.CodeRay .predefined{color:#369}
+.CodeRay .preprocessor{color:#579}
+.CodeRay .pseudo-class{color:#555}
+.CodeRay .directive{font-weight:bold}
+.CodeRay .type{font-weight:bold}
+.CodeRay .predefined-type{color:inherit}
+.CodeRay .reserved,.CodeRay .keyword {color:#000;font-weight:bold}
+.CodeRay .key{color:#808}
+.CodeRay .key .delimiter{color:#606}
+.CodeRay .key .char{color:#80f}
+.CodeRay .value{color:#088}
+.CodeRay .regexp .delimiter{color:#808}
+.CodeRay .regexp .content{color:#808}
+.CodeRay .regexp .modifier{color:#808}
+.CodeRay .regexp .char{color:#d14}
+.CodeRay .regexp .function{color:#404;font-weight:bold}
+.CodeRay .string{color:#d20}
+.CodeRay .string .string .string{background:#ffd0d0}
+.CodeRay .string .content{color:#d14}
+.CodeRay .string .char{color:#d14}
+.CodeRay .string .delimiter{color:#d14}
+.CodeRay .shell{color:#d14}
+.CodeRay .shell .delimiter{color:#d14}
+.CodeRay .symbol{color:#990073}
+.CodeRay .symbol .content{color:#a60}
+.CodeRay .symbol .delimiter{color:#630}
+.CodeRay .tag{color:#008080}
+.CodeRay .tag-special{color:#d70}
+.CodeRay .variable{color:#036}
+.CodeRay .insert{background:#afa}
+.CodeRay .delete{background:#faa}
+.CodeRay .change{color:#aaf;background:#007}
+.CodeRay .head{color:#f8f;background:#505}
+.CodeRay .insert .insert{color:#080}
+.CodeRay .delete .delete{color:#800}
+.CodeRay .change .change{color:#66f}
+.CodeRay .head .head{color:#f4f}
+ </style>
+ </head>
+ <body data-spy="scroll" data-target="#toc">
+ <div id="basedir" style="display:none;">
+ ../../
+ </div>
+ <div id="docname" style="display:none;">
+ ugfun
+ </div>
+ <div id="filetype" style="display:none;">
+ html
+ </div>
+ <!-- Navbar -->
+ <nav class="navbar navbar-default navbar-static-top header">
+ <div class="container">
+ <div class="navbar-header">
+ <!-- Three line menu button for use on mobile screens -->
+ <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar" aria-expanded="false" aria-controls="navbar"> <span class="sr-only">Toggle navigation</span> <span class="icon-bar"></span> <span class="icon-bar"></span> <span class="icon-bar"></span> </button>
+ <a class="navbar-brand" href="../../index.html"> <img alt="Brand" src="../../images/isis-logo-48x48.png"> </a>
+ <a class="navbar-brand" href="../../index.html">Apache Isis</a>
+ </div>
+ <!-- Navbar that will collapse on mobile screens -->
+ <div id="navbar" class="navbar-collapse collapse">
+ <ul class="nav navbar-nav">
+ <li class="dropdown"> <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">Documentation<span class="caret"></span></a>
+ <ul class="dropdown-menu">
+ <li><a href="../../documentation.html">Table of Contents</a></li>
+ <li role="separator" class="divider"></li>
+ <li class="dropdown-header">User Guides</li>
+ <li><a href="../../guides/ugfun/ugfun.html">Fundamentals</a></li>
+ <li><a href="../../guides/ugvw/ugvw.html">Wicket Viewer</a></li>
+ <li><a href="../../guides/ugvro/ugvro.html">Restful Objects Viewer</a></li>
+ <li><a href="../../guides/ugodn/ugodn.html">DataNucleus Object Store</a></li>
+ <li><a href="../../guides/ugsec/ugsec.html">Security</a></li>
+ <li><a href="../../guides/ugtst/ugtst.html">Testing</a></li>
+ <li><a href="../../guides/ugbtb/ugbtb.html">Beyond the Basics</a></li>
+ <li role="separator" class="divider"></li>
+ <li class="dropdown-header">Reference Guides</li>
+ <li><a href="../../guides/rgant/rgant.html">Annotations</a></li>
+ <li><a href="../../guides/rgsvc/rgsvc.html">Domain Services</a></li>
+ <li><a href="../../guides/rgcfg/rgcfg.html">Core Config' Properties</a></li>
+ <li><a href="../../guides/rgcms/rgcms.html">Classes, Methods and Schema</a></li>
+ <li><a href="../../guides/rgmvn/rgmvn.html">Maven plugin</a></li>
+ <li><a href="../../guides/rgfis/rgfis.html">Framework Internal Services</a></li>
+ <li role="separator" class="divider"></li>
+ <li class="dropdown-header">Javadoc</li>
+ <li><a href="http://javadoc.io/doc/org.apache.isis.core/isis-core-applib">Applib</a></li>
+ </ul> </li>
+ <li class="dropdown hidden-sm hidden-md"> <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">Downloads<span class="caret"></span></a>
+ <ul class="dropdown-menu">
+ <li class="dropdown-header">Maven archetypes</li>
+ <li><a href="../../guides/ugfun/ugfun.html#_ugfun_getting-started_helloworld-archetype">helloworld</a></li>
+ <li><a href="../../guides/ugfun/ugfun.html#_ugfun_getting-started_simpleapp-archetype">simpleapp</a></li>
+ <li role="separator" class="divider"></li>
+ <li><a href="../../downloads.html">Downloads</a></li>
+ <li><a href="../../release-notes/release-notes.html">Release Notes</a></li>
+ <li><a href="../../migration-notes/migration-notes.html">Migration Notes</a></li>
+ <li role="separator" class="divider"></li>
+ <li><a href="https://github.com/apache/isis">Github mirror</a></li>
+ </ul> </li>
+ <li class="dropdown hidden-sm"> <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">Support<span class="caret"></span></a>
+ <ul class="dropdown-menu">
+ <li class="dropdown-header">Guides</li>
+ <li><a href="../../guides/dg/dg.html">Developers' Guide</a></li>
+ <li><a href="../../guides/cgcom/cgcom.html">Committers' Guide</a></li>
+ <li><a href="../../guides/htg.html">Hints-n-Tips Guide</a></li>
+ <li role="separator" class="divider"></li>
+ <li class="dropdown-header">Mailing Lists</li>
+ <li><a href="../../support.html">How to subscribe</a></li>
+ <li><a href="https://lists.apache.org/list.html?users@isis.apache.org">Archives (ASF Pony mail)</a></li>
+ <li><a href="http://isis.markmail.org/search/?q=">Archives (Markmail)</a></li>
+ <li role="separator" class="divider"></li>
+ <li class="dropdown-header">Other Resources</li>
+ <li><a href="https://issues.apache.org/jira/browse/ISIS">ASF JIRA</a></li>
+ <li><a href="http://stackoverflow.com/questions/tagged/isis">Stack Overflow</a></li>
+ <li><a href="../../help.html">Wiki, Fisheye etc.</a></li>
+ </ul> </li>
+ <li class="dropdown hidden-sm hidden-md"> <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-haspopup="true" aria-expanded="false">@ASF<span class="caret"></span></a>
+ <ul class="dropdown-menu">
+ <li><a href="http://www.apache.org/">Apache Homepage</a></li>
+ <li><a href="http://www.apache.org/licenses/">Licenses</a></li>
+ <li><a href="http://www.apache.org/security/">Security</a></li>
+ <li><a href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li>
+ <li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+ <li role="separator" class="divider"></li>
+ <li><a href="https://whimsy.apache.org/board/minutes/Isis.html">PMC board minutes</a></li>
+ </ul> </li>
+ </ul>
+ <div class="nav navbar-nav navbar-right">
+ <!-- 'style' added to fix height of input box. FIX THIS -->
+ <form class="navbar-form" role="search" id="search-form" style="padding: 1px 15px;">
+ <div class="form-group">
+ <input class="form-control" id="search-field" type="text" size="30" placeholder="Search">
+ </div>
+ </form>
+ </div>
+ </div>
+ </div>
+ </nav>
+ <div class="container">
+ <div class="row-fluid">
+ <div class="col-xs-12 col-sm-12 col-md-12 col-lg-9">
+ <div id="search-panel">
+ <div id="search-results"></div>
+ <div>
+ <br>
+ <a href="#" id="search-results-clear">clear</a>
+ </div>
+ </div>
+ <span class="pdf-link"><a href="ugfun.pdf"><img src="../../images/PDF-50.png"></a></span>
+ <div class="page-title">
+ <h1>Fundamentals</h1>
+ </div>
+ <div id="doc-content">
+ <div class="btn-group" style="float: right; font-size: small; padding: 6px; ">
+ <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugfun/ugfun.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
+ <button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
+ <ul class="dropdown-menu">
+ <li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugfun/ugfun.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
+ <li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/ugfun/ugfun.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
+ <li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/ugfun/ugfun.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
+ <li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/ugfun/ugfun.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
+ </ul>
+ </div>
+ <div class="sect1">
+ <h2 id="__ugfun">1. Fundamentals</h2>
+ <div class="sectionbody">
+ <div class="paragraph">
+ <p>This guide introduces the <a href="../ugfun/ugfun.html#_ugfun_core-concepts">core concepts</a> and ideas behind Apache Isis, and tells you how to <a href="../ugfun/ugfun.html#_ugfun_getting-started">get started</a> with a Maven archetype.</p>
+ </div>
+ <div class="paragraph">
+ <p>It also describes a number of <a href="../ugfun/ugfun.html#_ugfun_how-tos">how-to</a>s, describes how to influence the <a href="../ugvw/ugvw.html#_ugvw_layout">UI layout</a> of your domain objects (this is ultimately just a type of metadata), and it catalogues various <a href="../dg/dg.html#_dg_hints-and-tips.adoc">FAQ</a>s.</p>
+ </div>
+ <div class="sect2">
+ <h3 id="_other_guides">1.1. Other Guides</h3>
+ <div class="paragraph">
+ <p>Apache Isis documentation is broken out into a number of user, reference and "supporting procedures" guides.</p>
+ </div>
+ <div class="paragraph">
+ <p>The user guides available are:</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p><a href="../ugfun/ugfun.html">Fundamentals</a> (this guide)</p> </li>
+ <li> <p><a href="../ugvw/ugvw.html">Wicket viewer</a></p> </li>
+ <li> <p><a href="../ugvro/ugvro.html">Restful Objects viewer</a></p> </li>
+ <li> <p><a href="../ugodn/ugodn.html">DataNucleus object store</a></p> </li>
+ <li> <p><a href="../ugsec/ugsec.html">Security</a></p> </li>
+ <li> <p><a href="../ugtst/ugtst.html">Testing</a></p> </li>
+ <li> <p><a href="../ugbtb/ugbtb.html">Beyond the Basics</a></p> </li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>The reference guides are:</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p><a href="../rgant/rgant.html">Annotations</a></p> </li>
+ <li> <p><a href="../rgsvc/rgsvc.html">Domain Services</a></p> </li>
+ <li> <p><a href="../rgcfg/rgcfg.html">Configuration Properties</a></p> </li>
+ <li> <p><a href="../rgcms/rgcms.html">Classes, Methods and Schema</a></p> </li>
+ <li> <p><a href="../rgmvn/rgmvn.html">Apache Isis Maven plugin</a></p> </li>
+ <li> <p><a href="../rgfis/rgfis.html">Framework Internal Services</a></p> </li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>The remaining guides are:</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p><a href="../dg/dg.html">Developers' Guide</a> (how to set up a development environment for Apache Isis and contribute back to the project)</p> </li>
+ <li> <p><a href="../cgcom/cgcom.html">Committers' Guide</a> (release procedures and related practices)</p> </li>
+ </ul>
+ </div>
+ </div>
+ </div>
+ </div>
+ <div class="sect1">
+ <h2 id="_ugfun_core-concepts">2. Core Concepts</h2>
+ <div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
+ <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
+ <button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
+ <ul class="dropdown-menu">
+ <li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
+ <li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
+ <li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
+ <li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
+ </ul>
+ </div>
+ <div class="sectionbody">
+ <div class="paragraph">
+ <p>This introductory chapter should give you a good about what Apache Isis actually <strong>is</strong>: the fundamental ideas and principles that it builds upon, how it compares with other frameworks, what the fundamental building blocks are for actually writing an Isis application, and what services and features the framework provides for you to leverage in your own apps.</p>
+ </div>
+ <div class="paragraph">
+ <p>Parts of this chapter have been adapted from Dan Haywood’s 2009 book, 'Domain Driven Design using Naked Objects'. We’ve also added some new insights and made sure the material we’ve used is relevant to Apache Isis.</p>
+ </div>
+ <div class="sect2">
+ <h3 id="_ugfun_core-concepts_philosophy">2.1. Philosophy and Architecture</h3>
+ <div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
+ <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
+ <button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
+ <ul class="dropdown-menu">
+ <li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
+ <li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
+ <li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
+ <li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>This section describes some of the core ideas and architectural patterns upon which Apache Isis builds.</p>
+ </div>
+ <div class="sect3">
+ <h4 id="_ugfun_core-concepts_philosophy_domain-driven-design">2.1.1. Domain-Driven Design</h4>
+ <div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
+ <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_domain-driven-design.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
+ <button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
+ <ul class="dropdown-menu">
+ <li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_domain-driven-design.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
+ <li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_domain-driven-design.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
+ <li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_domain-driven-design.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
+ <li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_domain-driven-design.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>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.</p>
+ </div>
+ <div class="paragraph">
+ <p>A couple of years back Eric Evans wrote his book <a href="http://www.amazon.co.uk/Domain-driven-Design-Tackling-Complexity-Software/dp/0321125215">Domain-Driven Design</a>, 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.</p>
+ </div>
+ <div class="paragraph">
+ <p>There are two central ideas at the heart of domain-driven design.</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p>the <strong><em>ubiquitous language</em></strong> is about getting the whole team (both domain experts and developers) to communicate more transparently using a domain model.</p> </li>
+ <li> <p>Meanwhile, <strong><em>model-driven design</em></strong> is about capturing that model in a very straightforward manner in code.</p> </li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>Let’s look at each in turn.</p>
+ </div>
+ <div class="sect4">
+ <h5 id="__ugfun_core-concepts_philosophy_domain-driven-design_ubiquitous-language">Ubiquitous Language</h5>
+ <div class="paragraph">
+ <p>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.</p>
+ </div>
+ <div class="paragraph">
+ <p>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.</p>
+ </div>
+ <div class="paragraph">
+ <p>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.</p>
+ </div>
+ <div class="paragraph">
+ <p>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.</p>
+ </div>
+ <div class="paragraph">
+ <p>Rather than trying to translate between a business language and a technical language, with <em>DDD</em> we aim to have the business and developers using the same terms for the same concepts in order to create a single <strong><em>domain model</em></strong>. 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.</p>
+ </div>
+ <div class="sidebarblock">
+ <div class="content">
+ <div class="title">
+ Ubiquitous Language
+ </div>
+ <div class="paragraph">
+ <p>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.</p>
+ </div>
+ <div class="paragraph">
+ <p>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.</p>
+ </div>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>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.</p>
+ </div>
+ <div class="paragraph">
+ <p>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 <strong>ubiquitous language</strong> demands that the developers work hard to understand the problem domain, but it also demands that the business works hard in being <strong>precise</strong> in its naming and descriptions of those concepts. After all, ultimately the developers will have to express those concepts in a computer programming language.</p>
+ </div>
+ <div class="paragraph">
+ <p>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"?</p>
+ </div>
+ <div class="paragraph">
+ <p>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.</p>
+ </div>
+ <div class="paragraph">
+ <p>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.</p>
+ </div>
+ <div class="paragraph">
+ <p>We use the ubiquitous language to build up a domain model. But what do we do <strong>with</strong> that model? The answer to that is the second of our central ideas.</p>
+ </div>
+ </div>
+ <div class="sect4">
+ <h5 id="_model_driven_design">Model-Driven Design</h5>
+ <div class="paragraph">
+ <p>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 <em>OMG</em>'s Model-Driven Architecture ( <em>MDA</em>) initiative, with its platform-independent model (the <em>PIM</em>) and a platform-specific model (the <em>PSM</em>).</p>
+ </div>
+ <div class="paragraph">
+ <p>Bah and humbug! If we use our ubiquitous language just to build up a high-level analysis model, then we will re-create the communication divide. The domain experts and business analysts will look only to the analysis model, and the developers will look only to the implementation model. Unless the mapping between the two is completely mechanical, inevitably the two will diverge.</p>
+ </div>
+ <div class="paragraph">
+ <p>What do we mean by <strong>model</strong> 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 <strong>representation</strong> 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.</p>
+ </div>
+ <div class="paragraph">
+ <p>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.</p>
+ </div>
+ <div class="sidebarblock">
+ <div class="content">
+ <div class="title">
+ Model-Driven Design
+ </div>
+ <div class="paragraph">
+ <p>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.</p>
+ </div>
+ <div class="paragraph">
+ <p>Changing the code means changing the model; refining the model requires a change to the code.</p>
+ </div>
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>Here also the word <strong>design</strong> might mislead; some might be thinking of design documents and design diagrams, or perhaps of user interface (UX) design. But by <strong>design</strong> we mean a way of organizing the domain concepts, which in turn leads to the way in which we organize their representation in code.</p>
+ </div>
+ <div class="paragraph">
+ <p>Luckily, using <strong><em>object-oriented</em></strong> (<em>OO</em>) languages such as Java, this is relatively easy to do; <em>OO</em> 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.</p>
+ </div>
+ <div class="paragraph">
+ <p>So far so good. Or maybe, so far so much motherhood and apple pie. Understanding the <em>DDD</em> concepts isn’t the same as being able to apply them, and some of the <em>DDD</em> 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 <em>DDD</em> in a very concrete way.</p>
+ </div>
+ </div>
+ </div>
+ <div class="sect3">
+ <h4 id="_ugfun_core-concepts_philosophy_naked-objects-pattern">2.1.2. Naked Objects Pattern</h4>
+ <div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
+ <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_naked-objects-pattern.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
+ <button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
+ <ul class="dropdown-menu">
+ <li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_naked-objects-pattern.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
+ <li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_naked-objects-pattern.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
+ <li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_naked-objects-pattern.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
+ <li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_naked-objects-pattern.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>Apache Isis implements the naked objects pattern, originally formulated by Richard Pawson. So who better than Richard to explain the origination of the idea:</p>
+ </div>
+ <div class="quoteblock">
+ <blockquote>
+ <div class="paragraph">
+ <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.</p>
+ </div>
+ <div class="paragraph">
+ <p>A common complaint from <em>DDD</em> 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.</p>
+ </div>
+ <div class="paragraph">
+ <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.</p>
+ </div>
+ <div class="paragraph">
+ <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 <em>CAD</em> system. Most business systems are not at all expressive; they treat the user merely as a dumb <strong>process-follower</strong>, rather than as an empowered <strong>problem-solver</strong>. 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 (<em>OOUI</em>). In practice, though, <em>OOUI</em>s were notoriously hard to develop.</p>
+ </div>
+ <div class="paragraph">
+ <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 <em>UI</em> 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.</p>
+ </div>
+ </blockquote>
+ </div>
+ <div class="paragraph">
+ <p>You can learn much more about the pattern in the book, <a href="http://www.amazon.com/exec/obidos/ISBN=0470844205/">Naked Objects</a>, also freely available to <a href="http://www.nakedobjects.org/book/">read online</a>. Richard co-wrote the book with one of Apache Isis' committers, Robert Matthews, who was in turn the author of the Naked Objects Framework for Java (the original codebase of of Apache Isis).</p>
+ </div>
+ <div class="paragraph">
+ <p>You might also want to read Richard’s <a href="resources/core-concepts/Pawson-Naked-Objects-thesis.pdf">PhD on the subject</a>.</p>
+ </div>
+ <div class="admonitionblock tip">
+ <table>
+ <tbody>
+ <tr>
+ <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td>
+ <td class="content">
+ <div class="paragraph">
+ <p>One of the external examiners for Richard’s PhD was <a href="http://en.wikipedia.org/wiki/Trygve_Reenskaug">Trygve Reenskaug</a>, who originally formulated the MVC pattern at Xeroc PARC. In his paper, <a href="http://heim.ifi.uio.no/~trygver/2007/2007.02.13-babyUML.pdf">Baby UML</a>, 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.</p>
+ </div>
+ <div class="paragraph">
+ <p>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."</p>
+ </div>
+ <div class="paragraph">
+ <p>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 (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a> the gmap3 wicket extension renders any object with latitude/longitude on a map, while fullcalendar2 renders any object with date(s) on a calendar.</p>
+ </div> </td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div class="sect4">
+ <h5 id="_ugfun_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping">Object Interface Mapping</h5>
+ <div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
+ <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
+ <button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
+ <ul class="dropdown-menu">
+ <li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
+ <li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
+ <li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
+ <li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>Another — more technical — way to think about the naked objects pattern is as an <em>object interface mapper</em>, or <code>OIM</code>. We sometimes use this idea to explain naked objects to a bunch of developers.</p>
+ </div>
+ <div class="paragraph">
+ <p>Just as an ORM (such as <a href="http://datanucleus.org">DataNucleus</a> or <a href="http://hibernate.org">Hibernate</a>) 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.</p>
+ </div>
+ <div class="paragraph">
+ <p>This is the way that the <a href="http://metawidget.org/">MetaWidget</a> team, in particular Richard Kennard, the primary contributor, likes to describe their tool. MetaWidget has a number of ideas in common with Apache Isis (we compare Apache Isis' with MetaWidget <a href="../ugfun/ugfun.html#_ugfun_core-concepts_principles_apache-isis-vs_metawidget">here</a>), in particular the runtime generation of a UI for domain objects. You can hear more from Kennard and others on this <a href="http://devchat.tv/js-jabber/150-jsj-oims">Javascript Jabber podcast</a>.</p>
+ </div>
+ </div>
+ <div class="sect4">
+ <h5 id="_what_this_means_in_practice">What this means in practice</h5>
+ <div class="paragraph">
+ <p>This <a href="https://www.youtube.com/watch?v=ludOLyi6VyY">screencast</a> shows what all of this means in practice, showing the relationship between a running app and the actual code underneath.</p>
+ </div>
+ <div class="admonitionblock note">
+ <table>
+ <tbody>
+ <tr>
+ <td class="icon"> <i class="fa icon-note" title="Note"></i> </td>
+ <td class="content">
+ <div class="paragraph">
+ <p>This screencast shows Apache Isis v1.0.0, Jan 2013. The UI has been substantially refined since that release.</p>
+ </div> </td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ </div>
+ </div>
+ <div class="sect3">
+ <h4 id="_ugfun_core-concepts_philosophy_hexagonal-architecture">2.1.3. Hexagonal Architecture</h4>
+ <div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
+ <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_hexagonal-architecture.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
+ <button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
+ <ul class="dropdown-menu">
+ <li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_hexagonal-architecture.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
+ <li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_hexagonal-architecture.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
+ <li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_hexagonal-architecture.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
+ <li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_hexagonal-architecture.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>One of the patterns that Evans discusses in his book is that of a <strong>layered architecture</strong>. 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.</p>
+ </div>
+ <div class="paragraph">
+ <p>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.</p>
+ </div>
+ <div class="paragraph">
+ <p>A few years ago Alistair Cockburn reworked the traditional layered architecture diagram and came up with the <strong><em>hexagonal architecture</em></strong>:.</p>
+ </div>
+ <div class="admonitionblock tip">
+ <table>
+ <tbody>
+ <tr>
+ <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td>
+ <td class="content">
+ <div class="paragraph">
+ <p>The hexagonal architecture is also known as the <a href="http://c2.com/cgi/wiki?PortsAndAdaptersArchitecture">Ports and Adapters</a> architecture or (less frequently) as the <a href="http://jeffreypalermo.com/blog/the-onion-architecture-part-1/">Onion</a> architecture.</p>
+ </div> </td>
+ </tr>
+ </tbody>
+ </table>
+ </div>
+ <div class="imageblock">
+ <div class="content">
+ <img src="images/core-concepts/philosophy/hexagonal-architecture.png" alt="hexagonal architecture" width="700px">
+ </div>
+ <div class="title">
+ Figure 1. The hexagonal architecture emphasizes multiple implementations of the different layers.
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>What Cockburn is emphasizing is that there’s usually more than one way <strong>into</strong> an application (what he called the <strong><em>user-side' ports</em></strong>) and more than one way <strong>out of</strong> an application too (the <strong><em>data-side ports</em></strong>). 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.</p>
+ </div>
+ <div class="paragraph">
+ <p>Associated with each port can be an <strong><em>adapter</em></strong> (in fact, Cockburn’s alternative name for this architecture is <strong><em>ports and adapters</em></strong>). An adapter is a device (piece of software) that talks in the protocol (or <em>API</em>) of the port. Each port could have several adapters.</p>
+ </div>
+ <div class="paragraph">
+ <p>Apache Isis maps very nicely onto the <strong>hexagonal architecture</strong>. Apache Isis' viewers act as user-side adapters and use the Apache Isis metamodel API as a port into the domain objects. For the data side, we are mostly concerned with persisting domain objects to some sort of object store. Here Apache Isis delegates most of the heavy lifting to ORM implementing the JDO API. Most of the time this will be DataNucleus configured to persist to an RDBMS, but DataNucleus can also support other object stores, for example Neo4J. Alternatively Apache Isis can be configured to persist using some other JDO implementation, for example Google App Engine.</p>
+ </div>
+ </div>
+ <div class="sect3">
+ <h4 id="_ugfun_core-concepts_philosophy_aop">2.1.4. Aspect Oriented</h4>
+ <div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
+ <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_aop.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
+ <button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
+ <ul class="dropdown-menu">
+ <li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_aop.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
+ <li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_aop.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
+ <li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_aop.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
+ <li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_aop.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>Although not a book about object modelling, Evans' "Domain Driven Design" does use object orientation as its primary modelling tool; while <a href="../ugfun/ugfun.html#_ugfun_core-concepts_philosophy_naked-objects-pattern">naked objects pattern</a> very much comes from an OO background (it even has 'object' in its name). Richard Pawson — the originator of Naked Objects pattern — lists Alan Kay as a key influence.</p>
+ </div>
+ <div class="paragraph">
+ <p>It’s certainly true that to develop an Apache Isis application you will need to have good object oriented modelling skills. But given that all the mainstream languages for developing business systems are object oriented (Java, C#, Ruby), that’s not such a stretch.</p>
+ </div>
+ <div class="paragraph">
+ <p>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.</p>
+ </div>
+ <div class="sect4">
+ <h5 id="_aop_concepts">AOP Concepts</h5>
+ <div class="paragraph">
+ <p>Aspect-orientation, then, is a different way of decomposing your application, by treating <em>cross-cutting concerns</em> 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).</p>
+ </div>
+ <div class="paragraph">
+ <p>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 <code>@Transactional</code> or <code>@Secured</code> to java beans.</p>
+ </div>
+ <div class="paragraph">
+ <p>Another aspect (so to speak!) of aspect-oriented programming has found its way into other programming languages, that of a mix-in or trait. In languages such as Scala these mix-ins are specified statically as part of the inheritance hierarchy, whereas with AOP the binding of a trait to some other class/type is done without the class "knowing" that additional behaviour is being mixed-in to it.</p>
+ </div>
+ </div>
+ <div class="sect4">
+ <h5 id="_realization_within_apache_isis">Realization within Apache Isis</h5>
+ <div class="paragraph">
+ <p>What has all this to do with Apache Isis, then?</p>
+ </div>
+ <div class="paragraph">
+ <p>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 <em>Apache Isis Programming Model</em> (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!</p>
+ </div>
+ <div class="paragraph">
+ <p>Apache Isis also draws heavily on the AOP concept of interceptors. Whenever an object is rendered in the UI, it is filtered with respect to the user’s permissions. That is, if a user is not authorized to either view or perhaps modify an object, then this is applied transparently by the framework. The (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a>'s 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.</p>
+ </div>
+ <div class="paragraph">
+ <p>Another example of interceptors are the (non-ASF) <a href="http://platform.incode.org" target="_blank">Incode Platform</a>'s command and 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.</p>
+ </div>
+ <div class="paragraph">
+ <p>Apache Isis also has an internal event bus (you can switch between an underlying implementation of Gauva or Axon). A domain event is fired whenever an object is interacted with, and this allows any subscribers to influence the operation (or even veto it). This is a key mechanism in ensuring that Isis applications are maintainable, and we discuss it in depth in the section on <a href="../ugbtb/ugbtb.html#_ugbtb_decoupling">Decoupling</a>. But fundamentally its relying on this AOP concept of interceptors.</p>
+ </div>
+ <div class="paragraph">
+ <p>Finally, Isis also a feature that is akin to AOP mix-ins. A "contributed action" is one that is implemented on a domain service but that appears to be a behaviour of rendered domain object. In other words, we can dissociate behaviour from data. That’s not always the right thing to do of course. In Richard Pawson’s description of the <a href="../ugfun/ugfun.html#_ugfun_core-concepts_philosophy_naked-objects-pattern">naked objects pattern</a> he talks about "behaviourally rich" objects, in other words where the business functionality encapsulated the data. But on the other hand sometimes the behaviour and data structures change at different rates. The <a href="http://en.wikipedia.org/wiki/Single_responsibility_principle">single responsibility principle</a> says we should only lump code together that changes at the same rate. Apache Isis' support for contributions (not only contributed actions, but also contributed properties and contributed collections) enables this
. And again, to loop back to the topic of this section, it’s an AOP concept that being implemented by the framework.</p>
+ </div>
+ <div class="paragraph">
+ <p>The nice thing about aspect orientation is that for the most part you can ignore these cross-cutting concerns and - at least initially - just focus on implementing your domain object. Later when your app starts to grow and you start to break it out into smaller modules, you can leverage Apache Isis' AOP support for (<a href="../ugfun/ugfun.html#_ugfun_building-blocks_types-of-domain-objects_mixins">mixins</a>), (<a href="../ugfun/ugfun.html#_ugfun_programming-model_domain-services_contributions">contributed services</a>) and interceptors (the <a href="../ugfun/ugfun.html#_ugfun_building-blocks_events_domain-events">event bus</a>) to ensure that your codebase remains maintainable.</p>
+ </div>
+ </div>
+ </div>
+ <div class="sect3">
+ <h4 id="_ugfun_core-concepts_philosophy_how-eases-ddd">2.1.5. How Apache Isis eases DDD</h4>
+ <div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
+ <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_how-eases-ddd.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
+ <button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
+ <ul class="dropdown-menu">
+ <li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_how-eases-ddd.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
+ <li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_how-eases-ddd.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
+ <li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_how-eases-ddd.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
+ <li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_how-eases-ddd.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>The case for <em>DDD</em> might be compelling, but that doesn’t necessarily make it easy to do. Let’s take a look at some of the challenges that <em>DDD</em> throws up and see how Apache Isis (and its implementation of the naked objects pattern) helps address them.</p>
+ </div>
+ <div class="sect4">
+ <h5 id="_ddd_takes_a_conscious_effort">DDD takes a conscious effort</h5>
+ <div class="paragraph">
+ <p>Here’s what Eric Evans says about ubiquitous language:</p>
+ </div>
+ <div class="quoteblock">
+ <blockquote>
+ <div class="paragraph">
+ <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.</p>
+ </div>
+ </blockquote>
+ </div>
+ <div class="paragraph">
+ <p>The word to pick up on here is <strong>conscious</strong>. It takes a <em>conscious</em> 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.</p>
+ </div>
+ <div class="paragraph">
+ <p>With Apache Isis, though, the ubiquitous language evolves with scarcely any effort at all. For the business experts, the Apache Isis viewers show the domain concepts they identify and the relationships between those concepts in a straightforward fashion. Meanwhile, the developers can devote themselves to encoding those domain concepts directly as domain classes. There’s no technology to get distracted by; there is literally nothing else for the developers to work on.</p>
+ </div>
+ </div>
+ <div class="sect4">
+ <h5 id="_ddd_must_be_grounded">DDD must be grounded</h5>
+ <div class="paragraph">
+ <p>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.</p>
+ </div>
+ <div class="paragraph">
+ <p>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.</p>
+ </div>
+ <div class="paragraph">
+ <p>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.</p>
+ </div>
+ </div>
+ <div class="sect4">
+ <h5 id="_model_must_be_understandable">Model must be understandable</h5>
+ <div class="paragraph">
+ <p>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.</p>
+ </div>
+ <div class="paragraph">
+ <p>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.</p>
+ </div>
+ <div class="paragraph">
+ <p>A better way to represent the model is to show it in action as a working prototype. As we show in the <a href="../ugfun/ugfun.html#_ugfun_getting-started">Getting Started</a> 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.</p>
+ </div>
+ <div class="paragraph">
+ <p>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.</p>
+ </div>
+ </div>
+ <div class="sect4">
+ <h5 id="_architecture_must_be_robust">Architecture must be robust</h5>
+ <div class="paragraph">
+ <p><em>DDD</em> 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.</p>
+ </div>
+ <div class="paragraph">
+ <p>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.</p>
+ </div>
+ <div class="paragraph">
+ <p>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.</p>
+ </div>
+ <div class="paragraph">
+ <p>Because of Apache Isis' generic <em>OOUI</em>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 <strong>must</strong> be in the domain model because there is nowhere else to put it.</p>
+ </div>
+ <div class="paragraph">
+ <p>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 <em>J(2)EE</em> architecture, with a custom <em>UI</em> if you want. Apache Isis guarantees that your domain model is complete.</p>
+ </div>
+ </div>
+ <div class="sect4">
+ <h5 id="_extending_the_reach_of_ddd">Extending the reach of DDD</h5>
+ <div class="paragraph">
+ <p>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?</p>
+ </div>
+ <div class="paragraph">
+ <p>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.</p>
+ </div>
+ <div class="paragraph">
+ <p>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.</p>
+ </div>
+ <div class="paragraph">
+ <p>If you’re just starting out writing domain-driven applications, then Apache Isis should significantly ease your journey into applying <em>DDD</em>. On the other hand, if you’ve used <em>DDD</em> for a while, then you should find Isis a very useful new tool in your arsenal.</p>
+ </div>
+ </div>
+ </div>
+ </div>
+ <div class="sect2">
+ <h3 id="_ugfun_core-concepts_principles">2.2. Principles and Values</h3>
+ <div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
+ <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
+ <button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
+ <ul class="dropdown-menu">
+ <li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
+ <li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
+ <li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
+ <li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>Apache Isis is primarily aimed at custom-built "enterprise" applications. The UI provided by the <a href="../ugvw/ugvw.html">Wicket viewer</a> is intended to be usable by domain experts, typically end-users within the organization. The REST API exposed by the <a href="../ugvro/ugvro.html">RestfulObjects viewer</a> allows custom apps to be developed — eg using Angular or similar — for use by those requiring more guidance; typically end-users outside of the organization. This section describes some of the core principles and values that the framework aims to honour and support.</p>
+ </div>
+ <div class="sect3">
+ <h4 id="_ugfun_core-concepts_principles_build-not-buy">2.2.1. Why Build instead of Buy?</h4>
+ <div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
+ <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_build-not-buy.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
+ <button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
+ <ul class="dropdown-menu">
+ <li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_build-not-buy.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
+ <li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_build-not-buy.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
+ <li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_build-not-buy.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
+ <li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_build-not-buy.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>Buying packaged software makes sense for statutory requirements, such as payroll or general ledger, or document management/retrieval. But (we argue) it makes much less sense to buy packaged software for the systems that support the core business: the software should fit the business, not the other way around.</p>
+ </div>
+ <div class="paragraph">
+ <p>Packaged software suffers from the problem of both having doing "too much" and "not enough":</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p>it does "too much" because it will have features that are not required by your business. These extra unnecessary features make the system difficult to learn and use.;</p> </li>
+ <li> <p>but it may also do "too little" because there may be crucial functionality not supported by the software.</p> </li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>The diagram below illustrates the dichotomy:</p>
+ </div>
+ <div class="imageblock">
+ <div class="content">
+ <a class="image" href="images/core-concepts/philosophy/build-vs-buy.png"><img src="images/core-concepts/philosophy/build-vs-buy.png" alt="build vs buy" width="800px"></a>
+ </div>
+ <div class="title">
+ Figure 2. build-vs-buy
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>What happens in this case is that end-users — needing some sort of solution for their particular business problem — will end up using unused fields to store the information they need. We end up with no correlation between the fields definitions and the values stored therein, sometimes with the datatypes not even matching. Any business rules pertaining to this extra data have to be enforced manually by the users, rather than by the system. The end result is a system even more complicated to learn and use, with the quality of the data held within it degrading as end users inevitably make mistakes in using it.</p>
+ </div>
+ <div class="paragraph">
+ <p>There are other benefits too for building rather than buying. Packaged software is almost always sold with a support package, the cover of which can vary enormously. At one end of the spectrum the support package ("bronze", say) will amount to little more than the ability to raise bug reports and to receive maintenance patches. At the other end ("platinum"?), the support package might provide the ability to influence the direction of the development of the product, perhaps specific features missing by the business.</p>
+ </div>
+ <div class="paragraph">
+ <p>Even so, the more widely used is the software package, the less chance of getting it changed. Does anyone reading this think they could get a new feature added (or removed) from Microsoft Word, for example?</p>
+ </div>
+ <div class="paragraph">
+ <p>Here’s another reason why you should build, and not buy, the software supporting your core business domain. Although most packaged software is customisable to a degree, there is always a limit to what can be customised. The consequence is that the business is forced to operate according to the way in which the software requires.</p>
+ </div>
+ <div class="paragraph">
+ <p>This might be something as relatively innocuous as imposing its own terminology onto the business, meaning that the end-users must mentally translate concepts in order to use the software. But it might impose larger constraints on the business; some packaged software (we carefully mention no names) is quite notorious for this</p>
+ </div>
+ <div class="paragraph">
+ <p>If your business is using the same software as your competitor, then obviously there’s no competitive advantage to be gained. And if your competitor has well-crafted custom software, then your business will be at a competitive <em>dis</em>advantage.</p>
+ </div>
+ <div class="paragraph">
+ <p>So, our philosophy is that custom software — for your core business domain — is the way to go. Let’s now look more closely at the types of custom applications you can consider building with the framework.</p>
+ </div>
+ </div>
+ <div class="sect3">
+ <h4 id="_ugfun_core-concepts_principles_for-the-long-term">2.2.2. For the long-term</h4>
+ <div class="btn-group" style="float: right; font-size: small; padding: 6px; margin-top: -55px; ">
+ <button type="button" class="btn btn-xs btn-default" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_for-the-long-term.adoc""><i class="fa fa-pencil-square-o"></i> Edit</button>
+ <button type="button" class="btn btn-xs btn-default dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false"><span class="caret"></span><span class="sr-only">Toggle Dropdown</span></button>
+ <ul class="dropdown-menu">
+ <li><a href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_for-the-long-term.adoc" target="_blank"><i class="fa fa-pencil-square-o fa-fw" aria-hidden="true"></i> Edit</a></li>
+ <li><a href="https://github.com/apache/isis/commits/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_for-the-long-term.adoc" target="_blank"><i class="fa fa-clock-o fa-fw" aria-hidden="true"></i> History</a></li>
+ <li><a href="https://github.com/apache/isis/raw/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_for-the-long-term.adoc" target="_blank"><i class="fa fa-file-text-o fa-fw" aria-hidden="true"></i> Raw</a></li>
+ <li><a href="https://github.com/apache/isis/blame/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles_for-the-long-term.adoc" target="_blank"><i class="fa fa-hand-o-right fa-fw" aria-hidden="true"></i> Blame</a></li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>Enterprise applications tend to stick around a long time; a business' core domains don’t tend to change all that often. What this means in turn is that the application needs to be maintainable, so that it is as easy to modify and extend when it’s 10 years old as when it was first written.</p>
+ </div>
+ <div class="paragraph">
+ <p>That’s a tall order for any application to meet, and realistically it <em>can</em> only be met if the application is modular. Any application that lacks a coherent internal structure will ultimately degrade into an unmaintable "big ball of mud", and the development team’s velocity/capacity to make changes will reduce accordingly.</p>
+ </div>
+ <div class="paragraph">
+ <p>Apache Isis' architecture allows the internal structure to be maintained in two distinct ways.</p>
+ </div>
+ <div class="ulist">
+ <ul>
+ <li> <p>first, the naked objects pattern acts as a "firewall", ensuring that any business logic in the domain layer doesn’t leak out into the presentation layer (it can’t, because the developer doesn’t write any controllers/views).</p> </li>
+ <li> <p>second, the framework’s provides various features (discussed in more detail below) to allow the different modules <em>within</em> the domain layer to interact with each in a decoupled fashion.</p> </li>
+ </ul>
+ </div>
+ <div class="paragraph">
+ <p>The diagram below illustrates this:</p>
+ </div>
+ <div class="imageblock">
+ <div class="content">
+ <a class="image" href="images/core-concepts/philosophy/decoupled-applications.png"><img src="images/core-concepts/philosophy/decoupled-applications.png" alt="decoupled applications" width="800px"></a>
+ </div>
+ <div class="title">
+ Figure 3. decoupled applications
+ </div>
+ </div>
+ <div class="paragraph">
+ <p>Here, the presentation layer (<a href="../ugvw/ugvw.html">Wicket UI</a> or <a href="../ugvro/ugvro.html">REST API</a>) is handled by the framework, while the developer focusses on just the domain layer. The framework encourages splitting this functionality into modules; each such module has its counterpart (typically tables within a given RDBMS database schema) within the persistence layer.</p>
+ </div>
+ <div class="paragraph">
+ <p>This architecture means that it’s impossible for business logic to leach out into the adjacent presentation layer because the developer d
<TRUNCATED>