NAME

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

AUTHOR

Jim Thomason, jim@jimandkoka.com

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

 notificationcenter=Basset::NotificationCenter

(or whatever center you're using)

ATTRIBUTES

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

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();