1 /* InvocationEvent.java -- call a runnable when dispatched 2 Copyright (C) 1999, 2002 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.ActiveEvent; 42 import java.awt.AWTEvent; 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 if (notifier != null) 193 notifier.notifyAll(); 194 } 195 196 /** 197 * This method returns the exception that occurred during the execution of 198 * the runnable, or <code>null</code> if not exception was thrown or 199 * exceptions were not caught. 200 * 201 * @return the exception thrown by the runnable 202 */ 203 public Exception getException() 204 { 205 return exception; 206 } 207 208 /** 209 * Gets the timestamp of when this event was created. 210 * 211 * @return the timestamp of this event 212 * @since 1.4 213 */ 214 public long getWhen() 215 { 216 return when; 217 } 218 219 /** 220 * This method returns a string identifying this event. This is formatted as: 221 * <code>"INVOCATION_DEFAULT,runnable=" + runnable + ",notifier=" + notifier 222 * + ",catchExceptions=" + catchExceptions + ",when=" + getWhen()</code>. 223 * 224 * @return a string identifying this event 225 */ 226 public String paramString() 227 { 228 return (id == INVOCATION_DEFAULT ? "INVOCATION_DEFAULT,runnable=" 229 : "unknown type,runnable=") + runnable + ",notifier=" + notifier 230 + ",catchExceptions=" + catchExceptions + ",when=" + when; 231 } 232 } // class InvocationEvent 233