Grace JavaLog

Example Code

Grace Software

JavaLog

$Revision: 1.5 $

$Date: 1999/10/28 11:17:23 $

Introduction

The programmer interfaces to the Log Facility using the grace.log.Log class. This section describes how to use this class and gives examples of common uses for each function. The Log Facility handles four predefined event types as well as any user defined event type. Events are described in more detail here. Briefly, the four predefined event types are:

Error - indicates an exception or situation that will corrupt or has already corrupted the running program.
Warning - indicates a situation that will not affect the operability of the program but could potentially affect the programs operation.
Notice - used to simple log informational messages and data. Notices typically indicate a program's state.
Trace - used to log the program's current position. Note, the difference between a notice and a trace is that tracing is turned off in the normal operation of a program. Therefore tracing is intended to be used for debugging by the programmer whereas notices are intended to be used by users of the program.
User Defined - used to log events of any type defined by the user.

Errors (and Exceptions)

There are four error handling functions:

public static void error(Exception);
public static void error(String message);
public static void error(String message, Object userData);
public static void error(String message, Exception);

The first of these functions is the most useful for handling exceptions. It can be used as follows:

    try {
        ... code that throws an exception ...
    }
    catch (Exception e) {
        grace.log.Log.error(e);
    }

The second of these functions can be used if an error has occurred but there is no exception to accompany it:

    if (can_not_open_file) {
        grace.log.Log.error("can't open file");
    }

The third function is useful also where there is no exception to accompany the error but it allows the caller to log an object in the log:

    if (!object.isValid()) {
        grace.log.Log.error("invalid object state", object);
    }

Warnings

public static void warning(String message);
public static void warning(String message, Object userData);
public static void warning(String message, Exception);

These functions are identical to their "error" counterparts other than the fact that they log a warning instead of an error.

Notices

public static void notice(String message);
public static void notice(String message, Object userData);

These functions allow the user to log information. They allows the programmer to write a simple message or a message and a user object. These messages should always be intended to be read by the user of the program (i.e. not just the programmer).

    grace.log.Log.notice("program is operational");

Traces

public static void trace();
public static void trace(String message);
public static void trace(Object userData);
public static void trace(String message, Object userData);

Tracing is intended as a debugging tool for the programmer. Log output is normally disabled in the normal operation of the program. The following example simply logs the entry and exit from a function called "cancel".

    public void cancel(Flight flight) {
        grace.log.Log.trace("begin", flight);
        ...
        grace.log.Log.trace("end");
    }

User Defined Event Types

public static void log(String eventType, String message);
public static void log(String eventType, Object userData);
public static void log(String eventType, String message, Object userData);

The above three functions allow the programmer to log events that are of any event type. In these functions, the eventType is passed as a user defined string. Using the event types "Error", "Warning", "Notice", or "Trace" is equivalent to calling the Log.error(), Log.warning(), Log.notice(), or Log.trace() function, respectively.

    double transactionRate;
    ...
    grace.log.Log.log("statistics", "transaction-rate=" + transactionRate);

Note, in the above code, the transactionRate double variable is appended to the "transaction-rate=" string instead of passing it as userData. This is because the Log interfaces do not accept primitive types currently. This may be an addition in the future.