Status handling

Status handling is a facility that allows to introduce a custom way of showing problems in the Eclipse based applications to users. The facility can be configured at both the application and the product level.

Status handlers

The handlers are responsible for presenting problems 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 contributing handlers to the Workbench:

  1. using the org.eclipse.ui.statusHandlers extension point, see User assistance and status handling
  2. using the workbench advisor and its method WorkbenchAdvisor#getWorkbenchErrorHandler()

NOTE! if there exists a handler associated with the product, it is used instead of the one defined in the advisor.

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

Logging with the use of the default logging mechanism

In order to log extra information with the use of the default logging mechanism, it is necessary to perform some additional steps. The status manager provides you with an API that allows you to hook into the mechanism.

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

The default status handler

The platform supplies its own status handler implementation org.eclipse.ui.statushandlers.WorkbenchErrorHandler. It respects all acceptable styles. It uses the default logging mechanism and a dialog based on the JFace org.eclipse.jface.dialogs.ErrorDialog.

Registering the ErrorSupportProvider with your status handler

There is a simple way to contribute a support area in the JFace ErrorDialog. It is the ErrorSupportProvider which can be set in the JFace policy. Because the default workbench handler uses a subclass of the ErrorDialog for its dialog, setting the provider on the JFace policy will affect this dialog as well.

When a handler like the one below is created

   public class CustomStatusHandler extends WorkbenchErrorHandler {
      public CompanyStatusHandler() {
         ErrorSupportProvider provider = createSupportProvider();
         Policy.setErrorSupportProvider(provider);
      }
	
      private ErrorSupportProvider createSupportProvider() {
         ...
      }
   }

and is contributed to the Workbench in one of two available ways, all dialogs based on the ErrorDialog including the one shown by the default handler, will have an extra support area.

Status manager

The status manager is the entry point for all statuses that are to be displayed in the user interface. Handlers are not intended to be used directly. They should be referenced via the StatusManager which selects the appropriate handler to apply. 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 parameters are used for supplying styles for handling. See Acceptable styles.

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

If a handler is associated with a product, it is used instead of the one that was defined in advisor. However because product handler is lazy initialized, an error can occur during the first attempt to access it. If any creation error occurs in the product handler, the workbench handler will process this error.

Acceptable styles

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

  1. 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
  2. LOG - a style indicating that the status should be logged only
  3. SHOW - a style indicating that handlers should show a problem to a user without blocking the calling method while awaiting user response. This is generally done using a non modal dialog
  4. 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

StatusAdapter

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

Each handler should specify what properties or types it accepts, being aware of the fact that developers can pass status adapters with such extra information.