AsyncTaskLauncher


1   /*BEGIN_COPYRIGHT_BLOCK
2    *
3    * This file is part of DrJava.  Download the current version of this project from http://www.drjava.org/
4    * or http://sourceforge.net/projects/drjava/
5    *
6    * DrJava Open Source License
7    * 
8    * Copyright (C) 2001-2005 JavaPLT group at Rice University (javaplt@rice.edu).  All rights reserved.
9    *
10   * Developed by:   Java Programming Languages Team, Rice University, http://www.cs.rice.edu/~javaplt/
11   * 
12   * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated 
13   * documentation files (the "Software"), to deal with the Software without restriction, including without limitation
14   * the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and 
15   * to permit persons to whom the Software is furnished to do so, subject to the following conditions:
16   * 
17   *     - Redistributions of source code must retain the above copyright notice, this list of conditions and the 
18   *       following disclaimers.
19   *     - Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the 
20   *       following disclaimers in the documentation and/or other materials provided with the distribution.
21   *     - Neither the names of DrJava, the JavaPLT, Rice University, nor the names of its contributors may be used to 
22   *       endorse or promote products derived from this Software without specific prior written permission.
23   *     - Products derived from this software may not be called "DrJava" nor use the term "DrJava" as part of their 
24   *       names without prior written permission from the JavaPLT group.  For permission, write to javaplt@rice.edu.
25   * 
26   * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO 
27   * THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 
28   * CONTRIBUTORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF 
29   * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS 
30   * WITH THE SOFTWARE.
31   * 
32   *END_COPYRIGHT_BLOCK*/
33  
34  package edu.rice.cs.util.swing;
35  
36  import javax.swing.ProgressMonitor  ;
37  
38  /**
39   * This is the base class to the component that launches the AsyncTask. It
40   * manages the multi-threading and ensures that the correct methods of the task
41   * are performed on the correct thread.
42   * 
43   * @author jlugo
44   */
45  public abstract class AsyncTaskLauncher {
46    
47    /**
48     * Returns whether the launcher should call
49     * <code>setParentContainerEnabled</code> both to dissable and to re-enable
50     * the parent. This gives the concrete implementation of the launcher more
51     * control in case dissabling and re-enabling the view could cause
52     * inconsistent behavior.
53     * <p>
54     * In some cases this should always be true, for instance, when for each call
55     * to lock the UI, you must call the unlock method an equal number of times to
56     * actually unlock the frame. If this were dissabling a normal swing
57     * component, where there is only on and off, you wouldn't want to re-enable
58     * the component if it was dissabled to begin with.
59     * 
60     * @return whether the launcher should call
61     *         <code>setParentContainerEnabled</code>
62     */
63    protected abstract boolean shouldSetEnabled();
64    
65    /**
66     * Sets the enabled state of the parent component. If the parent component is
67     * set to dissabled, this means that the user is unable to invoke any
68     * operations via mouse clicks or key strokes. <i><b>Note:</b> this method
69     * is called strictly on the event-handling thread.</i>
70     * 
71     * @param enabled
72     *          Whether the parent container should be enabled
73     */
74    protected abstract void setParentContainerEnabled(boolean enabled);
75    
76    /**
77     * Creates a progress monitor that can be used to provide feedback to the user
78     * during the asynchronous task. This progress monitor will also be used to
79     * allow the user to request the task to be canceled.
80     * <p>
81     * <i><b>Note:</b> this method is called strictly on the event-handling
82     * thread.</i>
83     * 
84     * @return The progress monitor used to provide feedback.
85     */
86    protected abstract IAsyncProgress createProgressMonitor(String   description, int min, int max);
87    
88    /**
89     * Executes the AsyncTask in its own thread after performing any needed steps
90     * to prepare the UI for its execution.
91     * 
92     * @param <R>
93     *          The type of result to pass from <code>runAsync</code> to
94     *          <code>complete</code>
95     * @param task
96     *          The task to execute on its own worker thread
97     * @param showProgress
98     *          Whether the progress monitor should be displayed to the user. If
99     *          it's value is false, the user will not be able to make any
100    *          cancelation requests to the task.
101    * @param lockUI
102    *          Whether the user should be able to interact with the rest of the
103    *          UI while the task is in progress
104    */
105   public <P, R> void executeTask(final AsyncTask<P, R> task, final P param, final boolean showProgress,
106                                  final boolean lockUI) {
107     Runnable   uiInit = new Runnable  () {
108       public void run() {
109         final boolean shouldUnlockUI = shouldSetEnabled() && lockUI;
110         final IAsyncProgress monitor = createProgressMonitor(task.getDiscriptionMessage(), 
111                                                              task.getMinProgress(), 
112                                                              task.getMaxProgress());
113         if (shouldSetEnabled() && lockUI) {
114           setParentContainerEnabled(false);
115         }
116         
117         Thread   taskThread = new Thread  (new Runnable  () {
118           public void run() {
119             R result = null;
120             Exception   caughtException = null;
121             try {
122               result = task.runAsync(param, monitor);
123             } catch (Exception   e) {
124               caughtException = e;
125             }
126             
127             final AsyncCompletionArgs<R> args = new AsyncCompletionArgs<R>(result, caughtException, monitor
128                                                                              .isCanceled());
129             
130             Runnable   cleanup = new Runnable  () {
131               public void run() {
132                 task.complete(args);
133                 
134                 if (shouldUnlockUI) {
135                   setParentContainerEnabled(true);
136                 }
137               }
138             };
139             
140             Utilities.invokeLater(cleanup);
141           }
142         }, "Task Thread - " + task.getName());
143         
144         taskThread.start();
145       }
146     };
147     
148     Utilities.invokeLater(uiInit);
149   }
150 }
151
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags