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