Eventing in Services - Revision history

Paulb: /* Supporting Events */

2008-12-25T01:12:03Z

‎Supporting Events

Paulb: /* Interface Event Declarations */

2008-12-25T01:04:30Z

‎Interface Event Declarations

Paulb: /* Creating an Observer */

2008-12-25T01:00:34Z

‎Creating an Observer

Paulb: /* Supporting Events */

2008-12-24T23:35:24Z

‎Supporting Events

Paulb: /* Interface Event Declarations */

2008-12-24T23:32:58Z

‎Interface Event Declarations

Paulb: /* Interface Event Declarations */

2008-12-24T23:31:55Z

‎Interface Event Declarations

Paulb: /* Creating an Observer */

2008-12-17T01:30:22Z

‎Creating an Observer

Paulb: /* Creating an Observer */

2008-12-17T00:49:31Z

‎Creating an Observer

Paulb: /* = Creating an Observer */

2008-12-16T23:01:44Z

‎= Creating an Observer

Paulb: /* Supporting Events */

2008-12-16T22:26:31Z

‎Supporting Events

@@ Line 76: / Line 76: @@
 <e>
-is_interface_usable: {l_usable: USABLE_I} Current implies l_usable.is_interface_usable
+    is_interface_usable: {l_usable: USABLE_I} Current implies l_usable.is_interface_usable
 </e>
 as the first assertion. Add any other preconditions for the event handler's arguments known to hold true when an event is published.
 ==== Create an Observer Connection Point ====

@@ Line 23: / Line 23: @@
 feature -- Events
-     changed_event: !EVENT_TYPE_I [TUPLE [flags: INTEGER]]
+     changed_event: !EVENT_TYPE_I [TUPLE [sender: MY_INTERFACE_I; flags: INTEGER]]
              -- Events call when a change occurs
          require

@@ Line 55: / Line 55: @@
 <e>
 class
-     INTERFACE_OBSERVER
+     MY_INTERFACE_OBSERVER
 inherit
@@ Line 62: / Line 62: @@
 feature -- Event Handler
-     on_changed (a_flags: INTEGER)
+     on_changed (a_sender: MY_INTERFACE_I; a_flags: INTEGER)
              --
          require
              is_interface_usable: {l_usable: USABLE_I} Current implies l_usable.is_interface_usable
          do
          end
 end
 </e>
 ==== Create an Observer Connection Point ====

@@ Line 42: / Line 42: @@
 === Supporting Events ===
-With this diminutive example there seems no need for any support for a single event, when using multiple events it becomes more necessary to support the interface. Here support comes in the form of providing an observer to all the events on a given interface. Utilizing an observer is a quick way for multiple clients to subscribe to an interface events. As an added feature, the implementation using observers is less error prone to memory leaks associated with failure to unscribed to all scribed-to events.
+With such a diminutive example there seems no need for any support for a single event, when using multiple events it becomes more evident and necessary to support the interface. Eventing support comes in the form of providing an implementation observer pattern, which can autonomously subscribe to all the events on a given interface. Utilizing an observer is a quick way for multiple clients to subscribe to an interface events. As an added feature, the implementation using observers is less error prone to memory leaks associated with failure to un-subscribed to all subscribed to events.
 ==== Creating an Observer ====

@@ Line 37: / Line 37: @@
 The first point to recognize is the name of the event feature is singular and not plural. It is, after all, an event and not a collection of events. An event will have multiple event handlers subscribed to it, all called when published, but it is still a single event.
-The design opts to define a deferred feature for specification of the event. As with all interface definitions should be free from all specific implementation and bindings to a particular declaration style, unless necessary of course. The implementation is now free to implement the event as a once, once-per-object, self-attribute or using a lazy-instantiation model (the latter being commonly used for efficient memory management and clean-up.)
+The design opts to define a deferred feature for specification of the event. As with all interface definitions should be free from all specific implementation and bindings to a particular declaration style, unless necessary of course. The implementation is now free to implement the event as a once, once-per-object, self-attribute, using a lazy-instantiation model (the latter being commonly used for efficient memory management and clean-up) or a façade to another interface.
 Finally, the <e>Result</e> type of the event feature is <e>EVENT_TYPE_I</e> and not the more specific implementation type <e>EVENT_TYPE</e>. As previously mentioned, the latter effective type contains means to publish the events, which should not be accessed by any client of the interface.

@@ Line 56: / Line 56: @@
 class
      INTERFACE_OBSERVER
 feature -- Event Handler
@@ Line 69: / Line 72: @@
 </e>
-The second step to supporting an interface's events is to provide access to a event connection point. A connection is the facade necessary to establish a connection with a set of interface events with a set of event handlers. There is a little trickery involved here and is a necessary evil in order to create a clean and versitle model for observers.
+==== Create an Observer Connection Point ====
-Again, there is a recommended rule to naming here. It is not recommended to simply call a connection access attribute/function <e>connection</e>. Multiple interfaces maybe implemented by the same class and as a result cause conflicts which have to be renamed. In such as case all connection point routines should be renamed for the sake of API consistency.
+A connection point is an attribute or a function, in the interface class, with a result type of <e>EVENT_CONNECTION_I</e>. <e>EVENT_CONNECTION_I</e> requires two formal generic parameter the former being the name of the observer class (<e>INTERFACE_OBSERVER</e>) and the latter the interface containing the events.
-{{Recommended|To pre-emptively avoid the clashing and to create APIs that are simplier to utilize and more consistent, name the connection point routine using the name of the interface suffix with <e>_connection</e>. Again, like the observer's class name, remove the <e>_I</e> (or <e>_S</e>) suffix from the class name. Of course, it goes without saying that the name should be in lower case.}}
+{{Warning|Do not use <e>like Current</e> when refering to the interface name in the formal generic parameter. This will only cause CAT-calls and headaches!}}
 <e>
@@ Line 83: / Line 89: @@
 feature -- Access
-     interface_connection: EVENT_CONNECTION_I [INTERFACE_OBSERVER, INTERFACE_I]
+     interface_connection: !EVENT_CONNECTION_I [INTERFACE_OBSERVER, INTERFACE_I]
              -- Connection point for {INTERFACE_I} events.
          require
              is_interface_usable: is_interface_usable
          local
              l_target: INTERFACE_OBSERVER
@@ Line 92: / Line 131: @@
                  -- Create the event-action bindings
              create l_target
-             create {EVENT_CONNECTION [INTERFACE_OBSERVER, INTERFACE_I]}
+             create Result.make_from_array (<<
-                Result.make_from_array (<<[changed_event, agent l_target.on_changed]>>)
+                [changed_event, agent l_target.on_changed]
          end
 ...
@@ Line 102: / Line 141: @@
 end
 </e>
 == Event Connections and Observers ==
 To Su

@@ Line 45: / Line 45: @@
 ==== Creating an Observer ====
-There are a number of guidelines when designing an observer for an interface's declared events, and just one requirement.
+There are a number of guidelines when designing an observer for an interface's declared events, and just one requirement:
-Observer names should contain the name of the interface it observers and suffixed with <e>_OBSERVER</e>. For the <e>INTERFACE_I</e>, drop the <e>_I</e> (or <e>_S</e> for services) interface declaration suffix and append the <e>_OBSERVER</e> suffix yielding <e>INTERFACE_OBSERVER</e>.
+{{Recommended|Observer names should contain the name of the interface it observers and suffixed with <e>_OBSERVER</e>. For the <e>INTERFACE_I</e>, drop the <e>_I</e> (or <e>_S</e> for services) interface declaration suffix and append the <e>_OBSERVER</e> suffix yielding <e>INTERFACE_OBSERVER</e>.
+<br/><br/>
-The second design guideline is in regards to naming the event handler routines, those called when an associated event is published.
+The second design guideline is in regards to naming the event handler routines, those called when an associated event is published. Like the class name, the event handling routine name should reflect an association with the event it's handling. Removing the <e>_event</e> suffix from the event feature and prefixing it with <e>on_</e> conveys the association with the event. For the <e>changed_event</e> the observer's event handler name would yield <e>on_changed</e>.
+<br/><br/>
-The requirement is the observer actually be a effective class, more on this later.
+The requirement is the observer actually be a effective class, more on this later. As the class has to be effective so do all event handler routines. Regardless of the deferred/effective status requirement of the observer class in the future, the event handler routines should always be effective. This removes the need to implement empty handler routines for a class implementing the observer. With a complete collection of effective handlers, the implementing class can redefine only what is needs to be notified of. Finally, the base event handler routines in the observer should '''not''' contain any implementation.}}
 <e>
@@ Line 68: / Line 68: @@
 end
 </e>
 <e>
@@ Line 73: / Line 79: @@
      INTERFACE_I
-inherit
+...
-    USABLE_I
 feature -- Access
@@ Line 85: / Line 90: @@
              l_target: INTERFACE_OBSERVER
          attribute
              create l_target
              create {EVENT_CONNECTION [INTERFACE_OBSERVER, INTERFACE_I]}
-                 Result.make_from_array (<<
+                 Result.make_from_array (<<[changed_event, agent l_target.on_changed]>>)
-                        -- Event-Action map
-                    [changed_event, agent l_target.on_changed]
-                >>)
          end
 feature -- Events
-    changed_event: !EVENT_TYPE_I [TUPLE [flags: INTEGER]]
+...
-            -- Events call when a change occurs
-        require
-            is_interface_usable: is_interface_usable
-        deferred
-        ensure
-            result_consistent: Result ~ changed_event
-            result_is_interface_usable: Result.is_interface_usable
-        end
 end