E4/Doc/Saveable Life Cycle

Under Construction: Please read first!

The evolution of this document is a collaborative effort between a team of students at the University of Manitoba and the wider Eclipse community. Details about the project can be found here and on our Blog.

Your input is not just welcome; it is needed! Please contribute as your expertise allows, while adhering to our template. To send your feedback and any questions or comments you may have please email us. Also, while we do our very best to be as accurate and precise as possible, it is worth noting that we are students with limited exposure to the Eclipse platform, so if you see any incorrect technical details please let us know.

Description

Tracking the state of user-modifiable 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.

Consumer

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

Java

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

Producer

e4 specific description of the service/ implementation details etc.

Usage

Code Samples

Eclipse 3.x

(this is not likely needed here)

Related Materials

Related Services

• Reporting Progress

Related API's

See Also