edu.umd.cs.piccolox.event
Class PNotificationCenter

java.lang.Object
  extended by 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 notfications center are held by weak references. So the notfication center will not create garbage collection problems as standard java event listeners do.

Author:
Jesse Grosjean

Nested Class Summary
protected static class PNotificationCenter.NotificationKey
           
protected static class PNotificationCenter.NotificationTarget
           
 
Field Summary
protected static PNotificationCenter DEFAULT_CENTER
           
protected  ReferenceQueue keyQueue
           
protected  HashMap listenersMap
           
static Object NULL_MARKER
           
 
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()
           
 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

DEFAULT_CENTER

protected static PNotificationCenter DEFAULT_CENTER

listenersMap

protected HashMap listenersMap

keyQueue

protected ReferenceQueue keyQueue
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)
                    throws SecurityException
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
Throws:
SecurityException - when attempting to register method as listener that is not accessible

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


Copyright © 1995-2011 Piccolo2D. All Rights Reserved.