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

Basset documentation Contained in the Basset distribution.

Index

Code Index:

NAME

Top

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

AUTHOR

Top

Jim Thomason, jim@jimandkoka.com

DESCRIPTION

Top

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 need to put a types entry into your conf file for

 notificationcenter=Basset::NotificationCenter

(or whatever center you're using)

ATTRIBUTES

Top

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'
 );
loggers

loggers should be specified in the conf file. Similar spec to the 'types' entry.

 loggers %= error=/tmp/error.log
 loggers %= warnings=/tmp/warnings.log
 loggers %= info=/tmp/info.log

etc. Those conf file entries create loggers watching all objects for error, warnings, and info notifications, and the log files to which they write.

METHODS

Top

new

Basset::NotificationCenter is a singleton. Calling the constructor will return the single instance that can exist. All other methods may be called as either an object or a class method.

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

postNotification (say it with me, now) posts a notification. It expects 2-3 arguments.

 object			- required. The object posting the notification. May be a class.
 notification	- required. A string containing the notification being posted.
 args			- optional. Additional arguments in an arrayref to pass through to any observers.

The observer receives a hashref containing the args passed into postNotification.

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

addObserver (say it with me, now) adds an observer. It expects 3-4 arguments.

 observer		- required. The object observing the notification. May be a class.
 notification	- required. A string containing the notification to watch for.
 method			- required. The method to call when the notification is observed.
 object			- optional. If specified, then the observer will only watch for notifications posted by that object (or class).
 					otherwise, watches for all notifications of that type.
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.

removeAllObservers

Sometimes, though, it's easier to just nuke all the existing observers. The end of execution in a mod_perl process, for instance. You don't need to care what observers are still around or what they're doing. You just want them to go away. So you can remove them all.

 Basset::NotificationCenter->removeAllObservers();
Basset documentation Contained in the Basset distribution. 
package Basset::NotificationCenter;

#Basset::NotificationCenter, copyright and (c) 2004, 2005, 2006 James A Thomason III
#Basset::NotificationCenter is distributed under the terms of the Perl Artistic License.


$VERSION = '1.02';

use Scalar::Util qw(weaken isweak);

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

use strict;
use warnings;


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


__PACKAGE__->add_attr('observation');


__PACKAGE__->add_default_class_attr('loggers');


sub init {
	return shift->SUPER::init(
		'observers' => {},
		@_
	);
}


__PACKAGE__->add_class_attr('center');


sub new {
	my $class = shift;
	
	#bail out and do nothing if we can't access the singleton. That means we're trying to
	#notify very very early in the compilation process.
	#We don't generate an error, because we may end up in an infinite loop because error
	#tries to post a notification. Remember - this is -very- early in the compilation process
	#if this breaks.
	return unless $class->can('center');
	
	if (my $center = $class->center) {
		return $center;
	}
	
	$class->center($class->SUPER::new());

	my $loggers = $class->loggers;
	foreach my $note (keys %$loggers) {
		my $log = $loggers->{$note};

		my $l = Basset::Object->factory(
			'type'		=> 'logger',
			'handle'	=> $log
		);

		if (defined $l) {
			$class->center->addObserver(
				'notification'	=> $note,
				'observer'		=> $l,
				'method'		=> 'log'
			);
		}

	}
	
	return $class->center;
};


sub postNotification {

	my $self = shift;
	$self = ref $self ? $self : $self->new() or return;

	my %args = @_;

	return $self->error("Cannot post notification w/o object", "BN-07") unless defined $args{'object'};
	return $self->error("Cannot post notification w/o notification", "BN-08") unless defined $args{'notification'};
	
	$args{'args'} ||= [];
	
	my $observers = $self->observers();
	
	my $note = $observers->{$args{'notification'}};
	
	if (my $observableObjects = $observers->{$args{'notification'}}) {
		foreach my $object (keys %$observableObjects) {

			if (defined $object && $object eq $args{'object'} || $object eq 'all') {
				my $observers = $observableObjects->{$object};# || {};
				foreach my $observerKey (keys %$observers) {
					my $data = $observers->{$observerKey};
					my ($observer, $method) = @$data{qw(observer method)};
					$observer->$method(\%args);
				}
			}
		}
	};
	return 1;
}


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;
};


sub removeObserver {
	my $self = shift;
	$self = ref $self ? $self : $self->new() or return;
	
	my %init = @_;
	
	return $self->error("Cannot remove observer w/o observer", "BN-05") unless defined $init{'observer'};
	return $self->error("Cannot remove observer w/o notification", "BN-06") unless defined $init{'notification'};
	$init{'object'} ||= 'all';
	
	my $observers = $self->observers();
	
	delete $observers->{$init{'notification'}}->{$init{'object'}}->{$init{'observer'}};
	
	return 1;
	
};
	

sub removeAllObservers {
	my $self = shift;
	$self = ref $self ? $self : $self->new() or return;
	
	$self->observers({});
	
	return 1;
};

1;