object titles and icons; fixing links
Project: http://git-wip-us.apache.org/repos/asf/isis/repo Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/85b1e70b Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/85b1e70b Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/85b1e70b Branch: refs/heads/wip Commit: 85b1e70b20db42fb7e576d38d5df995eb1279eab Parents: 2ca2ea1 Author: Dan Haywood <d...@haywood-associates.co.uk> Authored: Mon Apr 17 17:44:16 2017 +0100 Committer: Dan Haywood <d...@haywood-associates.co.uk> Committed: Thu Apr 20 09:09:30 2017 +0100 ---------------------------------------------------------------------- .../guides/cgcom/_cgcom-applying-patches.adoc | 90 --- .../guides/cgcom/_cgcom_applying-patches.adoc | 90 +++ .../cgcom/_cgcom_release-process-prereqs.adoc | 2 +- .../src/main/asciidoc/guides/cgcom/cgcom.adoc | 4 +- .../asciidoc/guides/dg/_dg_asciidoc-syntax.adoc | 4 +- .../asciidoc/guides/dg/_dg_building-isis.adoc | 2 +- .../asciidoc/guides/dg/_dg_ide_intellij.adoc | 4 +- .../asciidoc/guides/dg/_dg_project-lombok.adoc | 2 +- .../asciidoc/guides/rgcms/_rgcms_classes.adoc | 2 +- .../guides/rgcms/_rgcms_classes_layout.adoc | 2 +- .../rgcms/_rgcms_classes_mixins_Object.adoc | 2 +- ..._rgfis_spi_MessageBrokerServiceInternal.adoc | 2 +- ...s_spi_PersistenceSessionServiceInternal.adoc | 2 +- ...is_spi_TransactionStateProviderInternal.adoc | 2 +- .../guides/rgsvc/_rgsvc_api_LayoutService.adoc | 2 +- .../guides/rgsvc/_rgsvc_api_SwaggerService.adoc | 2 +- .../guides/rgsvc/_rgsvc_metadata-api.adoc | 2 +- .../rgsvc/_rgsvc_spi_ContentMappingService.adoc | 2 +- .../rgsvc/_rgsvc_spi_GridSystemService.adoc | 4 +- .../guides/rgsvc/_rgsvc_spi_HintStore.adoc | 2 +- ...placing-default-service-implementations.adoc | 2 +- ...gbtb_programming-model_custom-validator.adoc | 2 +- ...cks_types-of-domain-objects_view-models.adoc | 24 +- .../guides/ugfun/_ugfun_programming-model.adoc | 8 +- .../_ugfun_programming-model_collections.adoc | 2 +- ...ugfun_programming-model_domain-services.adoc | 359 +---------- ...ing-model_domain-services_contributions.adoc | 48 ++ ...model_domain-services_event-subscribers.adoc | 46 ++ ...ng-model_domain-services_initialization.adoc | 19 + ..._programming-model_domain-services_menu.adoc | 91 +++ ...del_domain-services_organizing-services.adoc | 33 + ...mming-model_domain-services_registering.adoc | 56 ++ ..._domain-services_repository-and-factory.adoc | 46 ++ ...g-model_domain-services_scoped-services.adoc | 23 + .../ugfun/_ugfun_programming-model_mixins.adoc | 305 +-------- ...ramming-model_mixins_contributed-action.adoc | 29 + ...ing-model_mixins_contributed-collection.adoc | 38 ++ ...mming-model_mixins_contributed-property.adoc | 35 ++ ...mming-model_mixins_contributed-services.adoc | 46 ++ ..._programming-model_mixins_inferred-name.adoc | 45 ++ ...ming-model_mixins_nested-static-classes.adoc | 78 +++ ...ramming-model_mixins_programmatic-usage.adoc | 26 + .../_ugfun_programming-model_properties.adoc | 2 +- .../_ugfun_programming-model_view-models.adoc | 629 +------------------ ...ugfun_programming-model_view-models_dto.adoc | 69 ++ ...ing-model_view-models_dto_dto-consumers.adoc | 32 + ...g-model_view-models_dto_generating-xsds.adoc | 176 ++++++ ...amming-model_view-models_dto_versioning.adoc | 106 ++++ ...gfun_programming-model_view-models_jaxb.adoc | 62 +- ...models_jaxb_referencing-domain-entities.adoc | 65 ++ ..._programming-model_view-models_non-jaxb.adoc | 69 +- ..._ugfun_ui-hints_object-titles-and-icons.adoc | 252 +++++++- ...nts-and-tips_overriding-jdo-annotations.adoc | 2 +- .../ugsec/_ugsec_usage-by-isis-viewers.adoc | 4 +- ...n-properties_suppressing-password-reset.adoc | 2 +- ...guration-properties_suppressing-sign-up.adoc | 2 +- .../guides/ugvw/_ugvw_layout_file-based.adoc | 2 +- .../_migration-notes_1.11.0-to-1.12.0.adoc | 2 +- .../_migration-notes_1.12.0-to-1.13.0.adoc | 2 +- .../_migration-notes_1.9.0-to-1.10.0.adoc | 3 +- .../asciidoc/pages/screencasts/screencasts.adoc | 12 +- 61 files changed, 1646 insertions(+), 1432 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom-applying-patches.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom-applying-patches.adoc b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom-applying-patches.adoc deleted file mode 100644 index a605202..0000000 --- a/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom-applying-patches.adoc +++ /dev/null @@ -1,90 +0,0 @@ -[[_cgcom_applying-patches]] -= Applying Patches -: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/ -:toc: right - - - -If a patch is received on a JIRA ticket, then it should be reviewed and applied. The commands are slightly different for diff files vs patch files. - - - - -== Diff files - -If a diff file has been provided, then it can easily be applied using eGit's wizards (Eclipse's Git integration)⦠- -NOTE: FIXME - this stuff needs fleshing out ... - - - - -== Patch files - -If a patch file has been provided, then it can be applied using command line tools. - -=== Inspect the patch - -First, take a look at what changes are in the patch. You can do this easily with `git apply` - -[source,bash] ----- -git apply --stat ISIS-xxx.patch ----- - -Note that this command does not apply the patch, but only shows you the stats about what itââ¬â¢ll do. After peeking into the patch file with your favorite editor, you can see what the actual changes are. - -Next, you're interested in how troublesome the patch is going to be. Git allows you to test the patch before you actually apply it. - -[source,bash] ----- -git apply --check ISIS-xxx.patch ----- - -If you don't get any errors, the patch has no conflicts. Otherwise you may see what trouble youââ¬â¢ll run into. - - -=== Apply a (clean) patch - -To apply a clean patch (adding the items and commit/signoff in a single step), use `git am`: - -[source,bash] ----- -git am --signoff < ISIS-xxx.patch ----- - -This preserves the original author's commit message. - -However, this can fail if the patch file does not contain the original committers email address. In this case you will need to abort the `am` session: - -[source,bash] ----- -git am abort ----- - -and continue on by applying a non-clean patch, as described next. - - - -=== Apply a (non-clean) patch - -If the patch does not apply cleanly, then the original authors commit message cannot be preserved. This sequence in this case is: - -[source,bash] ----- -git apply ISIS-xxx.patch ----- - -Fix up any issues. The add and commit as usual - -[source,bash] ----- -git add . -git commit -am "<original authors' commit message>" --signoff ----- - -The `--signoff` simply adds a line to the commit message indicating you have signed off the commit. - -Information adapted from https://ariejan.net/2009/10/26/how-to-create-and-apply-a-patch-with-git/[this blog post] and http://wiki.eclipse.org/Jetty/Contributor/Contributing_Patches[this wiki page]. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_applying-patches.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_applying-patches.adoc b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_applying-patches.adoc new file mode 100644 index 0000000..a605202 --- /dev/null +++ b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_applying-patches.adoc @@ -0,0 +1,90 @@ +[[_cgcom_applying-patches]] += Applying Patches +: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/ +:toc: right + + + +If a patch is received on a JIRA ticket, then it should be reviewed and applied. The commands are slightly different for diff files vs patch files. + + + + +== Diff files + +If a diff file has been provided, then it can easily be applied using eGit's wizards (Eclipse's Git integration)⦠+ +NOTE: FIXME - this stuff needs fleshing out ... + + + + +== Patch files + +If a patch file has been provided, then it can be applied using command line tools. + +=== Inspect the patch + +First, take a look at what changes are in the patch. You can do this easily with `git apply` + +[source,bash] +---- +git apply --stat ISIS-xxx.patch +---- + +Note that this command does not apply the patch, but only shows you the stats about what itââ¬â¢ll do. After peeking into the patch file with your favorite editor, you can see what the actual changes are. + +Next, you're interested in how troublesome the patch is going to be. Git allows you to test the patch before you actually apply it. + +[source,bash] +---- +git apply --check ISIS-xxx.patch +---- + +If you don't get any errors, the patch has no conflicts. Otherwise you may see what trouble youââ¬â¢ll run into. + + +=== Apply a (clean) patch + +To apply a clean patch (adding the items and commit/signoff in a single step), use `git am`: + +[source,bash] +---- +git am --signoff < ISIS-xxx.patch +---- + +This preserves the original author's commit message. + +However, this can fail if the patch file does not contain the original committers email address. In this case you will need to abort the `am` session: + +[source,bash] +---- +git am abort +---- + +and continue on by applying a non-clean patch, as described next. + + + +=== Apply a (non-clean) patch + +If the patch does not apply cleanly, then the original authors commit message cannot be preserved. This sequence in this case is: + +[source,bash] +---- +git apply ISIS-xxx.patch +---- + +Fix up any issues. The add and commit as usual + +[source,bash] +---- +git add . +git commit -am "<original authors' commit message>" --signoff +---- + +The `--signoff` simply adds a line to the commit message indicating you have signed off the commit. + +Information adapted from https://ariejan.net/2009/10/26/how-to-create-and-apply-a-patch-with-git/[this blog post] and http://wiki.eclipse.org/Jetty/Contributor/Contributing_Patches[this wiki page]. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_release-process-prereqs.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_release-process-prereqs.adoc b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_release-process-prereqs.adoc index d2c9491..e54d9de 100644 --- a/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_release-process-prereqs.adoc +++ b/adocs/documentation/src/main/asciidoc/guides/cgcom/_cgcom_release-process-prereqs.adoc @@ -14,7 +14,7 @@ This section (appendix) describes the prerequisites for the xref:../cgcom/cgcom. == Configure toolchains plugin Apache Isis releases are built using Java 7, enforced using the maven toolchains plugin. -Ensure that Java 7 is installed and the toolchains plugin is configured, as described in the xref:__dg_building-isis_configure-maven-toolchains-plugin[contributors' guide]. +Ensure that Java 7 is installed and the toolchains plugin is configured, as described in the xref:../dg/dg.adoc#__dg_building-isis_configure-maven-toolchains-plugin[contributors' guide]. http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/cgcom/cgcom.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/guides/cgcom/cgcom.adoc b/adocs/documentation/src/main/asciidoc/guides/cgcom/cgcom.adoc index d447116..3690a30 100644 --- a/adocs/documentation/src/main/asciidoc/guides/cgcom/cgcom.adoc +++ b/adocs/documentation/src/main/asciidoc/guides/cgcom/cgcom.adoc @@ -45,8 +45,8 @@ The remaining guides are: This guide provides guidance for Apache Isis' own committers. -// for some reason this doesn't seem to include:: correctly; that said, it's incomplete anyway -//include::_cgcom_applying-patches.adoc[leveloffset=+1] + +include::_cgcom_applying-patches.adoc[leveloffset=+1] include::_cgcom_merging-a-pull-request.adoc[leveloffset=+1] include::_cgcom_cutting-a-release.adoc[leveloffset=+1] http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc-syntax.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc-syntax.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc-syntax.adoc index 345a56a..9c4d74c 100644 --- a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc-syntax.adoc +++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_asciidoc-syntax.adoc @@ -237,9 +237,9 @@ link:http://ciserver:8080[CI Server^] |Link to an external hyperlink, with `target=blank` |.... -xref:_markup-docs_background[background] +xref:_markup-docs_background.adoc#[background] .... -|xref:_markup-docs_background[background] +|xref:_markup-docs_background.adoc#[background] |Cross-reference to section in same asciidoc document |.... http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_building-isis.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_building-isis.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_building-isis.adoc index 5f6335b..85ac50a 100644 --- a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_building-isis.adoc +++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_building-isis.adoc @@ -141,7 +141,7 @@ For further reading, see: Apache Isis is compatible with Java 7 and Java 8. For every-day use, the framework is usually compiled against Java 8. -Releases however are xref:_cgcom_cutting-a-release[cut] using Java 7, leveraging the link:http://maven.apache.org/plugins/maven-toolchains-plugin/[Maven toolchains plugin]). +Releases however are xref:../cgcom/cgcom.adoc#_cgcom_cutting-a-release[cut] using Java 7, leveraging the link:http://maven.apache.org/plugins/maven-toolchains-plugin/[Maven toolchains plugin]). Therefore install either/both of Java 7 JDK and Java 8 JDK. Note that the JRE is _not_ sufficient. http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_intellij.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_intellij.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_intellij.adoc index c458e0f..19bf9a7 100644 --- a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_intellij.adoc +++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_ide_intellij.adoc @@ -181,7 +181,7 @@ On the *Annotation Processors* page, enable and adjust for the 'default' setting image::{_imagesdir}intellij-idea/040-other-settings-compiler/020-annotation-processor.png[width="700px"] This setting enables the generation of the `Q*` classes for DataNucleus type-safe queries, as well as being required -for frameworks such as xref:_cg_ide_project-lombok[Project Lombok]. +for frameworks such as xref:../cgcom/cgcom.adoc#_cgcom_ide_project-lombok[Project Lombok]. [NOTE] ==== @@ -483,7 +483,7 @@ If you hit an error of "duplicate classes": image::{_imagesdir}intellij-idea/060-troubleshooting/010-duplicate-classes.png[width="600px",link="{_imagesdir}intellij-idea/060-troubleshooting/010-duplicate-classes.png"] -then make sure you have correctly configured the xref:_cg_ide_intellij_other-settings-compiler[annotation processor] +then make sure you have correctly configured the xref:../dg/dg.adoc#_dg_ide_intellij_other-settings-compiler[annotation processor] settings. Pay attention in particular to the "Production sources directory" and "Test sources directory", that these are set up correctly. http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_project-lombok.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_project-lombok.adoc b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_project-lombok.adoc index e3d7c4f..d8e86fe 100644 --- a/adocs/documentation/src/main/asciidoc/guides/dg/_dg_project-lombok.adoc +++ b/adocs/documentation/src/main/asciidoc/guides/dg/_dg_project-lombok.adoc @@ -31,7 +31,7 @@ private String name; ---- Under the covers it is implemented as an annotation processor; it basically hooks into the Java compiler -so that it can emit additional bytecode (eg for the getter and setter). See xref:_cg_ide_intellij_other-settings-compiler[here] for details of setting up in IntelliJ (Eclipse has very similar support). +so that it can emit additional bytecode (eg for the getter and setter). See xref:../dg/dg.adoc#_dg_ide_intellij_other-settings-compiler[here] for details of setting up in IntelliJ (Eclipse has very similar support). Apache Isis supports link:https://projectlombok.org/[Project Lombok], in that the annotations that would normally be placed on the getter (namely xref:../rgant/rgant.adoc#_rgant-Property[`Property`], xref:../rgant/rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`], xref:../rgant/rgant.adoc#_rgant-Collection[`@Collection`], xref:../rgant/rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`] and xref:../rgant/rgant.adoc#_rgant-MemberOrder[`@MemberOrder`]) can be placed on the field instead. http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes.adoc index 9aa0866..a5b318e 100644 --- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes.adoc +++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes.adoc @@ -5,7 +5,7 @@ :_imagesdir: images/ -This chapter describes the usage of various classes and interfaces that are not otherwise associated with xref:../rgsvc/rgsvc.adoc[domain services], xref:../ugvw/ugvw.adoc#_ugvw_layout[object layout] or xref:../rgcfg/rgcfg.adoc#_rgcfg[configuration]. +This chapter describes the usage of various classes and interfaces that are not otherwise associated with xref:../rgsvc/rgsvc.adoc#[domain services], xref:../ugvw/ugvw.adoc#_ugvw_layout[object layout] or xref:../rgcfg/rgcfg.adoc#_rgcfg[configuration]. include::_rgcms_classes_AppManifest-bootstrapping.adoc[leveloffset=+1] http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_layout.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_layout.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_layout.adoc index 6f860f8..f215ef5 100644 --- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_layout.adoc +++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_layout.adoc @@ -12,7 +12,7 @@ The `org.apache.isis.applib.layout` package defines a number of classes that all * common component classes, that capture the layout metadata for an object's properties, collections and actions. These are bound (or associated) to the regions of the grid -The framework provides an implementation of the grid classes modelled closely on link:http://getbootstrap.com[Bootstrap 3], along with xref:../ugvw/ugvw.adoc[Wicket viewer] components capable of rendering that grid system. In principle it is +The framework provides an implementation of the grid classes modelled closely on link:http://getbootstrap.com[Bootstrap 3], along with xref:../ugvw/ugvw.adoc#[Wicket viewer] components capable of rendering that grid system. In principle it is also possible to extend the layout architecture for other grid systems. The component classes, though, are intended to be reusable across all grid systems. The component classes, meanwhile, are broadly equivalent to the "layout" annotations (xref:../rgant/rgant.adoc#_rgant-PropertyLayout[`@PropertyLayout`], xref:../rgant/rgant.adoc#_rgant-CollectionLayout[`@CollectionLayout`], xref:../rgant/rgant.adoc#_rgant-ActionLayout[`@ActionLayout`] and xref:../rgant/rgant.adoc#_rgant-DomainObjectLayout[`@DomainObjectLayout`] http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_mixins_Object.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_mixins_Object.adoc b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_mixins_Object.adoc index db37617..77d5401 100644 --- a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_mixins_Object.adoc +++ b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_classes_mixins_Object.adoc @@ -14,7 +14,7 @@ The framework provides a single mixin that contributes to simply `java.lang.Obje When a domain object is rendered the end-user can select different tabs, and for collections can sort the columns, navigate to second pages, or select different views of collections. If the user revisits that object, the -xref:../ugvw/ugvw.adoc[Wicket viewer] will remember these hints and render the domain object in the same state. These +xref:../ugvw/ugvw.adoc#[Wicket viewer] will remember these hints and render the domain object in the same state. These rendering hints are also included if the user copies the URL using the anchor link (to right hand of the object's title). http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_MessageBrokerServiceInternal.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_MessageBrokerServiceInternal.adoc b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_MessageBrokerServiceInternal.adoc index 88b89cc..2632371 100644 --- a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_MessageBrokerServiceInternal.adoc +++ b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_MessageBrokerServiceInternal.adoc @@ -39,6 +39,6 @@ The framework provides two implementations: * `MessageBrokerServiceInternalDefault` is provided by `isis-core-runtime`, and is used during normal use and integration tests -* `MessageBrokerServiceInternalNoop` is provided as a fallback by `isis-core-metamodel`, and is provided to allow the xref:../rgmvn/rgmvn.adoc[maven plugin] to be bootstrapped without any "backend" database. +* `MessageBrokerServiceInternalNoop` is provided as a fallback by `isis-core-metamodel`, and is provided to allow the xref:../rgmvn/rgmvn.adoc#[maven plugin] to be bootstrapped without any "backend" database. The `...Default` implementation takes priority over the `...Noop` implementation. http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_PersistenceSessionServiceInternal.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_PersistenceSessionServiceInternal.adoc b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_PersistenceSessionServiceInternal.adoc index a7aee62..2427682 100644 --- a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_PersistenceSessionServiceInternal.adoc +++ b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_PersistenceSessionServiceInternal.adoc @@ -91,6 +91,6 @@ The framework provides two implementations: * `PersistenceSessionServiceInternalDefault` is provided by `isis-core-runtime`, and is used during normal use and integration tests -* `PersistenceSessionServiceInternalNoop` is provided as a fallback by `isis-core-metamodel`, and is provided to allow the xref:../rgmvn/rgmvn.adoc[maven plugin] to be bootstrapped without any "backend" database. +* `PersistenceSessionServiceInternalNoop` is provided as a fallback by `isis-core-metamodel`, and is provided to allow the xref:../rgmvn/rgmvn.adoc#[maven plugin] to be bootstrapped without any "backend" database. The `...Default` implementation takes priority over the `...Noop` implementation. http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_TransactionStateProviderInternal.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_TransactionStateProviderInternal.adoc b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_TransactionStateProviderInternal.adoc index 655f8d0..c866f60 100644 --- a/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_TransactionStateProviderInternal.adoc +++ b/adocs/documentation/src/main/asciidoc/guides/rgfis/_rgfis_spi_TransactionStateProviderInternal.adoc @@ -33,6 +33,6 @@ The framework provides two implementations: * `TransactionStateProviderInternalDefault` is provided by `isis-core-runtime`, and is used during normal use and integration tests -* `TransactionStateProviderInternalNoop` is provided as a fallback by `isis-core-metamodel`, and is provided to allow the xref:../rgmvn/rgmvn.adoc[maven plugin] to be bootstrapped without any "backend" database. +* `TransactionStateProviderInternalNoop` is provided as a fallback by `isis-core-metamodel`, and is provided to allow the xref:../rgmvn/rgmvn.adoc#[maven plugin] to be bootstrapped without any "backend" database. The `...Default` implementation takes priority over the `...Noop` implementation. http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_LayoutService.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_LayoutService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_LayoutService.adoc index 785354c..91f3890 100644 --- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_LayoutService.adoc +++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_LayoutService.adoc @@ -7,7 +7,7 @@ The `LayoutService` provides the ability to obtain the XML layout for a single domain object or for all domain -objects. This functionality is surfaced through the user interface through a related xref:__rgsvc_api_LayoutService_related-mixins-and-menus[mixin and menu action]. +objects. This functionality is surfaced through the user interface through a related xref:../rgsvc/rgsvc.adoc#__rgsvc_api_LayoutService_related-mixins-and-menus[mixin and menu action]. http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_SwaggerService.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_SwaggerService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_SwaggerService.adoc index 03109c9..3bc5d7b 100644 --- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_SwaggerService.adoc +++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_api_SwaggerService.adoc @@ -64,6 +64,6 @@ implementation of `SwaggerService` service is automatically registered and injec A `SwaggerServiceMenu` domain service provides a prototype action that enables the swagger spec to be downloaded from the Wicket viewer's UI. -Apache Isis' xref:rgmvn.aod[Maven plugin] also provides a xref:../rgmvn/rgmvn.adoc#_rgmvn_swagger[swagger goal] which allows the spec file(s) to be generated at build time. this then allows client-side stubs can then be generated in turn as part of a build pipeline. +Apache Isis' xref:../rgmvn/rgmvn.adoc#[Maven plugin] also provides a xref:../rgmvn/rgmvn.adoc#_rgmvn_swagger[swagger goal] which allows the spec file(s) to be generated at build time. this then allows client-side stubs can then be generated in turn as part of a build pipeline. http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_metadata-api.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_metadata-api.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_metadata-api.adoc index 4c565f4..0ec8336 100644 --- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_metadata-api.adoc +++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_metadata-api.adoc @@ -74,7 +74,7 @@ within the metamodel. |`SwaggerServiceDefault` + ``o.a.i.core`` + ``isis-core-metamodel`` -|A `SwaggerServiceMenu` domain service is also provided which enables the swagger spec to be downloaded. Apache Isis' xref:../rgmvn/rgmvn.adoc[Maven plugin] also provides a xref:../rgmvn/rgmvn.adoc#_rgmvn_swagger[swagger goal] which allows the spec file(s) to be generated at build time (eg so that client-side stubs can then be generated in turn). +|A `SwaggerServiceMenu` domain service is also provided which enables the swagger spec to be downloaded. Apache Isis' xref:../rgmvn/rgmvn.adoc#[Maven plugin] also provides a xref:../rgmvn/rgmvn.adoc#_rgmvn_swagger[swagger goal] which allows the spec file(s) to be generated at build time (eg so that client-side stubs can then be generated in turn). http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_ContentMappingService.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_ContentMappingService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_ContentMappingService.adoc index b06c46b..416666a 100644 --- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_ContentMappingService.adoc +++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_ContentMappingService.adoc @@ -42,7 +42,7 @@ public interface ContentMappingService { In versions prior to `v1.12.0`, this interface resided in a different package, internal to the -xref:../ugvro/ugvro.adoc[Restful Objects] viewer, and defined a slightly different signature that used an internal enum: +xref:../ugvro/ugvro.adoc#[Restful Objects] viewer, and defined a slightly different signature that used an internal enum: [source,java] ---- http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_GridSystemService.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_GridSystemService.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_GridSystemService.adoc index 523bea6..ac28e20 100644 --- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_GridSystemService.adoc +++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_GridSystemService.adoc @@ -54,8 +54,8 @@ the service with the lowest xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_ == Implementation -The framework provides `GridSystemServiceBS3`, an implementation that encodes the bootstrap3 grid system. (The framework -also provides xref:../ugvw/ugvw.adoc[Wicket viewer] components that are capable of interpreting and rendering this metadata). +The framework provides `GridSystemServiceBS3`, an implementation that encodes the bootstrap3 grid system. +(The framework also provides xref:../ugvw/ugvw.adoc#[Wicket viewer] components that are capable of interpreting and rendering this metadata). == Registering the Services http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_HintStore.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_HintStore.adoc b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_HintStore.adoc index 6d172d2..33f3e70 100644 --- a/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_HintStore.adoc +++ b/adocs/documentation/src/main/asciidoc/guides/rgsvc/_rgsvc_spi_HintStore.adoc @@ -59,6 +59,6 @@ in the xref:../rgsvc/rgsvc.adoc#__rgsvc_intro_overriding-the-services[introducti == Related Services -The xref:../ugvw/ugvw.adoc[Wicket viewer] exposes the xref:../rgcms/rgcms.adoc#__rgcms_classes_mixins_Object_clearHints["clear hints"] +The xref:../ugvw/ugvw.adoc#[Wicket viewer] exposes the xref:../rgcms/rgcms.adoc#__rgcms_classes_mixins_Object_clearHints["clear hints"] mixin action that is for use by end-users of the application to clear any UI hints that have accumulated for a domain object. http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_replacing-default-service-implementations.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_replacing-default-service-implementations.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_replacing-default-service-implementations.adoc index e3d29af..c4abd5d 100644 --- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_replacing-default-service-implementations.adoc +++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_other-techniques_replacing-default-service-implementations.adoc @@ -6,7 +6,7 @@ -The framework provides default implementations for many of the xref:../rgsvc/rgsvc.adoc[domain services]. This is convenient, but sometimes you will want to replace the default implementation with your own service implementation. +The framework provides default implementations for many of the xref:../rgsvc/rgsvc.adoc#[domain services]. This is convenient, but sometimes you will want to replace the default implementation with your own service implementation. The trick is to use the xref:../rgant/rgant.adoc#_rgant-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] attribute, specifying a low number (typically `"1"`). http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_programming-model_custom-validator.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_programming-model_custom-validator.adoc b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_programming-model_custom-validator.adoc index 3001a4a..732c0b9 100644 --- a/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_programming-model_custom-validator.adoc +++ b/adocs/documentation/src/main/asciidoc/guides/ugbtb/_ugbtb_programming-model_custom-validator.adoc @@ -17,7 +17,7 @@ You can also impose your own application-specific rules by installing your own m [TIP] ==== -Isis' xref:../rgmvn/rgmvn.adoc[Maven plugin] will also validate the domain object model during build time. +Isis' xref:../rgmvn/rgmvn.adoc#[Maven plugin] will also validate the domain object model during build time. ==== http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_types-of-domain-objects_view-models.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_types-of-domain-objects_view-models.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_types-of-domain-objects_view-models.adoc index bc08274..07c8b50 100644 --- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_types-of-domain-objects_view-models.adoc +++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_building-blocks_types-of-domain-objects_view-models.adoc @@ -132,31 +132,9 @@ In fact (as the xref:../ugbtb/ugbtb.adoc#_ugbtb_view-models_programming-model[pr It's also worth noting that it is also possible to download the XML (or XSD) straight from the UI, useful during development. The view model simply needs to implement the xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins_Dto[`Dto`] marker interface; the framework has xref:../rgcms/rgcms.adoc#_rgcms_classes_mixins_Dto[mixins] that contribute the download actions to the view model. - -[[__ugfun_building-blocks_view-models_dtos_consumers]] -=== DTO Consumers - -The actual consumers of DTOs will generally obtain the XML of the view models either by requesting the XML directly, eg using the xref:../ugvro/ugvro.adoc#[RestfulObjects viewer], or may have the XML sent to them asynchronously using an ESB such as Apache Camel. - -In the former case, the consumer requests the DTO by calling the REST API with the appropriate HTTP `Accept` header. -An appropriate implementation of xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_ContentMappingService[`ContentMappingService`] can then be used to return the appropriate DTO (as XML). - -For the latter case, one design is simply for the application to instantiate the view model, then call the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_JaxbService[`JaxbService`] to obtain its corresponding XML. This can then be published onto the ESB, for example using an http://activemq.apache.org[Apache ActiveMQ (TM)] queue. - -However, rather than try to push all the data that might be needed by any of these external systems in a single XML event (which would require anticipating all the requirements, likely a hopeless task), a better design is to publish only the fact that something of note has changed - ie, that an action on a domain object has been invoked - and then let the consumers call back to obtain other information if required. -This can once again be done by calling the REST API with an appropriate HTTP `Accept` header. - [TIP] ==== -This is an example of the link:https://leanpub.com/camel-design-patterns[VETRO pattern] (validate, enrich, transform, route, operate). -In our case we focus on the validation (to determine the nature of the inbound message, ie which action was invoked), and the enrich (callback to obtain a DTO with additional information required by the consumer). +Details of how to consume such DTOs can be found xref:../ugfun/ugfun.adoc#_ugfun_programming-model_view-models_jaxb_dto-consumers[here]. ==== -The (non-ASF) http://github.com/isisaddons/isis-module-publishmq[Isis addons' publishmq] module provides an out-of-the-box solution of this design. -It provides an implementation of the xref:../rgsvc/rgsvc.adoc#_rgsvc_spi_PublishingService[`PublishingService`], but which simply publishes instances of xref:../rgcms/rgcms.adoc#_rgcms_schema-aim[`ActionInvocationMemento`] to an ActiveMQ queue. -Camel (or similar) can then be hooked up to consume these events from this queue, and use a processor to parse the action memento to determine what has changed on the source system. -Thereafter, a subsequent Camel processor can then call back to the source - via the xref:../ugvro/ugvro.adoc[Restful Objects viewer] - to enrich the message with additional details using a DTO. - - - http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model.adoc index 98fcff1..f61440d 100644 --- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model.adoc +++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model.adoc @@ -73,10 +73,6 @@ include::_ugfun_programming-model_domain-entities.adoc[leveloffset=+1] include::_ugfun_programming-model_domain-services.adoc[leveloffset=+1] -include::_ugfun_programming-model_view-models.adoc[leveloffset=+1] - -include::_ugfun_programming-model_mixins.adoc[leveloffset=+1] - include::_ugfun_programming-model_properties.adoc[leveloffset=+1] include::_ugfun_programming-model_collections.adoc[leveloffset=+1] include::_ugfun_programming-model_actions.adoc[leveloffset=+1] @@ -85,6 +81,10 @@ include::_ugfun_programming-model_inject-services.adoc[leveloffset=+1] include::_ugfun_programming-model_properties-vs-parameters.adoc[leveloffset=+1] +include::_ugfun_programming-model_view-models.adoc[leveloffset=+1] + +include::_ugfun_programming-model_mixins.adoc[leveloffset=+1] + http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_collections.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_collections.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_collections.adoc index 8a7aafe..62d5c20 100644 --- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_collections.adoc +++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_collections.adoc @@ -25,7 +25,7 @@ This and other annotations can be used to specify if the association is bidirect Apache Isis recognises some of these annotations for JDO/DataNucleus and JAXB and infers some domain semantics from them (for example, the maximum allowable length of a string property). -Unlike xref:../ugfun/ugfun.adoc#_ugfun_programming-model_properties[properties], the framework (at least, the xref:../ugvw/ugvw.adoc[Wicket viewer]) does not allow collections to be "edited". +Unlike xref:../ugfun/ugfun.adoc#_ugfun_programming-model_properties[properties], the framework (at least, the xref:../ugvw/ugvw.adoc#[Wicket viewer]) does not allow collections to be "edited". Instead, xref:../ugfun/ugfun.adoc#_ugfun_programming-model_actions[action]s can be written that will modify the contents of the collection as a side-effect. For example, a `placeOrder(...)` action will likely add an `Order` to the `Customer#orders` collection. http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services.adoc index 4a322f3..cee3ce2 100644 --- a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services.adoc +++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services.adoc @@ -7,356 +7,13 @@ This section looks at the programming model for writing your own domain services. - -[[__ugfun_building-blocks_domain-services_organizing-services]] -== Organizing Services - -In larger applications we have found it worthwhile to ensure that our domain services only act aligned with these responsibilities, employing a naming convention so that it is clear what the responsibilities of each domain service is. - -The application provides the `@DomainService(nature=...)` annotation that helps distinguish some of these responsibilities: - -* `VIEW_MENU_ONLY` indicates that the actions should appear on the menu of the xref:../ugvw/ugvw.adoc#[Wicket viewer], and as top-level actions for the REST API provided by the xref:../ugvro/ugvro.adoc#[Restful Objects viewer] - -* `DOMAIN` indicates that the actions are for other domain objects to invoke (either directly or indirectly through the event bus), but in any case should not be rendered at all in the UI - -* `VIEW_REST_ONLY` indicates that the actions should appear in the REST API provided by the xref:../ugvro/ugvro.adoc#[Restful Objects viewer], but not rendered by the xref:../ugvw/ugvw.adoc#[Wicket viewer]. - -There are also two other natures that should be considered "deprecated": - -* `VIEW_CONTRIBUTIONS_ONLY` which indicates that the actions should be contributed as actions to its action parameters. + -+ -This feature is deprecated because xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_types-of-domain-objects_mixins[mixins] are equivalent in functionality with a simpler programming model. - -* `VIEW` combines both `VIEW_MENU_ONLY` and the deprecated `VIEW_CONTRIBUTIONS_ONLY`. - -If the domain service nature is not specified (or is left to its default, `VIEW`), then the service's actions will appear in the UI. - -While for long-term maintainability we do recommend the naming conventions described xref:../ugfun/ugfun.adoc#__ugfun_building-blocks_domain-services_organizing-services[above], you can get away with far fewer services when just prototyping a domain. -Later on it is easy enough to refactor the code to tease apart the different responsibilities. - -Pulling all the above together, here are our suggestions as to how you should organize your domain services. - - -[[__ugfun_programming-model_domain-services_menu]] -== Menu - -The following is a typical menu service: - -[source,java] ----- -@DomainService( // <1> - nature = NatureOfService.VIEW_MENU_ONLY -) -@DomainServiceLayout( // <2> - named = "Simple Objects", - menuOrder = "10" -) -public class SimpleObjectMenu { - - ... - - @Action(semantics = SemanticsOf.SAFE) - @ActionLayout(bookmarking = BookmarkPolicy.AS_ROOT) - @MemberOrder(sequence = "2") - public List<SimpleObject> findByName( // <3> - @ParameterLayout(named="Name") - final String name - ) { - return simpleObjectRepository.findByName(name); - } - - @javax.inject.Inject - SimpleObjectRepository simpleObjectRepository; // <4> -} ----- - - - -[[__ugfun_programming-model_domain-services_factory-and-repository]] -== Factory and Repository - -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: - - -[source,java] ----- -@DomainService( - nature=NatureOfService.DOMAIN // <1> -) -public CustomerRepository { - public List<Customer> findCustomerBy...(...) { - return repositoyService.allMatches(...); - } - public Customer newCustomer(...) { - Customer Customer = container.newTransientInstance(Customer.class); - ... - persistIfNotAlready(Customer); - return Customer; - } - public List<Customer> allCustomers() { - return repositoryService.allInstances(Customer.class); - } - @Inject - RepositoryService repositoryService; -} ----- -<1> interacted with only programmatically by other objects in the domain layer. - -There is no need to annotate the actions; they are implicitly hidden because of the domain service's nature. - - -[[__ugfun_building-blocks_domain-services_menu]] -== Menu - -Menu services provide actions to be rendered on the menu. - -For the Wicket viewer, each service's actions appear as a collection of menu items of a named menu, and this menu is on one of the three menu bars provided by the Wicket viewer. It is possible for more than one menu service's actions to appear on the same menu; a separator is shown between each. - -For the Restful Objects viewer, all menu services are shown in the services representation. - -We suggest naming such classes `XxxMenu`, eg: - - -[source,java] ----- -@DomainService( // <1> - nature = NatureOfService.VIEW_MENU_ONLY -) -@DomainServiceLayout( // <2> - named = "Customers", - menuBar = DomainServiceLayout.MenuBar.PRIMARY, - menuOrder = "10" -) -public class CustomerMenu { - - @Action( - semantics = SemanticsOf.SAFE - ) - @ActionLayout(bookmarking = BookmarkPolicy.AS_ROOT) - @MemberOrder( sequence = "1" ) - public List<Customer> findByName( // <3> - @ParameterLayout(named="Name") - final String name - ) { - return customerRepository.findByName(name); // <4> - } - - @Action( - semantics = SemanticsOf.NON_IDEMPOTENT - ) - @MemberOrder( sequence = "3" ) - public Customer newCustomer(...) { - return customerRepository.newCustomer(...); - } - - @Action( - semantics = SemanticsOf.SAFE, - restrictTo = RestrictTo.PROTOTYPING // <5> - ) - @MemberOrder( sequence = "99" ) - public List<Customer> listAll() { - return customerRepository.listAll(); - } - - @Inject - protected CustomerRepository customerRepository; // <4> -} ----- -<1> The (Apache Isis) xref:../rgant/rgant.adoc#_rgant_DomainService[`@DomainService`] annotation is used to identify the class as a domain service. -Apache Isis scans the classpath looking for classes with this annotation, so there very little configuration other than to tell the framework which packages to scan underneath. -The `VIEW_MENU_ONLY` nature indicates that this service's actions should be exposed as menu items. -<3> The xref:../rgant/rgant.adoc#_rgant_DomainServiceLayout[`@DomainServiceLayout`] annotation provides UI hints. -The menu is named "Customers" (otherwise it would have defaulted to "Customer Menu", based on the class name, while the xref:../rgant/rgant.adoc#_rgant_DomainServiceLayout_menuOrder[`menuOrder`] attribute determines the order of the menu with respect to other menu services. -<3> The `findByName` method is annotated with various Apache Isis annotations (xref:../rgant/rgant.adoc#_rgant_Action[`@Action`], xref:../rgant/rgant.adoc#_rgant_ActionLayout[`@ActionLayout`] and xref:../rgant/rgant.adoc#_rgant_MemberOrder[`@MemberOrder`] and is itself rendered in the UI as a "Find By Name" menu item underneath the "Simple Objects" menu. -<4> the action implementation delegates to an injected repository. -The framework can inject into not just other domain services but will also automatically into domain entities and view models. -There is further discussion of service injection xref:../ugfun/ugfun.adoc#_ugfun_programming-model_inject-services[below]. -<4> xref:../rgant/rgant.adoc#_rgant_Action_restrictTo[Prototype] actions are rendered only in prototyping mode. -A "list all" action such as this can be useful when exploring the domain with a small dataset. - -Not every action on the repository need to be delegated to of course (the above example does but only because it is very simple). - -[TIP] -==== -While there's nothing to stop `VIEW_MENU` domain services being injected into other domain objects and interacted with programmatically, we recommend against it. -Instead, inject the underlying repository. -If there is additional business logic, then consider introducing a further `DOMAIN`-scoped service and call that instead. -==== - - - - -[[__ugfun_building-blocks_domain-services_event-subscribers]] -== Event Subscribers - -Domain services acting as event subscribers can subscribe to xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_events_domain-events[domain], xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_events_ui-events[UI] and xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_events_lifecycle-events[lifecycle] events, influencing the rendering and behaviour of other objects. - -All subscribers must subscribe to the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`]; as this amounts to a few lines of boilerplate it's easiest to inherit from the convenience `AbstractSubscriber` class. - -We suggest naming such classes `XxxSubscriptions`, for example: - -[source,java] ----- -@DomainService( - nature=NatureOfService.DOMAIN // <1> -) -@DomainServiceLayout( - menuOrder="10", - name="...", -} -public class CustomerOrderSubscriptions - extends AbstractSubscriber { // <2> - - @org.axonframework.eventhandling.annotation.EventHandler // <3> - @com.google.common.eventbus.Subscribe // <3> - public void on(final Customer.DeletedEvent ev) { // <4> - Customer customer = ev.getSource(); - orderRepository.delete(customer); - } - - @Inject - OrderRepository orderRepository; -} ----- -<1> subscriptions do not appear in the UI at all, so should use the domain nature of service -<2> subclass from the `AbstractSubscriber` convenience superclass -<3> The framework supports two different implementations for the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] - Axon framework and Guava. -Subscribers should use the appropriate annotation type depending on the implementation chosen (or as shown here, use both annotations). -<4> the parameter type of the method corresponds to the event emitted on the event bus. -The actual method name does not matter (though it must have `public` visibility). - - -[[__ugfun_building-blocks_domain-services_contributions]] -== Contributions (deprecated) - -Services can contribute either actions, properties or collections, based on the type of their parameters. - -[WARNING] -==== -Contributed services should be considered a deprecated feature. -Instead, contribute the behaviour using xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_mixins[mixins]. -==== - -We suggest naming such classes `XxxContributions`, eg: - -[source,java] ----- -@DomainService( - nature=NatureOfService.VIEW_CONTRIBUTIONS_ONLY // <1> -) -@DomainServiceLayout( - menuOrder="10", - name="...", -} -public class OrderContributions { - @Action(semantics=SemanticsOf.SAFE) - @ActionLayout(contributed=Contributed.AS_ASSOCIATION) // <2> - @CollectionLayout(render=RenderType.EAGERLY) - public List<Order> orders(Customer customer) { // <3> - return container.allMatches(...); - } - - @Inject - CustomerRepository customerRepository; -} ----- -<1> the service's actions should be contributed to the entities of the parameters of those actions -<2> contributed as an association, in particular as a collection because returns a `List<T>`. -<3> Only actions with a single argument can be contributed as associations - -More information about contributions can be found xref:../ugfun/ugfun.adoc#_ugfun_how-tos_contributed-members[here]. More information -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]. - - - - - -[[__ugfun_building-blocks_domain-services_scoped-services]] -== Scoped services - -By default all domain services are considered to be singletons, and thread-safe. - -Sometimes though a service's lifetime is applicable only to a single request; in other words it is request-scoped. - -The CDI annotation xref:../rgant/rgant.adoc#_rgant-RequestScoped[`@javax.enterprise.context.RequestScoped`] is used to indicate this fact: - -[source,java] ----- -@javax.enterprise.context.RequestScoped -public class MyService extends AbstractService { - ... -} ----- - -The framework provides a number of request-scoped services, include a xref:../rgsvc/rgsvc.adoc#_rgsvc_api_Scratchpad[`Scratchpad`] service query results caching through the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_QueryResultsCache[`QueryResultsCache`], and support for co-ordinating bulk actions through the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_ActionInvocationContext[`ActionInvocationContext`] service. See the xref:../rgsvc/rgsvc.adoc[domain services] reference guide for further details. - - - - -[[__ugfun_building-blocks_domain-services_registering]] -== Registering - -The easiest way to register domain services with the framework is to use an xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`]. -This specifies the modules which contain xref:../rgant/rgant.adoc#_rgant-DomainService[`@DomainService`]-annotated classes. - -For example: - -[source,ini] ----- -public class MyAppManifest implements AppManifest { - public List<Class<?>> getModules() { - return Arrays.asList( - ToDoAppDomainModule.class, - ToDoAppFixtureModule.class, - ToDoAppAppModule.class, - org.isisaddons.module.audit.AuditModule.class); - } - ... -} ----- - -will load all services in the packages underneath the four modules listed. - -An alternative (older) mechanism is to registered domain services in the `isis.properties` configuration file, under `isis.services` key (a comma-separated list); for example: - -[source,ini] ----- -isis.services = com.mycompany.myapp.employee.Employees\, - com.mycompany.myapp.claim.Claims\, - ... ----- - -This will then result in the framework instantiating a single instance of each of the services listed. - -If all services reside under a common package, then the `isis.services.prefix` can specify this prefix: - -[source,ini] ----- -isis.services.prefix = com.mycompany.myapp -isis.services = employee.Employees,\ - claim.Claims,\ - ... ----- - -This is quite rare, however; you will often want to use default implementations of domain services that are provided by the framework and so will not reside under this prefix. - -Examples of framework-provided services (as defined in the applib) include clock, auditing, publishing, exception handling, view model support, snapshots/mementos, and user/application settings management; see the xref:../rgsvc/rgsvc.adoc[domain services] reference guide for further details. - - - -[[__ugfun_building-blocks_domain-services_initialization]] -== Initialization - -Services can optionally declare lifecycle callbacks to initialize them (when the app is deployed) and to shut them down (when the app is undeployed). - -An Apache Isis session _is_ available when initialization occurs (so services can interact with the object store, for example). - -The framework will call any `public` method annotated with xref:../rgant/rgant.adoc#_rgant-PostConstruct[`@PostConstruct`] with either no arguments of an argument of type `Map<String,String>`. -In the latter case, the framework passes in the configuration (`isis.properties` and any other component-specific configuration files). - -Shutdown is similar; the framework will call any method annotated with xref:../rgant/rgant.adoc#_rgant-PreDestroy[`@PreDestroy`]. - +include::_ugfun_programming-model_domain-services_organizing-services.adoc[leveloffset=+1] +include::_ugfun_programming-model_domain-services_repository-and-factory.adoc[leveloffset=+1] +include::_ugfun_programming-model_domain-services_menu.adoc[leveloffset=+1] +include::_ugfun_programming-model_domain-services_event-subscribers.adoc[leveloffset=+1] +include::_ugfun_programming-model_domain-services_contributions.adoc[leveloffset=+1] +include::_ugfun_programming-model_domain-services_scoped-services.adoc[leveloffset=+1] +include::_ugfun_programming-model_domain-services_registering.adoc[leveloffset=+1] +include::_ugfun_programming-model_domain-services_initialization.adoc[leveloffset=+1] http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_contributions.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_contributions.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_contributions.adoc new file mode 100644 index 0000000..107a550 --- /dev/null +++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_contributions.adoc @@ -0,0 +1,48 @@ +[[_ugfun_programming-model_domain-services_contributions]] += Contributions (deprecated) +: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/ + + + +Services can contribute either actions, properties or collections, based on the type of their parameters. + +[WARNING] +==== +Contributed services should be considered a deprecated feature. +Instead, contribute the behaviour using xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_mixins[mixins]. +==== + +We suggest naming such classes `XxxContributions`, eg: + +[source,java] +---- +@DomainService( + nature=NatureOfService.VIEW_CONTRIBUTIONS_ONLY // <1> +) +@DomainServiceLayout( + menuOrder="10", + name="...", +} +public class OrderContributions { + @Action(semantics=SemanticsOf.SAFE) + @ActionLayout(contributed=Contributed.AS_ASSOCIATION) // <2> + @CollectionLayout(render=RenderType.EAGERLY) + public List<Order> orders(Customer customer) { // <3> + return container.allMatches(...); + } + + @Inject + CustomerRepository customerRepository; +} +---- +<1> the service's actions should be contributed to the entities of the parameters of those actions +<2> contributed as an association, in particular as a collection because returns a `List<T>`. +<3> Only actions with a single argument can be contributed as associations + +More information about contributions can be found xref:../ugfun/ugfun.adoc#_ugfun_how-tos_contributed-members[here]. More information +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]. + + + http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_event-subscribers.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_event-subscribers.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_event-subscribers.adoc new file mode 100644 index 0000000..77c5040 --- /dev/null +++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_event-subscribers.adoc @@ -0,0 +1,46 @@ +[[_ugfun_programming-model_domain-services_event-subscribers]] += Event Subscribers +: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/ + + + + +Domain services acting as event subscribers can subscribe to xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_events_domain-events[domain], xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_events_ui-events[UI] and xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_events_lifecycle-events[lifecycle] events, influencing the rendering and behaviour of other objects. + +All subscribers must subscribe to the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`]; as this amounts to a few lines of boilerplate it's easiest to inherit from the convenience `AbstractSubscriber` class. + +We suggest naming such classes `XxxSubscriptions`, for example: + +[source,java] +---- +@DomainService( + nature=NatureOfService.DOMAIN // <1> +) +@DomainServiceLayout( + menuOrder="10", + name="...", +} +public class CustomerOrderSubscriptions + extends AbstractSubscriber { // <2> + + @org.axonframework.eventhandling.annotation.EventHandler // <3> + @com.google.common.eventbus.Subscribe // <3> + public void on(final Customer.DeletedEvent ev) { // <4> + Customer customer = ev.getSource(); + orderRepository.delete(customer); + } + + @Inject + OrderRepository orderRepository; +} +---- +<1> subscriptions do not appear in the UI at all, so should use the domain nature of service +<2> subclass from the `AbstractSubscriber` convenience superclass +<3> The framework supports two different implementations for the xref:../rgsvc/rgsvc.adoc#_rgsvc_api_EventBusService[`EventBusService`] - Axon framework and Guava. +Subscribers should use the appropriate annotation type depending on the implementation chosen (or as shown here, use both annotations). +<4> the parameter type of the method corresponds to the event emitted on the event bus. +The actual method name does not matter (though it must have `public` visibility). + + http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_initialization.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_initialization.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_initialization.adoc new file mode 100644 index 0000000..32544da --- /dev/null +++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_initialization.adoc @@ -0,0 +1,19 @@ +[[_ugfun_programming-model_domain-services_initialization]] += Initialization +: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/ + + + +Services can optionally declare lifecycle callbacks to initialize them (when the app is deployed) and to shut them down (when the app is undeployed). + +An Apache Isis session _is_ available when initialization occurs (so services can interact with the object store, for example). + +The framework will call any `public` method annotated with xref:../rgant/rgant.adoc#_rgant-PostConstruct[`@PostConstruct`] with either no arguments of an argument of type `Map<String,String>`. +In the latter case, the framework passes in the configuration (`isis.properties` and any other component-specific configuration files). + +Shutdown is similar; the framework will call any method annotated with xref:../rgant/rgant.adoc#_rgant-PreDestroy[`@PreDestroy`]. + + + http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_menu.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_menu.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_menu.adoc new file mode 100644 index 0000000..64d3201 --- /dev/null +++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_menu.adoc @@ -0,0 +1,91 @@ +[[_ugfun_programming-model_domain-services_menu]] += Menu +: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/ + + +Menu services provide actions to be rendered on the menu. + +For the Wicket viewer, each service's actions appear as a collection of menu items of a named menu, and this menu is on one of the three menu bars provided by the Wicket viewer. It is possible for more than one menu service's actions to appear on the same menu; a separator is shown between each. + +For the Restful Objects viewer, all menu services are shown in the services representation. + +We suggest naming such classes `XxxMenu`, eg: + + +[source,java] +---- +@DomainService( // <1> + nature = NatureOfService.VIEW_MENU_ONLY +) +@DomainServiceLayout( // <2> + named = "Customers", + menuBar = DomainServiceLayout.MenuBar.PRIMARY, + menuOrder = "10" +) +public class CustomerMenu { + + @Action( + semantics = SemanticsOf.SAFE + ) + @ActionLayout(bookmarking = BookmarkPolicy.AS_ROOT) + @MemberOrder( sequence = "1" ) + public List<Customer> findByName( // <3> + @ParameterLayout(named="Name") // <4> + final String name + ) { + return customerRepository.findByName(name); // <5> + } + + @Action( + semantics = SemanticsOf.NON_IDEMPOTENT + ) + @MemberOrder( sequence = "3" ) + public Customer newCustomer(...) { + return customerRepository.newCustomer(...); + } + + @Action( + semantics = SemanticsOf.SAFE, + restrictTo = RestrictTo.PROTOTYPING // <6> + ) + @MemberOrder( sequence = "99" ) + public List<Customer> listAll() { + return customerRepository.listAll(); + } + + @Inject + protected CustomerRepository customerRepository; // <4> +} +---- +<1> The (Apache Isis) xref:../rgant/rgant.adoc#_rgant_DomainService[`@DomainService`] annotation is used to identify the class as a domain service. +Apache Isis scans the classpath looking for classes with this annotation, so there very little configuration other than to tell the framework which packages to scan underneath. +The `VIEW_MENU_ONLY` nature indicates that this service's actions should be exposed as menu items. +<3> The xref:../rgant/rgant.adoc#_rgant_DomainServiceLayout[`@DomainServiceLayout`] annotation provides UI hints. +The menu is named "Customers" (otherwise it would have defaulted to "Customer Menu", based on the class name, while the xref:../rgant/rgant.adoc#_rgant_DomainServiceLayout_menuOrder[`menuOrder`] attribute determines the order of the menu with respect to other menu services. +<3> The `findByName` method is annotated with various Apache Isis annotations (xref:../rgant/rgant.adoc#_rgant_Action[`@Action`], xref:../rgant/rgant.adoc#_rgant_ActionLayout[`@ActionLayout`] and xref:../rgant/rgant.adoc#_rgant_MemberOrder[`@MemberOrder`] and is itself rendered in the UI as a "Find By Name" menu item underneath the "Simple Objects" menu. +<4> The xref:../rgant/rgant.adoc#_rgant_ParameterLayout[`@ParameterLayout`] provides metadata for the parameter itself, in this case its name. +<5> the action implementation delegates to an injected repository. +The framework can inject into not just other domain services but will also automatically into domain entities and view models. +There is further discussion of service injection xref:../ugfun/ugfun.adoc#_ugfun_programming-model_inject-services[below]. +<6> xref:../rgant/rgant.adoc#_rgant_Action_restrictTo[Prototype] actions are rendered only in prototyping mode. +A "list all" action such as this can be useful when exploring the domain with a small dataset. + +[TIP] +==== +Annotating action parameters with xref:../rgant/rgant.adoc#_rgant_ParameterLayout_named[`@ParameterLayout#named()`] can become somewhat tiresome. +You can avoid doing this by configuring the (non-ASF) http://github.com/isisaddons/isis-metamodel-paraname8[Isis addons' paraname8] metamodel extension. +==== + + +Not every action on the repository need to be delegated to of course (the above example does but only because it is very simple). + +[TIP] +==== +While there's nothing to stop `VIEW_MENU` domain services being injected into other domain objects and interacted with programmatically, we recommend against it. +Instead, inject the underlying repository. +If there is additional business logic, then consider introducing a further `DOMAIN`-scoped service and call that instead. +==== + + http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_organizing-services.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_organizing-services.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_organizing-services.adoc new file mode 100644 index 0000000..0ed0d44 --- /dev/null +++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_organizing-services.adoc @@ -0,0 +1,33 @@ +[[_ugfun_programming-model_domain-services_organizing-services]] += Organizing Services +: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/ + + + +In larger applications we have found it worthwhile to ensure that our domain services only act aligned with these responsibilities, employing a naming convention so that it is clear what the responsibilities of each domain service is. + +The application provides the `@DomainService(nature=...)` annotation that helps distinguish some of these responsibilities: + +* `VIEW_MENU_ONLY` indicates that the actions should appear on the menu of the xref:../ugvw/ugvw.adoc#[Wicket viewer], and as top-level actions for the REST API provided by the xref:../ugvro/ugvro.adoc#[Restful Objects viewer] + +* `DOMAIN` indicates that the actions are for other domain objects to invoke (either directly or indirectly through the event bus), but in any case should not be rendered at all in the UI + +* `VIEW_REST_ONLY` indicates that the actions should appear in the REST API provided by the xref:../ugvro/ugvro.adoc#[Restful Objects viewer], but not rendered by the xref:../ugvw/ugvw.adoc#[Wicket viewer]. + +There are also two other natures that should be considered "deprecated": + +* `VIEW_CONTRIBUTIONS_ONLY` which indicates that the actions should be contributed as actions to its action parameters. + ++ +This feature is deprecated because xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_types-of-domain-objects_mixins[mixins] are equivalent in functionality with a simpler programming model. + +* `VIEW` combines both `VIEW_MENU_ONLY` and the deprecated `VIEW_CONTRIBUTIONS_ONLY`. + +If the domain service nature is not specified (or is left to its default, `VIEW`), then the service's actions will appear in the UI. + +While for long-term maintainability we do recommend the naming conventions described xref:../ugfun/ugfun.adoc#__ugfun_building-blocks_domain-services_organizing-services[above], you can get away with far fewer services when just prototyping a domain. +Later on it is easy enough to refactor the code to tease apart the different responsibilities. + +Pulling all the above together, here are our suggestions as to how you should organize your domain services. + http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_registering.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_registering.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_registering.adoc new file mode 100644 index 0000000..409698a --- /dev/null +++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_registering.adoc @@ -0,0 +1,56 @@ +[[_ugfun_programming-model_domain-services_registering]] += Registering +: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 easiest way to register domain services with the framework is to use an xref:../rgcms/rgcms.adoc#_rgcms_classes_AppManifest-bootstrapping[`AppManifest`]. +This specifies the modules which contain xref:../rgant/rgant.adoc#_rgant-DomainService[`@DomainService`]-annotated classes. + +For example: + +[source,ini] +---- +public class MyAppManifest implements AppManifest { + public List<Class<?>> getModules() { + return Arrays.asList( + ToDoAppDomainModule.class, + ToDoAppFixtureModule.class, + ToDoAppAppModule.class, + org.isisaddons.module.audit.AuditModule.class); + } + ... +} +---- + +will load all services in the packages underneath the four modules listed. + +An alternative (older) mechanism is to registered domain services in the `isis.properties` configuration file, under `isis.services` key (a comma-separated list); for example: + +[source,ini] +---- +isis.services = com.mycompany.myapp.employee.Employees\, + com.mycompany.myapp.claim.Claims\, + ... +---- + +This will then result in the framework instantiating a single instance of each of the services listed. + +If all services reside under a common package, then the `isis.services.prefix` can specify this prefix: + +[source,ini] +---- +isis.services.prefix = com.mycompany.myapp +isis.services = employee.Employees,\ + claim.Claims,\ + ... +---- + +This is quite rare, however; you will often want to use default implementations of domain services that are provided by the framework and so will not reside under this prefix. + +Examples of framework-provided services (as defined in the applib) include clock, auditing, publishing, exception handling, view model support, snapshots/mementos, and user/application settings management; see the xref:../rgsvc/rgsvc.adoc#[domain services] reference guide for further details. + + + http://git-wip-us.apache.org/repos/asf/isis/blob/85b1e70b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_repository-and-factory.adoc ---------------------------------------------------------------------- diff --git a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_repository-and-factory.adoc b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_repository-and-factory.adoc new file mode 100644 index 0000000..850c05b --- /dev/null +++ b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_programming-model_domain-services_repository-and-factory.adoc @@ -0,0 +1,46 @@ +[[_ugfun_programming-model_domain-services_repository-and-factory]] += Repository and Factory +: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 repository/factory 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: + + +[source,java] +---- +@DomainService( + nature=NatureOfService.DOMAIN // <1> +) +public CustomerRepository { + public List<Customer> findByName(String name) { + return repositoryService.allMatches( // <2> + new QueryDefault<>(Customer.class, + "findByName", "name", name); + } + public Customer newCustomer(...) { + Customer Customer = + repositoryService.instantiate(Customer.class); // <3> + ... + repositoryService.persist(Customer); // <3> + return Customer; + } + public List<Customer> allCustomers() { + return repositoryService.allInstances(Customer.class); + } + @Inject + RepositoryService repositoryService; +} +---- +<1> interacted with only programmatically by other objects in the domain layer. +<2> uses injected `RepositoryService` to query via JDOQL. +<3> uses injected `RepositoryService` to first instantiate and then save into the database a new `Customer` instance. + +There is no need to annotate the actions; they are implicitly hidden because of the domain service's nature. + +
