Eclipse GMF Guide (Galileo) - CompositeCommand (Eclipse GMF Documentation)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

Runtime

PREV CLASS NEXT CLASS

NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

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
extends AbstractCommand
implements ICompositeCommand

An undoable command that is composed of child IUndoableOperations 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 IFiles 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 IUndoableOperations

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 IStatuses)
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 IFiles 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 IUndoableOperations may be added, otherwise ClassCastExceptions 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.

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.

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

Runtime

PREV CLASS NEXT CLASS

NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

Guidelines for using Eclipse APIs.

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

CompositeCommand

CompositeCommand

isEmpty

getChildren

size

add

remove

canExecute

canRedo

canUndo

dispose

compose

compose

reduce

getReturnValues

doExecuteWithResult

doRedoWithResult

doUndoWithResult

aggregateStatuses

isExecuted

assertNotExecuted

getAffectedFiles

iterator

listIterator

listIterator

getCommandResult

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