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:

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

    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