E4/EAS/Saveable Life Cycle

When a user modifies something, a component may choose to notify the user of this in some way. This state transition from "unmodified" to "modified" is known as the "dirty state". When something is dirty, it means that the user has interacted with the object in some way. It may or may not actually be different from the original object but is an indicator to the user that something may be different.

One example of where an editor may be dirty but no actually have its contents be different from the file on disk is where a user has inserted a character and then removed it from the document. Both the insertion and deletion operation are modification operations even if the contents are identical to what's on the disk. However, if the user were to undo the insertion operation instead of using a deletion operation to remove the change, then the dirty state should be cleared.

Eclipse 3.x API

In Eclipse 3.x, the visual cue to the user that a workbench part is dirty is by appending the asterisk character ('*') in front of the part's title. So if the original file was called 'Main.java' and it was edited by the user in the text editor, the title in the tab would switch from 'Main.java' to '*Main.java'. Workbench parts that wish to expose this functionality do so by implementing the org.eclipse.ui.ISaveablePart interface.

Saveable declaration

public class ModelTransformationView extends ViewPart implements ISaveablePart {
 
  private boolean fDirty = false;
 
  /**
   * Alters the dirty state of this part and notifies the workbench
   * of the change.
   */
  private void setDirty(boolean dirty) {
    if (fDirty != dirty) {
      fDirty = dirty;
      // send a notification about our dirty state changing
      firePropertyChange(IWorkbenchPartConstants.PROP_DIRTY);
    }
  }
 
  public boolean isDirty() {
    return fDirty;
  }
 
  /* Other code not included... */
 
}

Dirty state modification

fStateCheckbox.addListener(SWT.Selection, new Listener() {
  public void handleEvent(Event e) {
    // modify the model based on what the user selected
    // in the UI
    fModel.setState(fStateCheckbox.getSelection());
    // send out a dirty notification
    setDirty(true);
  }
});

Saving

public class ModelTransformationView extends ViewPart implements ISaveablePart {
 
  public void doSave(IProgressMonitor monitor) {
    /* Perform the save operation */
  }
 
  /* Other code not included... */
 
}

e4 (Java)

Saveable declaration

All parts can potentially be a saveable part. If you need to send out a notification that your part is dirty, you do so through the MDirtyable interface. You can then retrieve a MDirtyable instance from your part implementation through injection.

public class MySaveablePart {
 
  @Inject
  private MDirtyable dirtyable;
}

public class MySaveablePart {
 
  private MDirtyable dirtyable;
 
  public MySaveablePart(MDirtyable dirtyable) {
    this.dirtyable = dirtyable;
  }
}

Dirty state modification

public void setDirty(boolean dirty) {
  dirtyable.setDirty(dirty);
}

Saving

The framework will invoke your client object's method which is annotated with the @Persist annotation, injecting it with parameters if possible. It is recommended to flag as many parameters as @Optional in case there is insufficient information in the current context. Since the annotation is used to identify which method to invoke, you are under no obligation to name your method doSave(*).

public class MySaveablePart {
  @Persist
  void doSave(IProgressMonitor monitor) {
    /* Perform the save operation */
  }
 
}

If you don't have to have an IProgressMonitor, you can flag it as being optional or just remove it from the method definition.

public class MySaveablePart {
  @Persist
  void doSave(@Optional IProgressMonitor monitor) {
    /* Perform the save operation */
  }
 
}

public class MySaveablePart {
  @Persist
  void doSave() {
    /* Perform the save operation */
  }
 
}