NSNotification

Inherits from:
Object

Implements:
NSCoding
java.io.Serializable

Package:
com.webobjects.foundation

Class Description

NSNotification objects encapsulate information so that it can be broadcast to other objects by an NSNotificationCenter object.

Notifications and their Rationale

The standard way to pass information between objects is message passing-one object invokes the method of another object. However, message passing requires that the object sending the message know who the receiver is and what messages it responds to. At times, this tight coupling of two objects is undesirable-most notably because it would join together two otherwise independent subsystems. For these cases, a broadcast model is introduced: An object posts a notification, which is dispatched to the appropriate observers through an NSNotificationCenter object, or simply notification center.

An NSNotification object (referred to as a notification) contains a name, an object, and a dictionary. The name is a tag identifying the notification. The object is any object that the poster of the notification wants to send to observers of that notification (typically, it is the object that posted the notification). The dictionary stores other related objects if any.

Any object may post a notification. Other objects can register themselves as observers to receive notifications when they are posted. The object posting the notification, the object included in the notification, and the observer of the notification may all be different objects or the same object. Objects that post notifications need not know anything about the observers. On the other hand, observers need to know at least the notification name and keys to the dictionary if provided.

NSNotification objects are immutable objects.

Notification Centers

The notification center manages the sending and receiving of notifications. When an object wants to receive a certain notification, it registers itself with the notification center. When an object has a notification to send, it sends it to the notification center. When the notification center receives a notification, it passes that notification along to all objects registered to receive it. (See the NSNotificationCenter class specification for more on posting notifications.)

This notification model frees an object from concern about what objects it should send information to. Any object may simply post a notification without knowing what objects-if any-are receiving the notification. However, objects receiving notifications do need to know at least the notification name if not the type of information the notification contains. The notification center takes care of broadcasting notifications to registered observers. Another benefit of this model is to allow multiple objects to listen for notifications, which would otherwise be cumbersome.

You can create a notification object with the constructor. However, you don't usually create your own notifications directly. The NSNotificationCenter method postNotification allows you to conveniently post a notification without creating it first.

Notification and Delegation

Using the notification system is similar to using delegates, but it has these advantages:

Any number of objects may receive the notification, not just the delegate object. This precludes returning a value.
An object may receive any message you like from the notification center, not just the predefined delegate methods.
The object posting the notification does not even have to know the observer exists.

Creating Subclasses

You can subclass NSNotification to contain information in addition to the notification name, object, and dictionary. This extra data must be agreed upon between notifiers and observers.

Interfaces Implemented

NSCoding

classForCoder
encodeWithCoder

Method Types

Constructors

NSNotification

Obtaining information about a notification

name
object
userInfo

Methods inherited from Object

equals
hashCode
toString

Decoding the notification

decodeObject

Constructors

NSNotification

public NSNotification( String aName, Object anObject)

Creates a notification object that associates the name aName with the object anObject and contains an empty userInfo dictionary. The aName parameter may not be null.

public NSNotification( String aName, Object anObject, NSDictionary userInfo)

Returns a notification object that associates the name aName with the object anObject and the dictionary of arbitrary data userInfo. The dictionary userInfo may be null; if so, the new notification contains an empty userInfo dictionary. aName may not be null.

Static Methods

decodeObject

public static Object decodeObject(NSCoder coder)

Creates an NSNotification from the data in coder.

See Also: NSCoding

Instance Methods

classForCoder

public Class classForCoder()

Conformance with NSCoding. See the method description of classForCoder in the interface specification for NSCoding.

encodeWithCoder

public void encodeWithCoder(NSCoder aNSCoder)

Conformance with NSCoding. See the method description of encodeWithCoder in the interface specification for NSCoding.

equals

public boolean equals(Object anObject)

Compares the receiving NSNotification object to anObject. If anObject is an NSNotification and the contents of anObject are equal to the contents of the receiver, this method returns true. If not, it returns false. Two notifications are equal if their names, objects, and dictionaries are equal.

See Also: name, object, userInfo

hashCode

public int hashCode()

Provide an appropriate hash code useful for storing the receiver in a hash-based data structure.

name

public String name()

Returns the name of the notification. Examples of this might be "PortIsInvalid". Typically, you invoke this method on the notification object passed to your notification-handler method. (You specify a notification-handler method when you register to receive the notification.)

Notification names can be any string. To avoid name collisions, however, you might want to use a prefix that's specific to your application.

object

public Object object()

Returns the object associated with the notification. This is often the object that posted this notification. It may be null.

Typically, you invoke this method on the notification object passed in to your notification-handler method. (You specify a notification-handler method when you register to receive the notification.)

toString

public String toString()

Returns a string representation of the receiver including its name, object, and dictionary.

userInfo

public NSDictionary userInfo()

Returns the NSDictionary associated with the notification. The NSDictionary stores any additional objects that objects receiving the notification might use. For example a PortIsInvalid notification may provide the port number in the dictionary. The NSDictionary is empty if no userInfo dictionary was specified when the notification was created.