Package org.eclipse.emf.common.command

Class CompoundCommand

java.lang.Object
org.eclipse.emf.common.command.AbstractCommand
org.eclipse.emf.common.command.CompoundCommand
All Implemented Interfaces:
Command
Direct Known Subclasses:
StrictCompoundCommand
public class CompoundCommand extends AbstractCommand
A command that comprises a sequence of subcommands. Derived classes can control the way results are accumulated from the individual commands; the default behaviour is to return the result of the last command.

  • Field Details

    • commandList

      protected List<Command> commandList
      The list of subcommands.

    • LAST_COMMAND_ALL

      public static final int LAST_COMMAND_ALL
      When resultIndex is set to this, getResult() and getAffectedObjects() are delegated to the last command, if any, in the list.
      See Also:

    • MERGE_COMMAND_ALL

      public static final int MERGE_COMMAND_ALL
      When resultIndex is set to this, getResult() and getAffectedObjects() are set to the result of merging the corresponding collection of each command in the list.
      See Also:

    • resultIndex

      protected int resultIndex
      The index of the command whose result and affected objects are forwarded. Negative values have special meaning, as defined by the static constants. A value of -1 indicates that the last command in the list should be used. We could have more special behaviours implemented for other negative values.

  • Constructor Details

    • CompoundCommand

      public CompoundCommand()
      Creates an empty instance.

    • CompoundCommand

      public CompoundCommand(String label)
      Creates an instance with the given label.
      Parameters:
      label - the label.

    • CompoundCommand

      public CompoundCommand(String label, String description)
      Creates an instance with the given label and description.
      Parameters:
      label - the label.
      description - the description.

    • CompoundCommand

      public CompoundCommand(List<Command> commandList)
      Creates an instance with the given list.
      Parameters:
      commandList - the list of commands.

    • CompoundCommand

      public CompoundCommand(String label, List<Command> commandList)
      Creates instance with the given label and list.
      Parameters:
      label - the label.
      commandList - the list of commands.

    • CompoundCommand

      public CompoundCommand(String label, String description, List<Command> commandList)
      Creates an instance with the given label, description, and list.
      Parameters:
      label - the label.
      description - the description.
      commandList - the list of commands.

    • CompoundCommand

      public CompoundCommand(int resultIndex)
      Creates an empty instance with the given result index.
      Parameters:
      resultIndex - the resultIndex.

    • CompoundCommand

      public CompoundCommand(int resultIndex, String label)
      Creates an instance with the given result index and label.
      Parameters:
      resultIndex - the resultIndex.
      label - the label.

    • CompoundCommand

      public CompoundCommand(int resultIndex, String label, String description)
      Creates an instance with the given result index, label, and description.
      Parameters:
      resultIndex - the resultIndex.
      label - the label.
      description - the description.

    • CompoundCommand

      public CompoundCommand(int resultIndex, List<Command> commandList)
      Creates an instance with the given result index and list.
      Parameters:
      resultIndex - the resultIndex.
      commandList - the list of commands.

    • CompoundCommand

      public CompoundCommand(int resultIndex, String label, List<Command> commandList)
      Creates an instance with the given resultIndex, label, and list.
      Parameters:
      resultIndex - the resultIndex.
      label - the label.
      commandList - the list of commands.

    • CompoundCommand

      public CompoundCommand(int resultIndex, String label, String description, List<Command> commandList)
      Creates an instance with the given result index, label, description, and list.
      Parameters:
      resultIndex - the resultIndex.
      label - the label.
      description - the description.
      commandList - the list of commands.

  • Method Details

    • isEmpty

      public boolean isEmpty()
      Returns whether there are commands in the list.
      Returns:
      whether there are commands in the list.

    • getCommandList

      public List<Command> getCommandList()
      Returns an unmodifiable view of the commands in the list.
      Returns:
      an unmodifiable view of the commands in the list.

    • getResultIndex

      public int getResultIndex()
      Returns the index of the command whose result and affected objects are forwarded. Negative values have special meaning, as defined by the static constants.
      Returns:
      the index of the command whose result and affected objects are forwarded.
      See Also:

    • prepare

      protected boolean prepare()
      Returns whether all the commands can execute so that AbstractCommand.isExecutable can be cached. An empty command list causes false to be returned.
      Overrides:
      prepare in class AbstractCommand
      Returns:
      whether all the commands can execute.

    • execute

      public void execute()
      Calls Command.execute() for each command in the list.

    • canUndo

      public boolean canUndo()
      Returns false if any of the commands return false for Command.canUndo().
      Specified by:
      canUndo in interface Command
      Overrides:
      canUndo in class AbstractCommand
      Returns:
      false if any of the commands return false for canUndo.

    • undo

      public void undo()
      Calls Command.undo() for each command in the list, in reverse order.
      Specified by:
      undo in interface Command
      Overrides:
      undo in class AbstractCommand

    • redo

      public void redo()
      Calls Command.redo() for each command in the list.

    • getResult

      public Collection<?> getResult()
      Determines the result by composing the results of the commands in the list; this is affected by the setting of resultIndex.
      Specified by:
      getResult in interface Command
      Overrides:
      getResult in class AbstractCommand
      Returns:
      the result.

    • getMergedResultCollection

      protected Collection<?> getMergedResultCollection()
      Returns the merged collection of all command results.
      Returns:
      the merged collection of all command results.

    • getAffectedObjects

      public Collection<?> getAffectedObjects()
      Determines the affected objects by composing the affected objects of the commands in the list; this is affected by the setting of resultIndex.
      Specified by:
      getAffectedObjects in interface Command
      Overrides:
      getAffectedObjects in class AbstractCommand
      Returns:
      the affected objects.

    • getMergedAffectedObjectsCollection

      protected Collection<?> getMergedAffectedObjectsCollection()
      Returns the merged collection of all command affected objects.
      Returns:
      the merged collection of all command affected objects.

    • getLabel

      public String getLabel()
      Determines the label by composing the labels of the commands in the list; this is affected by the setting of resultIndex.
      Specified by:
      getLabel in interface Command
      Overrides:
      getLabel in class AbstractCommand
      Returns:
      the label.

    • getDescription

      public String getDescription()
      Determines the description by composing the descriptions of the commands in the list; this is affected by the setting of resultIndex.
      Specified by:
      getDescription in interface Command
      Overrides:
      getDescription in class AbstractCommand
      Returns:
      the description.

    • append

      public void append(Command command)
      Adds a command to this compound command's list of commands.
      Parameters:
      command - the command to append.

    • appendAndExecute

      public boolean appendAndExecute(Command command)
      Checks if the command can execute; if so, it is executed, appended to the list, and true is returned, if not, it is just disposed and false is returned. A typical use for this is to execute commands created during the execution of another command, e.g., 
         class MyCommand extends CommandBase
   {
     protected Command subcommand;

     //...

     public void execute()
     {
       // ...
       Compound subcommands = new CompoundCommand();
       subcommands.appendAndExecute(new AddCommand(...));
       if (condition) subcommands.appendAndExecute(new AddCommand(...));
       subcommand = subcommands.unwrap();
     }

     public void undo()
     {
       // ...
       subcommand.undo();
     }

     public void redo()
     {
       // ...
       subcommand.redo();
     }

     public void dispose()
     {
       // ...
       if (subcommand != null)
      {
         subcommand.dispose();
       }
     }
   }
      Another use is in an execute override of compound command itself: 
         class MyCommand extends CompoundCommand
   {
     public void execute()
     {
       // ...
       appendAndExecute(new AddCommand(...));
       if (condition) appendAndExecute(new AddCommand(...));
     }
   }
      Note that appending commands will modify what getResult and getAffectedObjects return, so you may want to set the resultIndex flag.
      Parameters:
      command - the command.
      Returns:
      whether the command was successfully executed and appended.

    • appendIfCanExecute

      public boolean appendIfCanExecute(Command command)
      Adds a command to this compound command's the list of commands and returns true, if command.canExecute() returns true; otherwise, it simply calls command.dispose() and returns false.
      Parameters:
      command - the command.
      Returns:
      whether the command was executed and appended.

    • dispose

      public void dispose()
      Calls Command.dispose() for each command in the list.
      Specified by:
      dispose in interface Command
      Overrides:
      dispose in class AbstractCommand

    • unwrap

      public Command unwrap()
      Returns one of three things: UnexecutableCommand.INSTANCE, if there are no commands, the one command, if there is exactly one command, or this, if there are multiple commands; this command is dispose()d in the first two cases. You should only unwrap a compound command if you created it for that purpose, e.g., 
         CompoundCommand subcommands = new CompoundCommand();
   subcommands.append(x);
   if (condition) subcommands.append(y);
   Command result = subcommands.unwrap();
      is a good way to create an efficient accumulated result.
      Returns:
      the unwrapped command.

    • toString

      public String toString()
      Description copied from class: AbstractCommand
      Returns an abbreviated name using this object's own class' name, without package qualification, followed by a space separated list of field:value pairs.
      Overrides:
      toString in class AbstractCommand
      Returns:
      string representation.