WebObjects 5.2

com.webobjects.foundation
Class NSNotificationCenter

java.lang.Object
  |
  +--com.webobjects.foundation.NSNotificationCenter

public class NSNotificationCenter
extends Object

An NSNotificationCenter object (or simply, notification center) is essentially a notification dispatch table. It notifies all observers of notifications meeting specific criteria. This information is encapsulated in NSNotification objects, also known as notifications. Client objects register themselves as observers of specific notifications posted by other objects. When an event occurs, an object posts an appropriate notification to the notification center. The notification center dispatches a message to each registered observer, passing the notification as the sole argument. It is possible for the posting object and the observing object to be the same.

There is a single notification center instance which can be accessed with the defaultCenter static method.

There are two ways to register to receive notifications:

It is possible for an observer to register to receive more than one message for the same notification. In such a case, the observer will receive all messages it is registered to receive for the notification, but the order in which it receives them cannot be determined.

Note: If the default NSNotificationCenter is the last object in your application with a reference to either an object registered to receive notifications or an object being observed, that object will be garbage collected.

See Also:
NSNotification, defaultCenter(), addOmniscientObserver(Object observer, NSSelector sel), addObserver(Object observer, NSSelector sel, String name, Object object)

Constructor Summary
protected NSNotificationCenter()
          Standard no-arg constructor.
 
Method Summary
 void addObserver(Object observer, NSSelector sel, String name, Object object)
          Registers observer to receive notifications with the name name and/or containing object.
 void addOmniscientObserver(Object observer, NSSelector sel)
          Registers observer to receive all notifications from all objects.
static NSNotificationCenter defaultCenter()
          Return the single instance of NSNotificationCenter, which should be used for registering all notifications.
 void postNotification(NSNotification notification)
          Posts notification to the notification center.
 void postNotification(String notificationName, Object notificationObject)
          Creates a notification with the name notificationName, associates it with the object notificationObject, and posts it to the notification center.
 void postNotification(String notificationName, Object notificationObject, NSDictionary userInfo)
          Creates a notification with the name notificationName, associates it with the object notificationObject and dictionary userInfo, and posts it to the notification center.
 void removeObserver(Object observer)
          Removes observer as the observer of notifications from the notification center.
 void removeObserver(Object observer, String name, Object object)
          Removes observer as the observer of notifications with the name name and object object from the notification center.
 void removeOmniscientObserver(Object observer)
          Unregisters observer as an observer of all notifications.
 String toString()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

NSNotificationCenter

protected NSNotificationCenter()
Standard no-arg constructor. For use by subclasses only.
Method Detail

addObserver

public void addObserver(Object observer,
                        NSSelector sel,
                        String name,
                        Object object)
Registers observer to receive notifications with the name name and/or containing object. When a notification of name name containing the object object is posted, the method specified by sel is invoked on observer with the notification as the argument. object or name can be null, but not both.

object name Action
null null Do not invoke this method specifying null for both name and object. Instead, use addOmniscientObserver.
anObject notificationName The notification center notifies the observer of all notifications with the name notficationName and object anObject.
null notificationName The notification center notifies the observer of all notifications with the name notificationName.
anObject null The notification center notifies the observer of all notifications with an object matching anObject.

Parameters:
observer - object which will receive notifications
sel - method that will be invoked on observer as notification
name - notification name
object - notification object
See Also:
addOmniscientObserver(Object anObserver, NSSelector aSelector)

addOmniscientObserver

public void addOmniscientObserver(Object observer,
                                  NSSelector sel)
Registers observer to receive all notifications from all objects. When a notification is posted, the method specified by sel is invoked on observer with the notification as the argument.

Omniscient observers can significantly degrade performance and should be used with care.

Parameters:
observer - object which will receive notification
sel - NSSelector containing the method to be invoked when a notification is sent

defaultCenter

public static NSNotificationCenter defaultCenter()
Return the single instance of NSNotificationCenter, which should be used for registering all notifications.
Returns:
the NSNotificationCenter singleton

postNotification

public void postNotification(NSNotification notification)
Posts notification to the notification center. You can create notification with the NSNotification constructor.
Parameters:
notification - notification to be propagated

postNotification

public void postNotification(String notificationName,
                             Object notificationObject)
Creates a notification with the name notificationName, associates it with the object notificationObject, and posts it to the notification center. notificationObject is typically the object posting the notification. It may be null, or something else entirely.
Parameters:
notificationName - the notification name
notificationObject - notificationObject that will be associated with notificationName

postNotification

public void postNotification(String notificationName,
                             Object notificationObject,
                             NSDictionary userInfo)
Creates a notification with the name notificationName, associates it with the object notificationObject and dictionary userInfo, and posts it to the notification center.

This method is the preferred method for posting notifications. notificationObject is typically the object posting the notification. It may be null, or something else entirely. userInfo also may be null.

Parameters:
notificationName - the notification name
notificationObject - notificationObject that will be associated with notificationName
userInfo - user information dictionary

removeObserver

public void removeObserver(Object observer)
Removes observer as the observer of notifications from the notification center.

Parameters:
observer - observer of notifications
See Also:
removeObserver(Object observer, String name, Object object)

removeObserver

public void removeObserver(Object observer,
                           String name,
                           Object object)
Removes observer as the observer of notifications with the name name and object object from the notification center. This method interprets null parameters as wildcards:

observer name object Action
null name object Removes all observers of name containing object.
observer null object Removes observer as an observer of all notifications containing object.
observer name null Removes observer as an observer of name containing any object.
observer null null Removes all notifications containing observer.
null name null Removes all observers of name.
null null object Removes all observers of object.

Recall that the object a notification contains is usually, but not always, the object that posted the notification.

Parameters:
observer - object which will receive notification
name - notification name
object - notification object

removeOmniscientObserver

public void removeOmniscientObserver(Object observer)
Unregisters observer as an observer of all notifications.

Parameters:
observer - observer of all notifications

toString

public String toString()
Overrides:
toString in class Object

Last updated Fri Feb 21 13:15:00 PST 2003.

Copyright © 2003 Apple Computer, Inc.