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 2015/11/15 11:06:09 UTC
isis git commit: ISIS-1249: docs
Repository: isis
Updated Branches:
refs/heads/master 2c89cbb44 -> a8c48a238
ISIS-1249: docs
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/a8c48a23
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/a8c48a23
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/a8c48a23
Branch: refs/heads/master
Commit: a8c48a2381608def30a4e6876617488652140213
Parents: 2c89cbb
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Sun Nov 15 10:01:07 2015 +0000
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Sun Nov 15 10:05:45 2015 +0000
----------------------------------------------------------------------
...lasses_super_manpage-AbstractSubscriber.adoc | 12 ++++++++++-
...rg_services-api_manpage-EventBusService.adoc | 22 +++++++++++++++++---
2 files changed, 30 insertions(+), 4 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/a8c48a23/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractSubscriber.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractSubscriber.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractSubscriber.adoc
index b663f38..520c0f9 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractSubscriber.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_classes_super_manpage-AbstractSubscriber.adoc
@@ -5,4 +5,14 @@
:_imagesdir: images/
-This is a convenience superclass for creating subscriber domain services on the xref:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`]. It uses xref:rg.adoc#_rg_annotations_manpage-PostConstruct[`@PostConstruct`] and xref:rg.adoc#_rg_annotations_manpage-PreDestroy[`@PreDestroy`] callbacks to automatically register itself with the `EventBusService`.
+This is a convenience superclass for creating subscriber domain services on the xref:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`]. It uses xref:rg.adoc#_rg_annotations_manpage-PostConstruct[`@PostConstruct`] and
+xref:rg.adoc#_rg_annotations_manpage-PreDestroy[`@PreDestroy`] callbacks to automatically register/unregister itself
+with the `EventBusService`.
+
+It's important that subscribers register before any domain services that might emit events on the
+xref:rg.adoc#_rg_services-api_manpage-EventBusService[`EventBusService`]. For example, the (non-ASF) http://github.com/isisaddons/isis-module-security[Isis addons' security] module provides a domain service that automatically
+seeds certain domain entities; these will generate xref:rg.adoc#_rg_classes_lifecycleevent[lifecycle events] and so
+any subscribers must be registered before such seed services. The easiest way to do this is to use the
+xref:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] attribute.
+
+As a convenience, (as of `1.11.0-SNAPSHOT`) the `AbstractSubscriber` specifies this attribute.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/a8c48a23/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-EventBusService.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-EventBusService.adoc b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-EventBusService.adoc
index fb01cba..3639e9b 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-EventBusService.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_rg_services-api_manpage-EventBusService.adoc
@@ -58,25 +58,41 @@ For example:
[source,java]
----
-@DomainService(nature=NatureOfService.DOMAIN)
+@DomainService(nature=NatureOfService.DOMAIN) // <1>
+@DomainServiceLayout( menuOrder="1") // <2>
public class MySubscribingDomainService {
@PostConstruct
public void postConstruct() {
- eventBusService.register(this);
+ eventBusService.register(this); // <3>
}
@PreDestroy
public void preDestroy() {
- eventBusService.unregister(this);
+ eventBusService.unregister(this); // <4>
}
...
@javax.inject.Inject
EventBusService eventBusService;
}
----
+<1> subscribers are typically not visible in the UI, so specify a `DOMAIN` nature
+<2> It's important that subscribers register before any domain services that might emit events on the event bus service.
+For example, the (non-ASF) http://github.com/isisaddons/isis-module-security[Isis addons' security] module provides a
+domain service that automatically seeds certain domain entities; these will generate
+xref:rg.adoc#_rg_classes_lifecycleevent[lifecycle events] and so any subscribers must be registered before such seed
+services. The easiest way to do this is to use the xref:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] attribute.
+<3> register with the event bus service during xref:rg.adoc#_rg_annotations_manpage-PostConstruct[`@PostConstruct`]
+ initialization
+<4> corresponding deregister when shutting down
This works for both singleton (application-scoped) and also xref:rg.adoc#_rg_annotations_manpage-RequestScoped[`@RequestScoped`] domain services.
+[TIP]
+====
+The xref:rg.adoc#_rg_classes_super_manpage-AbstractSubscriber[`AbstractSubscriber`] class automatically performs this
+registration. As a convenience, (as of `1.11.0-SNAPSHOT`) it is also annotated with the
+xref:rg.adoc#_rg_annotations_manpage-DomainServiceLayout_menuOrder[`@DomainServiceLayout#menuOrder()`] attribute.
+====