public final class DefaultOperationHistory extends Object implements 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.
IOperationHistory
,
IOperationApprover
Modifier and Type | Field and Description |
---|---|
static boolean |
DEBUG_OPERATION_HISTORY_APPROVAL
This flag can be set to
true if the history should print
information to System.out whenever an operation is not
approved. |
static boolean |
DEBUG_OPERATION_HISTORY_DISPOSE
This flag can be set to
true if the history should print
information to System.out whenever an undo context is
disposed. |
static boolean |
DEBUG_OPERATION_HISTORY_NOTIFICATION
This flag can be set to
true if the history should print
information to System.out whenever notifications about
changes to the history occur. |
static boolean |
DEBUG_OPERATION_HISTORY_OPENOPERATION
This flag can be set to
true if the history should print
information to System.out during the open/close sequence. |
static boolean |
DEBUG_OPERATION_HISTORY_UNEXPECTED
This flag can be set to
true if the history should print
information to System.out whenever an unexpected condition
arises. |
EXECUTE, GLOBAL_UNDO_CONTEXT, NOTHING_TO_REDO_STATUS, NOTHING_TO_UNDO_STATUS, OPERATION_INVALID_STATUS, REDO, UNDO
Constructor and Description |
---|
DefaultOperationHistory()
Create an instance of DefaultOperationHistory.
|
Modifier and Type | Method and 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 allowed to proceed.
|
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.
|
public static boolean DEBUG_OPERATION_HISTORY_NOTIFICATION
true
if the history should print
information to System.out
whenever notifications about
changes to the history occur. This flag should be used for debug purposes
only.public static boolean DEBUG_OPERATION_HISTORY_UNEXPECTED
true
if the history should print
information to System.out
whenever an unexpected condition
arises. This flag should be used for debug purposes only.public static boolean DEBUG_OPERATION_HISTORY_DISPOSE
true
if the history should print
information to System.out
whenever an undo context is
disposed. This flag should be used for debug purposes only.public static boolean DEBUG_OPERATION_HISTORY_OPENOPERATION
true
if the history should print
information to System.out
during the open/close sequence.
This flag should be used for debug purposes only.public static boolean DEBUG_OPERATION_HISTORY_APPROVAL
true
if the history should print
information to System.out
whenever an operation is not
approved. This flag should be used for debug purposes only.public DefaultOperationHistory()
public void add(IUndoableOperation operation)
IOperationHistory
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
).
add
in interface IOperationHistory
operation
- the operation to be added to the historypublic 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 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.
addOperationApprover
in interface IOperationHistory
approver
- the IOperationApprover to be added as an approver.IOperationApprover
public 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. 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.
addOperationHistoryListener
in interface IOperationHistory
listener
- the IOperationHistoryListener to be added as a listener.IOperationHistoryListener
,
OperationHistoryEvent
public boolean canRedo(IUndoContext context)
IOperationHistory
Return whether there is a valid redoable operation available in the given context.
canRedo
in interface IOperationHistory
context
- the context to be checkedtrue
if there is a redoable operation,
false
otherwise.public boolean canUndo(IUndoContext context)
IOperationHistory
Return whether there is a valid undoable operation available in the given context
canUndo
in interface IOperationHistory
context
- the context to be checkedtrue
if there is an undoable operation,
false
otherwise.public void dispose(IUndoContext context, boolean flushUndo, boolean flushRedo, boolean flushContext)
IOperationHistory
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.
dispose
in interface IOperationHistory
context
- the context to be disposedflushUndo
- true
if the context should be flushed from the
undo history, false
if it should notflushRedo
- 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.public IStatus execute(IUndoableOperation operation, IProgressMonitor monitor, IAdaptable info) throws ExecutionException
IOperationHistory
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.
execute
in interface IOperationHistory
operation
- the operation to be executed and then added to the historymonitor
- 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.
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.
ExecutionException
- if an exception occurred during execution.public int getLimit(IUndoContext context)
IOperationHistory
Return the limit on the undo and redo history for a particular context.
getLimit
in interface IOperationHistory
context
- the context whose limit is requestedpublic IUndoableOperation[] getRedoHistory(IUndoContext context)
IOperationHistory
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.
getRedoHistory
in interface IOperationHistory
context
- the context for the redopublic IUndoableOperation getRedoOperation(IUndoContext context)
IOperationHistory
Get the operation that will next be redone in the given undo context.
getRedoOperation
in interface IOperationHistory
context
- the context for the redonull
if there is no
operation available. There is no guarantee that the returned
operation is valid for redo.public IUndoableOperation[] getUndoHistory(IUndoContext context)
IOperationHistory
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.
getUndoHistory
in interface IOperationHistory
context
- the context for the undopublic IUndoableOperation getUndoOperation(IUndoContext context)
IOperationHistory
Get the operation that will next be undone in the given undo context.
getUndoOperation
in interface IOperationHistory
context
- the context for the undonull
if there is no
operation available. There is no guarantee that the available
operation is valid for the undo.public IStatus redo(IUndoContext context, IProgressMonitor monitor, IAdaptable info) throws ExecutionException
IOperationHistory
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.
redo
in interface IOperationHistory
context
- the context to be redonemonitor
- 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.
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.
ExecutionException
- if an exception occurred during redo.public IStatus redoOperation(IUndoableOperation operation, IProgressMonitor monitor, IAdaptable info) throws ExecutionException
IOperationHistory
Redo the specified operation. The redo of the operation is subject to
approval by any registered IOperationApprover
before it is
attempted.
redoOperation
in interface IOperationHistory
operation
- the operation to be redonemonitor
- the progress monitor to be used for the redo, or code>null
if no progress monitor is providedinfo
- 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.
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.
ExecutionException
- if an exception occurred during redo.public void removeOperationApprover(IOperationApprover approver)
IOperationHistory
Remove the specified operation approver from the list of operation approvers that are consulted before an operation is undone or redone.
removeOperationApprover
in interface IOperationHistory
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.public void removeOperationHistoryListener(IOperationHistoryListener listener)
IOperationHistory
Remove the specified listener from the list of operation history listeners.
removeOperationHistoryListener
in interface IOperationHistory
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.public void replaceOperation(IUndoableOperation operation, IUndoableOperation[] replacements)
IOperationHistory
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.
replaceOperation
in interface IOperationHistory
operation
- The IUndoableOperation to be replacedreplacements
- the array of IUndoableOperation to replace the first operationpublic void setLimit(IUndoContext context, int limit)
IOperationHistory
Set the limit on the undo and redo history for a particular context.
setLimit
in interface IOperationHistory
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.public IStatus undo(IUndoContext context, IProgressMonitor monitor, IAdaptable info) throws ExecutionException
IOperationHistory
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.
undo
in interface IOperationHistory
context
- the context to be undonemonitor
- 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.
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.
ExecutionException
- if an exception occurred during undo.public IStatus undoOperation(IUndoableOperation operation, IProgressMonitor monitor, IAdaptable info) throws ExecutionException
IOperationHistory
Undo the specified operation. The undo of the operation is subject to
approval by any registered IOperationApprover
before it is
attempted.
undoOperation
in interface IOperationHistory
operation
- the operation to be undonemonitor
- the progress monitor to be used for the undo, or
null
if no progress monitor is providedinfo
- 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.
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.
ExecutionException
- if an exception occurred during undo.public void openOperation(ICompositeOperation operation, int mode)
IOperationHistory
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.
openOperation
in interface IOperationHistory
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.public void closeOperation(boolean operationOK, boolean addToHistory, int mode)
IOperationHistory
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
IOperationHistory.openOperation(org.eclipse.core.commands.operations.ICompositeOperation, int)
.
closeOperation
in interface IOperationHistory
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.public void operationChanged(IUndoableOperation operation)
IOperationHistory
The specified operation has changed in some way since it was added to the operation history. Notify listeners with an OPERATION_CHANGED event.
operationChanged
in interface IOperationHistory
operation
- the operation that has changed.
Copyright (c) 2000, 2014 Eclipse Contributors and others. All rights reserved.Guidelines for using Eclipse APIs.