run() method on a Runnable
* when dispatched by the AWT event dispatcher thread. This class can
* be used as a reference implementation of ActiveEvent rather
* than declaring a new class and defining dispatch().
*
* Instances of this class are placed on the EventQueue by calls
* to invokeLater and invokeAndWait. Client code
* can use this fact to write replacement functions for invokeLater
* and invokeAndWait without writing special-case code
* in any AWTEventListener objects.
*
* @author Fred Ecks
* @author David Mendenhall
* @version 1.18, 02/05/04
*
* @see java.awt.ActiveEvent
* @see java.awt.EventQueue#invokeLater
* @see java.awt.EventQueue#invokeAndWait
* @see AWTEventListener
*
* @since 1.2
*/
public class InvocationEvent extends AWTEvent implements ActiveEvent {
/**
* Marks the first integer id for the range of invocation event ids.
*/
public static final int INVOCATION_FIRST = 1200;
/**
* The default id for all InvocationEvents.
*/
public static final int INVOCATION_DEFAULT = INVOCATION_FIRST;
/**
* Marks the last integer id for the range of invocation event ids.
*/
public static final int INVOCATION_LAST = INVOCATION_DEFAULT;
/**
* The Runnable whose run() method will be called.
*/
protected Runnable runnable;
/**
* The (potentially null) Object whose notifyAll() method will be called
* immediately after the Runnable.run() method returns.
*/
protected Object notifier;
/**
* Set to true if dispatch() catches Throwable and stores it in the
* exception instance variable. If false, Throwables are propagated up
* to the EventDispatchThread's dispatch loop.
*/
protected boolean catchExceptions;
/**
* The (potentially null) Exception thrown during execution of the
* Runnable.run() method. This variable will also be null if a particular
* instance does not catch exceptions.
*/
private Exception exception = null;
/**
* The (potentially null) Throwable thrown during execution of the
* Runnable.run() method. This variable will also be null if a particular
* instance does not catch exceptions.
*/
private Throwable throwable = null;
/**
* The timestamp of when this event occurred.
*
* @serial
* @see #getWhen
*/
private long when;
/*
* JDK 1.1 serialVersionUID.
*/
private static final long serialVersionUID = 436056344909459450L;
/**
* Constructs an InvocationEvent with the specified
* source which will execute the runnable's run
* method when dispatched.
*
This is a convenience constructor. An invocation of the form * InvocationEvent(source, runnable) * behaves in exactly the same way as the invocation of * {@link #InvocationEvent(Object, Runnable, Object, boolean) InvocationEvent}(source, runnable, null, false). *
This method throws an IllegalArgumentException
* if source is null.
*
* @param source the Object that originated the event
* @param runnable the Runnable whose run
* method will be executed
* @throws IllegalArgumentException if source is null
*
* @see #InvocationEvent(Object, Runnable, Object, boolean)
*/
public InvocationEvent(Object source, Runnable runnable) {
this(source, runnable, null, false);
}
/**
* Constructs an InvocationEvent with the specified
* source which will execute the runnable's run
* method when dispatched. If notifier is non-null,
* notifyAll() will be called on it
* immediately after run returns.
*
An invocation of the form InvocationEvent(source, * runnable, notifier, catchThrowables) * behaves in exactly the same way as the invocation of * {@link #InvocationEvent(Object, int, Runnable, Object, boolean) InvocationEvent}(source, InvocationEvent.INVOCATION_DEFAULT, runnable, notifier, catchThrowables). *
This method throws an IllegalArgumentException
* if source is null.
*
* @param source the Object that originated
* the event
* @param runnable the Runnable whose
* run method will be
* executed
* @param notifier the Object whose notifyAll
* method will be called after
* Runnable.run has returned
* @param catchThrowables specifies whether dispatch
* should catch Throwable when executing
* the Runnable's run
* method, or should instead propagate those
* Throwables to the EventDispatchThread's
* dispatch loop
* @throws IllegalArgumentException if source is null
*
* @see #InvocationEvent(Object, int, Runnable, Object, boolean)
*/
public InvocationEvent(Object source, Runnable runnable, Object notifier,
boolean catchThrowables) {
this(source, INVOCATION_DEFAULT, runnable, notifier, catchThrowables);
}
/**
* Constructs an InvocationEvent with the specified
* source and ID which will execute the runnable's run
* method when dispatched. If notifier is non-null,
* notifyAll will be called on it
* immediately after run returns.
*
Note that passing in an invalid id results in
* unspecified behavior. This method throws an
* IllegalArgumentException if source
* is null.
*
* @param source the Object that originated
* the event
* @param id the ID for the event
* @param runnable the Runnable whose
* run method will be executed
* @param notifier the Object whose notifyAll
* method will be called after
* Runnable.run has returned
* @param catchThrowables specifies whether dispatch
* should catch Throwable when executing the
* Runnable's run
* method, or should instead propagate those
* Throwables to the EventDispatchThread's
* dispatch loop
* @throws IllegalArgumentException if source is null
*/
protected InvocationEvent(Object source, int id, Runnable runnable,
Object notifier, boolean catchThrowables) {
super(source, id);
this.runnable = runnable;
this.notifier = notifier;
this.catchExceptions = catchThrowables;
this.when = System.currentTimeMillis();
}
/**
* Executes the Runnable's run() method and notifies the
* notifier (if any) when run() returns.
*/
public void dispatch() {
if (catchExceptions) {
try {
runnable.run();
}
catch (Throwable t) {
if (t instanceof Exception) {
exception = (Exception) t;
}
throwable = t;
}
}
else {
runnable.run();
}
if (notifier != null) {
synchronized (notifier) {
notifier.notifyAll();
}
}
}
/**
* Returns any Exception caught while executing the Runnable's run()
* method.
*
* @return A reference to the Exception if one was thrown; null if no
* Exception was thrown or if this InvocationEvent does not
* catch exceptions
*/
public Exception getException() {
return (catchExceptions) ? exception : null;
}
/**
* Returns any Throwable caught while executing the Runnable's run()
* method.
*
* @return A reference to the Throwable if one was thrown; null if no
* Throwable was thrown or if this InvocationEvent does not
* catch Throwables
*/
public Throwable getThrowable() {
return (catchExceptions) ? throwable : null;
}
/**
* Returns the timestamp of when this event occurred.
*
* @return this event's timestamp
* @since 1.4
*/
public long getWhen() {
return when;
}
/**
* Returns a parameter string identifying this event.
* This method is useful for event-logging and for debugging.
*
* @return A string identifying the event and its attributes
*/
public String paramString() {
String typeStr;
switch(id) {
case INVOCATION_DEFAULT:
typeStr = "INVOCATION_DEFAULT";
break;
default:
typeStr = "unknown type";
}
return typeStr + ",runnable=" + runnable + ",notifier=" + notifier +
",catchExceptions=" + catchExceptions + ",when=" + when;
}
}