/*
Wotonomy: OpenStep design patterns for pure Java applications.
Copyright (C) 2001 Intersect Software Corporation

This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with this library; if not, see http://www.gnu.org
*/

package net.wotonomy.foundation;

import java.util.Iterator;
import java.util.LinkedList;
import java.util.List;

/**
 * NSNotificationQueue coalesces notifications to be posted to the
 * NSNotificationCenter and can post them asynchronously. While calling
 * postNotification on the notification center does not return until all
 * receivers have been notified, calling enqueueNotification can return
 * immediately. Use this class when you want to coalesce notifications or notify
 * asynchronously, or both, which is the typical case.
 *
 * @author michael@mpowers.net
 * @author $Author: cgruber $
 * @version $Revision: 893 $
 */
public class NSNotificationQueue {
	private static NSNotificationQueue defaultQueue = null;

	/**
	 * Posting style specifying that the notification should be posted on the next
	 * available event loop.
	 */
	public static final int PostASAP = 4;

	/**
	 * Posting style specifying that the notification should be posted on the next
	 * available idle loop.
	 */
	public static final int PostWhenIdle = 8;

	/**
	 * Posting style specifying that the notification should be posted immediately.
	 * The enqueue method will not return until all receivers have been notified.
	 */
	public static final int PostNow = 16;

	/**
	 * Used to indicate that this notification should not be coalesced with other
	 * notifications. Ignored if combined with other coalesce flags.
	 */
	public static final int NotificationNoCoalescing = 0;

	/**
	 * Used to indicate that this notification should be coalesced with other
	 * notifications with the same name. May be combined with
	 * NotificationCoalescingOnSender.
	 */
	public static final int NotificationCoalescingOnName = 1;

	/**
	 * Used to indicate that this notification should be coalesced with other
	 * notifications with the same object argument (which is typically the sender).
	 * May be combined with NotificationCoalescingOnName.
	 */
	public static final int NotificationCoalescingOnSender = 2;

	/**
	 * The ASAP queue, which should probably use a LinkedList.
	 */
	private List queue;

	/**
	 * The idle queue, which should probably use a LinkedList.
	 */
	private List idleQueue;

	/**
	 * The notification center we will be using.
	 */
	private NSNotificationCenter center;

	/**
	 * Our private ASAP notifier.
	 */
	private Notifier notifier;

	/**
	 * Our private idle notifier.
	 */
	private Notifier idleNotifier;

	/**
	 * Default constructor creates a new notification queue that uses the default
	 * notification center.
	 */
	public NSNotificationQueue() {
		this(NSNotificationCenter.defaultCenter());
	}

	/**
	 * Creates a new notification queue that uses the specified notification center.
	 */
	public NSNotificationQueue(NSNotificationCenter aCenter) {
		queue = new LinkedList();
		idleQueue = new LinkedList();
		center = aCenter;
		notifier = new Notifier(this, queue);
		idleNotifier = new Notifier(this, idleQueue);
	}

	/**
	 * Returns the system default queue, creating one if it has not yet been
	 * created. The system default queue uses the system default notification
	 * center.
	 */
	static public NSNotificationQueue defaultQueue() {
		if (defaultQueue == null) {
			defaultQueue = new NSNotificationQueue();
		}
		return defaultQueue;
	}

	/**
	 * Removes notifications from the queue that match the specified notification,
	 * considering the specified coalesce mask.
	 */
	public void dequeueMatchingNotifications(NSNotification aNotification, int aCoalesceMask) {
		if (aCoalesceMask == NotificationNoCoalescing)
			return;
		dequeueFromQueue(aNotification, aCoalesceMask, queue);
		dequeueFromQueue(aNotification, aCoalesceMask, idleQueue);
	}

	private void dequeueFromQueue(NSNotification aNotification, int aCoalesceMask, List aQueue) {
		synchronized (aQueue) {
			int flag;
			NSNotification notification;
			Object name = aNotification.name();
			Object object = aNotification.object();
			Iterator it = aQueue.iterator();
			while (it.hasNext()) {
				flag = 0;
				notification = (NSNotification) it.next();
				// if NotificationCoalescingOnName
				if ((aCoalesceMask == 1) || (aCoalesceMask == 3)) {
					if (name == null) {
						if (notification.name() != null) {
							flag += NotificationCoalescingOnName;
						}
					} else {
						// compare by value
						if (name.equals(notification.name())) {
							flag += NotificationCoalescingOnName;
						}
					}
				}
				// if NotificationCoalescingOnSender
				if (aCoalesceMask >= 2) {
					// compare by reference
					if (object == notification.object()) {
						flag += NotificationCoalescingOnSender;
					}
				}

				if (flag == aCoalesceMask) {
					it.remove();
				}
			}
		}
	}

	/**
	 * Adds the notification to the queue to be run at the time specified by the
	 * posting style. The notification will be coalesced with other notifications
	 * that match the same name and object (sender) argument.
	 */
	public void enqueueNotification(NSNotification aNotification, int aPostingStyle) {
		enqueueNotificationWithCoalesceMaskForModes(aNotification, aPostingStyle,
				NotificationCoalescingOnName + NotificationCoalescingOnSender, null);
	}

	/**
	 * Adds the notification to the queue to be run at the time specified by the
	 * posting style and coelesced as the specified mask indicates. aModeList is
	 * currently ignored and may be null.
	 */
	public void enqueueNotificationWithCoalesceMaskForModes(NSNotification aNotification, int aPostingStyle,
			int aCoalesceMask, List aModeList) {
		dequeueMatchingNotifications(aNotification, aCoalesceMask);

		if (aPostingStyle == PostNow) {
			center.postNotification(aNotification);
			return;
		}

		if (aPostingStyle == PostASAP) {
			synchronized (queue) {
				queue.add(aNotification);
				if (!notifier.willRun) {
					// asap runs at the very first run loop ordering, plus one just in case
					NSRunLoop.invokeLaterWithOrder(notifier, 1);
					notifier.willRun = true;
				}
			}
			return;
		}

		if (aPostingStyle == PostWhenIdle) {
			synchronized (idleQueue) {
				idleQueue.add(aNotification);
				if (!idleNotifier.willRun) {
					// when idle runs at the very last run loop ordering, minus one just in case
					NSRunLoop.invokeLaterWithOrder(idleNotifier, Integer.MAX_VALUE - 1);
					idleNotifier.willRun = true;
				}
			}
			return;
		}

	}

	private class Notifier implements Runnable {
		public boolean willRun;

		NSNotificationQueue parent;
		List queue;

		public Notifier(NSNotificationQueue aParent, List aQueue) {
			willRun = false;
			parent = aParent;
			queue = aQueue;
		}

		public void run() {
			Iterator it = new LinkedList(queue).iterator();
			synchronized (queue) {
				queue.clear();
			}
			willRun = false;

			// queue must already be cleared and willRun reset
			// because this loop might queue more notifications
			while (it.hasNext()) {
				parent.center.postNotification((NSNotification) it.next());
			}
		}
	}

}

/*
 * $Log$ Revision 1.2 2006/02/16 13:15:00 cgruber Check in all sources in
 * eclipse-friendly maven-enabled packages.
 *
 * Revision 1.6 2003/08/11 18:18:08 chochos improved encoding of strings,
 * removed warnings
 *
 * Revision 1.5 2003/08/06 23:07:52 chochos general code cleanup (mostly,
 * removing unused imports)
 *
 * Revision 1.4 2001/11/01 15:49:26 mpowers With NSRunLoop, we can now correctly
 * implement PostASAP and PostWhenIdle.
 *
 * Revision 1.3 2001/06/25 14:47:24 mpowers Fixed serious error where some
 * notifications were not being posted at all. A simple change to Notifier class
 * fixed the problem. Thanks to glista.
 *
 * Revision 1.2 2001/02/26 15:53:22 mpowers Fine-tuning notification firing.
 * Child display groups now update properly after parent save or invalidate.
 *
 * Revision 1.1 2001/02/24 17:03:22 mpowers Implemented the notification queue,
 * and changed editing context to use it.
 *
 *
 */