diff options
Diffstat (limited to 'libjava/java/awt/event/InvocationEvent.java')
| -rw-r--r-- | libjava/java/awt/event/InvocationEvent.java | 254 |
1 files changed, 195 insertions, 59 deletions
diff --git a/libjava/java/awt/event/InvocationEvent.java b/libjava/java/awt/event/InvocationEvent.java index 6ee6300e7fc..fbf7b5e9379 100644 --- a/libjava/java/awt/event/InvocationEvent.java +++ b/libjava/java/awt/event/InvocationEvent.java @@ -1,96 +1,232 @@ -/* Copyright (C) 2000 Free Software Foundation +/* InvocationEvent.java -- call a runnable when dispatched + Copyright (C) 1999, 2002 Free Software Foundation, Inc. + +This file is part of GNU Classpath. + +GNU Classpath is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2, or (at your option) +any later version. + +GNU Classpath 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 +General Public License for more details. + +You should have received a copy of the GNU General Public License +along with GNU Classpath; see the file COPYING. If not, write to the +Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA +02111-1307 USA. + +Linking this library statically or dynamically with other modules is +making a combined work based on this library. Thus, the terms and +conditions of the GNU General Public License cover the whole +combination. + +As a special exception, the copyright holders of this library give you +permission to link this library with independent modules to produce an +executable, regardless of the license terms of these independent +modules, and to copy and distribute the resulting executable under +terms of your choice, provided that you also meet, for each linked +independent module, the terms and conditions of the license of that +module. An independent module is a module which is not derived from +or based on this library. If you modify this library, you may extend +this exception to your version of the library, but you are not +obligated to do so. If you do not wish to do so, delete this +exception statement from your version. */ - This file is part of libjava. - -This software is copyrighted work licensed under the terms of the -Libjava License. Please consult the file "LIBJAVA_LICENSE" for -details. */ package java.awt.event; -import java.awt.*; + +import java.awt.ActiveEvent; +import java.awt.AWTEvent; +import java.awt.EventQueue; /** - * @author Tom Tromey <tromey@cygnus.com> - * @date April 8, 2000 + * This event executes {@link Runnable#run()} of a target object when it is + * dispatched. This class is used by calls to <code>invokeLater</code> and + * <code>invokeAndWait</code>, so client code can use this fact to avoid + * writing special-casing AWTEventListener objects. + * + * @author Aaron M. Renn <arenn@urbanophile.com> + * @see ActiveEvent + * @see EventQueue#invokeLater(Runnable) + * @see EventQueue#invokeAndWait(Runnable) + * @see AWTEventListener + * @since 1.2 + * @status updated to 1.4 */ - -/* Status: Believed to be complete and correct. */ - public class InvocationEvent extends AWTEvent implements ActiveEvent { - public static final int INVOCATION_DEFAULT = 1200; + /** + * Compatible with JDK 1.2+. + */ + private static final long serialVersionUID = 436056344909459450L; + + /** This is the first id in the range of event ids used by this class. */ public static final int INVOCATION_FIRST = 1200; + + /** This is the default id for this event type. */ + public static final int INVOCATION_DEFAULT = 1200; + + /** This is the last id in the range of event ids used by this class. */ public static final int INVOCATION_LAST = 1200; - protected InvocationEvent (Object source, int id, Runnable runnable, - Object notifier, boolean catchExceptions) + /** + * This is the <code>Runnable</code> object to call when dispatched. + * + * @serial the runnable to execute + */ + protected Runnable runnable; + + /** + * This is the object to call <code>notifyAll()</code> on when + * the call to <code>run()</code> returns, or <code>null</code> if no + * object is to be notified. + * + * @serial the object to notify + */ + protected Object notifier; + + /** + * This variable is set to <code>true</code> if exceptions are caught + * and stored in a variable during the call to <code>run()</code>, otherwise + * exceptions are ignored and propagate up. + * + * @serial true to catch exceptions + */ + protected boolean catchExceptions; + + /** + * This is the caught exception thrown in the <code>run()</code> method. It + * is null if exceptions are ignored, the run method hasn't completed, or + * there were no exceptions. + * + * @serial the caught exception, if any + */ + private Exception exception; + + /** + * The timestamp when this event was created. + * + * @see #getWhen() + * @serial the timestamp + * @since 1.4 + */ + private final long when = EventQueue.getMostRecentEventTime(); + + /** + * Initializes a new instance of <code>InvocationEvent</code> with the + * specified source and runnable. + * + * @param source the source of the event + * @param runnable the <code>Runnable</code> object to invoke + * @throws IllegalArgumentException if source is null + */ + public InvocationEvent(Object source, Runnable runnable) { - super (source, id); - this.runnable = runnable; - this.notifier = notifier; - this.catchExceptions = catchExceptions; + this(source, INVOCATION_DEFAULT, runnable, null, false); } - public InvocationEvent (Object source, Runnable runnable) + /** + * Initializes a new instance of <code>InvocationEvent</code> with the + * specified source, runnable, and notifier. It will also catch exceptions + * if specified. If notifier is non-null, this will call notifyAll() on + * the object when the runnable is complete. If catchExceptions is true, + * this traps any exception in the runnable, otherwise it lets the exception + * propagate up the Event Dispatch thread. + * + * @param source the source of the event + * @param runnable the <code>Runnable</code> object to invoke + * @param notifier the object to notify, or null + * @param catchExceptions true to catch exceptions from the runnable + */ + public InvocationEvent(Object source, Runnable runnable, Object notifier, + boolean catchExceptions) { - super (source, INVOCATION_DEFAULT); - this.runnable = runnable; + this(source, INVOCATION_DEFAULT, runnable, notifier, catchExceptions); } - public InvocationEvent(Object source, Runnable runnable, Object notifier, - boolean catchExceptions) + /** + * Initializes a new instance of <code>InvocationEvent</code> with the + * specified source, runnable, and notifier. It will also catch exceptions + * if specified. If notifier is non-null, this will call notifyAll() on + * the object when the runnable is complete. If catchExceptions is true, + * this traps any exception in the runnable, otherwise it lets the exception + * propagate up the Event Dispatch thread. Note that an invalid id leads to + * unspecified results. + * + * @param source the source of the event + * @param id the event id + * @param runnable the <code>Runnable</code> object to invoke + * @param notifier the object to notify, or null + * @param catchExceptions true to catch exceptions from the runnable + */ + protected InvocationEvent(Object source, int id, Runnable runnable, + Object notifier, boolean catchExceptions) { - super (source, INVOCATION_DEFAULT); + super(source, id); this.runnable = runnable; this.notifier = notifier; this.catchExceptions = catchExceptions; } - public void dispatch () + /** + * This method calls the <code>run()</code> method of the runnable, traps + * exceptions if instructed to do so, and calls <code>notifyAll()</code> + * on any notifier if all worked successfully. + */ + public void dispatch() { - Exception e = null; if (catchExceptions) try - { - runnable.run (); - } - catch (Exception x) - { - exception = x; - } + { + runnable.run(); + } + catch (Exception e) + { + exception = e; + } else - runnable.run (); - + runnable.run(); if (notifier != null) - { - synchronized (notifier) - { - notifier.notifyAll (); - } - } + notifier.notifyAll(); } - public Exception getException () + /** + * This method returns the exception that occurred during the execution of + * the runnable, or <code>null</code> if not exception was thrown or + * exceptions were not caught. + * + * @return the exception thrown by the runnable + */ + public Exception getException() { return exception; } - public String paramString () + /** + * Gets the timestamp of when this event was created. + * + * @return the timestamp of this event + * @since 1.4 + */ + public long getWhen() { - String r; - if (id == INVOCATION_DEFAULT) - r = "INVOCATION_DEFAULT"; - else - r = "unknown type"; - - r += ",runnable=" + runnable + ",notifier=" + notifier + - ",catchExceptions=" + catchExceptions; - return r; + return when; } - protected boolean catchExceptions; - protected Object notifier; - protected Runnable runnable; - - private Exception exception; -} + /** + * This method returns a string identifying this event. This is formatted as: + * <code>"INVOCATION_DEFAULT,runnable=" + runnable + ",notifier=" + notifier + * + ",catchExceptions=" + catchExceptions + ",when=" + getWhen()</code>. + * + * @return a string identifying this event + */ + public String paramString() + { + return (id == INVOCATION_DEFAULT ? "INVOCATION_DEFAULT,runnable=" + : "unknown type,runnable=") + runnable + ",notifier=" + notifier + + ",catchExceptions=" + catchExceptions + ",when=" + when; + } +} // class InvocationEvent |
