ugfun.adoc - services and mixins

Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/9e1ea1b6
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/9e1ea1b6
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/9e1ea1b6

Branch: refs/heads/wip
Commit: 9e1ea1b605d58db4524b6d35a0f8bd6f9b9672e5
Parents: 9fbf3d5
Author: Dan Haywood <d...@haywood-associates.co.uk>
Authored: Sat Apr 15 11:04:39 2017 +0100
Committer: Dan Haywood <d...@haywood-associates.co.uk>
Committed: Thu Apr 20 09:09:30 2017 +0100

----------------------------------------------------------------------
 .../ugfun/_ugfun_core-concepts_add-ons.adoc     |  42 ++++++++++++------
 .../ugfun/_ugfun_domain-class-ontology.adoc     |  14 +++---
 ...n_domain-class-ontology_domain-services.adoc |  43 +++++++++++++------
 .../_ugfun_domain-class-ontology_mixins.adoc    |   2 +
 .../hexagonal-architecture-addons.png           | Bin 0 -> 100666 bytes
 .../philosophy/hexagonal-architecture.png       | Bin 85844 -> 75942 bytes
 .../philosophy/hexagonal-architecture.pptx      | Bin 263812 -> 263049 bytes
 7 files changed, 69 insertions(+), 32 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/9e1ea1b6/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_add-ons.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_add-ons.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_add-ons.adoc
index cfae890..c13a4b2 100644
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_add-ons.adoc
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_core-concepts_add-ons.adoc
@@ -1,36 +1,54 @@
 [[_ugfun_core-concepts_add-ons]]
-= Isis Add-ons
+= Isis Add-ons & Incode Catalog
 :Notice: Licensed to the Apache Software Foundation (ASF) under one or more 
contributor license agreements. See the NOTICE file distributed with this work 
for additional information regarding copyright ownership. The ASF licenses this 
file to you under the Apache License, Version 2.0 (the "License"); you may not 
use this file except in compliance with the License. You may obtain a copy of 
the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by 
applicable law or agreed to in writing, software distributed under the License 
is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY 
KIND, either express or implied. See the License for the specific language 
governing permissions and limitations under the License.
 :_basedir: ../../
 :_imagesdir: images/
 
 
-The link:http://www.isisaddons.org[Isis Addons] website provides a number of 
reusable modules and other extensions for Apache Isis.
-This chapter focuses just on the modules, all of which have a name of the form 
`isis-module-xxx`.
+The link:http://www.isisaddons.org[Isis Addons] website provides a number of 
reusable modules for Apache Isis, focusing either on specific technologies or 
in technical cross-cutting concerns.
+Some of these modules implement SPIs defined by the framework.
+
+The link:http://catalog.incode.org[Incode Catalog] website also provides a 
number of reusable modules, focusing on business logic for generic subdomains.
+
+This section surveys the functionality available.
+
 
 [WARNING]
 ====
-Note that Isis Addons, although maintained by Apache Isis committers, are not 
part of the ASF.
+Note that Isis Addons and Incode Catalog, although maintained by Apache Isis 
committers, are not part of the ASF.
 ====
 
 
 
-The modules themselves fall into four broad groups:
+The modules themselves fall into a number of broader groups:
 
-* modules that provide an implementations of API defined by Apache Isis +
+* modules that provide an implementations of SPI defined by Apache Isis +
 +
-where Apache Isis has hooks to use the service if defined by provides no 
implementations of its own.  The 
http://github.com/isisaddons/isis-module-command[command], 
http://github.com/isisaddons/isis-module-audit[auditing], 
http://github.com/isisaddons/isis-module-publishing[publishing], 
http://github.com/isisaddons/isis-module-security[security]  and 
http://github.com/isisaddons/isis-module-sessionlogger[sessionlogger] modules 
fall into this category.  Typically the domain objects themselves wouldn't 
interact with these services
+where Apache Isis has hooks to use the service if defined by provides no 
implementations of its own. +
++
+From the link:http://www.isisaddons.org[Isis Addons] website, the 
http://github.com/isisaddons/isis-module-command[command], 
http://github.com/isisaddons/isis-module-audit[auditer], 
http://github.com/isisaddons/isis-module-publishmq[publisher], 
http://github.com/isisaddons/isis-module-security[security]  and 
http://github.com/isisaddons/isis-module-sessionlogger[sessionlogger] modules 
fall into this category.  Typically the domain objects themselves wouldn't 
interact with these services
 
 * modules that provide standalone domain services with their own API and 
implementation +
 +
-These are simply intended to be used by domain objects.  The 
http://github.com/isisaddons/isis-module-docx[docx], 
http://github.com/isisaddons/isis-module-excel[excel], 
http://github.com/isisaddons/isis-module-settings[settings] and 
http://github.com/isisaddons/isis-module-stringinterpolator[stringinterpolator] 
fall into this category.
+These are simply intended to be used by domain objects. +
++
+From the link:http://www.isisaddons.org[Isis Addons] website, the 
http://github.com/isisaddons/isis-module-docx[docx], 
http://github.com/isisaddons/isis-module-excel[excel], 
http://github.com/isisaddons/isis-module-freemarker[freemarker], 
http://github.com/isisaddons/isis-module-pdfbox[pdfbox], 
http://github.com/isisaddons/isis-module-settings[settings], 
http://github.com/isisaddons/isis-module-servletapi[servletapi], 
http://github.com/isisaddons/isis-module-stringinterpolator[stringinterpolator] 
and http://github.com/isisaddons/isis-module-xdocreport[xdocreport] fall into 
this category. +
++
+From the link:http://catalog.incode.org[Incode Catalog] website, the 
http://github.com/incodehq/incode-module-alias[alias], 
http://github.com/incodehq/incode-module-classification[classification], 
http://github.com/incodehq/incode-module-commchannel[commchannel], 
http://github.com/incodehq/incode-module-communications[communications], 
http://github.com/incodehq/incode-module-country[country], 
http://github.com/incodehq/incode-module-docfragment[docfragment],
+http://github.com/incodehq/incode-module-document[document] and 
http://github.com/incodehq/incode-module-document[note] modules fall into this 
category.
 
 * modules that provide standalone domain entities (and supporting services) 
for a particular subdomain +
 +
-The http://github.com/isisaddons/isis-module-tags[tags] module falls into this 
category
+From the link:http://www.isisaddons.org[Isis Addons] website, the 
http://github.com/isisaddons/isis-module-tags[tags] module falls into this 
category
+
+* modules that provide developer/testing utilities +
++
+From the link:http://www.isisaddons.org[Isis Addons] website, the 
http://github.com/isisaddons/isis-module-fakedata[fakedata] module provides 
fakedata for unit- and integration testing +
++
+From the link:http://catalog.incode.org[Incode Catalog] website, the 
http://github.com/incodehq/incode-module-fixturesupport[fixturesupport], 
http://github.com/incodehq/incode-module-integtestsupport[integtestsupport] and 
http://github.com/incodehq/incode-module-unittestsupport[unittestsupport] 
modules fall into this category.
 
-* modules that provide developer utilities +
+* modules that support runtime/integration support +
 +
-Not intended for use by either the framework or domain objects, but provide 
utilities that the developer themselves might use.  The 
http://github.com/isisaddons/isis-module-devutils[devutils] module (not 
suprisingly) falls into this category
+From the link:http://www.isisaddons.org[Isis Addons] website, 
link:http://github.com/isisaddons/isis-module-flywaydb[flywaydb] handle RDBMS 
schema migration, http://github.com/isisaddons/isis-module-quartz[quartz] 
provides scheduling of background jobs; and the 
http://github.com/isisaddons/isis-module-togglz[togglz] provides feature 
toggles.
 
-Each of the modules has a full README and example application demonstrating 
their usage.  The sections below briefly outline the capabilities of these 
modules.
+Each of the modules has a full README and demo application demonstrating their 
usage.  The sections below briefly outline the capabilities of these modules.

http://git-wip-us.apache.org/repos/asf/isis/blob/9e1ea1b6/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology.adoc
index 7e496a0..580f084 100644
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology.adoc
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology.adoc
@@ -6,13 +6,16 @@
 
 
 
-Apache Isis supports recognises three main types of domain classes:
+Apache Isis supports recognises four main types of domain classes:
 
-* domain entities - domain objects persisted to the database using 
JDO/DataNucleus; for example `Customer`
+* xref:../ugfun/ugfun.adoc#_ugfun_domain-class-ontology_domain-entities[domain 
entities] - domain objects persisted to the database using JDO/DataNucleus; for 
example `Customer`
 
-* domain services - generally singletons, automatically injected, and 
providing various functionality; for example `CustomerRepository`
+* xref:../ugfun/ugfun.adoc#_ugfun_domain-class-ontology_domain-services[domain 
services] - generally singletons, automatically injected, and providing various 
functionality; for example `CustomerRepository`
 
-* view models - domain objects that are a projection of some state held by the 
database, in support a particular use case; for example `CustomerDashboard` (to 
pull together commonly accessed information about a customer).
+* xref:../ugfun/ugfun.adoc#_ugfun_domain-class-ontology_view-models[view 
models] - domain objects that are a projection of some state held by the 
database, in support a particular use case; for example `CustomerDashboard` (to 
pull together commonly accessed information about a customer).
+
+* xref:../ugfun/ugfun.adoc#_ugfun_domain-class-ontology_mixins[mixins] - 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 decoupled.
 
 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).
@@ -37,7 +40,6 @@ In the same way that the Java module act as a namespace for 
domain objects, it's
 include::_ugfun_domain-class-ontology_domain-entities.adoc[leveloffset=+1]
 include::_ugfun_domain-class-ontology_domain-services.adoc[leveloffset=+1]
 include::_ugfun_domain-class-ontology_view-models.adoc[leveloffset=+1]
-
-
+include::_ugfun_domain-class-ontology_mixins.adoc[leveloffset=+1]
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/9e1ea1b6/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_domain-services.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_domain-services.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_domain-services.adoc
index e89b754..25b27db 100644
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_domain-services.adoc
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_domain-services.adoc
@@ -14,12 +14,14 @@ In Apache Isis domain services have several 
responsibilities:
 - they provide other services (eg performing calculations, attach a barcode, 
send an email etc).
 - to implement an SPI of the framework, most notably cross-cutting concerns 
such as security, command profiling, auditing and publishing.
 
-It's worth extending the 
xref:../ugfun/ugfun.adoc#_ugfun_core-concepts_philosophy_hexagonal-architecture[Hexagonal
 Architecture] to show where domain services -- and in particular the domain 
services provided by link:http://www.isisaddons.org[Isis Addons] (non-ASF) -- 
fit in:
+It's worth extending the 
xref:../ugfun/ugfun.adoc#_ugfun_core-concepts_philosophy_hexagonal-architecture[Hexagonal
 Architecture] to show where domain services fit in:
 
 .The hexagonal architecture with Isis addons
-image::{_imagesdir}how-tos/domain-services/hexagonal-architecture-addons.png[width="700px"]
+image::{_imagesdir}core-concepts/philosophy/hexagonal-architecture-addons.png[width="700px"]
 
-The (non-ASF) link:http://isisaddons.org[Isis Addons] are a good source of 
domain services, providing SPI implementations of the common cross-cutting 
concerns, and also a number of APIs for domain objects to invoke (eg tags, 
excel, settings).  Of course, you can also write your own domain services as 
well, for example to interface with some external CMS system, say.
+The (non-ASF) link:http://isisaddons.org[Isis Addons] 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.
 
 
 
@@ -38,9 +40,10 @@ The application provides the `@DomainService(nature=...)` 
annotation that helps
 Pulling all the above together, here are our suggestions as to how you should 
organize your domain services.
 
 
-=== Factory and Repository
+[[__ugfun_domain-class-ontology_domain-services_factory-and-repository]]
+== Factory and Repository
 
-The factory/repository uses an injected `DomainObjectContainer` to both 
instantiate new objects and to query the database for existing objects of a 
given entity type.  It is not visible in UI, rather other services delegate to 
it.
+The factory/repository uses an injected 
xref:../rgsvc/rgsvc.adoc#_rgsvc_api_RepositoryService[`RepositoryService`] to 
both instantiate new objects and to query the database for existing objects of 
a given entity type.  It is not visible in UI, rather other services delegate 
to it.
 
 We suggest naming such classes `XxxRepository`, eg:
 
@@ -52,7 +55,7 @@ We suggest naming such classes `XxxRepository`, eg:
 )
 public CustomerRepository {
     public List<Customer> findCustomerBy...(...) {
-        return allMatches(...);
+        return repositoyService.allMatches(...);
     }
     public Customer newCustomer(...) {
         Customer Customer = container.newTransientInstance(Customer.class);
@@ -61,10 +64,10 @@ public CustomerRepository {
         return Customer;
     }
     public List<Customer> allCustomers() {
-        return container.allInstances(Customer.class);
+        return repositoryService.allInstances(Customer.class);
     }
     @Inject
-    DomainObjectContainer container;
+    RepositoryService repositoryService;
 }
 ----
 <1> interacted with only programmatically by other objects in the domain layer.
@@ -72,8 +75,8 @@ public CustomerRepository {
 There is no need to annotate the actions; they are implicitly hidden because 
of the domain service's nature.
 
 
-
-=== Menu
+[[__ugfun_domain-class-ontology_domain-services_menu]]
+== Menu
 
 Menu services provide actions to be rendered on the menu.
 
@@ -137,10 +140,19 @@ Note also that while there's nothing to stop `VIEW_MENU` 
domain services being i
 
 
 
-=== Contributions
+[[__ugfun_domain-class-ontology_domain-services_contributions]]
+== Contributions (deprecated)
+
 
 Services can contribute either actions, properties or collections, based on 
the type of their parameters.
 
+[TIP]
+====
+Contributed services can instead be implemented as
+xref:../ugfun/ugfun.adoc#_ugfun_domain-class-ontology_mixins[mixins].
+As such, contributed services should be considered as deprecated.
+====
+
 We suggest naming such classes `XxxContributions`, eg:
 
 [source,java]
@@ -152,7 +164,7 @@ We suggest naming such classes `XxxContributions`, eg:
     menuOrder="10",
     name="...",
 }
-public OrderContributions {
+public class OrderContributions {
     @Action(semantics=SemanticsOf.SAFE)
     @ActionLayout(contributed=Contributed.AS_ASSOCIATION)       // <2>
     @CollectionLayout(render=RenderType.EAGERLY)
@@ -172,7 +184,10 @@ More information about contributions can be found 
xref:../ugfun/ugfun.adoc#_ugfu
 about using contributions and mixins to keep your domain application decoupled 
can be found xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_contributions[here] and 
xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_mixins[here].
 
 
-=== Event Subscribers
+
+
+[[__ugfun_domain-class-ontology_domain-services_event-subscribers]]
+== Event Subscribers
 
 Event subscribers can both veto interactions (hiding members, disabling 
members or validating changes), or can react to interactions (eg action 
invocation or property edit).
 
@@ -187,7 +202,7 @@ We suggest naming such classes `XxxSubscriptions`, eg:
     menuOrder="10",
     name="...",
 }
-public CustomerOrderSubscriptions {
+public class CustomerOrderSubscriptions {
     @com.google.common.eventbus.Subscribe
     public void on(final Customer.DeletedEvent ev) {
         Customer customer = ev.getSource();

http://git-wip-us.apache.org/repos/asf/isis/blob/9e1ea1b6/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_mixins.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_mixins.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_mixins.adoc
index abecbd5..0acc6cb 100644
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_mixins.adoc
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_domain-class-ontology_mixins.adoc
@@ -52,3 +52,5 @@ public class Customer_orders {                              
// <2>
 This could also be an interface.
 <4> Indicates that the action should be interpreted as a collection.
 This requires that the action has safe semantics, ie does not alter state/no 
side-effects.
+
+There is further discussion of mixins in the 
xref:../ugbtb/ugbtb.adoc#_ugbtb_decoupling_mixins[beyond the basics] guide.
\ No newline at end of file

http://git-wip-us.apache.org/repos/asf/isis/blob/9e1ea1b6/adocs/documentation/src/main/asciidoc/guides/ugfun/images/core-concepts/philosophy/hexagonal-architecture-addons.png
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/core-concepts/philosophy/hexagonal-architecture-addons.png
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/core-concepts/philosophy/hexagonal-architecture-addons.png
new file mode 100644
index 0000000..ff271e9
Binary files /dev/null and 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/core-concepts/philosophy/hexagonal-architecture-addons.png
 differ

http://git-wip-us.apache.org/repos/asf/isis/blob/9e1ea1b6/adocs/documentation/src/main/asciidoc/guides/ugfun/images/core-concepts/philosophy/hexagonal-architecture.png
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/core-concepts/philosophy/hexagonal-architecture.png
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/core-concepts/philosophy/hexagonal-architecture.png
index d8b28bd..9d9a2c6 100644
Binary files 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/core-concepts/philosophy/hexagonal-architecture.png
 and 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/core-concepts/philosophy/hexagonal-architecture.png
 differ

http://git-wip-us.apache.org/repos/asf/isis/blob/9e1ea1b6/adocs/documentation/src/main/asciidoc/guides/ugfun/images/core-concepts/philosophy/hexagonal-architecture.pptx
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/core-concepts/philosophy/hexagonal-architecture.pptx
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/core-concepts/philosophy/hexagonal-architecture.pptx
index 3eb0aad..f6c7adb 100644
Binary files 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/images/core-concepts/philosophy/hexagonal-architecture.pptx
 and 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/images/core-concepts/philosophy/hexagonal-architecture.pptx
 differ

Reply via email to