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