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.

Nested Class Summary

Nested classes/interfaces inherited from class org.eclipse.emf.common.command.AbstractCommand

AbstractCommand.NonDirtying

Field Summary

Fields

Modifier and Type	Field and Description
protected java.util.List<Command>	commandList The list of subcommands.
static int	LAST_COMMAND_ALL When resultIndex is set to this, getResult() and getAffectedObjects() are delegated to the last command, if any, in the list.
static 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.
protected int	resultIndex The index of the command whose result and affected objects are forwarded.

Fields inherited from class org.eclipse.emf.common.command.AbstractCommand

description, isExecutable, isPrepared, label

Constructor Summary

Constructors

Constructor and Description
CompoundCommand() Creates an empty instance.
CompoundCommand(int resultIndex) Creates an empty instance with the given result index.
CompoundCommand(int resultIndex, java.util.List<Command> commandList) Creates an instance with the given result index and list.
CompoundCommand(int resultIndex, java.lang.String label) Creates an instance with the given result index and label.
CompoundCommand(int resultIndex, java.lang.String label, java.util.List<Command> commandList) Creates an instance with the given resultIndex, label, and list.
CompoundCommand(int resultIndex, java.lang.String label, java.lang.String description) Creates an instance with the given result index, label, and description.
CompoundCommand(int resultIndex, java.lang.String label, java.lang.String description, java.util.List<Command> commandList) Creates an instance with the given result index, label, description, and list.
CompoundCommand(java.util.List<Command> commandList) Creates an instance with the given list.
CompoundCommand(java.lang.String label) Creates an instance with the given label.
CompoundCommand(java.lang.String label, java.util.List<Command> commandList) Creates instance with the given label and list.
CompoundCommand(java.lang.String label, java.lang.String description) Creates an instance with the given label and description.
CompoundCommand(java.lang.String label, java.lang.String description, java.util.List<Command> commandList) Creates an instance with the given label, description, and list.

Method Summary

Modifier and Type	Method and Description
void	append(Command command) Adds a command to this compound command's list of commands.
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.
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.
boolean	canUndo() Returns false if any of the commands return false for Command.canUndo().
void	dispose() Calls Command.dispose() for each command in the list.
void	execute() Calls Command.execute() for each command in the list.
java.util.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.
java.util.List<Command>	getCommandList() Returns an unmodifiable view of the commands in the list.
java.lang.String	getDescription() Determines the description by composing the descriptions of the commands in the list; this is affected by the setting of resultIndex.
java.lang.String	getLabel() Determines the label by composing the labels of the commands in the list; this is affected by the setting of resultIndex.
protected java.util.Collection<?>	getMergedAffectedObjectsCollection() Returns the merged collection of all command affected objects.
protected java.util.Collection<?>	getMergedResultCollection() Returns the merged collection of all command results.
java.util.Collection<?>	getResult() Determines the result by composing the results of the commands in the list; this is affected by the setting of resultIndex.
int	getResultIndex() Returns the index of the command whose result and affected objects are forwarded.
boolean	isEmpty() Returns whether there are commands in the list.
protected boolean	prepare() Returns whether all the commands can execute so that AbstractCommand.isExecutable can be cached.
void	redo() Calls Command.redo() for each command in the list.
java.lang.String	toString() Returns an abbreviated name using this object's own class' name, without package qualification, followed by a space separated list of field:value pairs.
void	undo() Calls Command.undo() for each command in the list, in reverse order.
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.

Methods inherited from class org.eclipse.emf.common.command.AbstractCommand

canExecute, chain, setDescription, setLabel

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

commandList

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

Constant Field Values

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:

Constant Field Values

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 Detail

CompoundCommand

public CompoundCommand()

Creates an empty instance.

CompoundCommand

public CompoundCommand(java.lang.String label)

Creates an instance with the given label.

Parameters:

label - the label.

CompoundCommand

public CompoundCommand(java.lang.String label,
                       java.lang.String description)

Creates an instance with the given label and description.

Parameters:

label - the label.

description - the description.

CompoundCommand

public CompoundCommand(java.util.List<Command> commandList)

Creates an instance with the given list.

Parameters:

commandList - the list of commands.

CompoundCommand

public CompoundCommand(java.lang.String label,
                       java.util.List<Command> commandList)

Creates instance with the given label and list.

Parameters:

label - the label.

commandList - the list of commands.

CompoundCommand

public CompoundCommand(java.lang.String label,
                       java.lang.String description,
                       java.util.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,
                       java.lang.String label)

Creates an instance with the given result index and label.

Parameters:

resultIndex - the resultIndex.

label - the label.

CompoundCommand

public CompoundCommand(int resultIndex,
                       java.lang.String label,
                       java.lang.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,
                       java.util.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,
                       java.lang.String label,
                       java.util.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,
                       java.lang.String label,
                       java.lang.String description,
                       java.util.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 Detail

isEmpty

public boolean isEmpty()

Returns whether there are commands in the list.

Returns:

whether there are commands in the list.

getCommandList

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

LAST_COMMAND_ALL, MERGE_COMMAND_ALL

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 java.util.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 java.util.Collection<?> getMergedResultCollection()

Returns the merged collection of all command results.

Returns:

the merged collection of all command results.

getAffectedObjects

public java.util.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 java.util.Collection<?> getMergedAffectedObjectsCollection()

Returns the merged collection of all command affected objects.

Returns:

the merged collection of all command affected objects.

getLabel

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