view release on metacpan or  search on metacpan

lib/Basset/NotificationCenter.pm  view on Meta::CPAN

=pod

=head1 NAME

Basset::NotificationCenter - used to notify other objects of interesting things

=head1 AUTHOR

Jim Thomason, jim@jimandkoka.com

=head1 DESCRIPTION

This concept is stolen lock stock and barrel from Objective-C (Apple's cocoa frameworks, specifically). Basically, the notification
center is a high level object that sits off to the side. Objects can register with it to pay attention to interesting things
that other objects do, and they can then act upon the interesting things.

For example. Let's keep track of all times we see a weasel. First, we'll set up a logger (see Basset::Logger) to write to a log file.

 my $logger = Basset::Logger->new(
 	'handle' => '/tmp/weasels.log'
 );

Now, we register it as an observer

 Basset::NotificationCenter->addObserver(
  	'observer'		=> $logger,
 	'notification'	=> 'weasels',
 	'object'		=> 'all',
 	'method'		=> 'log'
 );

And we're done! Now we've registered our observer that will watch for "weasels" notifications posted by all objects, and when it
seems them, it will call its log method.

So when a notification is posted:

 Basset::NotificationCenter->postNotification(
 	'object'		=> $henhouse,
 	'notification'	=> 'weasels',
 	'args'			=> ["Weasels in the hen house!"]
 );

That will look for all observers registered to watch for 'weasels' notifications (our logger, in this case) and call their methods.
Again, for our example, internally the notification center fires off:

 $logger->log("Weasels in the hen house!");

Which logs the line of data to our /tmp/weasels.log file.

You will B<need> to put a types entry into your conf file for

 notificationcenter=Basset::NotificationCenter

(or whatever center you're using)

=cut

$VERSION = '1.02';

use Scalar::Util qw(weaken isweak);

use Basset::Object;
our @ISA = Basset::Object->pkg_for_type('object');

use strict;
use warnings;

=pod

=head1 ATTRIBUTES

=over

=cut

=pod

=begin btest observers

$test->ok(1, "testing is implied");

=end btest

=cut

# the observers list is handled internally. It keeps track of the registered observers.
__PACKAGE__->add_attr('observers');

=pod

=item observation

This is useful for debugging purposes. Set the notification center as an observer, and the
observation will contain the most recently postend notification.


 Basset::NotificationCenter->addObserver(
  	'observer'		=> Basset::NotificationCenter->new,
 	'notification'	=> "YOUR NOTIFICATION,
 	'object'		=> 'all',
 	'method'		=> 'observation'
 );

=cut

=pod

=begin btest observation

my $center = __PACKAGE__->new();
$test->ok($center, 'got default center');

$test->is($center->addObserver('method' => 'observation', 'observer' => $center, 'notification' => 'foo'), 1, 'Added center-as-observer for foo from all');

$test->is($center->postNotification('notification' => 'foo', 'object' => $center), 1, "Center posted foo notification");
my $note = $center->observation;
$test->is($note->{'object'}, $center, 'Notification object is center');
$test->is($note->{'notification'}, 'foo', 'Notification is foo');

$test->is($center->removeAllObservers(), 1, 'cleaned up and removed observers');

lib/Basset/NotificationCenter.pm  view on Meta::CPAN

$test->is($center->errcode, 'BN-01', 'proper error code');
$test->is(scalar($center->addObserver('method' => 'observation')), undef, 'Could not add observer w/o observer');
$test->is($center->errcode, 'BN-02', 'proper error code');
$test->is(scalar($center->addObserver('method' => 'observation', 'observer' => $o)), undef, 'Could not add observer w/o notification');
$test->is($center->errcode, 'BN-03', 'proper error code');
$test->is($center->addObserver('method' => 'observation', 'observer' => $o, 'notification' => 'foo'), 1, 'Added observer for foo from all');
$test->is($center->addObserver('method' => 'observation', 'observer' => $o, 'notification' => 'bar', 'object' => $o), 1, 'Added observer for bar from self');

my $args = [qw(a b c)];
$test->ok($args, "Got args");

$test->is($center->postNotification('notification' => 'foo', 'object' => $center, 'args' => $args), 1, "Center posted foo notification");
my $note = $o->observation;
$test->is($note->{'object'}, $center, 'Notification object is center');
$test->is($note->{'notification'}, 'foo', 'Notification is foo');
$test->is($note->{'args'}, $args, 'args are correct');

$test->is($center->postNotification('notification' => 'bar', 'object' => $center, 'args' => $args), 1, "Center posted bar notification");
$note = $o->observation;
$test->is($note->{'object'}, $center, 'Notification object is center (object ignores bar from center)');
$test->is($note->{'notification'}, 'foo', 'Notification is foo (object ignores bar from center)');
$test->is($note->{'args'}, $args, 'args are correct (object ignores bar from center)');

$test->is($center->postNotification('notification' => 'bar', 'object' => $o, 'args' => $args), 1, "o posted bar notification");
$note = $o->observation;
$test->is($note->{'object'}, $o, 'Notification object is o');
$test->is($note->{'notification'}, 'bar', 'Notification is bar');
$test->is($note->{'args'}, $args, 'args are correct');

$test->is($center->postNotification('notification' => 'bar', 'object' => $o), 1, "o posted bar notification w/no args");
$note = $o->observation;
$test->is($note->{'object'}, $o, 'Notification object is o');
$test->is($note->{'notification'}, 'bar', 'Notification is bar');
$test->is(scalar(@{$note->{'args'}}), 0, 'args are empty arrayref');

$test->is($center->removeAllObservers(), 1, 'cleaned up and removed observers');

=end btest

=cut

sub addObserver {
	my $self = shift;
	$self = ref $self ? $self : $self->new() or return;
	
	my %init = @_;
	
	return $self->error("Cannot add observer w/o method", "BN-01") unless defined $init{'method'};
	return $self->error("Cannot add observer w/o observer", "BN-02") unless defined $init{'observer'};
	return $self->error("Cannot add observer w/o notification", "BN-03") unless defined $init{'notification'};
	$init{'object'} ||= 'all';
	
	my $observers = $self->observers();
	
	$observers->{$init{'notification'}}->{$init{'object'}}->{$init{'observer'}} = \%init;
	
	#this is off for now, 'til I think of how to deal with the case of objects that exist
	#only in the notification center, such as loggers
	#
	#we don't want the notification center to keep observer objects around by mistake.
	#weaken($init{'observer'}) if ref $init{'observer'};
	
	return 1;
};

=pod

=item removeObserver

 Basset::NotificationCenter->removeObserver(
  	'observer'		=> $logger
 	'notification'	=> 'weasels',
 );

removeObserver (say it with me, now) removes an observer. It expects 2 arguments.

 observer		- required. The object observing the notification. May be a class.
 notification	- required. A string containing the notification to watch for.

Behave yourself and properly manage your memory. Remove observers when you're no longer using them. This is especially important
in a mod_perl environment.

=cut

=pod

=begin btest removeObserver

package Basset::Test::Testing::Basset::NotificationCenter::removeObserver;
our @ISA = qw(Basset::Object);

Basset::Test::Testing::Basset::NotificationCenter::removeObserver->add_attr('observation');

package __PACKAGE__;

my $o = Basset::Test::Testing::Basset::NotificationCenter::removeObserver->new();
$test->ok($o, "got object");

my $center = __PACKAGE__->new();
$test->ok($center, 'got default center');

$test->is($center->addObserver('method' => 'observation', 'observer' => $o, 'notification' => 'foo'), 1, 'Added observer for foo from all');
$test->is($center->addObserver('method' => 'observation', 'observer' => $o, 'notification' => 'bar', 'object' => $o), 1, 'Added observer for bar from self');

$test->is(scalar($center->removeObserver), undef, 'Could not remove observer w/o observer');
$test->is($center->errcode, 'BN-05', 'proper error code');
$test->is(scalar(__PACKAGE__->removeObserver), undef, 'Could not remove observer w/o observer through package');
$test->is($center->errcode, 'BN-05', 'proper error code');
$test->is(scalar($center->removeObserver('observer' => $o)), undef, 'Could not remove observer w/o notification');
$test->is($center->errcode, 'BN-06', 'proper error code');

$test->is($center->removeObserver('observer' => $o, 'notification' => 'foo'), 1, 'removed foo notification');
$test->is(scalar($o->observation(undef)), undef, 'wiped out any previous notifications');
$test->is($center->postNotification('notification' => 'foo', 'object' => $o), 1, "o posted foo notification");
my $note = $o->observation;
$test->is($note, undef, "No notification received");

$test->is($center->postNotification('notification' => 'bar', 'object' => $o), 1, "o posted bar notification w/no args");
$note = $o->observation;
$test->is($note->{'object'}, $o, 'Notification object is o');
$test->is($note->{'notification'}, 'bar', 'Notification is bar');