KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > foxtrot > Worker


1 /**
2  * Copyright (c) 2002-2005, Simone Bordet
3  * All rights reserved.
4  *
5  * This software is distributable under the BSD license.
6  * See the terms of the BSD license in the documentation provided with this software.
7  */
8
9 package foxtrot;
10
11 import foxtrot.workers.SingleWorkerThread;
12
13 /**
14  * The class that execute time-consuming {@link Task}s and {@link Job}s. <br />
15  * It is normally used in event listeners that must execute time-consuming operations without
16  * freezing the Swing GUI. <br />
17  * Usage example (simplified from the Foxtrot examples):
18  * <pre>
19  * JButton button = new JButton("Take a nap!");
20  * button.addActionListener(new ActionListener()
21  * {
22  * public void actionPerformed(ActionEvent e)
23  * {
24  * try
25  * {
26  * Worker.post(new Task()
27  * {
28  * public Object run() throws Exception
29  * {
30  * Thread.sleep(10000);
31  * return null;
32  * }
33  * });
34  * }
35  * catch (Exception ignored) {}
36  * }
37  * });
38  * </pre>
39  * While normally not necessary, it is possible to customize the two core components of this
40  * class, the {@link EventPump} and the {@link WorkerThread} via the corrispondent setter
41  * methods. <br />
42  * This class uses by default a WorkerThread that enqueues Tasks; Tasks will be executed one
43  * after the other. This is the behavior needed by most applications that want to rely on a
44  * synchronous model. For an alternative behavior, see {@link ConcurrentWorker}
45  * @version $Revision: 1.23 $
46  */
47 public class Worker extends AbstractSyncWorker
48 {
49    private static Worker instance = new Worker();
50
51    /**
52     * Cannot be instantiated, use static methods only.
53     */
54    private Worker()
55    {
56    }
57
58    /**
59     * Returns the WorkerThread used to run {@link foxtrot.Task}s subclasses in a thread
60     * that is not the Event Dispatch Thread.
61     * By default, the WorkerThread will enqueue the Tasks and execute them one after the
62     * other.
63     * @see #setWorkerThread
64     */
65    public static WorkerThread getWorkerThread()
66    {
67       return instance.workerThread();
68    }
69
70    /**
71     * Sets the WorkerThread used to run {@link foxtrot.Task}s subclasses in a thread
72     * that is not the Event Dispatch Thread.
73     * @see #getWorkerThread
74     * @throws java.lang.IllegalArgumentException If workerThread is null
75     */
76    public static void setWorkerThread(WorkerThread workerThread)
77    {
78       instance.workerThread(workerThread);
79    }
80
81    WorkerThread createDefaultWorkerThread()
82    {
83       return new SingleWorkerThread();
84    }
85
86    /**
87     * Returns the EventPump used to pump events from the AWT Event Queue. <br />
88     * If no calls to {@link #setEventPump} have been made a default pump is returned;
89     * this default pump is obtained by instantiating the suitable pump for the
90     * Java version that is running the code.
91     * @see #setEventPump
92     */
93    public static EventPump getEventPump()
94    {
95       return instance.eventPump();
96    }
97
98    /**
99     * Sets the EventPump to be used to pump events from the AWT Event Queue. <br />
100     * After calling this method, subsequent invocation of {@link #post(Task)}
101     * or {@link #post(Job)} will use the newly installed EventPump.
102     * Use with care, since implementing correcly a new EventPump is not easy.
103     * Foxtrot's default EventPumps are normally sufficient.
104     * @see #getEventPump
105     * @throws IllegalArgumentException If eventPump is null
106     */
107    public static void setEventPump(EventPump eventPump)
108    {
109       instance.eventPump(eventPump);
110    }
111
112    /**
113     * Enqueues the given Task to be executed by the WorkerThread, while dequeueing
114     * AWT events. <br />
115     * If this method is called from the Event Dispatch Thread, it blocks until the task
116     * has been executed, either by finishing normally or throwing an exception. <br />
117     * If this method is called from a worker thread, it executes the new Task
118     * immediately in the same thread and then returns the control to the calling Task. <br />
119     * While Tasks are executed, AWT events are dequeued from the AWT Event Queue;
120     * even in case of AWT events that throw RuntimeExceptions or Errors, this method will
121     * not return until the first Task (posted from the Event Dispatch Thread) is finished.
122     * @throws IllegalStateException if is not called from the Event Dispatch Thread nor
123     * from a worker thread.
124     * @see #post(Job job)
125     */
126    public static Object JavaDoc post(Task task) throws Exception JavaDoc
127    {
128       return instance.post(task, getWorkerThread(), getEventPump());
129    }
130
131    /**
132     * Enqueues the given Job to be executed in the worker thread. <br />
133     * This method behaves exactly like {@link #post(Task task)}, but it does not throw checked exceptions.
134     * @throws IllegalStateException if is not called from the Event Dispatch Thread nor from another Job or Task.
135     * @see #post(Task)
136     */
137    public static Object JavaDoc post(Job job)
138    {
139       return instance.post(job, getWorkerThread(), getEventPump());
140    }
141 }
142
Popular Tags