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"

m
(Overview)
(141 intermediate revisions by 7 users not shown)
Line 1: Line 1:
== Error manager & Error handlers ==
+
{{Platform UI}}
 +
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.
  
=== Error manager ===
+
== Use cases ==
  
Error manager decides what to do with a problem occurred in an application.
+
We will use 4 different customers to ensure the proposal is scalable
  
Error manager (EM) is a part of the framework which can be used directly or by calling method handleError() from plugin (in a similar way as log() method) which delegates problems to the error manager.
+
*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.
Method handleError() takes IStatus as an attribute (or subclass of IStatus which carries additional info about problem)
+
  
Error manager decides which error handler should handle the problem.
+
*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.
  
=== Error handlers ===
+
*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.
  
Error handler (EH) is related to a plugin. It can be defined as an extension point. If plugin is defined as a product, its error handler is a product error handler (ProductEH).
+
*John is a Java Perl developer. He downloaded Eclipse 3.3 and a Perl feature from the open source web site.
  
If we want to introduce company (admin) error handler (CompanyEH) we have to install something what we can call Support Centre plugin and its EH becomes company error handler.
+
=== Issue to solve ===
  
Error handler decides how serious a problem is for plugin, product or company.
+
This is the main issue to solve for the 4 customers
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).
+
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.
  
;Questions!
+
The behavior for each is based on policies.
*How can error handlers recognize severity of the problem? Is it necessary?
+
*The feature who threw the error should have a chance to handle the error and help the customer.
*What extra information should be carried in Status to help error handler to recognize type, severity of problems.
+
*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.
  
=== Policy of choosing error handlers by the manager ===
+
=== See the error ===
  
The policy can be fixed (as Christophe suggested) or can be defined dynamically in for instance xml file assigned to the application.
+
It is very important to distinguish between expected and unexpected error.
 +
* Expected Error is when a developer expects the exception to be thrown in particular situation (network not available, resource locked by another person, invalid license etc).
 +
* Unexpected Error is an error that should not happen (internal error, NPE etc).
  
Fixed policy can look like this
+
Generally expected errors should come with idea how to solve the problem, while it should be easy to report unexpected one and/or to get workaround.
  
If company handler is defined errors are forwarded to it.
+
When an error occurs, the developer may decide to show the error to the user. The code is opening an error dialog. However handler may ignore developer request and handle the error in different way, f.e. log it. 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.
If no company handler, errors are delegated to product handler.
+
If no product handler, manager checks if plugin has its own handler.
+
If not, manager asks all plugin handlers whether they want to handle the error. (Small change to Christophe way)
+
At the end we have eclipse handler which handles problems in “let’s say eclipse way” ;-)
+
  
Each EH can have at least two methods
+
=== What does it mean to me the user? ===
handleError() – which actually handles a problem
+
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).
canHandleError() – which asks a handler if it can handle a problem
+
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.
  
;Questions!
+
=== What can I do next? ===
*Fixed or dynamically defined policy? If dynamically defined… what can be dynamic?
+
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.
*If fixed, which policy is better?
+
Eclipse could still provide a ‘show log’ button that policy provider can extend (this is a nice to have…)
*Should we delegate problems to a “lower layer” (from company to product EH, from product do plugin EH) if EH can’t handle them?
+
  
== Error dialog ==
+
== Status manager & Status handlers ==
  
This is the way of showing problems to application users.
+
=== Status manager ===
  
;Main requirements
+
StatusManager is the entry point for all statuses to be reported in the user interface. Handlers are not intended to be used directly. They should be referenced via the StatusManager which selects the handler corresponding to the product to apply. Right now it is impossible to have more than one handler per product because of scalability issues.
*shows list of the problems already occurred in the application
+
 
 +
 
 +
The following methods are the API entry points to the StatusManager
 +
 
 +
<code><pre>
 +
StatusManager#handle(IStatus)
 +
 
 +
StatusManager#handle(IStatus, int)
 +
 
 +
StatusManager#handle(StatusAdapter)
 +
 
 +
StatusManager#handle(StatusAdapter, int)
 +
</pre></code>
 +
 
 +
The StatusManager singleton is accessed using
 +
 
 +
<code><pre>
 +
StatusManager.getManager()
 +
</pre></code>
 +
 
 +
The <code>int</code> parameter are for supplying style for handling. See [[Platform UI Error Handling#Styles|Acceptable styles]].
 +
 
 +
'''NOTE!''' the style is a suggestion and may not be honoured by the current handler. For instance
 +
a handler may choose to not show the user anything when the SHOW flag is sent. See [[Platform UI Error Handling#Status handlers|Status handlers]] for more details.
 +
 
 +
The StatusManager gets it's list of handlers from the extension point <code>org.eclipse.ui.statusHandlers</code>. Should none of those handlers process the status it
 +
will fall through to the default handler (the the SDk this is <code>WorkbenchAdvisor#getWorkbenchErrorHandler()</code>). If a handler is associated with a product, it is used instead of this defined in advisor.
 +
 
 +
=== Styles ===
 +
 
 +
Below is a list of StatusManager styles which can be combined with logical OR.
 +
*NONE - a style indicating that the status should not be acted on. This is used by objects such as log listeners that do not want to report a status twice
 +
*LOG - a style indicating that the status should be logged only
 +
*SHOW - a style indicating that handlers should show a problem to an user without blocking the calling method while awaiting user response. This is generally done using a non modal dialog
 +
*BLOCK - a style indicating that the handling should block the calling method until the user has responded. This is generally done using a modal window such as a dialog
 +
 
 +
=== Status handlers ===
 +
 
 +
Status handlers are part of the status handling facility. The handlers are responsible for presenting statuses by logging or showing appropriate feedback to the user (generally dialogs). All status handlers extend <code>org.eclipse.ui.statushandlers.AbstractStatusHandler</code> which requires each handler to implement <code>handle(StatusAdapter status, int style)</code>. This method handles statuses based on a handling style. The style indicates how status handler should handle a status. See [[Platform UI Error Handling#Styles| Acceptable styles]].
 +
 
 +
There are two ways for adding handlers to the handling flow.
 +
* using extension point <code>org.eclipse.ui.statusHandlers</code>
 +
* by the workbench advisor and its method {@link WorkbenchAdvisor#getWorkbenchErrorHandler()}.
 +
 
 +
If a handler is associated with a product, it is used instead of this defined in advisor.
 +
 
 +
 
 +
A status handler has the id and a set of parameters. The handler can use them during handling. If the handler is added as an extension, both are set during initialization of the handler using elements and attributes of <code>statusHandler</code> element.
 +
 
 +
 
 +
'''WARNING!''' We have to take the extra action when something has to be logged using the default logging mechanism, because the facility is hooked into it. See [[Platform UI Error Handling#Hooking the facility into Platform|Hooking the facility into Platform]]. For this special case the status manager provides API.
 +
 
 +
<code><pre>
 +
  StatusManager#addLoggedStatus(IStatus status)
 +
</pre></code>
 +
 
 +
And below is the example of <code>addLoggedStatus(IStatus status)</code> proper usage.
 +
 
 +
<code><pre>
 +
  public void handle(final StatusAdapter statusAdapter, int style) {
 +
 
 +
    ...
 +
 
 +
    if ((style & StatusManager.LOG) == StatusManager.LOG) {
 +
      StatusManager.getManager().addLoggedStatus(statusAdapter.getStatus());
 +
        WorkbenchPlugin.getDefault().getLog().log(statusAdapter.getStatus());
 +
    }
 +
  }
 +
</pre></code>
 +
 
 +
=== StatusAdapter ===
 +
 
 +
The StatusAdapter wraps an instance of IStatus subclass and can hold additional information either by using properties or by adding a new adapter. Used during status handling process.
 +
 
 +
=== The facility and Platform ===
 +
 
 +
The places where the facility is hooked in
 +
 
 +
* <code>WorkbenchAdvisor#eventLoopException(Throwable)</code> - it handles all uncaught exceptions from main application loop
 +
* Jobs framework
 +
* Error log file (all logged messages are forwarded to the facility with the LOG style)
 +
* Exceptions from opening a part (the error view and error editor)
 +
 
 +
Platform is still under refactoring aimed at introducing the status handling facility.
 +
 
 +
 
 +
'''WARNING!''' The facility isn't hooked into JFace ErrorDialog or MessageDialog in any way. The code has to be refactored if the facility is to be used.
 +
 
 +
The old code
 +
 
 +
<code><pre>
 +
  ErrorDialog.openError(...);
 +
</pre></code>
 +
 
 +
or
 +
 
 +
<code><pre>
 +
  MessageDialog.openError(...);
 +
</pre></code>
 +
 
 +
should be refactored into
 +
 
 +
<code><pre>
 +
  StatusManager.getManager().handle(..., StatusManager.SHOW);
 +
</pre></code>
 +
 
 +
== 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.
 +
 
 +
== 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 details of the problems
 
*shows view which helps user to handle or report 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.
+
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.
 
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.
+
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.
 +
 
 +
===New StatusDialog===
 +
 
 +
==== Overview ====
 +
New Status Dialog is integrated with Status Handling facility. Unless no other handler is specified, the default dialog will be used.
 +
 
 +
<b>Main concepts</b>
 +
* Message - This is the most important piece of information.
 +
* Details - Sometimes there is not enough place to display all necessary info on the dialog, or we do not want to scary the user. Then we can place leading message on the dialog, and all other things make accessible via details area. Currently it is possible to set up one kind of details area provider, but there is no further requirement.
 +
* Support - It is possible to place some contact form on the dialog, so the user will know where to look for help or will be able to easily contact vendor.
 +
 
 +
Support and Details are terms introduced to distinct the behavior and functionality although they extend common abstract class. One should remember that user expects more information after pressing "Details >>>" button.
 +
 
 +
<b>Messages hierarchy</b>
 +
 
 +
Status Dialog uses following messages hierarchy:
 +
* Job name (if available)
 +
* StatusAdapter title
 +
* IStatus message
 +
* MultiStatus information (applies only if MultiStatus is handled).
 +
* message extracted from exception
 +
* exception name
 +
 
 +
Status Dialog displays always two the most important messages. If first one is not found then the dialog should give information about general error instead. If the second one is not found, dialog should point to the details.
 +
 
 +
<b>User interface</b>
 +
* Only one status is handled
 +
** First message displayed is the most important message.
 +
** Second message displayed is the second most important message.
 +
** Timestamp is displayed in the details (if available)
 +
* More statuses handled - the selection list appears
 +
** There is the most important message used on the selection list.
 +
** The second most important message is displayed right to the severity icon.
 +
** Timestamp (if available) is appended to the message in the selection list.
 +
 
 +
<b>Extensions</b>
 +
* Details area can be replaced - it does not display stack trace anymore, rather the error hierarchy (message from Status, Exception, Nested statuses, etc) by default. Product may decide to provide some high level description, or even retrieve description from database.
 +
* Support area can be added - product may hook into the error dialog and place there f.e. browser with url pointing to the helpdesk, or some reporting mechanism.
 +
 
 +
The basic idea is that even unexperienced user should be able to understand what is going on while looking at details, and should be able to report/get help using support area.
 +
 
 +
<b>Examples:</b>
 +
* Only one status is reported. Primary message and secondary message should be displayed. Secondary message should have timestamp if one is available.
 +
[[Image:Singlestatus2.jpg]]
 +
 
 +
* Job reported an error. Display message informing which job, and primary message.
 +
[[Image:Singlejob2.jpg]]
 +
 
 +
 
 +
* Multiple errors occured. On the list should be displayed job name or primary message of the status. In the title primary message should appear for jobs and secondary for statuses.
 +
[[Image:Manystatuses.jpg]]
 +
 
 +
* One stastus has been reported and support is available.
 +
 
 +
[[Image:Statusdialogwithsupport.JPG]]
 +
 
 +
after pressing bug icon:
  
Below sample error dialogs with and without extra details area.
+
[[Image:Statusdialogwithsupportopened.JPG]]
  
[[Image:ErrorDialog1.jpg|thumb|Description]]
+
and many statuses. The selected in the list Status is a base for support area.
  
[[Image:ErrorDialog2.jpg|thumb|Description]]
+
[[Image:Manystatuseswithsupportopened.JPG]]
  
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.
+
==== Use cases ====
  
;Questions!
+
To be done
*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.
+
==== Usage ====
  
Error types (related to problem list)
+
<font color="red"><b>Note for WorkbenchStatusDialog clients</b></font><br/>
 +
Please note that WorkbenchStatusDialog#getPrimaryMessage & WorkbenchStatusDialog#getSecondaryMessage begin searching for the message from StatusAdapter title.
 +
It means that when we are handling job statuses we display:
 +
*single status
 +
** job name as the first message
 +
** WorkbenchStatusDialog#getPrimaryMessage result as second message
 +
*list
 +
** job name (and eventually timestamp) as the position on the list.
 +
** WorkbenchStatusDialog#getPrimaryMessage result right to the severity icon.
  
Developer can define error types for a plugin as extension points.
+
==== Bugs ====
  
Each such a type can define icon of the error type and other things which can be rendered in the error dialog list. Of course if we want to use error types in other areas, it can have more parameters and attributes.
+
{| border="1" align="center" cellpadding="3" cellspacing="1"
 +
! No
 +
! Task
 +
! Assigne
 +
! Status
 +
! Bug id
 +
|-
 +
| 1. || Create new StatusDialog exteds TrayDialog || krzysztof.michalski@pl.ibm.com || done ||  193612
 +
|-
 +
| 2. || Merge old StatusDialog and StatusNotificatonsManager functionality || krzysztof.michalski@pl.ibm.com || done ||
 +
|-
 +
| 3. || Add possibility of set label provider on StatusListView || krzysztof.michalski@pl.ibm.com || done ||
 +
|-
 +
| 4. || Add slection change Listener on StatusListView which recreate reportingView || krzysztof.michalski@pl.ibm.com || done ||
 +
|-
 +
| 5. || Create ReportingTray extends DialogTray || krzysztof.michalski@pl.ibm.com || done ||
 +
|-
 +
| 6. || Create InternalDialog to manage modal of window || krzysztof.michalski@pl.ibm.com || done ||
 +
|-
 +
| 7. || Add possibility of create reporting view: by method createReportingView, setStatusAdapter || krzysztof.michalski@pl.ibm.com || in progress ||
 +
|-
 +
| 8. || Creating reporting view by Policy || krzysztof_daniel@pl.ibm.com || done || 180300
 +
|-
 +
| 9. || Explanation and Action in IStatus || krzysztof_daniel@pl.ibm.com || done || 179373
 +
|-
 +
| 10. || User decides if open support area || krzysztof.michalski@pl.ibm.com || done || 179375
 +
|-
 +
|}
  
The error type has id. We can use error class name (for instance NullPointerException) as the id.  
+
===Work plan for 3.4.1 & 3.5===
  
If we have Status with NullPonterException in the error dialog list, the error type with this id and for plugin which caused the error will be used to render the problem in the list.
+
{| border="1" align="center" cellpadding="3" cellspacing="1"
 +
! No
 +
! Task
 +
! When
 +
! Assigne
 +
! Status
 +
! Bug id  
 +
|-
 +
| 1. || Update this document to reflect real Status Handling capabilities|| 3.4.1 || krzysztof_daniel@pl.ibm.com || in progress||
 +
|-
 +
| 2. || Incorporate ErrorDialog into status handling|| 3.5 || krzysztof_daniel@pl.ibm.com || ||
 +
|-
 +
|}
  
If we define error type only for super type (e.g. error, exception or runtime exception) it will be used for errors which inherit from this type.
 
  
The same as in EH’s we can override error types in plugin defined as a product or in Support Center plugin.
+
[[Category:Platform UI]]

Revision as of 06:55, 21 July 2008

Template:Platform UI 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

It is very important to distinguish between expected and unexpected error.

  • Expected Error is when a developer expects the exception to be thrown in particular situation (network not available, resource locked by another person, invalid license etc).
  • Unexpected Error is an error that should not happen (internal error, NPE etc).

Generally expected errors should come with idea how to solve the problem, while it should be easy to report unexpected one and/or to get workaround.

When an error occurs, the developer may decide to show the error to the user. The code is opening an error dialog. However handler may ignore developer request and handle the error in different way, f.e. log it. 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

StatusManager is the entry point for all statuses to be reported in the user interface. Handlers are not intended to be used directly. They should be referenced via the StatusManager which selects the handler corresponding to the product to apply. Right now it is impossible to have more than one handler per product because of scalability issues.


The following methods are the API entry points to the StatusManager

StatusManager#handle(IStatus)

StatusManager#handle(IStatus, int)

StatusManager#handle(StatusAdapter)

StatusManager#handle(StatusAdapter, int)

The StatusManager singleton is accessed using

StatusManager.getManager()

The int parameter are for supplying style for handling. See Acceptable styles.

NOTE! the style is a suggestion and may not be honoured by the current handler. For instance a handler may choose to not show the user anything when the SHOW flag is sent. See Status handlers for more details.

The StatusManager gets it's list of handlers from the extension point org.eclipse.ui.statusHandlers. Should none of those handlers process the status it will fall through to the default handler (the the SDk this is WorkbenchAdvisor#getWorkbenchErrorHandler()). If a handler is associated with a product, it is used instead of this defined in advisor.

Styles

Below is a list of StatusManager styles which can be combined with logical OR.

  • NONE - a style indicating that the status should not be acted on. This is used by objects such as log listeners that do not want to report a status twice
  • LOG - a style indicating that the status should be logged only
  • SHOW - a style indicating that handlers should show a problem to an user without blocking the calling method while awaiting user response. This is generally done using a non modal dialog
  • BLOCK - a style indicating that the handling should block the calling method until the user has responded. This is generally done using a modal window such as a dialog

Status handlers

Status handlers are part of the status handling facility. The handlers are responsible for presenting statuses by logging or showing appropriate feedback to the user (generally dialogs). All status handlers extend org.eclipse.ui.statushandlers.AbstractStatusHandler which requires each handler to implement handle(StatusAdapter status, int style). This method handles statuses based on a handling style. The style indicates how status handler should handle a status. See Acceptable styles.

There are two ways for adding handlers to the handling flow.

  • using extension point org.eclipse.ui.statusHandlers
  • by the workbench advisor and its method {@link WorkbenchAdvisor#getWorkbenchErrorHandler()}.

If a handler is associated with a product, it is used instead of this defined in advisor.


A status handler has the id and a set of parameters. The handler can use them during handling. If the handler is added as an extension, both are set during initialization of the handler using elements and attributes of statusHandler element.


WARNING! We have to take the extra action when something has to be logged using the default logging mechanism, because the facility is hooked into it. See Hooking the facility into Platform. For this special case the status manager provides API.

  StatusManager#addLoggedStatus(IStatus status)

And below is the example of addLoggedStatus(IStatus status) proper usage.

  public void handle(final StatusAdapter statusAdapter, int style) {
  
    ...

    if ((style & StatusManager.LOG) == StatusManager.LOG) {
      StatusManager.getManager().addLoggedStatus(statusAdapter.getStatus());
        WorkbenchPlugin.getDefault().getLog().log(statusAdapter.getStatus());
    }
  }

StatusAdapter

The StatusAdapter wraps an instance of IStatus subclass and can hold additional information either by using properties or by adding a new adapter. Used during status handling process.

The facility and Platform

The places where the facility is hooked in

  • WorkbenchAdvisor#eventLoopException(Throwable) - it handles all uncaught exceptions from main application loop
  • Jobs framework
  • Error log file (all logged messages are forwarded to the facility with the LOG style)
  • Exceptions from opening a part (the error view and error editor)

Platform is still under refactoring aimed at introducing the status handling facility.


WARNING! The facility isn't hooked into JFace ErrorDialog or MessageDialog in any way. The code has to be refactored if the facility is to be used.

The old code

  ErrorDialog.openError(...);

or

  MessageDialog.openError(...);

should be refactored into

  StatusManager.getManager().handle(..., StatusManager.SHOW);

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.

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.

New StatusDialog

Overview

New Status Dialog is integrated with Status Handling facility. Unless no other handler is specified, the default dialog will be used.

Main concepts

  • Message - This is the most important piece of information.
  • Details - Sometimes there is not enough place to display all necessary info on the dialog, or we do not want to scary the user. Then we can place leading message on the dialog, and all other things make accessible via details area. Currently it is possible to set up one kind of details area provider, but there is no further requirement.
  • Support - It is possible to place some contact form on the dialog, so the user will know where to look for help or will be able to easily contact vendor.

Support and Details are terms introduced to distinct the behavior and functionality although they extend common abstract class. One should remember that user expects more information after pressing "Details >>>" button.

Messages hierarchy

Status Dialog uses following messages hierarchy:

  • Job name (if available)
  • StatusAdapter title
  • IStatus message
  • MultiStatus information (applies only if MultiStatus is handled).
  • message extracted from exception
  • exception name

Status Dialog displays always two the most important messages. If first one is not found then the dialog should give information about general error instead. If the second one is not found, dialog should point to the details.

User interface

  • Only one status is handled
    • First message displayed is the most important message.
    • Second message displayed is the second most important message.
    • Timestamp is displayed in the details (if available)
  • More statuses handled - the selection list appears
    • There is the most important message used on the selection list.
    • The second most important message is displayed right to the severity icon.
    • Timestamp (if available) is appended to the message in the selection list.

Extensions

  • Details area can be replaced - it does not display stack trace anymore, rather the error hierarchy (message from Status, Exception, Nested statuses, etc) by default. Product may decide to provide some high level description, or even retrieve description from database.
  • Support area can be added - product may hook into the error dialog and place there f.e. browser with url pointing to the helpdesk, or some reporting mechanism.

The basic idea is that even unexperienced user should be able to understand what is going on while looking at details, and should be able to report/get help using support area.

Examples:

  • Only one status is reported. Primary message and secondary message should be displayed. Secondary message should have timestamp if one is available.

Singlestatus2.jpg

  • Job reported an error. Display message informing which job, and primary message.

Singlejob2.jpg


  • Multiple errors occured. On the list should be displayed job name or primary message of the status. In the title primary message should appear for jobs and secondary for statuses.

Manystatuses.jpg

  • One stastus has been reported and support is available.

Statusdialogwithsupport.JPG

after pressing bug icon:

Statusdialogwithsupportopened.JPG

and many statuses. The selected in the list Status is a base for support area.

Manystatuseswithsupportopened.JPG

Use cases

To be done

Usage

Note for WorkbenchStatusDialog clients
Please note that WorkbenchStatusDialog#getPrimaryMessage & WorkbenchStatusDialog#getSecondaryMessage begin searching for the message from StatusAdapter title. It means that when we are handling job statuses we display:

  • single status
    • job name as the first message
    • WorkbenchStatusDialog#getPrimaryMessage result as second message
  • list
    • job name (and eventually timestamp) as the position on the list.
    • WorkbenchStatusDialog#getPrimaryMessage result right to the severity icon.

Bugs

No Task Assigne Status Bug id
1. Create new StatusDialog exteds TrayDialog krzysztof.michalski@pl.ibm.com done 193612
2. Merge old StatusDialog and StatusNotificatonsManager functionality krzysztof.michalski@pl.ibm.com done
3. Add possibility of set label provider on StatusListView krzysztof.michalski@pl.ibm.com done
4. Add slection change Listener on StatusListView which recreate reportingView krzysztof.michalski@pl.ibm.com done
5. Create ReportingTray extends DialogTray krzysztof.michalski@pl.ibm.com done
6. Create InternalDialog to manage modal of window krzysztof.michalski@pl.ibm.com done
7. Add possibility of create reporting view: by method createReportingView, setStatusAdapter krzysztof.michalski@pl.ibm.com in progress
8. Creating reporting view by Policy krzysztof_daniel@pl.ibm.com done 180300
9. Explanation and Action in IStatus krzysztof_daniel@pl.ibm.com done 179373
10. User decides if open support area krzysztof.michalski@pl.ibm.com done 179375

Work plan for 3.4.1 & 3.5

No Task When Assigne Status Bug id
1. Update this document to reflect real Status Handling capabilities 3.4.1 krzysztof_daniel@pl.ibm.com in progress
2. Incorporate ErrorDialog into status handling 3.5 krzysztof_daniel@pl.ibm.com

Back to the top