Command


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: Command.java,v 1.2 2005/06/08 05:44:08 nickb Exp $
16   */
17  package org.eclipse.emf.common.command;
18  
19  
20  import java.util.Collection  ;
21  
22  
23  /**
24   * An interface that every command is expected to support.
25   * A command can be tested for executability, 
26   * it can be executed, 
27   * it can be tested for undoability, 
28   * it can be undone, 
29   * and can then be redone.
30   * A comand also provides access to a result collection, an affected-objects collection,
31   * a label, and a description.
32   *
33   * <p>
34   * There are important constraints on the valid order in which the various methods may be invoked,
35   * e.g., you cannot ask for the result before you've executed the command.
36   * These constraints are documented with the various methods.
37   */
38  public interface Command 
39  {
40    /**
41     * Returns whether the comamad is valid to <code>execute</code>.
42     * The {@link UnexecutableCommand#INSTANCE}.<code>canExecute()</code> always returns <code>false</code>.
43     * This <b>must</b> be called before calling <code>execute</code>.
44     * @return whether the comamad is valid to <code>execute</code>.
45     */
46    boolean canExecute();
47  
48    /**
49     * Performs the command activity required for the effect.
50     * The effect of calling <code>execute</code> when <code>canExecute</code> returns <code>false</code>, 
51     * or when <code>canExecute</code> hasn't been called, is undefined.
52     */
53    void execute();
54  
55    /**
56     * Returns whether the command can be undone.
57     * The result of calling this before <code>execute</code> is well defined,
58     * but the result of calling this before calling <code>canExecute</code> is undefined, i.e.,
59     * a command that returns <code>false</code> for <code>canExecute</code> may return <code>true</code> for canUndo, 
60     * even though that is a contradiction.
61     * @return whether the command can be undone.
62     */
63    boolean canUndo();
64  
65    /**
66     * Performs the command activity required to <code>undo</code> the effects of a preceding <code>execute</code> (or <code>redo</code>).
67     * The effect, if any, of calling <code>undo</code> before <code>execute</code> or <code>redo</code> have been called, 
68     * or when canUndo returns <code>false</code>, is undefined.
69     */
70    void undo();
71  
72    /**
73     * Performs the command activity required to <code>redo</code> the effect after undoing the effect.
74     * The effect, if any, of calling <code>redo</code> before <code>undo</code> is called is undefined.
75     * Note that if you implement <code>redo</code> to call <code>execute</code> 
76     * then any derived class will be restricted by that decision also.
77     */
78    void redo();
79  
80    /**
81     * Returns a collection of things which this command wishes to present as it's result.
82     * The result of calling this before an <code>execute</code> or <code>redo</code>, or after an <code>undo</code>, is undefined.
83     * @return a collection of things which this command wishes to present as it's result.
84     */
85    Collection   getResult();
86  
87    /**
88     * Returns the collection of things which this command wishes to present as the objects affected by the command.
89     * Typically should could be used as the selection that should be highlighted to best illustrate the effect of the command.
90     * The result of calling this before an <code>execute</code>, <code>redo</code>, or <code>undo</code> is undefined.
91     * The result may be different after an <code>undo</code> than it is after an <code>execute</code> or <code>redo</code>,
92     * but the result should be the same (equivalent) after either an <code>execute</code> or <code>redo</code>.
93     * @return the collection of things which this command wishes to present as the objects affected by the command.
94     */
95    Collection   getAffectedObjects();
96  
97    /**
98     * Returns a string suitable to represent the label that identifies this command.
99     * @return a string suitable to represent the label that identifies this command.
100    */
101   String   getLabel();
102 
103   /**
104    * Returns a string suitable to help describe the effect of this command.
105    * @return a string suitable to help describe the effect of this command.
106    */
107   String   getDescription();
108 
109   /**
110    * Called to indicate that the command will never be used again.
111    * Calling any other method after this one has undefined results.
112    */
113   void dispose();
114 
115   /**
116    * Returns a command that represents the composition of this command with the given command.
117    * The resulting command may just be this, if this command is capabable of composition.
118    * Otherwise, it will be a new command created to compose the two.
119    * <p>
120    * Instead of the following pattern of usage
121    * <pre>
122    *   Command result = x;
123    *   if (condition) result = result.chain(y);
124    * </pre>
125    * you should consider using a {@link org.eclipse.emf.common.command.CompoundCommand} 
126    * and using {@link org.eclipse.emf.common.command.CompoundCommand#unwrap()} to optimize the result:
127    * <pre>
128    *   CompoundCommand subcommands = new CompoundCommand();
129    *   subcommands.append(x);
130    *   if (condition) subcommands.append(y);
131    *   Command result = subcommands.unwrap();
132    * </pre>
133    * This gives you more control over how the compound command composes it's result and affected objects.
134    * @param command the command to chain.
135    * @return a command that represents the composition of this command with the given command.
136    */
137   Command chain(Command command);
138 }
139
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags