Home » openjdk-7 » java » awt » event » [javadoc | source]
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}.

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 has returned or thrown an exception. 
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.util.EventObject:
source
Constructor:
 public InvocationEvent(Object source,
    Runnable runnable) 
    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.

 public InvocationEvent(Object source,
    Runnable runnable,
    Object notifier,
    boolean 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 has returned or thrown an exception.

    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 or thrown an exception
    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) 
    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 has returned or thrown an exception.

    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 or thrown an exception
    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()
Method from java.awt.event.InvocationEvent Summary:
dispatch,   getException,   getThrowable,   getWhen,   isDispatched,   paramString
Methods from java.awt.AWTEvent:
consume,   convertToOld,   copyPrivateDataInto,   dispatched,   getAccessControlContext,   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() 
    Executes the Runnable's run() method and notifies the notifier (if any) when run() has returned or thrown an exception.
 public Exception getException() 
    Returns any Exception caught while executing the Runnable's run() method.
 public Throwable getThrowable() 
    Returns any Throwable caught while executing the Runnable's run() method.
 public long getWhen() 
    Returns the timestamp of when this event occurred.
 public boolean isDispatched() 
    Returns {@code true} if the event is dispatched or any exception is thrown while dispatching, {@code false} otherwise. The method should be called by a waiting thread that calls the {@code notifier.wait()} method. Since spurious wakeups are possible (as explained in Object#wait() ), this method should be used in a waiting loop to ensure that the event got dispatched:
        while (!event.isDispatched()) {
            notifier.wait();
        }
    
    If the waiting thread wakes up without dispatching the event, the {@code isDispatched()} method returns {@code false}, and the {@code while} loop executes once more, thus, causing the awakened thread to revert to the waiting mode.

    If the {@code notifier.notifyAll()} happens before the waiting thread enters the {@code notifier.wait()} method, the {@code while} loop ensures that the waiting thread will not enter the {@code notifier.wait()} method. Otherwise, there is no guarantee that the waiting thread will ever be woken from the wait.

 public String paramString() 
    Returns a parameter string identifying this event. This method is useful for event-logging and for debugging.