- 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
An event which executes therun()method on aRunnablewhen dispatched by the AWT event dispatcher thread. This class can be used as a reference implementation ofActiveEventrather than declaring a new class and definingdispatch().Instances of this class are placed on the
EventQueueby calls toinvokeLaterandinvokeAndWait. Client code can use this fact to write replacement functions forinvokeLaterandinvokeAndWaitwithout writing special-case code in anyAWTEventListenerobjects.An unspecified behavior will be caused if the
idparameter of any particularInvocationEventinstance is not in the range fromINVOCATION_FIRSTtoINVOCATION_LAST.
-
-
Field Summary
Fields Modifier and Type Field Description protected booleancatchExceptionsSet to true if dispatch() catches Throwable and stores it in the exception instance variable.static intINVOCATION_DEFAULTThe default id for all InvocationEvents.static intINVOCATION_FIRSTMarks the first integer id for the range of invocation event ids.static intINVOCATION_LASTMarks the last integer id for the range of invocation event ids.protected ObjectnotifierThe (potentially null) Object whose notifyAll() method will be called immediately after the Runnable.run() method has returned or thrown an exception or after the event was disposed.protected RunnablerunnableThe Runnable whose run() method will be called.-
Fields declared in 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 declared in class java.util.EventObject
source
-
-
Constructor Summary
Constructors Modifier Constructor Description protectedInvocationEvent(Object source, int id, Runnable runnable, Object notifier, boolean catchThrowables)Constructs anInvocationEventwith the specified source and ID which will execute the runnable'srunmethod when dispatched.InvocationEvent(Object source, Runnable runnable)Constructs anInvocationEventwith the specified source which will execute the runnable'srunmethod when dispatched.InvocationEvent(Object source, Runnable runnable, Object notifier, boolean catchThrowables)Constructs anInvocationEventwith the specified source which will execute the runnable'srunmethod when dispatched.InvocationEvent(Object source, Runnable runnable, Runnable listener, boolean catchThrowables)Constructs anInvocationEventwith the specified source which will execute the runnable'srunmethod when dispatched.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description voiddispatch()Executes the Runnable'srun()method and notifies the notifier (if any) whenrun()has returned or thrown an exception.ExceptiongetException()Returns any Exception caught while executing the Runnable'srun()method.ThrowablegetThrowable()Returns any Throwable caught while executing the Runnable'srun()method.longgetWhen()Returns the timestamp of when this event occurred.booleanisDispatched()Returnstrueif the event is dispatched or any exception is thrown while dispatching,falseotherwise.StringparamString()Returns a parameter string identifying this event.-
Methods declared in class java.util.EventObject
getSource
-
-
-
-
Field Detail
-
INVOCATION_FIRST
public static final int INVOCATION_FIRST
Marks the first integer id for the range of invocation event ids.- See Also:
- Constant Field Values
-
INVOCATION_DEFAULT
public static final int INVOCATION_DEFAULT
The default id for all InvocationEvents.- See Also:
- Constant Field Values
-
INVOCATION_LAST
public static final int INVOCATION_LAST
Marks the last integer id for the range of invocation event ids.- See Also:
- Constant Field Values
-
runnable
protected Runnable runnable
The Runnable whose run() method will be called.
-
notifier
protected volatile Object notifier
The (potentially null) Object whose notifyAll() method will be called immediately after the Runnable.run() method has returned or thrown an exception or after the event was disposed.- See Also:
isDispatched()
-
catchExceptions
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.
-
-
Constructor Detail
-
InvocationEvent
public InvocationEvent(Object source, Runnable runnable)
Constructs anInvocationEventwith the specified source which will execute the runnable'srunmethod when dispatched.This is a convenience constructor. An invocation of the form
InvocationEvent(source, runnable)behaves in exactly the same way as the invocation ofInvocationEvent(source, runnable, null, false).This method throws an
IllegalArgumentExceptionifsourceisnull.- Parameters:
source- TheObjectthat originated the eventrunnable- TheRunnablewhoserunmethod will be executed- Throws:
IllegalArgumentException- ifsourceis null- See Also:
EventObject.getSource(),InvocationEvent(Object, Runnable, Object, boolean)
-
InvocationEvent
public InvocationEvent(Object source, Runnable runnable, Object notifier, boolean catchThrowables)
Constructs anInvocationEventwith the specified source which will execute the runnable'srunmethod when dispatched. If notifier is non-null,notifyAll()will be called on it immediately afterrunhas returned or thrown an exception.An invocation of the form
InvocationEvent(source, runnable, notifier, catchThrowables)behaves in exactly the same way as the invocation ofInvocationEvent(source, InvocationEvent.INVOCATION_DEFAULT, runnable, notifier, catchThrowables).This method throws an
IllegalArgumentExceptionifsourceisnull.- Parameters:
source- TheObjectthat originated the eventrunnable- TheRunnablewhoserunmethod will be executednotifier- TheObjectwhosenotifyAllmethod will be called afterRunnable.runhas returned or thrown an exception or after the event was disposedcatchThrowables- Specifies whetherdispatchshould catch Throwable when executing theRunnable'srunmethod, or should instead propagate those Throwables to the EventDispatchThread's dispatch loop- Throws:
IllegalArgumentException- ifsourceis null- See Also:
EventObject.getSource(),InvocationEvent(Object, int, Runnable, Object, boolean)
-
InvocationEvent
public InvocationEvent(Object source, Runnable runnable, Runnable listener, boolean catchThrowables)
Constructs anInvocationEventwith the specified source which will execute the runnable'srunmethod when dispatched. If listener is non-null,listener.run()will be called immediately afterrunhas returned, thrown an exception or the event was disposed.This method throws an
IllegalArgumentExceptionifsourceisnull.- Parameters:
source- TheObjectthat originated the eventrunnable- TheRunnablewhoserunmethod will be executedlistener- TheRunnableRunnable whoserun()method will be called after theInvocationEventwas dispatched or disposedcatchThrowables- Specifies whetherdispatchshould catch Throwable when executing theRunnable'srunmethod, or should instead propagate those Throwables to the EventDispatchThread's dispatch loop- Throws:
IllegalArgumentException- ifsourceis null
-
InvocationEvent
protected InvocationEvent(Object source, int id, Runnable runnable, Object notifier, boolean catchThrowables)
Constructs anInvocationEventwith the specified source and ID which will execute the runnable'srunmethod when dispatched. If notifier is non-null,notifyAllwill be called on it immediately afterrunhas returned or thrown an exception.This method throws an
IllegalArgumentExceptionifsourceisnull.- Parameters:
source- TheObjectthat originated the eventid- An integer indicating the type of event. For information on allowable values, see the class description forInvocationEventrunnable- TheRunnablewhoserunmethod will be executednotifier- TheObjectwhosenotifyAllmethod will be called afterRunnable.runhas returned or thrown an exception or after the event was disposedcatchThrowables- Specifies whetherdispatchshould catch Throwable when executing theRunnable'srunmethod, or should instead propagate those Throwables to the EventDispatchThread's dispatch loop- Throws:
IllegalArgumentException- ifsourceis null- See Also:
EventObject.getSource(),AWTEvent.getID()
-
-
Method Detail
-
dispatch
public void dispatch()
Executes the Runnable'srun()method and notifies the notifier (if any) whenrun()has returned or thrown an exception.- Specified by:
dispatchin interfaceActiveEvent- See Also:
isDispatched()
-
getException
public Exception getException()
Returns any Exception caught while executing the Runnable'srun()method.- Returns:
- A reference to the Exception if one was thrown; null if no Exception was thrown or if this InvocationEvent does not catch exceptions
-
getThrowable
public Throwable getThrowable()
Returns any Throwable caught while executing the Runnable'srun()method.- Returns:
- A reference to the Throwable if one was thrown; null if no Throwable was thrown or if this InvocationEvent does not catch Throwables
- Since:
- 1.5
-
getWhen
public long getWhen()
Returns the timestamp of when this event occurred.- Returns:
- this event's timestamp
- Since:
- 1.4
-
isDispatched
public boolean isDispatched()
Returnstrueif the event is dispatched or any exception is thrown while dispatching,falseotherwise. The method should be called by a waiting thread that calls thenotifier.wait()method. Since spurious wakeups are possible (as explained inObject.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, theisDispatched()method returnsfalse, and thewhileloop executes once more, thus, causing the awakened thread to revert to the waiting mode.If the
notifier.notifyAll()happens before the waiting thread enters thenotifier.wait()method, thewhileloop ensures that the waiting thread will not enter thenotifier.wait()method. Otherwise, there is no guarantee that the waiting thread will ever be woken from the wait.- Returns:
trueif the event has been dispatched, or any exception has been thrown while dispatching,falseotherwise- Since:
- 1.7
- See Also:
dispatch(),notifier,catchExceptions
-
paramString
public String paramString()
Returns a parameter string identifying this event. This method is useful for event-logging and for debugging.- Overrides:
paramStringin classAWTEvent- Returns:
- A string identifying the event and its attributes
-
-