* This is a default implementation of a character output stream that can be
* suspended and resumed (see {@link SuspendableWriterI}), based on the standard
* {@link java.io.Writer} class. It provides the capability of suspending all
* output written to the stream, so that subsequent write requests perform no
* output. It also has the capability of resuming all output written to the
* stream.
*
* @version $Revision: 1.1 $ $Date: 2001/09/01 17:59:40 $
* @since 2001-06-21
* @author
* David R. Tribble,
* david@tribble.com.
*
* Copyright ©2001 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.
*
* @see Writer
*/
public class SuspendableWriter
extends Writer
implements SuspendableWriterI
{
// Identification
/** Revision information. */
static final String REV =
"@(#)tribble/io/SuspendableWriter.java $Revision: 1.1 $ $Date: 2001/09/01 17:59:40 $\n";
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// Protected constants
/** Exception text contents for a closed output stream. */
protected static final String EXCEPT_CLOSED =
"Output stream is closed";
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// Protected variables
/** Underlying output stream. */
protected Writer m_out;
/** Suspended underlying output stream. */
protected Writer m_sus;
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// Public constructor methods
/***************************************************************************
* Constructor.
*
* @since 1.1, 2001-06-21
*/
public SuspendableWriter()
{
// Do nothing
}
/***************************************************************************
* Constructor.
* Establishes the underlying output stream to which all output for this
* stream is written.
*
* @param out
* The underlying output stream for this stream.
*
* @since 1.1, 2001-06-21
*/
public SuspendableWriter(Writer out)
{
// Establish the underlying output stream for this stream
setOutput(out);
}
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// Public methods
/***************************************************************************
* Suspends subsequent output written to this output stream.
*
*
* Output to this stream can be resumed by calling {@link #resume}. * *
* 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 synchronized void suspend() //implements tribble.io.SuspendableWriterI { // Suspend subsequent output to this stream if (m_out != null) { m_sus = m_out; m_out = null; } } /*************************************************************************** * Resumes subsequent output written to this output stream. * *
* Output to this stream can be suspended by calling {@link #suspend}. * *
* 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 synchronized void resume() //implements tribble.io.SuspendableWriterI { // Resume subsequent output to this stream if (m_sus != null) { m_out = m_sus; m_sus = null; } } /*************************************************************************** * Determines 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() //implements tribble.io.SuspendableWriterI { // Determine if this output stream is suspended return (m_out == null); } /*************************************************************************** * Closes this output stream. * *
* Note that this method is required to flush and close the underlying * output stream of this stream. Any writes subsequent to closing this * stream should throw an IOException exception. * * @throws IOException * Thrown if an output error occurs. * * @since 1.1, 2001-06-21 */ public synchronized void close() throws IOException //overrided java.io.Writer { // Close the underlying output stream if (m_out != null) { m_out.flush(); // May throw m_out.close(); // May throw } // Disassociate the underlying output stream from this stream m_out = null; m_sus = null; } /*************************************************************************** * Flushes any pending output to the output stream. * * @throws IOException * Thrown if an output error occurs. * * @since 1.1, 2001-06-21 */ public void flush() throws IOException //overrided java.io.Writer { // Flush the underlying output stream if (m_out != null) m_out.flush(); } /*************************************************************************** * Writes the contents of a character array to this output stream. * * @param cbuf * A character buffer to write. * * @throws IOException * Thrown if an output error occurs, or if this output stream is closed. * * @since 1.1, 2001-06-21 */ public synchronized void write(char[] cbuf) throws IOException //overrided java.io.Writer { // Write character output to the underlying output stream if (m_out != null) m_out.write(cbuf); // May throw else if (m_sus == null) throw (new IOException(EXCEPT_CLOSED)); } /*************************************************************************** * Writes a portion of a character array to this output stream. * * @param cbuf * A character buffer, from which a subset of characters is written. * * @param off * The offset of the first character within character buffer cbuf * to write. * * @param len * The number of characters from character buffer cbuf to write. * * @throws IOException * Thrown if an output error occurs, or if this output stream is closed. * * @since 1.1, 2001-06-21 */ public synchronized void write(char[] cbuf, int off, int len) throws IOException //overrided java.io.Writer { // Write character output to the underlying output stream if (m_out != null) m_out.write(cbuf, off, len); // May throw else if (m_sus == null) throw (new IOException(EXCEPT_CLOSED)); } /*************************************************************************** * Writes the contents of a string to this output stream. * * @param str * A string to write. * * @throws IOException * Thrown if an output error occurs, or if this output stream is closed. * * @since 1.1, 2001-06-21 */ public synchronized void write(String str) throws IOException //overrided java.io.Writer { // Write character output to the underlying output stream if (m_out != null) m_out.write(str); // May throw else if (m_sus == null) throw (new IOException(EXCEPT_CLOSED)); } /*************************************************************************** * Writes a subset of a string to this output stream. * * @param str * A string containing the substring to write. * * @param off * The offset of the first character within the string to write. * * @param len * The number of characters from the substring to write. * * @throws IOException * Thrown if an output error occurs, or if this output stream is closed. * * @since 1.1, 2001-06-21 */ public synchronized void write(String str, int off, int len) throws IOException //overrided java.io.Writer { // Write character output to the underlying output stream if (m_out != null) m_out.write(str, off, len); // May throw else if (m_sus == null) throw (new IOException(EXCEPT_CLOSED)); } /*************************************************************************** * Writes a single character to this output stream. * * @param c * A character code to write. * * @throws IOException * Thrown if an output error occurs, or if this output stream is closed. * * @since 1.1, 2001-06-21 */ public synchronized void write(int c) throws IOException //overrided java.io.Writer { // Write character output to the underlying output stream if (m_out != null) m_out.write(c); // May throw else if (m_sus == null) throw (new IOException(EXCEPT_CLOSED)); } /*************************************************************************** * Establishes the underlying output stream to which all output for this * stream is written. * * @param out * The underlying output stream for this stream. * * @since 1.1, 2001-06-21 */ public synchronized void setOutput(Writer out) { // Establish the underlying output stream for this stream m_out = out; m_sus = null; } /*************************************************************************** * Retrieves the underlying output stream to which all output for this * stream is written. * * @return * The underlying output stream of this stream. * * @since 1.1, 2001-06-21 */ public Writer getOutput() { // Retrieve the underlying output stream for this stream return (m_out); } // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - // Protected methods /*************************************************************************** * Finalization. * *
* Flushes, but does not close, the underlying output stream (if there is * one), and then disassociates it from this output stream. * * @throws Throwable * Thrown if an error occurs. * * @since 1.1, 2001-06-21 */ protected synchronized void finalize() throws Throwable { try { // Flush the underlying output stream for this stream if (m_out != null) m_out.flush(); // May throw } catch (Exception ex) { // Ignore } // Note: Do not close the underlying output stream for this stream // Disassociate the underlying output stream from this stream m_out = null; m_sus = null; super.finalize(); } } // End SuspendableWriter.java