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:

• If an object wishes to register itself to receive all notifications from all objects, it should invoke the addOmniscientObserver method specifying the method the notification should invoke on the observer
• Otherwise, an object should register itself to receive a notification by invoking the addObserver method, specifying the method the notification should invoke, and one or both of the name of the notification the observer wants to receive, and which object notifications it receives should contain. If the observer specifies only the object, it will receive all notifications containing that object. If the observer specifies only a notification name, it will receive that notification every time it's posted, regardless of the object associated with it. If both are specified, the observer will receive all of the notifications with that name and associated with the object

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