tribble.io
Class SuspendablePrintWriter

java.lang.Object
  extended by java.io.Writer
      extended by java.io.PrintWriter
          extended by 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