EOObserverCenter

Inherits from: Object

Package: com.webobjects.eocontrol

Class Description

EOObserverCenter is the central player in EOControl's change tracking mechanism. EOObserverCenter records observers and the objects they observe, and it distributes notifications when the observable objects change. For an overview of the change tracking mechanism, see "Tracking Enterprise Objects Changes" (page 22) in the introduction to the EOControl Framework.

You don't ever create instances of EOObserverCenter. Instead, the class itself acts as the central manager of change notification, registering observers and notifying them of changes. The EOObserverCenter API is provided entirely in static methods.

EOObserverCenter is implemented using weak references (see the Sun documentation of java.lang.ref for details). Thus, if EOObserverCenter is the last object in your application with a reference to either an object which is registered to receive notifications, or to an object which is being observed, the object is garbage collected.

Registering an Observer

Objects that directly observe others must implement the EOObserving interface, which consists of the single method objectWillChange. To register an object as an observer, invoke EOObserverCenter's addObserver with the observer and the object to be observed. Once this is done, any time the observed object invokes its willChange method, the observer is sent an objectWillChange message informing it of the pending change. You can also register an observer to be notified when any object changes using addOmniscientObserver. This can be useful in certain situations, but as it's very costly to deal out frequent change notifications, you should use omniscient observers sparingly. To unregister either kind of observer, simply use the corresponding remove... method.

Change Notification

Objects that are about to change invoke willChange, a method defined by the EOEnterpriseObject interface. The implementations of this method invoke EOObserverCenter's notifyObserversObjectWillChange, which sends an objectWillChange message to all observers registered for the object that's changing, as well as to any omniscient observers. notifyObserversObjectWillChange optimizes the process by suppressing redundant objectWillChange messages when the same object invokes willChange several times in a row (as often happens when multiple properties are changed). Change notification is immediate, and takes place before the object's state changes. If you need to compare the object's state before and after the change, you must arrange to examine the new state at the end of the run loop.

You can suppress change notification when necessary, using the suppressObserverNotification and enableObserverNotification methods. While notification is suppressed, neither regular nor omniscient observers are informed of changes. These methods nest, so you can invoke suppressObserverNotification multiple times, and notification isn't re-enabled until a matching number of enableObserverNotification message have been sent.

Method Types

Registering and unregistering observersaddObserver removeObserver addOmniscientObserver removeOmniscientObserverNotifying observers of changenotifyObserversObjectWillChangeGetting observersobserversForObject observerForObjectSuppressing change notificationsuppressObserverNotification enableObserverNotification observerNotificationSuppressCount

Constructors

EOObserverCenter

public EOObserverCenter()

Description forthcoming.

Static Methods

addObserver

public static synchronized void addObserver( EOObserving anObserver, Object anObject)

Records anObserver to be notified with an objectWillChange message when anObject changes.

See Also: removeObserver

addOmniscientObserver

public static synchronized void addOmniscientObserver(EOObserving anObserver)

Records anObserver to be notified with an objectWillChange message when any object changes. This can cause significant performance degradation, and so should be used with care. The ominiscient observer must be prepared to receive the objectWillChange message with a null argument.

See Also: addObserver, removeOmniscientObserver

enableObserverNotification

public static void enableObserverNotification()

Counters a prior suppressObserverNotification message. When no such messages remain in effect, the notifyObserversObjectWillChange method is re-enabled. Throws an exception if not paired with a prior suppressObserverNotification message.

notifyObserversObjectWillChange

public synchronized void notifyObserversObjectWillChange(Object anObject)

Unless change notification is suppressed, sends an objectWillChange to all observers registered for anObject with that object as the argument, and sends that message to all omniscient observers as well. If invoked several times in a row with the same object, only the first invocation has any effect, since subsequent change notifications are redundant.

If an observer wants to ensure that it receives notification the next time the last object to change changes again, it should use the statement:








EOObserverCenter.notifyObserversObjectWillChange(null);

An observable object (typically an enterprise object) invokes this method from its willChange implementation, so you should never have to invoke this method directly.

observerForObject

public static synchronized EOObserving observerForObject( Object anObject, Class aClass)

Returns an observer for anObject that's a kind of aClass. If more than one observer of anObject is a kind of aClass, the specific observer returned is undetermined. You can use observersForObject instead to get all observers and examine their class membership.

observerNotificationSuppressCount

public static int observerNotificationSuppressCount()

Returns the number of suppressObserverNotification messages in effect.

See Also: enableObserverNotification

observersForObject

public static synchronized NSArray observersForObject(Object anObject)

Returns all observers of anObject.

removeObserver

public static synchronized void removeObserver( EOObserving anObserver, Object anObject)

Removes anObserver as an observer of anObject.

See Also: addObserver

removeOmniscientObserver

public static synchronized void removeOmniscientObserver(EOObserving anObserver)

Unregisters anObserver as an observer of all objects.

See Also: removeObserver, addOmniscientObserver

suppressObserverNotification

public static void suppressObserverNotification()

Disables the notifyObserversObjectWillChange method, so that no change notifications are sent. This method can be invoked multiple times; enableObserverNotification must then be invoked an equal number of times to re-enable change notification.