NSNotificationCenter

Inherits from:
Object

Package:
com.webobjects.foundation

Class Description

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. (See the NSNotification class specification for more on notifications.) 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.

Each task has a default notification center that you access with the defaultCenter static method.

NSNotificationCenter is implemented using weak references (see Sun's documentation for java.lang.ref.* for details). Thus, 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, the object will be garbage collected.

Registering to Receive Notifications

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 send the addOmniscientObserver method, specifying the message the notification should send.

Otherwise, an object registers itself to receive a notification by sending the addObserver method, specifying the message the notification should send, the name of the notification it wants to receive, and about which object. However, the observer need not specify both the name and the object. If it specifies only the object, it will receive all notifications containing that object. If the object specifies only a notification name, it will receive that notification every time it's posted, regardless of the object associated with it.

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.

Method Types

Constructors

NSNotificationCenter

Accessing the default center

defaultCenter

Adding and removing observers

addObserver
addOmniscientObserver
removeObserver
removeOmniscientObserver

Posting notifications

postNotification

Constructors

NSNotificationCenter

protected NSNotificationCenter()

Standard no-arg constructor. For use by subclasses only.

Static Methods

defaultCenter

public static NSNotificationCenter defaultCenter()

Returns the current task's notification center, which is used for system notifications.

Instance Methods

addObserver

public synchronized void addObserver( Object anObserver, NSSelector aSelector, String notificationName, Object anObject)

Registers anObserver to receive notifications with the name notificationName and/or containing anObject. When a notification of name notificationName containing the object anObject is posted, anObserver receives an aSelector message with this notification as the argument. The method for the selector specified in aSelector must have one and only one argument. anObject or notificationName can be null, but not both:

anObject	notificationName	Action
`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.
`null`	null	Do not invoke this method specifying `null` for both notificationName and anObject. Instead, use addOmniscientObserver.

addOmniscientObserver

public synchronized void addOmniscientObserver( Object anObserver, NSSelector aSelector)

Registers anObserver to receive all notifications from all objects. When a notification is posted, anObserver receives an aSelector message with this notification as the argument. The method for the selector specified in aSelector must have exactly one argument. Omniscient observers can significantly degrade performance and should be used with care.

postNotification

public void postNotification( String notificationName, Object anObject, NSDictionary userInfo)

Creates a notification with the name notificationName, associates it with the object anObject and dictionary userInfo, and posts it to the notification center.

This method is the preferred method for posting notifications. anObject is typically the object posting the notification. It may be null. userInfo also may be null.

public void postNotification( String notificationName, Object anObject)

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

public void postNotification(NSNotification notification)

Posts notification to the notification center. You can create notification with the NSNotification constructor.

removeObserver

public void removeObserver(Object anObserver)

Same as removeObserver(anObserver, null, null).

public synchronized void removeObserver( Object anObserver, String notificationName, Object anObject)

Removes anObserver as the observer of notifications with the name notificationName and object anObject from the notification center. This method interprets null parameters as wildcards:

removeObserver Parameters	Action
`null`, notificationName, anObject	Removes all observers of notificationName containing anObject.
anObserver, `null`, anObject	Removes anObserver as an observer of all notifications containing anObject.
anObserver, notificationName, `null`	Removes anObserver as an observer of notificationName containing any object.
anObserver, `null`, `null`	Removes all notifications containing anObserver.
`null`, notificationName, `null`	Removes all observers of notificationName.
`null`, `null`, anObject	Removes all observers of anObject.

Recall that the object a notification contains is usually the object that posted the notification.

removeOmniscientObserver

public synchronized void removeOmniscientObserver(Object anObserver)

Unregisters anObserver as an observer of all notifications.

toString

public String toString()

Returns a String representation of the receiver.