Source code: javax/ide/command/Command.java
1 package javax.ide.command;
2
3 import javax.ide.Identifiable;
4 import javax.ide.model.Document;
5
6 /**
7 * The <code>Command</code> interface defines the interface of all command
8 * objects. This interface consists of a procedure, <code>doit</code>, to
9 * execute a command. Concrete Command subclasses implement the necessary
10 * behavior to carry out a specific command.<p>
11 *
12 * This interface also provides additional methods necessary to implement
13 * the undo service provided by the <code>CommandProcessor</code>. For the
14 * undo mechanism it is necessary to distinguish three types of commands:<p>
15 *
16 * <ul>
17 * <li><code>NO_CHANGE</code>: A command that require no undo.</li><p>
18 * <li><code>NORMAL</code>: A command that can be undone.</li><p>
19 * <li><code>NO_UNDO</code>: A command that cannot be undone, and which
20 * prevents the undo of previously performed
21 * normal commands.</li><p>
22 * </ul>
23 *
24 * Commands are executed using the {@link javax.ide.command.CommandProcessor}.
25 * As <code>NORMAL</code> commands are executed, they are recorded by the
26 * command processor. This allows the command processor to perform undo and
27 * redo operations.
28 *
29 * @see javax.ide.command.CommandProcessor
30 */
31 public abstract class Command implements Identifiable
32 {
33 private Context _context;
34 private final int _type;
35
36 /**
37 * Indicates a command that can be undone.
38 */
39 public static final int NORMAL = 0;
40
41 /**
42 * Indicates a command that requires no undo.
43 */
44 public static final int NO_CHANGE = 1;
45
46 /**
47 * Indicates a command that cannot be undone, and which
48 * prevents the undo of previously performed normal commands.
49 */
50 public static final int NO_UNDO = 2;
51
52 /**
53 * Command execution OK status
54 */
55 public static final int OK = 0;
56
57 /**
58 * Command execution CANCEL status
59 */
60 public static final int CANCEL = 1;
61
62 protected Command()
63 {
64 this( NORMAL );
65 }
66
67 protected Command( int type )
68 {
69 _type = type;
70 }
71
72 /**
73 * Executes the actions associated with a specific command.
74 * When a command executes successfully, implementations should
75 * return OK, otherwise, return CANCEL or any other non-zero value.
76 */
77 public abstract int doit() throws Exception;
78
79 /**
80 * Called by the CommandProcessor to undo a command
81 * When a command executes successfully, implementations should
82 * return OK, otherwise, return CANCEL or any other non-zero value.
83 */
84 public abstract int undo() throws Exception;
85
86 /**
87 * Gets the name of the command to display as the action to undo
88 */
89 public abstract String getName();
90
91 /**
92 * Gets the command type
93 * @return The command type. Can be one of the following values:
94 * {@link #NORMAL}, {@link #NO_UNDO}, or {@link #NO_CHANGE}.
95 */
96 public final int getType()
97 {
98 return _type;
99 }
100
101 /**
102 * Gets the ide current {@link Context}.
103 */
104 protected final Context getContext()
105 {
106 return _context;
107 }
108
109 /**
110 * Sets {@link Context} associated with command
111 */
112 public final void setContext(Context context)
113 {
114 _context = context;
115 }
116
117 /**
118 * In general, the command processor manages undo stacks on a per
119 * {@link javax.ide.model.Document} basis. When the execution of a
120 * command affects more than the target document, the other affected
121 * documents undo stacks must be be flushed in order to maintain document
122 * consistency. This method should be called by the command processor
123 * implementations after a command is executed to determine if that
124 * command affects other documents.<p>
125 *
126 * The CommandProcessor uses the return value to clear the undo stack
127 * of the affected documents.<p>
128 *
129 * For commands of the NORMAL and NO_UNDO type, this method should return an
130 * array of documents affected by the execution of this command.
131 * This array should not include the primary document on which this
132 * command is operating, it should only include other documents affected
133 * as a side effect of executing this command. The affected documents
134 * undo stack will be flushed.<p>
135 *
136 * Commands of type NO_CHANGE should return an empty array. The default
137 * implementation returns an empty array.
138 *
139 * @return the documents affected by this command, otherwise, an empty
140 * array. This method must not return <code>null</code>.
141 */
142 public Document[] getAffectedDocuments()
143 {
144 return new Document[0];
145 }
146 }