Tracking the state of user-modifyable resources is a common development problem. It is often useful for the UI to be aware of whether a resource has changed, but manually comparing two versions of a resource is computationally expensive and usually unnecessary.

For example, a user may wish to recieve an alert when a text editor is closed with unsaved changes. The details of any changes are irrelevant; the user is only concerned about the fact that changes have occurred.

Eclipse's Saveable life cycle features address the problem of resource modification at the level of workbench Parts. Parts can be made dirtyable, saveable, or both.

Usage

A dirtyable workbench part is deemed 'dirty' if has modified, unsaved content. To become clean, the changes to a Part's contents must be saved or reverted through an undo command. In e4, any Part can be made dirtyable. Typically, however, it will only be reasonable for Parts which modify and save content to utilize this feature. As a result, Parts where are dirtyable are also often saveable.

A saveable Part is definied by its ability to save its associated content. Usually, a Part will be made saveable if it allows user-modification of some associated resource. More generally, any Part can which provides the ability to persist its data can be saveable.

Code Samples

In e4, saveable Parts are built using SaveablePart objects. A SaveablePart is defined in a plugin's XMI file.

<children
    xsi:type="application:SaveablePart"
    id="MySaveablePart"
    URI="platform:/plugin/org.eclipse.e4.examples/org.eclipse.e4.examples.MySaveablePart"
    name="MySaveablePart"
    iconURI="platform:/plugin/org.eclipse.e4.demo.contacts/icons/silk/folder_user.png"/>

To provide dirty/clean functionality, a Part must be associated with an object which implements the MDirtyable interface. This can be implemented through constructor injection. When a Part becomes dirty, it calls the setDirty() method of its associated MDirtyable.

public class MySaveablePart {
 
  private MDirtyable dirtyable;
 
 
  public MySaveablePart(MDirtyable dirtyable) {
 
    this.dirtyable = dirtyable;
  }
 
  public void setDirty(boolean dirty) {
    dirtyable.setDirty(dirty);
  }
}

When a save is requested for an SaveablePart, the framework calls the Part's doSave(*) method. The user-defined doSave(*) can take any parameters. One might choose, for example, to inject an IProgressMonitor for reporting save progress.

  public void doSave(IProgressMonitor monitor) {
    /* Perform the save operation */
  }

Eclipse 3.x

In Eclipse 3.x, views can expose dirtyable functionality by implementing the ISaveablePart interface. This interface enforces a setDirty() method. The setDirty() method typically modifies the PROP_DIRTY workbench constant associated with the view. This contrasts with the e4, where SaveableParts need not be aware of the workbench.

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... */
 
}

e4 specific description of the service/ implementation details etc.

Usage

Code Samples

Eclipse 3.x

(this is not likely needed here)

Related Services

Related API's

See Also