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/04/15 21:07:51 UTC
isis git commit: ISIS-1133: triggering events subsection of user
guide.
Repository: isis
Updated Branches:
refs/heads/ISIS-1133-docs f95f34535 -> e530bda86
ISIS-1133: triggering events subsection of user guide.
also:
- deleting a backup accidentally committed.
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/e530bda8
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/e530bda8
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/e530bda8
Branch: refs/heads/ISIS-1133-docs
Commit: e530bda868bee7fc2fee2070186defed7908e132
Parents: f95f345
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Wed Apr 15 20:07:45 2015 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Wed Apr 15 20:07:45 2015 +0100
----------------------------------------------------------------------
.../src/main/asciidoc/documentation.adoc | 10 +-
.../asciidoc/user-guide/user-guide-ORIG.adoc | 24 ----
.../user-guide-how-tos-triggering-events.adoc | 136 +++++++++++++++++++
.../asciidoc/user-guide/user-guide-how-tos.adoc | 7 +
.../main/asciidoc/user-guide/user-guide.adoc | 1 -
5 files changed, 151 insertions(+), 27 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/e530bda8/adocs/documentation/src/main/asciidoc/documentation.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/documentation.adoc b/adocs/documentation/src/main/asciidoc/documentation.adoc
index 10afc0e..c6f3008 100644
--- a/adocs/documentation/src/main/asciidoc/documentation.adoc
+++ b/adocs/documentation/src/main/asciidoc/documentation.adoc
@@ -7,9 +7,15 @@
Finding your way around:
+ifdef::env-github[]
+WARNING: You are browsing this file on Github.
+
+For the links below, replace the `.html` with `.adoc` to find the original source.
+endif::[]
+
* Introducing Isis
-** link:introducing-isis/isis-in-pictures/isis-in-pictures.html[Isis in Pictures]
-** link:introducing-isis/common-use-cases/common-use-cases.html[Common Use Cases]
+** link:introducing-apache-isis/isis-in-pictures/isis-in-pictures.html[Isis in Pictures]
+** link:introducing-apache-isis/common-use-cases/common-use-cases.html[Common Use Cases]
* Getting Started
** link:getting-started/archetype/simpleapp-archetype.html[SimpleApp Archetype]
** Development Environments
http://git-wip-us.apache.org/repos/asf/isis/blob/e530bda8/adocs/documentation/src/main/asciidoc/user-guide/user-guide-ORIG.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/user-guide-ORIG.adoc b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-ORIG.adoc
deleted file mode 100644
index 8febabb..0000000
--- a/adocs/documentation/src/main/asciidoc/user-guide/user-guide-ORIG.adoc
+++ /dev/null
@@ -1,24 +0,0 @@
-= User Guide
-: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
-:numbered:
-
-## Core Concepts
-
-include::user-guide-core-concepts.adoc[leveloffset=+1]
-
-## Reference
-
-include::user-guide-reference.adoc[leveloffset=+1]
-
-## How-tos
-
-include::user-guide-howtos.adoc[leveloffset=+2]
-
-## Configuration
-
-include::user-guide-config.adoc[leveloffset=+1]
-
-
http://git-wip-us.apache.org/repos/asf/isis/blob/e530bda8/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos-triggering-events.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos-triggering-events.adoc b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos-triggering-events.adoc
new file mode 100644
index 0000000..50a41d9
--- /dev/null
+++ b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos-triggering-events.adoc
@@ -0,0 +1,136 @@
+= User Guide: How-tos: Triggering Events
+: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/
+
+NOTE: TODO
+
+## Publishing and Subscribing to Events (Pulling Changes)
+
+
+
+## Pushing Changes
+
+NOTE: this technique is much less powerful than the event bus described in <<Publishing and Subscribing to Events (Pulling Changes)>>). We present it mostly for completeness.
+
+### When a property is changed
+
+If you want to invoke functionality whenever a property is changed by the user, then you should create a supporting `modifyXxx()` method and include the functionality within that. The syntax is:
+
+[source,java]
+--
+public void modifyPropertyName(PropertyType param) { ... }
+--
+
+Why not just put this functionality in the setter? Well, the setter is used by the object store to recreate the state of an already persisted object. Putting additional behaviour in the setter would cause it to be triggered incorrectly.
+
+For example:
+
+[source,java]
+--
+public class Order() {
+ public Integer getAmount() { ... }
+ public void setAmount(Integer amount) { ... }
+ public void modifyAmount(Integer amount) { // <1>
+ setAmount(amount); // <3>
+ addToTotal(amount); // <2>
+ }
+ ...
+}
+--
+<1> The `modifyAmount()` method calls ...
+<2> ... the `addToTotal()` (not shown) to maintain some running total.
+
+We don't want this `addToCall()` method to be called when pulling the object back from the object store, so we put it into the modify, not the setter.
+
+You may optionally also specify a `clearXxx()` which works the same way as modify `modify Xxx()` but is called when the property is cleared by the user (i.e. the current value replaced by nothing). The syntax is:
+
+[source,java]
+--
+public void clearPropertyName() { ... }
+--
+
+To extend the above example:
+
+[source,java]
+--
+public class Order() {
+ public Integer getAmount() { ... }
+ public void setAmount(Integer amount) { ... }
+ public void modifyAmount(Integer amount) { ... }
+ public void clearAmount() {
+ removeFromTotal(this.amount);
+ setAmount(null);
+ }
+ ...
+}
+--
+
+### When a collection is added to or removed from
+
+A collection may have a corresponding `addToXxx()` and/or
+`removeFromXxx()` method. If present, and direct manipulation of the
+contents of the connection has not been disabled (see ?), then they will
+be called (instead of adding/removing an object directly to the
+collection returned by the accessor).
+
+The reason for this behaviour is to allow other behaviour to be
+triggered when the contents of the collection is altered. That is, it is
+directly equivalent to the supporting `modifyXxx()` and `clearXxx()`
+methods for properties (see ?).
+
+The syntax is:
+
+[source,java]
+--
+public void addTo<CollectionName>(EntityType param) { ... }
+--
+
+and
+
+[source,java]
+--
+public void removeFromCollectionName(EntityType param) { ... }
+--
+
+where `EntityType` is the same type as the generic collection type.
+
+For example:
+
+[source,java]
+--
+public class Employee { ... }
+
+public class Department {
+
+ private int numMaleEmployees; // <1>
+ private int numFemaleEmployees; // <1>
+
+ private Set<Employee> employees = new TreeSet<Employee>();
+ public Set<Employee> getEmployees() {
+ return employees;
+ }
+ private void setEmployees(Set<Employee> employees) {
+ this.employees = employees;
+ }
+ public void addToEmployees(Employee employee) {
+ numMaleEmployees += countOneMale(employee); // <2>
+ numFemaleEmployees += countOneFemale(employee); // <2>
+ employees.add(employee);
+ }
+ public void removeFromEmployees(Employee employee) {
+ numMaleEmployees -= countOneMale(employee); // <3>
+ numFemaleEmployees -= countOneFemale(employee); // <3>
+ employees.remove(employee);
+ }
+ private int countOneMale(Employee employee) { return employee.isMale()?1:0; }
+ private int countOneFemale(Employee employee) { return employee.isFemale()?1:0; }
+
+ ...
+}
+--
+<1> maintain a count of the number of male and female employees (getters and setters omitted)
+<2> the `addTo...()` method increments the derived properties
+<3> the `removeTo...()` method similarly decrements the derived properties
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/e530bda8/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos.adoc b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos.adoc
index c15020f..1e1b387 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/user-guide-how-tos.adoc
@@ -52,3 +52,10 @@ include::user-guide-how-tos-business-rules.adoc[leveloffset=+1]
include::user-guide-how-tos-drop-downs-and-defaults.adoc[leveloffset=+1]
+
+## Triggering Events
+
+include::user-guide-how-tos-triggering-events.adoc[leveloffset=+1]
+
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/e530bda8/adocs/documentation/src/main/asciidoc/user-guide/user-guide.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/user-guide.adoc b/adocs/documentation/src/main/asciidoc/user-guide/user-guide.adoc
index 8febabb..ea4aeac 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/user-guide.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/user-guide.adoc
@@ -2,7 +2,6 @@
: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
:numbered:
## Core Concepts