UndoRedo V1.2
by Matthew Ford
2005/06/27

au.com.forward.undoRedo
Interface ICanBeRolledBack

All Known Implementing Classes:
UndoRedoEdit

public interface ICanBeRolledBack

This interface marks an UndoableEdit as being able to roll back the undo/redo tree in the event that it fails or is cancelled. This interface also allows for re-syncing the undo/redo tree to the last edit sucessfully completed.

When the UndoableEdit is registered with the UndoRedoManager (via UndoRedoManager.undoableEditHappened(javax.swing.event.UndoableEditEvent)) and each time and undo or redo is performed by the UndoRedoManager, the setFrameMarker(java.lang.Long) is called with the current frameMarker.

This means that the same UndoableEdit will have multiple frameMarkers set as undos and redos are preformed. This means you need to save the frameMarker somewhere else (typically with the task preforming the operation) at the beginning of the intial edit and at the start of any undo/redo. If the edit, undo or redo fails to complete sucessfully (i.e is cancelled or fails), call UndoRedoManager.cancel(java.lang.Long) to remove the unsucessful operation from the undo/redo tree. You can also re-sync the tree to the last sucessfull command by calling UndoRedoManager.syncToLastSuccessfull(java.lang.Long) passing it the frame of the last command sucessfully processed. If the edit, undo or redo is sucessful you can call UndoRedoManager.disposeOfRollBack(java.lang.Long) to free the resources used by the frameMarker. Alternatively freeing references to the marker will allow it to be garbaged collected as it is only weekly held be the UndoRedoManager.


Method Summary
 java.lang.Long getFrameMarker()
          Returns the last frameMarker set.
 void setFrameMarker(java.lang.Long marker)
          Called by the UndoRedoManager to set the frame marker for future roll back.
 void setUndoState(boolean undoState)
          Sets the undo or redo state.
 

Method Detail

setFrameMarker

void setFrameMarker(java.lang.Long marker)
Called by the UndoRedoManager to set the frame marker for future roll back.
This method is called when the UndoableEdit is registered with the UndoRedoManager and each time an undo or redo operation is performed on this UndoableEdit, so the frame marker it needs to be saved elsewhere (usually with the task performing the operation).

Parameters:
marker - the frameMarker associated with this operation

getFrameMarker

java.lang.Long getFrameMarker()
Returns the last frameMarker set.
Because the frameMarker is set for the original edit and every subsequent undo/redo of it, the frameMarker needs to be saved with the task preforming the operation.

A typical implementation of this method nulls the frameMarker when it is returned.
Nulling the frameMarker here allows it to be garbaged collected from the UndoRedoManager when there are no other references.
I.e. a typical implementation would be:-

  public Long getFrameMarker() {
   Long rtn = frameMarker;
   frameMarker = null;
   return rtn;
  }
 

Returns:
the last frameMarker set.

setUndoState

void setUndoState(boolean undoState)
Sets the undo or redo state.
Called multiple times by the UndoRedoManager when rolling back to reset the UndoableEdit to its previous state.

This method should also do any other clean up necessary in the UndoableEdit to return it to its previous state.

This method is only called to toggle the state. That is if the current state is canRedo() then
setUndoRedoState(true);
will be called to change the state to canUndo();

Note: The hasBeenDone variable in AbstractUndoableEdit has package scope and no direct setter, so if you are extending from AbstractUndoableEdit then to set the hasBeenDone flag to true you need to call

 try {
   super.undo();
 } catch (CannotUndoException cex) {
  // ignore
 }
 
To set it to false use
 try {
   super.redo();
 } catch (CannotRedoException cex) {
  // ignore
 }
 

Parameters:
undoState - true to return UndoableEdit to undo state, false to return it to a redo state.

©2005, Forward Computing and Control Pty. Ltd
ACN 003 669 994   NSW Australia
All Rights Reserved.