Package 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

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.
`String`
`getRedoLabel()`
Returns an optional label for the next command to redo.
`IActivityRecord`
`getRedoRecord()`
Peeks at the top of the redo stack.
`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(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 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

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(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(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.