tribble.io
Class SuspendablePrintWriter

java.lang.Object
  java.io.Writer
      java.io.PrintWriter
          tribble.io.SuspendablePrintWriter

All Implemented Interfaces:

java.io.Closeable, java.io.Flushable, java.lang.Appendable, SuspendableWriterI

Direct Known Subclasses:

DiagnosticOutputDfl

public class SuspendablePrintWriter
extends java.io.PrintWriter
implements SuspendableWriterI

A character print output stream that can be suspended and resumed.

This is a default implementation of a character output stream that can be suspended and resumed (see SuspendableWriterI), based on the standard PrintWriter 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.

The member methods of this class never throw exceptions (such as IOException). Instead, when errors occur, they set an internal flag that can be examined by calling method checkError(). Unlike the PrintWriter class, this class provides a clearError() method for clearing the internal error flag.

Since:

2001-06-30

Version:

$Revision: 1.3 $ $Date: 2003/02/01 17:28:18 $

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 Also:

SuspendableWriter

Field Summary

protected boolean	m_err Internal error flag.
protected java.io.Writer	m_sus Underlying output stream.
(package private) static java.lang.String	REV Revision information.

Fields inherited from class java.io.PrintWriter

out

Fields inherited from class java.io.Writer

lock

Constructor Summary

SuspendablePrintWriter()
Constructor.

SuspendablePrintWriter(java.io.OutputStream os)
Constructor.

SuspendablePrintWriter(java.io.OutputStream os, boolean autoFlush)
Constructor.

SuspendablePrintWriter(java.io.Writer os)
Constructor.

SuspendablePrintWriter(java.io.Writer os, boolean autoFlush)
Constructor.

Method Summary

boolean	checkError() Checks the internal error flag.
void	clearError() Clears the internal error flag.
void	close() Closes this output stream.
protected void	finalize() Finalization.
void	flush() Flushes any pending output to the output stream.
java.io.Writer	getOutput() Retrieves the underlying output stream to which all output for this stream is written.
boolean	isSuspended() Determines if this output stream is suspended or not.
void	print(boolean val) Writes a boolean value, as its equivalent text string, to this output stream.
void	print(char val) Writes a character to this output stream.
void	print(char[] val) Writes the contents of a character array to this output stream.
void	print(double val) Writes a double float value, as its equivalent text string, to this output stream.
void	print(float val) Writes a float value, as its equivalent text string, to this output stream.
void	print(int val) Writes an integer value, as its equivalent text string, to this output stream.
void	print(long val) Writes a long integer value, as its equivalent text string, to this output stream.
void	print(java.lang.Object val) Writes an object, as its equivalent text string, to this output stream.
void	print(java.lang.String val) Writes the contents of a text string to this output stream.
void	println() Writes a newline to this output stream.
void	println(boolean val) Writes a boolean value, as its equivalent text string, and then a newline to this output stream.
void	println(char val) Writes a character and then a newline to this output stream.
void	println(char[] val) Writes the contents of a character array and then a newline to this output stream.
void	println(double val) Writes a double float value, as its equivalent text string, and then a newline to this output stream.
void	println(float val) Writes a float value, as its equivalent text string, and then a newline to this output stream.
void	println(int val) Writes an integer value, as its equivalent text string, and then a newline to this output stream.
void	println(long val) Writes a long integer value, as its equivalent text string, and then a newline to this output stream.
void	println(java.lang.Object val) Writes an object, as its equivalent text string, and then a newline to this output stream.
void	println(java.lang.String val) Writes the contents of a string and then a newline to this output stream.
void	resume() Resumes subsequent output written to this output stream.
void	setOutput(java.io.Writer os) Establishes the underlying output stream to which all output for this stream is written.
void	suspend() Suspends subsequent output written to this output stream.
void	write(char[] cbuf) Writes the contents of a character array to this output stream.
void	write(char[] cbuf, int off, int len) Writes a portion of a character array to this output stream.
void	write(int c) Writes a single character to this output stream.
void	write(java.lang.String str) Writes the contents of a string to this output stream.
void	write(java.lang.String str, int off, int len) Writes a subset of a string to this output stream.

Methods inherited from class java.io.PrintWriter

append, append, append, format, format, printf, printf, setError

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

REV

static final java.lang.String REV

Revision information.

See Also:

Constant Field Values

m_sus

protected java.io.Writer m_sus

Underlying output stream.

m_err

protected boolean m_err

Internal error flag.

Constructor Detail

SuspendablePrintWriter

public SuspendablePrintWriter()

Constructor. Establishes a null (empty) underlying output stream for this stream.

Since:

1.1, 2001-06-30

See Also:

setOutput(java.io.Writer)

SuspendablePrintWriter

public SuspendablePrintWriter(java.io.Writer os)

Constructor. Establishes the underlying output stream to which all output for this stream is written.

Parameters:

os - The underlying output stream for this print stream.

Since:

1.1, 2001-06-30

SuspendablePrintWriter

public SuspendablePrintWriter(java.io.Writer os,
                              boolean autoFlush)

Constructor. Establishes the underlying output stream to which all output for this stream is written.

Parameters:

os - The underlying output stream for this print stream.

autoFlush - If true, this flag specifies that pending (buffered) output should be flushed to the underlying output stream whenever println() is called.

Since:

1.1, 2001-06-30

SuspendablePrintWriter

public SuspendablePrintWriter(java.io.OutputStream os)

Constructor. Establishes the underlying output stream to which all output for this stream is written.

Parameters:

os - The underlying output stream (which is a byte output stream) for this print stream.

Since:

1.1, 2001-06-30

SuspendablePrintWriter

public SuspendablePrintWriter(java.io.OutputStream os,
                              boolean autoFlush)

Constructor. Establishes the underlying output stream to which all output for this stream is written.

Parameters:

os - The underlying output stream (which is a byte output stream) for this print stream.

autoFlush - If true, this flag specifies that pending (buffered) output should be flushed to the underlying output stream whenever println() is called.

Since:

1.1, 2001-06-30

Method Detail

suspend

public void suspend()

Suspends subsequent output written to this output stream.

Subsequent calls to any of the write(), 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, 2001-06-30

See Also:

resume()

resume

public void resume()

Resumes subsequent output written to this output stream.

Subsequent calls to any of the write(), 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, 2001-06-30

See Also:

suspend()

isSuspended

public boolean isSuspended()

Determines if this 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, 2001-09-11

See Also:

suspend()

close

public void close()

Closes this output stream.

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.

Note that this method does not throw any unchecked exceptions (in particular, java.io.IOException).

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface SuspendableWriterI

Overrides:

close in class java.io.PrintWriter

Since:

1.1, 2001-06-30

flush

public void flush()

Flushes any pending output to the output stream.

This does nothing if this output stream is suspended.

Specified by:

flush in interface java.io.Flushable

Overrides:

flush in class java.io.PrintWriter

Since:

1.1, 2001-06-30

checkError

public boolean checkError()

Checks the internal error flag.

Any pending output to the underlying output stream is flushed, and then the setting of the internal error flag is is returned. The flag is set any time an output (write) error occurs on the underlying output stream.

The status of the underlying output stream is always checked, whether or not this stream is suspended.

Overrides:

checkError in class java.io.PrintWriter

Returns:

True if an output (write) error has occurred on this stream.

Since:

1.1, 2001-06-30

See Also:

clearError()

write

public void write(char[] cbuf)

Writes the contents of a character array to this output stream. No output is written if this stream is suspended.

Overrides:

write in class java.io.PrintWriter

Parameters:

cbuf - A character buffer to write.

Since:

1.1, 2001-06-30

write

public void write(char[] cbuf,
                  int off,
                  int len)

Writes a portion of a character array to this output stream. No output is written if this stream is suspended.

Overrides:

write in class java.io.PrintWriter

Parameters:

cbuf - A character buffer, from which a subset of characters is written.

off - The offset of the first character within character buffer cbuf to write.

len - The number of characters from character buffer cbuf to write.

Since:

1.1, 2001-06-30

write

public void write(java.lang.String str)

Writes the contents of a string to this output stream. No output is written if this stream is suspended.

Overrides:

write in class java.io.PrintWriter

Parameters:

str - A string to write.

Since:

1.1, 2001-06-30

write

public void write(java.lang.String str,
                  int off,
                  int len)

Writes a subset of a string to this output stream. No output is written if this stream is suspended.

Overrides:

write in class java.io.PrintWriter

Parameters:

str - A string containing the substring to write.

off - The offset of the first character within the string to write.

len - The number of characters from the substring to write.

Since:

1.1, 2001-06-30

write

public void write(int c)

Writes a single character to this output stream. No output is written if this stream is suspended.

Overrides:

write in class java.io.PrintWriter

Parameters:

c - A character code to write.

Since:

1.1, 2001-06-30

print

public void print(boolean val)

Writes a boolean value, as its equivalent text string, to this output stream. No output is written if this stream is suspended.

Overrides:

print in class java.io.PrintWriter

Parameters:

val - A boolean value to write.

Since:

1.1, 2001-06-30

print

public void print(int val)

Writes an integer value, as its equivalent text string, to this output stream. No output is written if this stream is suspended.

Overrides:

print in class java.io.PrintWriter

Parameters:

val - An integer value to write.

Since:

1.1, 2001-06-30

print

public void print(long val)

Writes a long integer value, as its equivalent text string, to this output stream. No output is written if this stream is suspended.

Overrides:

print in class java.io.PrintWriter

Parameters:

val - A long integer value to write.

Since:

1.1, 2001-06-30

print

public void print(float val)

Writes a float value, as its equivalent text string, to this output stream. No output is written if this stream is suspended.

Overrides:

print in class java.io.PrintWriter

Parameters:

val - A float value to write.

Since:

1.1, 2001-06-30

print

public void print(double val)

Writes a double float value, as its equivalent text string, to this output stream. No output is written if this stream is suspended.

Overrides:

print in class java.io.PrintWriter

Parameters:

val - A double float value to write.

Since:

1.1, 2001-06-30

print

public void print(char val)

Writes a character to this output stream. No output is written if this stream is suspended.

Overrides:

print in class java.io.PrintWriter

Parameters:

val - A character to write.

Since:

1.1, 2001-06-30

print

public void print(char[] val)

Writes the contents of a character array to this output stream. No output is written if this stream is suspended.

Overrides:

print in class java.io.PrintWriter

Parameters:

val - A character array to write.

Since:

1.1, 2001-06-30

print

public void print(java.lang.String val)

Writes the contents of a text string to this output stream. No output is written if this stream is suspended.

Overrides:

print in class java.io.PrintWriter

Parameters:

val - A string to write.

Since:

1.1, 2001-06-30

print

public void print(java.lang.Object val)

Writes an object, as its equivalent text string, to this output stream. No output is written if this stream is suspended.

Overrides:

print in class java.io.PrintWriter

Parameters:

val - An object to write.

Since:

1.1, 2001-06-30

println

public void println()

Writes a newline to this output stream. No output is written if this stream is suspended.

Overrides:

println in class java.io.PrintWriter

Since:

1.1, 2001-06-30

println

public void println(boolean val)

Writes a boolean value, as its equivalent text string, and then a newline to this output stream. No output is written if this stream is suspended.

Overrides:

println in class java.io.PrintWriter

Parameters:

val - A boolean value to write.

Since:

1.1, 2001-06-30

println

public void println(int val)

Writes an integer value, as its equivalent text string, and then a newline to this output stream. No output is written if this stream is suspended.

Overrides:

println in class java.io.PrintWriter

Parameters:

val - An integer value to write.

Since:

1.1, 2001-06-30

println

public void println(long val)

Writes a long integer value, as its equivalent text string, and then a newline to this output stream. No output is written if this stream is suspended.

Overrides:

println in class java.io.PrintWriter

Parameters:

val - A long integer value to write.

Since:

1.1, 2001-06-30

println

public void println(float val)

Writes a float value, as its equivalent text string, and then a newline to this output stream. No output is written if this stream is suspended.

Overrides:

println in class java.io.PrintWriter

Parameters:

val - A float value to write.

Since:

1.1, 2001-06-30

println

public void println(double val)

Writes a double float value, as its equivalent text string, and then a newline to this output stream. No output is written if this stream is suspended.

Overrides:

println in class java.io.PrintWriter

Parameters:

val - A double float value to write.

Since:

1.1, 2001-06-30

println

public void println(char val)

Writes a character and then a newline to this output stream. No output is written if this stream is suspended.

Overrides:

println in class java.io.PrintWriter

Parameters:

val - A character to write.

Since:

1.1, 2001-06-30

println

public void println(char[] val)

Writes the contents of a character array and then a newline to this output stream. No output is written if this stream is suspended.

Overrides:

println in class java.io.PrintWriter

Parameters:

val - A character array to write.

Since:

1.1, 2001-06-30

println

public void println(java.lang.String val)

Writes the contents of a string and then a newline to this output stream. No output is written if this stream is suspended.

Overrides:

println in class java.io.PrintWriter

Parameters:

val - A string to write.

Since:

1.1, 2001-06-30

println

public void println(java.lang.Object val)

Writes an object, as its equivalent text string, and then a newline to this output stream. No output is written if this stream is suspended.

Overrides:

println in class java.io.PrintWriter

Parameters:

val - An object to write.

Since:

1.1, 2001-06-30

setOutput

public void setOutput(java.io.Writer os)

Establishes the underlying output stream to which all output for this stream is written.

Note that calling this method implicitly resumes output to this stream and clears the internal error flag.

Parameters:

os - The underlying output stream for this stream.

Since:

1.1, 2001-06-30

getOutput

public java.io.Writer getOutput()

Retrieves the underlying output stream to which all output for this stream is written.

Returns:

The underlying output stream of this stream.

Since:

1.1, 2001-06-30

clearError

public void clearError()

Clears the internal error flag.

Note that due to the deficiencies in the way that the PrintWriter class is implemented, the effect of clearing the internal flag may be undone after the next call to any of the write() or print() methods.

Since:

1.1, 2001-06-30

See Also:

checkError()

finalize

protected void finalize()
                 throws java.lang.Throwable

Finalization.

Flushes, but does not close, the underlying output stream (if there is one), and then disassociates it from this output stream.

Overrides:

finalize in class java.lang.Object

Throws:

java.lang.Throwable - Thrown if an error occurs.

Since:

1.1, 2001-06-30