http://git-wip-us.apache.org/repos/asf/isis-site/blob/6ad91949/content/guides/ugfun/ugfun.html ---------------------------------------------------------------------- diff --git a/content/guides/ugfun/ugfun.html b/content/guides/ugfun/ugfun.html index 761561d..988fc47 100644 --- a/content/guides/ugfun/ugfun.html +++ b/content/guides/ugfun/ugfun.html @@ -377,10 +377,10 @@ <h2 id="__ugfun">1. Fundamentals</h2> <div class="sectionbody"> <div class="paragraph"> - <p>This guide introduces the <a href="#_ugfun_core-concepts">core concepts</a> and ideas behind Apache Isis, and tells you how to <a href="#_ugfun_getting-started">get started</a> with a Maven archetype.</p> + <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_how-tos">how-to</a>s, describes how to influence the <a href="#_ugfun_object-layout">UI layout</a> of your domain objects (this is ultimately just a type of metadata), and it catalogues various <a href="#_ugfun_faqs.adoc">FAQ</a>s.</p> + <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> @@ -610,7 +610,7 @@ <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_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> + <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"> @@ -680,7 +680,7 @@ <h4 id="_ugfun_core-concepts_philosophy_aop">2.1.4. Aspect Oriented</h4> <button type="button" class="button secondary" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_philosophy_aop.adoc""; style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i> Edit</button> <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_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> + <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> @@ -715,13 +715,13 @@ <p>Another example of interceptors are the <a href="http://github.com/isisaddons/isis-module-command";>Isis addons' command</a> and <a href="http://github.com/isisaddons/isis-module-audit";>Isis addons' audit</a> 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.html#_ugbtb_decoupling">Decoupling</a>. But fundamentally its relying on this AOP concept of interceptors.</p> + <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_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> + <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 at least - just focus on implementing your domain object. Later when your app starts to grow and you start to break it out into smaller modules, you can leverage Apache Isis' AOP support for (<a href="ugbtb.html#_ugbtb_decoupling_mixins">mixins</a>), (<a href="ugbtb.html#_ugbtb_decoupling_contributions">contributions</a>) and interceptors (the <a href="ugbtb.html#_ugbtb_decoupling_event-bus">event bus</a>) to ensure that your codebase remains maintainable.</p> + <p>The nice thing about aspect orientation is that for the most part you can ignore these cross-cutting concerns and - at least initially at least - just focus on implementing your domain object. Later when your app starts to grow and you start to break it out into smaller modules, you can leverage Apache Isis' AOP support for (<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> @@ -771,7 +771,7 @@ <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_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> + <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> @@ -816,7 +816,7 @@ <h3 id="_ugfun_core-concepts_principles">2.2. Principles and Values</h3> <button type="button" class="button secondary" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_principles.adoc""; style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i> Edit</button> <div class="paragraph"> - <p>Apache Isis is primarily aimed at custom-built "enterprise" applications. The UI provided by the <a href="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.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> + <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.pdf 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> @@ -896,7 +896,7 @@ </div> </div> <div class="paragraph"> - <p>Here, the presentation layer (<a href="ugvw.html">Wicket UI</a> or <a href="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> + <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 doesnât (canât) write any code for presentation layer. We in effect have a "firewall" between the two layers.</p> @@ -908,7 +908,7 @@ <ul> <li> <p>dependency injection of services<br></p> <div class="paragraph"> - <p>Both <a href="rgsvc.html">framework-defined domain services</a> and application-defined services (eg repositories and factories) are injected everywhere, using the regular <a href="rgant.html#_rgant-Inject"><code>@javax.inject.Inject</code></a> annotation.</p> + <p>Both <a href="../rgsvc/rgsvc.html">framework-defined domain services</a> and application-defined services (eg repositories and factories) are injected everywhere, using the regular <a href="../rgant/rgant.html#_rgant-Inject"><code>@javax.inject.Inject</code></a> annotation.</p> </div> </li> <li> <p>mixins allow functionality defined in one module to appear (in the UI) to be provided by some other module.<br></p> <div class="paragraph"> @@ -921,7 +921,7 @@ </ul> </div> <div class="paragraph"> - <p>For those cases where a module needs to interact with other modules but does not know about their implementations, the module can either define its own <a href="https://en.wikipedia.org/wiki/Service_provider_interface";>SPI</a> domain services or it can define custom domain events and fire them. This technique is also used extensively by the framework itself. For example, the <a href="rgsvc.html#_rgsvc_spi_AuditerService"><code>AuditerService</code></a> SPI enables custom auditing, and the <a href="rgsvc.html#_rgsvc_spi_PublisherService"><code>PublisherService</code></a> SPI enables custom publishing</p> + <p>For those cases where a module needs to interact with other modules but does not know about their implementations, the module can either define its own <a href="https://en.wikipedia.org/wiki/Service_provider_interface";>SPI</a> domain services or it can define custom domain events and fire them. This technique is also used extensively by the framework itself. For example, the <a href="../rgsvc/rgsvc.html#_rgsvc_spi_AuditerService"><code>AuditerService</code></a> SPI enables custom auditing, and the <a href="../rgsvc/rgsvc.html#_rgsvc_spi_PublisherService"><code>PublisherService</code></a> SPI enables custom publishing</p> </div> <div class="paragraph"> <p>When building a modular application, itâs important to consider the logical layering of the modules: we donât need every module to be completely decoupled from every other. The most important requirement is that there are no cyclic dependencies, because otherwise we run the risk of the application degrading into a <a href="https://en.wikipedia.org/wiki/Big_ball_of_mud";>"big ball of mud"</a>. OO design techniques such as the <a href="https://en.wikipedia.org/wiki/Dependency_inversion_principle";>dependency inversion principle</a> can be used to any such</p> @@ -948,8 +948,8 @@ <p>Many other frameworks promise rapid application development and provide automatically generated user interfaces, so how do they compare to Apache Isis?</p> </div> <div class="sect3"> - <h4 id="_ugfun_core-concepts_apache-isis-vs_mvc-server-side-frameworks">2.3.1. vs MVC server-side frameworks</h4> - <button type="button" class="button secondary" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_mvc-server-side-frameworks.adoc""; style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i> Edit</button> + <h4 id="_ugfun_core-concepts_apache-isis-vs_mvc-server-side">2.3.1. vs MVC server-side</h4> + <button type="button" class="button secondary" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_mvc-server-side.adoc""; style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i> Edit</button> <div class="paragraph"> <p>Some of most commonly used frameworks today are <a href="http://www.spring.io/";>Spring MVC</a>, <a href="http://rubyonrails.org/";>Ruby on Rails</a> and <a href="http://www.grails.org";>Grails</a>, all of which implement one flavour or another of the server-side MVC pattern. The MVC 1.0 specification (originally scheduled for JavaEE 8 though since removed) is also similar.</p> </div> @@ -957,13 +957,13 @@ <p>These frameworks all use the classic <strong>model-view-controller</strong> ( <em>MVC</em>) 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 <em>CRUD</em>-style interfaces. More sophisticated behavior is accomplished by customizing the generated controllers.</p> </div> <div class="paragraph"> - <p>The most obvious difference when developing an Apache Isis application is its deliberate lack of an explicit controller layer; non- <em>CRUD</em> behavior is automatically made available in its generic object-oriented _UI_s. More sophisticated UIs can be built either by <a href="ugvw.html#_ugvw_extending">extending Apache Isis' Wicket viewer</a> or by writing a bespoke UI leveraging the REST (hypermedia) API automatically exposed by <a href="ugvro.html">Isis' Restful Objects viewer</a>. Other frameworks can also be used to implement REST APIs, of course, but generally they require a significant amount of development to get anywhere near the level of sophistication provided automatically by Apache Isis' REST API.</p> + <p>The most obvious difference when developing an Apache Isis application is its deliberate lack of an explicit controller layer; non- <em>CRUD</em> behavior is automatically made available in its generic object-oriented _UI_s. More sophisticated UIs can be built either by <a href="../ugvw/ugvw.html#_ugvw_extending">extending Apache Isis' Wicket viewer</a> or by writing a bespoke UI leveraging the REST (hypermedia) API automatically exposed by <a href="../ugvro/ugvro.html">Isis' Restful Objects viewer</a>. Other frameworks can also be used to implement REST APIs, of course, but generally they require a significant amount of development to get anywhere near the level of sophistication provided automatically by Apache Isis' REST API.</p> </div> <div class="paragraph"> <p>Although these frameworks all provide their own ecosystems of extensions, Apache Isis' equivalent <a href="http://www.isisaddons.org";>Isis Addons</a> (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 <a href="http://github.com/isisaddons/isis-module-security";>Isis addons' security module</a> provides a full subdomain of users, roles, features and permissions that can be plugged into any Isis application. Similarly, the <a href="http://github.com/isisaddons/isis-module-command";>Isis addons' command</a> and <a href="http://github.com/isisaddons/isis-module-audit";>Isis addons' audit</a> 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.</p> </div> <div class="paragraph"> - <p>In terms of testing support, each of these other frameworks provide mechanisms to allow the webapp to be tested from within a JUnit test harness. Apache Isis' support is similar. Where Apache Isis differs though is that it enables end-to-end testing without the need for slow and fragile Selenium tests. Instead, Apache Isis provides a "<a href="ugtst.html#_ugtst_integ-test-support_wrapper-factory">WrapperFactory</a>" domain service that allows the generic UI provided to in essence be simulated. On a more pragmatic level, the <a href="http://github.com/isisaddons/isis-module-fakedata";>Isis addons' fakedata</a> 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.</p> + <p>In terms of testing support, each of these other frameworks provide mechanisms to allow the webapp to be tested from within a JUnit test harness. Apache Isis' support is similar. Where Apache Isis differs though is that it enables end-to-end testing without the need for slow and fragile Selenium tests. Instead, Apache Isis provides a "<a href="../ugtst/ugtst.html#_ugtst_integ-test-support_wrapper-factory">WrapperFactory</a>" domain service that allows the generic UI provided to in essence be simulated. On a more pragmatic level, the <a href="http://github.com/isisaddons/isis-module-fakedata";>Isis addons' fakedata</a> 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.</p> </div> </div> <div class="sect3"> @@ -991,16 +991,16 @@ <p>There are other reasons though why a separate read model might make sense, such as to precompute particular queries, or against denormalized data. In these cases Apache Isis can often provide a reasonable alternative, namely to map domain entities against RDBMS views, either materialized views or dynamic. In such cases there is still only a single physical datastore, and so transactional integrity is retained.</p> </div> <div class="paragraph"> - <p>Or, the CQRS architecture can be more fully implemented with Apache Isis by introducing a separate read model, synchronized using the <a href="rgsvc.html#_rgsvc_api_PublishingService"><code>PublishingService</code></a>, or using <a href="rgcms.html#_rgcms_classes_super_AbstractSubscriber">subscribers</a> on the <a href="rgsvc.html#_rgsvc_api_EventBusService"><code>EventBusService</code></a>. One can then use <a href="ugbtb.html#_ugbtb_view-models">view models</a> to surface the data in the external read datastore.</p> + <p>Or, the CQRS architecture can be more fully implemented with Apache Isis by introducing a separate read model, synchronized using the <a href="../rgsvc/rgsvc.html#_rgsvc_api_PublishingService"><code>PublishingService</code></a>, or using <a href="../rgcms/rgcms.html#_rgcms_classes_super_AbstractSubscriber">subscribers</a> on the <a href="../rgsvc/rgsvc.html#_rgsvc_api_EventBusService"><code>EventBusService</code></a>. One can then use <a href="../ugfun/ugfun.html#_ugfun_building-blocks_types-of-domain-objects_view-models">view models</a> to surface the data in the external read datastore.</p> </div> <div class="paragraph"> - <p>With respect to commands, Apache Isis does of course support the <a href="rgsvc.html#_rgsvc_spi_CommandService"><code>CommandService</code></a> which allows each business action to be reified into a <code>Command</code>. However, names are misleading here: Apache Isis' commands are relatively passive, merely recording the intent of the user to invoke some operation. In a CQRS architecture, though, commands take a more active role, locating and acting upon the domain objects. More significantly, in CQRS each command has its own class, such as <code>PlaceOrderCommand</code>, instantiated by the client and then executed. With Apache Isis, though, the end-user merely invokes the <code>placeOrder(â¦â)</code> action upon the domain object; the framework itself creates the <code>Command</code> as a side-effect of this.</p> + <p>With respect to commands, Apache Isis does of course support the <a href="../rgsvc/rgsvc.html#_rgsvc_spi_CommandService"><code>CommandService</code></a> which allows each business action to be reified into a <code>Command</code>. However, names are misleading here: Apache Isis' commands are relatively passive, merely recording the intent of the user to invoke some operation. In a CQRS architecture, though, commands take a more active role, locating and acting upon the domain objects. More significantly, in CQRS each command has its own class, such as <code>PlaceOrderCommand</code>, instantiated by the client and then executed. With Apache Isis, though, the end-user merely invokes the <code>placeOrder(â¦â)</code> action upon the domain object; the framework itself creates the <code>Command</code> as a side-effect of this.</p> </div> <div class="paragraph"> <p>In CQRS the commands correspond to the business logic that mutates the system. Whether this logic is part of the command class (<code>PlaceOrderCommand</code>) or whether that command delegates to methods on the domain object is an implementation detail; but it certainly is common for the business logic to be wholly within the command object and for the domain object to be merely a data holder of the data within the command/write datastore.</p> </div> <div class="paragraph"> - <p>In Apache Isis this same separation of business logic from the underlying data can be accomplished most straightforwardly using <a href="ugbtb.html#_ugbtb_decoupling_mixins">mixins</a> or <a href="#_ugfun_how-tos_contributed-members">contributions</a>. In the UI (surfaced by the <a href="ugvw.html">Wicket viewer</a>) or in the REST API (surfaced by the <a href="ugvro.html">RestfulObjects viewer</a>) the behaviour appears to reside on the domain object; however the behaviour actually resides on separate classes and is mixed in (like a trait) only at runtime.</p> + <p>In Apache Isis this same separation of business logic from the underlying data can be accomplished most straightforwardly using <a href="../ugfun/ugfun.html#_ugfun_building-blocks_types-of-domain-objects_mixins">mixins</a> or <a href="../ugfun/ugfun.html#_ugfun_how-tos_contributed-members">contributions</a>. In the UI (surfaced by the <a href="../ugvw/ugvw.html">Wicket viewer</a>) or in the REST API (surfaced by the <a href="../ugvro/ugvro.html">RestfulObjects viewer</a>) the behaviour appears to reside on the domain object; however the behaviour actually resides on separate classes and is mixed in (like a trait) only at runtime.</p> </div> </div> <div class="sect3"> @@ -1019,20 +1019,20 @@ <p>When combined with CQRS we see a command that triggers a business operation, and an event that results from it. So, a <code>PlaceOrderCommand</code> command can result in an <code>OrderPlacedEvent</code> event. A subscriber to this event might then generate a further command to act upon some other system (eg to dispatch the system). Note that the event might be dispatched and consumed in-process or alternatively this might occur out-of-process. If the latter, then the subscriber will operate within a separate transaction, meaning the usual eventual consistency concerns and also compensating actions if a rollback is required. CQRS/event sourcing advocates point outâââcorrectlyâââthat this is just how things are in the "real world" too.</p> </div> <div class="paragraph"> - <p>In Apache Isis every business action (and indeed, property and collection) emits domain events through the <a href="rgsvc.html#_rgsvc_api_EventBusService"><code>EventBusService</code></a>, and can optionally also be published through the <a href="rgsvc.html#_rgsvc_spi_PublishingService"><code>PublishingService</code></a>. The former are dispatched and consumed in-process and within the same transaction, and for this reason the <a href="rgcms.html#_rgcms_classes_super_AbstractSubscriber">subscribers</a> can also veto the events. The latter are intended for out-of-process consumption; the (non-ASF) <a href="http://github.com/isisaddons/isis-module-publishing";>Isis addons' publishing</a> and <a href="http://github.com/isisaddons/isis-module-publishmq";>Isis addons' publishmq</a> modules provide implementations for dispatching either through a RDBMS database table, or directly through to an <a href="http://camel.apache.org";>ActiveMQ</a> message queue (eg wired up to <a href= "http://camel.apache.org";>Apache Camel</a> event bus).</p> + <p>In Apache Isis every business action (and indeed, property and collection) emits domain events through the <a href="../rgsvc/rgsvc.html#_rgsvc_api_EventBusService"><code>EventBusService</code></a>, and can optionally also be published through the <a href="../rgsvc/rgsvc.html#_rgsvc_spi_PublishingService"><code>PublishingService</code></a>. The former are dispatched and consumed in-process and within the same transaction, and for this reason the <a href="../rgcms/rgcms.html#_rgcms_classes_super_AbstractSubscriber">subscribers</a> can also veto the events. The latter are intended for out-of-process consumption; the (non-ASF) <a href="http://github.com/isisaddons/isis-module-publishing";>Isis addons' publishing</a> and <a href="http://github.com/isisaddons/isis-module-publishmq";>Isis addons' publishmq</a> modules provide implementations for dispatching either through a RDBMS database table, or directly through to an <a href="http://camel.apache.org";>ActiveMQ</a> message que ue (eg wired up to <a href="http://camel.apache.org";>Apache Camel</a> event bus).</p> </div> </div> <div class="sect3"> <h4 id="_ugfun_core-concepts_apache-isis-vs_metawidget">2.3.4. vs MetaWidget</h4> <button type="button" class="button secondary" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_apache-isis-vs_metawidget.adoc""; style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i> Edit</button> <div class="paragraph"> - <p>MetaWidget (mentioned <a href="#_ugfun_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping">earlier</a> has a number of ideas in common with Apache Isis, specifically the runtime generation of a UI for domain objects. And like Apache Isis, MetaWidget builds its own metamodel of the domain objects and uses this to render the object.</p> + <p>MetaWidget (mentioned <a href="../ugfun/ugfun.html#_ugfun_core-concepts_philosophy_naked-objects-pattern_object-interface-mapping">earlier</a> has a number of ideas in common with Apache Isis, specifically the runtime generation of a UI for domain objects. And like Apache Isis, MetaWidget builds its own metamodel of the domain objects and uses this to render the object.</p> </div> <div class="paragraph"> <p>However, there is a difference in philosophy in that MW is not a full-stack framework and does not (in their words) try to "own the UI". Rather they support a huge variety of UI technologies and allow the domain object to be rendered in any of them.</p> </div> <div class="paragraph"> - <p>In contrast, Apache Isis is full-stack and does generate a complete UI; we then allow you to customize or extend this UI (as per the various <a href="http://www.isisaddons.org";>Isis Addons</a> (non-ASF), and we also provide a full REST API through the <a href="ugvro.html">Restful Objects viewer</a></p> + <p>In contrast, Apache Isis is full-stack and does generate a complete UI; we then allow you to customize or extend this UI (as per the various <a href="http://www.isisaddons.org";>Isis Addons</a> (non-ASF), and we also provide a full REST API through the <a href="../ugvro/ugvro.html">Restful Objects viewer</a></p> </div> <div class="paragraph"> <p>Also, itâs worth noting that MetaWidget does have an elegant pipeline architecture, with APIs to allow even its metamodel to be replaced. It would be feasible and probably quite straightforward to use Apache Isis' own metamodel as an implementation of the MetaWidget API. This would allow MetaWidget to be able to render an Apache Isis domain application.</p> @@ -1040,27 +1040,172 @@ </div> </div> <div class="sect2"> - <h3 id="_ugfun_core-concepts_building-blocks">2.4. Building Blocks</h3> - <button type="button" class="button secondary" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_building-blocks.adoc""; style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i> Edit</button> + <h3 id="_ugfun_core-concepts_deployment-options">2.4. Deployment Options</h3> + <button type="button" class="button secondary" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_deployment-options.adoc""; style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i> Edit</button> <div class="paragraph"> - <p>In this section we run through the main building blocks that make up an Apache Isis application.</p> + <p>Apache Isis is a mature platform suitable for production deployment, with its "sweet spot" being line-of-business enterprise applications. So if youâre looking to develop that sort of application, we certainly hope youâll seriously evaluate it.</p> + </div> + <div class="paragraph"> + <p>But there are other ways that you can make Apache Isis work for you; in this section we explore a few of them.</p> + </div> + <div class="sect3"> + <h4 id="_deploy_to_production">2.4.1. Deploy to production</h4> + <div class="paragraph"> + <p>Letâs start though with the default use case for Apache Isis: building line-of-business enterprise applications, on top of its Wicket viewer.</p> + </div> + <div class="paragraph"> + <p>Apache Wicket, and therefore Apache Isis in this configuration, is a stateful architecture. As a platform it is certainly capable of supporting user bases of several thousand (with perhaps one or two hundred concurrent); however it isnât an architecture that you should try to scale up to tens of thousands of concurrent users.</p> + </div> + <div class="paragraph"> + <p>The UI generated by the Wicket viewer is well suited to many line-of-business apps, but itâs also worth knowing that (with a little knowledge of the Wicket APIs) it relatively straightforward to extend. As described in <a href="../ugfun/ugfun.html#_ugfun_available-domain-services_isis-addons">Isis addons</a> chapter, the viewer already has integrations with <a href="https://github.com/isisaddons/isis-wicket-gmap3";>google maps</a>, <a href="https://github.com/isisaddons/isis-wicket-fullcalendar2";>a full calendar</a> and an <a href="https://github.com/isisaddons/isis-wicket-excel";>export to Excel</a> component. We are also aware of integrations with SVG images (for floor maps of shopping center) and of custom widgets displaying a catalogue (text and images) of medical diseases.</p> + </div> + <div class="paragraph"> + <p>Deploying on Apache Isis means that the framework also manages object persistence. For many line-of-business applications this will mean using a relational database. It is also possible (courtesy of its integratinon with <a href="http://www.datanucleus.org";>DataNucleus</a>) to deploy an Isis app to a NoSQL store such as Neo4J or MongoDB; and it is also possible to deploy to cloud platforms such as <a href="https://cloud.google.com/appengine/docs";>Google App Engine (GAE)</a>.</p> + </div> + </div> + <div class="sect3"> + <h4 id="_prototyping">2.4.2. Prototyping</h4> + <div class="paragraph"> + <p>Even if you donât intend to deploy your application on top of Apache Isis, there can be a lot of value in using Apache Isis for prototyping. Because all you need do to get an app running is write domain objects, you can very quickly explore a domain object model and validate ideas with a domain expert.</p> + </div> + <div class="paragraph"> + <p>By focusing just on the domain, youâll also find that you start to develop a ubiquitous language - a set of terms and concepts that the entire team (business and technologists alike) have a shared understanding.</p> + </div> + <div class="paragraph"> + <p>Once youâve sketched out your domain model, you can then "start-over" using your preferred platform.</p> + </div> + </div> + <div class="sect3"> + <h4 id="_deploy_on_your_own_platform">2.4.3. Deploy on your own platform</h4> + <div class="paragraph"> + <p>The programming model defined by Apache Isis deliberately minimizes the dependencies on the rest of the framework. In fact, the only hard dependency that the domain model classes have on Apache Isis is through the <code>org.apache.isis.applib</code> classes, mostly to pick up annotations such as <code>@Disabled</code>. So, if you have used Apache Isis for prototyping (discussed above), then note that itâs quite feasible to take your domain model a the basis of your actual development effort; Apache Isis' annotations and programming conventions will help ensure that any subtle semantics you might have captured in your prototyping are not lost.</p> + </div> + <div class="paragraph"> + <p>If you go this route, your deployment platform will of course need to provide similar capabilities to Apache Isis. In particular, youâll need to figure out a way to inject domain services into domain entities (eg using a JPA listener), and youâll also need to reimplement any domain services you have used that Apache Isis provides "out-of-the-box" (eg <a href="../rgsvc/rgsvc.html#_rgsvc_api_QueryResultsCache"><code>QueryResultsCache</code></a> domain service).</p> + </div> + </div> + <div class="sect3"> + <h4 id="_deploy_the_rest_api">2.4.4. Deploy the REST API</h4> + <div class="paragraph"> + <p>REST (Representation State Transfer) is an architectural style for building highly scalable distributed systems, using the same principles as the World Wide Web. Many commercial web APIs (twitter, facebook, Amazon) are implemented as either pure REST APIs or some approximation therein.</p> + </div> + <div class="paragraph"> + <p>The <a href="http://restfulobjects.org";>Restful Objects specification</a> defines a means by a domain object model can be exposed as RESTful resources using JSON representations over HTTP. Apache Isis' <a href="../ugvro/ugvro.html">RestfulObjects viewer</a> is an implementation of that spec, making any Apache Isis domain object automatically available via REST.</p> + </div> + <div class="paragraph"> + <p>There are a number of use cases for deploying Isis as a REST API, including:</p> + </div> + <div class="ulist"> + <ul> + <li> <p>to allow a custom UI to be built against the RESTful API<br></p> + <div class="paragraph"> + <p>For example, using Angular or some other RIA technology such as Flex, JavaFX, Silverlight</p> + </div> </li> + <li> <p>to enable integration between systems<br></p> + <div class="paragraph"> + <p>REST is designed to be machine-readable, and so is an excellent choice for synchronous data interchange scenarios.</p> + </div> </li> + <li> <p>as a ready-made API for migrating data from one legacy system to its replacement.</p> </li> + </ul> + </div> + <div class="paragraph"> + <p>As for the auto-generated webapps, the framework manages object persistence. It is perfectly possible to deploy the REST API alongside an auto-generated webapp; both work from the same domain object model.</p> + </div> + </div> + <div class="sect3"> + <h4 id="_implement_your_own_viewer">2.4.5. Implement your own viewer</h4> + <div class="paragraph"> + <p>Isis' architecture was always designed to support multiple viewers; and indeed Apache Isis out-of-the-box supports two: the Wicket viewer, and the Restful Objects viewer (or three, if one includes the Wrapper Factory).</p> + </div> + <div class="paragraph"> + <p>While we mustnât understate the effort involved here, it is feasible to implement your own viewers too. Indeed, one of Apache Isis' committers does indeed have a (closed source) viewer, based on <a href="http://www.wavemaker.com/";>Wavemaker</a>.</p> + </div> + </div> + </div> + </div> + </div> + <div class="sect1"> + <h2 id="_ugfun_building-blocks">3. Building Blocks</h2> + <button type="button" class="button secondary" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks.adoc""; style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i> Edit</button> + <div class="sectionbody"> + <div class="paragraph"> + <p>In this section we run through the main building blocks that make up an Apache Isis application.</p> + </div> + <div class="sect2"> + <h3 id="_ugfun_building-blocks_metamodel">3.1. A MetaModel</h3> + <button type="button" class="button secondary" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_metamodel.adoc""; style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i> Edit</button> + <div class="paragraph"> + <p>At its core, Apache Isis is a metamodel that is built at runtime from the domain classes (eg <code>Customer.java</code>), along with optional supporting metadata (eg <code>Customer.layout.xml</code>).</p> + </div> + <div class="paragraph"> + <p>The contents of this metamodel is inferred from the Java classes discovered on the classpath: the entities and supporting services, as well the members of those classes. The detail of the metamodel is generally explicit, usually represented by Java annotations such as <code>@Title</code> or <code>@Action</code>. Notably the metamodel is <a href="../ugbtb/ugbtb.html#_ugbtb_programming-model">extensible</a>; it is possible to teach Apache Isis new programming conventions/rules (and conversely to remove those that are built in).</p> + </div> + <div class="paragraph"> + <p>Most of the annotations recognized by the framework are defined by the Apache Isis framework itself. For example the <code>@Title</code> annotationâââwhich identifies how the framework should derive a human-readable label for each rendered domain objectâââis part of the <code>org.apache.isis.applib.annotations</code> package. However the framework also recognizes certain other JEE annotations such as <code>@javax.inject.Inject</code> (used for dependency injection).</p> + </div> + <div class="paragraph"> + <p>The framework uses DataNucleus for its persistence mechanism. This is an ORM that implements the JDO and JPA APIs, and which can map domain objects either to an RDBMS or to various NoSQL objectstores such as MongoDB or Neo4J. Apache Isis recognizes a number of the JDO annotations such as <code>@javax.jdo.annotations.Column(allowsNull=â¦â)</code>.</p> + </div> + <div class="paragraph"> + <p>In addition, the framework builds up the metamodel for each domain object using <a href="../ugvw/ugvw.html#_ugvw_layout">layout hints</a>, such as <code>Customer.layout.xml</code>. These provide metadata such as grouping elements of the UI together, using multi-column layouts, and so on. The layout file can be modified while the application is still running, and are picked up automatically; a useful way to speed up feedback.</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>At the time of writing Apache Isis only recognizes and supports the JDO API, though we expect JPA to be supported in the future.</p> + </div> </td> + </tr> + </tbody> + </table> + </div> + </div> + <div class="sect2"> + <h3 id="_ugfun_building-blocks_types-of-domain-objects">3.2. Type of Domain Objects</h3> + <button type="button" class="button secondary" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_types-of-domain-objects.adoc""; style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i> Edit</button> + <div class="paragraph"> + <p>Apache Isis supports recognises four main types of domain classes:</p> + </div> + <div class="ulist"> + <ul> + <li> <p><strong>domain entities</strong> - domain objects persisted to the database using JDO/DataNucleus; for example <code>Customer</code></p> </li> + <li> <p><strong>domain services</strong> - generally singletons, automatically injected, and providing various functionality; for example <code>CustomerRepository</code></p> </li> + <li> <p><strong>view models</strong> - domain objects that are a projection of some state held by the database, in support a particular use case; for example <code>CustomerDashboard</code> (to pull together commonly accessed information about a customer).</p> </li> + <li> <p><strong>mixins</strong> - allow functionality to be "contributed" in the UI by one module to another object, similar to traits or extension methods provided in some programming languages. This is an important capability to help keep large applications <a href="../ugbtb/ugbtb.html#_ugbtb_decoupling">decoupled</a>.</p> </li> + </ul> + </div> + <div class="paragraph"> + <p>From the end-userâs perspective the UI displays a single domain object instance that has state (that is, a domain entity or a view model) per page. The end-user can then inspect and modify its state, and navigate to related objects.</p> + </div> + <div class="paragraph"> + <p>Domain classes are generally recognized using annotations. Apache Isis defines its own set of annotations, while entities are annotated using JDO/DataNucleus (though XML can also be used if required). Apache Isis recognizes some of the JDO and JAXB annotations and infers domain semantics from these annotations. Similarly, JAXB annotations are typically used for view models. There is a smattering of other Java/JEE annotations that are also supported, such as <code>@javax.inject.Inject</code> and <code>@javax.annotation.Nullable</code>.</p> + </div> + <div class="paragraph"> + <p>The following subsections explain this in further detail.</p> </div> <div class="sect3"> - <h4 id="__ugfun_core-concepts_building-blocks_metamodel">2.4.1. A MetaModel</h4> + <h4 id="_ugfun_building-blocks_types-of-domain-objects_domain-entities">3.2.1. Domain Entities</h4> + <button type="button" class="button secondary" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_types-of-domain-objects_domain-entities.adoc""; style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i> Edit</button> <div class="paragraph"> - <p>At its core, Apache Isis is a metamodel that is built at runtime from the domain classes (eg <code>Customer.java</code>), along with optional supporting metadata (eg <code>Customer.layout.xml</code>).</p> + <p>Most domain objects that the end-user interacts with are <em>domain entities</em>, such as <code>Customer</code>, <code>Order</code>, <code>Product</code> and so on. These are persistent objects and which are mapped to a database (usually relational), using JDO/DataNucleus annotations.</p> </div> <div class="paragraph"> - <p>The contents of this metamodel is inferred from the Java classes discovered on the classpath: the entities and supporting services, as well the members of those classes. The detail of the metamodel is generally explicit, usually represented by Java annotations such as <code>@Title</code> or <code>@Action</code>. Notably the metamodel is <a href="ugbtb.html#_ugbtb_programming-model">extensible</a>; it is possible to teach Apache Isis new programming conventions/rules (and conversely to remove those that are built in).</p> + <p>Some domain entities are really aggregates, a combination of multiple objects. A commonly cited example of this is an <code>Order</code>, which really consists of both a root <code>Order</code> entity and a collection of <code>OrderItem</code>s. From the end-users' perspective, when they talk of "order" they almost always mean the aggregate rather than just the <code>Order</code> root entity.</p> </div> <div class="paragraph"> - <p>Most of the annotations recognized by the framework are defined by the Apache Isis framework itself. For example the <code>@Title</code> annotationâââwhich identifies how the framework should derive a human-readable label for each rendered domain objectâââis part of the <code>org.apache.isis.applib.annotations</code> package. However the framework also recognizes certain other JEE annotations such as <code>@javax.inject.Inject</code> (used for dependency injection).</p> + <p>Eric Evans' <a href="http://books.google.com/books/about/Domain_Driven_Design.html?id=hHBf4YxMnWMC";>Domain Driven Design</a> has a lot to say about aggregate roots and their responsibilities: in particular that it is the responsibility of the aggregate root to maintain the invariants of its component pieces, and that roots may only reference other roots. Thereâs good logic here: requiring only root-to-root relationships reduces the number of moving parts that the developer has to think about.</p> </div> <div class="paragraph"> - <p>The framework uses DataNucleus for its persistence mechanism. This is an ORM that implements the JDO and JPA APIs, and which can map domain objects either to an RDBMS or to various NoSQL objectstores such as MongoDB or Neo4J. Apache Isis recognizes a number of the JDO annotations such as <code>@javax.jdo.annotations.Column(allowsNull=â¦â)</code>.</p> + <p>On the other hand, this constraint can substantially complicate matters when mapping domain layer to the persistenec layer. DDD tends to de-emphasise such matters: it aims to be completely agnostic about the persistence layer, with the responsibilities for managing relationships moved (pretty much by definition) into the domain layer.</p> </div> <div class="paragraph"> - <p>In addition, the framework builds up the metamodel for each domain object using <a href="#_ugfun_object-layout">layout hints</a>, such as <code>Customer.layout.xml</code>. These provide metadata such as grouping elements of the UI together, using multi-column layouts, and so on. The layout file can be modified while the application is still running, and are picked up automatically; a useful way to speed up feedback.</p> + <p>As a framework though Apache Isis is less dogmatic about such things. Generally the domain objects are mapped to a relational database and so we can lean on the referential integrity capabilities of the persistence layer to maintain referential invariants. Said another way: we donât tend to require that only roots can maintain roots: we donât see anything wrong in an <code>InvoiceItem</code> referencing an <code>OrderItem</code>, for example.</p> + </div> + <div class="paragraph"> + <p>Nonetheless the concepts of "aggregate" and "aggregate root" are worth holding onto. Youâll likely find that youâll define a repository service (discussed in more detail below) for each aggregate root: for example <code>Order</code> will have a corresponding <code>OrderRepository</code> service. Similarly, you may also have a factory service, for example <code>OrderFactory</code>. However, you are less likely to have a repository service for the parts of an aggregate root: the role of retrieving <code>OrderItem</code>s should fall to the <code>Order</code> (typically by way of lazy loading of an "items" collection) rather than through an <code>OrderItemRepository</code> service. Again, this isnât a hard-n-fast rule, but a good rule of thumb.</p> </div> <div class="admonitionblock tip"> <table> @@ -1069,7 +1214,7 @@ <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td> <td class="content"> <div class="paragraph"> - <p>At the time of writing Apache Isis only recognizes and supports the JDO API, though we expect JPA to be supported in the future.</p> + <p>Details on how to actually write a domain entity (the programming model for domain entities) is <a href="../ugfun/ugfun.html#_ugfun_programming-model_domain-entities">here</a>.</p> </div> </td> </tr> </tbody> @@ -1077,129 +1222,212 @@ </div> </div> <div class="sect3"> - <h4 id="__ugfun_core-concepts_building-blocks_types-of-domain-objects">2.4.2. Type of Domain Objects</h4> - <div class="paragraph"> - <p>Most domain objects that the end-user interacts with are <strong>domain entities</strong>, such as <code>Customer</code>, <code>Order</code>, <code>Product</code> and so on. These are persistent objects and which are mapped to a database (usually relational), using JDO/DataNucleus annotations. From the end-userâs perspective the UI displays a single domain object per page; they can then inspect and modify its state, and navigate to related objects.</p> - </div> - <div class="paragraph"> - <p>The next type of domain object to discuss is <strong>domain services</strong>. These are (usually) singleton stateless services that provide additional functionality. The behaviour of these services is rendered in various ways, though the most obvious is as the menu actions on the top-level menu bars in the <a href="ugvw.html">Wicket viewer</a>'s UI.</p> - </div> - <div class="paragraph"> - <p>Domain objects can also delegate to domain services; domain services are automatically injected into every other domain object; this includes domain entities as well as other services. This injection of domain services into entities is significant: it allows business logic to be implemented in the domain entities, rather than have it "leach away" into supporting service layers. Said another way: it is the means by which Apache Isis helps you avoid the anaemic domain model anti-pattern.</p> - </div> + <h4 id="_ugfun_building-blocks_types-of-domain-objects_domain-services">3.2.2. Domain Services</h4> + <button type="button" class="button secondary" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_types-of-domain-objects_domain-services.adoc""; style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i> Edit</button> <div class="paragraph"> - <p>As well as domain entitiesâââmapped to a datastoreâââApache Isis also supports <strong>view models</strong>. End users interact with view models in the same way as a domain entity, indeed they are unlikely to distinguish one from the other. However view models are <em>not</em> mapped to the underlying database, rather they represent some aggregation of state from one or more underlying entities. Their state is serialized and recreated from their internal identifier; this identifier is visible as the objectâs URL in the <a href="ugvw.html">Wicket viewer</a> or <a href="ugvro.html">RestfulObjects viewer</a>.</p> + <p><em>Domain services</em> are (usually) singleton stateless services that provide additional functionality. Domain services consist of a set of logically grouped actions, and as such follow the same conventions as for entities. However, a service cannot have (persisted) properties, nor can it have (persisted) collections.</p> </div> <div class="paragraph"> - <p>Thereâs no need though for the view model to aggregate the state of regular domain entities. A view model could also be used as a proxy for some externally managed entity, accessed over a web service or REST API; it could even be a representation of state held in-memory (such as user preferences, for example).</p> + <p>A very common type of domain service is a repository, that is used to look up existing instances of a domain entity. For example, for the <code>Customer</code> entity there may be a <code>CustomerRepository</code>, while for <code>Order</code> entity there may be an <code>OrderRepository</code>.</p> </div> <div class="paragraph"> - <p>There are also several types of domain services. Most easily described are those domain services (discussed above) that are represented as the menu actions on top-level menu bars. Another variation are <strong>contributed services</strong>: domain services that contribute behaviour or (derived) state to entities/view models. Finally domain services may also simply provide additional non-UI functionality; an example being to perform an address geocoding lookup against the google-maps API.</p> + <p>Similarly, entities might also have a corresponding factory service: a <code>CustomerFactory</code> or an <code>OrderFactory</code>; Evans' <a href="http://books.google.com/books/about/Domain_Driven_Design.html?id=hHBf4YxMnWMC";>Domain Driven Design</a>, draws a clear distinction is made between a factory (that creates object) and a repository (that is used to find existing objects).</p> </div> <div class="paragraph"> - <p>Also worth mentioning: domain services can also be either singletons (discussed above) or request-scoped; the latter being annotated with <code>@javax.enterprise.context.RequestScoped</code>. An example of the request-scoped service is the <a href="rgsvc.html#_rgsvc_api_Scratchpad"><code>Scratchpad</code></a> service, for sharing arbitrary data between multiple objects.</p> + <p>On the other hand, from an end-users' perspective the act of finding an existing object vs creating a new one are quite closely related. For this reason, in Apache Isis itâs therefore quite common to have a single domain service that acts as both a factory and a repository (and is usually called just a "repository").</p> </div> <div class="paragraph"> - <p>The final type of domain object is the <strong>mixin</strong>. These are similar to contributed services in that they also contribute (or rather, mixin) both behaviour or (derived) state to entities/view models. However, they provide a more control over contributed services, with a cleaner programming model similar to traits found in other languages.</p> + <p>The behaviour of these services is rendered in various ways, though the most obvious is as the menu actions on the top-level menu bars in the <a href="../ugvw/ugvw.html">Wicket viewer</a>'s UI.</p> </div> <div class="paragraph"> - <p>The diagram below summarizes the various types of domain object:</p> - </div> - <div class="imageblock"> - <div class="content"> - <a class="image" href="images/core-concepts/building-blocks/types-of-domain-object.png"><img src="images/core-concepts/building-blocks/types-of-domain-object.png" alt="types of domain object" width="860px"></a> - </div> - </div> - <div class="paragraph"> - <p>The Apache Isis programming model uses annotations to distinguish these object types:</p> + <p>Domain services can also be used for a number of other purposes:</p> </div> <div class="ulist"> <ul> - <li> <p><strong>view models</strong> are annotated either with <code>@DomainObject(nature=VIEW_MODEL)</code> or using <code>@ViewModel</code>. Which is used is a matter of personal preference. <br></p> - <div class="paragraph"> - <p>It is also possible to implement the <code>ViewModel</code> interface, for finer-grained control.</p> - </div> </li> - <li> <p><strong>domain entities</strong> that are persisted to the database (as the vast majority will) are annotated with <code>@DomainObject(nature=ENTITY)</code>. In addition such domain entities are annotated with the JDO/DataNucleus annotation of <code>@javax.jdo.annotations.PersistenceCapable</code>.<br></p> + <li> <p>to provide additional non-UI functionality; an example being to perform an address geocoding lookup against the google-maps API, or to perform some calculation, or attach a barcode, send an email etc</p> </li> + <li> <p>to act as a subscribers to the event bus, potentially influencing events fired by some other module (a key technique for decoupling large applications)<br></p> <div class="paragraph"> - <p>In addition, if a domain entity is a proxy for state managed in an external system, or merely for some state held in-memory, then <code>@DomainObject(nature=EXTERNAL_ENTITY)</code> or <code>@DomainObject(nature=INMEMORY_ENTITY)</code> can be used.</p> + <p>This is discussed in more detail below, in the section on <a href="../ugfun/ugfun.html#_ugfun_building-blocks_events">events</a>.</p> </div> </li> - <li> <p><strong>mixins</strong> are annotated either with <code>@DomainObject(nature=MIXIN)</code> or using <code>@Mixin</code>. As for view models, which is used is a matter of personal preference.</p> </li> - <li> <p>finally, <strong>domain services</strong>` are annotated with <code>@DomainService(nature=â¦â)</code> where the nature is either <code>VIEW_MENU_ONLY</code> (for domain services whose actions appear on the top-level menu bars), or <code>VIEW_CONTRIBUTIONS_ONLY</code> (for domain services whose actions are contributed to entities or view models), or <code>DOMAIN</code> (for domain services whose functionality is simply for other domain objects to invoke programmatically).</p> - <div class="paragraph"> - <p>It is also possible to specify a nature of simply <code>VIEW</code>, this combining <code>VIEW_MENU_ONLY</code> and <code>VIEW_CONTRIBUTIONS_ONLY</code>. This is in fact the default, useful for initial prototyping. A final nature is <code>VIEW_REST_ONLY</code> which is for domain services whose functionality is surfaced only by the <a href="ugvro.html">RestfulObjects viewer</a>.</p> + <li> <p>to implement an <a href="https://en.wikipedia.org/wiki/Service_provider_interface";>SPI</a> of the Apache Isis framework, most notably cross-cutting concerns such as security, command profiling, auditing and publishing.</p> </li> + <li> <p>to contribute behaviour or (derived) state to entities/view models.<br></p> + <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>Mixins can do everything that contributed services can, and have a cleaner programming model. As such, contributed services should be considered a deprecated feature; it may be removed in a future release.</p> + </div> </td> + </tr> + </tbody> + </table> </div> </li> </ul> </div> <div class="paragraph"> - <p>Worth emphasising is that domain entities and view models hold state, whereas domain services are generally stateless. If a domain service does hold state (eg the <code>Scratchpad</code> service noted above) then it should be <code>@RequestScoped</code> so that this state is short-lived and usable only within a single request.</p> + <p>Domain objects of any type (entities, other services, view models, mixins) can also delegate to domain services; domain services are automatically injected into every other domain object. This injection of domain services into entities is significant: it allows business logic to be implemented in the domain entities, rather than have it "leach away" into supporting service layers. Said another way: it is the means by which Apache Isis helps you avoid the anaemic domain model anti-pattern.</p> + </div> + <div class="paragraph"> + <p>Domain services are instantiated once and once only by the framework, and are used to centralize any domain logic that does not logically belong in a domain entity or value.</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>Details on how to actually write a domain service (the programming model for domain services) is <a href="../ugfun/ugfun.html#_ugfun_programming-model_domain-services">here</a>.</p> + </div> </td> + </tr> + </tbody> + </table> + </div> + <div class="sect4"> + <h5 id="_hexagonal_arch_services">Hexagonal Arch. + services</h5> + <div class="paragraph"> + <p>Itâs worth extending the <a href="../ugfun/ugfun.html#_ugfun_core-concepts_philosophy_hexagonal-architecture">Hexagonal Architecture</a> to show where domain services fit in:</p> + </div> + <div class="imageblock"> + <div class="content"> + <img src="images/core-concepts/philosophy/hexagonal-architecture-addons.png" alt="hexagonal architecture addons" width="700px"> + </div> + <div class="title"> + Figure 4. The hexagonal architecture with Isis addons + </div> + </div> + <div class="paragraph"> + <p>The (non-ASF) <a href="http://isisaddons.org";>Isis Addons</a> provide SPI implementations of the common cross-cutting concerns. They also provide a number of APIs for domain objects to invoke (not shown in the diagram). You can also write your own domain services as well, for example to interface with some external CMS system, say.</p> + </div> </div> </div> <div class="sect3"> - <h4 id="__ugfun_core-concepts_building-blocks_objects-members">2.4.3. Object Members</h4> + <h4 id="_ugfun_building-blocks_types-of-domain-objects_view-models">3.2.3. View Models</h4> + <button type="button" class="button secondary" onclick="window.location.href="https://github.com/apache/isis/edit/master/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_types-of-domain-objects_view-models.adoc""; style="float: right; font-size: small; padding: 6px; margin-top: -55px; "><i class="fa fa-pencil-square-o"></i> Edit</button> + <div class="paragraph"> + <p>View models are similar to entities in that (unlike domain services) there can be many instances of any given type. End users interact with view models in the same way as a domain entity, indeed they are unlikely to distinguish one from the other.</p> + </div> <div class="paragraph"> - <p>Every domain object in Apache Isis consists of (at most) three types of members:</p> + <p>However, whereas a domain entities is mapped to a datastore, view models are not. Instead they are recreated dynamically by serializing their state, ultimately into the URL itself (meaning their state it is in effect implicitly managed by the client browser). You will notice that the URL for view models (as shown in <a href="../ugvw/ugvw.html">Wicket viewer</a> or <a href="../ugvro/ugvro.html">RestfulObjects viewer</a>) tends to be quite long.</p> + </div> + <div class="paragraph"> + <p>This capability opens up a number of more advanced use cases:</p> </div> <div class="ulist"> <ul> - <li> <p>properties, such as a `Customerâs `firstName</p> </li> - <li> <p>collections, such as a <code>Customerâs `orders</code> collection of <code>Order</code>s</p> </li> - <li> <p>actions, such as a <code>Customer'`s `placeOrder(â¦â)</code> method.</p> </li> + <li> <p>In the same way that an (RDBMS) database view can aggregate and abstract from multiple underlying database tables, so a view model sits on top of one or many underlying entities.</p> </li> + <li> <p>A view model could also be used as a proxy for some externally managed entity, accessed over a web service or REST API; it could even be a representation of state held in-memory (such as user preferences, for example).</p> </li> + <li> <p>view models can also be used to support a particular use case. An example that comes to mind is to expose a list of scanned PDFs to be processed as an "intray", showing the list of PDFs on one side of the page, and the current PDF being viewed on the other. Such view models are part of the application layer, not part of the domain layer (where entities live).</p> </li> </ul> </div> <div class="paragraph"> - <p>Some domain objectsâââspecifically domain services and mixinsâââonly have actions. In the case of contributing services and mixins these actions can (depending upon their semantics and signatures) be represented as derived properties or collections on the entity/view model to which they contribute/mix-in.</p> + <p>We explore these use cases in more detail below.</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>Details on how to actually write a view model (the programming model for view models) is <a href="../ugfun/ugfun.html#_ugfun_programming-model_view-models">here</a>.</p> + </div> </td> + </tr> + </tbody> + </table> </div> <div class="sect4"> - <h5 id="_properties">Properties</h5> + <h5 id="__ugfun_building-blocks_view-models_externally-managed-entities">Externally-managed entities</h5> <div class="paragraph"> - <p>Properties follow the standard getter/setter pattern, with the return type being a scalar (a value object or another entity or view model).</p> + <p>Sometimes the entities that make up your application are persisted not in the local JDO/DataNucleus database but reside in some other system, for example accessible only through a SOAP web service. Logically that data might still be considered a domain entity and we might want to associate behaviour with it, however it cannot be modelled as a domain entity if only because JDO/DataNucleus doesnât know about the entity nor how to retrieve or update it.</p> </div> <div class="paragraph"> - <p>For example, with:</p> + <p>There are a couple of ways around this: we could either replicate the data somehow from the external system into the Isis-managed database (in which case it is once again just another domain entity), or we could set up a stub/proxy for the externally managed entity. This proxy would hold the reference to the externally-managed domain entity (eg an external id), as well as the "smarts" to know how to interact with that entity (by making SOAP web service calls etc).</p> </div> - <div class="listingblock"> - <div class="content"> - <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">Customer</span> - <span class="directive">private</span> <span class="predefined-type">String</span> firstName; - <span class="directive">public</span> <span class="predefined-type">String</span> getFirstName() { <span class="keyword">return</span> firstName; } - <span class="directive">public</span> <span class="type">void</span> setFirstName(<span class="predefined-type">String</span> firstName) { <span class="local-variable">this</span>.firstName = firstName; } - ... -}</code></pre> - </div> + <div class="paragraph"> + <p>The stub/proxy is a type of view model: a viewâââif you likeâââonto the domain entity managed by the external system.</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>DataNucleus does in fact define its own <a href="http://www.datanucleus.org/documentation/extensions/store_manager.html";>Store Manager</a> extension point, so an alternative architecture would be to implement this interface such that DataNucleus could make the calls to the external system; these externally-persisted domain entities would therefore be modelled as regular <code>@PersistenceCapable</code> entities after all. For entities not persisted externally the implementation would delegate down to the default RDBMS-specific <code>StoreManager</code> provided by DataNucleus itself.</p> + </div> + <div class="paragraph"> + <p>An implementation that supported only reading from an external entity ought to be comparatively straight-forward, but implementing one that also supported updating external entities would need to carefully consider error conditions if the external system is unavailable; distributed transactions are most likely difficult/impossible to implement (and not desirable in any case).</p> + </div> </td> + </tr> + </tbody> + </table> + </div> + </div> + <div class="sect4"> + <h5 id="__ugfun_building-blocks_view-models_in-memory-entities">In-memory entities</h5> + <div class="paragraph"> + <p>As a variation on the above, sometimes there are domain objects that are, conceptually at least entities, but whose state is not actually persisted anywhere, merely held in-memory (eg in a hash).</p> </div> <div class="paragraph"> - <p>the framework infers the <code>Customer</code> domain entity, which in turn has a <code>firstName</code> string <em>property</em>.</p> + <p>A simple example might be read-only configuration data that is read from a config file (eg log4j appender definitions) but thereafter is presented in the UI just like any other entity.</p> </div> </div> <div class="sect4"> - <h5 id="_collections">Collections</h5> + <h5 id="__ugfun_building-blocks_view-models_application-layer-view-models">Application-layer view models</h5> <div class="paragraph"> - <p>Collections are also represented by a getter and setter, however the return type is a <code>Collection</code> or subtype.</p> + <p>Domain entities (whether locally persisted using JDO/DataNucleus or managed externally) are the bread-and-butter of Apache Isis applications: the focus after all, should be on the business domain concepts and ensuring that they are solid. Generally those domain entities will make sense to the business domain experts: they form the <em>ubiquitous language</em> of the domain. These domain entities are part of the domain layer.</p> </div> <div class="paragraph"> - <p>For example, with:</p> + <p>That said, it may not always be practical to expect end-users of the application to interact solely with those domain entities. For example, it may be useful to show a dashboard of the most significant data in the system to a user, often pulling in and aggregating information from multiple points of the app. Obtaining this information by hand (by querying the respective services/repositories) would be tedious and slow; far better to have a dashboard do the job for the end user.</p> </div> - <div class="listingblock"> + <div class="paragraph"> + <p>A dashboard object is a model of the most relevant state to the end-user, in other words it is (quite literally) a view model. It is not a persisted entity, instead it belongs to the application layer.</p> + </div> + <div class="paragraph"> + <p>A view model need not merely aggregate data; it could also provide actions of its own. Most likely these actions will be queries and will always ultimately just delegate down to the appropriate domain-layer service/repository. But in some cases such view model actions might also modify state of underlying domain entities.</p> + </div> + <div class="paragraph"> + <p>Another common use for view models is to help co-ordinate complex business processes; for example to perform a quarterly invoicing run, or to upload annual interest rates from an Excel spreadsheet. In these cases the view model might have some state of its own, but in most cases that state does not need to be persisted per se.</p> + </div> + <div class="sidebarblock"> <div class="content"> - <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">Customer</span> - <span class="directive">private</span> <span class="predefined-type">SortedSet</span><Order> orders = <span class="keyword">new</span> <span class="predefined-type">TreeSet</span><Order>(); - <span class="directive">public</span> <span class="predefined-type">SortedSet</span><Order> getOrders() { <span class="keyword">return</span> orders; } - <span class="directive">public</span> <span class="type">void</span> setOrders(<span class="predefined-type">SortedSet</span><Order> orders) { <span class="local-variable">this</span>.orders = orders; } - ... -}</code></pre> + <div class="title"> + Desire Lines + </div> + <div class="paragraph"> + <p>One way to think of application view models is as modelling the "desire line": the commonly-trod path that end-users must follow to get from point A to point B as quickly as possible.</p> + </div> + <div class="paragraph"> + <p>To explain: there are <a href="http://ask.metafilter.com/62599/Where-the-sidewalk-ends";>documented</a> <a href="https://sivers.org/walkways";>examples</a> <a href="http://www.softpanorama.org/People/Wall/larry_wall_articles_and_interviews.shtml";>that</a> architects of university campus will only add in paths some while after the campus buildings are complete: let the pedestrians figure out the routes they want to take. The name we like best for this idea is "desire lines", though it has also been called a "desire path", "paving the path" or "paving the sidewalk".</p> + </div> + <div class="paragraph"> + <p>What that means is you should add view models <em>after</em> having built up the domain layer, rather than before. These view models pave that commonly-trod path, automating the steps that the end-user would otherwise have to do by hand.</p> + </div> + <div class="paragraph"> + <p>It takes a little practice though, because even when building the domain layer "first", you should still bear in mind what the use cases are that those domain entities are trying to support. You certainly <em>shouldnât</em> try to build out a domain layer that could support every conceivable use case before starting to think about view models.</p> + </div> + <div class="paragraph"> + <p>Instead, you should iterate. Identify the use case/story/end-user objective that you will deliver value to the business. Then build out the minimum domain entities to support that use case (refining the <a href="../ugfun/ugfun.html#__ugfun_core-concepts_philosophy_domain-driven-design_ubiquitous-language">ubiquitous language</a> as you go). Then, identify if there any view models that could be introduced which would simplify the end-user interactions with the system (perhaps automating several related use cases together).</p> + </div> </div> </div> <div class="paragraph"> - <p>the framework infers the <code>orders</code> <em>collection</em>.</p> + <p>When developing an Apache Isis application you will most likely start off with the persistent domain entities: <code>Customer</code>, <code>Order</code>, <code>Product</code>, and so on. For some applications this may well suffice.</p> </div> - <div class="admonitionblock tip"> + <div class="paragraph"> + <p>However, if the application needs to integrate with other systems, or if the application needs to support reasonably complex business processes, then you may need to look beyond just domain entities; view models are the tool of choice.</p> + </div> + <div class="admonitionblock warning"> <table> <tbody> <tr> - <td class="icon"> <i class="fa icon-tip" title="Tip"></i> </td> + <td class="icon"> <i class="fa icon-warning" title="Warning"></i> </td> <td class="content"> <div class="paragraph"> - <p>The most commonly used collection type is <code>java.util.SortedSet</code>; entities are most commonly mapped to a relational database (ie a datastore with set semantics) and we recommend that all entities define a natural ordering so that when rendered in the UI they will be ordered "meaningfully" to the end-user.</p> + <p>We strongly recommend that you build your applications from the domain layer up, rather than from the view model down.</p> </div> </td> </tr> </tbody> @@ -1207,32 +1435,33 @@ </div> </div> <div class="sect4"> - <h5 id="_actions">Actions</h5> + <h5 id="__ugfun_building-blocks_view-models_dtos">DTOs</h5> <div class="paragraph"> - <p>The third type of object member is actions. (To a first approximation), actions are all public methods that do not represent properties or collections.</p> + <p>DTOs (data transfer objects) are simple classes that (according to <a href="https://en.wikipedia.org/wiki/Data_transfer_object";>wikipedia</a>) "carry data between processes".</p> </div> <div class="paragraph"> - <p>For example:</p> + <p>If those two processes are parts of the same overall application (the same team builds and deploys both server and client) then thereâs generally no need to define a DTO; just access the entities using Apache Isis' <a href="../ugvro/ugvro.html">RestfulObjects viewer</a>.</p> </div> - <div class="listingblock"> - <div class="content"> - <pre class="CodeRay highlight"><code data-lang="java"><span class="directive">public</span> <span class="type">class</span> <span class="class">Customer</span> - <span class="directive">public</span> Customer placeOrder(Product p, <span class="type">int</span> quantity) { ... } - ... -}</code></pre> - </div> + <div class="paragraph"> + <p>On the other hand, if the client consuming the DTO is a different applicationâââby which we mean developed/deployed by a different (possible third-party) teamâââthen the DTOs act as a formal contract between the provider and the consumer. In such cases, exposing domain entities over <a href="../ugvro/ugvro.html">RestfulObjects</a> would be "A Bad Thing"⢠because the consumer would in effect have access to implementation details that could then not be easily changed by the producer.</p> </div> <div class="paragraph"> - <p>corresponds to the <code>placeOrder</code> <em>action</em>.</p> + <p>To support this use case, a view model can be defined such that it can act as a DTO. This is done by annotating the class us
<TRUNCATED>
