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 /**
19 * <p>
20 * Definition of an interface for command objects.
21 * </p>
22 * <p>
23 * This interface is a typical application of the famous <em>Command</em>
24 * pattern. It allows constructing objects that can be executed in a worker
25 * thread in the background of a Java GUI (e.g. Swing) application. This is
26 * important for every longer running task that would block the whole GUI (i.e.
27 * the event dispatch thread) otherwise. The life-cycle of a {@code Command}
28 * object is a follows:
29 * </p>
30 * <p>
31 * Objects implementing this interface can be passed to a {@link CommandQueue}
32 * object. When the {@code CommandQueue} object decides to execute the command
33 * it invokes its {@link #execute()} method in a background thread. {@code
34 * execute()} can implement whatever logic is needed for the command. It can
35 * also throw an arbitrary exception. If an exception is thrown, the command's
36 * {@link #onException(Throwable)} method is invoked (this also happens in the
37 * background thread). After completing {@code execute()} the
38 * {@link #onFinally()} method is invoked (it does not matter whether an
39 * exception occurred or not; this method is always called), also in the
40 * background thread.
41 * </p>
42 * <p>
43 * Command typically need to update the UI after executing their business logic.
44 * This must be done in the event dispatch thread. The {@code Command} interface
45 * supports updating the UI through its {@link #getGUIUpdater()} method. Here an
46 * implementation can return a {@code Runnable} object that will be executed
47 * synchronously on the event dispatch thread; here arbitrary updates of the
48 * application's UI can be performed.
49 * </p>
50 *
51 * @author Oliver Heger
52 * @version $Id: Command.java 205 2012-01-29 18:29:57Z oheger $
53 */
54 public interface Command
55 {
56 /**
57 * Executes this command. Here the business logic of this command has to be
58 * implemented. The {@code execute()} method is invoked on a background
59 * thread so that the event dispatch thread of the application is not
60 * blocked.
61 *
62 * @throws Exception if an error occurs
63 */
64 void execute() throws Exception;
65
66 /**
67 * Callback method that is invoked if an exception occurs during command
68 * execution. If {@link #execute()} throws an exception, this method is
69 * called (also on the background thread). Here actions like logging or
70 * special exception handling can be performed. Note that UI updates are not
71 * allowed in this method because it runs on a separate thread.
72 *
73 * @param t the exception that occurred
74 */
75 void onException(Throwable t);
76
77 /**
78 * This method will be executed after each command execution, no matter if
79 * an exception has occurred or not. It can be used for instance to free
80 * resources. Like {@code execute()} it is called on a background thread, so
81 * no UI updates are allowed.
82 */
83 void onFinally();
84
85 /**
86 * This method is invoked after the background processing of the command
87 * ends. It can return a {@code Runnable} object that will be executed in
88 * the application's event dispatching thread, which means that it is
89 * allowed to update GUI widgets. The idea of this method is that after a
90 * command has been executed often GUI updates have to be performed. These
91 * can be done using this mechanism in a safe manner.
92 *
93 * @return an object to be executed in the event dispatching thread (may be
94 * <b>null</b>
95 */
96 Runnable getGUIUpdater();
97 }