NAME

       UR::Observer - bind callbacks to object changes

SYNOPSIS

           $rocket = Acme::Rocket->create(
               fuel_level => 100
           );

           $observer = $rocket->add_observer(
               aspect => 'fuel_level',
               callback =>
                   sub {
                       print "fuel level is: " . shift->fuel_level . "\n"
                   },
               priority => 2,
           );

           $observer2 = UR::Observer->create(
               subject_class_name => 'Acme::Rocket',
               subject_id    => $rocket->id,
               aspect => 'fuel_level',
               callback =>
                   sub {
                       my($self,$changed_aspect,$old_value,$new_value) = @_;
                       if ($new_value == 0) {
                           print "Bail out!\n";
                       }
                   },
               priority => 0
           );

           for (3 .. 0) {
               $rocket->fuel_level($_);
           }
           # fuel level is: 3
           # fuel level is: 2
           # fuel level is: 1
           # Bail out!
           # fuel level is: 0

           $observer->delete;

DESCRIPTION

       UR::Observer implements the observer pattern for UR objects.  These observers can be attached to
       individual object instances, or to whole classes.  They can send notifications for changes to object
       attributes, or to other state changes such as when an object is loaded from its datasource or deleted.

CONSTRUCTOR

       Observers can be created either by using the method "add_observer()" on another class, or by calling
       "create()" on the UR::Observer class.

         my $o1 = Some::Other::Class->add_observer(...);
         my $o2 = $object_instance->add_observer(...);
         my $o3 = UR::Observer->create(...);

       The constructor accepts these parameters:

       subject_class_name
         The   name   of  the  class  the  observer  is  watching.   If  this  observer  is  being  created  via
         "add_observer()", then it figures out the subject_class_name from the  class  or  object  it  is  being
         called on.

       subject_id
         The ID of the object the observer is watching.  If this observer is being created via "add_observer()",
         then it figures out the subject_id from the object it was called on.  If "add_observer()" was called as
         a  class method, then subject_id is omitted, and means that the observer should fire for changes on any
         instance of the class or sub-class.

       priority
         A numeric value used to determine the  order  the  callbacks  are  fired.   Lower  numbers  are  higher
         priority,  and are run before callbacks with a numerically higher priority.  The default priority is 1.
         Negative numbers are ok.

       aspect
         The attribute the observer is watching for changes on.  The aspect is commonly one of the properties of
         the class.  In this case, the callback is fired after the property's  value  changes.   aspect  can  be
         omitted,  which  means the observer should fire for any change in the object state.  If both subject_id
         and aspect are omitted, then the observer will fire for any change to any instance of the class.

         There are other, system-level aspects that can be watched for that correspond to other types  of  state
         change:

         create
           After a new object instance is created

         delete
           After an n object instance is deleted

         load
           After an object instance is loaded from its data source

         commit
           After an object instance has changes saved to its data source

       callback
         A  coderef  that  is called after the observer's event happens.  The coderef is passed four parameters:
         $self, $aspect, $old_value, $new_value.  In this case, $self is the object that is  changing,  not  the
         UR::Observer  instance  (unless,  of course, you have created an observer on UR::Observer).  The return
         value of the callback is ignored.

       once
         If the 'once' attribute is true, the observer is deleted immediately after the callback is  run.   This
         has  the  effect  of running the callback only once, no matter how many times the observer condition is
         triggered.

       note
         A text string that is ignored by the system

   Custom aspects
       You can create an observer for an aspect that is neither a property nor one  of  the  system  aspects  by
       listing the aspect names in the metadata for the class.

           class My::Class {
               has => [ 'prop_a', 'another_prop' ],
               valid_signals => ['custom', 'pow' ],
           };

           my $o = My::Class->add_observer(
                       aspect => 'pow',
                       callback => sub { print "POW!\n" },
                   );
           My::Class->__signal_observers__('pow');  # POW!

           my $obj = My::Class->create(prop_a => 1);
           $obj->__signal_observers__('custom');  # not an error

       To  help catch typos, creating an observer for a non-standard aspect throws an exception unless the named
       aspect is in the list of 'valid_signals' in the class metadata.  Nothing in the system will trigger these
       observers, but they can be triggered in your own code using the "__signal_observers()__" class or  object
       method.  Sending a signal for an aspect that no observers are watching for is not an error.

perl v5.32.1                                       2022-01-17                                  UR::Observer(3pm)