com.webobjects.eocontrol
Class EODelayedObserverQueue

java.lang.Object
  |
  +--com.webobjects.eocontrol.EODelayedObserverQueue

public class EODelayedObserverQueue

extends Object

The EODelayedObserverQueue class is a part of EOControl's change tracking mechanism. An EODelayedObserverQueue collects change notifications for observers of multiple objects and notifies them of the changes all at once during the application's run loop, according to their individual priorities.

EODelayedObserverQueue's style of notification is particularly useful for coalescing and prioritizing multiple changes. The EOInterface layer's EOAssociation subclasses use it extensively to update Java Client and Cocoa user interfaces, for example. Instead of being told that an object will change, an EODelayedObserver is told that it did change, with a subjectChanged message, as described in the EODelayedObserver class specification. Delayed observation is thus not useful for comparing old and new states, but only for examining the new state. Delayed observation also isn't ordinarily used outside the scope of a Java Client or Cocoa application.

The motivation for a delayed change notification mechanism arises mainly from issues in observing multiple objects. Any single change to an observed object typically requires the observer to update some state or perform an action. When many such objects change, it makes no sense to recalculate the new state and perform the action for each object. EODelayedObserverQueue allows these changes to be collected into a single notification. It further orders change notifications according to priorities, allowing observers to be updated in sequence according to dependencies among them. For example, an EOMasterDetailAssociation (in EOInterface), which must update its detail EODisplayGroup (in EOInterface) according to the selection in the master before any redisplay occurs, has an earlier priority than the default for EOAssociations. This prevents regular EOAssociations from redisplaying old values and then displaying the new values after the EOMasterDetailAssociation updates.

See EODelayedObserverQueueConcepts for more information.

See Also:

enqueueObserver(EODelayedObserver observer), defaultObserverQueue(), dequeueObserver(EODelayedObserver anObserver), EOObserving.objectWillChange(Object anObject), EOEnterpriseObject.willChange(), EODelayedObserver.observerQueue(), EODelayedObserver.discardPendingNotification(), EODelayedObserver.subjectChanged(), EOObserverCenter.addObserver(EOObserving observer , Object eo)

Field Summary

static int

FlushDelayedObserversRunLoopOrdering Used as a priority the first time enqueueObserver is invoked( if the observer doesn't have a priority ObserverPriorityImmediate) to register the receiver to be sent a notifyObserversUpToPriority message at the end of the run loop.

Constructor Summary

EODelayedObserverQueue()
Creates and returns a new EODelayedObserverQueue with NSRunLoop.DefaultRunLoopMode as its only run loop mode.

Method Summary

static EODelayedObserverQueue	defaultObserverQueue() Gets a default observer queue so it can be used to enqueue delay observers.
void	dequeueObserver(EODelayedObserver observer) Removes observer from the receiver.
void	enqueueObserver(EODelayedObserver observer) Records observer to be sent subjectChanged messages.
void	notifyObserversUpToPriority(int lastPriority) Sends subjectChanged messages to all of the receiver's enqueued observers whose priority is lastPriority or earlier.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

FlushDelayedObserversRunLoopOrdering

public static final int FlushDelayedObserversRunLoopOrdering

Used as a priority the first time enqueueObserver is invoked( if the observer doesn't have a priority ObserverPriorityImmediate) to register the receiver to be sent a notifyObserversUpToPriority message at the end of the run loop.

See Also:

enqueueObserver(EODelayedObserver)

Constructor Detail

EODelayedObserverQueue

public EODelayedObserverQueue()

Creates and returns a new EODelayedObserverQueue with NSRunLoop.DefaultRunLoopMode as its only run loop mode.

Method Detail

defaultObserverQueue

public static EODelayedObserverQueue defaultObserverQueue()

Gets a default observer queue so it can be used to enqueue delay observers.

Returns:

the EODelayedObserverQueue that EODelayedObservers use by default

dequeueObserver

public void dequeueObserver(EODelayedObserver observer)

Removes observer from the receiver.

Parameters:

observer - specifies an enqueued observer

See Also:

enqueueObserver(EODelayedObserver observer)

enqueueObserver

public void enqueueObserver(EODelayedObserver observer)

Records observer to be sent subjectChanged messages. If observer's priority is ObserverPriorityImmediate, it's immediately sent the message and not enqueued. Otherwise observer is sent the message the next time notifyObserversUpToPriority is invoked with a priority later than or equal to observer's. Does nothing if observer is already recorded.

The first time this method is invoked during the run loop with an observer whose priority isn't ObserverPriorityImmediate, it registers the receiver to be sent a notifyObserversUpToPriority message at the end of the run loop, using FlushDelayedObserversRunLoopOrdering and the receiver's run loop modes. This causes enqueued observers up to a priority of ObserverPrioritySixth to be notified automatically during each pass of the run loop.

When observer is done observing changes, it should invoke discardPendingNotification to remove itself from the queue.

Parameters:

observer - specifies observer to be sent to examine the receiver's observed objects

See Also:

dequeueObserver(EODelayedObserver anObserver), FlushDelayedObserversRunLoopOrdering, EODelayedObserver.priority(), EODelayedObserver.discardPendingNotification(), EODelayedObserver.subjectChanged(), notifyObserversUpToPriority(int priority)

notifyObserversUpToPriority

public void notifyObserversUpToPriority(int lastPriority)

Sends subjectChanged messages to all of the receiver's enqueued observers whose priority is lastPriority or earlier. This method cycles through the receiver's enqueued observers in priority order, sending each a subjectChanged message and then returning to the very beginning of the queue, in case another observer with an earlier priority was enqueued as a result of the message.

EODelayedObserverQueue invokes this method automatically as needed during the run loop, with a lastPriority of ObserverPrioritySixth.

Parameters:

lastPriority - specifies priority of the receiver's enqueued observers

See Also:

enqueueObserver(EODelayedObserver observer), EODelayedObserver.priority(), EODelayedObserver.subjectChanged()