.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "UR::Observer 3pm"
.TH UR::Observer 3pm "2019-01-02" "perl v5.28.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
UR::Observer \- bind callbacks to object changes
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&    $rocket = Acme::Rocket\->create(
\&        fuel_level => 100
\&    );
\&    
\&    $observer = $rocket\->add_observer(
\&        aspect => \*(Aqfuel_level\*(Aq,
\&        callback => 
\&            sub {
\&                print "fuel level is: " . shift\->fuel_level . "\en"
\&            },
\&        priority => 2,
\&    );
\&
\&    $observer2 = UR::Observer\->create(
\&        subject_class_name => \*(AqAcme::Rocket\*(Aq,
\&        subject_id    => $rocket\->id,
\&        aspect => \*(Aqfuel_level\*(Aq,
\&        callback =>
\&            sub {
\&                my($self,$changed_aspect,$old_value,$new_value) = @_;
\&                if ($new_value == 0) {
\&                    print "Bail out!\en";
\&                }
\&            },
\&        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;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
UR::Observer implements the observer pattern for \s-1UR\s0 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.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
Observers can be created either by using the method \f(CW\*(C`add_observer()\*(C'\fR on
another class, or by calling \f(CW\*(C`create()\*(C'\fR on the UR::Observer class.
.PP
.Vb 3
\&  my $o1 = Some::Other::Class\->add_observer(...);
\&  my $o2 = $object_instance\->add_observer(...);
\&  my $o3 = UR::Observer\->create(...);
.Ve
.PP
The constructor accepts these parameters:
.IP "subject_class_name" 2
.IX Item "subject_class_name"
The name of the class the observer is watching.  If this observer is being
created via \f(CW\*(C`add_observer()\*(C'\fR, then it figures out the subject_class_name
from the class or object it is being called on.
.IP "subject_id" 2
.IX Item "subject_id"
The \s-1ID\s0 of the object the observer is watching.  If this observer is being
created via \f(CW\*(C`add_observer()\*(C'\fR, then it figures out the subject_id from the
object it was called on.  If \f(CW\*(C`add_observer()\*(C'\fR 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.
.IP "priority" 2
.IX Item "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.
.IP "aspect" 2
.IX Item "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.
.Sp
There are other, system-level aspects that can be watched for that correspond to other types
of state change:
.RS 2
.IP "create" 2
.IX Item "create"
After a new object instance is created
.IP "delete" 2
.IX Item "delete"
After an n object instance is deleted
.IP "load" 2
.IX Item "load"
After an object instance is loaded from its data source
.IP "commit" 2
.IX Item "commit"
After an object instance has changes saved to its data source
.RE
.RS 2
.RE
.IP "callback" 2
.IX Item "callback"
A coderef that is called after the observer's event happens.  The coderef is
passed four parameters: \f(CW$self\fR, \f(CW$aspect\fR, \f(CW$old_value\fR, \f(CW$new_value\fR.  In this case,
\&\f(CW$self\fR 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.
.IP "once" 2
.IX Item "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.
.IP "note" 2
.IX Item "note"
A text string that is ignored by the system
.SS "Custom aspects"
.IX Subsection "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.
.PP
.Vb 4
\&    class My::Class {
\&        has => [ \*(Aqprop_a\*(Aq, \*(Aqanother_prop\*(Aq ],
\&        valid_signals => [\*(Aqcustom\*(Aq, \*(Aqpow\*(Aq ],
\&    };
\&
\&    my $o = My::Class\->add_observer(
\&                aspect => \*(Aqpow\*(Aq,
\&                callback => sub { print "POW!\en" },
\&            );
\&    My::Class\->_\|_signal_observers_\|_(\*(Aqpow\*(Aq);  # POW!
\&
\&    my $obj = My::Class\->create(prop_a => 1);
\&    $obj\->_\|_signal_observers_\|_(\*(Aqcustom\*(Aq);  # not an error
.Ve
.PP
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 \f(CW\*(C`_\|_signal_observers()_\|_\*(C'\fR class or
object method.  Sending a signal for an aspect that no observers are watching
for is not an error.