//==============================================================================
// tribble/io/DebugWriterI.java
//------------------------------------------------------------------------------

package tribble.io;


// System imports

import java.lang.String;


// Local imports

import tribble.io.SuspendableWriterI;


/*******************************************************************************
* Debugging (tracing) message output stream.
*
* <p>
* 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.
*
* <p>
* 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
* {@link java.io.Writer} or {@link java.io.OutputStream}).
*
* <p>
* This interface extends {@link tribble.io.SuspendableWriterI}, meaning that
* its output can be suspended and resumed by the controlling program.
*
* <p>
* Implementations of this interface are encouraged to provide at least one
* constructor that takes an output stream argument (such as a
* {@link java.io.Writer} or {@link java.io.OutputStream}) specifying the
* underlying character output stream for the debugging output stream.
* For example:
* <pre>
*    class MyDebugOutput
*        extends tribble.io.DebugWriterI
*    {
*        /** Constructor. &#42;/
*        public MyDebugOutput(java.io.Writer out)
*        { ... }
*
*        ...
*    } </pre>
*
* <p>
* <pre>
*    PrintWriter     out;
*    DebugWriterI    dbg;
*
*    out = ...;
*    dbg = new DebugWriterI(out); </pre>
*
* <p>
* Implementations of this interface are encouraged to flush any pending
* character output to their underlying output streams whenever a newline is
* written.
* (See methods {@link #println()} and {@link #println(java.lang.String)}.)
*
* @version	$Revision: 1.1 $ $Date: 2003/02/01 17:15:34 $
* @since	2003-02-01
* @author
*	David R. Tribble,
*	<a href="mailto:david@tribble.com">david@tribble.com</a>.
*	<br>
*	<a href="../Copyright.html">Copyright</a> ©2003 by David R. Tribble,
*	all rights reserved.
*	<br>
*	Permission is granted to freely use and distribute this source code
*	provided that the original copyright and authorship notices remain
*	intact.
*/

public interface DebugWriterI
    extends SuspendableWriterI
{
// Identification

    /** Revision information. */
    static final String		REV =
        "@(#)tribble/io/DebugWriterI.java $Revision: 1.1 $ $Date: 2003/02/01 17:15:34 $\n";


// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// Public constants

    // (None)


// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// Public methods

    /***************************************************************************
    * Writes a text message to the debugging output stream.
    *
    * <p>
    * Note that this method does not throw any checked exceptions (such as
    * {@link java.io.IOException}).
    *
    * @param	msg
    * The message text.
    * Note that the message text should not contain a terminating newline.
    *
    * @return
    * This debugging output stream.
    *
    * <p>
    * This allows several debugging calls to be chained together.
    * For example:
    * <pre>
    *    DebugWriterI  dbg = ...;
    *
    *    dbg.print("length=")
    *        .print(len)
    *        .print(", width=")
    *        .print(wid)
    *        .println(); </pre>
    *
    * @since	1.1, 2003-02-01
    */

    public DebugWriterI print(String msg);


    /***************************************************************************
    * Writes a text message to the debugging output stream, followed by a
    * newline.
    *
    * <p>
    * 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 <tt>'\n'</tt> character.
    *
    * <p>
    * Note that this method does not throw any checked exceptions (such as
    * {@link java.io.IOException}).
    *
    * @param	msg
    * The message text.
    * Note that the message text should not contain a terminating newline.
    *
    * @return
    * This debugging output stream.
    *
    * <p>
    * This allows several debugging calls to be chained together.
    * For example:
    * <pre>
    *    DebugWriterI  dbg = ...;
    *
    *    dbg.println("Customer: ")
    *        .println(" name:    " + cust.name)
    *        .println(" addr:    " + cust.addr)
    *        .println(" balance: " + cust.balance); </pre>
    *
    * @since	1.1, 2003-02-01
    */

    public DebugWriterI println(String msg);


    /***************************************************************************
    * Writes a newline to the debugging output stream.
    *
    * <p>
    * 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 <tt>'\n'</tt> character.
    *
    * <p>
    * Note that this method does not throw any checked exceptions (such as
    * {@link java.io.IOException}).
    *
    * @return
    * This debugging output stream.
    *
    * <p>
    * This allows several debugging calls to be chained together.
    * For example:
    * <pre>
    *    DebugWriterI  dbg = ...;
    *
    *    dbg.print("x=" + x).print(", y=" + y).println(); </pre>
    *
    * @since	1.1, 2003-02-01
    */

    public DebugWriterI println();
}

// End DebugWriterI.java