Platform UI Error Handling

This proposal is for error messages only. It does not include Log, trace or Application Life Cycle linked to errors in a software application. Yet, this proposal should fit very nicely in above mentioned features.

Use cases

We will use 4 different customers to ensure the proposal is scalable

• BigCompany is using Eclipse 3.3. They decide to buy different features from different companies. They want an AJAX feature from company AjaxWorldCom and they decide on a database tooling feature from SQLForever Company. All user will have the same desktop feature and all call should be routed to the BigCompany’s help desk. Users do not have access to the web.

• TaxInc develops an Tax Solution software. It has RCP clients and a server. TaxRUS bought the tax solution. They installed a server internally and deployed the RCP client to 250 employees around the world. The employees are not developers. They just use the RCP application to do Tax related tasks. They have an internal help desk.

• BigSoftware develops a set of Eclipse feature for a product named: J2EE development 13.0. User can buy the product off the self or order a large amount of products and install them in their enterprise. BigSoftware has a huge support center. BigSoftware also ships 3rd party features it supports in its tooling.

• John is a Java Perl developer. He downloaded Eclipse 3.3 and a Perl feature from the open source web site.

Issue to solve

This is the main issue to solve for the 4 customers

When an error occurs in the tooling (Error message, error dialog, error in the console view, error in the log view, error in the job dialog or any other error), Eclipse needs to provide a way for the users to:

• see what the error is
• understand what it means to the them
• how can they act on the error.

The behavior for each is based on policies.

• The feature who threw the error should have a chance to handle the error and help the customer.
• The feature should have an idea about what the error handler wants it to do.
  • i.e. when there is an error opening a view should we show the error view or not
  • also do we prompt when the workbench layout cannot be reset?
• The product/branding that is installed can override all feature’s behavior it ships and manage or delegate to them as appropriate.

See the error

When an error occurs, the developer may decide to show the error to the user. The code is opening an error dialog. Before opening the error dialog, and based on the policy, the flow can be re-routed and the error dialog may never show up like the developer intended to. There should be a hook in the code, based on policy that will express manage the behavior.

What does it mean to me the user?

Most users are not interested in the ‘stack trace’ of the error. When a user sees an error or actively double clicks on an error we ought to see the information on how to solve the error (without technological background). This presumes the feature or the product or the company provided the data the user can understand and that the associated policy allows such data to be shown.

What can I do next?

Based on the policy, it is the responsibility of the feature provider (component provider), the product provider or the company to decide what the ‘what to do next’ action will do. Eclipse could still provide a ‘show log’ button that policy provider can extend (this is a nice to have…)

Error manager & Error handlers

Error manager

Error manager (EM) decides how to handle a problem occurred in an application. It is located in the workbench and manages error handler extensions and creates instances of error handlers (defined as extensions to errorHandler ext. point). It keeps reference to default WorkbenchErrorHandler instance.

This is how a developer can use EM for handling problems in applications

ErrorManager.getDefault().handle(IStatus);

To be more similar to logging stuff, plugin classes can have handleError(IStatus) methods and then a developer can call handle method from plugin, for instance:

WorkbenchPlugin.getDefault().handleError(IStatus);

Basic implementation of plugin handleError(IStatus) is

public void handleError(IStatus)
{
    ErrorManager.getDefault().handle(IStatus);
}

Method handle(IStatus) from EM takes IStatus as an attribute (or subclass of IStatus which carries additional info about problem). Error manager delegates problems to error handlers according to the error handling policy.

If we decide to move EH stuff to the core, we can make it more similar to logging facility. We can add getErrorManager() in the Plugin class and use EM in this way

[PluginClassInstance].getErrorManager().handle(IStatus);

Error handlers

Error handler (EH) can be defined as an extension point.

Error handler decides how serious a problem is for plugin, product or company. It is not responsibility of a plugin to decide how serious a problem is.

Error handler can log error to a file, can do nothing with it or show error dialog (see Error Dialog).

Each EH has two extra attributes

• "productRelated" attribute indicates if the EH is product EH.
• "blocker" indicates if this EH (if can handle the problem) should block other subsequent (according to the policy) EHs. By default is set to true.

ErrorHandler API

public abstract class AbstractErrorHandler {

  /**
   * Checks if the handler can handle the status
   *
   * @param status the IStatus about to be shown
   * @return true if handler can handle the status, false otherwise
   */
  boolean canHandle(IStatus status);
		
  /**
   * Passes the status to the handler
   *
   * @param status the IStatus
   * @return true if handler handled the status, false otherwise
   */
  boolean handle(IStatus status);

}

Questions!

• How can error handlers recognize severity of the problem? Is it necessary?

It is responsibility of the builder of EH

• What extra information should be carried in Status to help error handler to recognize type, severity of problems.

Extra informations can be defined in subclasses of IStatus, we can use status code too

WorkbenchErrorHandler and WorkbenchStatus

Eclipse has its default error handler called Workbench EH or default EH.

WorkbenchStatus is a implementation of IStatus which has extra information for Workbench EH.

One of these extra infos is "whine mode" - which indicates to EH how errors should be handled.

We can introduce this in two ways

Either fixed levels, for instance

• IGNORE - EH should ignore the error
• SILENT - EH should handle it in silent way, e.g. log to file
• SHOW - EH should show the problem to an user, e.g. error dialog

or

like in logging facility. We will have levels of severity and we will decide from which level EH should handle problems in SILENT mode and from which in SHOW mode.

Example: Five levels of severity and we have handler where from severity 2 we have SILENT mode and from severity 5 we have SHOW mode.

We can use status code for carrying this "whine mode" but I suggest leave it for plugin purposes. We can use codes for error reporting.

Policy of choosing error handlers by the manager

The policy can be fixed (as Christophe suggested) or can be defined dynamically in for instance xml file assigned to the application.

Fixed policy can look like this

• tries to handle the problem with product EH (if application runs as a product)
• tries to handle the problem with any product related EH
• tries to handle the problem with the EH for status plugin
• delegates the problem to default EH

What is a difference between product & product related EHs? Both have product related flag set to true. But product EH is a handler defined in a current product plugin.

If we agree for having "blocker" attribute in EHs, we will control the flow from EHs too. If all EHs have blocker set to false, the status will be handled by all handlers which can handle it. But by default this attribute is set to true, so if one EH can handle the problem it blocks subsequent ones and handling is over.

If we set our product handler "productRelated" flag to false error handling won't be stopped even if EH manages to handle the problem.

Questions!

• Fixed or dynamically defined policy? If dynamically defined… what can be dynamic? 
• If fixed, which policy is better?
• Should we delegate problems to a “lower layer” (from product do plugin EH) if EH can’t handle them?
  • How should JFace errors be handled?
  • Do we want some support in equinox.common and what should it look like?

Error dialog

This is the way of showing problems to application users.

Main requirements

• shows list of the problems
• shows details of the problems
• shows view which helps user to handle or report the problems

Each problem on the list should have error reporting view (ERView) associated to it. This relation can be set in error handler which handles the problem. This reporting view will be showed in the tray part of the dialog.

For Eclipse EH it can be simply a basic view with stack trace. For company or product EH it can be a html view with a form for registering the problem or for checking the state of the problem.

Below sample error dialogs with and without extra details area.

In a tray of the dialogs there is an error reporting view. In these cases this is a html view with form to raise a problem in the eclipse bugzilla.

Questions!

• How long the problem should be visible on the list (until it is handled? or user can decide that it should be deleted)
• Should the problem list be persisted?
• Is it necessary to have both details and tray view? We can use tray to show details of the problem.
• Should we show each problem or error, or should we group the same problems and show them as one line in the list?

Although we will be able to show (use) the error dialog directly, it would be a good practice to do this through error manager.