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);

WorkbenchPlugin.getDefault().handleError(Throwable exception, String message, int code);

But in this case we have to override status pluginId with id of a plugin whose method handleError is called.

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).

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 (or "doit" as Christophe suggested)
   */
  boolean handle(IStatus status);

}

I think that our status should have "doit" flag inside like swt events. If we have it, handlers can set it to false if want to stop handling.

Christophe suggested that we can use returned param from handle method for this.

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. I'm not sure about the name, but we can use ErrorStatus as well.

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

Whine levels

• NONE- we are not sure who EH should handle it
• 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

This is only a suggestion for EH. EH should return to user which mode in fact is used. Because return param is reserved allready we should modify a bit hadle(IStatus) method

My suggestion is

public WorkbenchStatus handle(IStatus); 

and in WorkbenchStatus we can carry infos like "handled true or false" and what "whine mode" was used.

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 isn't fixed. It can be changed if it is necessary for developer or vendor. We will have one default policy.

Default policy (After conv. with Christophe)

• tries to handle the problem with default EH for a product
• tries to find a right EH for status plugin
• delegates the problem to default EH

We need to define pattern for each EH which defines statuses which can be hadled by this EH. This pattern is for status plugin and we can use regex pattern or something simplier.

The pattern can look like this "org.eclipse.jface.*". It means that if this EH will be asked to handle the status with pluginId matching this pattern, this EH can handle it.

If the pattern is set to "*" it means that it handles all statuses. Of course when we are going through the policy and we want to find a right EH (point 2 of the policy) we are lookin for the most specific EH. So if we have a status with "org.eclipse.jface..." plugin and we have two EHs one with pattern "org.eclipse.*" and second "org.eclipse.jface.*" the policy will choose the second one.

Of course this policy will respect doit flag.

Old version of the default policy

• 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.

I'm not sure.. but if someone wants to change policy which uses extra attributes or information we should subclass our AbstractErrorHandler and add extra methods or add new attributes in extension.

Example: The new vendor policy is that we have extra "order" attribute. And we have to implement our policy to use new subclass of AbstractEH (OrderedErrorHandler) which have getOrder() method. If this policy meets other EHs it will treat them as EH with default order value.

Handling Errors From Core and JFace

There are two places where we want to hook into existing Core API

• we want to be able to catch calls to ILog
• we want to specify the default error handler (and perhaps error manager) in the product

These issues can already be solved with existing API from Core so that there is no need for them to change anything for this support.

Handling the log

We can use the existing ILogListener so long as we are OK with the .log file also being written (this is how the Error Log view works). From a debugging perspective it is likely best that we keep this file anyways as a last resort way for people to trace errors.

Specifying product error handler

The product extension point allows for addition of parameters to a product. Initially we did not think this was a good idea because we did not want to specify a class name as a String. We can specify a ProductHandler id as a String however as we can assume that any ProductHandler referenced in the product plug-in will have been created by one of it's prerequisites.

Error dialog

(will discuss later)

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!

• What if more that one EH want to visualize a problem? For instance each one wants to show a dialog.
• 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.