Package org.eclipse.core.commands.operations

# Interface IOperationHistory

All Known Implementing Classes:
  `DefaultOperationHistory`

public interface IOperationHistory

IOperationHistory tracks a history of operations that can be undone or redone. Operations are added to the history once they have been initially executed. Clients may choose whether to have the operations history perform the initial execution or to simply add an already-executed operation to the history.

Once operations are added to the history, the methods `canRedo(IUndoContext)` and `canUndo(IUndoContext)` are used to determine whether there is an operation available for undo and redo in a given undo context. The context-based protocol implies that there is only one operation that can be undone or redone at a given time in a given context. This is typical of a linear undo model, when only the most recently executed operation is available for undo. When this protocol is used, a linear model is enforced by the history.

It is up to clients to determine how to maintain a history that is invalid or stale. For example, when the most recent operation for a context cannot be performed, clients may wish to dispose the history for that context.

Additional protocol allows direct undo and redo of a specified operation, regardless of its position in the history. When a more flexible undo model is supported, these methods can be implemented to undo and redo directly specified operations. If an implementer of IOperationHistory does not allow direct undo and redo, these methods can return a status indicating that it is not allowed.

Listeners (`IOperationHistoryListener`) can listen for notifications about changes in the history (operations added or removed), and for notification before and after any operation is executed, undone or redone. Notification of operation execution only occurs when clients direct the history to execute the operation. If the operation is added after it is executed, there can be no notification of its execution.

`IOperationApprover` defines an interface for approving an undo or redo before it occurs. This is useful for injecting policy-decisions into the undo model - whether direct undo and redo are supported, or warning the user about certain kinds of operations. It can also be used when clients maintain state related to an operation and need to determine whether an undo or redo will cause any conflicts with their local state.

Since:
  3.1

## Field Summary

Fields
Modifier and Type
Field
Description
`static final int`
`EXECUTE`
An operation is to be opened or closed for execution.
`static final IUndoContext`
`GLOBAL_UNDO_CONTEXT`
An undo context that can be used to refer to the global undo history.
`static final IStatus`
`NOTHING_TO_REDO_STATUS`
An operation info status describing the condition that there is no available operation for redo.
`static final IStatus`
`NOTHING_TO_UNDO_STATUS`
An operation info status describing the condition that there is no available operation for undo.
`static final IStatus`
`OPERATION_INVALID_STATUS`
An operation error status describing the condition that the operation available for execution, undo or redo is not in a valid state for the action to be performed.
`static final int`
`REDO`
An operation is to be opened for redo.
`static final int`
`UNDO`
An operation is to be opened for undo.

## Method Summary

Modifier and Type
Method
Description
`void`
`add(IUndoableOperation operation)`
Add the specified operation to the history without executing it.
`void`
`addOperationApprover(IOperationApprover approver)`
Add the specified approver to the list of operation approvers consulted by the operation history before an undo or redo is attempted.
`void`
`addOperationHistoryListener(IOperationHistoryListener listener)`
Add the specified listener to the list of operation history listeners that are notified about changes in the history or operations that are executed, undone, or redone.
`boolean`
`canRedo(IUndoContext context)`
Return whether there is a valid redoable operation available in the given context.
`boolean`
`canUndo(IUndoContext context)`
Return whether there is a valid undoable operation available in the given context
`void`
`closeOperation(boolean operationOK, boolean addToHistory, int mode)`
Close the current operation.
`void`
`dispose(IUndoContext context, boolean flushUndo, boolean flushRedo, boolean flushContext)`
Dispose of the specified context in the history.
`IStatus`
`execute(IUndoableOperation operation, IProgressMonitor monitor, IAdaptable info)`
Execute the specified operation and add it to the operations history if successful.
`int`
`getLimit(IUndoContext context)`
Return the limit on the undo and redo history for a particular context.
`IUndoableOperation[]`
`getRedoHistory(IUndoContext context)`
Get the array of operations in the redo history for a the specified undo context.
`IUndoableOperation`
`getRedoOperation(IUndoContext context)`
Get the operation that will next be redone in the given undo context.
`IUndoableOperation[]`
`getUndoHistory(IUndoContext context)`
Get the array of operations in the undo history for the specified undo context.
`IUndoableOperation`
`getUndoOperation(IUndoContext context)`
Get the operation that will next be undone in the given undo context.
`void`
`openOperation(ICompositeOperation operation, int mode)`
Open this composite operation and consider it an operation that contains other related operations.
`void`
`operationChanged(IUndoableOperation operation)`
The specified operation has changed in some way since it was added to the operation history.
`IStatus`
`redo(IUndoContext context, IProgressMonitor monitor, IAdaptable info)`
Redo the most recently undone operation in the given context.
`IStatus`
`redoOperation(IUndoableOperation operation, IProgressMonitor monitor, IAdaptable info)`
Redo the specified operation.
`void`
`removeOperationApprover(IOperationApprover approver)`
Remove the specified operation approver from the list of operation approvers that are consulted before an operation is undone or redone.
`void`
`removeOperationHistoryListener(IOperationHistoryListener listener)`
Remove the specified listener from the list of operation history listeners.
`void`
`replaceOperation(IUndoableOperation operation, IUndoableOperation[] replacements)`
Replace the specified operation in the undo or redo history with the provided list of replacements.
`void`
`setLimit(IUndoContext context, int limit)`
Set the limit on the undo and redo history for a particular context.
`IStatus`
`undo(IUndoContext context, IProgressMonitor monitor, IAdaptable info)`
Undo the most recently executed operation in the given context.
`IStatus`
`undoOperation(IUndoableOperation operation, IProgressMonitor monitor, IAdaptable info)`
Undo the specified operation.

## Field Details

### EXECUTE

static final int EXECUTE
An operation is to be opened or closed for execution. (value is 1).

See Also:
  - Constant Field Values

### UNDO

static final int UNDO
An operation is to be opened for undo. (value is 2).

See Also:
  - Constant Field Values

### REDO

static final int REDO
An operation is to be opened for redo. (value is 3).

See Also:
  - Constant Field Values

### GLOBAL_UNDO_CONTEXT

static final IUndoContext GLOBAL_UNDO_CONTEXT
An undo context that can be used to refer to the global undo history. This context is not intended to be assigned to operations. Instead, it is used for querying the history or performing an undo or redo on the entire history, regardless of each operation's undo contexts.

### NOTHING_TO_REDO_STATUS

static final IStatus NOTHING_TO_REDO_STATUS
An operation info status describing the condition that there is no available operation for redo.

### NOTHING_TO_UNDO_STATUS

static final IStatus NOTHING_TO_UNDO_STATUS
An operation info status describing the condition that there is no available operation for undo.

### OPERATION_INVALID_STATUS

static final IStatus OPERATION_INVALID_STATUS
An operation error status describing the condition that the operation available for execution, undo or redo is not in a valid state for the action to be performed.

## Method Details

### add

void add(IUndoableOperation operation)

Add the specified operation to the history without executing it. The operation should have already been executed by the time it is added to the history. Listeners will be notified that the operation was added to the history (`OPERATION_ADDED`).

Parameters:
  `operation` - the operation to be added to the history

### addOperationApprover

void addOperationApprover(IOperationApprover approver)

Add the specified approver to the list of operation approvers consulted by the operation history before an undo or redo is attempted.

Parameters:
  `approver` - the IOperationApprover to be added as an approver.the instance to remove. Must not be `null`. If an attempt is made to register an instance which is already registered with this instance, this method has no effect.
See Also:
  - `IOperationApprover`

### addOperationHistoryListener

void addOperationHistoryListener(IOperationHistoryListener listener)

Add the specified listener to the list of operation history listeners that are notified about changes in the history or operations that are executed, undone, or redone.

Parameters:
  `listener` - the IOperationHistoryListener to be added as a listener. Must not be `null`. If an attempt is made to register an instance which is already registered with this instance, this method has no effect.
See Also:
  - `IOperationHistoryListener`
  - `OperationHistoryEvent`

### closeOperation

void closeOperation(boolean operationOK, boolean addToHistory, int mode)

Close the current operation. If the operation has successfully completed, send listeners a `DONE`, `UNDONE`, or `REDONE` notification, depending on the mode. Otherwise send an `OPERATION_NOT_OK` notification. Add the operation to the history if specified and send an `OPERATION_ADDED` notification.

Any operations that are executed and added after this operation is closed will no longer be considered part of this operation.

This method has no effect if the caller has not previously called `openOperation(org.eclipse.core.commands.operations.ICompositeOperation, int)`.

Parameters:
  `operationOK` - `true` if the operation successfully completed. Listeners should be notified with `DONE`, `UNDONE`, or `REDONE`. `false` if the operation did not successfully complete. Listeners should be notified with `OPERATION_NOT_OK`.
  `addToHistory` - `true` if the operation should be added to the history, `false` if it should not. If the `operationOK` parameter is `false`, the operation will never be added to the history.
  `mode` - the mode the operation was opened in. Can be one of `EXECUTE`, `UNDO`, or `REDO`. This determines what notifications are sent.

### canRedo

boolean canRedo(IUndoContext context)

Return whether there is a valid redoable operation available in the given context.

Parameters:
  `context` - the context to be checked
Returns:
  `true` if there is a redoable operation, `false` otherwise.

### canUndo

boolean canUndo(IUndoContext context)

Return whether there is a valid undoable operation available in the given context

Parameters:
  `context` - the context to be checked
Returns:
  `true` if there is an undoable operation, `false` otherwise.

### dispose

void dispose(IUndoContext context, boolean flushUndo, boolean flushRedo, boolean flushContext)

Dispose of the specified context in the history. All operations that have only the given context will be disposed. References to the context in operations that have more than one context will also be removed. A history notification for the removal of each operation being disposed will be sent.

Parameters:
  `context` - the context to be disposed
  `flushUndo` - `true` if the context should be flushed from the undo history, `false` if it should not
  `flushRedo` - `true` if the context should be flushed from the redo history, `false` if it should not.
  `flushContext` - `true` if the context is no longer in use and references to it should be flushed.

### execute

IStatus execute(IUndoableOperation operation, IProgressMonitor monitor, IAdaptable info) throws ExecutionException

Execute the specified operation and add it to the operations history if successful. This method is used by clients who wish operation history listeners to receive notifications before and after the execution of the operation. Execution of the operation is subject to approval by any registered `IOperationApprover2`. If execution is approved, listeners will be notified before (`ABOUT_TO_EXECUTE`) and after (`DONE` or `OPERATION_NOT_OK`).

If the operation successfully executes, an additional notification that the operation has been added to the history (`OPERATION_ADDED`) will be sent.

Parameters:
  `operation` - the operation to be executed and then added to the history
  `monitor` - the progress monitor to be used (or `null`) during the operation.
  `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 indicating whether the execution succeeded.

  The severity code in the returned status describes whether the operation succeeded and whether it was added to the history. `OK` severity indicates that the execute operation was successful and that the operation has been added to the history. Listeners will receive notifications about the operation's success (`DONE`) and about the operation being added to the history (`OPERATION_ADDED`).

  `CANCEL` severity indicates that the user cancelled the operation and that the operation was not added to the history. `ERROR` severity indicates that the operation did not successfully execute and that it was not added to the history. Any other severity code is not specifically interpreted by the history, and the operation will not be added to the history. For all severities other than `OK`, listeners will receive the `OPERATION_NOT_OK` notification instead of the `DONE` notification if the execution was approved and attempted.

Throws:
  `ExecutionException` - if an exception occurred during execution.

### getLimit

int getLimit(IUndoContext context)

Return the limit on the undo and redo history for a particular context.

Parameters:
  `context` - the context whose limit is requested
Returns:
  the undo and redo history limit for the specified context.

### getRedoHistory

IUndoableOperation[] getRedoHistory(IUndoContext context)

Get the array of operations in the redo history for a the specified undo context. The operations are in the order that they were added to the history, with the most recently undone operation appearing last in the array. This history is used LIFO (last in, first out) when successive "Redo" commands are invoked.

Parameters:
  `context` - the context for the redo
Returns:
  the array of operations in the history

### getRedoOperation

IUndoableOperation getRedoOperation(IUndoContext context)

Get the operation that will next be redone in the given undo context.

Parameters:
  `context` - the context for the redo
Returns:
  the operation to be redone or `null` if there is no operation available. There is no guarantee that the returned operation is valid for redo.

### getUndoHistory

IUndoableOperation[] getUndoHistory(IUndoContext context)

Get the array of operations in the undo history for the specified undo context. The operations are in the order that they were added to the history, with the most recently added operation appearing last in the array. This history is used LIFO (last in, first out) when successive "Undo" commands are invoked.

Parameters:
  `context` - the context for the undo
Returns:
  the array of operations in the history

### openOperation

void openOperation(ICompositeOperation operation, int mode)

Open this composite operation and consider it an operation that contains other related operations. Consider all operations that are subsequently executed or added to be part of this operation. When an operation is opened, listeners will immediately receive a notification for the opened operation. The specific notification depends on the mode in which the operation is opened (`ABOUT_TO_EXECUTE`, `ABOUT_TO_UNDO`, `ABOUT_TO_REDO`). Notifications for any other execute or add while this operation is open will not occur. Instead, those operations will be added to the current operation.

Note: This method is intended to be used by legacy undo frameworks that do not expect related undo operations to appear in the same undo history as the triggering undo operation. When an operation is open, any subsequent requests to execute, add, undo, or redo another operation will result in that operation being added to the open operation. Once the operation is closed, the composite will be considered an atomic operation. Clients should not modify the composite directly (by adding and removing children) while it is open.

When a composite is open, operations that are added to the history will be considered part of the open operation instead. Operations that are executed while a composite is open will first be executed and then added to the composite.

Open operations cannot be nested. If this method is called when a different operation is open, it is presumed to be an application coding error and this method will throw an IllegalStateException.

Parameters:
  `operation` - the composite operation to be considered as the parent for all subsequent operations.
  `mode` - the mode the operation is executing in. Can be one of `EXECUTE`, `UNDO`, or `REDO`. This determines what notifications are sent.

### operationChanged

void operationChanged(IUndoableOperation operation)

The specified operation has changed in some way since it was added to the operation history. Notify listeners with an OPERATION_CHANGED event.

Parameters:
  `operation` - the operation that has changed.

### getUndoOperation

IUndoableOperation getUndoOperation(IUndoContext context)

Get the operation that will next be undone in the given undo context.

Parameters:
  `context` - the context for the undo
Returns:
  the operation to be undone or `null` if there is no operation available. There is no guarantee that the available operation is valid for the undo.

### redo

IStatus redo(IUndoContext context, IProgressMonitor monitor, IAdaptable info) throws ExecutionException

Redo the most recently undone operation in the given context. The redo of the operation is subject to approval by any registered `IOperationApprover` before it is attempted.

Parameters:
  `context` - the context to be redone
  `monitor` - the progress monitor to be used for the redo, or `null` if no progress monitor is provided.
  `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 indicating whether the redo succeeded.

  The severity code in the returned status describes whether the operation succeeded and whether it remains in the history. `OK` severity indicates that the redo operation was successful and (since release 3.2), that the operation will be placed in the undo history. (Prior to 3.2, a successfully redone operation would not be placed on the undo history if it could not be undone. Since 3.2, this is relaxed, and all successfully redone operations are placed in the undo history.) Listeners will receive the `REDONE` notification.

  Other severity codes (`CANCEL`, `ERROR`, `INFO`, etc.) are not specifically interpreted by the history. The operation will remain in the history and the returned status is simply passed back to the caller. For all severities other than `OK`, listeners will receive the `OPERATION_NOT_OK` notification instead of the `REDONE` notification if the redo was approved and attempted.

Throws:
  `ExecutionException` - if an exception occurred during redo.

### redoOperation

IStatus redoOperation(IUndoableOperation operation, IProgressMonitor monitor, IAdaptable info) throws ExecutionException

Redo the specified operation. The redo of the operation is subject to approval by any registered `IOperationApprover` before it is attempted.

Parameters:
  `operation` - the operation to be redone
  `monitor` - the progress monitor to be used for the redo, or `null` if no progress monitor is provided
  `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 indicating whether the redo succeeded.

  The severity code in the returned status describes whether the operation succeeded and whether it remains in the history. `OK` severity indicates that the redo operation was successful, and (since release 3.2), that the operation will be placed in the undo history. (Prior to 3.2, a successfully redone operation would not be placed on the undo history if it could not be undone. Since 3.2, this is relaxed, and all successfully redone operations are placed in the undo history.) Listeners will receive the `REDONE` notification.

  Other severity codes (`CANCEL`, `ERROR`, `INFO`, etc.) are not specifically interpreted by the history. The operation will remain in the history and the returned status is simply passed back to the caller. For all severities other than `OK`, listeners will receive the `OPERATION_NOT_OK` notification instead of the `REDONE` notification if the redo was approved and attempted.

Throws:
  `ExecutionException` - if an exception occurred during redo.

### removeOperationApprover

void removeOperationApprover(IOperationApprover approver)

Remove the specified operation approver from the list of operation approvers that are consulted before an operation is undone or redone.

Parameters:
  `approver` - the IOperationApprover to be removed. Must not be `null`. If an attempt is made to remove an instance which is not already registered with this instance, this method has no effect.

### removeOperationHistoryListener

void removeOperationHistoryListener(IOperationHistoryListener listener)

Remove the specified listener from the list of operation history listeners.

Parameters:
  `listener` - The IOperationHistoryListener to be removed. Must not be `null`. If an attempt is made to remove an instance which is not already registered with this instance, this method has no effect.

### replaceOperation

void replaceOperation(IUndoableOperation operation, IUndoableOperation[] replacements)

Replace the specified operation in the undo or redo history with the provided list of replacements. This protocol is typically used when a composite is broken up into its atomic parts. The replacements will be inserted so that the first replacement will be the first of the replacements to be undone or redone. Listeners will be notified about the removal of the replaced element and the addition of each replacement.

Parameters:
  `operation` - The IUndoableOperation to be replaced
  `replacements` - the array of IUndoableOperation to replace the first operation

### setLimit

void setLimit(IUndoContext context, int limit)

Set the limit on the undo and redo history for a particular context.

Parameters:
  `context` - the context whose limit is being set.
  `limit` - the maximum number of operations that should be kept in the undo or redo history for the specified context. Must not be negative.

### undo

IStatus undo(IUndoContext context, IProgressMonitor monitor, IAdaptable info) throws ExecutionException

Undo the most recently executed operation in the given context. The undo of the operation is subject to approval by any registered `IOperationApprover` before it is attempted.

Parameters:
  `context` - the context to be undone
  `monitor` - the progress monitor to be used for the undo, or `null` if no progress monitor is provided.
  `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 indicating whether the undo succeeded.

  The severity code in the returned status describes whether the operation succeeded and whether it remains in the history. `OK` severity indicates that the undo operation was successful, and (since release 3.2), that the operation will be placed on the redo history. (Prior to 3.2, a successfully undone operation would not be placed on the redo history if it could not be redone. Since 3.2, this is relaxed, and all successfully undone operations are placed in the redo history.) Listeners will receive the `UNDONE` notification.

  Other severity codes (`CANCEL`, `ERROR`, `INFO`, etc.) are not specifically interpreted by the history. The operation will remain in the history and the returned status is simply passed back to the caller. For all severities other than `OK`, listeners will receive the `OPERATION_NOT_OK` notification instead of the `UNDONE` notification if the undo was approved and attempted.

Throws:
  `ExecutionException` - if an exception occurred during undo.

### undoOperation

IStatus undoOperation(IUndoableOperation operation, IProgressMonitor monitor, IAdaptable info) throws ExecutionException

Undo the specified operation. The undo of the operation is subject to approval by any registered `IOperationApprover` before it is attempted.

Parameters:
  `operation` - the operation to be undone
  `monitor` - the progress monitor to be used for the undo, or `null` if no progress monitor is provided
  `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 indicating whether the undo succeeded.

  The severity code in the returned status describes whether the operation succeeded and whether it remains in the history. `OK` severity indicates that the undo operation was successful, and (since release 3.2), that the operation will be placed on the redo history. (Prior to 3.2, a successfully undone operation would not be placed on the redo history if it could not be redone. Since 3.2, this is relaxed, and all successfully undone operations are placed in the redo history.) Listeners will receive the `UNDONE` notification.

  Other severity codes (`CANCEL`, `ERROR`, `INFO`, etc.) are not specifically interpreted by the history. The operation will remain in the history and the returned status is simply passed back to the caller. For all severities other than `OK`, listeners will receive the `OPERATION_NOT_OK` notification instead of the `UNDONE` notification if the undo was approved and attempted.

Throws:
  `ExecutionException` - if an exception occurred during undo.