KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > emf > common > command > AbstractCommand


1 /**
2  * <copyright>
3  *
4  * Copyright (c) 2002-2004 IBM Corporation and others.
5  * All rights reserved. This program and the accompanying materials
6  * are made available under the terms of the Eclipse Public License v1.0
7  * which accompanies this distribution, and is available at
8  * http://www.eclipse.org/legal/epl-v10.html
9  *
10  * Contributors:
11  * IBM - Initial API and implementation
12  *
13  * </copyright>
14  *
15  * $Id: AbstractCommand.java,v 1.4 2005/06/08 05:44:08 nickb Exp $
16  */
17 package org.eclipse.emf.common.command;
18
19
20 import java.util.Collection JavaDoc;
21 import java.util.Collections JavaDoc;
22
23 import org.eclipse.emf.common.CommonPlugin;
24
25
26 /**
27  * An abstract implementation of a basic command.
28  * Each derived class <bold>must</bold> implement {@link Command#execute} and {@link Command#redo},
29  * <bold>must</bold> either implement {@link #undo} or implement {@link #canUndo} to return false,
30  * and <bold>must</bold> either override {@link #prepare} (this is the preferred approach) or can override {@link #canExecute} directly.
31  *
32  * <p>
33  * It is very convenient to use prepare, as it is guaranteed to be called only once just before canExecute is to be tested.
34  * It can be implemented to create any additional commands that need to be executed,
35  * and the result it yields becomes the permanent cached return value for canExecute.
36  *
37  */
38 public abstract class AbstractCommand implements Command
39 {
40   /**
41    * Keeps track of whether prepare needs to be called.
42    * It is tested in {@link #canExecute} so that {@link #prepare} is called exactly once to ready the command for execution.
43    */
44   protected boolean isPrepared;
45
46   /**
47    * Keeps track of whether the command is executable.
48    * It is set in {@link #canExecute} to the result of calling {@link #prepare}.
49    */
50   protected boolean isExecutable;
51
52   /**
53    * Holds a short textual description of the command
54    * as returned by {@link #getDescription} and set by {@link #setDescription}.
55    */
56   protected String JavaDoc description;
57
58   /**
59    * Holds the label of the command as returned by {@link #getLabel} and set by {@link #setLabel}.
60    */
61   protected String JavaDoc label;
62         
63   /**
64    * Creates an empty instance.
65    */
66   protected AbstractCommand()
67   {
68   }
69
70   /**
71    * Creates an instance with the given label.
72    * @param label the label.
73    */
74   protected AbstractCommand(String JavaDoc label)
75   {
76     this.label = label;
77   }
78   
79   /**
80    * Creates and instance with the given label and description.
81    * @param label the label.
82    * @param description the description.
83    */
84   protected AbstractCommand(String JavaDoc label, String JavaDoc description)
85   {
86     this.label = label;
87     this.description = description;
88   }
89
90   /**
91    * Called at most once in {@link #canExecute} to give the command an opportunity to ready itself for execution.
92    * The returned value is stored in {@link #canExecute}.
93    * In other words, you can override this method to initialize
94    * and to yield a cached value for the all subsequent calls to canExecute.
95    * @return whether the command is executable.
96    */
97   protected boolean prepare()
98   {
99     return false;
100   }
101
102   /**
103    * Calls {@link #prepare},
104    * caches the result in {@link #isExecutable},
105    * and sets {@link #isPrepared} to <code>true</code>;
106    * from then on, it will yield the value of isExecutable.
107    * @return whether the command can execute.
108    */
109   public boolean canExecute()
110   {
111     if (!isPrepared)
112     {
113       isExecutable = prepare();
114       isPrepared = true;
115     }
116
117     return isExecutable;
118   }
119
120   /**
121    * Returns <code>true</code> because most command should be undoable.
122    * @return <code>true</code>.
123    */
124   public boolean canUndo()
125   {
126     return true;
127   }
128
129   /**
130    * Throws a runtime exception.
131    * @exception UnsupportedOperationException always.
132    */
133   public void undo()
134   {
135     throw
136       new UnsupportedOperationException JavaDoc
137         (CommonPlugin.INSTANCE.getString
138            ("_EXC_Method_not_implemented", new String JavaDoc [] { this.getClass().getName() + ".undo()" }));
139   }
140
141   /**
142    * Returns an empty list.
143    * @return an empty list.
144    */
145   public Collection JavaDoc getResult()
146   {
147     return Collections.EMPTY_LIST;
148   }
149
150   /**
151    * Returns an empty list.
152    * @return an empty list.
153    */
154   public Collection JavaDoc getAffectedObjects()
155   {
156     return Collections.EMPTY_LIST;
157   }
158
159   /*
160    * Javadoc copied from interface.
161    */
162   public String JavaDoc getLabel()
163   {
164     return label == null ? CommonPlugin.INSTANCE.getString("_UI_AbstractCommand_label") : label;
165   }
166
167   /**
168    * Sets the label after construction.
169    * @param label the new label.
170    */
171   public void setLabel(String JavaDoc label)
172   {
173     this.label = label;
174   }
175   
176   /*
177    * Javadoc copied from interface.
178    */
179   public String JavaDoc getDescription()
180   {
181     return description == null ? CommonPlugin.INSTANCE.getString("_UI_AbstractCommand_description") : description;
182   }
183         
184   /**
185    * Sets the description after construction.
186    * @param description the new description.
187    */
188   public void setDescription(String JavaDoc description)
189   {
190     this.description = description;
191   }
192   
193   /**
194    * Creates a new compound command, containing this command and the given command,
195    * that delegates chain to {@link CompoundCommand#append}.
196    * @param command the command to chain with this one.
197    * @return a new chained compound command.
198    */
199   public Command chain(Command command)
200   {
201     class ChainedCompoundCommand extends CompoundCommand
202     {
203       public ChainedCompoundCommand()
204       {
205       }
206
207       public Command chain(Command c)
208       {
209         append(c);
210         return this;
211       }
212     }
213
214     CompoundCommand result = new ChainedCompoundCommand();
215     result.append(this);
216     result.append(command);
217     return result;
218   }
219
220   /*
221    * Javadoc copied from interface.
222    */
223   public void dispose()
224   {
225   }
226   
227   /**
228    * Returns an abbreviated name using this object's own class' name, without package qualification,
229    * followed by a space separated list of <tt>field:value</tt> pairs.
230    * @return string representation.
231    */
232   public String JavaDoc toString()
233   {
234     String JavaDoc className = getClass().getName();
235     int lastDotIndex = className.lastIndexOf('.');
236     StringBuffer JavaDoc result = new StringBuffer JavaDoc(lastDotIndex == -1 ? className : className.substring(lastDotIndex + 1));
237     result.append(" (label: " + label + ")");
238     result.append(" (description: " + description + ")");
239     result.append(" (isPrepared: " + isPrepared + ")");
240     result.append(" (isExecutable: " + isExecutable + ")");
241
242     return result.toString();
243   }
244
245   /**
246    * A marker interface implemented by commands that don't dirty the model.
247    */
248   public static interface NonDirtying
249   {
250   }
251 }
252
Popular Tags