Interface CommandStack
-
public interface CommandStack
Application-level interface into the Model's command stack. Each design owns a separate command stack. Only operations available to the application are exposed; those internal to the model are not.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 callingstartTrans(String)
. However, if the operation fails, and so the whole sequence should be abandoned, the application calls thecommit()
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 callscommit
. 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 callrollbackAll
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
orrollbackAll
. 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 callsstartPersistentTrans(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
All Methods Instance Methods Abstract Methods Modifier and Type Method Description void
addListener(ActivityStackListener obj)
Registers a listener.boolean
canRedo()
Reports whether a command is available to redo.boolean
canUndo()
Reports whether a command is available to undo.void
clearListeners()
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.java.lang.String
getRedoLabel()
Returns an optional label for the next command to redo.IActivityRecord
getRedoRecord()
Peeks at the top of the redo stack.java.lang.String
getUndoLabel()
Returns an optional label for the next command to undo.IActivityRecord
getUndoRecord()
Peeks at the top of the undo stack.void
redo()
Redoes a command.void
removeListener(ActivityStackListener obj)
Removes a listener.void
rollback()
Rolls back an application-level transaction.void
rollbackAll()
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(java.lang.String label)
Starts one persistent transaction, which will never be rollbacked once the parent transaction is rollbacked.void
startTrans(java.lang.String string)
Starts an application-level transaction.void
undo()
Undoes a command.
-
-
-
Method Detail
-
canUndo
boolean canUndo()
Reports whether a command is available to undo.- Returns:
true
if a command is available to undo,false
if not.
-
getUndoLabel
java.lang.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
java.lang.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
void startTrans(java.lang.String string)
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
void execute(IActivityRecord record)
Executes the specified record and flushes the redo stack.- Parameters:
record
- the ActivityRecord to execute
-
execute
void execute(IElementCommand command)
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
void addListener(ActivityStackListener obj)
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
void removeListener(ActivityStackListener obj)
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
void startPersistentTrans(java.lang.String label)
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.
-
-