Runtime

## org.eclipse.gmf.runtime.common.core.command
Class CompositeCommand

    java.lang.Object
      org.eclipse.core.commands.operations.AbstractOperation
          org.eclipse.gmf.runtime.common.core.command.AbstractCommand
              org.eclipse.gmf.runtime.common.core.command.CompositeCommand

All Implemented Interfaces:
  IUndoableOperation, ICommand, ICompositeCommand, org.eclipse.gmf.runtime.common.core.internal.command.ICommandWithSettableResult

    public class CompositeCommand

extends AbstractCommand
implements ICompositeCommand

An undoable command that is composed of child `IUndoableOperation`s that are not known to modify EMF model resources, but can contain model-affecting children. Execute, undo, redo and dispose result in execute, undo, redo and dispose on each child operation. The operation provides a list of `IFile`s that may be modified when the operation is executed, undone or redone.

The children are explicitly composed by a client before the composite is executed. Children cannot be added or removed after the composite has been executed.

The undo contexts of the composite are a union of the undo contexts of its children.

If a child command returns a cancel or an error status during execution, undo or redo, the remaining child commands are not processed and those that have already been executed are rolled back.

Constructor Summary
`CompositeCommand(java.lang.String label)` Initializes me with a label.
`CompositeCommand(java.lang.String label, java.util.List children)` Initializes me with a label and a list of child operations.

Method Summary
`void` `add(IUndoableOperation operation)` Adds a child operation to me.
`protected IStatus` `aggregateStatuses(java.util.List statuses)` Creates a suitable aggregate from these statuses.
`protected void` `assertNotExecuted()` Asserts that I have not yet been executed.
`boolean` `canExecute()` I can execute if I am not empty and all of my children can execute.
`boolean` `canRedo()` I can redo if I am not empty and all my children can all be redone.
`boolean` `canUndo()` I can undo if I am not empty and all my children can all be undone.
`static ICommand` `compose(ICommand command, ICommand next)` Appends a command onto a (possibly) existing composeite of commands.
`ICommand` `compose(IUndoableOperation operation)` Adds `command` to the list of commands with which this composite is composed.
`void` `dispose()` Disposes of each of my children.
`protected CommandResult` `doExecuteWithResult(IProgressMonitor progressMonitor, IAdaptable info)` Implements the execution logic by sequential execution of my children.
`protected CommandResult` `doRedoWithResult(IProgressMonitor progressMonitor, IAdaptable info)` I redo by asking my children to redo, in forward order.
`protected CommandResult` `doUndoWithResult(IProgressMonitor progressMonitor, IAdaptable info)` I undo by asking my children to undo, in reverse order.
`java.util.List` `getAffectedFiles()` Returns a list containing all of the affected files from `ICommand` children.
`protected java.util.List` `getChildren()` Obtains my nested operations.
`CommandResult` `getCommandResult()` Retrieves the result of executing, undoing, or redoing this command, depending on which of these operations was last performed.
`protected java.util.List` `getReturnValues()` Returns a list containing all of the return values from `ICommand` children.
`boolean` `isEmpty()` Answers whether or not this composite operation has children.
`protected boolean` `isExecuted()` Answers whether or not I have been executed.
`java.util.Iterator` `iterator()` Obtains an iterator to traverse my child operations.
`java.util.ListIterator` `listIterator()` Obtains an iterator to traverse my child operations in either direction.
`java.util.ListIterator` `listIterator(int index)` Obtains an iterator to traverse my child operations in either direction, starting from the specified `index`.
`ICommand` `reduce()` Returns the simplest form of this command that is equivalent.
`void` `remove(IUndoableOperation operation)` Removes a child operation from me.
`int` `size()` Queries the number of child operations that I contain.

Methods inherited from class org.eclipse.gmf.runtime.common.core.command.AbstractCommand
`execute, internalSetResult, redo, setResult, undo`

Methods inherited from class org.eclipse.core.commands.operations.AbstractOperation
`addContext, getContexts, getLabel, hasContext, removeContext, setLabel, toString`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Methods inherited from interface org.eclipse.gmf.runtime.common.core.command.ICommand
`setLabel`

Methods inherited from interface org.eclipse.core.commands.operations.IUndoableOperation
`addContext, execute, getContexts, getLabel, hasContext, redo, removeContext, undo`

Constructor Detail

### CompositeCommand

    public CompositeCommand(java.lang.String label)

  Initializes me with a label.

  Parameters:
    `label` - a user-readable label

### CompositeCommand

    public CompositeCommand(java.lang.String label,
                            java.util.List children)

  Initializes me with a label and a list of child operations.

  Parameters:
    `label` - a user-readable label
    `children` - a list of child `IUndoableOperation`s

Method Detail

### isEmpty

    public final boolean isEmpty()

  Answers whether or not this composite operation has children.

  Specified by:
    `isEmpty` in interface `ICompositeCommand`
  Returns:
    `true` if the operation does not have children, `false` otherwise.

### getChildren

    protected java.util.List getChildren()

  Obtains my nested operations. Note that the return result is mutable and is identical to my child-operation storage, so subclasses should be careful of adding or removing contents. This should ordinarily be done only via the `add(IUndoableOperation)` and `remove(IUndoableOperation)` methods because these maintain the undo contexts (or, equivalently, using the iterators).

  Returns:
    my list of children
  See Also:
    `add(IUndoableOperation)`, `remove(IUndoableOperation)`, `iterator()`, `listIterator(int)`

### size

    public int size()

  Description copied from interface: `ICompositeCommand`
  Queries the number of child operations that I contain.

  Specified by:
    `size` in interface `ICompositeCommand`
  Returns:
    my size

### add

    public void add(IUndoableOperation operation)

  Adds a child operation to me. This should only be done before I am executed. Has no effect if I already contain this operation as a child.

  Specified by:
    `add` in interface `ICompositeCommand`
  Parameters:
    `operation` - a new child operation
  Throws:
    `java.lang.IllegalStateException` - if I have already been successfully executed

### remove

    public void remove(IUndoableOperation operation)

  Removes a child operation from me. This should only be done before I am executed. Has no effect if I do not contain this operation as a child.

  Note that I do not dispose an operation when it is removed from me. Although this is specified in the contract of the `ICompositeOperation` interface, this would not be correct, as I did not create that operation.

  Specified by:
    `remove` in interface `ICompositeCommand`
  Parameters:
    `operation` - a child operation to remove
  Throws:
    `java.lang.IllegalStateException` - if I have already been successfully executed

### canExecute

    public boolean canExecute()

  I can execute if I am not empty and all of my children can execute.

  Specified by:
    `canExecute` in interface `IUndoableOperation`
  Overrides:
    `canExecute` in class `AbstractOperation`

### canRedo

    public boolean canRedo()

  I can redo if I am not empty and all my children can all be redone.

  Specified by:
    `canRedo` in interface `IUndoableOperation`
  Overrides:
    `canRedo` in class `AbstractOperation`

### canUndo

    public boolean canUndo()

  I can undo if I am not empty and all my children can all be undone.

  Specified by:
    `canUndo` in interface `IUndoableOperation`
  Overrides:
    `canUndo` in class `AbstractOperation`

### dispose

    public void dispose()

  Disposes of each of my children.

  Specified by:
    `dispose` in interface `IUndoableOperation`
  Overrides:
    `dispose` in class `AbstractCommand`

### compose

    public final ICommand compose(IUndoableOperation operation)

  Adds `command` to the list of commands with which this composite is composed.

  Specified by:
    `compose` in interface `ICommand`
  Overrides:
    `compose` in class `AbstractCommand`
  Parameters:
    `operation` - The command with which to compose this command.
  Returns:
    `this`.

### compose

    public static ICommand compose(ICommand command,
                                   ICommand next)

  Appends a command onto a (possibly) existing composeite of commands.

  Parameters:
    `command` - an existing command, which may be a composite, a single command, or `null`
    `next` - a command to append to the composite (may also be `null`, which produces no effect)
  Returns:
    the new composite, which is just `next` if `command` was `null`

### reduce

    public ICommand reduce()

  Returns the simplest form of this command that is equivalent. This is useful for removing unnecessary nesting of commands.

  If the composite has a single command, it returns the reduction of that single command. Otherwise, it returns itself.

  Specified by:
    `reduce` in interface `ICommand`
  Overrides:
    `reduce` in class `AbstractCommand`
  Returns:
    the simplest form of this command that is equivalent

### getReturnValues

    protected java.util.List getReturnValues()

  Returns a list containing all of the return values from `ICommand` children.

### doExecuteWithResult

    protected CommandResult doExecuteWithResult(IProgressMonitor progressMonitor,
                                                IAdaptable info)
                                         throws ExecutionException

  Implements the execution logic by sequential execution of my children.

  Specified by:
    `doExecuteWithResult` in class `AbstractCommand`
  Parameters:
    `progressMonitor` - the progress monitor provided by the operation history. Must never be `null`.
    `info` - the IAdaptable (or `null`) provided by the caller in order to supply UI information for prompting the user if necessary. When this parameter is not `null`, it should minimally contain an adapter for the org.eclipse.swt.widgets.Shell.class.
  Returns:
    The result of executing this command. May be `null` if the execution status is OK, but there is no meaningful result to be returned.
  Throws:
    `ExecutionException` - if, for some reason, I fail to complete the operation

### doRedoWithResult

    protected CommandResult doRedoWithResult(IProgressMonitor progressMonitor,
                                             IAdaptable info)
                                      throws ExecutionException

  I redo by asking my children to redo, in forward order.

  Specified by:
    `doRedoWithResult` in class `AbstractCommand`
  Parameters:
    `progressMonitor` - the progress monitor provided by the operation history. Must never be `null`.
    `info` - the IAdaptable (or `null`) provided by the caller in order to supply UI information for prompting the user if necessary. When this parameter is not `null`, it should minimally contain an adapter for the org.eclipse.swt.widgets.Shell.class.
  Returns:
    The result of redoing this command. May be `null` if the execution status is OK, but there is no meaningful result to be returned.
  Throws:
    `ExecutionException` - on failure to redo

### doUndoWithResult

    protected CommandResult doUndoWithResult(IProgressMonitor progressMonitor,
                                             IAdaptable info)
                                      throws ExecutionException

  I undo by asking my children to undo, in reverse order.

  Specified by:
    `doUndoWithResult` in class `AbstractCommand`
  Parameters:
    `progressMonitor` - the progress monitor provided by the operation history. Must never be `null`.
    `info` - the IAdaptable (or `null`) provided by the caller in order to supply UI information for prompting the user if necessary. When this parameter is not `null`, it should minimally contain an adapter for the org.eclipse.swt.widgets.Shell.class.
  Returns:
    The result of undoing this command. May be `null` if the execution status is OK, but there is no meaningful result to be returned.
  Throws:
    `ExecutionException` - on failure to undo

### aggregateStatuses

    protected IStatus aggregateStatuses(java.util.List statuses)

  Creates a suitable aggregate from these statuses. If there are no statuses to aggregate, then an OK status is returned. If there is a single status to aggregate, then it is returned. Otherwise, a multi-status is returned with the provided statuses as children.

  Parameters:
    `statuses` - the statuses to aggregate. May have zero, one, or more elements (all must be `IStatus`es)
  Returns:
    the multi-status

### isExecuted

    protected final boolean isExecuted()

  Answers whether or not I have been executed.

  Returns:
    `true` if I have been executed, `false` otherwise.

### assertNotExecuted

    protected final void assertNotExecuted()

  Asserts that I have not yet been executed. Changes to my children are not permitted after I have been executed.

### getAffectedFiles

    public java.util.List getAffectedFiles()

  Returns a list containing all of the affected files from `ICommand` children.

  Specified by:
    `getAffectedFiles` in interface `ICommand`
  Overrides:
    `getAffectedFiles` in class `AbstractCommand`
  Returns:
    the list of `IFile`s that will be modified

### iterator

    public java.util.Iterator iterator()

  Obtains an iterator to traverse my child operations. Removing children via this iterator correctly maintains my undo contexts.

  Specified by:
    `iterator` in interface `ICompositeCommand`
  Returns:
    an iterator of my children

### listIterator

    public java.util.ListIterator listIterator()

  Obtains an iterator to traverse my child operations in either direction. Adding and removing children via this iterator correctly maintains my undo contexts.

  Note that, unlike list iterators generally, this implementation does not permit the addition of an operation that I already contain (the composite does not permit duplicates). Moreover, only `IUndoableOperation`s may be added, otherwise `ClassCastException`s will result.

  Specified by:
    `listIterator` in interface `ICompositeCommand`
  Returns:
    an iterator of my children

### listIterator

    public java.util.ListIterator listIterator(int index)

  Obtains an iterator to traverse my child operations in either direction, starting from the specified `index`. Adding and removing children via this iterator correctly maintains my undo contexts.

  Note that, unlike list iterators generally, this implementation does not permit the addition of an operation that I already contain (the composite does not permit duplicates). Moreover, only `IUndoableOperation`s may be added, otherwise `ClassCastException`s will result.

  Specified by:
    `listIterator` in interface `ICompositeCommand`
  Parameters:
    `index` - the index in my children at which to start iterating
  Returns:
    an iterator of my children

### getCommandResult

    public CommandResult getCommandResult()

  Description copied from interface: `ICommand`
  Retrieves the result of executing, undoing, or redoing this command, depending on which of these operations was last performed. This value can be `null` if the operation has no meaningful result.

  The value of this result is undefined if the command has not yet been executed, undone or redone.

  Specified by:
    `getCommandResult` in interface `ICommand`
  Overrides:
    `getCommandResult` in class `AbstractCommand`
  Returns:
    The result of executing, undoing or redoing this command.

Runtime

Guidelines for using Eclipse APIs.

Copyright (c) IBM Corp., Borland Software Corp., and others 2005,2006. All rights reserved.