Difference between revisions of "Platform UI Error Handling"

Revision as of 07:30, 20 November 2006

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 shelf 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…)

Status manager & Status handlers

Status manager

Status manager decides how to handle a problem occurred in an application. It is located in the workbench and creates instances of status handlers (defined as extensions to statusHandler ext. point). It keeps reference to a workbench status handler.

This is how a developer can use status manager for handling problems in applications.

StatusManager.getDefault().handle(IStatus);

Status handlers

Status handler can be defined as an extension point.

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

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

StatusHandler API

public abstract class AbstractStatusHandler {
	
  /**
   * Passes the status to the handler
   *
   * @param handlingState a state of handling status
   */
  public void handle(StatusHandlingState handlingState);

}

StatusHandlingState

Status handlers get StatusHandlingState object as an argument. The state contains status and handling hint. It is important because handlers can replace statuses and sets reporting hint if necessary.

Handling hints are only 'hints' and handlers can ignore them. We have four values for hint.

• IGNORE - status should be ignored
• LOG - the status should be logged
• SHOW - the status should be shown to an user
• SHOWANDLOG - the status should be logged and shown to an user

The hints issue should be discussed...

WorkbenchStatusHandler and IDEWorkbenchStatusHandler

There are two implementation of status handlers

• org.eclipse.ui.application.WorkbenchErrorHandler which is assigned to WorkbenchAdvisor
• org.eclipse.ui.internal.ide.IDEWorkbenchErrorHandler assigned to IDEWorkbenchAdvisor

The current advisor indicates which handler is the workbench one.

Places for hooking error handling up in the platform

• WorkbenchAdvisor#eventLoopException(Throwable exception) method - it handles all uncaught exceptions from main application loop
• Jobs related stuff - ErrorNotificationManager class - it receives notifications about exceptions in jobs
• Error log file from Core
• Error and Warning dialogs (see the static methods in MessageDialog)
• Exceptions from invalid extension definitions. Everything from failed instantiations (i.e. LightweightDecoratorDefinition#internalGetDecorator) to invalid references determined at load time (i.e. WorkbenchEncodings#getDefinedEncodings).
• Exceptions from opening a part (the error view and error editor)

Status handling policy

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

• tries to handle the problem with default (product) status handler
• tries to find a right status handler for status plugin
• delegates the problem to workbench status handler

We need to define prefix for each status handler which defines statuses which can be hadled by this status handler.

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

If the prefix isn't set, it means that it handles all statuses. Of course when we are going through the policy and we want to find a right handler (point 2 of the policy) we are lookin for the most specific handler. So if we have a status from "org.eclipse.jface" plugin and we have two handlers one with prefix "org.eclipse" and second "org.eclipse.jface" the policy will choose the second one.

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 status handler

There is a requirement to allow rebranding of the status manager when installing on a client site. i.e. company A wants you to use their internal status reporting - not the status reporting supplied by IBM.

The way to do this in other extension points (such as intro) is to redefine the product and updating the extensions so an element for the default status handler would be consistent with how it is done elsewhere in Eclipse. See org.eclipse.ui.intro.introproductbinding.

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 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 workbench handler it can be simply a basic view with stack trace. For product handler 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 handler 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.