001/* InvocationEvent.java -- call a runnable when dispatched
002   Copyright (C) 1999, 2002, 2004, 2005  Free Software Foundation, Inc.
003
004This file is part of GNU Classpath.
005
006GNU Classpath is free software; you can redistribute it and/or modify
007it under the terms of the GNU General Public License as published by
008the Free Software Foundation; either version 2, or (at your option)
009any later version.
010
011GNU Classpath is distributed in the hope that it will be useful, but
012WITHOUT ANY WARRANTY; without even the implied warranty of
013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014General Public License for more details.
015
016You should have received a copy of the GNU General Public License
017along with GNU Classpath; see the file COPYING.  If not, write to the
018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
01902110-1301 USA.
020
021Linking this library statically or dynamically with other modules is
022making a combined work based on this library.  Thus, the terms and
023conditions of the GNU General Public License cover the whole
024combination.
025
026As a special exception, the copyright holders of this library give you
027permission to link this library with independent modules to produce an
028executable, regardless of the license terms of these independent
029modules, and to copy and distribute the resulting executable under
030terms of your choice, provided that you also meet, for each linked
031independent module, the terms and conditions of the license of that
032module.  An independent module is a module which is not derived from
033or based on this library.  If you modify this library, you may extend
034this exception to your version of the library, but you are not
035obligated to do so.  If you do not wish to do so, delete this
036exception statement from your version. */
037
038
039package java.awt.event;
040
041import java.awt.AWTEvent;
042import java.awt.ActiveEvent;
043import 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 */
059public 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