|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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.
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 | |
---|---|
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 |
---|
boolean canUndo()
true
if a command is available to undo,
false
if not.java.lang.String getUndoLabel()
null
if either the
command has no label, of if there is no command to undo.void undo()
canUndo( )
returns
true.
boolean canRedo()
true
if a command is available to redo,
false
if not.java.lang.String getRedoLabel()
void redo()
canRedo( )
returns
true.
void setStackLimit(int limit)
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.
limit
- the new undo stack sizevoid startTrans(java.lang.String string)
string
- the localized label of the transactionvoid commit()
void rollback()
void rollbackAll()
void flush()
IActivityRecord getRedoRecord()
IActivityRecord getUndoRecord()
void execute(IActivityRecord record)
record
- the ActivityRecord to executevoid execute(IElementCommand command)
command
- the ActivityRecord to executevoid addListener(ActivityStackListener obj)
obj
- the activity stack listener to registervoid removeListener(ActivityStackListener obj)
obj
- the activity stack listener to removevoid startPersistentTrans(java.lang.String label)
label
- the localized label of the transactionvoid clearListeners()
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |