com.cleancode.log
Class LogWriter

java.lang.Object
  com.cleancode.log.LogWriter

public class LogWriter
extends Object

Provides very basic data logging facilities.

                import ...Tracking.Log;

                // Log objects fully specified
                errlog = new Log("logDir", "errlog", true, false);
                diaglog = new Log("logDir/diaglog", false, true);
                // a Log object with defaults
                log = new Log("logDir/mylog");

                // scalar and list versions of write method
                log.write("message");
                log.write(String[] {"field1","field2","field3"});

                diaglog.flush();
                errlog.close();
 

Each message logged defines a series of fields and are written as a record to a text file. Records are separated by the system-dependent line terminator. Fields are separated by the value specified in the LOG_FIELD_SEPARATOR property. The first few fields of every record are added automatically. These are the date, the time, and optionally, the thread which is logging the message.

There are several modes for a Log object, controlled by parameters to the constructor.
The autoFlush parameter is a boolean switch. Turned on, every write call will flush immediately to the file. Turned off, no flushing will be done. You may at any time invoke the flush method to do it manually, or wait until program termination. The immediate-flush may be desirable, for instance, when attempting to diagnose a problem where the program is long-running and/or log messages occur infrequently.
The verbose parameter is also a boolean switch. Turned on, a standard phrase (the value of the LOG_START_TEXT property) is written to the log file when a LogWriter object is created. Similarly, at the termination of the program (when close is called) the value of the LOG_END_TEXT property is written. These phrases serves to demarcate session boundaries for ease in reviewing the log file. The absence of the LOG_END_TEXT marker, for instance, might indicate abnormal program termination. Turned off, the demarcation phrases are not written to the log file. Additionally, the log file is not even created until the first write is invoked. Thus, for an error log, for example, if no errors occur during a program invocation, the log file will not be created (or not updated if one already exists).

Each time a program is invoked, the log file will be appended to. There is currently no facility for length-limiting the file, so it must be archived per your system requirements from time to time.

InputOptions properties used by this class

InputOptions properties used by this class
Property	Type	Default	Specifies...
LOG_FILE_EXT	String	.log	Extension for log file name.
LOG_FIELD_SEPARATOR	String	| (a vertical bar)	Field separator in each record of the log file.
LOG_START_TEXT	String	=== Starting log session ===	Initial text written when LogWriter object is created.
LOG_END_TEXT	String	=== Ending log session ===	Final text written when LogWriter object is created.
LOG_DATE_FMT	String	yyyy-MM-dd	Format string (per SimpleDateFormat) for date field of each log record.
LOG_TIME_FMT	String	HH:mm:ss	Format string (per SimpleDateFormat) for time field of each log record.
SHOW_THREAD	boolean	true	Show or hide thread name with each message.

Since:

CleanCode 0.9

Version:

$Revision: 380 $

Author:

Michael Sorens

Nested Class Summary

static class

LogWriter.Test A standalone test class to exercise the LogWriter class.

Field Summary

static int	DEFAULT_DATA_COLUMN The default column index for the actual data.
static String	DEFAULT_LOG_FIELD_SEPARATOR Default log file field separator.
static String	DEFAULT_LOG_FILE_EXT Default log file extension.
static String	DEFAULT_NON_CONFLICTING_STRING In case text to store in log contains field separator, change to this character.
static String	VERSION Current version of this class.

Constructor Summary

LogWriter(PrintWriter printWriter)
Creates a LogWriter object from the specified PrintWriter with verbose mode active.

LogWriter(PrintWriter printWriter, boolean verbose)
Creates a LogWriter object from the specified PrintWriter.

LogWriter(String logName)
Creates a LogWriter object; verbose mode is active and auto-flushing disabled.

LogWriter(String logName, boolean autoFlush, boolean verbose)
Creates a LogWriter object, verifies the log directory exists (or creates it if needed), and initializes the log file.

LogWriter(String logName, InputOptions settings)
Creates a LogWriter object, allowing full customization via the InputOptions object.

Method Summary

void	close() Close the log stream.
void	flush() Flush the log stream.
void	write(String msg) Write a log record with a single data field.
void	write(String[] msgList) Write a log record with multiple data fields.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_LOG_FILE_EXT

public static final String DEFAULT_LOG_FILE_EXT

Default log file extension.

See Also:

Constant Field Values

DEFAULT_LOG_FIELD_SEPARATOR

public static final String DEFAULT_LOG_FIELD_SEPARATOR

Default log file field separator.

See Also:

Constant Field Values

DEFAULT_NON_CONFLICTING_STRING

public static final String DEFAULT_NON_CONFLICTING_STRING

In case text to store in log contains field separator, change to this character.

See Also:

Constant Field Values

DEFAULT_DATA_COLUMN

public static final int DEFAULT_DATA_COLUMN

The default column index for the actual data. Prior columns are: date, time, and thread. Note that if thread is deactivated, data column will by reduced by 1.

See Also:

Constant Field Values

VERSION

public static final String VERSION

Current version of this class.

Constructor Detail

LogWriter

public LogWriter(String logName,
                 boolean autoFlush,
                 boolean verbose)
          throws IOException

Creates a LogWriter object, verifies the log directory exists (or creates it if needed), and initializes the log file. If verbose is true, the file is initialized with the value of the LOG_START_TEXT property. If this property is empty, nothing is initially written to the log file, but it is still created as an empty file. If verbose is false, the initial phrase is not written and the file creation is delayed until the first write.

Parameters:

logName - base name of log file including path but no extension

autoFlush - boolean indicating to flush after every write

verbose - boolean directing opening and closing behavior

Throws:

IOException - if there's a problem with the path or file

LogWriter

public LogWriter(String logName)
          throws IOException

Creates a LogWriter object; verbose mode is active and auto-flushing disabled.

Parameters:

logName - base name of log file including path but no extension

Throws:

IOException - if there's a problem with the path or file

See Also:

for more

LogWriter

public LogWriter(String logName,
                 InputOptions settings)
          throws IOException

Creates a LogWriter object, allowing full customization via the InputOptions object.

Parameters:

logName - base name of log file including path but no extension

settings - InputOptions object to customize the log output

Throws:

IOException - if there's a problem with the path or file

See Also:

for more

LogWriter

public LogWriter(PrintWriter printWriter,
                 boolean verbose)
          throws IOException

Creates a LogWriter object from the specified PrintWriter. As this constructor is given an existing PrintWriter, the verbose flag does not control the just-in-time file creation behavior.

Parameters:

printWriter - LogWriter object to output messages

verbose - boolean directing opening and closing behavior

Throws:

IOException - if an I/O error occurs

See Also:

for more

LogWriter

public LogWriter(PrintWriter printWriter)
          throws IOException

Creates a LogWriter object from the specified PrintWriter with verbose mode active. As this constructor is given an existing PrintWriter, the verbose flag does not control the just-in-time file creation behavior.

Parameters:

printWriter - LogWriter object to output messages

Throws:

IOException - if an I/O error occurs

See Also:

for more

Method Detail

flush

public void flush()

Flush the log stream.

close

public void close()
           throws IOException

Close the log stream.

Throws:

IOException - if an I/O error occurs

write

public void write(String msg)
           throws IOException

Write a log record with a single data field. The date, time, and optionally thread are the initial fields of the record. The single message is the final field of the record. Thus, each record will contain either 3 or 4 fields, depending on whether you have included the thread field. The DEFAULT_LOG_FIELD_SEPARATOR string separates fields in each record. (You may elect to change this field separator string via the LOG_FIELD_SEPARATOR property.) If your data contains the field separator you have chosen, it will automatically be changed to DEFAULT_NON_CONFLICTING_STRING so as to maintain the ability to properly distinguish fields of the record.

Parameters:

msg - message to output to log file

Throws:

IOException - if there's a problem writing to the file

write

public void write(String[] msgList)
           throws IOException

Write a log record with multiple data fields. The date, time, and optionally thread are the initial fields of the record. The specified list of messages follows these, all separated by the DEFAULT_LOG_FIELD_SEPARATOR string (unless you have changed it).

Parameters:

msgList - list of messages to output to log file

Throws:

IOException - if there's a problem writing to the file

See Also:

write(String)