KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > edu > rice > cs > util > swing > AsyncTask


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 JavaDoc;
37
38 /**
39  * The AsyncTask base class is a framework that facilitates execution of
40  * operations asynchronously in order to free up the event-handling thread. This
41  * task is passed to an implementation of the AsyncTaskLauncher to be run.
42  * <p>
43  * Any code that should be performed in asynchronously with the UI should be put
44  * in the <code>runAsync</code> method. Any code that is run in this method
45  * should NOT modify any Swing components at all. All modifications to Swing
46  * components must either be enqueued on the event-handling thread or performed
47  * in the <code>complete</code> method. If there is any data that must be
48  * passed from the asynchronous step to the completion step, it should be
49  * returned by the <code>runAsync</code> method. The same data returned by the
50  * <code>runAsync</code> method will be given to the <code>complete</code>
51  * method. In short, implementations of an AsyncTask need not manage the
52  * information passing between the task thread and the UI thread.
53  * <p>
54  * The <code>runAsync</code> method is given a progress monitor in order for
55  * the task to provide feedback to the user as to the progress of the task. The
56  * min and max values for the progress are specified by the
57  * <code>getMinProgress</code> and <code>getMaxProgress</code> methods in
58  * the task.
59  *
60  * @author jlugo
61  */
62 public abstract class AsyncTask<ParamType, ResType> {
63
64  private String JavaDoc _name;
65
66  /** Default Constructor */
67  public AsyncTask() { this("Untitled"); }
68
69  /** Creates a task that has the given name
70    * @param name The name of the task.
71    */
72  public AsyncTask(String JavaDoc name) { _name = name; }
73
74  /** This is the method of the task that is run on the separate thread. Any
75    * implementation of this method should not make any changes to GUI components
76    * unless those calls are made explicitly thread safe by the developer. Any
77    * code that modifies swing GUI components in any way should be located in the
78    * <code>complete</code> method.
79    *
80    * @param param
81    * Any parameter that should be passed to the task when it is
82    * executed
83    * @param monitor
84    * An object that handles the flow of information about the progress
85    * of the task both to and from the runAsync method. This also offers
86    * a means of passing a result from the async step to the completion
87    * step.
88    * @throws Exception
89    */
90  public abstract ResType runAsync(ParamType param, IAsyncProgress monitor) throws Exception JavaDoc;
91
92  /** This is the completion step where any modifications to swing components
93    * should be made. This method is called on the AWT event thread and so any
94    * changes made to swing components are safe.
95    */
96  public abstract void complete(AsyncCompletionArgs<ResType> args);
97
98  /** Sets the description of the task that should be displayed in the progress
99    * monitor that the user sees. While the task is in progress, a separate note
100    * can be set in order to display specific information about the progress of
101    * the task. This can be set by calling <code>ProgressMonitor.setNote</code>
102    *
103    * @return A brief description of the task being performed
104    */
105  public abstract String JavaDoc getDiscriptionMessage();
106
107  /** Returns the name of this specific type of task. If this is not overridden
108    * @return the name of the task
109    */
110  public String JavaDoc getName() { return _name; }
111
112  /** Returns the minimum value of the progress monitor
113    * @return The minimum value (0.0%) of the progress monitor
114    */
115  public int getMinProgress() { return 0; }
116
117  /** Reutrns the minimum value of the progress monitor
118    * @return The minimum value (100.0%) of the progress monitor
119    */
120  public int getMaxProgress() { return 100; }
121
122  public String JavaDoc toString() {
123   return getClass().getName() + ": " + getName() + " (@" + System.identityHashCode(this) + ")";
124  }
125 }
Popular Tags