//==============================================================================
// tribble/io/SuspendableWriterI.java
//------------------------------------------------------------------------------

package tribble.io;


// System imports

import java.io.IOException;

import java.lang.String;


// Local imports

// (None)


/*******************************************************************************
* A character output stream that can be suspended and resumed.
*
* <p>
* This interface is used to implement any kind of character output stream that
* is capable of writing output (e.g., {@link java.io.Writer}).  It also
* provides the capability of suspending all output written to the stream, so
* that subsequent write requests perform no output.  It also provides the
* capability of resuming all output written to the stream.
*
* <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 example:
* <pre>
*    class MySuspendableOutput
*        extends tribble.io.SuspendableWriterI
*    {
*        /** Constructor. &#42;/
*        public MySuspendableOutput(java.io.Writer out)
*        { ... }
*
*        ...
*    } </pre>
*
* @version	$Revision: 1.3 $ $Date: 2003/02/01 17:30:03 $
* @since	2001-06-21
* @author
*	David R. Tribble,
*	<a href="mailto:david@tribble.com">david@tribble.com</a>.
*	<br>
*	<a href="../Copyright.html">Copyright</a> ©2001-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.
*
* @see	SuspendableWriter
* @see	SuspendablePrintWriter
* @see	DebugWriterI
*/

public interface SuspendableWriterI
{
// Identification

    /** Revision information. */
    static final String		REV =
        "@(#)tribble/io/SuspendableWriterI.java $Revision: 1.3 $ $Date: 2003/02/01 17:30:03 $\n";


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

    /***************************************************************************
    * Suspend subsequent output written to this output stream.
    *
    * <p>
    * Output to this stream can be resumed by calling {@link #resume}.
    *
    * <p>
    * This method may be called multiple times without any intervening call to
    * {@link #resume} without any ill effects.
    *
    * @since	1.1, 2001-06-21
    *
    * @see	#resume
    */

    public void suspend();


    /***************************************************************************
    * Resume subsequent output written to this output stream.
    *
    * <p>
    * Output to this stream can be suspended by calling {@link #suspend}.
    *
    * <p>
    * This method may be called multiple times without any previous or
    * intervening call to {@link #suspend} without any ill effects.
    *
    * @since	1.1, 2001-06-21
    *
    * @see	#suspend
    */

    public void resume();


    /***************************************************************************
    * Determine if this output stream is suspended or not.
    *
    * @return
    * True if this output stream is currently suspended, otherwise false.
    *
    * @since	1.1, 2001-09-01
    *
    * @see	#suspend
    */

    public boolean isSuspended();


    /***************************************************************************
    * Close this output stream.
    *
    * <p>
    * Note that this method is required to flush and close the underlying
    * output stream of this stream.  It does this regardless of whether or not
    * this stream is suspended.
    *
    * @throws	IOException
    * Thrown if an error occurs.
    *
    * @since	1.3, 2003-02-01
    */

    public void close()
        throws IOException;
}

// End SuspendableWriterI.java