java.awt.event

Class InvocationEvent

java.lang.Object

java.util.EventObject

java.awt.AWTEvent

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

Fields

Modifier and Type	Field and Description
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

Constructors

Modifier	Constructor and Description
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

Methods

Modifier and Type	Method and Description
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