old-autovect-branch/libjava/classpath/java/awt/event/InvocationEvent.java

   1 /* InvocationEvent.java -- call a runnable when dispatched
   2    Copyright (C) 1999, 2002, 2004, 2005  Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19 02110-1301 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38
  39 package java.awt.event;
  40
  41 import java.awt.AWTEvent;
  42 import java.awt.ActiveEvent;
  43 import java.awt.EventQueue;
  44
  45 /**
  46  * This event executes {@link Runnable#run()} of a target object when it is
  47  * dispatched. This class is used by calls to <code>invokeLater</code> and
  48  * <code>invokeAndWait</code>, so client code can use this fact to avoid
  49  * writing special-casing AWTEventListener objects.
  50  *
  51  * @author Aaron M. Renn (arenn@urbanophile.com)
  52  * @see ActiveEvent
  53  * @see EventQueue#invokeLater(Runnable)
  54  * @see EventQueue#invokeAndWait(Runnable)
  55  * @see AWTEventListener
  56  * @since 1.2
  57  * @status updated to 1.4
  58  */
  59 public class InvocationEvent extends AWTEvent implements ActiveEvent
  60 {
  61   /**
  62    * Compatible with JDK 1.2+.
  63    */
  64   private static final long serialVersionUID = 436056344909459450L;
  65
  66   /** This is the first id in the range of event ids used by this class. */
  67   public static final int INVOCATION_FIRST = 1200;
  68
  69   /** This is the default id for this event type. */
  70   public static final int INVOCATION_DEFAULT = 1200;
  71
  72   /** This is the last id in the range of event ids used by this class. */
  73   public static final int INVOCATION_LAST = 1200;
  74
  75   /**
  76    * This is the <code>Runnable</code> object to call when dispatched.
  77    *
  78    * @serial the runnable to execute
  79    */
  80   protected Runnable runnable;
  81
  82   /**
  83    * This is the object to call <code>notifyAll()</code> on when
  84    * the call to <code>run()</code> returns, or <code>null</code> if no
  85    * object is to be notified.
  86    *
  87    * @serial the object to notify
  88    */
  89   protected Object notifier;
  90
  91   /**
  92    * This variable is set to <code>true</code> if exceptions are caught
  93    * and stored in a variable during the call to <code>run()</code>, otherwise
  94    * exceptions are ignored and propagate up.
  95    *
  96    * @serial true to catch exceptions
  97    */
  98   protected boolean catchExceptions;
  99
 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