wip - ugfun.adoc ... business rules

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

Branch: refs/heads/wip
Commit: acf946c0b36514886e27617d9b930a71a01516d8
Parents: 842c5b4
Author: Dan Haywood <d...@haywood-associates.co.uk>
Authored: Tue Apr 18 00:21:46 2017 +0200
Committer: Dan Haywood <d...@haywood-associates.co.uk>
Committed: Thu Apr 20 09:09:31 2017 +0100

----------------------------------------------------------------------
 .../rgcms/_rgcms_methods_prefixes_addTo.adoc    |   2 +-
 .../rgcms/_rgcms_methods_prefixes_clear.adoc    |   9 +-
 .../rgcms/_rgcms_methods_prefixes_modify.adoc   |  10 +-
 .../_rgcms_methods_prefixes_removeFrom.adoc     |   2 +-
 .../_rgcms_methods_prefixes_validateAddTo.adoc  |   5 +-
 ...cms_methods_prefixes_validateRemoveFrom.adoc |   5 +-
 .../guides/ugfun/_ugfun_business-rules.adoc     | 180 +++++++++++++++----
 .../guides/ugfun/_ugfun_crud_finding.adoc       |   2 +-
 .../guides/ugfun/_ugfun_crud_instantiating.adoc |  16 ++
 .../ugfun/_ugfun_drop-downs-and-defaults.adoc   |   4 +-
 10 files changed, 191 insertions(+), 44 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/acf946c0/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_addTo.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_addTo.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_addTo.adoc
index ba67ff6..e44255e 100644
--- 
a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_addTo.adoc
+++ 
b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_addTo.adoc
@@ -1,5 +1,5 @@
 [[_rgcms_methods_prefixes_addTo]]
-= `addTo...()`
+= `addTo...()` (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/

http://git-wip-us.apache.org/repos/asf/isis/blob/acf946c0/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_clear.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_clear.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_clear.adoc
index a70856e..1fe3809 100644
--- 
a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_clear.adoc
+++ 
b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_clear.adoc
@@ -1,13 +1,18 @@
 [[_rgcms_methods_prefixes_clear]]
-= `clear...()`
+= `clear...()` (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/
 
 
 
-The `clear...()` supporting method is called -- instead of the setter -- 
whenever an (optional) property is to be set to `null`.  Its purpose is to 
allow additional business logic to be performed.
+The `clear...()` supporting method is called -- instead of the setter -- 
whenever an (optional) property is to be set to `null`.
+Its purpose is to allow additional business logic to be performed.
 
+[NOTE]
+====
+DataNucleus' smart handling of setters means that this supporting methods are 
in essence redundant, and so should be considered deprecated.
+====
 
 For example:
 

http://git-wip-us.apache.org/repos/asf/isis/blob/acf946c0/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_modify.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_modify.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_modify.adoc
index bc41a70..7938bd3 100644
--- 
a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_modify.adoc
+++ 
b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_modify.adoc
@@ -1,12 +1,18 @@
 [[_rgcms_methods_prefixes_modify]]
-= `modify...()`
+= `modify...()` (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/
 
 
 
-The `modify...()` supporting method is called -- instead of the setter -- 
whenever a property has been set to be set to a new value.  Its purpose is to 
allow additional business logic to be performed.
+The `modify...()` supporting method is called -- instead of the setter -- 
whenever a property has been set to be set to a new value.
+Its purpose is to allow additional business logic to be performed.
+
+[NOTE]
+====
+DataNucleus' smart handling of setters means that this supporting methods are 
in essence redundant, and so should be considered deprecated.
+====
 
 
 For example:

http://git-wip-us.apache.org/repos/asf/isis/blob/acf946c0/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_removeFrom.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_removeFrom.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_removeFrom.adoc
index a95aa44..7915745 100644
--- 
a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_removeFrom.adoc
+++ 
b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_removeFrom.adoc
@@ -1,5 +1,5 @@
 [[_rgcms_methods_prefixes_removeFrom]]
-= `removeFrom...()`
+= `removeFrom...()` (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/

http://git-wip-us.apache.org/repos/asf/isis/blob/acf946c0/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_validateAddTo.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_validateAddTo.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_validateAddTo.adoc
index 50e11ec..40ff60a 100644
--- 
a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_validateAddTo.adoc
+++ 
b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_validateAddTo.adoc
@@ -1,5 +1,5 @@
 [[_rgcms_methods_prefixes_validateAddTo]]
-= `validateAddTo...()`
+= `validateAddTo...()` (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/
@@ -11,7 +11,8 @@ The `validateAddTo...()` supporting method is called whenever 
an object is to be
 
 [NOTE]
 ====
-Directly mutable collections are not currently supported by the 
xref:../ugvw/ugvw.adoc#[Wicket viewer].  The suggested workaround is to simply 
define an action.
+Directly mutable collections are not currently supported by the 
xref:../ugvw/ugvw.adoc#[Wicket viewer].
+The suggested workaround is to simply define an action.
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/acf946c0/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_validateRemoveFrom.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_validateRemoveFrom.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_validateRemoveFrom.adoc
index cec48a7..985c033 100644
--- 
a/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_validateRemoveFrom.adoc
+++ 
b/adocs/documentation/src/main/asciidoc/guides/rgcms/_rgcms_methods_prefixes_validateRemoveFrom.adoc
@@ -1,5 +1,5 @@
 [[_rgcms_methods_prefixes_validateRemoveFrom]]
-= `validateRemoveFrom...()`
+= `validateRemoveFrom...()` (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/
@@ -11,7 +11,8 @@ The `validateRemoveFrom...()` supporting method is called 
whenever an object is
 
 [NOTE]
 ====
-Directly mutable collections are not currently supported by the 
xref:../ugvw/ugvw.adoc#[Wicket viewer].  The suggested workaround is to simply 
define an action.
+Directly mutable collections are not currently supported by the 
xref:../ugvw/ugvw.adoc#[Wicket viewer].
+The suggested workaround is to simply define an action.
 ====
 
 

http://git-wip-us.apache.org/repos/asf/isis/blob/acf946c0/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_business-rules.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_business-rules.adoc 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_business-rules.adoc
index e799572..681c263 100644
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_business-rules.adoc
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_business-rules.adoc
@@ -4,86 +4,204 @@
 :_basedir: ../../
 :_imagesdir: images/
 
-NOTE: FIXME
 
+When a domain object is rendered in the UI or the end-user interacts with the 
domain object through the UI, the framework applies a series of precondition 
business rules to each object member (property, collection or action).
+
+When the object is being rendered, the framework checks:
+
+* is the object member visible? +
++
+Members that are not visible are simply omitted from the page.
+If all the members in a fieldset (property group) are hidden, then the 
fieldset is not shown.
+If all the members in a tab are hidden, then the tab is not shown.
+If all the members of the object are hidden, then a "404" style message ("no 
such object") is returned to the user.
+
+* if the object member is visible, is the object member enabled? +
++
+An enabled property can be edited (otherwise it is read-only), and an enabled 
action can be invoked (otherwise it's button is "greyed-out").
+Note that collections are always read-only.
+
+* for enabled object members, if the user then interacts with that member, are 
the supplied values valid (can the user "do it"). +
++
+For an editable property this means validating the proposed new value of the 
property.
+For an invokable action this means validating that arguments being used to 
invoke the action.
+
+
+One way to remember this is: *"see it, use it, do it"*
+
+
+The framework provides a multitude of ways to implement these business rules.
+One decoupled approach is using 
xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_events_domain-events[domain 
events]; the checks above correspond to the phases of the domain event.
+A simpler approach is to just implement the business rules imperatively in the 
domain object, or in a mixin for the object.
 
 
 == Visibility ("see it")
 
-NOTE: FIXME - 
xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_hide[`hide...()`]
+To hide an object action:
+
+[source,java]
+----
+public Customer placeOrder(Product p, int quantity) { ... }
+public boolean hidePlaceOrder() { ... }
+----
 
-### Hide a Property
+If the `hideXxx` method returns `true` then the action is hidden.
+Note that the supporting method takes no parameters.
 
-### Hide a Collection
 
-### Hide an Action
+A property or collection can be hidden similarly:
 
-### Hide a Contributed Property, Collection or Action
+[source,java]
+----
+public String getStatus() { ... }
+public void setStatus(String status) { ... }
 
-### All Members Hidden
+public boolean hideStatus() { ... }
+----
 
 
+For more information, see the 
xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_hide[`hide...()`] section in 
the appropriate reference guide.
 
 
 == Usability ("use it")
 
-NOTE: FIXME - 
xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_disable[`disable...()`]
+To disable an object action:
 
-### Disable a Property
+[source,java]
+----
+public Customer placeOrder(Product p, int quantity) { ... }
+public String disablePlaceOrder() { ... }
+----
 
-### Disable a Collection
+Here a non-`null` value is used as the reason why the action is disabled.
+It is also possible to return a localized string by returning a 
`TranslatableString`.
 
-### Disable an Action
 
-### Disable a Contributed Property, Collection or Action
+Properties are similar (note that collections are implicitly read-only in the 
xref:../ugvw/ugvw.adoc#[Wicket viewer]:
 
-### All Members Unmodifiable (Disabling the Edit Button)
 
-Sometimes an object is unmodifiable.
+[source,java]
+----
+public String getStatus() { ... }
+public void setStatus(String status) { ... }
 
-In the Wicket viewer this means disabling the edit button.
+public String disableStatus() { ... }
+----
 
-#### Declarative
+For more information, see  
xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_disable[`disable...()`] 
section in the appropriate reference guide.
 
-`@DomainObject(editing=...)`
 
-#### Imperative
+It is also possible to make all properties of a domain object unmodifiable, 
using:
+
+[source,java]
+----
+@DomainObject(
+    editing=Editing.DISABLED
+)
+public class Customer { ... }
+----
+
+This can be made a global policy using a 
xref:../rgcfg/rgcfg.adoc#__rgcfg_configuring-core_isis-objects-editing[configuration
 setting]:
+
+.isis.properties
+[source,ini]
+----
+isis.objects.editing=false
+----
 
 
 
 == Validity ("do it")
 
-NOTE: FIXME - 
xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_validate[`validate...()`], 
xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_validateAddTo[`validateAddTo...()`],
 
xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_validateRemoveFrom[`validateRemoveFrom...()`]
 and xref:../rgcms/rgcms.adoc#_rgcms_methods_reserved_validate[`validate()`]
+Action arguments can be validated either singly or as a set.
+For example:
+
+[source,java]
+----
+public Customer placeOrder(Product p, int quantity) { ... }
+public String validate0PlaceOrder(Product p) { ... }               // <1>
+public String validate1PlaceOrder(int quantity) { ... }            // <2>
+public String validatePlaceOrder(Product p, int quantity) { ... }  // <3>
+----
+<1> validates the 0th argument of the action (0-based numbering), ie `Product`
+<2> validates the 1st argument of the action, ie `int quantity`
+<3> validates all the arguments of the action together.
+
+The framework validates each argument separately; only if all are valid does 
it check all the arguments together.
+
+As for usability check, a non-`null` value is used as the reason why the 
action arguments are invalid.
+It is also possible to return a localized string by returning a 
`TranslatableString`.
+
+Similarly, property edits can also be validated:
+
+[source,java]
+----
+public String getStatus() { ... }
+public void setStatus(String status) { ... }
+
+public String validateStatus(String status) { ... }
+----
 
+For more information, see the 
xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_validate[`validate...()`] 
section in the appropriate reference guide.
+The reference guide also explains how to define validation declaratively, 
using the 
xref:../rgant/rgant.adoc#_rgant-Parameter_mustSatisfy[`@Parameter#mustSatisfy()`]
 or 
xref:../rgant/rgant.adoc#_rgant-Property_mustSatisfy[`@Property#mustSatisfy()`] 
attributes.
 
-### Validate (change to) a Property
 
-### Validate (adding or removing from) a Collection
 
-### Validate (arguments to invoke) an Action
+== Actions
 
-### Validating a Contributed Property, Collection or Action
+Of course, the precondition business rules described above are only one type 
of business rule.
 
-### Declarative validation
+More generally, business rules are implemented in the form of the 
implementation of actions.
+Rather than have the end-user have to edit individual properties of numerous 
objects, an action can encode these rules and allow only safe transformations 
of the application from one consistent state to the next.
 
-NOTE: FIXME - using 
xref:../rgant/rgant.adoc#_rgant-Parameter_mustSatisfy[`@Parameter#mustSatisfy()`],
 xref:../rgant/rgant.adoc#_rgant-Property_mustSatisfy[`@Property#mustSatisfy()`]
 
 
+== Side effects
 
+Often when the state of an object is modified there is a business rule for 
some sort of side-effect.
+For example, suppose that a `Person` has a persisted derived property:
 
+[source,java]
+----
+public class Person {
 
+    @Getter @Setter                     // <1>
+    private LocalDate dateOfBirth;
 
+    @Getter @Setter
+    private int age;                    // <2>
+----
+<1> using Lombok to remove boilerplate.
+<2> persisted derived property based on `dateOfBirth`.
 
-== On modification
+One design would be to only allow the two properties to be modified through an 
action:
 
-NOTE: FIXME - detail here...
+[source,java]
+----
+public Person updateDateOfBirth(LocalDate dateOfBirth) {
+    setDateOfBirth(dateOfBirth);
+    setAge(Years.between(clockService.now(), dateOfBirth));
+    return this;
+}
+----
 
-=== Trigger on property change
+Alternatively we could allow the property to be edited, and then compute the 
side-effect.
 
-NOTE: FIXME - 
xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_modify[`modify...()`], 
xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_clear[`clear...()`]
+[source,java]
+----
+public void setDateOfBirth(LocalDate dateOfBirth) {
+    this.dateOfBirth = dateOfBirth;
+    setAge(Years.between(clockService.now(), dateOfBirth));
+    return this;
+}
+----
 
+Datanucleus does _not_ call the setter when reloading the object from the 
database, so there is no issue in having the side-effect code (calling 
`setAge(...)`).
 
+[NOTE]
+====
+The framework also allows side-effect code to be placed in separate 
xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_modify[`modify...()`], 
xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_clear[`clear...()`] supporting 
methods; if present then these will be called by the framework rather than the 
setter.
+However, because of DataNucleus' smart handling of setters, these supporting 
methods are in essence redundant, and so should be considered deprecated.
+====
 
-=== Trigger on collection change
 
-NOTE: FIXME - 
xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_addTo[`addTo...()`], 
xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_removeFrom[`removeFrom...()`]

http://git-wip-us.apache.org/repos/asf/isis/blob/acf946c0/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_finding.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_finding.adoc 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_finding.adoc
index 971245b..3bbd67f 100644
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_finding.adoc
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_finding.adoc
@@ -60,7 +60,7 @@ This ensures that the database query runs against an 
up-to-date table so that al
 When an object is loaded from the database the framework will emit 
`ObjectLoadedEvent` 
xref:../ugfun/ugfun.adoc#_ugfun_building-blocks_events_lifecycle-events[lifecycle
 event].
 
 
-== Using DataNucleus type-safe queries
+== Type-safe queries
 
 DataNucleus also supports type-safe queries; see 
xref:../rgsvc/rgsvc.adoc#__rgsvc_api_IsisJdoSupport_type-safe-jdoql-queries[here]
 for further details.
 

http://git-wip-us.apache.org/repos/asf/isis/blob/acf946c0/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_instantiating.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_instantiating.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_instantiating.adoc
index 1ed757d..bfcb7c6 100644
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_instantiating.adoc
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_crud_instantiating.adoc
@@ -50,3 +50,19 @@ serviceRegister.injectServicesInto(customer);
 ----
 
 Note that this does _not_ raise any lifecycle event.
+
+
+To instantiate a mixin, a different API of `FactoryService` is used:
+
+[source,java]
+----
+Customer_placeOrder placeOrderMixin = 
factoryService.mixin(Customer_placeOrder.class, customer);
+----
+
+Alternatively and equivalently, the mixin can be manually instantiated, and 
then the services injected directly:
+
+[source,java]
+----
+Customer_placeOrder placeOrderMixin = new Customer_placeOrder(customer);
+serviceRegistry.injectServicesInto(placeOrderMixin);
+----

http://git-wip-us.apache.org/repos/asf/isis/blob/acf946c0/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_drop-downs-and-defaults.adoc
----------------------------------------------------------------------
diff --git 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_drop-downs-and-defaults.adoc
 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_drop-downs-and-defaults.adoc
index fdf2a1f..44bab58 100644
--- 
a/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_drop-downs-and-defaults.adoc
+++ 
b/adocs/documentation/src/main/asciidoc/guides/ugfun/_ugfun_drop-downs-and-defaults.adoc
@@ -7,6 +7,7 @@
 NOTE: FIXME
 
 
+
 == For Properties
 
 NOTE: FIXME
@@ -49,8 +50,7 @@ NOTE: FIXME -  
xref:../rgcms/rgcms.adoc#_rgcms_methods_prefixes_default[`default
 
 
 
-
-== For both Properties and Action Parameters
+== For both Properties and Params
 
 NOTE: FIXME
 

Reply via email to