Package org.eclipse.emf.common.command

Interface Command

All Known Implementing Classes:
AbstractCommand, CommandWrapper, CompoundCommand, IdentityCommand, StrictCompoundCommand, UnexecutableCommand
public interface Command
An interface that every command is expected to support. A command can be tested for executability, it can be executed, it can be tested for undoability, it can be undone, and can then be redone. A command also provides access to a result collection, an affected-objects collection, a label, and a description.

There are important constraints on the valid order in which the various methods may be invoked, e.g., you cannot ask for the result before you've executed the command. These constraints are documented with the various methods.

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    canExecute()
    Returns whether the command is valid to execute.
    boolean
    canUndo()
    Returns whether the command can be undone.
    Command
    chain(Command command)
    Returns a command that represents the composition of this command with the given command.
    void
    dispose()
    Called to indicate that the command will never be used again.
    void
    execute()
    Performs the command activity required for the effect.
    Collection<?>
    getAffectedObjects()
    Returns the collection of things which this command wishes to present as the objects affected by the command.
    String
    getDescription()
    Returns a string suitable to help describe the effect of this command.
    String
    getLabel()
    Returns a string suitable to represent the label that identifies this command.
    Collection<?>
    getResult()
    Returns a collection of things which this command wishes to present as it's result.
    void
    redo()
    Performs the command activity required to redo the effect after undoing the effect.
    void
    undo()
    Performs the command activity required to undo the effects of a preceding execute (or redo).

  • Method Details

    • canExecute

      boolean canExecute()
      Returns whether the command is valid to execute. The UnexecutableCommand.INSTANCE.canExecute() always returns false. This must be called before calling execute.
      Returns:
      whether the command is valid to execute.

    • execute

      void execute()
      Performs the command activity required for the effect. The effect of calling execute when canExecute returns false, or when canExecute hasn't been called, is undefined.

    • canUndo

      boolean canUndo()
      Returns whether the command can be undone. The result of calling this before execute is well defined, but the result of calling this before calling canExecute is undefined, i.e., a command that returns false for canExecute may return true for canUndo, even though that is a contradiction.
      Returns:
      whether the command can be undone.

    • undo

      void undo()
      Performs the command activity required to undo the effects of a preceding execute (or redo). The effect, if any, of calling undo before execute or redo have been called, or when canUndo returns false, is undefined.

    • redo

      void redo()
      Performs the command activity required to redo the effect after undoing the effect. The effect, if any, of calling redo before undo is called is undefined. Note that if you implement redo to call execute then any derived class will be restricted by that decision also.

    • getResult

      Collection<?> getResult()
      Returns a collection of things which this command wishes to present as it's result. The result of calling this before an execute or redo, or after an undo, is undefined.
      Returns:
      a collection of things which this command wishes to present as it's result.

    • getAffectedObjects

      Collection<?> getAffectedObjects()
      Returns the collection of things which this command wishes to present as the objects affected by the command. Typically should could be used as the selection that should be highlighted to best illustrate the effect of the command. The result of calling this before an execute, redo, or undo is undefined. The result may be different after an undo than it is after an execute or redo, but the result should be the same (equivalent) after either an execute or redo.
      Returns:
      the collection of things which this command wishes to present as the objects affected by the command.

    • getLabel

      String getLabel()
      Returns a string suitable to represent the label that identifies this command.
      Returns:
      a string suitable to represent the label that identifies this command.

    • getDescription

      String getDescription()
      Returns a string suitable to help describe the effect of this command.
      Returns:
      a string suitable to help describe the effect of this command.

    • dispose

      void dispose()
      Called to indicate that the command will never be used again. Calling any other method after this one has undefined results.

    • chain

      Command chain(Command command)
      Returns a command that represents the composition of this command with the given command. The resulting command may just be this, if this command is capable of composition. Otherwise, it will be a new command created to compose the two.

      Instead of the following pattern of usage 

         Command result = x;
   if (condition) result = result.chain(y);
      you should consider using a CompoundCommand and using CompoundCommand.unwrap() to optimize the result: 
         CompoundCommand subcommands = new CompoundCommand();
   subcommands.append(x);
   if (condition) subcommands.append(y);
   Command result = subcommands.unwrap();
      This gives you more control over how the compound command composes it's result and affected objects.
      Parameters:
      command - the command to chain.
      Returns:
      a command that represents the composition of this command with the given command.