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.

• Key - A key is a unique string identifier for a preference setting.

Motivation

In eclipse the "Easy things should be easy."

Status reporting adheres to this by simplifying the most common case when a developer needs to report an event without being necessarily concerned about the details of the reporting code. Therefore, with Status Reporting the programmer can make a decision at a time an exception or event occurs on what severity and type of reporting is necessary. The framework cannot infer the severity and content of the event; only the programmer is aware of the context. In e4 there is a separation between client and provider side view of the service.

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 most common case the developer specifies two parameters: severity and style. There are three styles which are handled by default: log, show and block. The log style causes an event to be logged using the logging service. The show style displays a message to the user. The block style will suspend all program operation and prompt the user for an action.

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