Interface CommandStack
Although termed a "command stack", the implementation in BIRT is a bit more complex. Every user gesture produces one or more changes. Each change is recorded as an activity record. The set of activity records is grouped into a transaction. The transaction represents the overall application action.
Nested Transactions
The application can create transactions to group a collection of operations that should be undone and redone as a unit. When performing a series of such operations, the application must consider the case where one of the operations fails. It can be difficult to ensure ahead of time that that the entire sequence will succeed. It is often easier to simply try the entire sequence, and discover failures when they occur. In this case, the application needs a way to undo work already done when it encounters an errors. Transactions provide this support.
The application starts an operation with a call to the
method, supplying a localized label
that can appear in the menu along with the "Undo" command. For example, "Undo
Align Left." The application then makes changes as usual. If the operation
succeeds, the application ends the transaction by calling
startTrans(String)
. However, if the operation fails, and so the
whole sequence should be abandoned, the application calls the
commit()
method.
rollback()
The application is often designed in a modular fashion; several modules may
contribute to an operation. Sometimes, the module is executed alone;
sometimes, in conjunction with others. For example, the module that changes
the x position might sometimes be called in response to moving one element,
but it may also be called as part of aligning several elements. To make the
code easier, each module can introduce its own transaction. This leads to
"nested" transactions. Each module calls startTrans
, does its
work, and calls commit
. The top-level commit commits the entire
transaction.
If an operation fails, the application can undo just the current nested
transaction. The rollback
method undoes just the innermost
transaction. Or, if the application has a generic error handler, it can call
rollbackAll
to undo the entire set of active transactions.
Sometimes, there is possibility that when a transaction fails, some certain
operation that has already done and succeeded is essential to be persistent
and not to be undone when the application call rollback
or
rollbackAll
. Considering that an Eclipse user select Eclipse ->
Search (Outer Dialog) -> Scope -> Choose -> Select Working Set (Inner Dialog)
to do some searching, he or she customizes the working set and succeeds, and
then he or she clicks "cancel" button to quit the searching, it is completely
possible to rollback the transaction while the customized working set is
still existent and impactful to the next searching working, which therefore
is called as "persistent transaction". In this condition, the application
calls startPersistentTrans(String)
to do the customization of
the working set. So a persistent transaction means that, once the transaction
is committed, it will never be undone with all calls to rollback( ) or
rollbackAll( ) and the only way to make the transaction undone is just to
call undo( ).
-
Method Summary
Modifier and TypeMethodDescriptionvoid
Registers a listener.boolean
canRedo()
Reports whether a command is available to redo.boolean
canUndo()
Reports whether a command is available to undo.void
Removes all listeners on the ActivityStack.void
commit()
Commits an application-level transaction.void
execute
(IActivityRecord record) Executes the specified record and flushes the redo stack.void
execute
(IElementCommand command) Executes the specified extended element command.void
flush()
Clears the record stack.Returns an optional label for the next command to redo.Peeks at the top of the redo stack.Returns an optional label for the next command to undo.Peeks at the top of the undo stack.void
redo()
Redoes a command.void
Removes a listener.void
rollback()
Rolls back an application-level transaction.void
Rolls back all active transactions, leaving the design in the same state it was in when the top-most transaction started.void
setStackLimit
(int limit) Sets the size of the undo stack.void
startPersistentTrans
(String label) Starts one persistent transaction, which will never be rollbacked once the parent transaction is rollbacked.void
startTrans
(String string) Starts an application-level transaction.void
undo()
Undoes a command.
-
Method Details
-
canUndo
boolean canUndo()Reports whether a command is available to undo.- Returns:
true
if a command is available to undo,false
if not.
-
getUndoLabel
String getUndoLabel()Returns an optional label for the next command to undo. The UI can display this label as part of the "Undo" menu command. The label should have been localized when set.- Returns:
- The command label. Returns
null
if either the command has no label, of if there is no command to undo.
-
undo
void undo()Undoes a command. Call this only ifcanUndo( )
returns true. -
canRedo
boolean canRedo()Reports whether a command is available to redo.- Returns:
true
if a command is available to redo,false
if not.
-
getRedoLabel
String getRedoLabel()Returns an optional label for the next command to redo. The UI can display this label as part of the "Redo" menu command. The label should have been localized when set.- Returns:
- The command label. Returns null if either the command has no label, of if there is no command to redo.
-
redo
void redo()Redoes a command. Call this only ifcanRedo( )
returns true. -
setStackLimit
void setStackLimit(int limit) Sets the size of the undo stack. A larger size keeps more history and allows the user to "unwind" a greater number of change; but at the cost of greater memory usage. Note that the size applies to top-level operations, not to the contents of composite commands.If the new size is smaller than the existing size, then the method will remove any commands above the new limit. If the limit is set to zero, then no undo history is kept.
- Parameters:
limit
- the new undo stack size
-
startTrans
Starts an application-level transaction.- Parameters:
string
- the localized label of the transaction
-
commit
void commit()Commits an application-level transaction. -
rollback
void rollback()Rolls back an application-level transaction. Rolls back just the inner-most transaction. -
rollbackAll
void rollbackAll()Rolls back all active transactions, leaving the design in the same state it was in when the top-most transaction started. -
flush
void flush()Clears the record stack. -
getRedoRecord
IActivityRecord getRedoRecord()Peeks at the top of the redo stack.- Returns:
- The record at the top of the redo stack, or null if there is no such record.
-
getUndoRecord
IActivityRecord getUndoRecord()Peeks at the top of the undo stack.- Returns:
- The record at the top of the undo stack, or null if there is no such record.
-
execute
Executes the specified record and flushes the redo stack.- Parameters:
record
- the ActivityRecord to execute
-
execute
Executes the specified extended element command. The command must be ready to execute. As noted above, any required checks must have already been done. Flushes the redo stack.- Parameters:
command
- the ActivityRecord to execute
-
addListener
Registers a listener. A listener can be registered any number of times, but will receive each event only once.- Parameters:
obj
- the activity stack listener to register
-
removeListener
Removes a listener. The listener is removed from the list of listeners. If the item is not in the list, then the request is silently ignored.- Parameters:
obj
- the activity stack listener to remove
-
startPersistentTrans
Starts one persistent transaction, which will never be rollbacked once the parent transaction is rollbacked.- Parameters:
label
- the localized label of the transaction
-
clearListeners
void clearListeners()Removes all listeners on the ActivityStack.
-