Status Handling Best Practices

This is Status Handling Best Practices page.

Draft Table of contents

Rationale for a Status Handling (possibly link to UI best practices)

  * discuss the need of 'showing and logging' and express the different logging level
  * discuss the different API for logging
  * discuss the different api for showing (ErrorDialog, MessageDialog, StatusDialog ?, Job Dialog ?)

Discussion about IStatus best practices (does it carry a payload?)

  * Subclassing and IStatus

Introduction

In software engineering and hardware engineering, serviceability is also known as supportability, and is one of the -ilities or aspects. It refers to the ability of technical support personnel to debug or perform root cause analysis in pursuit of solving a problem with a product. [ http://en.wikipedia.org/wiki/Serviceability]

One of the feature of Serviceability includes the logging of state and the notification of the user.

Eclipse already provides different framework to manage the Log file as well as Dialog to notify the user. In Eclipse 3.3 we introduce a framework that will make the logging and Dialog consistent across the Eclipse platform. This new framework also allows provider to plug-in their diagnosis tools, providing extra value to the user.

This paper will explain the best practices a developer should follow to exploit this new framework appropriately using the IStatus class. The second part will explain to plugin provider how to exploit the new ‘StatusHandler’ model, allowing them to contribute to the user interface as well as manaing the IStatus we are about to show or log.

Before we investigate IStatus, we need to agree on a couple basic principle about logging and error message rendering.

Eclipse UI best practices about Common Error Message [ http://wiki.eclipse.org/index.php/UI_Best_Practices_v3.x#Common_Error_Messages]

Messages

A message is the principal information the user will see in the log or in the User Interface. A message that is logged is supposed to be user consumable and thus follow the same readability and globalization rules as a String rendered in a menu.

Message content

There is tons of information on how to create a usable message. We rely on your Software Engineering experience to void messages like: ‘internal error, please see log’.

Provide additional information in your message

We recommend you provide two other pieces of information when you create a message.

1. An explanation to the message. This is also a String that will provide more information to the user than a one liner message. The explanation should not be too technical, yet provide more value than the message text itself. Once again, there is information available on the web.
2. A recommendation of the message. This is a String that will tell the user what he/she should do. When you write this part, put yourself in the shows of the user and answer the following question: “ok, now what do I do ?”

Attempt to use a unique identifier

Unique identifier could be an int or a String that uniquely tag the message. There are two main reasons why you want to add a unique identifier to your message.

1. It is easier to search a knowledge base with a unique int than the full text of the message.
2. Because messages are translated, a user in a foreign country may send your support team a translated message. If you do not have a unique identifier, it will be difficult for your team to translate it back into the original language.

Developing messages in eclipse: using NLS. Bind

Eclipse provides a great mechanism to manage your messages from within your Java code. Look at the NLS class

Developing Message Bundles in Eclipse [ http://help.eclipse.org/help32/index.jsp?topic=/org.eclipse.platform.doc.isv/reference/misc/message_bundles.html]

Internationalization best practices [ http://www-128.ibm.com/developerworks/opensource/library/os-i18n/] [ http://icu-project.org/]

Event Record

While a message is important, we need to realize it can occurs in many situation. I do not mean by that you should reuse a message in different places in your code..(it is a big no-no). I mean this message will occur on a certain machine at a certain time. This is what we call the ‘metadata’ around the message. This encompasses things like the timestamp, the thread identifier, the ip of the machine etc etc…

Example of such record are found in java.logging.logging.LogRecord from the JSR specification. Other logger like Apache Log4J currently use an Object as a record.

Eclipse does not provide the concept of a record in itself yet. So we usually end up writing our own method like debug(String) or warn(String) in our plugins. The equinox team is working on proving a full fledge logging framework, including the concept of a LogRecord in future releases. NotaBene: The previous sentence is pure speculation as the team is currently investigating…

Using IStatus

As we saw, Eclipse does not have the concept of a LogRecord as per say, but has the concept of an ‘outcome of an operation’. The class org.eclipse.core.runtime.IStatus represents the outcome. Most of the framework related to Logging and Error rendering uses an IStatus:

   * ILog.log(IStatus status)
   * IProgressMonitorWithBlocking.setBlocked(IStatus reason)
   * ErrorDialog.openError(Shell parent, String dialogTitle, String message, IStatus status)

Create your Statuses

You should consider the following when creating an IStatus instance.

1. Try to create a subclass of IStatus that will carry your specific payload. An Example in Eclipse 3.3 is the class CVSStatus. The class carries information that diagnostic tool can use to validate CVS.
2. Do not use IStatus.ERROR as a code. Try to use your own code. As an example, look at the Class CVSSTatus.

Using StatusManager

calling StatusManager

public void run(IAction action) {
 // Throw an error to be handled
 File aConfigurationFile = obtainConfigurationFileFor(authenticatedUser);
 FileInputStream aStream = null;
 try {
   aStream = new FileInputStream(aConfigurationFile);
  //... if no error, then continue
 } catch (IOException exception){
   String message = NLS.bind(Error_Accessing_Configuration, aConfigurationFile);
   IStatus status = new CompanyStatus(IStatus.ERROR,Activator.PLUGIN_ID,CompanyStatus.CONFIGURATION_ERROR,
                                       message,exception, aConfigurationFile);
   StatusManager.getManager().handle(status, StatusManager.LOG|StatusManager.SHOW);
 } finally {
   if (aStream!=null){
    try {aStream.close();} catch (Exception e){};
   }
 } 
}

Developing StatusHandlers

The Handle(Istatus) the core

public void handle(StatusAdapter statusAdapter, int style) {

 // Retrieve IStatus and message
 IStatus oldStatus = statusAdapter.getStatus();		
 
 // Verify we do not have a CompanyStatusWithID
 if (!(oldStatus instanceof CompanyStatusWithID)){
  String message = oldStatus.getMessage();

  //All our ID start with DYNA
  if (null!=message && message.startsWith("DYNA")){		
 
   //Remove any unique identifier to not show it to the user
   int lengthOfUniqueId = message.indexOf(' ');
   
   String uniqueID = message.substring(0,lengthOfUniqueId);			
   message = message.substring(lengthOfUniqueId);
   message = message + getExplanation(oldStatus);	// Retrieve the explanation for this status
   
   // Create a new CompanyStatusWithID
   IStatus newStatus = new CompanyStatusWithID(oldStatus.getPlugin(),oldStatus.getCode(), new IStatus[]{oldStatus}, uniqueID, message,null);
   statusAdapter.setStatus(newStatus);
  }
 }
 
 // check the Style. We still want to trace even if we do not log
 if ((style & StatusManager.LOG)==0){
  trace(statusAdapter);
 }

 super.handle(statusAdapter, style);
}

The UI part

public Control createSupportArea(Composite parent, IStatus status) {
 parent.addDisposeListener(this); // get notified so we can clean our SWT widgets
 
 // if the dialog is too short, make it taller
 ensureMinimumHeight(parent.getShell());
 
 toolkit = new FormToolkit(parent.getDisplay());
 toolkit.getHyperlinkGroup().setHyperlinkUnderlineMode(HyperlinkGroup.UNDERLINE_HOVER);
 toolkit.getColors().initializeSectionToolBarColors();
 ...
}