You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2017/04/17 10:32:30 UTC
[36/43] isis git commit: ugfun.adoc - services and mixins
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/a18c7b24
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/a18c7b24
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/a18c7b24
Branch: refs/heads/wip
Commit: a18c7b241f35dd3c33917ee630936164c1cbb407
Parents: d84ec71
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Sat Apr 15 11:04:39 2017 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Sat Apr 15 11:04:39 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/a18c7b24/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/a18c7b24/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/a18c7b24/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/a18c7b24/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/a18c7b24/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/a18c7b24/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/a18c7b24/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