001 /**
002 * <copyright>
003 *
004 * Copyright (c) 2002-2006 IBM Corporation and others.
005 * All rights reserved. This program and the accompanying materials
006 * are made available under the terms of the Eclipse Public License v1.0
007 * which accompanies this distribution, and is available at
008 * http://www.eclipse.org/legal/epl-v10.html
009 *
010 * Contributors:
011 * IBM - Initial API and implementation
012 *
013 * </copyright>
014 *
015 * $Id: Command.java,v 1.4 2007/06/12 20:56:17 emerks Exp $
016 */
017 package org.eclipse.emf.common.command;
018
019
020 import java.util.Collection;
021
022
023 /**
024 * An interface that every command is expected to support.
025 * A command can be tested for executability,
026 * it can be executed,
027 * it can be tested for undoability,
028 * it can be undone,
029 * and can then be redone.
030 * A command also provides access to a result collection, an affected-objects collection,
031 * a label, and a description.
032 *
033 * <p>
034 * There are important constraints on the valid order in which the various methods may be invoked,
035 * e.g., you cannot ask for the result before you've executed the command.
036 * These constraints are documented with the various methods.
037 */
038 public interface Command
039 {
040 /**
041 * Returns whether the command is valid to <code>execute</code>.
042 * The {@link UnexecutableCommand#INSTANCE}.<code>canExecute()</code> always returns <code>false</code>.
043 * This <b>must</b> be called before calling <code>execute</code>.
044 * @return whether the command is valid to <code>execute</code>.
045 */
046 boolean canExecute();
047
048 /**
049 * Performs the command activity required for the effect.
050 * The effect of calling <code>execute</code> when <code>canExecute</code> returns <code>false</code>,
051 * or when <code>canExecute</code> hasn't been called, is undefined.
052 */
053 void execute();
054
055 /**
056 * Returns whether the command can be undone.
057 * The result of calling this before <code>execute</code> is well defined,
058 * but the result of calling this before calling <code>canExecute</code> is undefined, i.e.,
059 * a command that returns <code>false</code> for <code>canExecute</code> may return <code>true</code> for canUndo,
060 * even though that is a contradiction.
061 * @return whether the command can be undone.
062 */
063 boolean canUndo();
064
065 /**
066 * Performs the command activity required to <code>undo</code> the effects of a preceding <code>execute</code> (or <code>redo</code>).
067 * The effect, if any, of calling <code>undo</code> before <code>execute</code> or <code>redo</code> have been called,
068 * or when canUndo returns <code>false</code>, is undefined.
069 */
070 void undo();
071
072 /**
073 * Performs the command activity required to <code>redo</code> the effect after undoing the effect.
074 * The effect, if any, of calling <code>redo</code> before <code>undo</code> is called is undefined.
075 * Note that if you implement <code>redo</code> to call <code>execute</code>
076 * then any derived class will be restricted by that decision also.
077 */
078 void redo();
079
080 /**
081 * Returns a collection of things which this command wishes to present as it's result.
082 * The result of calling this before an <code>execute</code> or <code>redo</code>, or after an <code>undo</code>, is undefined.
083 * @return a collection of things which this command wishes to present as it's result.
084 */
085 Collection<?> getResult();
086
087 /**
088 * Returns the collection of things which this command wishes to present as the objects affected by the command.
089 * Typically should could be used as the selection that should be highlighted to best illustrate the effect of the command.
090 * The result of calling this before an <code>execute</code>, <code>redo</code>, or <code>undo</code> is undefined.
091 * The result may be different after an <code>undo</code> than it is after an <code>execute</code> or <code>redo</code>,
092 * but the result should be the same (equivalent) after either an <code>execute</code> or <code>redo</code>.
093 * @return the collection of things which this command wishes to present as the objects affected by the command.
094 */
095 Collection<?> getAffectedObjects();
096
097 /**
098 * Returns a string suitable to represent the label that identifies this command.
099 * @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 capable 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 }