Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
E4/Doc/Saveable Life Cycle
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.
Many applications require input from users that needs to be persisted, or saved, between user sessions. Given Eclipse's pluggable nature, having each new plugin that contributes to the UI worry about how to invoke it's own save (for e.x. from File->Save) would result in a lot of redundant, boiler-plate code. E4 provides a consistent and greatly simplified way (over previous Eclipse versions) to allow UI Parts to save information and to notify the framework when a Part is dirty.
Contents
Relevant Terms
Dirty - A Part is considered dirty when it has unsaved changes. A dirty state is typically denoted by a '*' beside the filename on a tab, for example. Editors & Views - Editors and views are UI objects that were created by the plugin in Eclipse 3.x and previous versions. Part - A part is UI object in E4 that removes the distinction between Editor and View to provide more customizable properties.
Motivation
The distinction between Editors and Views in past versions of Eclipse was unnecessary. In e4, all high-level UI elements are instead classified as Parts, and Parts can be customized as required.
The dirty bit is now stored in the model object instead of with the client object, thus removing the need for an extra event to be fired. Instead, the client object calls setDirty on its model object to let the framework know that unsaved changes have been made to it.
In previous versions of Eclipse, the code to do the save was implemented in a "save" method on the client object. In E4, to increase flexibility, you can mark any method with an @Save annotation and it will be called be the framework when a save is invoked.
Applicability
E4's saveable lifecycle features are suitable in any situation where a user needs to be able to save information.
Implementation
A class contributing to the UI can use dependency injection (@Inject) to get instances of the model object (the Part). Parts can be customized using multiple inheritance to implement interfaces like Dirtyable (MDirtyable in Java). These features would allow you, for example, to specify whether your part can become dirty, and to set it dirty or clean. Other customizations are provided by interfaces like Contribution and Item.
The signature of the save method can vary. It can optionally ask for things like a ProgressMonitor or StatusHandler, so that it has access to supporting services for the duration of the save. These services could, for example, be used to notify the user if a save fails, or to keep the user up to date on the progress of a long running operation (like a save over HTTP).
Auto-Save
At this point E4 does not provide an auto-saving features in the framework as noted here however some proposed solutions are found in the aforementioned link and you're encouraged to help out where possible.
Related Services
- Persisting UI State & Data - There is an important distinction between these two services; Persisting UI State & Data is meant for things like user's resizing table column widths and you want to persist that information whereas Saveable Life Cycle deals with user inputted data, like a document in a word editor or information in a bug report.