Difference between revisions of "E4/Doc/Status Reporting"

Revision as of 18:26, 7 April 2010

A diagram of the status reporting service's use with default handlers

Status reporting is a service which provides developers with a simple API for notifying system components about various events. Instead of being concerned with how event information is disseminated or responded to, consumers of a reporting service can simply focus on determining when events of the appropriate type should occur.

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

Relevant Terms

• Style - A style is a mandatory attribute of a status notification that determines how a status is handled.

• Severity - A severity level classifies the degree to which a event is problematic for continuing program execution.

Motivation

Status reporting in Eclipse e4 is a product of an unofficial e4 mantra, "The Easy Thing Should Be Easy." Consumers of the service who want to report a status in a standard way can do so simply, ignoring the complexities which underlie the reporting mechanism. 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 a developer needs only to provide status information which cannot be inferred by the framework. 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, encompassing a large variety of situations where one or more system components must be kept aware of system events. These situations include:

• Reporting errors and exceptions encountered by I/O handlers.
• Notifying users about potentially dangerous situations:
  • A second user opens a file that is currently being edited
  • A user attempts to close an unsaved document
• Logging the progress of a scheduled operation.

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 a set of styles for which the framework provides default handlers.

Styles dictate the class of handler that is used to report a status, and severity values can be used to further customize handler behaviour. For example, the default handler for the SHOW style displays a pop-up notification with an icon that corresponds to the provided severity level.

The following code example demonstrates how a developer might use the status reporting service after catching an exception. The ERROR severity is specified as a parameter for the created Status object, and the SHOW style is provided as a parameter to the injected StatusReporter.

@Inject Provider<StatusReporter> statusReporter;
 
public void foo() {
  try {
    // some operation
  } catch (SomeException ex) {
     //Create a new status
     IStatus someStatus = statusReporter.newStatus(IStatus.ERROR, "A SomeException was thrown!", ex);
     //Report the status
     statusReporter.report(someStatus, StatusReporter.SHOW);
  }
}

In the "20-percent" case where default handlers are not suitable, custom handlers can be defined by a developer. These custom handlers can be associated with newly-defined styles, or can override the default handlers for standard styles. For example, a custom handler might be defined to log a status to a database in addition to displaying a pop-up when a SHOW style is specified.

Related Services

• Notifications