001: /*BEGIN_COPYRIGHT_BLOCK
002: *
003: * Copyright (c) 2001-2007, JavaPLT group at Rice University (javaplt@rice.edu)
004: * All rights reserved.
005: *
006: * Redistribution and use in source and binary forms, with or without
007: * modification, are permitted provided that the following conditions are met:
008: * * Redistributions of source code must retain the above copyright
009: * notice, this list of conditions and the following disclaimer.
010: * * Redistributions in binary form must reproduce the above copyright
011: * notice, this list of conditions and the following disclaimer in the
012: * documentation and/or other materials provided with the distribution.
013: * * Neither the names of DrJava, the JavaPLT group, Rice University, nor the
014: * names of its contributors may be used to endorse or promote products
015: * derived from this software without specific prior written permission.
016: *
017: * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
018: * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
019: * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
020: * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
021: * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
022: * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
023: * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
024: * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
025: * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
026: * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
027: * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
028: *
029: * This software is Open Source Initiative approved Open Source Software.
030: * Open Source Initative Approved is a trademark of the Open Source Initiative.
031: *
032: * This file is part of DrJava. Download the current version of this project
033: * from http://www.drjava.org/ or http://sourceforge.net/projects/drjava/
034: *
035: * END_COPYRIGHT_BLOCK*/
036:
037: package edu.rice.cs.util.swing;
038:
039: import javax.swing.ProgressMonitor;
040:
041: /**
042: * The AsyncTask base class is a framework that facilitates execution of
043: * operations asynchronously in order to free up the event-handling thread. This
044: * task is passed to an implementation of the AsyncTaskLauncher to be run.
045: * <p>
046: * Any code that should be performed in asynchronously with the UI should be put
047: * in the <code>runAsync</code> method. Any code that is run in this method
048: * should NOT modify any Swing components at all. All modifications to Swing
049: * components must either be enqueued on the event-handling thread or performed
050: * in the <code>complete</code> method. If there is any data that must be
051: * passed from the asynchronous step to the completion step, it should be
052: * returned by the <code>runAsync</code> method. The same data returned by the
053: * <code>runAsync</code> method will be given to the <code>complete</code>
054: * method. In short, implementations of an AsyncTask need not manage the
055: * information passing between the task thread and the UI thread.
056: * <p>
057: * The <code>runAsync</code> method is given a progress monitor in order for
058: * the task to provide feedback to the user as to the progress of the task. The
059: * min and max values for the progress are specified by the
060: * <code>getMinProgress</code> and <code>getMaxProgress</code> methods in
061: * the task.
062: *
063: * @author jlugo
064: */
065: public abstract class AsyncTask<ParamType, ResType> {
066:
067: private String _name;
068:
069: /** Default Constructor */
070: public AsyncTask() {
071: this ("Untitled");
072: }
073:
074: /** Creates a task that has the given name
075: * @param name The name of the task.
076: */
077: public AsyncTask(String name) {
078: _name = name;
079: }
080:
081: /** This is the method of the task that is run on the separate thread. Any
082: * implementation of this method should not make any changes to GUI components
083: * unless those calls are made explicitly thread safe by the developer. Any
084: * code that modifies swing GUI components in any way should be located in the
085: * <code>complete</code> method.
086: *
087: * @param param
088: * Any parameter that should be passed to the task when it is
089: * executed
090: * @param monitor
091: * An object that handles the flow of information about the progress
092: * of the task both to and from the runAsync method. This also offers
093: * a means of passing a result from the async step to the completion
094: * step.
095: * @throws Exception
096: */
097: public abstract ResType runAsync(ParamType param,
098: IAsyncProgress monitor) throws Exception;
099:
100: /** This is the completion step where any modifications to swing components
101: * should be made. This method is called on the AWT event thread and so any
102: * changes made to swing components are safe.
103: */
104: public abstract void complete(AsyncCompletionArgs<ResType> args);
105:
106: /** Sets the description of the task that should be displayed in the progress
107: * monitor that the user sees. While the task is in progress, a separate note
108: * can be set in order to display specific information about the progress of
109: * the task. This can be set by calling <code>ProgressMonitor.setNote</code>
110: *
111: * @return A brief description of the task being performed
112: */
113: public abstract String getDiscriptionMessage();
114:
115: /** Returns the name of this specific type of task. If this is not overridden
116: * @return the name of the task
117: */
118: public String getName() {
119: return _name;
120: }
121:
122: /** Returns the minimum value of the progress monitor
123: * @return The minimum value (0.0%) of the progress monitor
124: */
125: public int getMinProgress() {
126: return 0;
127: }
128:
129: /** Reutrns the minimum value of the progress monitor
130: * @return The minimum value (100.0%) of the progress monitor
131: */
132: public int getMaxProgress() {
133: return 100;
134: }
135:
136: public String toString() {
137: return getClass().getName() + ": " + getName() + " (@"
138: + System.identityHashCode(this ) + ")";
139: }
140: }
|