001: /*
002: * @(#)InvocationEvent.java 1.23 06/10/19
003: *
004: * Copyright 1990-2006 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program 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 version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: *
026: */
027:
028: package java.awt.event;
029:
030: import java.awt.ActiveEvent;
031: import java.awt.AWTEvent;
032:
033: /**
034: * An event which executes the <code>run()</code> method on a <code>Runnable
035: * </code> when dispatched by the AWT event dispatcher thread. This class can
036: * be used as a implementation of <code>ActiveEvent</code> rather
037: * than declaring a new class and defining <code>dispatch()</code>.<p>
038: *
039: * Instances of this class are placed on the <code>EventQueue</code> by calls
040: * to <code>invokeLater</code> and <code>invokeAndWait</code>. Client code
041: * can use this fact to write replacement functions for <code>invokeLater
042: * </code> and <code>invokeAndWait</code> without writing special-case code
043: * in any <code>AWTEventListener</code> objects.
044: *
045: * @author Fred Ecks
046: * @author David Mendenhall
047: * @version 1.16, 08/19/02
048: *
049: * @see java.awt.ActiveEvent
050: * @see java.awt.EventQueue#invokeLater
051: * @see java.awt.EventQueue#invokeAndWait
052: * @see AWTEventListener
053: *
054: * @since 1.2
055: */
056: public class InvocationEvent extends AWTEvent implements ActiveEvent {
057: /**
058: * Marks the first integer id for the range of invocation event ids.
059: */
060: public static final int INVOCATION_FIRST = 1200;
061: /**
062: * The default id for all InvocationEvents.
063: */
064: public static final int INVOCATION_DEFAULT = INVOCATION_FIRST;
065: /**
066: * Marks the last integer id for the range of invocation event ids.
067: */
068: public static final int INVOCATION_LAST = INVOCATION_DEFAULT;
069: /**
070: * The Runnable whose run() method will be called.
071: */
072: protected Runnable runnable;
073: /**
074: * The (potentially null) Object whose notifyAll() method will be called
075: * immediately after the Runnable.run() method returns.
076: */
077: protected Object notifier;
078: /**
079: * Set to true if dispatch() catches Exception and stores it in the
080: * exception instance variable. If false, Exceptions are propagated up
081: * to the EventDispatchThread's dispatch loop.
082: */
083: protected boolean catchExceptions;
084: /**
085: * The (potentially null) Exception thrown during execution of the
086: * Runnable.run() method. This variable will also be null if a particular
087: * instance does not catch exceptions.
088: */
089: private Exception exception = null;
090:
091: private long when;
092:
093: /*
094: * JDK 1.1 serialVersionUID.
095: */
096: private static final long serialVersionUID = 436056344909459450L;
097:
098: /**
099: * Constructs an InvocationEvent with the specified source which will
100: * execute the runnable's <code>run()</code> method when dispatched.
101: *
102: * @param source the Object that originated the event
103: * @param runnable the Runnable whose run() method will be executed
104: */
105: public InvocationEvent(Object source, Runnable runnable) {
106: this (source, runnable, null, false);
107: }
108:
109: /**
110: * Constructs an InvocationEvent with the specified source which will
111: * execute the runnable's <code>run()</code> method when dispatched. If
112: * notifier is non-null, <code>notifyAll()</code> will be called on it
113: * immediately after <code>run()</code> returns.
114: *
115: * @param source the Object that originated the event
116: * @param runnable the Runnable whose run() method will be
117: * executed
118: * @param notifier the Object whose notifyAll() method will be
119: * called after Runnable.run() has returned
120: * @param catchExceptions specifies whether dispatch() should catch
121: * Exception when executing the Runnable's run()
122: * method, or should instead propagate those
123: * Exceptions to the EventDispatchThread's
124: * dispatch loop
125: */
126: public InvocationEvent(Object source, Runnable runnable,
127: Object notifier, boolean catchExceptions) {
128: this (source, INVOCATION_DEFAULT, runnable, notifier,
129: catchExceptions);
130: }
131:
132: /**
133: * Constructs an InvocationEvent with the specified source and ID which
134: * will execute the runnable's <code>run()</code> method when dispatched.
135: * If notifier is non-null, <code>notifyAll()</code> will be called on it
136: * immediately after <code>run()</code> returns.
137: *
138: * @param source the Object that originated the event
139: * @param id the ID for the Event
140: * @param runnable the Runnable whose run() method will be
141: * executed
142: * @param notifier the Object whose notifyAll() method will be
143: * called after Runnable.run() has returned
144: * @param catchExceptions specifies whether dispatch() should catch
145: * Exception when executing the Runnable's run()
146: * method, or should instead propagate those
147: * Exceptions to the EventDispatchThread's
148: * dispatch loop
149: */
150: protected InvocationEvent(Object source, int id, Runnable runnable,
151: Object notifier, boolean catchExceptions) {
152: super (source, id);
153: this .runnable = runnable;
154: this .notifier = notifier;
155: this .catchExceptions = catchExceptions;
156: this .when = System.currentTimeMillis();
157: }
158:
159: /**
160: * Executes the Runnable's <code>run()</code> method and notifies the
161: * notifier (if any) when <code>run()</code> returns.
162: */
163: public void dispatch() {
164: if (catchExceptions) {
165: try {
166: runnable.run();
167: } catch (Exception e) {
168: exception = e;
169: }
170: } else {
171: runnable.run();
172: }
173: if (notifier != null) {
174: synchronized (notifier) {
175: notifier.notifyAll();
176: }
177: }
178: }
179:
180: /**
181: * Returns any Exception caught while executing the Runnable's <code>run()
182: * </code> method.
183: *
184: * @return A reference to the Exception if one was thrown; null if no
185: * Exception was thrown or if this InvocationEvent does not
186: * catch exceptions
187: */
188: public Exception getException() {
189: return (catchExceptions) ? exception : null;
190: }
191:
192: public long getWhen() {
193: return when;
194: }
195:
196: /**
197: * Returns a parameter string identifying this event.
198: * This method is useful for event-logging and for debugging.
199: *
200: * @return A string identifying the event and its attributes
201: */
202: public String paramString() {
203: String typeStr;
204: switch (id) {
205: case INVOCATION_DEFAULT:
206: typeStr = "INVOCATION_DEFAULT";
207: break;
208:
209: default:
210: typeStr = "unknown type";
211: }
212: return typeStr + ",runnable=" + runnable + ",notifier="
213: + notifier + ",catchExceptions=" + catchExceptions
214: + ",when=" + when;
215: }
216: }
|