1 /*
2 * Copyright 2006-2016 The JGUIraffe Team.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License")
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package net.sf.jguiraffe.gui.cmd;
17
18 import net.sf.jguiraffe.gui.builder.utils.GUISynchronizer;
19
20 /**
21 * <p>
22 * Definition of an interface that describes a <em>command queue</em>.
23 * </p>
24 * <p>
25 * A command queue can be used by an application to execute longer-running tasks
26 * in the background without blocking the main event dispatching thread. This
27 * way the application will stay responsive. The command pattern also provides a
28 * suitable way of structuring the logic implemented in an application.
29 * </p>
30 * <p>
31 * The most important method in this interface is of course the
32 * <code>execute()</code> method, which allows scheduling new commands to be
33 * executed. With <code>shutdown()</code> the queue can be gracefully closed
34 * (commands that are contained in the queue or are currently executed will be
35 * finished before the queue actually shuts down). Further methods are available
36 * for checking the current status of the queue.
37 * </p>
38 *
39 * @author Oliver Heger
40 * @version $Id: CommandQueue.java 127 2008-05-24 15:59:16Z oheger $
41 */
42 public interface CommandQueue
43 {
44 /**
45 * Adds a new listener to this queue.
46 *
47 * @param l the event listener to add (must not be <b>null</b>)
48 * @throws IllegalArgumentException if the listener is undefined
49 */
50 void addQueueListener(CommandQueueListener l);
51
52 /**
53 * Removes the specified event listener from this command queue.
54 *
55 * @param l the listener to remove
56 */
57 void removeQueueListener(CommandQueueListener l);
58
59 /**
60 * Returns the <code>GUISynchronizer</code> that is used by this command
61 * queue.
62 *
63 * @return the GUI synchronizer
64 */
65 GUISynchronizer getGUISynchronizer();
66
67 /**
68 * Sets the <code>GUISynchronizer</code> to be used by this command queue.
69 * This object will be used to ensure that GUI updates performed by commands
70 * are done on the event dispatch thread.
71 *
72 * @param sync the GUI synchronizer
73 */
74 void setGUISynchronizer(GUISynchronizer sync);
75
76 /**
77 * Adds a new <code>Command</code> object to this queue. It will be
78 * executed as soon as the next worker thread is available.
79 *
80 * @param cmd the command to be executed (must not be <b>null</b>)
81 * @throws IllegalArgumentException if the command is <b>null</b>
82 * @throws IllegalStateException if <code>shutdown()</code> has already
83 * been called
84 */
85 void execute(Command cmd);
86
87 /**
88 * Checks if there are commands to be executed or in execution. This method
89 * can be called for instance if the user wants to exit the application to
90 * check if there are still running command threads.
91 *
92 * @return a flag if there are pending commands
93 */
94 boolean isPending();
95
96 /**
97 * Returns a flag if <code>shutdown()</code> was called. After that no
98 * commands can be executed any more.
99 *
100 * @return a flag if the queue is shut down
101 */
102 boolean isShutdown();
103
104 /**
105 * Initiates the shutdown sequence. New commands won't be accepted any more.
106 * The boolean parameter determines the kind of shutdown: If set to <b>false</b>,
107 * the commands contained in the queue will still be executed, and the
108 * method blocks until everything is complete. A value of <b>true</b>
109 * forces an immediate shutdown (as far as this is possible for a concrete
110 * implementation).
111 *
112 * @param immediate a flag how the shutdown should be performed
113 */
114 void shutdown(boolean immediate);
115 }