Eclipse logging for Lotus Notes and Domino

The following is tip #6 from "Developing Eclipse plug-ins for Lotus Notes and Domino -- 7 tips in 7 minutes," excerpted from Chapter 3 of the book Eclipse: Building Commercial Quality Plug-ins, published by Addison-Wesley Publishing.

The RFRS requirements indicate that exceptions and other service-related information should be appended to a log file. To facilitate this, the plug-in class provides a method for accessing the plug-in logging mechanism via the getLog() method. For convenience, the FavoritesLog wraps the ILog interface returned by the getLog() method with several utility methods:

package com.qualityeclipse.favorites;

import org.eclipse.core.runtime.IStatus;
import org.eclipse.core.runtime.Status;

public class FavoritesLog {

The first group of methods that follow are for convenience, appending information, error messages, and exceptions to the log for the Favorites plugin.

public static void logInfo(String message) {
   log(IStatus.INFO, IStatus.OK, message, null);
}

public static void logError
(Throwable exception) {
   logError("Unexpected Exception", exception);
}

public static void logError
(String message, Throwable exception) {
   log(IStatus.ERROR, 
IStatus.OK, message, exception);
}

Each of the preceding methods ultimately calls the following methods which create a status object (Status objects) and then append that status object to the log.

public static void log(int severity, 
int code, String message,
      Throwable exception) {
   log(createStatus
(severity, code, message, exception));
}

public static IStatus createStatus
(int severity, int code,
String message, Throwable exception) {
return new Status
(severity, FavoritesPlugin.ID, code,
         message, exception);
}

public static void log(IStatus status) {
   FavoritesPlugin.getDefault().
getLog().log(status);
}

The log() and createStatus() methods take the following parameters:

• severity - the severity; one of these:

IStatus.OK, IStatus.WARNING, IStatus.ERROR, 
IStatus.INFO, or IStatus.CANCEL

• code - the plug-in-specific status code or IStatus.OK
• message - a human-readable message, localized to the current locale
• exception - a low-level exception, or null if not applicable

Status objects

The IStatus type hierarchy in the org.eclipse.core.runtime package provides a mechanism for wrapping, forwarding, and logging the result of an operation, including an exception if there is one. A single error is represented using an instance of Status (see method createStatus in the previous source code), while a MultiStatus object that contains zero or more child status objects represents multiple errors.

When creating a framework plug-in that will be used by many other plug-ins, it is helpful to create status subtypes similar to IResourceStatus and ResourceStatus; however, for the Favorites plug-in, the existing status types that follow will do:

• IStatus - A status object that represents the outcome of an operation. All CoreExceptions carry a status object to indicate what went wrong. Status objects are also returned by methods needing to provide details of failures (e.g., validation methods).
• IJavaModelStatus - Represents the outcome of a Java model operation. Status objects are used inside JavaModelException objects to indicate what went wrong.
• IResourceStatus - Represents a status related to resources in the Resources plug-in and defines the relevant status code constants. Status objects created by the Resources plug-in bear its unique identifier, ResourcesPlugin.PI_RESOURCES, and one of these status codes.
• MultiStatus - A concrete multistatus implementation, suitable either for instantiating or subclassing.
• OperationStatus - Describes the status of a request to execute, undo, or redo an operation.
• Status - A concrete status implementation, suitable either for instantiating or subclassing.
• TeamStatus - Returned from some Team operations or is the payload of some exceptions of type TeamException.

The Error Log view

The PDE provides an Error Log view for inspecting the Eclipse log file. To open the Error Log view, select Window -> Show View -> Other…, and in the Show View dialog, expand the PDE Runtime category to find the Error Log view (The Error Log view is provided by the Eclipse platform and displays in). Double-clicking on an entry opens a dialog showing details for the error log entry. If Eclipse is installed in C:\Eclipse and the default workspace location is being used, you can find the Eclipse log file at C:\Eclipse\workspace\.metadata\.log.

Figure 7: The Error Log view is provided by the Eclipse platform and displays information and exceptions generated while Eclipse is running.

Developing Eclipse plug-ins for Lotus Notes and Domino

 Home: Introduction
 Tip 1: The Eclipse plug-in structure for Lotus Notes and Domino
 Tip 2: The Eclipse plug-in directory for Lotus Notes and Domino
 Tip 3: The Eclipse plug-in manifest for Lotus Notes and Domino
 Tip 4: The Eclipse plug-in class for Lotus Notes and Domino
 Tip 5: The Eclipse plug-in model for Lotus Notes and Domino
 Tip 6: Eclipse logging for Lotus Notes and Domino
 Tip 7: Eclipse plug-in types for Lotus Notes and Domino