wt.util
Class LogOutputStream

java.lang.Object
  java.io.OutputStream
      java.io.FilterOutputStream
          wt.util.LogOutputStream

All Implemented Interfaces:

Closeable, Flushable

public class LogOutputStream
extends FilterOutputStream

A filter output stream for writing log entries. Each line of output is prefixed by the current time and optional stream identifier and thread name.

This filter buffers bytes until a line is received, at which time a log entry is written to the underlying output stream. Each log entry is written to the underlying output stream using a single write operation. This is done in order to minimize the potential for interspersing writes if separate processes are appending to a common file. However, if the underlying FileOutputStream and operating system do not guarantee atomic, sequential appends, then simultaneous writes could still result in lost data.

Output to a LogOutputStream should already be translated into bytes according to a desired character encoding. The output bytes are not affected by this filter. This makes the filter an ideal target for PrintStream or PrintWriter objects which perform character-to-byte conversions before passing the data to this output stream. Each LogOutputStream incorporates its own OutputStreamWriter to translate the additional text being added by the filter. The system default file encoding is used (same as PrintStream and PrintWriter) unless explicity specified as an argument to the constructor.

Currently, this class assumes that a line is terminated by any one of a line feed ('\n'), a carriage return ('\r'), or a carriage return followed immediately by a linefeed. This is not a perfect solution. It assumes these are valid line separators and ignores the possible mapping of these characters to different byte representations or their occurance within multi-byte characters. However, most popular multi-byte character encodings (EUC, Shift-JIS, UTF-8) don't overload these control bytes so it is a fairly safe assumption. It is a compormise intended to allow newline characters in strings (such as nested exceptions) to produce multi-line log entries regardless of default line separator, and to do so in a filter that can be used with both PrintStream and PrintWriter classes.

Supported API: true

See Also:

LogFile

Field Summary

Fields inherited from class java.io.FilterOutputStream

out

Constructor Summary

LogOutputStream(OutputStream out, String name, boolean thread_names)
Construct a log output stream.

LogOutputStream(OutputStream out, String name, boolean thread_names, String enc)
Construct a log output stream using a specified character encoding.

Method Summary

static void	main(String[] argv) Simple tester.
void	write(byte[] b, int off, int len) Writes len bytes from the specified byte array starting at offset off to the log file.
void	write(int b) Write a byte of data to the log output stream.

Methods inherited from class java.io.FilterOutputStream

close, flush, write

Methods inherited from class java.lang.Object

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

Constructor Detail

LogOutputStream

public LogOutputStream(OutputStream out,
                       String name,
                       boolean thread_names)

Construct a log output stream. The default character encoding is used for log text.

Supported API: true

Parameters:

out - target byte stream

name - optional name to identify this stream (may be null)

thread_names - include thread names?

LogOutputStream

public LogOutputStream(OutputStream out,
                       String name,
                       boolean thread_names,
                       String enc)
                throws UnsupportedEncodingException

Construct a log output stream using a specified character encoding.

Supported API: true

Parameters:

out - target byte stream

name - optional name to identify this stream

thread_names - include thread names?

enc - character encoding

Throws:

UnsupportedEncodingException

Method Detail

write

public void write(int b)
           throws IOException

Write a byte of data to the log output stream. Bytes are appended to a buffer until a complete line is recieved, at which time the currently buffered bytes are written to the underlying output stream prefixed by the log information.

Supported API: true

Overrides:

write in class FilterOutputStream

Parameters:

b - the byte to be written.

Throws:

IOException

write

public void write(byte[] b,
                  int off,
                  int len)
           throws IOException

Writes len bytes from the specified byte array starting at offset off to the log file. Each byte is passed to the write byte method.

Supported API: true

Overrides:

write in class FilterOutputStream

Parameters:

b - the data.

off - the start offset in the data.

len - the number of bytes to write.

Throws:

IOException

main

public static void main(String[] argv)
                 throws IOException

Simple tester. Copies standard input to standard output through a LogOutputStream filter. System properties called name and thread_names can be used to specify the name and thread_names arguments to the constructor.

Supported API: true

Throws:

IOException