tribble.io
Class DebugWriter

java.lang.Object
  tribble.io.DebugWriter

All Implemented Interfaces:

DebugWriterI, SuspendableWriterI

public class DebugWriter
extends java.lang.Object
implements DebugWriterI, SuspendableWriterI

Debugging (tracing) message output stream.

Provides an output stream suitable for writing debug or trace text messages to.

A debugging output stream is used to provide debugging trace information, which is typically needed during program development to identify bugs. Such a stream is capable of printing text string messages. The underlying output stream is some kind of output stream derived from java.io.Writer or @link java.io.OutputStream.

This debugging output stream implements SuspendableWriterI, which means that its output can be selectively suspended and resumed (i.e., turned off and on).

Since:

2003-02-25

Version:

$Revision: 1.1 $ $Date: 2003/02/25 20:27:23 $

Author:

David R. Tribble, david@tribble.com.
Copyright ©2003 by David R. Tribble all rights reserved.
Permission is granted to freely use and distribute this source code provided that the original copyright and authorship notices remain intact.

Field Summary

protected java.io.Writer	m_out Underlying output stream.
protected java.io.Writer	m_sus Saved (suspended) output stream.
protected static java.lang.String	NEWLINE Native operating system newline character sequence.
(package private) static java.lang.String	REV Revision information.

Constructor Summary

DebugWriter(java.io.OutputStream out)
Constructor.

DebugWriter(java.io.Writer out)
Constructor.

Method Summary

void	close() Close this debugging output stream.
boolean	isSuspended() Determine if this debugging output stream is suspended or not.
DebugWriterI	print(java.lang.String msg) Write a text message to this debugging output stream.
DebugWriterI	println() Write a newline to this debugging output stream.
DebugWriterI	println(java.lang.String msg) Write a text message to this debugging output stream, followed by a newline.
void	resume() Resume subsequent output written to this debugging output stream.
void	suspend() Suspend subsequent output written to this debugging output stream.

Methods inherited from class java.lang.Object

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

Field Detail

REV

static final java.lang.String REV

Revision information.

See Also:

Constant Field Values

NEWLINE

protected static final java.lang.String NEWLINE

Native operating system newline character sequence.

m_out

protected java.io.Writer m_out

Underlying output stream.

m_sus

protected java.io.Writer m_sus

Saved (suspended) output stream.

Constructor Detail

DebugWriter

public DebugWriter(java.io.Writer out)

Constructor.

Parameters:

out - The underlying output stream for this debugging output stream.

Since:

1.1, 2003-02-25

DebugWriter

public DebugWriter(java.io.OutputStream out)

Constructor.

Parameters:

out - The underlying output stream for this debugging output stream.

Since:

1.1, 2003-02-25

Method Detail

close

public void close()

Close this debugging output stream.

Note that this method flushes any pending output to the underlying output stream of this stream, regardless of whether or not this stream is currently suspended. The underlying output stream is then closed (by calling its close() method). (This is probably not be a wise thing to do if the underlying output stream is System.out.)

Note that this method does not throw any checked exceptions (such as java.io.IOException).

Specified by:

close in interface SuspendableWriterI

Since:

1.1, 2003-02-25

print

public DebugWriterI print(java.lang.String msg)

Write a text message to this debugging output stream.

Note that this method does not throw any checked exceptions (such as java.io.IOException).

Specified by:

print in interface DebugWriterI

Parameters:

msg - The message text. Note that the message text should not contain a terminating newline.

Returns:

This debugging output stream.

This allows several debugging calls to be chained together. For example:

    DebugWriter   dbg = ...;

    dbg.print("length=")
        .print(len+"")
        .print(", width=")
        .print(wid+"")
        .println(); 

Since:

1.1, 2003-02-01

println

public DebugWriterI println(java.lang.String msg)

Write a text message to this debugging output stream, followed by a newline.

Note that the means of writing a "newline" are dependent upon the implementation of the underlying output stream as well as the underlying operating system, and might involve something other than simply writing a single '\n' character. The exact character sequence is specified by the "line.separator" Java system property.

Note that this method does not throw any checked exceptions (such as java.io.IOException).

Specified by:

println in interface DebugWriterI

Parameters:

msg - The message text. Note that the message text should not contain a terminating newline.

Returns:

This debugging output stream.

This allows several debugging calls to be chained together. For example:

    DebugWriter   dbg = ...;

    dbg.println("Customer: ")
        .println(" name:    " + cust.name)
        .println(" addr:    " + cust.addr)
        .println(" balance: " + cust.balance); 

Since:

1.1, 2003-02-01

println

public DebugWriterI println()

Write a newline to this debugging output stream. This also flushes any pending output to the underlying output stream.

Note that the means of writing a "newline" are dependent upon the implementation of the underlying output stream as well as the underlying operating system, and might involve something other than simply writing a single '\n' character. The exact character sequence is specified by the "line.separator" Java system property.

Note that this method does not throw any checked exceptions (such as java.io.IOException).

Specified by:

println in interface DebugWriterI

Returns:

This debugging output stream.

This allows several debugging calls to be chained together. For example:

    DebugWriter   dbg = ...;

    dbg.print("x=" + x).print(", y=" + y).println(); 

Since:

1.1, 2003-02-01

suspend

public void suspend()

Suspend subsequent output written to this debugging output stream.

Subsequent calls to any of the print() or println() methods will not write any output to the underlying stream.

Output to this stream can be resumed by calling resume().

This method may be called multiple times without any intervening call to resume() without any ill effects.

Specified by:

suspend in interface SuspendableWriterI

Since:

1.1, 2002-03-25

See Also:

resume()

resume

public void resume()

Resume subsequent output written to this debugging output stream.

Subsequent calls to any of the print() or println() methods will cause output to be written to the underlying stream.

Output to this stream can be suspended by calling suspend().

This method may be called multiple times without any previous or intervening call to suspend() without any ill effects.

Specified by:

resume in interface SuspendableWriterI

Since:

1.1, 2003-02-25

See Also:

suspend()

isSuspended

public boolean isSuspended()

Determine if this debugging output stream is suspended or not.

Specified by:

isSuspended in interface SuspendableWriterI

Returns:

True if this output stream is currently suspended, otherwise false.

Since:

1.1, 2003-02-25

See Also:

suspend()