src/share/classes/java/awt/event/InvocationEvent.java

Print this page




  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package java.awt.event;
  27 
  28 import java.awt.ActiveEvent;
  29 import java.awt.AWTEvent;
  30 



  31 /**
  32  * An event which executes the <code>run()</code> method on a <code>Runnable
  33  * </code> when dispatched by the AWT event dispatcher thread. This class can
  34  * be used as a reference implementation of <code>ActiveEvent</code> rather
  35  * than declaring a new class and defining <code>dispatch()</code>.<p>
  36  *
  37  * Instances of this class are placed on the <code>EventQueue</code> by calls
  38  * to <code>invokeLater</code> and <code>invokeAndWait</code>. Client code
  39  * can use this fact to write replacement functions for <code>invokeLater
  40  * </code> and <code>invokeAndWait</code> without writing special-case code
  41  * in any <code>AWTEventListener</code> objects.
  42  * <p>
  43  * An unspecified behavior will be caused if the {@code id} parameter
  44  * of any particular {@code InvocationEvent} instance is not
  45  * in the range from {@code INVOCATION_FIRST} to {@code INVOCATION_LAST}.
  46  *
  47  * @author      Fred Ecks
  48  * @author      David Mendenhall
  49  *
  50  * @see         java.awt.ActiveEvent


 110     /**
 111      * The (potentially null) Throwable thrown during execution of the
 112      * Runnable.run() method. This variable will also be null if a particular
 113      * instance does not catch exceptions.
 114      */
 115     private Throwable throwable = null;
 116 
 117     /**
 118      * The timestamp of when this event occurred.
 119      *
 120      * @serial
 121      * @see #getWhen
 122      */
 123     private long when;
 124 
 125     /*
 126      * JDK 1.1 serialVersionUID.
 127      */
 128     private static final long serialVersionUID = 436056344909459450L;
 129 










 130     /**
 131      * Constructs an <code>InvocationEvent</code> with the specified
 132      * source which will execute the runnable's <code>run</code>
 133      * method when dispatched.
 134      * <p>This is a convenience constructor.  An invocation of the form
 135      * <tt>InvocationEvent(source, runnable)</tt>
 136      * behaves in exactly the same way as the invocation of
 137      * <tt>{@link #InvocationEvent(Object, Runnable, Object, boolean) InvocationEvent}(source, runnable, null, false)</tt>.
 138      * <p> This method throws an <code>IllegalArgumentException</code>
 139      * if <code>source</code> is <code>null</code>.
 140      *
 141      * @param source    The <code>Object</code> that originated the event
 142      * @param runnable  The <code>Runnable</code> whose <code>run</code>
 143      *                  method will be executed
 144      * @throws IllegalArgumentException if <code>source</code> is null
 145      *
 146      * @see #getSource()
 147      * @see #InvocationEvent(Object, Runnable, Object, boolean)
 148      */
 149     public InvocationEvent(Object source, Runnable runnable) {


 211      *                          thrown an exception
 212      * @param catchThrowables   Specifies whether <code>dispatch</code>
 213      *                          should catch Throwable when executing the
 214      *                          <code>Runnable</code>'s <code>run</code>
 215      *                          method, or should instead propagate those
 216      *                          Throwables to the EventDispatchThread's
 217      *                          dispatch loop
 218      * @throws IllegalArgumentException if <code>source</code> is null
 219      * @see #getSource()
 220      * @see #getID()
 221      */
 222     protected InvocationEvent(Object source, int id, Runnable runnable,
 223                               Object notifier, boolean catchThrowables) {
 224         super(source, id);
 225         this.runnable = runnable;
 226         this.notifier = notifier;
 227         this.catchExceptions = catchThrowables;
 228         this.when = System.currentTimeMillis();
 229     }
 230 













 231     /**
 232      * Executes the Runnable's <code>run()</code> method and notifies the
 233      * notifier (if any) when <code>run()</code> has returned or thrown an exception.
 234      *
 235      * @see #isDispatched
 236      */
 237     public void dispatch() {
 238         try {
 239             if (catchExceptions) {
 240                 try {
 241                     runnable.run();
 242                 }
 243                 catch (Throwable t) {
 244                     if (t instanceof Exception) {
 245                         exception = (Exception) t;
 246                     }
 247                     throwable = t;
 248                 }
 249             }
 250             else {
 251                 runnable.run();
 252             }
 253         } finally {
 254             dispatched = true;
 255 
 256             if (notifier != null) {
 257                 synchronized (notifier) {
 258                     notifier.notifyAll();
 259                 }
 260             }
 261         }







 262     }
 263 
 264     /**
 265      * Returns any Exception caught while executing the Runnable's <code>run()
 266      * </code> method.
 267      *
 268      * @return  A reference to the Exception if one was thrown; null if no
 269      *          Exception was thrown or if this InvocationEvent does not
 270      *          catch exceptions
 271      */
 272     public Exception getException() {
 273         return (catchExceptions) ? exception : null;
 274     }
 275 
 276     /**
 277      * Returns any Throwable caught while executing the Runnable's <code>run()
 278      * </code> method.
 279      *
 280      * @return  A reference to the Throwable if one was thrown; null if no
 281      *          Throwable was thrown or if this InvocationEvent does not




  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package java.awt.event;
  27 
  28 import java.awt.ActiveEvent;
  29 import java.awt.AWTEvent;
  30 
  31 import sun.awt.AWTAccessor;
  32 import sun.awt.AWTInterruptedException;
  33 
  34 /**
  35  * An event which executes the <code>run()</code> method on a <code>Runnable
  36  * </code> when dispatched by the AWT event dispatcher thread. This class can
  37  * be used as a reference implementation of <code>ActiveEvent</code> rather
  38  * than declaring a new class and defining <code>dispatch()</code>.<p>
  39  *
  40  * Instances of this class are placed on the <code>EventQueue</code> by calls
  41  * to <code>invokeLater</code> and <code>invokeAndWait</code>. Client code
  42  * can use this fact to write replacement functions for <code>invokeLater
  43  * </code> and <code>invokeAndWait</code> without writing special-case code
  44  * in any <code>AWTEventListener</code> objects.
  45  * <p>
  46  * An unspecified behavior will be caused if the {@code id} parameter
  47  * of any particular {@code InvocationEvent} instance is not
  48  * in the range from {@code INVOCATION_FIRST} to {@code INVOCATION_LAST}.
  49  *
  50  * @author      Fred Ecks
  51  * @author      David Mendenhall
  52  *
  53  * @see         java.awt.ActiveEvent


 113     /**
 114      * The (potentially null) Throwable thrown during execution of the
 115      * Runnable.run() method. This variable will also be null if a particular
 116      * instance does not catch exceptions.
 117      */
 118     private Throwable throwable = null;
 119 
 120     /**
 121      * The timestamp of when this event occurred.
 122      *
 123      * @serial
 124      * @see #getWhen
 125      */
 126     private long when;
 127 
 128     /*
 129      * JDK 1.1 serialVersionUID.
 130      */
 131     private static final long serialVersionUID = 436056344909459450L;
 132 
 133     static {
 134         AWTAccessor.setInvocationEventAccessor(
 135                 new AWTAccessor.InvocationEventAccessor() {
 136                     @Override
 137                     public void dispose(InvocationEvent ie) {
 138                         ie.dispose();
 139                     }
 140                 });
 141     }
 142 
 143     /**
 144      * Constructs an <code>InvocationEvent</code> with the specified
 145      * source which will execute the runnable's <code>run</code>
 146      * method when dispatched.
 147      * <p>This is a convenience constructor.  An invocation of the form
 148      * <tt>InvocationEvent(source, runnable)</tt>
 149      * behaves in exactly the same way as the invocation of
 150      * <tt>{@link #InvocationEvent(Object, Runnable, Object, boolean) InvocationEvent}(source, runnable, null, false)</tt>.
 151      * <p> This method throws an <code>IllegalArgumentException</code>
 152      * if <code>source</code> is <code>null</code>.
 153      *
 154      * @param source    The <code>Object</code> that originated the event
 155      * @param runnable  The <code>Runnable</code> whose <code>run</code>
 156      *                  method will be executed
 157      * @throws IllegalArgumentException if <code>source</code> is null
 158      *
 159      * @see #getSource()
 160      * @see #InvocationEvent(Object, Runnable, Object, boolean)
 161      */
 162     public InvocationEvent(Object source, Runnable runnable) {


 224      *                          thrown an exception
 225      * @param catchThrowables   Specifies whether <code>dispatch</code>
 226      *                          should catch Throwable when executing the
 227      *                          <code>Runnable</code>'s <code>run</code>
 228      *                          method, or should instead propagate those
 229      *                          Throwables to the EventDispatchThread's
 230      *                          dispatch loop
 231      * @throws IllegalArgumentException if <code>source</code> is null
 232      * @see #getSource()
 233      * @see #getID()
 234      */
 235     protected InvocationEvent(Object source, int id, Runnable runnable,
 236                               Object notifier, boolean catchThrowables) {
 237         super(source, id);
 238         this.runnable = runnable;
 239         this.notifier = notifier;
 240         this.catchExceptions = catchThrowables;
 241         this.when = System.currentTimeMillis();
 242     }
 243 
 244     /*
 245      * Marks the event as dispatched and notifies all interested parties.
 246      */
 247     private void setDispatched() {
 248         dispatched = true;
 249 
 250         if (notifier != null) {
 251             synchronized (notifier) {
 252                 notifier.notifyAll();
 253             }
 254         }
 255     }
 256 
 257     /**
 258      * Executes the Runnable's <code>run()</code> method and notifies the
 259      * notifier (if any) when <code>run()</code> has returned or thrown an exception.
 260      *
 261      * @see #isDispatched
 262      */
 263     public void dispatch() {
 264         try {
 265             if (catchExceptions) {
 266                 try {
 267                     runnable.run();
 268                 }
 269                 catch (Throwable t) {
 270                     if (t instanceof Exception) {
 271                         exception = (Exception) t;
 272                     }
 273                     throwable = t;
 274                 }
 275             }
 276             else {
 277                 runnable.run();
 278             }
 279         } finally {
 280             setDispatched();





 281         }
 282     }
 283 
 284     private void dispose() {
 285         throwable = exception =
 286             new AWTInterruptedException(
 287                     "The event is discarded due to Event Thread interruption");
 288 
 289         setDispatched();
 290     }
 291 
 292     /**
 293      * Returns any Exception caught while executing the Runnable's <code>run()
 294      * </code> method.
 295      *
 296      * @return  A reference to the Exception if one was thrown; null if no
 297      *          Exception was thrown or if this InvocationEvent does not
 298      *          catch exceptions
 299      */
 300     public Exception getException() {
 301         return (catchExceptions) ? exception : null;
 302     }
 303 
 304     /**
 305      * Returns any Throwable caught while executing the Runnable's <code>run()
 306      * </code> method.
 307      *
 308      * @return  A reference to the Throwable if one was thrown; null if no
 309      *          Throwable was thrown or if this InvocationEvent does not