libjava/java/awt/event/InvocationEvent.java

   1 /* InvocationEvent.java -- call a runnable when dispatched
   2    Copyright (C) 1999, 2002, 2004  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., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 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    * The timestamp when this event was created.
 111    *
 112    * @see #getWhen()
 113    * @serial the timestamp
 114    * @since 1.4
 115    */
 116   private final long when = EventQueue.getMostRecentEventTime();
 117
 118   /**
 119    * Initializes a new instance of <code>InvocationEvent</code> with the
 120    * specified source and runnable.
 121    *
 122    * @param source the source of the event
 123    * @param runnable the <code>Runnable</code> object to invoke
 124    * @throws IllegalArgumentException if source is null
 125    */
 126   public InvocationEvent(Object source, Runnable runnable)
 127   {
 128     this(source, INVOCATION_DEFAULT, runnable, null, false);
 129   }
 130
 131   /**
 132    * Initializes a new instance of <code>InvocationEvent</code> with the
 133    * specified source, runnable, and notifier.  It will also catch exceptions
 134    * if specified. If notifier is non-null, this will call notifyAll() on
 135    * the object when the runnable is complete. If catchExceptions is true,
 136    * this traps any exception in the runnable, otherwise it lets the exception
 137    * propagate up the Event Dispatch thread.
 138    *
 139    * @param source the source of the event
 140    * @param runnable the <code>Runnable</code> object to invoke
 141    * @param notifier the object to notify, or null
 142    * @param catchExceptions true to catch exceptions from the runnable
 143    */
 144   public InvocationEvent(Object source, Runnable runnable, Object notifier,
 145                          boolean catchExceptions)
 146   {
 147     this(source, INVOCATION_DEFAULT, runnable, notifier, catchExceptions);
 148   }
 149
 150   /**
 151    * Initializes a new instance of <code>InvocationEvent</code> with the
 152    * specified source, runnable, and notifier.  It will also catch exceptions
 153    * if specified. If notifier is non-null, this will call notifyAll() on
 154    * the object when the runnable is complete. If catchExceptions is true,
 155    * this traps any exception in the runnable, otherwise it lets the exception
 156    * propagate up the Event Dispatch thread. Note that an invalid id leads to
 157    * unspecified results.
 158    *
 159    * @param source the source of the event
 160    * @param id the event id
 161    * @param runnable the <code>Runnable</code> object to invoke
 162    * @param notifier the object to notify, or null
 163    * @param catchExceptions true to catch exceptions from the runnable
 164    */
 165   protected InvocationEvent(Object source, int id, Runnable runnable,
 166                             Object notifier, boolean catchExceptions)
 167   {
 168     super(source, id);
 169     this.runnable = runnable;
 170     this.notifier = notifier;
 171     this.catchExceptions = catchExceptions;
 172   }
 173
 174   /**
 175    * This method calls the <code>run()</code> method of the runnable, traps
 176    * exceptions if instructed to do so, and calls <code>notifyAll()</code>
 177    * on any notifier if all worked successfully.
 178    */
 179   public void dispatch()
 180   {
 181     if (catchExceptions)
 182       try
 183         {
 184           runnable.run();
 185         }
 186       catch (Exception e)
 187         {
 188           exception = e;
 189         }
 190     else
 191       runnable.run();
 192
 193     Object o = notifier;
 194     if (o != null)
 195       synchronized(o)
 196         {
 197           o.notifyAll();
 198         }
 199   }
 200
 201   /**
 202    * This method returns the exception that occurred during the execution of
 203    * the runnable, or <code>null</code> if not exception was thrown or
 204    * exceptions were not caught.
 205    *
 206    * @return the exception thrown by the runnable
 207    */
 208   public Exception getException()
 209   {
 210     return exception;
 211   }
 212
 213   /**
 214    * Gets the timestamp of when this event was created.
 215    *
 216    * @return the timestamp of this event
 217    * @since 1.4
 218    */
 219   public long getWhen()
 220   {
 221     return when;
 222   }
 223
 224   /**
 225    * This method returns a string identifying this event. This is formatted as:
 226    * <code>"INVOCATION_DEFAULT,runnable=" + runnable + ",notifier=" + notifier
 227    * + ",catchExceptions=" + catchExceptions + ",when=" + getWhen()</code>.
 228    *
 229    * @return a string identifying this event
 230    */
 231   public String paramString()
 232   {
 233     return (id == INVOCATION_DEFAULT ? "INVOCATION_DEFAULT,runnable="
 234             : "unknown type,runnable=") + runnable + ",notifier=" + notifier
 235       + ",catchExceptions=" + catchExceptions + ",when=" + when;
 236   }
 237 } // class InvocationEvent