edu.umd.cs.piccolox.event
Class PNotificationCenter

java.lang.Object
  edu.umd.cs.piccolox.event.PNotificationCenter

public class PNotificationCenter
extends Object

PNotificationCenter provides a way for objects that don't know about each other to communicate. It receives PNotification objects and broadcasts them to all interested listeners. Unlike standard Java events, the event listeners don't need to know about the event source, and the event source doesn't need to maintain the list of listeners.

Listeners of the notifications center are held by weak references. So the notification center will not create garbage collection problems as standard java event listeners do.

Author:

Jesse Grosjean

Nested Class Summary

protected static class	PNotificationCenter.NotificationKey Represents a notification type from a particular object.
protected static class	PNotificationCenter.NotificationTarget A NotificationTarget is a method on a particular object that can be invoked.

Field Summary

protected static PNotificationCenter	DEFAULT_CENTER Singleton instance of the notification center.
protected ReferenceQueue	keyQueue A queue of NotificationKeys that are available to be garbage collected.
protected HashMap	listenersMap A map of listeners keyed by NotificationKey objects.
static Object	NULL_MARKER Used as a place holder for null names or objects.

Method Summary

boolean	addListener(Object listener, String callbackMethodName, String notificationName, Object object) Registers the 'listener' to receive notifications with the name 'notificationName' and/or containing 'object'.
static PNotificationCenter	defaultCenter() Singleton accessor for the PNotificationCenter.
protected List	matchingKeys(String name, Object object) Returns a list of keys with the given name and object.
void	postNotification(PNotification notification) Post the notification to this notification center.
void	postNotification(String notificationName, Object object) Post a new notification with notificationName and object.
void	postNotification(String notificationName, Object object, Map properties) Creates a notification with the name notificationName, associates it with the object, and posts it to this notification center.
protected void	processKeyQueue() Iterates over available keys in the key queue and removes the queue from the listener map.
void	removeListener(Object listener) Removes the listener so that it no longer receives notfications from this notification center.
protected void	removeListener(Object listener, Object key) Removes the given listener from receiving notifications with the given key.
void	removeListener(Object listener, String notificationName, Object object) Unregisters the listener as a listener for the specified kind of notification.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

NULL_MARKER

public static final Object NULL_MARKER

Used as a place holder for null names or objects.

DEFAULT_CENTER

protected static volatile PNotificationCenter DEFAULT_CENTER

Singleton instance of the notification center.

listenersMap

protected HashMap listenersMap

A map of listeners keyed by NotificationKey objects.

keyQueue

protected ReferenceQueue keyQueue

A queue of NotificationKeys that are available to be garbage collected.

Method Detail

defaultCenter

public static PNotificationCenter defaultCenter()

Singleton accessor for the PNotificationCenter.

Returns:

singleton instance of PNotificationCenter

addListener

public boolean addListener(Object listener,
                           String callbackMethodName,
                           String notificationName,
                           Object object)

Registers the 'listener' to receive notifications with the name 'notificationName' and/or containing 'object'. When a matching notification is posted the callBackMethodName message will be sent to the listener with a single PNotification argument. If notificationName is null then the listener will receive all notifications with an object matching 'object'. If 'object' is null the listener will receive all notifications with the name 'notificationName'.

Parameters:

listener - object to be notified of notifications

callbackMethodName - method to be invoked on the listener

notificationName - name of notifications to filter on

object - source of notification messages that this listener is interested in

Returns:

true if listener has been added

removeListener

public void removeListener(Object listener)

Removes the listener so that it no longer receives notfications from this notification center.

Parameters:

listener - listener to be removed from this notification center

removeListener

public void removeListener(Object listener,
                           String notificationName,
                           Object object)

Unregisters the listener as a listener for the specified kind of notification. If listener is null all listeners matching notificationName and object are removed. If notificationName is null the listener will be removed from all notifications containing the object. If the object is null then the listener will be removed from all notifications matching notficationName.

Parameters:

listener - listener to be removed

notificationName - name of notifications or null for all

object - notification source or null for all

postNotification

public void postNotification(String notificationName,
                             Object object)

Post a new notification with notificationName and object. The object is typically the object posting the notification. The object may be null.

Parameters:

notificationName - name of notification to post

object - source of the notification, null signifies unknown

postNotification

public void postNotification(String notificationName,
                             Object object,
                             Map properties)

Creates a notification with the name notificationName, associates it with the object, and posts it to this notification center. The object is typically the object posting the notification. It may be null.

Parameters:

notificationName - name of notification being posted

object - source of the notification, may be null

properties - properties associated with the notification

postNotification

public void postNotification(PNotification notification)

Post the notification to this notification center. Most often clients will instead use one of this classes convenience postNotifcations methods.

Parameters:

notification - notification to be dispatched to appropriate listeners

matchingKeys

protected List matchingKeys(String name,
                            Object object)

Returns a list of keys with the given name and object.

Parameters:

name - name of key

object - key associated with the object

Returns:

list of matching keys

removeListener

protected void removeListener(Object listener,
                              Object key)

Removes the given listener from receiving notifications with the given key.

Parameters:

listener - the listener being unregistered

key - the key that identifies the listener

processKeyQueue

protected void processKeyQueue()

Iterates over available keys in the key queue and removes the queue from the listener map.