E4/Doc/Status Reporting

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.

A placeholder diagram.

Status reporting is a service which provides developers with a simple API for system components about various events. Consumers of a reporting service need not be concerned with the details of how event information is disseminated or responded to; they must only determine when notifications of the appropriate type should occur.

For example, status reporting could be used to trigger a pop-up dialogue for a "File Not Found" exception. The component generating the exception would create an appropriate notification, and the status reporting service would deliver and the notification to a component that displays the pop-up.

Relevant Terms

• Style - A style is a mandatory attribute of a status notification that determines how recipients respond. Eclipse e4 provides three standard styles:
  • LOG - The LOG style indicates that a notification should be logged.
  • SHOW - The SHOW style indicates that a notification should be displayed to a system's user.
  • BLOCK - The BLOCK style indicates that a notification should suspend user operations and ask the user for input.

• Severity - A severity level classifies the degree to which a event is problematic for continuing program execution. Eclipse specifies five severity levels: OK, INFO, WARN, ERROR, and CANCEL.

Motivation

Status reporting in Eclipse e4 is a product of an unofficial e4 mantra, "The Easy Thing Should Be Easy." Instead of having to be concerned with the complexities of customized status reporting, consumers of the service who want to report a status in a standard way can do so simply. The minority of service consumers who require greater control over how status notifications are handled can still do so through a correspondingly complex API.

The simplicity of the e4 status reporting service means that, at a minimum, a developer most only provide status information which cannot be supplied by framework inferences. As a developer requires greater specificity over how components respond to status notifications, more information can be supplied.

Applicability

The applications of status reporting are many:

• I/O handlers: report errors and exception
• Events of importance to the user:
  • Somebody opens a file that is currently being edited
  • The user attempts to close an unsaved document

Implementation

In the "80-percent" case where a status notification receives standard handling, a developer must specify only two attributes: severity and style. Possible severity levels are those standardized by Eclipse, and there are three styles for which default handlers are provided: log, show and block.

If the default handlers are not applicable to the specific application, custom handlers can be specifying by editing the provider side of the service. In addition, during application deployment a developer can decide the details of handling for the default styles. For example, the log style can be modified to interact with a DB, the block