java.awt.event
Class InvocationEvent

java.lang.Object
  extended by java.util.EventObject
      extended by java.awt.AWTEvent
          extended by java.awt.event.InvocationEvent
All Implemented Interfaces:
ActiveEvent, Serializable

public class InvocationEvent
extends AWTEvent
implements ActiveEvent

This event executes Runnable.run() of a target object when it is dispatched. This class is used by calls to invokeLater and invokeAndWait, so client code can use this fact to avoid writing special-casing AWTEventListener objects.

Since:
1.2
See Also:
ActiveEvent, EventQueue.invokeLater(Runnable), EventQueue.invokeAndWait(Runnable), AWTEventListener, Serialized Form

Field Summary
protected  boolean catchExceptions
          This variable is set to true if exceptions are caught and stored in a variable during the call to run(), otherwise exceptions are ignored and propagate up.
static int INVOCATION_DEFAULT
          This is the default id for this event type.
static int INVOCATION_FIRST
          This is the first id in the range of event ids used by this class.
static int INVOCATION_LAST
          This is the last id in the range of event ids used by this class.
protected  Object notifier
          This is the object to call notifyAll() on when the call to run() returns, or null if no object is to be notified.
protected  Runnable runnable
          This is the Runnable object to call when dispatched.
 
Fields inherited from class java.awt.AWTEvent
ACTION_EVENT_MASK, ADJUSTMENT_EVENT_MASK, COMPONENT_EVENT_MASK, consumed, CONTAINER_EVENT_MASK, FOCUS_EVENT_MASK, HIERARCHY_BOUNDS_EVENT_MASK, HIERARCHY_EVENT_MASK, id, INPUT_METHOD_EVENT_MASK, INVOCATION_EVENT_MASK, ITEM_EVENT_MASK, KEY_EVENT_MASK, MOUSE_EVENT_MASK, MOUSE_MOTION_EVENT_MASK, MOUSE_WHEEL_EVENT_MASK, PAINT_EVENT_MASK, RESERVED_ID_MAX, TEXT_EVENT_MASK, WINDOW_EVENT_MASK, WINDOW_FOCUS_EVENT_MASK, WINDOW_STATE_EVENT_MASK
 
Fields inherited from class java.util.EventObject
source
 
Constructor Summary
protected InvocationEvent(Object source, int id, Runnable runnable, Object notifier, boolean catchExceptions)
          Initializes a new instance of InvocationEvent with the specified source, runnable, and notifier.
  InvocationEvent(Object source, Runnable runnable)
          Initializes a new instance of InvocationEvent with the specified source and runnable.
  InvocationEvent(Object source, Runnable runnable, Object notifier, boolean catchExceptions)
          Initializes a new instance of InvocationEvent with the specified source, runnable, and notifier.
 
Method Summary
 void dispatch()
          This method calls the run() method of the runnable, traps exceptions if instructed to do so, and calls notifyAll() on any notifier if all worked successfully.
 Exception getException()
          This method returns the exception that occurred during the execution of the runnable, or null if not exception was thrown or exceptions were not caught.
 Throwable getThrowable()
          Returns a throwable caught while executing the Runnable's run() method.
 long getWhen()
          Gets the timestamp of when this event was created.
 String paramString()
          This method returns a string identifying this event.
 
Methods inherited from class java.awt.AWTEvent
consume, getID, isConsumed, setSource, toString
 
Methods inherited from class java.util.EventObject
getSource
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

INVOCATION_FIRST

public static final int INVOCATION_FIRST
This is the first id in the range of event ids used by this class.

See Also:
Constant Field Values

INVOCATION_DEFAULT

public static final int INVOCATION_DEFAULT
This is the default id for this event type.

See Also:
Constant Field Values

INVOCATION_LAST

public static final int INVOCATION_LAST
This is the last id in the range of event ids used by this class.

See Also:
Constant Field Values

runnable

protected Runnable runnable
This is the Runnable object to call when dispatched.


notifier

protected Object notifier
This is the object to call notifyAll() on when the call to run() returns, or null if no object is to be notified.


catchExceptions

protected boolean catchExceptions
This variable is set to true if exceptions are caught and stored in a variable during the call to run(), otherwise exceptions are ignored and propagate up.

Constructor Detail

InvocationEvent

public InvocationEvent(Object source,
                       Runnable runnable)
Initializes a new instance of InvocationEvent with the specified source and runnable.

Parameters:
source - the source of the event
runnable - the Runnable object to invoke
Throws:
IllegalArgumentException - if source is null

InvocationEvent

public InvocationEvent(Object source,
                       Runnable runnable,
                       Object notifier,
                       boolean catchExceptions)
Initializes a new instance of InvocationEvent with the specified source, runnable, and notifier. It will also catch exceptions if specified. If notifier is non-null, this will call notifyAll() on the object when the runnable is complete. If catchExceptions is true, this traps any exception in the runnable, otherwise it lets the exception propagate up the Event Dispatch thread.

Parameters:
source - the source of the event
runnable - the Runnable object to invoke
notifier - the object to notify, or null
catchExceptions - true to catch exceptions from the runnable

InvocationEvent

protected InvocationEvent(Object source,
                          int id,
                          Runnable runnable,
                          Object notifier,
                          boolean catchExceptions)
Initializes a new instance of InvocationEvent with the specified source, runnable, and notifier. It will also catch exceptions if specified. If notifier is non-null, this will call notifyAll() on the object when the runnable is complete. If catchExceptions is true, this traps any exception in the runnable, otherwise it lets the exception propagate up the Event Dispatch thread. Note that an invalid id leads to unspecified results.

Parameters:
source - the source of the event
id - the event id
runnable - the Runnable object to invoke
notifier - the object to notify, or null
catchExceptions - true to catch exceptions from the runnable
Method Detail

dispatch

public void dispatch()
This method calls the run() method of the runnable, traps exceptions if instructed to do so, and calls notifyAll() on any notifier if all worked successfully.

Specified by:
dispatch in interface ActiveEvent

getException

public Exception getException()
This method returns the exception that occurred during the execution of the runnable, or null if not exception was thrown or exceptions were not caught.

Returns:
the exception thrown by the runnable

getThrowable

public Throwable getThrowable()
Returns a throwable caught while executing the Runnable's run() method. Null if none was thrown or if this InvocationEvent doesn't catch throwables.

Returns:
the caught Throwable
Since:
1.5

getWhen

public long getWhen()
Gets the timestamp of when this event was created.

Returns:
the timestamp of this event
Since:
1.4

paramString

public String paramString()
This method returns a string identifying this event. This is formatted as: "INVOCATION_DEFAULT,runnable=" + runnable + ",notifier=" + notifier + ",catchExceptions=" + catchExceptions + ",when=" + getWhen().

Overrides:
paramString in class AWTEvent
Returns:
a string identifying this event