From cd9c15605821996a31f1ec9f32959286d2f1a6fb Mon Sep 17 00:00:00 2001
From: cvs2svn
Date: Sat, 3 Jun 2006 13:15:46 +0000
Subject: This commit was manufactured by cvs2svn to create branch
 'R3_2_maintenance'.

Sprout from master 2006-06-03 13:15:42 UTC DJ Houghton <dj> 'Released new about.html files.'
Delete:
    bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/framework/eventmgr/EventDispatcher.java
    bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/framework/eventmgr/EventListeners.java
    bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/framework/eventmgr/EventManager.java
    bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/framework/eventmgr/ListenerQueue.java---
 .../osgi/framework/eventmgr/EventDispatcher.java   |  49 ---
 .../osgi/framework/eventmgr/EventListeners.java    | 234 -------------
 .../osgi/framework/eventmgr/EventManager.java      | 368 ---------------------
 .../osgi/framework/eventmgr/ListenerQueue.java     | 144 --------
 4 files changed, 795 deletions(-)
 delete mode 100644 bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/framework/eventmgr/EventDispatcher.java
 delete mode 100644 bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/framework/eventmgr/EventListeners.java
 delete mode 100644 bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/framework/eventmgr/EventManager.java
 delete mode 100644 bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/framework/eventmgr/ListenerQueue.java

diff --git a/bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/framework/eventmgr/EventDispatcher.java b/bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/framework/eventmgr/EventDispatcher.java
deleted file mode 100644
index e858d05f1..000000000
--- a/bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/framework/eventmgr/EventDispatcher.java
+++ /dev/null
@@ -1,49 +0,0 @@
-/*******************************************************************************
- * Copyright (c) 2003, 2005 IBM Corporation and others.
- * All rights reserved. This program and the accompanying materials
- * are made available under the terms of the Eclipse Public License v1.0
- * which accompanies this distribution, and is available at
- * http://www.eclipse.org/legal/epl-v10.html
- *
- * Contributors:
- *     IBM Corporation - initial API and implementation
- *******************************************************************************/
-
-package org.eclipse.osgi.framework.eventmgr;
-
-/**
- * The EventDispatcher interface contains the method that is called by the
- * Event Manager to complete the event delivery to the event listener.
- * <p>
- * Clients may implement this interface.
- * </p>
- * @since 3.1
- */
-public interface EventDispatcher {
-	/**
-	 * This method is called once for each listener.
-	 * This method must cast the event listener object to the appropriate listener
-	 * class for the event type and call the appropriate listener method.
-	 * 
-	 * <p>The method should properly log/handle any exceptions thrown by the called
-	 * listener. The EventManager will ignore any Throwable thrown by this method
-	 * in order to continue delivery of the event to the next listener.
-	 *
-	 * @param eventListener This listener must be cast to the appropriate listener
-	 * class for the event to be delivered and the appropriate listener method
-	 * must then be called.
-	 * @param listenerObject This is the optional companion object that was 
-	 * specified when the listener was added to the EventListeners object.
-	 * @param eventAction This value was passed to the ListenerQueue object via one of its
-	 * dispatchEvent* method calls. It can provide information (such
-	 * as which listener method to call) so that the EventDispatcher
-	 * can complete the delivery of the event to the listener.
-	 * @param eventObject This object was passed to the ListenerQueue object via one of its
-	 * dispatchEvent* method calls. This object was created by the event source and
-	 * is passed to this method. It should contain all the necessary information (such
-	 * as what event object to pass) so that this method
-	 * can complete the delivery of the event to the listener.
-	 * This is typically the actual event object.
-	 */
-	public void dispatchEvent(Object eventListener, Object listenerObject, int eventAction, Object eventObject);
-}
diff --git a/bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/framework/eventmgr/EventListeners.java b/bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/framework/eventmgr/EventListeners.java
deleted file mode 100644
index 86c760b99..000000000
--- a/bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/framework/eventmgr/EventListeners.java
+++ /dev/null
@@ -1,234 +0,0 @@
-/*******************************************************************************
- * Copyright (c) 2003, 2005 IBM Corporation and others.
- * All rights reserved. This program and the accompanying materials
- * are made available under the terms of the Eclipse Public License v1.0
- * which accompanies this distribution, and is available at
- * http://www.eclipse.org/legal/epl-v10.html
- *
- * Contributors:
- *     IBM Corporation - initial API and implementation
- *******************************************************************************/
-
-package org.eclipse.osgi.framework.eventmgr;
-
-/**
- * This class manages a list of listeners.
- * Listeners may be added or removed as necessary.
- * @since 3.1
- */
-public class EventListeners {
-	/**
-	 * The empty array singleton instance, returned by getListeners()
-	 * when size == 0.
-	 */
-	private static final ListElement[] emptyArray = new ListElement[0];
-
-	/**
-	 * The initial capacity of the list. Always >= 1.
-	 */
-	private final int initialCapacity;
-
-	/**
-	 * The list of elements.  Initially <code>null</code> but initialized
-	 * to an array of size initialCapacity the first time an element is added.
-	 * Maintains invariants: 
-	 * 	list != null IFF size != 0
-	 * 	list[size] == null
-	 *  for all i < size: list[i] != null
-     * Access to this field must be protected by a synchronized region.
-	 */
-	private ListElement[] list = null;
-
-	/**
-	 * The current number of elements.
-	 * Maintains invariant: 0 <= size <= list.length.
-     * Access to this field must be protected by a synchronized region.
-	 */
-	private int size = 0;
-
-	/**
-	 * If true and about to modify the list,
-	 * then the list must be copied first.
-     * Access to this field must be protected by a synchronized region.
-	 */
-	private boolean copyOnWrite = false;
-
-	/**
-	 * Creates a listener list with an initial capacity of 10.
-	 *
-	 */
-	public EventListeners() {
-		this(10);
-	}
-
-	/**
-	 * Creates a listener list with the given initial capacity.
-	 *
-	 * @param capacity The number of listeners which this list can initially 
-	 *    accept without growing its internal representation; must be at
-	 *    least 1
-	 * @throws IllegalArgumentException If capacity is less than 1.
-	 */
-	public EventListeners(int capacity) {
-		if (capacity < 1)
-			throw new IllegalArgumentException();
-		this.initialCapacity = capacity;
-	}
-
-	/**
-	 * Add a listener to the list.
-	 * If a listener object is already in the list, then it is replaced.
-	 *
-	 * @param listener This is the listener object to be added to the list.
-	 * @param listenerObject This is an optional listener-specific object.
-	 * This object will be passed to the EventDispatcher along with the listener
-	 * when the listener is to be called. This may be null
-	 * @throws IllegalArgumentException If listener is null.
-	 */
-	public synchronized void addListener(Object listener, Object listenerObject) { 
-		if (listener == null) {
-			throw new IllegalArgumentException();
-		}
-
-		if (size == 0) {
-			list = new ListElement[initialCapacity];
-		} 
-		else {
-			// copy array if necessary
-			if (copyOnWrite) {
-				copyList(size);
-				copyOnWrite = false;
-			}
-
-			// check for duplicates using identity
-			for (int i = 0; i < size; i++) {
-				if (list[i].primary == listener) {
-					list[i] = new ListElement(listener, listenerObject); /* use the most recent companion */
-					return;
-				}
-			}
-
-			// grow array if necessary
-			// This wont recopy list if copy on write occured above since that
-			// would have grown the list.
-			if (size == list.length) {
-				copyList(size);
-			}
-		}
-
-		list[size] = new ListElement(listener, listenerObject);
-		size++;
-	}
-
-	/**
-	 * Remove a listener from the list.
-	 *
-	 * @param listener This is the listener object to be removed from the list.
-	 * @throws IllegalArgumentException If listener is null.
-	 */
-	public synchronized void removeListener(Object listener) {
-		if (listener == null) {
-			throw new IllegalArgumentException();
-		}
-
-		for (int i = 0; i < size; i++) {
-			if (list[i].primary == listener) {
-				size--;
-				if (size == 0) {
-					list = null; /* invariant: list must be null iff size is zero */
-					return;
-				}
-				if (copyOnWrite) {
-					copyList(i);
-					copyOnWrite = false;
-				}
-				else {
-					System.arraycopy(list, i + 1, list, i, size - i);
-					list[size] = null; /* invariant: end of list must be null */
-				}
-				return;
-			}
-		}
-	}
-
-	/**
-	 * Remove all listeners from the list.
-	 */
-	public synchronized void removeAllListeners() {
-		/* invariant: list must be null iff size is zero */
-		list = null;
-		size = 0;
-	}
-
-	/**
-	 * Return the list of (listener, listenerObject) pairs.
-	 * Package private method.
-	 * The array may be longer than the number of pairs in the array.
-	 * The end of the pairs is signalled by a null element or
-	 * end of array. 
-	 * This array must not be modified by anyone and should not be 
-	 * exposed outside of this package.
-	 * To reduce memory allocations, the internal array is shared
-	 * with the rest of this package. However an array returned by this method
-	 * must not be modified in anyway.
-	 * 
-	 * @return A shared array that must not be modified by anyone. 
-	 */
-	synchronized ListElement[] getListeners() {
-		if (size == 0) {
-			return emptyArray;
-		}
-		copyOnWrite = true;
-		return list;
-	}
-	
-	/**
-	 * Copy the array.
-	 * @param i Index of element to remove from array. Must be equal to size to 
-	 * copy entire array.
-	 * @throws IndexOutOfBoundsException If i < 0 or i > size.
-	 */
-	private void copyList(int i) {
-		if (i > size) {
-			throw new IndexOutOfBoundsException();
-		}
-		int capacity = (size * 3) / 2 + 1;
-		if (capacity < initialCapacity) {
-			capacity = initialCapacity;
-		}
-		ListElement[] newList = new ListElement[capacity];
-		System.arraycopy(list, 0, newList, 0, i);
-		if (i < size) {
-			System.arraycopy(list, i + 1, newList, i, size - i);
-		}
-		list = newList;
-	}
-
-	/**
-	 * ListElement is a package private class. This class
-	 * represents a primary object (e.g. listener) and its companion object.
-	 * ListElements are stored in EventListeners.
-	 * ListElements are immutable.
-	 */
-	static class ListElement {
-		/**
-		 * Primary object.
-		 */
-		final Object primary;
-
-		/**
-		 * Companion object.
-		 */
-		final Object companion;
-
-		/**
-		 * Constructor for ElementList element
-		 * @param primary Primary object in element. Used for uniqueness.
-		 * @param companion Companion object stored with primary object.
-		 */
-		ListElement(final Object primary, final Object companion) {
-			this.primary = primary;
-			this.companion = companion;
-		}
-	}
-}
diff --git a/bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/framework/eventmgr/EventManager.java b/bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/framework/eventmgr/EventManager.java
deleted file mode 100644
index 1788c56a8..000000000
--- a/bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/framework/eventmgr/EventManager.java
+++ /dev/null
@@ -1,368 +0,0 @@
-/*******************************************************************************
- * Copyright (c) 2003, 2005 IBM Corporation and others.
- * All rights reserved. This program and the accompanying materials
- * are made available under the terms of the Eclipse Public License v1.0
- * which accompanies this distribution, and is available at
- * http://www.eclipse.org/legal/epl-v10.html
- *
- * Contributors:
- *     IBM Corporation - initial API and implementation
- *******************************************************************************/
-
-package org.eclipse.osgi.framework.eventmgr;
-
-import org.eclipse.osgi.framework.eventmgr.EventListeners.ListElement;
-
-/**
- * This class is the central class for the Event Manager. Each
- * program that wishes to use the Event Manager should construct
- * an EventManager object and use that object to construct
- * ListenerQueue for dispatching events. EventListeners objects
- * should be used to manage listener lists.
- *
- * <p>This example uses the ficticous SomeEvent class and shows how to use this package 
- * to deliver a SomeEvent to a set of SomeEventListeners.  
- * <pre>
- *
- * 		// Create an EventManager with a name for an asynchronous event dispatch thread
- * 		EventManager eventManager = new EventManager("SomeEvent Async Event Dispatcher Thread");
- * 		// Create an EventListeners to hold the list of SomeEventListeners
- *		EventListeners eventListeners = new EventListeners();
- *
- *		// Add a SomeEventListener to the listener list
- *	    eventListeners.addListener(someEventListener, null);
- *
- *		// Asynchronously deliver a SomeEvent to registered SomeEventListeners
- *		// Create the listener queue for this event delivery
- *		ListenerQueue listenerQueue = new ListenerQueue(eventManager);
- *		// Add the listeners to the queue and associate them with the event dispatcher
- *		listenerQueue.queueListeners(eventListeners, new EventDispatcher() {
- *	        public void dispatchEvent(Object eventListener, Object listenerObject, 
- *                                    int eventAction, Object eventObject) {
- * 				try {
- *					(SomeEventListener)eventListener.someEventOccured((SomeEvent)eventObject);
- * 				} catch (Throwable t) {
- * 					// properly log/handle any Throwable thrown by the listener
- * 				}
- *			}
- *		});
- *		// Deliver the event to the listeners. 
- *		listenerQueue.dispatchEventAsynchronous(0, new SomeEvent());
- *		
- *		// Remove the listener from the listener list
- *	    eventListeners.removeListener(someEventListener);
- *
- *		// Close EventManager to clean when done to terminate async event dispatch thread
- *		eventManager.close();
- * </pre>
- * 
- * <p>At first glance, this package may seem more complicated than necessary
- * but it has support for some important features. The listener list supports
- * companion objects for each listener object. This is used by the OSGi framework
- * to create wrapper objects for a listener which are passed to the event dispatcher.
- * The ListenerQueue class is used to build a snap shot of the listeners prior to beginning
- * event dispatch. 
- * 
- * The OSGi framework uses a 2 level listener list (EventListeners) for each listener type (4 types). 
- * Level one is managed by the framework and contains the list of BundleContexts which have 
- * registered a listener. Level 2 is managed by each BundleContext for the listeners in that 
- * context. This allows all the listeners of a bundle to be easily and atomically removed from 
- * the level one list. To use a "flat" list for all bundles would require the list to know which 
- * bundle registered a listener object so that the list could be traversed when stopping a bundle 
- * to remove all the bundle's listeners. 
- * 
- * When an event is fired, a snapshot list (ListenerQueue) must be made of the current listeners before delivery 
- * is attempted. The snapshot list is necessary to allow the listener list to be modified while the 
- * event is being delivered to the snapshot list. The memory cost of the snapshot list is
- * low since the ListenerQueue object shares the array of listeners with the EventListeners object.
- * EventListeners uses copy-on-write semantics for managing the array and will copy the array
- * before changing it IF the array has been shared with a ListenerQueue. This minimizes 
- * object creation while guaranteeing the snapshot list is never modified once created.
- * 
- * The OSGi framework also uses a 2 level dispatch technique (EventDispatcher).
- * Level one dispatch is used by the framework to add the level 2 listener list of each 
- * BundleContext to the snapshot in preparation for delivery of the event.
- * Level 2 dispatch is used as the final event deliverer and must cast the listener 
- * and event objects to the proper type before calling the listener. Level 2 dispatch
- * will cancel delivery of an event 
- * to a bundle that has stopped bewteen the time the snapshot was created and the
- * attempt was made to deliver the event.
- * 
- * <p> The highly dynamic nature of the OSGi framework had necessitated these features for 
- * proper and efficient event delivery.  
- * @since 3.1
- */
-
-public class EventManager {
-	static final boolean DEBUG = false;
-
-	/**
-	 * EventThread for asynchronous dispatch of events.
-     * Access to this field must be protected by a synchronized region.
-	 */
-	private EventThread thread;
-
-	/**
-	 * EventThread Name
-	 */
-	protected final String threadName;
-
-	/**
-	 * EventManager constructor. An EventManager object is responsible for
-	 * the delivery of events to listeners via an EventDispatcher.
-	 *
-	 */
-	public EventManager() {
-		this(null);
-	}
-
-	/**
-	 * EventManager constructor. An EventManager object is responsible for
-	 * the delivery of events to listeners via an EventDispatcher.
-	 *
-	 * @param threadName The name to give the event thread associated with
-	 * this EventManager.
-	 */
-	public EventManager(String threadName) {
-		thread = null;
-		this.threadName = threadName;
-	}
-
-	/**
-	 * This method can be called to release any resources associated with this
-	 * EventManager.
-	 *
-	 */
-	public synchronized void close() {
-		if (thread != null) {
-			thread.close();
-			thread = null;
-		}
-	}
-
-	/**
-	 * Returns the EventThread to use for dispatching events asynchronously for
-	 * this EventManager.
-	 *
-	 * @return EventThread to use for dispatching events asynchronously for
-	 * this EventManager.
-	 */
-	synchronized EventThread getEventThread() {
-		if (thread == null) {
-			/* if there is no thread, then create a new one */
-			if (threadName == null) {
-				thread = new EventThread();
-			} 
-			else {
-				thread = new EventThread(threadName);
-			}
-			thread.start(); /* start the new thread */
-		}
-
-		return thread;
-	}
-
-	/**
-	 * This method calls the EventDispatcher object to complete the dispatch of
-	 * the event. If there are more elements in the list, call dispatchEvent
-	 * on the next item on the list.
-	 * This method is package private.
-	 *
-	 * @param listeners A null terminated array of ListElements with each element containing the primary and 
-	 * companion object for a listener. This array must not be modified.
-	 * @param dispatcher Call back object which is called to complete the delivery of
-	 * the event.
-	 * @param eventAction This value was passed by the event source and
-	 * is passed to this method. This is passed on to the call back object.
-	 * @param eventObject This object was created by the event source and
-	 * is passed to this method. This is passed on to the call back object.
-	 */
-	static void dispatchEvent(ListElement[] listeners, EventDispatcher dispatcher, int eventAction, Object eventObject) {
-		int size = listeners.length;
-		for (int i = 0; i < size; i++) { /* iterate over the list of listeners */
-			ListElement listener = listeners[i];
-			if (listener == null) {		/* a null element terminates the list */
-				break;
-			}
-			try {
-				/* Call the EventDispatcher to complete the delivery of the event. */
-				dispatcher.dispatchEvent(listener.primary, listener.companion, eventAction, eventObject);
-			} 
-			catch (Throwable t) {
-				/* Consume and ignore any exceptions thrown by the listener */
-				if (DEBUG) {
-					System.out.println("Exception in " + listener.primary); //$NON-NLS-1$
-					t.printStackTrace();
-				}
-			}
-		}
-	}
-
-	/**
-	 * This package private class is used for asynchronously dispatching events.
-	 */
-
-	static class EventThread extends Thread {
-		/**
-		 * Queued is a nested top-level (non-member) class. This class
-		 * represents the items which are placed on the asynch dispatch queue.
-		 * This class is private.
-		 */
-		private static class Queued {
-			/** listener list for this event */
-			final ListElement[] listeners;
-			/** dispatcher of this event */
-			final EventDispatcher dispatcher;
-			/** action for this event */
-			final int action;
-			/** object for this event */
-			final Object object;
-			/** next item in event queue */
-			Queued next;
-
-			/**
-			 * Constructor for event queue item
-			 *
-			 * @param l Listener list for this event
-			 * @param d Dispatcher for this event
-			 * @param a Action for this event
-			 * @param o Object for this event
-			 */
-			Queued(ListElement[] l, EventDispatcher d, int a, Object o) {
-				listeners = l;
-				dispatcher = d;
-				action = a;
-				object = o;
-				next = null;
-			}
-		}
-
-		/** item at the head of the event queue */
-		private Queued head;
-		/** item at the tail of the event queue */
-		private Queued tail;
-		/** if false the thread must terminate */
-		private volatile boolean running;
-
-		/**
-		 * Constructor for the event thread. 
-		 * @param threadName Name of the EventThread 
-		 */
-		EventThread(String threadName) {
-			super(threadName);
-			init();
-		}
-
-		/**
-		 * Constructor for the event thread.
-		 */
-		EventThread() {
-			super();
-			init();
-		}
-
-		private void init() {
-			running = true;
-			head = null;
-			tail = null;
-
-			setDaemon(true); /* Mark thread as daemon thread */
-		}
-
-		/**
-		 * Stop thread.
-		 */
-		void close() {
-			running = false;
-			interrupt();
-		}
-
-		/**
-		 * This method pulls events from
-		 * the queue and dispatches them.
-		 */
-		public void run() {
-			try {
-				while (true) {
-					Queued item = getNextEvent();
-					if (item == null) {
-						return;
-					}
-					EventManager.dispatchEvent(item.listeners, item.dispatcher, item.action, item.object);
-				}
-			}
-			catch (RuntimeException e) {
-				if (EventManager.DEBUG) {
-					e.printStackTrace();
-				}
-				throw e;
-			}
-			catch (Error e) {
-				if (EventManager.DEBUG) {
-					e.printStackTrace();
-				}
-				throw e;
-			}
-		}
-
-		/**
-		 * This methods takes the input parameters and creates a Queued
-		 * object and queues it.
-		 * The thread is notified.
-		 *
-		 * @param l Listener list for this event
-		 * @param d Dispatcher for this event
-		 * @param a Action for this event
-		 * @param o Object for this event
-		 */
-		synchronized void postEvent(ListElement[] l, EventDispatcher d, int a, Object o) {
-			if (!isAlive()) {	/* If the thread is not alive, throw an exception */
-				throw new IllegalStateException();
-			}
-			
-			Queued item = new Queued(l, d, a, o);
-
-			if (head == null) /* if the queue was empty */
-			{
-				head = item;
-				tail = item;
-			} else /* else add to end of queue */
-			{
-				tail.next = item;
-				tail = item;
-			}
-
-			notify();
-		}
-
-		/**
-		 * This method is called by the thread to remove
-		 * items from the queue so that they can be dispatched to their listeners.
-		 * If the queue is empty, the thread waits.
-		 *
-		 * @return The Queued removed from the top of the queue or null
-		 * if the thread has been requested to stop.
-		 */
-		private synchronized Queued getNextEvent() {
-			while (running && (head == null)) {
-				try {
-					wait();
-				} 
-				catch (InterruptedException e) {
-				}
-			}
-
-			if (!running) { /* if we are stopping */
-				return null;
-			}
-
-			Queued item = head;
-			head = item.next;
-			if (head == null) {
-				tail = null;
-			}
-
-			return item;
-		}
-	}
-}
diff --git a/bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/framework/eventmgr/ListenerQueue.java b/bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/framework/eventmgr/ListenerQueue.java
deleted file mode 100644
index ff6cabf33..000000000
--- a/bundles/org.eclipse.osgi/supplement/src/org/eclipse/osgi/framework/eventmgr/ListenerQueue.java
+++ /dev/null
@@ -1,144 +0,0 @@
-/*******************************************************************************
- * Copyright (c) 2003, 2005 IBM Corporation and others.
- * All rights reserved. This program and the accompanying materials
- * are made available under the terms of the Eclipse Public License v1.0
- * which accompanies this distribution, and is available at
- * http://www.eclipse.org/legal/epl-v10.html
- *
- * Contributors:
- *     IBM Corporation - initial API and implementation
- *******************************************************************************/
-
-package org.eclipse.osgi.framework.eventmgr;
-
-import java.util.ArrayList;
-import org.eclipse.osgi.framework.eventmgr.EventListeners.ListElement;
-import org.eclipse.osgi.framework.eventmgr.EventManager.EventThread;
-
-/**
- * The ListenerQueue is used to snapshot the set of listeners at the time the event
- * is fired. The snapshot list is then used to dispatch
- * events to those listeners. A ListenerQueue object is associated with a
- * specific EventManager object. ListenerQueue objects constructed with the same
- * EventManager object will get in-order delivery of events
- * using asynchronous delivery. No delivery order is guaranteed for synchronous
- * delivery to avoid any potential deadly embraces.
- *
- * <p>ListenerQueue objects are created as necesssary to build a set of listeners
- * that should receive a specific event or events. Once the set is created, the event
- * can then be synchronously or asynchronously delivered to the set of
- * listeners. After the event has been dispatched for delivery, the
- * ListenerQueue object should be discarded as it is likely the list of listeners is stale.
- * A new ListenerQueue object should be created when it is time to deliver 
- * another event.  The memory cost of a ListenerQueue object is
- * low since the ListenerQueue object shares the array of listeners with the EventListeners 
- * object which are queued.
- * EventListeners uses copy-on-write semantics for managing the array and will copy the array
- * before changing it once the array has been shared with a ListenerQueue. This minimizes 
- * object creation while guaranteeing the snapshot list is never modified once created.
- * @since 3.1
- */
-public class ListenerQueue {
-	/**
-	 * EventManager with which this queue is associated.
-	 */
-	protected final EventManager manager;
-	/**
-	 * A list of listener lists.
-	 */
-	private final ArrayList queue;
-
-	/**
-	 * Once the listener queue has been used to dispatch an event, 
-	 * you cannot add modify the queue.
-     * Access to this field must be protected by a synchronized region.
-	 */
-	private boolean readOnly;
-
-	/**
-	 * ListenerQueue constructor. This method creates an empty snapshop list.
-	 *
-	 * @param manager The EventManager this queue is associated with.
-	 * @throws IllegalArgumentException If manager is null.
-	 */
-	public ListenerQueue(EventManager manager) {
-		if (manager == null) {
-			throw new IllegalArgumentException();
-		}
-
-		this.manager = manager;
-		queue = new ArrayList();
-		readOnly = false;
-	}
-
-	/**
-	 * Add a listener list to the snapshot list. This method can be called multiple times, prior to
-	 * calling one of the dispatchEvent methods, to build the set of listeners for the
-	 * delivery of a specific event. The current list of listeners in the specified EventListeners
-	 * object is added to the snapshot list.
-	 *
-	 * @param listeners An EventListeners object to add to the queue. The current listeners
-	 * in the EventListeners object will be called when an event is dispatched.
-	 * @param dispatcher An EventDispatcher object to use when dispatching an event
-	 * to the listeners on the specified EventListeners.
-	 * @throws IllegalStateException If called after one of the dispatch methods has been called.
-	 */
-	public synchronized void queueListeners(EventListeners listeners, EventDispatcher dispatcher) {
-		if (readOnly) {
-			throw new IllegalStateException();
-		}
-
-		if (listeners != null) {
-			ListElement[] list = listeners.getListeners();
-
-			if (list.length > 0) {
-				queue.add(new EventListeners.ListElement(list, dispatcher));
-			}
-		}
-	}
-
-	/**
-	 * Asynchronously dispatch an event to the snapshot list. An event dispatch thread
-	 * maintained by the associated EventManager is used to deliver the events.
-	 * This method may return immediately to the caller.
-	 *
-	 * @param eventAction This value is passed to the EventDispatcher.
-	 * @param eventObject This object is passed to the EventDispatcher.
-	 */
-	public void dispatchEventAsynchronous(int eventAction, Object eventObject) {
-		synchronized (this) {
-			readOnly = true;
-		}
-		EventThread eventThread = manager.getEventThread();
-		synchronized (eventThread) { /* synchronize on the EventThread to ensure no interleaving of posting to the event thread */
-			int size = queue.size();
-			for (int i = 0; i < size; i++) { /* iterate over the list of listener lists */
-				ListElement list = (ListElement)queue.get(i);
-				eventThread.postEvent((ListElement[]) list.primary, (EventDispatcher) list.companion, eventAction, eventObject);
-			}
-		}
-	}
-
-	/**
-	 * Synchronously dispatch an event to the snapshot list. The event may
-	 * be dispatched on the current thread or an event dispatch thread
-	 * maintained by the associated EventManager.
-	 * This method will not return to the caller until the EventDispatcher
-	 * has been called (and has returned) for each listener on the queue.
-	 *
-	 * @param eventAction This value is passed to the EventDispatcher.
-	 * @param eventObject This object is passed to the EventDispatcher.
-	 */
-	public void dispatchEventSynchronous(int eventAction, Object eventObject) {
-		synchronized (this) {
-			readOnly = true;
-		}
-		// We can't guarantee any delivery order for synchronous events.
-		// Attempts to do so result in deadly embraces.
-		int size = queue.size();
-		for (int i = 0; i < size; i++) { /* iterate over the list of listener lists */
-			ListElement list = (ListElement)queue.get(i);
-			EventManager.dispatchEvent((ListElement[]) list.primary, (EventDispatcher) list.companion, eventAction, eventObject);
-		}
-	}
-}
-- 
cgit v1.2.3