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 org.apache.commons.logging.Log;
19 import org.apache.commons.logging.LogFactory;
20
21 /**
22 * <p>
23 * An abstract base class for implementations of the <code>Command</code>
24 * interface.
25 * </p>
26 * <p>
27 * This abstract class provides some simple base implementations for methods
28 * required by the <code>Command</code> interface. It also defines some
29 * utility methods that are useful in GUI applications.
30 * </p>
31 * <p>
32 * The main execution method of course must be implemented in concrete sub
33 * classes. The <code>onException()</code> method passes the exception to a
34 * logger. For <code>onFinally()</code> an empty dummy implementation is
35 * provided. GUI updates can be performed in the <code>performGUIUpdate()</code>
36 * method. This method will be executed by a <code>Runnable</code> object in
37 * the application's event handler thread if the <code>UpdateGUI</code>
38 * property is set to <b>true</b>.
39 * </p>
40 *
41 * @author Oliver Heger
42 * @version $Id: CommandBase.java 205 2012-01-29 18:29:57Z oheger $
43 */
44 public abstract class CommandBase implements Command
45 {
46 /** A logger instance. */
47 private final Log log = LogFactory.getLog(CommandBase.class);
48
49 /** A flag if GUI updates should be performed. */
50 private final boolean updateGUI;
51
52 /** Stores the exception that was set using onException().*/
53 private volatile Throwable exception;
54
55 /**
56 * Creates a new instance of {@code CommandBase}. The {@code UpdateGUI}
57 * property is set to <b>true</b>.
58 */
59 protected CommandBase()
60 {
61 this(true);
62 }
63
64 /**
65 * Creates a new instance of {@code CommandBase} and sets the
66 * {@code UpdateGUI} property.
67 *
68 * @param updateGUI a flag if GUI updates are to be performed
69 */
70 protected CommandBase(boolean updateGUI)
71 {
72 this.updateGUI = updateGUI;
73 }
74
75 /**
76 * This method is called if an exception occurs. This implementation calls
77 * {@link #setException(Throwable)} to store the exception.
78 *
79 * @param t the exception
80 */
81 public void onException(Throwable t)
82 {
83 setException(t);
84 getLog().info("Command execution caused an exception", t);
85 }
86
87 /**
88 * This method is called after each command execution. This is an empty
89 * dummy implementation.
90 */
91 public void onFinally()
92 {
93 }
94
95 /**
96 * Returns a <code>Runnable</code> object for updating the GUI. This
97 * implementation returns either <b>null </b> or a <code>Runnable</code>
98 * object that invokes the <code>performGUIUpdate()</code> method,
99 * depending on the value of the <code>UpdateGUI</code> property.
100 *
101 * @return an object for updating the GUI
102 */
103 public Runnable getGUIUpdater()
104 {
105 return (isUpdateGUI()) ? new Runnable()
106 {
107 public void run()
108 {
109 performGUIUpdate();
110 }
111 } : null;
112 }
113
114 /**
115 * Returns the value of the {@code UpdateGUI} property. This flag can be set
116 * in the constructor. If set to <b>true</b>, the {@link #performGUIUpdate()}
117 * method will be invoked on the event dispatch thread after the command was
118 * executed. If a derived class needs a more complex logic that can be
119 * implemented using a final flag, it can override this method to return a
120 * value that is computed based on arbitrary criteria.
121 *
122 * @return the {@code UpdateGUI} property
123 */
124 public boolean isUpdateGUI()
125 {
126 return updateGUI;
127 }
128
129 /**
130 * Returns an exception that was thrown during the execution of this
131 * command. Result can be <b>null</b>, which means that no exception was
132 * thrown.
133 *
134 * @return an exception thrown during the execution of this command
135 */
136 public Throwable getException()
137 {
138 return exception;
139 }
140
141 /**
142 * Sets an exception that was thrown during the execution of this command.
143 * The {@link #onException(Throwable)} implementation invokes this method to
144 * store the exception passed to this method. It can then be queried by the
145 * methods invoked later in the command's life-cycle (e.g. {@code
146 * onFinally()} or {@code performGUIUpdate()}) to find out whether the
147 * command's execution was successful.
148 *
149 * @param exception an exception
150 */
151 public void setException(Throwable exception)
152 {
153 this.exception = exception;
154 }
155
156 /**
157 * Returns the logger used by this object.
158 *
159 * @return the logger
160 */
161 protected Log getLog()
162 {
163 return log;
164 }
165
166 /**
167 * Performs GUI updates. Here the code for thread safe GUI updates can be
168 * placed. If the {@code UpdateGUI} property is set, this method will
169 * automatically be invoked in the event dispatch thread after the command
170 * has been executed (also if an exception was thrown - in this case the
171 * exception can be queried using the {@link #getException()} method). This
172 * base implementation is empty.
173 */
174 protected void performGUIUpdate()
175 {
176 }
177 }