## org.eclipse.emf.common.command
Interface Command

All Known Subinterfaces:
  OverrideableCommand

All Known Implementing Classes:
  AbstractCommand, AbstractOverrideableCommand, AddCommand, AddMappingCommand, AddOverrideCommand, ChangeCommand, CommandWrapper, CompoundCommand, ControlAction.SelfAffectingCommand, CopyCommand, CopyToClipboardCommand, CopyToClipboardOverrideCommand, CreateChildCommand, CreateCopyCommand, CreateCopyOverrideCommand, CreateMappingAction.DelegateCommand, CreateMappingCommand, CreateOneSidedMappingAction.DelegateCommand, CutToClipboardCommand, DelegatingWrapperItemProvider.AffectedObjectsWrappingCommand, DelegatingWrapperItemProvider.AffectedObjectsWrappingCommandActionDelegate, DeleteCommand, DragAndDropCommand, DragAndDropOverrideCommand, Ecore2EcoreEditor.Ecore2EcoreInitializeCopyOverrideCommand, IdentityCommand, InitializeCopyCommand, InitializeCopyOverrideCommand, ItemProviderAdapter.ResultAndAffectedObjectsWrappingCommand, ItemProviderAdapter.ResultAndAffectedObjectsWrappingCommandActionDelegate, MatchMappingCommand, MoveCommand, NameMatchMappingAction.DelegateCommand, NameMatchMappingCommand, PasteFromClipboardCommand, PasteFromClipboardOverrideCommand, RemoveCommand, RemoveMappingAction.CommandDelegate, RemoveMappingCommand, RemoveOverrideCommand, ReplaceCommand, RestoreInitialStateCommand, SetCommand, SetCommand.PessimisticStrictCompoundCommand, SetOverrideCommand, StrictCompoundCommand, TypeMatchMappingAction.DelegateCommand, TypeMatchMappingCommand, UnexecutableCommand, WrapperItemProvider.ReplacementAffectedObjectCommand, WrapperItemProvider.SimpleCopyCommand, WrapperItemProvider.WrappingCopyCommand

    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
`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.
`java.util.Collection<?>` `getAffectedObjects()` Returns the collection of things which this command wishes to present as the objects affected by the command.
`java.lang.String` `getDescription()` Returns a string suitable to help describe the effect of this command.
`java.lang.String` `getLabel()` Returns a string suitable to represent the label that identifies this command.
`java.util.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 Detail

### 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

    java.util.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

    java.util.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

    java.lang.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

    java.lang.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.

Copyright 2001-2006 IBM Corporation and others. All Rights Reserved.