This is an automated email from the ASF dual-hosted git repository. danhaywood pushed a commit to branch release-2.0.0-M8-RC4 in repository https://gitbox.apache.org/repos/asf/isis.git
commit 553072f0cf591725a0e28797faa5e8c525c0a8ff Author: Dan Haywood <[email protected]> AuthorDate: Sun Oct 2 15:21:01 2022 +0100 ISIS-3222: minor doc improvement re: mixins --- .../userguide/modules/fun/pages/mixins.adoc | 36 ++++++++++++++-------- 1 file changed, 23 insertions(+), 13 deletions(-) diff --git a/antora/components/userguide/modules/fun/pages/mixins.adoc b/antora/components/userguide/modules/fun/pages/mixins.adoc index 6d28ce9fbc..dbe04ac727 100644 --- a/antora/components/userguide/modules/fun/pages/mixins.adoc +++ b/antora/components/userguide/modules/fun/pages/mixins.adoc @@ -5,6 +5,7 @@ As described in the xref:userguide:fun:overview.adoc#mixins[overview], a mixin acts like a trait or extension method, allowing one module to contribute behaviour or derived state to another object. +This is a *very powerful feature*, but at the same time is easy to use. Under the covers, all mixins are basically actions that use the mixee as one of their arguments. @@ -17,13 +18,15 @@ Under the covers, all mixins are basically actions that use the mixee as one of Accordingly, a mixin can be defined using the xref:refguide:applib:index/annotation/Action.adoc[@Action], xref:refguide:applib:index/annotation/Property.adoc[@Property] or xref:refguide:applib:index/annotation/Collection.adoc[@Collection] annotations, but defined at the domain class level rather than at the method level. -Using xref:refguide:applib:index/annotation/DomainObject.adoc#nature[@DomainObject#nature] attribute (specifying a nature of `Nature.MIXIN`), in combination with the above allows for more fine grained control, eg. nominating the mixin's method name. +The mixin is expected to follow the naming convention `SomeType_mixinName`, with the name of the contributed member being contributed is inferred from the name of the class itself, being everything after the last '_'. +For example, if the mixin is called `DocumentHolder_documents`, then the mixee is `DocumentHolder` interface, and `documents` is the name of the contributed collection. -When the mixin follows the naming convention `SomeType_mixinName` then the method name can be abbreviated, and the name of the member being contributed is inferred from the name of the class itself, being everything after the last '_'. +This example also hints at why mixins are so powerful: the mixee's type is usually an interface, not a concrete class. +Thus, any class that implements `DocumentHolder`, eg `Customer` or `Order`, will be contributed to. == Contributed Collection -The example below shows how to contribute a collection, using xref:refguide:applib:index/annotation/Collection.adoc[@Collection]. +The example below shows in more detail how to contribute a collection, using xref:refguide:applib:index/annotation/Collection.adoc[@Collection]. The method is expected to be called "coll": [source,java] @@ -125,15 +128,17 @@ For example, the following refactors the "updateName" action -- of the `SimpleOb public class SimpleObject /* ... */ { // ... - public static class UpdateNameActionDomainEvent extends - SimpleModule.ActionDomainEvent<SimpleObject.updateName> {} // <.> @Action(semantics = IDEMPOTENT, - commandPublishing = Publishing.ENABLED, - executionPublishing = Publishing.ENABLED, - associateWith = "name", - domainEvent = UpdateNameActionDomainEvent.class) + commandPublishing = Publishing.ENABLED, + executionPublishing = Publishing.ENABLED, + associateWith = "name", + domainEvent = updateName.DomainEvent.class) // <2> public class updateName { // <.> + + public class DomainEvent extends + SimpleModule.ActionDomainEvent<SimpleObject.updateName> {} // <.> + public SimpleObject act(@Name final String name) { setName(name); // <.> return SimpleObject.this; @@ -145,9 +150,14 @@ public class SimpleObject /* ... */ { // ... } ---- -<.> Domain event is genericised on the mixin, not on the mixee -<.> Not static. -Can be camelCase or PascalCase, either will work. +<.> Mixin class is not `static`, so that the containing object is implicitly available. ++ +Its name can be either "camelCase" or "PascalCase", either will work. + +<.> Domain event can be declared within the mixin, again, not `static`. ++ +Note that it is genericised on the mixin, not on the mixee + <.> Acts on the owning instance. <.> xref:business-rules.adoc[Supporting methods] follow the same naming convention. <.> Acts on the owning instance. @@ -169,7 +179,7 @@ DocumentHolder_documents mixin = ---- Alternatively, you can use xref:refguide:applib:index/services/inject/ServiceInjector.adoc[ServiceInjector] to inject domain services after the mixin has been instantiated. -You'll need to use this method if using nested non-static mixins: +You'll need to use this method if using nested non-`static` mixins: [source,java]
