org.eclipse.birt.report.model.api
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 startTrans(String) 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 commit(). However, if the operation fails, and so the whole sequence should be abandoned, the application calls the rollback() method.

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

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 if canUndo( ) 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 if canRedo( ) 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.



Copyright © 2008 Actuate Corp. All rights reserved.