Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Platform UI Error Handling"

(Status handlers)
m (Status handlers)
Line 72: Line 72:
  
 
Status handler can be added with the "org.eclipse.ui.statusHandlers" extension point.
 
Status handler can be added with the "org.eclipse.ui.statusHandlers" extension point.
 
  
 
Status handler decides how serious a problem is for plugin, product or company.
 
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.  
 
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).
 
Status handler can log something to a file, can do nothing with it or show error dialog (see Error Dialog).
 
  
 
StatusHandler methods
 
StatusHandler methods

Revision as of 09:09, 11 January 2007

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.

Developers can pass problems to the facility using the default instance of manager

StatusManager.getDefault();

and calling one of three methods from StatusManager API

public void handle(IStatus status);

public void handle(IStatus status, int handlingHint);

public void handle(IStatus status, int handlingHint, Object handlingProps);

Hints are defined in StatusManager class. The names of handling properties are defined in IHandlingContants.

Status handlers

Status handler can be added with the "org.eclipse.ui.statusHandlers" 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 methods

public abstract class AbstractStatusHandler {
	
  /**
   * Handles StatusHandlingState objects. This method can modify
   * status, hint and properties. Each handler can suggest the facility to stop handling a
   * problem. If handling policy respects it, handling will be stopped.
   * 
   * @param handlingState
   *            the handling state
   * @return false if handling should be stopped, true otherwise
   */
  abstract public boolean handle(StatusHandlingState handlingState);

  /**
   * This method is used for collecting statuses which were already handled
   * and logged by the handler. Because the status handling facility handles
   * statuses from plug-in's log, it prevents handling logged statuses again.
   * 
   * This method should be called before each status logging in handlers.
   * 
   * @param status
   *            already handled and logged status
   */
  protected void addLoggedStatus(IStatus status);
}

This is how addLoggedStatus(IStatus status) is used in WorkbenchErrorHandler class and this is a good practice.

  public boolean handle(final StatusHandlingState handlingState) {
    if (handlingState.getHandlingHint() != StatusManager.SHOW
       && handlingState.getHandlingHint() != StatusManager.NONE) {
       addLoggedStatus(handlingState.getStatus());
       WorkbenchPlugin.getDefault().getLog().log(handlingState.getStatus());
    }
    return true;
  }

StatusHandlingState

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

Handling hints

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

  • NONE - nothing should be done with the status
  • 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

Next step is to use logical OR instead of SHOWANDLOG.

Handling properties

Names of the handling properties are defined in IHadlingConstants.

Available properties

  • shell - if a status should be shown, this shell will be used for error dialog
  • action(optional) - action can be associated with a hadled status
  • job - will be used to keep current functionality for job errors
Questions!
  • I would prefer to use default workbench shell for showing error dialog (PlatformUI.getWorkbench().getActiveWorkbenchWindow().getShell())

or null shell if workbench is not initialized. My concern is that we can have more than one error to show with different shells. In this case I would like to show one error dialog for the default shell.

  • JFace error and warning dialogs are modal by default. But our error dialog in the facility will be non-modal.

Is it a problem that JFace errors will be shown in a non-modal dialog?

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 is fixed.

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.

Below is a definition of a hadler with the prefix

  <extension
    point="org.eclipse.ui.statusHandlers">
    <statusHandler
      class="org.eclipse.ui.examples.statushandlers.handlers.SampleStatusHandler"
      id="org.eclipse.ui.examples.statushandling.handlers.SampleStatusHandler">
      <parameter
        name="prefix"
        value="org.eclipse.ui.examples">
      </parameter>
    </statusHandler>
  </extension>

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 Messages: User Interface

Error Messages User Interface Use Cases

There are three types of user interfaces that will present a message, an error or a warning to a user. The three categories are

  • Message that requires user’s action now
  • Message that requires user’s action that can be done later
  • List of messages.
Message that requires action now.

They are typically represented in a modal dialog box. The user has to act on it or he/she will not be able to finish the task. Such a dialog should provide a standard view with an icon and a message. The message can provide an advanced view, in which case a ‘details’ or ‘advanced’ button is present on the standard view. When the user selects the details button, the advanced information about the message are displayed. The provider of the message or the Error handler will provide the user interface that will be embedded in the dialog. The user can pres the details button again, and this will collapse the advanced view. Messages must be persisted in an external file. The message in the modal window is the most relevant to the user and is decided by the ErrorHandler. If the message has offspring, they will be rendered in the advanced user interface.

Message that can have action later.

They are messages that can be error, but do not prevent the user from pursuing his/her task. All message may need to be solved at a certain point, but do not require immediate action. They are usually represented by information and icon in the user interface. The user can finish some other part of the interface before solving the message. Concrete examples are wizard pages and editors. In wizard pages the message is presented at the top of the page, in an editor it is usually embedded in the form editor or on the side of the editor (right or left side) To get more information about the message, the user clicks on it. A modeless window opens with the information. When the user clicks elsewhere, the window closes. Messages do not have to be persistent. The owner of the user interface can decide to save them or decide to recalculate the messages when the user interface is reopened. The owner of the user interface can decide to not allow the task to be saved or finished if the message is not act upon.

List of errors

The user is presented with a double pane view. One pane represents the list of messages. The user can filter them and reorganized them. Some filter could be based on the resources, the format (tree, table) or the dependency (ex: acting on this message will also resolve the following messages…). The filtering mechanism should be lighter in its usage than the current one. When the user selects a message, the second pane is filled with the details of the message. This will show the exact same information as #1. The messages are persistent. PS: the semantic of this user interface is like an ‘email reader’ where you select the email message to see the content of the email. A provider could replace the first pane of the list of errors. ErrorView and Problem view should be merged in a unique view.

Eclipse mapping

MessageDialog and ErrorDialog are of type 1.

The user must act of them. The best practice is that only error message should appear to the user using this format. Warning and Information messages should not. The error handler can decide if a message is worth showing or not and will also provide the details.

Errors in a background process are of type 2.

We should not open a modal dialog when an issue occurs. The user can ‘glance’ in the result in the bottom right corner, click on it to see the list of errors and click on an error to see a detail.

Wizard messages are of type 1.

The user must act on them to go to the next page but also clicking on them will open a pop up. There is no ‘details’ button in the wizard user interface

Error log is of type 3

The view shows the different errors from the log. The user can click on an error in the list to see more details.

Use cases

The User Interface behavior will depend from the context of the error. If an error occurs during a Job, we will not prompt the user but rather notify the Job View. If the same error occurs in the plug-in itself, we will open a modal window.

The error manager framework must keep track of the context and if the error handler decides to show the error to the user, the Error Manager Framework should use the appropriate User Interface.

Context of the use cases

The plug-in is looking for a file named ‘result.txt’ on a web site. When executing, the plug-in is unable to connect to the web server. The plug-in throws an error using the error handler mechanism. The error is modified to notify the user that the remote site does not answer and that the user should check if there is any proxy of if the site is actually down.

Use Case 1
Modal Dialog

The framework realizes the context and opens an ErrorDialog. The ErrorDialog detail is filled with content from the plug-in error handler.

Use Case 2
Job Error

The framework realizes the context and modifies the user interface for the Job. A red ‘x’ appears in the bottom right hand corner of eclipse. The User double clicks on the red ‘x’ and a window opens, showing the message of the error. When the user clicks on the message; the framework opens a modal window like in use case #1.

Use Case 3
Wizard

The framework realizes the context and updates the top of the wizard with the message. When the user hovers over the message a pop up appears. If the user wants to see more details, a modal window opens.

Use Case 4
Error Log

The error handler decided to not show the user about the error. It decided to only log it. The error appears in the error log view. The user clicks on the entry and a modal dialog (like in #1) opens.

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.

New error dialog with a details area

New error dialog without a 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.

Back to the top