Serviceability - Example

In Chapter 28, Serviceability, you learned how to take advantage of the service features in Eclipse to inform the user of a problem, and if appropriate, log diagnosis information. The features demonstrated in this example include sending trace messages to the console, error dialogs and logging support. Below are those service items that you'll see demonstrated in the example project com.ibm.jdg2e.serviceability.

Error Dialog

Error Log

Tracing

Running the Example

To run this example, you must configure the run-time instance with trace enabled using a launch configuration. First select the Run > Run... menu choice; in the launch configuration dialog, select Eclipse Application and then New. In the Name field, enter Trace_configuration. Select Enable tracing for the selected plug-ins and the com.ibm.jdg2e.serviceability options on the Tracing page as shown below.
To start the run-time instance, press Run.
To produce the errors shown in the Error Dialog and Error Log, select the JDG2E > Error Dialog and Logging menu choice. This action will display a dialog as shown above. This is an example of a correctly constructed error message. Note the information when the dialog is expanded by the Details>> button.
Select Window > Show View > Error Log to view the plug-in error log.
To produce trace statements, select the JDG2E > Trace This menu choice. To see the trace messages, refer to the Console view in the host (development) instance of the Workbench.

Roadmap of the Example

Let's explore the steps involved in creating this example.

Adding Error Dialog and Error Log Support

The Workbench provides a mechanism for writing to the Error Log. The API to access the error log is Plugin.getLog(). To write to the log, use the method log(IStatus). See the ErrorDialogAction.run(IAction) method for an example of writing to the Error Log.
To use Error dialogs to display a simple error message along with details button, open an error dialog specifying a MultiStatus object which contains children. Child Status objects are used to populate the details section of the dialog. See the ServiceablePlugin.getServiceInfo() method for an example of creating the MultiStatus and Status objects.

Adding Tracing Support

The Workbench provides a mechanism for controlling the generation of tracing information of your plug-in at runtime with or without a launch configuration. The flags that plug-ins can query to determine the desired tracing information are defined in files named .options. The contents of the .options file also determines the choices that are shown for your plug-in in the Tracing page of a launch configuration. This file has the following syntax:

<plug-in-id>/debug = true|false (master switch)
<plug-in-id>/<tracing flag> = <value>

The first entry represents the master switch for tracing your plug-in. The method isDebugging() of your plug-in class will return the value of this variable. You can define other tracing flags and retrieve their value using Platform.getDebugOption(optionName). Most of the Workbench plug-ins define tracing flags, particularly the Platform Core. For a new plug-in developer, one interesting set of tracing flags are the org.eclipse.osgi options related to class loading for diagnosing plug-in loading problems.

The key classes of the example are shown in the table below.

Class (All)	Description
`ErrorDialogAction`	Triggers the error dialog and writes to the Error Log
`TraceAction`	Triggers the evaluation of the trace flags and writes to the system console
`ServiceablePlugin`	Plug-in singleton with helper methods to collect global plug-in diagnostics
`ServiceException`	Subclass of `CoreException` class