Package org.eclipse.core.commands.operations

# Class TriggeredOperations

java.lang.Object
org.eclipse.core.commands.operations.AbstractOperation
org.eclipse.core.commands.operations.TriggeredOperations

All Implemented Interfaces:
  `IAdvancedUndoableOperation`, `IAdvancedUndoableOperation2`, `ICompositeOperation`, `IContextReplacingOperation`, `IUndoableOperation`

public final class TriggeredOperations extends AbstractOperation implements ICompositeOperation, IAdvancedUndoableOperation, IAdvancedUndoableOperation2, IContextReplacingOperation
Triggered operations are a specialized implementation of a composite operation that keeps track of operations triggered by the execution of some primary operation. The composite knows which operation was the trigger for subsequent operations, and adds all triggered operations as children. When execution, undo, or redo is performed, only the triggered operation is executed, undone, or redone if it is still present. If the trigger is removed from the triggered operations, then the child operations will replace the triggered operations in the history.

This class may be instantiated by clients.

Since:
  3.1

## Constructor Summary

Constructors
Constructor
Description
`TriggeredOperations(IUndoableOperation operation, IOperationHistory history)`
Construct a composite triggered operations using the specified undoable operation as the trigger.

## Method Summary

Modifier and Type
Method
Description
`void`
`aboutToNotify(OperationHistoryEvent event)`
An operation history notification about this operation is about to be sent to operation history listeners.
`void`
`add(IUndoableOperation operation)`
Add the specified operation as a child of this operation.
`void`
`addContext(IUndoContext context)`
Add the specified context to the operation.
`boolean`
`canExecute()`
Returns whether the operation can be executed in its current state.
`boolean`
`canRedo()`
Returns whether the operation can be redone in its current state.
`boolean`
`canUndo()`
Returns whether the operation can be undone in its current state.
`IStatus`
`computeExecutionStatus(IProgressMonitor monitor)`
Return a status indicating the projected outcome of executing the receiver.
`IStatus`
`computeRedoableStatus(IProgressMonitor monitor)`
Return a status indicating the projected outcome of redoing the receiver.
`IStatus`
`computeUndoableStatus(IProgressMonitor monitor)`
Return a status indicating the projected outcome of undoing the receiver.
`void`
`dispose()`
Dispose of the operation.
`IStatus`
`execute(IProgressMonitor monitor, IAdaptable info)`
Execute the operation.
`Object[]`
`getAffectedObjects()`
Return an array of objects that are affected by executing, undoing, or redoing this operation.
`IUndoableOperation`
`getTriggeringOperation()`
Return the operation that triggered the other operations in this composite.
`IStatus`
`redo(IProgressMonitor monitor, IAdaptable info)`
Redo the operation.
`void`
`remove(IUndoableOperation operation)`
Remove the specified operation from this operation.
`void`
`removeContext(IUndoContext context)`
Remove the specified context from the receiver.
`void`
`replaceContext(IUndoContext original, IUndoContext replacement)`
Replace the undo context of the receiver with the provided replacement undo context.
`boolean`
`runInBackground()`
Return a boolean that instructs whether the operation should be executed, undone, or redone in a background thread.
`void`
`setQuietCompute(boolean quiet)`
Set a boolean that instructs whether the computation of the receiver's execution, undo, or redo status should quietly compute status without consulting or prompting the user.
`IStatus`
`undo(IProgressMonitor monitor, IAdaptable info)`
Undo the operation.

### Methods inherited from class org.eclipse.core.commands.operations.AbstractOperation

`getContexts, getLabel, hasContext, 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.core.commands.operations.IUndoableOperation

`getContexts, getLabel, hasContext`

## Constructor Details

### TriggeredOperations

public TriggeredOperations(IUndoableOperation operation, IOperationHistory history)
Construct a composite triggered operations using the specified undoable operation as the trigger. Use the label of this trigger as the label of the operation.

Parameters:
  `operation` - the operation that will trigger other operations.
  `history` - the operation history containing the triggered operations.

## Method Details

### add

public void add(IUndoableOperation operation)
Description copied from interface: `ICompositeOperation`

Add the specified operation as a child of this operation.

Specified by:
  `add` in interface `ICompositeOperation`
Parameters:
  `operation` - the operation to be added. If the operation instance has already been added, this method will have no effect.

### remove

public void remove(IUndoableOperation operation)
Description copied from interface: `ICompositeOperation`

Remove the specified operation from this operation.

The composite operation should dispose the operation as part of removing it.

Specified by:
  `remove` in interface `ICompositeOperation`
Parameters:
  `operation` - the operation to be removed. The operation should be disposed by the receiver. This method will have no effect if the operation instance is not already a child.

### removeContext

public void removeContext(IUndoContext context)
Remove the specified context from the receiver. This method is typically invoked when the history is being flushed for a certain context. In the case of triggered operations, if the only context for the triggering operation is being removed, then the triggering operation must be replaced in the operation history with the atomic operations that it triggered. If the context being removed is not the only context for the triggering operation, the triggering operation will remain, and the children will each be similarly checked.

Specified by:
  `removeContext` in interface `IUndoableOperation`
Overrides:
  `removeContext` in class `AbstractOperation`
Parameters:
  `context` - the undo context being removed from the receiver.

### execute

public IStatus execute(IProgressMonitor monitor, IAdaptable info) throws ExecutionException
Description copied from interface: `IUndoableOperation`
Execute the operation. This method should only be called the first time that an operation is executed.

Specified by:
  `execute` in interface `IUndoableOperation`
Specified by:
  `execute` in class `AbstractOperation`
Parameters:
  `monitor` - the progress monitor (or `null`) to use for reporting progress to the user.
  `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 IStatus of the execution. The status severity should be set to `OK` if the operation was successful, and `ERROR` if it was not. Any other status is assumed to represent an incompletion of the execution.
Throws:
  `ExecutionException` - if an exception occurred during execution.

### redo

public IStatus redo(IProgressMonitor monitor, IAdaptable info) throws ExecutionException
Description copied from interface: `IUndoableOperation`
Redo the operation. This method should only be called after an operation has been undone.

Specified by:
  `redo` in interface `IUndoableOperation`
Specified by:
  `redo` in class `AbstractOperation`
Parameters:
  `monitor` - the progress monitor (or `null`) to use for reporting progress to the user.
  `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 IStatus of the redo. The status severity should be set to `OK` if the redo was successful, and `ERROR` if it was not. Any other status is assumed to represent an incompletion of the redo.
Throws:
  `ExecutionException` - if an exception occurred during redo.

### undo

public IStatus undo(IProgressMonitor monitor, IAdaptable info) throws ExecutionException
Description copied from interface: `IUndoableOperation`
Undo the operation. This method should only be called after an operation has been executed.

Specified by:
  `undo` in interface `IUndoableOperation`
Specified by:
  `undo` in class `AbstractOperation`
Parameters:
  `monitor` - the progress monitor (or `null`) to use for reporting progress to the user.
  `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 IStatus of the undo. The status severity should be set to `OK` if the redo was successful, and `ERROR` if it was not. Any other status is assumed to represent an incompletion of the undo.
Throws:
  `ExecutionException` - if an exception occurred during undo.

### canUndo

public boolean canUndo()
Description copied from interface: `IUndoableOperation`

Returns whether the operation can be undone in its current state.

Note: The computation for this method must be fast, as it is called frequently. If necessary, this method can be optimistic in its computation (returning true) and later perform more time-consuming computations during the actual undo of the operation, returning the appropriate status if the operation cannot actually be undone at that time.

Specified by:
  `canUndo` in interface `IUndoableOperation`
Overrides:
  `canUndo` in class `AbstractOperation`
Returns:
  `true` if the operation can be undone; `false` otherwise.

### canExecute

public boolean canExecute()
Description copied from interface: `IUndoableOperation`

Returns whether the operation can be executed in its current state.

Note: The computation for this method must be fast, as it is called frequently. If necessary, this method can be optimistic in its computation (returning true) and later perform more time-consuming computations during the actual execution of the operation, returning the appropriate status if the operation cannot actually execute at that time.

Specified by:
  `canExecute` in interface `IUndoableOperation`
Overrides:
  `canExecute` in class `AbstractOperation`
Returns:
  `true` if the operation can be executed; `false` otherwise.

### canRedo

public boolean canRedo()
Description copied from interface: `IUndoableOperation`

Returns whether the operation can be redone in its current state.

Note: The computation for this method must be fast, as it is called frequently. If necessary, this method can be optimistic in its computation (returning true) and later perform more time-consuming computations during the actual redo of the operation, returning the appropriate status if the operation cannot actually be redone at that time.

Specified by:
  `canRedo` in interface `IUndoableOperation`
Overrides:
  `canRedo` in class `AbstractOperation`
Returns:
  `true` if the operation can be redone; `false` otherwise.

### dispose

public void dispose()
Description copied from interface: `IUndoableOperation`
Dispose of the operation. This method is used when the operation is no longer kept in the history. Implementers of this method typically unregister any listeners.

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

### getTriggeringOperation

public IUndoableOperation getTriggeringOperation()
Return the operation that triggered the other operations in this composite.

Returns:
  the IUndoableOperation that triggered the other children or `null` if the triggeringOperation was removed
See Also:
  - `remove(IUndoableOperation)`

### getAffectedObjects

public Object[] getAffectedObjects()
Description copied from interface: `IAdvancedUndoableOperation`

Return an array of objects that are affected by executing, undoing, or redoing this operation. If it cannot be determined which objects are affected, return null.

Specified by:
  `getAffectedObjects` in interface `IAdvancedUndoableOperation`
Returns:
  the array of Objects modified by this operation, or `null` if the affected objects cannot be determined.

### aboutToNotify

public void aboutToNotify(OperationHistoryEvent event)
Description copied from interface: `IAdvancedUndoableOperation`

An operation history notification about this operation is about to be sent to operation history listeners. Any preparation needed before listeners are notified about this operation should be performed here.

This method has been added to support legacy undo frameworks that are adapting to IUndoableOperation. Operations that previously relied on notification from their containing history or stack before any listeners are notified about changes to the operation should implement this interface.

Specified by:
  `aboutToNotify` in interface `IAdvancedUndoableOperation`
Parameters:
  `event` - the event that is about to be sent with the pending notification

### computeUndoableStatus

public IStatus computeUndoableStatus(IProgressMonitor monitor) throws ExecutionException
Description copied from interface: `IAdvancedUndoableOperation`
Return a status indicating the projected outcome of undoing the receiver. This method should be used to report the possible outcome of an undo and is used when computing the validity of an undo is too expensive to perform in `IUndoableOperation.canUndo()`. It is not called by the operation history, but instead is used by clients (such as implementers of `IOperationApprover`) who wish to perform advanced validation of an operation before attempting to undo it. If the result of this method is the discovery that an operation can in fact not be undone, then the operation is expected to correctly answer `false` on subsequent calls to `IUndoableOperation.canUndo()`.

Specified by:
  `computeUndoableStatus` in interface `IAdvancedUndoableOperation`
Parameters:
  `monitor` - the progress monitor (or `null`) to use for reporting progress to the user while computing the validity.
Returns:
  the IStatus indicating the validity of the undo. The status severity should be set to `OK` if the undo can successfully be performed, and `ERROR` if it cannnot. Any other status is assumed to represent an ambiguous state.
Throws:
  `ExecutionException` - if an exception occurs while computing the validity.

### computeRedoableStatus

public IStatus computeRedoableStatus(IProgressMonitor monitor) throws ExecutionException
Description copied from interface: `IAdvancedUndoableOperation`
Return a status indicating the projected outcome of redoing the receiver. This method should be used to report the possible outcome of a redo and is used when computing the validity of a redo is too expensive to perform in `IUndoableOperation.canRedo()`. It is not called by the operation history, but instead is used by clients (such as implementers of `IOperationApprover`) who wish to perform advanced validation of an operation before attempting to redo it. If the result of this method is the discovery that an operation can in fact not be redone, then the operation is expected to correctly answer `false` on subsequent calls to `IUndoableOperation.canRedo()`.

Specified by:
  `computeRedoableStatus` in interface `IAdvancedUndoableOperation`
Parameters:
  `monitor` - the progress monitor (or `null`) to use for reporting progress to the user while computing the validity.
Returns:
  the IStatus indicating the validity of the redo. The status severity should be set to `OK` if the redo can successfully be performed, and `ERROR` if it cannnot. Any other status is assumed to represent an ambiguous state.
Throws:
  `ExecutionException` - if an exception occurs while computing the validity.

### replaceContext

public void replaceContext(IUndoContext original, IUndoContext replacement)
Replace the undo context of the receiver with the provided replacement undo context. In the case of triggered operations, all contained operations are checked and any occurrence of the original context is replaced with the new undo context.

This message has no effect if the original undo context is not present in the receiver.

Specified by:
  `replaceContext` in interface `IContextReplacingOperation`
Parameters:
  `original` - the undo context which is to be replaced
  `replacement` - the undo context which is replacing the original
Since:
  3.2

### addContext

public void addContext(IUndoContext context)
Add the specified context to the operation. Overridden in TriggeredOperations to add the specified undo context to the triggering operation.

Specified by:
  `addContext` in interface `IUndoableOperation`
Overrides:
  `addContext` in class `AbstractOperation`
Parameters:
  `context` - the context to be added
Since:
  3.2

### computeExecutionStatus

public IStatus computeExecutionStatus(IProgressMonitor monitor) throws ExecutionException
Description copied from interface: `IAdvancedUndoableOperation2`
Return a status indicating the projected outcome of executing the receiver. This method should be used to report the possible outcome of executing an operation when computing the validity of an execute is too expensive to perform in `IUndoableOperation.canExecute()`. It is not called by the operation history, but instead is used by clients (such as implementers of `IOperationApprover2`) who wish to perform advanced validation of an operation before attempting to execute it. If the result of this method is the discovery that an operation can in fact not be executed, then the operation is expected to correctly answer `false` on subsequent calls to `IUndoableOperation.canExecute()`.

Specified by:
  `computeExecutionStatus` in interface `IAdvancedUndoableOperation2`
Parameters:
  `monitor` - the progress monitor (or `null`) to use for reporting progress to the user while computing the validity.
Returns:
  the IStatus indicating the validity of the execute. The status severity should be set to `OK` if the execute can successfully be performed, and `ERROR` if it cannot. Any other severity is assumed to represent an ambiguous state.
Throws:
  `ExecutionException` - if an exception occurs while computing the validity.
Since:
  3.6

### setQuietCompute

public void setQuietCompute(boolean quiet)
Description copied from interface: `IAdvancedUndoableOperation2`
Set a boolean that instructs whether the computation of the receiver's execution, undo, or redo status should quietly compute status without consulting or prompting the user. The default value is `false`. This flag should only be set to `true` while the execution, undo, or redo status computations are being performed in the background, and should be restored to `false` when complete.

If the status computation methods typically need to consult the user in order to determine the severity of a particular situation, the least severe status that could be chosen by the user should be returned when this flag is `true`. This can help to prevent overzealous disposal of the operation history when an operation is in an ambiguous state. Typically, the status computation methods are invoked with this flag set to `false` just before the actual execution, undo, or redo occurs, so the user can be consulted for the final outcome.

Specified by:
  `setQuietCompute` in interface `IAdvancedUndoableOperation2`
Parameters:
  `quiet` - `true` if it is inappropriate to consult or otherwise prompt the user while computing status, and `false` if the user may be prompted.
Since:
  3.6
See Also:
  - `IAdvancedUndoableOperation2.computeExecutionStatus(IProgressMonitor)`
  - `IAdvancedUndoableOperation.computeUndoableStatus(IProgressMonitor)`
  - `IAdvancedUndoableOperation.computeRedoableStatus(IProgressMonitor)`

### runInBackground

public boolean runInBackground()
Description copied from interface: `IAdvancedUndoableOperation2`
Return a boolean that instructs whether the operation should be executed, undone, or redone in a background thread.

Specified by:
  `runInBackground` in interface `IAdvancedUndoableOperation2`
Returns:
  `true` if the operation should be run in the background, `false` if it should not.
Since:
  3.6