InvocationEvent


1   /*
2    * @(#)InvocationEvent.java 1.18 04/02/05
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package java.awt.event;
9   
10  import java.awt.ActiveEvent  ;
11  import java.awt.AWTEvent  ;
12  
13  /**
14   * An event which executes the <code>run()</code> method on a <code>Runnable
15   * </code> when dispatched by the AWT event dispatcher thread. This class can
16   * be used as a reference implementation of <code>ActiveEvent</code> rather
17   * than declaring a new class and defining <code>dispatch()</code>.<p>
18   *
19   * Instances of this class are placed on the <code>EventQueue</code> by calls
20   * to <code>invokeLater</code> and <code>invokeAndWait</code>. Client code
21   * can use this fact to write replacement functions for <code>invokeLater
22   * </code> and <code>invokeAndWait</code> without writing special-case code
23   * in any <code>AWTEventListener</code> objects.
24   *
25   * @author  Fred Ecks
26   * @author  David Mendenhall
27   * @version 1.18, 02/05/04
28   *
29   * @see     java.awt.ActiveEvent
30   * @see     java.awt.EventQueue#invokeLater
31   * @see     java.awt.EventQueue#invokeAndWait
32   * @see     AWTEventListener
33   *
34   * @since   1.2
35   */
36  public class InvocationEvent extends AWTEvent   implements ActiveEvent   {
37  
38      /**
39       * Marks the first integer id for the range of invocation event ids.
40       */
41      public static final int INVOCATION_FIRST = 1200;
42  
43      /**
44       * The default id for all InvocationEvents.
45       */
46      public static final int INVOCATION_DEFAULT = INVOCATION_FIRST;
47  
48      /**
49       * Marks the last integer id for the range of invocation event ids.
50       */
51      public static final int INVOCATION_LAST = INVOCATION_DEFAULT;
52  
53      /**
54       * The Runnable whose run() method will be called.
55       */
56      protected Runnable   runnable;
57  
58      /**
59       * The (potentially null) Object whose notifyAll() method will be called
60       * immediately after the Runnable.run() method returns.
61       */
62      protected Object   notifier;
63  
64      /**
65       * Set to true if dispatch() catches Throwable and stores it in the
66       * exception instance variable. If false, Throwables are propagated up
67       * to the EventDispatchThread's dispatch loop.
68       */
69      protected boolean catchExceptions;
70  
71      /**
72       * The (potentially null) Exception thrown during execution of the
73       * Runnable.run() method. This variable will also be null if a particular
74       * instance does not catch exceptions.
75       */
76      private Exception   exception = null;
77  
78      /**
79       * The (potentially null) Throwable thrown during execution of the
80       * Runnable.run() method. This variable will also be null if a particular
81       * instance does not catch exceptions.
82       */
83      private Throwable   throwable = null;
84  
85      /**
86       * The timestamp of when this event occurred.
87       *
88       * @serial
89       * @see #getWhen
90       */
91      private long when;
92  
93      /*
94       * JDK 1.1 serialVersionUID.
95       */
96      private static final long serialVersionUID = 436056344909459450L;
97  
98      /**
99       * Constructs an <code>InvocationEvent</code> with the specified
100      * source which will execute the runnable's <code>run</code>
101      * method when dispatched.
102      * <p>This is a convenience constructor.  An invocation of the form
103      * <tt>InvocationEvent(source, runnable)</tt>
104      * behaves in exactly the same way as the invocation of
105      * <tt>{@link #InvocationEvent(Object, Runnable, Object, boolean) InvocationEvent}(source, runnable, null, false)</tt>.
106      * <p> This method throws an <code>IllegalArgumentException</code>
107      * if <code>source</code> is <code>null</code>.
108      *
109      * @param source    the <code>Object</code> that originated the event
110      * @param runnable  the <code>Runnable</code> whose <code>run</code>
111      *                  method will be executed
112      * @throws IllegalArgumentException if <code>source</code> is null
113      *
114      * @see     #InvocationEvent(Object, Runnable, Object, boolean)
115      */
116     public InvocationEvent(Object   source, Runnable   runnable) {
117         this(source, runnable, null, false);
118     }
119 
120     /**
121      * Constructs an <code>InvocationEvent</code> with the specified
122      * source which will execute the runnable's <code>run</code>
123      * method when dispatched.  If notifier is non-<code>null</code>,
124      * <code>notifyAll()</code> will be called on it
125      * immediately after <code>run</code> returns.
126      * <p>An invocation of the form <tt>InvocationEvent(source,
127      * runnable, notifier, catchThrowables)</tt>
128      * behaves in exactly the same way as the invocation of
129      * <tt>{@link #InvocationEvent(Object, int, Runnable, Object, boolean) InvocationEvent}(source, InvocationEvent.INVOCATION_DEFAULT, runnable, notifier, catchThrowables)</tt>.
130      * <p>This method throws an <code>IllegalArgumentException</code>
131      * if <code>source</code> is <code>null</code>.
132      *
133      * @param source        the <code>Object</code> that originated
134      *                          the event
135      * @param runnable      the <code>Runnable</code> whose
136      *                          <code>run</code> method will be
137      *                          executed
138      * @param notifier      the Object whose <code>notifyAll</code>
139      *                          method will be called after
140      *                          <code>Runnable.run</code> has returned
141      * @param catchThrowables   specifies whether <code>dispatch</code>
142      *                          should catch Throwable when executing
143      *                          the <code>Runnable</code>'s <code>run</code>
144      *                          method, or should instead propagate those
145      *                          Throwables to the EventDispatchThread's
146      *                          dispatch loop
147      * @throws IllegalArgumentException if <code>source</code> is null
148      *
149      * @see     #InvocationEvent(Object, int, Runnable, Object, boolean)
150      */
151     public InvocationEvent(Object   source, Runnable   runnable, Object   notifier,
152                            boolean catchThrowables) {
153     this(source, INVOCATION_DEFAULT, runnable, notifier, catchThrowables);
154     }
155 
156     /**
157      * Constructs an <code>InvocationEvent</code> with the specified
158      * source and ID which will execute the runnable's <code>run</code>
159      * method when dispatched.  If notifier is non-<code>null</code>,
160      * <code>notifyAll</code> will be called on it 
161      * immediately after <code>run</code> returns.
162      * <p>Note that passing in an invalid <code>id</code> results in
163      * unspecified behavior. This method throws an
164      * <code>IllegalArgumentException</code> if <code>source</code>
165      * is <code>null</code>.
166      *
167      * @param source        the <code>Object</code> that originated
168      *                          the event
169      * @param id        the ID for the event
170      * @param runnable      the <code>Runnable</code> whose
171      *                          <code>run</code> method will be executed
172      * @param notifier      the <code>Object whose <code>notifyAll</code>
173      *                          method will be called after
174      *                          <code>Runnable.run</code> has returned
175      * @param catchThrowables   specifies whether <code>dispatch</code>
176      *                          should catch Throwable when executing the
177      *                          <code>Runnable</code>'s <code>run</code>
178      *                          method, or should instead propagate those
179      *                          Throwables to the EventDispatchThread's
180      *                          dispatch loop
181      * @throws IllegalArgumentException if <code>source</code> is null
182      */
183     protected InvocationEvent(Object   source, int id, Runnable   runnable, 
184                               Object   notifier, boolean catchThrowables) {
185         super(source, id);
186     this.runnable = runnable;
187     this.notifier = notifier;
188     this.catchExceptions = catchThrowables;
189         this.when = System.currentTimeMillis();
190     }
191 
192     /**
193      * Executes the Runnable's <code>run()</code> method and notifies the
194      * notifier (if any) when <code>run()</code> returns.
195      */
196     public void dispatch() {
197     if (catchExceptions) {
198         try {
199         runnable.run();
200         } 
201         catch (Throwable   t) {
202                 if (t instanceof Exception  ) {
203                     exception = (Exception  ) t;
204                 }
205                 throwable = t;
206         }
207     }
208     else {
209         runnable.run();
210     }
211 
212     if (notifier != null) {
213         synchronized (notifier) {
214         notifier.notifyAll();
215         }
216     }
217     }
218 
219     /**
220      * Returns any Exception caught while executing the Runnable's <code>run()
221      * </code> method.
222      *
223      * @return  A reference to the Exception if one was thrown; null if no
224      *      Exception was thrown or if this InvocationEvent does not
225      *      catch exceptions
226      */
227     public Exception   getException() {
228     return (catchExceptions) ? exception : null;
229     }
230 
231     /**
232      * Returns any Throwable caught while executing the Runnable's <code>run()
233      * </code> method.
234      *
235      * @return  A reference to the Throwable if one was thrown; null if no
236      *      Throwable was thrown or if this InvocationEvent does not
237      *      catch Throwables
238      */
239     public Throwable   getThrowable() {
240     return (catchExceptions) ? throwable : null;
241     }
242 
243     /**
244      * Returns the timestamp of when this event occurred.
245      *
246      * @return this event's timestamp
247      * @since 1.4
248      */
249     public long getWhen() {
250         return when;
251     }
252 
253     /**
254      * Returns a parameter string identifying this event.
255      * This method is useful for event-logging and for debugging.
256      *
257      * @return  A string identifying the event and its attributes
258      */
259     public String   paramString() {
260         String   typeStr;
261     switch(id) {
262             case INVOCATION_DEFAULT:
263             typeStr = "INVOCATION_DEFAULT";
264         break;
265             default:
266             typeStr = "unknown type";
267     }
268     return typeStr + ",runnable=" + runnable + ",notifier=" + notifier +
269         ",catchExceptions=" + catchExceptions + ",when=" + when;
270     }
271 }
272
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags