001 /* InvocationEvent.java -- call a runnable when dispatched
002 Copyright (C) 1999, 2002, 2004, 2005 Free Software Foundation, Inc.
003
004 This file is part of GNU Classpath.
005
006 GNU Classpath is free software; you can redistribute it and/or modify
007 it under the terms of the GNU General Public License as published by
008 the Free Software Foundation; either version 2, or (at your option)
009 any later version.
010
011 GNU Classpath is distributed in the hope that it will be useful, but
012 WITHOUT ANY WARRANTY; without even the implied warranty of
013 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014 General Public License for more details.
015
016 You should have received a copy of the GNU General Public License
017 along with GNU Classpath; see the file COPYING. If not, write to the
018 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019 02110-1301 USA.
020
021 Linking this library statically or dynamically with other modules is
022 making a combined work based on this library. Thus, the terms and
023 conditions of the GNU General Public License cover the whole
024 combination.
025
026 As a special exception, the copyright holders of this library give you
027 permission to link this library with independent modules to produce an
028 executable, regardless of the license terms of these independent
029 modules, and to copy and distribute the resulting executable under
030 terms of your choice, provided that you also meet, for each linked
031 independent module, the terms and conditions of the license of that
032 module. An independent module is a module which is not derived from
033 or based on this library. If you modify this library, you may extend
034 this exception to your version of the library, but you are not
035 obligated to do so. If you do not wish to do so, delete this
036 exception statement from your version. */
037
038
039 package java.awt.event;
040
041 import java.awt.AWTEvent;
042 import java.awt.ActiveEvent;
043 import java.awt.EventQueue;
044
045 /**
046 * This event executes {@link Runnable#run()} of a target object when it is
047 * dispatched. This class is used by calls to <code>invokeLater</code> and
048 * <code>invokeAndWait</code>, so client code can use this fact to avoid
049 * writing special-casing AWTEventListener objects.
050 *
051 * @author Aaron M. Renn (arenn@urbanophile.com)
052 * @see ActiveEvent
053 * @see EventQueue#invokeLater(Runnable)
054 * @see EventQueue#invokeAndWait(Runnable)
055 * @see AWTEventListener
056 * @since 1.2
057 * @status updated to 1.4
058 */
059 public class InvocationEvent extends AWTEvent implements ActiveEvent
060 {
061 /**
062 * Compatible with JDK 1.2+.
063 */
064 private static final long serialVersionUID = 436056344909459450L;
065
066 /** This is the first id in the range of event ids used by this class. */
067 public static final int INVOCATION_FIRST = 1200;
068
069 /** This is the default id for this event type. */
070 public static final int INVOCATION_DEFAULT = 1200;
071
072 /** This is the last id in the range of event ids used by this class. */
073 public static final int INVOCATION_LAST = 1200;
074
075 /**
076 * This is the <code>Runnable</code> object to call when dispatched.
077 *
078 * @serial the runnable to execute
079 */
080 protected Runnable runnable;
081
082 /**
083 * This is the object to call <code>notifyAll()</code> on when
084 * the call to <code>run()</code> returns, or <code>null</code> if no
085 * object is to be notified.
086 *
087 * @serial the object to notify
088 */
089 protected Object notifier;
090
091 /**
092 * This variable is set to <code>true</code> if exceptions are caught
093 * and stored in a variable during the call to <code>run()</code>, otherwise
094 * exceptions are ignored and propagate up.
095 *
096 * @serial true to catch exceptions
097 */
098 protected boolean catchExceptions;
099
100 /**
101 * This is the caught exception thrown in the <code>run()</code> method. It
102 * is null if exceptions are ignored, the run method hasn't completed, or
103 * there were no exceptions.
104 *
105 * @serial the caught exception, if any
106 */
107 private Exception exception;
108
109 /**
110 * This is the caught Throwable thrown in the <code>run()</code> method.
111 * It is null if throwables are ignored, the run method hasn't completed,
112 * or there were no throwables thrown.
113 */
114 private Throwable throwable;
115
116 /**
117 * The timestamp when this event was created.
118 *
119 * @see #getWhen()
120 * @serial the timestamp
121 * @since 1.4
122 */
123 private final long when = EventQueue.getMostRecentEventTime();
124
125 /**
126 * Initializes a new instance of <code>InvocationEvent</code> with the
127 * specified source and runnable.
128 *
129 * @param source the source of the event
130 * @param runnable the <code>Runnable</code> object to invoke
131 * @throws IllegalArgumentException if source is null
132 */
133 public InvocationEvent(Object source, Runnable runnable)
134 {
135 this(source, INVOCATION_DEFAULT, runnable, null, false);
136 }
137
138 /**
139 * Initializes a new instance of <code>InvocationEvent</code> with the
140 * specified source, runnable, and notifier. It will also catch exceptions
141 * if specified. If notifier is non-null, this will call notifyAll() on
142 * the object when the runnable is complete. If catchExceptions is true,
143 * this traps any exception in the runnable, otherwise it lets the exception
144 * propagate up the Event Dispatch thread.
145 *
146 * @param source the source of the event
147 * @param runnable the <code>Runnable</code> object to invoke
148 * @param notifier the object to notify, or null
149 * @param catchExceptions true to catch exceptions from the runnable
150 */
151 public InvocationEvent(Object source, Runnable runnable, Object notifier,
152 boolean catchExceptions)
153 {
154 this(source, INVOCATION_DEFAULT, runnable, notifier, catchExceptions);
155 }
156
157 /**
158 * Initializes a new instance of <code>InvocationEvent</code> with the
159 * specified source, runnable, and notifier. It will also catch exceptions
160 * if specified. If notifier is non-null, this will call notifyAll() on
161 * the object when the runnable is complete. If catchExceptions is true,
162 * this traps any exception in the runnable, otherwise it lets the exception
163 * propagate up the Event Dispatch thread. Note that an invalid id leads to
164 * unspecified results.
165 *
166 * @param source the source of the event
167 * @param id the event id
168 * @param runnable the <code>Runnable</code> object to invoke
169 * @param notifier the object to notify, or null
170 * @param catchExceptions true to catch exceptions from the runnable
171 */
172 protected InvocationEvent(Object source, int id, Runnable runnable,
173 Object notifier, boolean catchExceptions)
174 {
175 super(source, id);
176 this.runnable = runnable;
177 this.notifier = notifier;
178 this.catchExceptions = catchExceptions;
179 }
180
181 /**
182 * This method calls the <code>run()</code> method of the runnable, traps
183 * exceptions if instructed to do so, and calls <code>notifyAll()</code>
184 * on any notifier if all worked successfully.
185 */
186 public void dispatch()
187 {
188 if (catchExceptions)
189 try
190 {
191 runnable.run();
192 }
193 catch (Throwable t)
194 {
195 throwable = t;
196 if (t instanceof Exception)
197 exception = (Exception)t;
198 }
199 else
200 runnable.run();
201
202 Object o = notifier;
203 if (o != null)
204 synchronized(o)
205 {
206 o.notifyAll();
207 }
208 }
209
210 /**
211 * This method returns the exception that occurred during the execution of
212 * the runnable, or <code>null</code> if not exception was thrown or
213 * exceptions were not caught.
214 *
215 * @return the exception thrown by the runnable
216 */
217 public Exception getException()
218 {
219 return exception;
220 }
221
222 /**
223 * Returns a throwable caught while executing the Runnable's run() method.
224 * Null if none was thrown or if this InvocationEvent doesn't catch
225 * throwables.
226 * @return the caught Throwable
227 * @since 1.5
228 */
229 public Throwable getThrowable()
230 {
231 return throwable;
232 }
233
234 /**
235 * Gets the timestamp of when this event was created.
236 *
237 * @return the timestamp of this event
238 * @since 1.4
239 */
240 public long getWhen()
241 {
242 return when;
243 }
244
245 /**
246 * This method returns a string identifying this event. This is formatted as:
247 * <code>"INVOCATION_DEFAULT,runnable=" + runnable + ",notifier=" + notifier
248 * + ",catchExceptions=" + catchExceptions + ",when=" + getWhen()</code>.
249 *
250 * @return a string identifying this event
251 */
252 public String paramString()
253 {
254 return (id == INVOCATION_DEFAULT ? "INVOCATION_DEFAULT,runnable="
255 : "unknown type,runnable=") + runnable + ",notifier=" + notifier
256 + ",catchExceptions=" + catchExceptions + ",when=" + when;
257 }
258 } // class InvocationEvent