com.javaranch.common
Class ErrorLog

java.lang.Object
  |
  +--com.javaranch.common.ErrorLog

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

TestLog

public class ErrorLog

extends java.lang.Object

implements java.io.Serializable

ErrorLog is a simple way of handling warnings and errors in your programs.

Rather than having 20 lines of error handling for each occurance of an error, you can have just one. When the time comes to handle your errors a different way, you don't have to find a thousand error locations and rewrite the handling: just change the ErrorLog initialization.

To use ErrorLog, create a log instance:

    ErrorLog log = new ErrorLog();
    

and then when the error occurs:

    log.add( "file " + fileName + " corrupted at byte " + pos );
    

The time and date will be added to your message and written to System.err.

FILE LOGGING
To activate this feature, use the setLogFile() method. To deactivate this feature, or to complete file logging, use the setLogFileOff() method. When activated, all error messages will be copied to a text file (using the name provided in setLogFile()). By default, this feature is off.

Example:

    ErrorLog log = new ErrorLog();
    log.setLogFile( "errors.txt" ); // turn on text file logging

    ...

    log.add( "file " + fileName + " corrupted at byte " + pos );
    // this error message is sent to the console and copied to the file "errors.txt"

    ...

    // end of the program
    log.setLogFileOff();
    

Note that a "file flush" is performed after each error message is processed. This is in case your program is prematurely terminated: the file will still contain all of the messages you sent (instead of having them in a buffer in memory waiting for the file to be closed).

Note also that setLogFileOff() does not have to be called when your program finishes, although it is good programming practice. In other words, you will not lose any data from your file if you do not call setLogFileOff().

INTERNAL LOGGING
To activate/deactivate this feature, use the setInternalLog() method. When activated, all error messages will be stored inside the ErrorLog object. By default, this feature is off.

Example:

    ErrorLog log = new ErrorLog();
    log.setInternalLog( true ); // turn on internal logging

    ...

    log.add( "file " + fileName + " corrupted at byte " + pos );
    // this error message is stored in Errors and copied to the console

    ...

    //When you are ready to extract the log:

    String[] errors = log.getList();
    

DIALOG DISPLAY
If your program is a GUI application or applet, you may want to notify your user of an error as you add it to the log. Do this by using the addAndDisplay() method. It works exactly the same as the add() method except it also copies the message into a Dialog which it creates.

Example:

    ErrorLog log = new ErrorLog();

    ...

    log.addAndDisplay( myPanel , "file " + fileName + " corrupted" );
    // this error message is written to the console and instantly
    // appears in a Dialog
    

If you have different levels of severity you wish to keep track of, you can create different ErrorLog objects:

    ErrorLog errors      = new ErrorLog();
    ErrorLog warnings    = new ErrorLog();
    ErrorLog suggestions = new ErrorLog();

    ...

    errors.add( "file " + fileName + " corrupted at byte " + pos );

    ...

    warnings.add( "employee " + empName + " found twice - could be a duplicate" );

    ...


    if ( password.length() < 5 )
    {
    

    suggestions.add( "short passwords are not very secure" );
    
    }
    

- - - - - - - - - - - - - - - - -

Copyright (c) 1998-2004 Paul Wheaton

You are welcome to do whatever you want to with this source file provided that you maintain this comment fragment (between the dashed lines). Modify it, change the package name, change the class name ... personal or business use ... sell it, share it ... add a copyright for the portions you add ...

My goal in giving this away and maintaining the copyright is to hopefully direct developers back to JavaRanch.

The original source can be found at JavaRanch

- - - - - - - - - - - - - - - - -

Author:

Paul Wheaton

See Also:

Serialized Form

Constructor Summary

ErrorLog()
Create an ErrorLog object where errors are sent to System.err

ErrorLog(java.lang.String fileName)
Create an ErrorLog object where errors are sent to a text file.

Method Summary

void	add(java.lang.String message) Add an error message to the ErrorLog object.
void	addAndDisplay(java.awt.Component c, java.lang.String message) Add an error message to the ErrorLog object and display that mesage to the user in a Dialog.
void	appendLogFile(java.lang.String fileName) Tell the ErrorLog object that all future error messages are to be copied to a text file.
java.lang.String[]	getList() Get a list of all error messages that have been passed in to the ErrorLog object.
boolean	isConsoleLogOn() Test to see if this ErrorLog object currently copies error messages to the console.
boolean	isFileLogOn() Test to see if this ErrorLog object currently copies error messages to a text file.
boolean	isInternalLogOn() Test to see if this ErrorLog object currently copies error messages to an internal buffer.
int	numErrors() Get the number of errors that this object has encountered.
void	setConsole(boolean on) Tell the ErrorLog object to start/stop copying error messages to the console.
void	setInternalLog(boolean on) Tell the ErrorLog object to start/stop copying error messages to an internal buffer.
void	setLogFile(java.lang.String fileName) Tell the ErrorLog object that all future error messages are to be copied to a text file.
void	setLogFileOff() Tell the ErrorLog object that no further errors are to be copied to a text file.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ErrorLog

public ErrorLog()

Create an ErrorLog object where errors are sent to System.err

ErrorLog

public ErrorLog(java.lang.String fileName)
         throws java.io.IOException

Create an ErrorLog object where errors are sent to a text file.

If the text file already exists, it will first be deleted. If the text file does not already exist, it will be created.

This constructor defaults to console logging off. If you want both console logging and file logging, call this constructor and then call setConsole( true );

Parameters:

fileName - The name of the file that will be created and store future error messages.

Throws:

java.io.IOException - thrown for any IO errors encountered while creating the file.

Method Detail

setLogFile

public void setLogFile(java.lang.String fileName)
                throws java.io.IOException

Tell the ErrorLog object that all future error messages are to be copied to a text file.

If the text file already exists, it will first be deleted. If the text file does not already exist, it will be created.

Parameters:

fileName - The name of the file that will be created and store future error messages.

Throws:

java.io.IOException - thrown for any IO errors encountered while creating the file.

appendLogFile

public void appendLogFile(java.lang.String fileName)
                   throws java.io.IOException

Tell the ErrorLog object that all future error messages are to be copied to a text file.

If the text file already exists, new messages will be appended to the end. If the text file does not already exist, it will be created.

Parameters:

fileName - The name of the file that will store future error messages.

Throws:

java.io.IOException - thrown for any IO errors encountered while creating/opening the file.

setLogFileOff

public void setLogFileOff()

Tell the ErrorLog object that no further errors are to be copied to a text file.

This method also properly closes the log file.

isFileLogOn

public boolean isFileLogOn()

Test to see if this ErrorLog object currently copies error messages to a text file.

Returns:

true if all messages are copied to a text file.
false if no messages are copied to a text file.

setConsole

public void setConsole(boolean on)

Tell the ErrorLog object to start/stop copying error messages to the console.

Parameters:

on - true: start sending messages to the console. false: stop sending messages to the console.

isConsoleLogOn

public boolean isConsoleLogOn()

Test to see if this ErrorLog object currently copies error messages to the console.

Returns:

true if all messages are copied to the console.
false if no messages are copied to the console.

add

public void add(java.lang.String message)

Add an error message to the ErrorLog object.

"message" has a time/date stamp added to it.

If internal logging is on, the message is appended to the internal collection of error messages.

If console logging is on, the message is copied to the console.

If file logging is on, the message is copied to the log file.

Parameters:

message - this can be any text you want.

addAndDisplay

public void addAndDisplay(java.awt.Component c,
                          java.lang.String message)

Add an error message to the ErrorLog object and display that mesage to the user in a Dialog.

"message" has a time/date stamp added to it.

A diolog box is created and the message is displayed in that dialog.

If internal logging is on, the message is appended to the internal collection of error messages.

If console logging is on, the message is copied to the console.

If file logging is on, the message is copied to the log file.

Parameters:

c - any AWT or JFC component. It will be used to find an AWT Frame which is required for all Dialogs.

message - this can be any text you want.

numErrors

public int numErrors()

Get the number of errors that this object has encountered.

Returns:

the number of error that this object has encountered.

getList

public java.lang.String[] getList()

Get a list of all error messages that have been passed in to the ErrorLog object.

Returns:

an array of strings which represent the error messages that were passed to the ErrorLog object. Each message includes a date and time stamp. If errors are not currently stored in this object, null is returned.

setInternalLog

public void setInternalLog(boolean on)

Tell the ErrorLog object to start/stop copying error messages to an internal buffer.

Parameters:

on - true start copying messages to the internal buffer. false stop copying messages to the internal buffer.

isInternalLogOn

public boolean isInternalLogOn()

Test to see if this ErrorLog object currently copies error messages to an internal buffer.

Returns:

true if all messages are copied to the internal buffer.
false if no messages are copied to the internal buffer.