Note
	The following example uses features not covered yet (e.g. type inheritance and generic types). No need to worry if some details are not yet explained; they can be considered as a sneak preview of techniques explained in subsequent chapters.

Suppose we have a first-in-first-out stack of televisions to be delivered. A new television to be delivered can be added to the stack with a push command, and the least recently added television can be removed from the stack for delivery with a pop command.

First we have to define type television:

type television default_factory:yes
   attribute model type:string end
   attribute customer type:string end
   // other attributes omitted for brevity
end

Type television_stack can be written as:

type television_stack_1

   attribute is_empty type:yes_no kind:readonly_variable end

   command push
      in television type:television end
   end

   command pop
      in_check check: not i_object_.a_is_empty end

      out television type:television end
   end

end type

Now suppose that other objects or services want to be informed whenever a television is pushed or popped. For example, it might be necessary to log each action in a database, or to send an email whenever a television is removed from the stack for delivery. This can be done with events.

First we have to define two types for the two events, television_pushed and television_popped. We assume that both events hold the same simple data: the television that has been pushed or popped, and the time the event occurred. Hence, we first define a parent type that inherits from type object_event:

type television_pushed_or_popped_event

   inherit object_event end

   attribute television type:television end
   attribute time type:date_time end
end

	Note
	Type object_event in Obix's standard library is defined as: type object_event inherit event end end type And type event in Obix's standard library is defined as: type event attribute source type:any_type end // attribute time type:date_time voidable:yes end end type

The two event types can now be written using type inheritance again:

type television_pushed_event default_factory:yes
   inherit television_pushed_or_popped_event end
end

type television_popped_event default_factory:yes
   inherit television_pushed_or_popped_event end
end

Both events are generated from objects of type television_stack, so we have to declare that by adding two event declaration instructions at the end of type television_stack:

type television_stack

   attribute is_empty type:yes_no kind:readonly_variable end

   command push
      in television type:television end
   end

   command pop
      in_check check: not i_object_.a_is_empty end

      out television type:television end
   end
   
   event television_pushed type: television_pushed_event end
   event television_popped type: television_popped_event end

end type

What remains to be done for our event source is to write an implementation for type television_stack. A possible solution would be:

factory television_stack type: television_stack

   // this private attribute contains the list of all pending televisions in the stack
   attribute television_list type:!mutable_indexed_list<television> default: !mutable_indexed_list_factory<television>.co_create private:yes end

   attribute is_empty
      get
         script
            // simply return attribute 'a_is_empty' of private attribute 'a_television_list'
            o_is_empty = a_television_list.a_is_empty
         end
      end
   end

   command push
      script

         // append new television to the list of pending televisions
         a_television_list.co_append ( i_television )

         // generate a 'television_pushed' event
         generate event television_pushed from fa_television_pushed_event.co_create ( &
            source = this &
            television = i_television &
            time = se_date_time.a_current_date_time )
      end
   end

   command pop
      script

         // take least recently television from the list of pending televisions
         o_television = a_television_list.co_first_item
         a_television_list.co_remove_first

         // generate a 'television_popped' event
         generate event television_popped from fa_television_popped_event.co_create ( &
            source = this &
            television = o_television &
            time = se_date_time.a_current_date_time )
      end
   end

   creator create kind:in_all end

end factory

That's it for the event source. Let's now create an event listener. The following service listens to events in a television_stack object. To keep the example simple we will just display a message on the system console, each time an event is generated.

service television_stack_logger

   command start_logging
      in television_stack type: television_stack end
      script
         // register two event handlers for input argument 'television_stack'

         // each time a 'television_pushed' event is fired in 'i_television_stack', execute command 'new_pushed_event'
         on event television_pushed in i_television_stack execute script new_pushed_event

         // each time a 'television_popped' event is fired in 'i_television_stack', execute command 'new_popped_event'
         on event television_popped in i_television_stack execute script new_popped_event
      end
   end
   
   command_list private:yes // all following commands are private

      command new_pushed_event
         in event type: television_pushed_event end

         script
             co_log_event ( &
                television = i_event.a_television &
                action = "pushed" &
                time = i_event.a_time )
         end
       end

       command new_popped_event
          in event type: television_popped_event end

          script
             co_log_event ( &
                television = i_event.a_television &
                action = "popped" &
                time = i_event.a_time )
          end
       end

       command log_event
          in television type: television end
          in action type: string end
          in time type: date_time end

          script
             se_console.co_message ( "Television " & i_television.a_model & &
                " of customer " & i_television.a_customer & " has been " & i_action & &
                " on " & i_time.co_to_string )
          end
       end

   end command_list
end service

We are now ready to use our tiny application. Let's create a television_stack, ask service television_stack_logger to listen for events in television_stack, push and pop some televisions and see what is displayed on the system console:

service television_stack_test

   command test
      script
         // create a 'television_stack'
         var television_stack television_stack = fa_television_stack.co_create
         
         // ask 'se_television_stack_logger' to log events
         se_television_stack_logger.co_start_logging ( v_television_stack )
         
         // push a new television to be delivered
         v_television_stack.co_push ( fa_television.co_create ( &
              model = "Nice telli" &
              customer = "Nicolas Paganini" ) )
              
         // wait 5 seconds
         se_time.co_wait_seconds ( 5 )

         // push a second television
         v_television_stack.co_push ( fa_television.co_create ( &
              model = "ABC 123" &
              customer = "Wolfgang" ) )
              
         // wait 7 seconds
         se_time.co_wait_seconds ( 7 )
         
         // pop television
         var television popped_television = v_television_stack.co_pop
      end
   end
end

Executing the above command will display the following on the system console:

Television Nice telli of customer Nicolas Paganini has been pushed on Aug 10, 2007 1:39:22 PM
Television ABC 123 of customer Wolfgang has been pushed on Aug 10, 2007 1:39:27PM
Television Nice telli of customer Nicolas Paganini has been popped on Aug 10, 2007 1:39:34 PM

Note

It is of course legitimate to ask why the same result couldn't be achieved by simply displaying a message in commands push and pop of factory television_stack, instead of using events and writing the whole code to manage them. Well, the same result could indeed be achieved, but the very big advantage of using events is that responsibilities (e.g. the responsibility to log actions) can much better be modularized and distributed, which sustains separation of concerns, gives us much more flexibility at runtime, and results in code that is easier to maintain. For example, suppose that besides logging each push and pop action, we are required to send an email notification each time a new television is popped. In that case we can simply create another service which takes care of sending the emails. The great advantage is that we can do this without changing anything in the existing code. The email service would just be another listener to events in television_stack. Moreover, this new service could also be used to listen to other events in other objects and send appropriate emails. As a result, the whole job of sending emails throughout the whole application is assured by one single software component with a well defined responsibility. Thus, in case of any changes regarding email notification, only one software component needs to be adapted.