tribble.io
Class DebugWriter

java.lang.Object
  extended by 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()