java.awt.event: public class: InvocationEvent

java.awt.event
public class: InvocationEvent [javadoc | source]

java.lang.Object
   java.util.EventObject
      java.awt.AWTEvent
         java.awt.event.InvocationEvent

All Implemented Interfaces:
ActiveEvent, Serializable

An event which executes the 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.

An unspecified behavior will be caused if the {@code id} parameter of any particular {@code InvocationEvent} instance is not in the range from {@code INVOCATION_FIRST} to {@code INVOCATION_LAST}.

Also see:

java.awt.ActiveEvent

java.awt.EventQueue#invokeLater

java.awt.EventQueue#invokeAndWait

AWTEventListener

author: Fred - Ecks

author: David - Mendenhall

since: 1.2 -

Field Summary
public static final int	INVOCATION_FIRST	Marks the first integer id for the range of invocation event ids.
public static final int	INVOCATION_DEFAULT	The default id for all InvocationEvents.
public static final int	INVOCATION_LAST	Marks the last integer id for the range of invocation event ids.
protected Runnable	runnable	The Runnable whose run() method will be called.
protected Object	notifier	The (potentially null) Object whose notifyAll() method will be called immediately after the Runnable.run() method returns.
protected boolean	catchExceptions	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.

Fields inherited from java.awt.AWTEvent:
id, consumed, focusManagerIsDispatching, isPosted, COMPONENT_EVENT_MASK, CONTAINER_EVENT_MASK, FOCUS_EVENT_MASK, KEY_EVENT_MASK, MOUSE_EVENT_MASK, MOUSE_MOTION_EVENT_MASK, WINDOW_EVENT_MASK, ACTION_EVENT_MASK, ADJUSTMENT_EVENT_MASK, ITEM_EVENT_MASK, TEXT_EVENT_MASK, INPUT_METHOD_EVENT_MASK, INPUT_METHODS_ENABLED_MASK, PAINT_EVENT_MASK, INVOCATION_EVENT_MASK, HIERARCHY_EVENT_MASK, HIERARCHY_BOUNDS_EVENT_MASK, MOUSE_WHEEL_EVENT_MASK, WINDOW_STATE_EVENT_MASK, WINDOW_FOCUS_EVENT_MASK, RESERVED_ID_MAX

Fields inherited from java.awt.AWTEvent:

id, consumed, focusManagerIsDispatching, isPosted, COMPONENT_EVENT_MASK, CONTAINER_EVENT_MASK, FOCUS_EVENT_MASK, KEY_EVENT_MASK, MOUSE_EVENT_MASK, MOUSE_MOTION_EVENT_MASK, WINDOW_EVENT_MASK, ACTION_EVENT_MASK, ADJUSTMENT_EVENT_MASK, ITEM_EVENT_MASK, TEXT_EVENT_MASK, INPUT_METHOD_EVENT_MASK, INPUT_METHODS_ENABLED_MASK, PAINT_EVENT_MASK, INVOCATION_EVENT_MASK, HIERARCHY_EVENT_MASK, HIERARCHY_BOUNDS_EVENT_MASK, MOUSE_WHEEL_EVENT_MASK, WINDOW_STATE_EVENT_MASK, WINDOW_FOCUS_EVENT_MASK, RESERVED_ID_MAX

Fields inherited from java.util.EventObject:
source

Constructor:

Constructor:
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. This is a convenience constructor. An invocation of the form `InvocationEvent(source, runnable)` behaves in exactly the same way as the invocation of `InvocationEvent (source, runnable, null, false)`. This method throws an `IllegalArgumentException` if `source` is `null`. Parameters: `source` - The `Object` that originated the event `runnable` - The `Runnable` whose `run` method will be executed Throws: `IllegalArgumentException` - if `source` is null Also see: getSource() InvocationEvent(Object, 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 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 `InvocationEvent (source, InvocationEvent.INVOCATION_DEFAULT, runnable, notifier, catchThrowables)`. This method throws an `IllegalArgumentException` if `source` is `null`. Parameters: `source` - The `Object` that originated the event `runnable` - The `Runnable` whose `run` method will be executed `notifier` - The {@code Object} whose `notifyAll` method will be called after `Runnable.run` has returned `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 Also see: getSource() InvocationEvent(Object, int, Runnable, Object, boolean)
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(); } 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. This method throws an `IllegalArgumentException` if `source` is `null`. Parameters: `source` - The `Object` that originated the event `id` - An integer indicating the type of event. For information on allowable values, see the class description for InvocationEvent `runnable` - The `Runnable` whose `run` method will be executed `notifier` - The `Object` whose `notifyAll` method will be called after `Runnable.run` has returned `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 Also see: getSource() getID()

 public InvocationEvent(Object source,
    Runnable runnable) {
                                                                                                                       
        this(source, runnable, null, false);
}

InvocationEvent

run

This is a convenience constructor. An invocation of the form InvocationEvent(source, runnable) behaves in exactly the same way as the invocation of InvocationEvent (source, runnable, null, false).

This method throws an IllegalArgumentException if source is null.

Parameters:

source - The Object that originated the event

runnable - The Runnable whose run method will be executed

Throws:

IllegalArgumentException - if source is null

Also see:

getSource()

InvocationEvent(Object, Runnable, Object, boolean)

 public InvocationEvent(Object source,
    Runnable runnable,
    Object notifier,
    boolean catchThrowables) {
        this(source, INVOCATION_DEFAULT, runnable, notifier, catchThrowables);
}

InvocationEvent

run

null

notifyAll()

run

An invocation of the form InvocationEvent(source, runnable, notifier, catchThrowables) behaves in exactly the same way as the invocation of InvocationEvent (source, InvocationEvent.INVOCATION_DEFAULT, runnable, notifier, catchThrowables).

This method throws an IllegalArgumentException if source is null.

Parameters:

source - The Object that originated the event

runnable - The Runnable whose run method will be executed

notifier - The {@code Object} whose notifyAll method will be called after Runnable.run has returned

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

Also see:

getSource()

InvocationEvent(Object, int, Runnable, Object, boolean)

 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();
}

InvocationEvent

run

null

notifyAll

run

This method throws an IllegalArgumentException if source is null.

Parameters:

source - The Object that originated the event

id - An integer indicating the type of event. For information on allowable values, see the class description for InvocationEvent

runnable - The Runnable whose run method will be executed

notifier - The Object whose notifyAll method will be called after Runnable.run has returned

Throws:

IllegalArgumentException - if source is null

Also see:

getSource()

getID()

Method from java.awt.event.InvocationEvent Summary:
dispatch, getException, getThrowable, getWhen, paramString

Methods from java.awt.AWTEvent:
consume, convertToOld, copyPrivateDataInto, dispatched, getID, isConsumed, paramString, setSource, toString

Methods from java.util.EventObject:
getSource, toString

Methods from java.lang.Object:
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method from java.awt.event.InvocationEvent Detail:
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(); } } } Executes the Runnable's `run()` method and notifies the notifier (if any) when `run()` returns.
public Exception getException() { return (catchExceptions) ? exception : null; } Returns any Exception caught while executing the Runnable's `run()` method.
public Throwable getThrowable() { return (catchExceptions) ? throwable : null; } Returns any Throwable caught while executing the Runnable's `run()` method.
public long getWhen() { return when; } Returns the timestamp of when this event occurred.
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; } Returns a parameter string identifying this event. This method is useful for event-logging and for debugging.

Method from java.awt.event.InvocationEvent Detail:

 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();
            }
        }
}

run()

 public Exception getException() {
        return (catchExceptions) ? exception : null;
}

run()

 public Throwable getThrowable() {
        return (catchExceptions) ? throwable : null;
}

run()

 public long getWhen() {
        return when;
}

Returns the timestamp of when this event occurred.

 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;
}

Returns a parameter string identifying this event. This method is useful for event-logging and for debugging.