3.6. Logging

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 plug-in.

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 (see Section 3.6.1, Status objects, on page 123) 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

3.6.1. 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 (see Section 6.6.2, Commands, on page 252).

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.

3.6.2. 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 (see Figure 3-7). 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 3-7. The Error Log view is provided by the Eclipse platform and displays information and exceptions generated while Eclipse is running.

[View full size image]