Class DefaultOperationHistory
- All Implemented Interfaces:
IOperationHistory
A base implementation of IOperationHistory that implements a linear undo and redo model . The most recently added operation is available for undo, and the most recently undone operation is available for redo.
If the operation eligible for undo is not in a state where it can be undone, then no undo is available. No other operations are considered. Likewise, if the operation available for redo cannot be redone, then no redo is available.
Implementations for the direct undo and redo of a specified operation are available. If a strict linear undo is to be enforced, than an IOperationApprover should be installed that prevents undo and redo of any operation that is not the most recently undone or redone operation in all of its undo contexts.
The data structures used by the DefaultOperationHistory are synchronized, and entry points that modify the undo and redo history concurrently are also synchronized. This means that the DefaultOperationHistory is relatively "thread-friendly" in its implementation. Outbound notifications or operation approval requests will occur on the thread that initiated the request. Clients may use DefaultOperationHistory API from any thread; however, listeners or operation approvers that receive notifications from the DefaultOperationHistory must be prepared to receive these notifications from a background thread. Any UI access occurring inside these notifications must be properly synchronized using the techniques specified by the client's widget library.
This implementation is not intended to be subclassed.
- Since:
- 3.1
- See Also:
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic booleanThis flag can be set totrueif the history should print information toSystem.outwhenever an operation is not approved.static booleanThis flag can be set totrueif the history should print information toSystem.outwhenever an undo context is disposed.static booleanThis flag can be set totrueif the history should print information toSystem.outwhenever notifications about changes to the history occur.static booleanThis flag can be set totrueif the history should print information toSystem.outduring the open/close sequence.static booleanThis flag can be set totrueif the history should print information toSystem.outwhenever an unexpected condition arises.Fields inherited from interface org.eclipse.core.commands.operations.IOperationHistory
EXECUTE, GLOBAL_UNDO_CONTEXT, NOTHING_TO_REDO_STATUS, NOTHING_TO_UNDO_STATUS, OPERATION_INVALID_STATUS, REDO, UNDO -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionvoidadd(IUndoableOperation operation) Add the specified operation to the history without executing it.voidaddOperationApprover(IOperationApprover approver) Add the specified approver to the list of operation approvers consulted by the operation history before an undo or redo is allowed to proceed.voidAdd 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.booleancanRedo(IUndoContext context) Return whether there is a valid redoable operation available in the given context.booleancanUndo(IUndoContext context) Return whether there is a valid undoable operation available in the given contextvoidcloseOperation(boolean operationOK, boolean addToHistory, int mode) Close the current operation.voiddispose(IUndoContext context, boolean flushUndo, boolean flushRedo, boolean flushContext) Dispose of the specified context in the history.execute(IUndoableOperation operation, IProgressMonitor monitor, IAdaptable info) Execute the specified operation and add it to the operations history if successful.intgetLimit(IUndoContext context) Return the limit on the undo and redo history for a particular context.getRedoHistory(IUndoContext context) Get the array of operations in the redo history for a the specified undo context.getRedoOperation(IUndoContext context) Get the operation that will next be redone in the given undo context.getUndoHistory(IUndoContext context) Get the array of operations in the undo history for the specified undo context.getUndoOperation(IUndoContext context) Get the operation that will next be undone in the given undo context.voidopenOperation(ICompositeOperation operation, int mode) Open this composite operation and consider it an operation that contains other related operations.voidoperationChanged(IUndoableOperation operation) The specified operation has changed in some way since it was added to the operation history.redo(IUndoContext context, IProgressMonitor monitor, IAdaptable info) Redo the most recently undone operation in the given context.redoOperation(IUndoableOperation operation, IProgressMonitor monitor, IAdaptable info) Redo the specified operation.voidremoveOperationApprover(IOperationApprover approver) Remove the specified operation approver from the list of operation approvers that are consulted before an operation is undone or redone.voidRemove the specified listener from the list of operation history listeners.voidreplaceOperation(IUndoableOperation operation, IUndoableOperation[] replacements) Replace the specified operation in the undo or redo history with the provided list of replacements.voidsetLimit(IUndoContext context, int limit) Set the limit on the undo and redo history for a particular context.undo(IUndoContext context, IProgressMonitor monitor, IAdaptable info) Undo the most recently executed operation in the given context.undoOperation(IUndoableOperation operation, IProgressMonitor monitor, IAdaptable info) Undo the specified operation.
-
Field Details
-
DEBUG_OPERATION_HISTORY_NOTIFICATION
public static boolean DEBUG_OPERATION_HISTORY_NOTIFICATIONThis flag can be set totrueif the history should print information toSystem.outwhenever notifications about changes to the history occur. This flag should be used for debug purposes only. -
DEBUG_OPERATION_HISTORY_UNEXPECTED
public static boolean DEBUG_OPERATION_HISTORY_UNEXPECTEDThis flag can be set totrueif the history should print information toSystem.outwhenever an unexpected condition arises. This flag should be used for debug purposes only. -
DEBUG_OPERATION_HISTORY_DISPOSE
public static boolean DEBUG_OPERATION_HISTORY_DISPOSEThis flag can be set totrueif the history should print information toSystem.outwhenever an undo context is disposed. This flag should be used for debug purposes only. -
DEBUG_OPERATION_HISTORY_OPENOPERATION
public static boolean DEBUG_OPERATION_HISTORY_OPENOPERATIONThis flag can be set totrueif the history should print information toSystem.outduring the open/close sequence. This flag should be used for debug purposes only. -
DEBUG_OPERATION_HISTORY_APPROVAL
public static boolean DEBUG_OPERATION_HISTORY_APPROVALThis flag can be set totrueif the history should print information toSystem.outwhenever an operation is not approved. This flag should be used for debug purposes only.
-
-
Constructor Details
-
DefaultOperationHistory
public DefaultOperationHistory()Create an instance of DefaultOperationHistory.
-
-
Method Details
-
add
Description copied from interface:IOperationHistoryAdd 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).- Specified by:
addin interfaceIOperationHistory- Parameters:
operation- the operation to be added to the history
-
addOperationApprover
Add the specified approver to the list of operation approvers consulted by the operation history before an undo or redo is allowed to proceed. This method has no effect if the instance being added is already in the list.
Operation approvers must be prepared to receive these the operation approval messages from a background thread. Any UI access occurring inside the implementation must be properly synchronized using the techniques specified by the client's widget library.
- Specified by:
addOperationApproverin interfaceIOperationHistory- Parameters:
approver- the IOperationApprover to be added as an approver.- See Also:
-
addOperationHistoryListener
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. This method has no effect if the instance being added is already in the list.
Operation history listeners must be prepared to receive notifications from a background thread. Any UI access occurring inside the implementation must be properly synchronized using the techniques specified by the client's widget library.
- Specified by:
addOperationHistoryListenerin interfaceIOperationHistory- Parameters:
listener- the IOperationHistoryListener to be added as a listener.- See Also:
-
canRedo
Description copied from interface:IOperationHistoryReturn whether there is a valid redoable operation available in the given context.
- Specified by:
canRedoin interfaceIOperationHistory- Parameters:
context- the context to be checked- Returns:
trueif there is a redoable operation,falseotherwise.
-
canUndo
Description copied from interface:IOperationHistoryReturn whether there is a valid undoable operation available in the given context
- Specified by:
canUndoin interfaceIOperationHistory- Parameters:
context- the context to be checked- Returns:
trueif there is an undoable operation,falseotherwise.
-
dispose
public void dispose(IUndoContext context, boolean flushUndo, boolean flushRedo, boolean flushContext) Description copied from interface:IOperationHistoryDispose 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.
- Specified by:
disposein interfaceIOperationHistory- Parameters:
context- the context to be disposedflushUndo-trueif the context should be flushed from the undo history,falseif it should notflushRedo-trueif the context should be flushed from the redo history,falseif it should not.flushContext-trueif the context is no longer in use and references to it should be flushed.
-
execute
public IStatus execute(IUndoableOperation operation, IProgressMonitor monitor, IAdaptable info) throws ExecutionException Description copied from interface:IOperationHistoryExecute 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 (DONEorOPERATION_NOT_OK).If the operation successfully executes, an additional notification that the operation has been added to the history (
OPERATION_ADDED) will be sent.- Specified by:
executein interfaceIOperationHistory- Parameters:
operation- the operation to be executed and then added to the historymonitor- the progress monitor to be used (ornull) during the operation.info- the IAdaptable (ornull) provided by the caller in order to supply UI information for prompting the user if necessary. When this parameter is notnull, 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.
OKseverity 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).CANCELseverity indicates that the user cancelled the operation and that the operation was not added to the history.ERRORseverity 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 thanOK, listeners will receive theOPERATION_NOT_OKnotification instead of theDONEnotification if the execution was approved and attempted. - Throws:
ExecutionException- if an exception occurred during execution.
-
getLimit
Description copied from interface:IOperationHistoryReturn the limit on the undo and redo history for a particular context.
- Specified by:
getLimitin interfaceIOperationHistory- Parameters:
context- the context whose limit is requested- Returns:
- the undo and redo history limit for the specified context.
-
getRedoHistory
Description copied from interface:IOperationHistoryGet 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.
- Specified by:
getRedoHistoryin interfaceIOperationHistory- Parameters:
context- the context for the redo- Returns:
- the array of operations in the history
-
getRedoOperation
Description copied from interface:IOperationHistoryGet the operation that will next be redone in the given undo context.
- Specified by:
getRedoOperationin interfaceIOperationHistory- Parameters:
context- the context for the redo- Returns:
- the operation to be redone or
nullif there is no operation available. There is no guarantee that the returned operation is valid for redo.
-
getUndoHistory
Description copied from interface:IOperationHistoryGet 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.
- Specified by:
getUndoHistoryin interfaceIOperationHistory- Parameters:
context- the context for the undo- Returns:
- the array of operations in the history
-
getUndoOperation
Description copied from interface:IOperationHistoryGet the operation that will next be undone in the given undo context.
- Specified by:
getUndoOperationin interfaceIOperationHistory- Parameters:
context- the context for the undo- Returns:
- the operation to be undone or
nullif there is no operation available. There is no guarantee that the available operation is valid for the undo.
-
redo
public IStatus redo(IUndoContext context, IProgressMonitor monitor, IAdaptable info) throws ExecutionException Description copied from interface:IOperationHistoryRedo the most recently undone operation in the given context. The redo of the operation is subject to approval by any registered
IOperationApproverbefore it is attempted.- Specified by:
redoin interfaceIOperationHistory- Parameters:
context- the context to be redonemonitor- the progress monitor to be used for the redo, ornullif no progress monitor is provided.info- the IAdaptable (ornull) provided by the caller in order to supply UI information for prompting the user if necessary. When this parameter is notnull, 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.
OKseverity 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 theREDONEnotification.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 thanOK, listeners will receive theOPERATION_NOT_OKnotification instead of theREDONEnotification if the redo was approved and attempted. - Throws:
ExecutionException- if an exception occurred during redo.
-
redoOperation
public IStatus redoOperation(IUndoableOperation operation, IProgressMonitor monitor, IAdaptable info) throws ExecutionException Description copied from interface:IOperationHistoryRedo the specified operation. The redo of the operation is subject to approval by any registered
IOperationApproverbefore it is attempted.- Specified by:
redoOperationin interfaceIOperationHistory- Parameters:
operation- the operation to be redonemonitor- the progress monitor to be used for the redo, ornullif no progress monitor is providedinfo- the IAdaptable (ornull) provided by the caller in order to supply UI information for prompting the user if necessary. When this parameter is notnull, 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.
OKseverity 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 theREDONEnotification.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 thanOK, listeners will receive theOPERATION_NOT_OKnotification instead of theREDONEnotification if the redo was approved and attempted. - Throws:
ExecutionException- if an exception occurred during redo.
-
removeOperationApprover
Description copied from interface:IOperationHistoryRemove the specified operation approver from the list of operation approvers that are consulted before an operation is undone or redone.
- Specified by:
removeOperationApproverin interfaceIOperationHistory- Parameters:
approver- the IOperationApprover to be removed. Must not benull. If an attempt is made to remove an instance which is not already registered with this instance, this method has no effect.
-
removeOperationHistoryListener
Description copied from interface:IOperationHistoryRemove the specified listener from the list of operation history listeners.
- Specified by:
removeOperationHistoryListenerin interfaceIOperationHistory- Parameters:
listener- The IOperationHistoryListener to be removed. Must not benull. If an attempt is made to remove an instance which is not already registered with this instance, this method has no effect.
-
replaceOperation
Description copied from interface:IOperationHistoryReplace 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.
- Specified by:
replaceOperationin interfaceIOperationHistory- Parameters:
operation- The IUndoableOperation to be replacedreplacements- the array of IUndoableOperation to replace the first operation
-
setLimit
Description copied from interface:IOperationHistorySet the limit on the undo and redo history for a particular context.
- Specified by:
setLimitin interfaceIOperationHistory- 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
public IStatus undo(IUndoContext context, IProgressMonitor monitor, IAdaptable info) throws ExecutionException Description copied from interface:IOperationHistoryUndo the most recently executed operation in the given context. The undo of the operation is subject to approval by any registered
IOperationApproverbefore it is attempted.- Specified by:
undoin interfaceIOperationHistory- Parameters:
context- the context to be undonemonitor- the progress monitor to be used for the undo, ornullif no progress monitor is provided.info- the IAdaptable (ornull) provided by the caller in order to supply UI information for prompting the user if necessary. When this parameter is notnull, 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.
OKseverity 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 theUNDONEnotification.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 thanOK, listeners will receive theOPERATION_NOT_OKnotification instead of theUNDONEnotification if the undo was approved and attempted. - Throws:
ExecutionException- if an exception occurred during undo.
-
undoOperation
public IStatus undoOperation(IUndoableOperation operation, IProgressMonitor monitor, IAdaptable info) throws ExecutionException Description copied from interface:IOperationHistoryUndo the specified operation. The undo of the operation is subject to approval by any registered
IOperationApproverbefore it is attempted.- Specified by:
undoOperationin interfaceIOperationHistory- Parameters:
operation- the operation to be undonemonitor- the progress monitor to be used for the undo, ornullif no progress monitor is providedinfo- the IAdaptable (ornull) provided by the caller in order to supply UI information for prompting the user if necessary. When this parameter is notnull, 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.
OKseverity 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 theUNDONEnotification.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 thanOK, listeners will receive theOPERATION_NOT_OKnotification instead of theUNDONEnotification if the undo was approved and attempted. - Throws:
ExecutionException- if an exception occurred during undo.
-
openOperation
Description copied from interface:IOperationHistoryOpen 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.
- Specified by:
openOperationin interfaceIOperationHistory- 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 ofEXECUTE,UNDO, orREDO. This determines what notifications are sent.
-
closeOperation
public void closeOperation(boolean operationOK, boolean addToHistory, int mode) Description copied from interface:IOperationHistoryClose the current operation. If the operation has successfully completed, send listeners a
DONE,UNDONE, orREDONEnotification, depending on the mode. Otherwise send anOPERATION_NOT_OKnotification. Add the operation to the history if specified and send anOPERATION_ADDEDnotification.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
IOperationHistory.openOperation(org.eclipse.core.commands.operations.ICompositeOperation, int).- Specified by:
closeOperationin interfaceIOperationHistory- Parameters:
operationOK-trueif the operation successfully completed. Listeners should be notified withDONE,UNDONE, orREDONE.falseif the operation did not successfully complete. Listeners should be notified withOPERATION_NOT_OK.addToHistory-trueif the operation should be added to the history,falseif it should not. If theoperationOKparameter isfalse, the operation will never be added to the history.mode- the mode the operation was opened in. Can be one ofEXECUTE,UNDO, orREDO. This determines what notifications are sent.
-
operationChanged
Description copied from interface:IOperationHistoryThe specified operation has changed in some way since it was added to the operation history. Notify listeners with an OPERATION_CHANGED event.
- Specified by:
operationChangedin interfaceIOperationHistory- Parameters:
operation- the operation that has changed.
-