- All Implemented Interfaces:
ActiveEvent
,Serializable
public class InvocationEvent extends AWTEvent implements ActiveEvent
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 id
parameter
of any particular InvocationEvent
instance is not
in the range from INVOCATION_FIRST
to INVOCATION_LAST
.
-
Field Summary
Fields Modifier and Type Field Description protected boolean
catchExceptions
Set to true if dispatch() catches Throwable and stores it in the exception instance variable.static int
INVOCATION_DEFAULT
The default id for all InvocationEvents.static int
INVOCATION_FIRST
Marks the first integer id for the range of invocation event ids.static int
INVOCATION_LAST
Marks the last integer id for the range of invocation event ids.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 or after the event was disposed.protected Runnable
runnable
The 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 protected
InvocationEvent(Object source, int id, Runnable runnable, Object notifier, boolean catchThrowables)
Constructs anInvocationEvent
with the specified source and ID which will execute the runnable'srun()
method when dispatched.InvocationEvent(Object source, Runnable runnable)
Constructs anInvocationEvent
with the specified source which will execute the runnable'srun()
method when dispatched.InvocationEvent(Object source, Runnable runnable, Object notifier, boolean catchThrowables)
Constructs anInvocationEvent
with the specified source which will execute the runnable'srun()
method when dispatched.InvocationEvent(Object source, Runnable runnable, Runnable listener, boolean catchThrowables)
Constructs anInvocationEvent
with the specified source which will execute the runnable'srun()
method when dispatched. -
Method Summary
Modifier and Type Method Description void
dispatch()
Executes the Runnable'srun()
method and notifies the notifier (if any) whenrun()
has returned or thrown an exception.Exception
getException()
Returns any Exception caught while executing the Runnable'srun()
method.Throwable
getThrowable()
Returns any Throwable caught while executing the Runnable'srun()
method.long
getWhen()
Returns the timestamp of when this event occurred.boolean
isDispatched()
Returnstrue
if the event is dispatched or any exception is thrown while dispatching,false
otherwise.String
paramString()
Returns a parameter string identifying this event.Methods declared in class java.util.EventObject
getSource
-
Field Details
-
INVOCATION_FIRST
public static final int INVOCATION_FIRSTMarks the first integer id for the range of invocation event ids.- See Also:
- Constant Field Values
-
INVOCATION_DEFAULT
public static final int INVOCATION_DEFAULTThe default id for all InvocationEvents.- See Also:
- Constant Field Values
-
INVOCATION_LAST
public static final int INVOCATION_LASTMarks the last integer id for the range of invocation event ids.- See Also:
- Constant Field Values
-
runnable
The Runnable whose run() method will be called. -
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 catchExceptionsSet 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 Details
-
InvocationEvent
Constructs anInvocationEvent
with the specified source which will execute the runnable'srun()
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 ofInvocationEvent(source, runnable, null, false)
.This method throws an
IllegalArgumentException
ifsource
isnull
.- Parameters:
source
- TheObject
that originated the eventrunnable
- TheRunnable
whoserun()
method will be executed- Throws:
IllegalArgumentException
- ifsource
is null- See Also:
EventObject.getSource()
,InvocationEvent(Object, Runnable, Object, boolean)
-
InvocationEvent
Constructs anInvocationEvent
with the specified source which will execute the runnable'srun()
method when dispatched. If notifier is non-null
,notifyAll()
will be called on it immediately afterrun()
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 ofInvocationEvent(source, InvocationEvent.INVOCATION_DEFAULT, runnable, notifier, catchThrowables)
.This method throws an
IllegalArgumentException
ifsource
isnull
.- Parameters:
source
- TheObject
that originated the eventrunnable
- TheRunnable
whoserun()
method will be executednotifier
- TheObject
whosenotifyAll
method will be called afterRunnable.run
has returned or thrown an exception or after the event was disposedcatchThrowables
- Specifies whetherdispatch
should catch Throwable when executing theRunnable
'srun()
method, or should instead propagate those Throwables to the EventDispatchThread's dispatch loop- Throws:
IllegalArgumentException
- ifsource
is null- See Also:
EventObject.getSource()
,InvocationEvent(Object, int, Runnable, Object, boolean)
-
InvocationEvent
public InvocationEvent(Object source, Runnable runnable, Runnable listener, boolean catchThrowables)Constructs anInvocationEvent
with the specified source which will execute the runnable'srun()
method when dispatched. If listener is non-null
,listener.run()
will be called immediately afterrun
has returned, thrown an exception or the event was disposed.This method throws an
IllegalArgumentException
ifsource
isnull
.- Parameters:
source
- TheObject
that originated the eventrunnable
- TheRunnable
whoserun()
method will be executedlistener
- TheRunnable
whoserun()
method will be called after theInvocationEvent
was dispatched or disposedcatchThrowables
- Specifies whetherdispatch
should catch Throwable when executing theRunnable
'srun()
method, or should instead propagate those Throwables to the EventDispatchThread's dispatch loop- Throws:
IllegalArgumentException
- ifsource
is null
-
InvocationEvent
protected InvocationEvent(Object source, int id, Runnable runnable, Object notifier, boolean catchThrowables)Constructs anInvocationEvent
with the specified source and ID which will execute the runnable'srun()
method when dispatched. If notifier is non-null
,notifyAll()
will be called on it immediately afterrun()
has returned or thrown an exception.This method throws an
IllegalArgumentException
ifsource
isnull
.- Parameters:
source
- TheObject
that originated the eventid
- An integer indicating the type of event. For information on allowable values, see the class description forInvocationEvent
runnable
- TheRunnable
whoserun()
method will be executednotifier
- TheObject
whosenotifyAll
method will be called afterRunnable.run
has returned or thrown an exception or after the event was disposedcatchThrowables
- Specifies whetherdispatch
should catch Throwable when executing theRunnable
'srun()
method, or should instead propagate those Throwables to the EventDispatchThread's dispatch loop- Throws:
IllegalArgumentException
- ifsource
is null- See Also:
EventObject.getSource()
,AWTEvent.getID()
-
-
Method Details
-
dispatch
public void dispatch()Executes the Runnable'srun()
method and notifies the notifier (if any) whenrun()
has returned or thrown an exception.- Specified by:
dispatch
in interfaceActiveEvent
- See Also:
isDispatched()
-
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
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()Returnstrue
if the event is dispatched or any exception is thrown while dispatching,false
otherwise. 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 thewhile
loop 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, thewhile
loop 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:
true
if the event has been dispatched, or any exception has been thrown while dispatching,false
otherwise- Since:
- 1.7
- See Also:
dispatch()
,notifier
,catchExceptions
-
paramString
Returns a parameter string identifying this event. This method is useful for event-logging and for debugging.- Overrides:
paramString
in classAWTEvent
- Returns:
- A string identifying the event and its attributes
-