tribble.io
Interface DebugWriterI

All Superinterfaces:

SuspendableWriterI

All Known Implementing Classes:

DebugWriter

public interface DebugWriterI
extends SuspendableWriterI

Debugging (tracing) message output stream.

This interface is used to implement any kind of output stream that is capable of writing text output lines. Such a stream is used to display debugging (trace) information.

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 (e.g., a class derived from Writer or OutputStream).

This interface extends SuspendableWriterI, meaning that its output can be suspended and resumed by the controlling program.

Implementations of this interface are encouraged to provide at least one constructor that takes an output stream argument (such as a Writer or OutputStream) specifying the underlying character output stream for the debugging output stream. For example:

    class MyDebugOutput
        extends tribble.io.DebugWriterI
    {
        /** Constructor. */
        public MyDebugOutput(java.io.Writer out)
        { ... }

        ...
    } 

    PrintWriter     out;
    DebugWriterI    dbg;

    out = ...;
    dbg = new DebugWriterI(out); 

Implementations of this interface are encouraged to flush any pending character output to their underlying output streams whenever a newline is written. (See methods println() and println(java.lang.String).)

Since:

2003-02-01

Version:

$Revision: 1.1 $ $Date: 2003/02/01 17:15:34 $

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

static java.lang.String

REV Revision information.

Method Summary

DebugWriterI	print(java.lang.String msg) Writes a text message to the debugging output stream.
DebugWriterI	println() Writes a newline to the debugging output stream.
DebugWriterI	println(java.lang.String msg) Writes a text message to the debugging output stream, followed by a newline.

Methods inherited from interface tribble.io.SuspendableWriterI

close, isSuspended, resume, suspend

Field Detail

REV

static final java.lang.String REV

Revision information.

See Also:

Constant Field Values

Method Detail

print

DebugWriterI print(java.lang.String msg)

Writes a text message to the debugging output stream.

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

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:

    DebugWriterI  dbg = ...;

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

Since:

1.1, 2003-02-01

println

DebugWriterI println(java.lang.String msg)

Writes a text message to the 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.

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

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:

    DebugWriterI  dbg = ...;

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

Since:

1.1, 2003-02-01

println

DebugWriterI println()

Writes a newline to the debugging 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.

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

Returns:

This debugging output stream.

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

    DebugWriterI  dbg = ...;

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

Since:

1.1, 2003-02-01