* Unlike the {@link PrintStream} class, if automatic flushing is enabled it will be done only when one of the * println, printf, or format methods is invoked, rather than whenever a newline character * happens to be output. These methods use the platform's own notion of line separator rather than the newline * character. * *
* Methods in this class never throw I/O exceptions, although some of its constructors may. The client may inquire as to
* whether any errors have occurred by invoking {@link #checkError checkError()}.
*
* @author Frank Yellin
* @author Mark Reinhold
* @since JDK1.1
*/
public class PrintWriter extends Writer {
/**
* The underlying character-output stream of this PrintWriter.
*
* @since 1.2
*/
@Nullable
protected Writer out;
private final boolean autoFlush;
private boolean trouble = false;
@Nullable
private PrintStream psOut = null;
/**
* Line separator string. This is the value of the line.separator property at the moment that the stream was
* created.
*/
private final String lineSeparator;
/**
* Creates a new PrintWriter, without automatic line flushing.
*
* @param out
* A character-output stream
*/
public PrintWriter(Writer out) {
this(out, false);
}
/**
* Creates a new PrintWriter.
*
* @param out
* A character-output stream
* @param autoFlush
* A boolean; if true, the println, printf, or format methods will flush the
* output buffer
*/
public PrintWriter(Writer out, boolean autoFlush) {
super(out);
this.out = out;
this.autoFlush = autoFlush;
String lineSeparator = System.getProperty("line.separator");
assert lineSeparator != null; // line.separator is a built-in property and should not be null
this.lineSeparator = lineSeparator;
}
/**
* Creates a new PrintWriter, without automatic line flushing, from an existing OutputStream. This convenience
* constructor creates the necessary intermediate OutputStreamWriter, which will convert characters into bytes using
* the default character encoding.
*
* @param out
* An output stream
*
* @see java.io.OutputStreamWriter#OutputStreamWriter(java.io.OutputStream)
*/
public PrintWriter(OutputStream out) {
this(out, false);
}
/**
* Creates a new PrintWriter from an existing OutputStream. This convenience constructor creates the necessary
* intermediate OutputStreamWriter, which will convert characters into bytes using the default character encoding.
*
* @param out
* An output stream
* @param autoFlush
* A boolean; if true, the println, printf, or format methods will flush the
* output buffer
*
* @see java.io.OutputStreamWriter#OutputStreamWriter(java.io.OutputStream)
*/
public PrintWriter(OutputStream out, boolean autoFlush) {
this(new OutputStreamWriter(out), autoFlush);
// save print stream for error propagation
if (out instanceof java.io.PrintStream) {
this.psOut = (PrintStream) out;
}
}
/** Checks to make sure that the stream has not been closed */
private void ensureOpen() throws IOException {
if (this.out == null) {
throw new IOException("Stream closed");
}
}
/**
* Flushes the stream.
*
* @see #checkError()
*/
@Override
public void flush() {
try {
synchronized (this.lock) {
ensureOpen();
Writer out = this.out;
assert out != null;
out.flush();
}
} catch (IOException x) {
this.trouble = true;
}
}
/**
* Closes the stream and releases any system resources associated with it. Closing a previously closed stream has no
* effect.
*
* @see #checkError()
*/
@Override
public void close() {
Writer out = this.out;
try {
synchronized (this.lock) {
if (out == null) {
return;
}
out.close();
out = null;
}
} catch (IOException x) {
this.trouble = true;
}
}
/**
* Flushes the stream if it's not closed and checks its error state.
*
* @return true if the print stream has encountered an error, either on the underlying output stream or
* during a format conversion.
*/
public boolean checkError() {
Writer out = this.out;
if (out != null) {
flush();
}
if (out instanceof java.io.PrintWriter) {
PrintWriter pw = (PrintWriter) out;
return pw.checkError();
} else {
PrintStream psOut = this.psOut;
if (psOut != null) {
return psOut.checkError();
}
}
return this.trouble;
}
/**
* Indicates that an error has occurred.
*
*
* This method will cause subsequent invocations of {@link #checkError()} to return true until * {@link #clearError()} is invoked. */ protected void setError() { this.trouble = true; } /** * Clears the error state of this stream. * *
* This method will cause subsequent invocations of {@link #checkError()} to return false until another
* write operation fails and invokes {@link #setError()}.
*
* @since 1.6
*/
protected void clearError() {
this.trouble = false;
}
/*
* Exception-catching, synchronized output operations, which also implement the write() methods of Writer
*/
/**
* Writes a single character.
*
* @param c
* int specifying a character to be written.
*/
@Override
public void write(int c) {
try {
synchronized (this.lock) {
ensureOpen();
Writer out = this.out;
assert out != null;
out.write(c);
}
} catch (InterruptedIOException x) {
Thread.currentThread().interrupt();
} catch (IOException x) {
this.trouble = true;
}
}
/**
* Writes A Portion of an array of characters.
*
* @param buf
* Array of characters
* @param off
* Offset from which to start writing characters
* @param len
* Number of characters to write
*/
@Override
public void write(char buf[], int off, int len) {
try {
synchronized (this.lock) {
ensureOpen();
Writer out = this.out;
assert out != null;
out.write(buf, off, len);
}
} catch (InterruptedIOException x) {
Thread.currentThread().interrupt();
} catch (IOException x) {
this.trouble = true;
}
}
/**
* Writes an array of characters. This method cannot be inherited from the Writer class because it must suppress I/O
* exceptions.
*
* @param buf
* Array of characters to be written
*/
@Override
public void write(char buf[]) {
write(buf, 0, buf.length);
}
/**
* Writes a portion of a string.
*
* @param s
* A String
* @param off
* Offset from which to start writing characters
* @param len
* Number of characters to write
*/
@Override
public void write(String s, int off, int len) {
try {
synchronized (this.lock) {
ensureOpen();
Writer out = this.out;
assert out != null;
out.write(s, off, len);
}
} catch (InterruptedIOException x) {
Thread.currentThread().interrupt();
} catch (IOException x) {
this.trouble = true;
}
}
/**
* Writes a string. This method cannot be inherited from the Writer class because it must suppress I/O exceptions.
*
* @param s
* String to be written
*/
@Override
public void write(String s) {
write(s, 0, s.length());
}
private void newLine() {
try {
synchronized (this.lock) {
ensureOpen();
Writer out = this.out;
assert out != null;
out.write(this.lineSeparator);
if (this.autoFlush) {
out.flush();
}
}
} catch (InterruptedIOException x) {
Thread.currentThread().interrupt();
} catch (IOException x) {
this.trouble = true;
}
}
/* Methods that do not terminate lines */
/**
* Prints a boolean value. The string produced by {@link
* java.lang.String#valueOf(boolean)} is translated into bytes according to the platform's default character
* encoding, and these bytes are written in exactly the manner of the {@link
* #write(int)} method.
*
* @param b
* The boolean to be printed
*/
public void print(boolean b) {
write(b ? "true" : "false");
}
/**
* Prints a character. The character is translated into one or more bytes according to the platform's default
* character encoding, and these bytes are written in exactly the manner of the {@link
* #write(int)} method.
*
* @param c
* The char to be printed
*/
public void print(char c) {
write(c);
}
/**
* Prints an integer. The string produced by {@link
* java.lang.String#valueOf(int)} is translated into bytes according to the platform's default character
* encoding, and these bytes are written in exactly the manner of the {@link #write(int)} method.
*
* @param i
* The int to be printed
* @see java.lang.Integer#toString(int)
*/
public void print(int i) {
write(String.valueOf(i));
}
/**
* Prints a long integer. The string produced by {@link
* java.lang.String#valueOf(long)} is translated into bytes according to the platform's default character
* encoding, and these bytes are written in exactly the manner of the {@link #write(int)} method.
*
* @param l
* The long to be printed
* @see java.lang.Long#toString(long)
*/
public void print(long l) {
write(String.valueOf(l));
}
/**
* Prints a floating-point number. The string produced by {@link
* java.lang.String#valueOf(float)} is translated into bytes according to the platform's default character
* encoding, and these bytes are written in exactly the manner of the {@link #write(int)} method.
*
* @param f
* The float to be printed
* @see java.lang.Float#toString(float)
*/
public void print(float f) {
write(String.valueOf(f));
}
/**
* Prints a double-precision floating-point number. The string produced by
* {@link java.lang.String#valueOf(double)} is translated into bytes according to the platform's
* default character encoding, and these bytes are written in exactly the manner of the {@link
* #write(int)} method.
*
* @param d
* The double to be printed
* @see java.lang.Double#toString(double)
*/
public void print(double d) {
write(String.valueOf(d));
}
/**
* Prints an array of characters. The characters are converted into bytes according to the platform's default
* character encoding, and these bytes are written in exactly the manner of the {@link #write(int)}
* method.
*
* @param s
* The array of chars to be printed
*
* @throws NullPointerException
* If s is null
*/
public void print(char s[]) {
write(s);
}
/**
* Prints a string. If the argument is null then the string "null" is printed. Otherwise,
* the string's characters are converted into bytes according to the platform's default character encoding, and
* these bytes are written in exactly the manner of the {@link #write(int)} method.
*
* @param s
* The String to be printed
*/
public void print(@Nullable String s) {
if (s == null) {
s = "null";
}
write(s);
}
/**
* Prints an object. The string produced by the {@link
* java.lang.String#valueOf(Object)} method is translated into bytes according to the platform's default
* character encoding, and these bytes are written in exactly the manner of the {@link #write(int)}
* method.
*
* @param obj
* The Object to be printed
* @see java.lang.Object#toString()
*/
public void print(Object obj) {
write(String.valueOf(obj));
}
/* Methods that do terminate lines */
/**
* Terminates the current line by writing the line separator string. The line separator string is defined by the
* system property line.separator, and is not necessarily a single newline character
* ('\n').
*/
public void println() {
newLine();
}
/**
* Prints a boolean value and then terminates the line. This method behaves as though it invokes
* {@link #print(boolean)} and then {@link #println()}.
*
* @param x
* the boolean value to be printed
*/
public void println(boolean x) {
synchronized (this.lock) {
print(x);
println();
}
}
/**
* Prints a character and then terminates the line. This method behaves as though it invokes
* {@link #print(char)} and then {@link
* #println()}.
*
* @param x
* the char value to be printed
*/
public void println(char x) {
synchronized (this.lock) {
print(x);
println();
}
}
/**
* Prints an integer and then terminates the line. This method behaves as though it invokes
* {@link #print(int)} and then {@link
* #println()}.
*
* @param x
* the int value to be printed
*/
public void println(int x) {
synchronized (this.lock) {
print(x);
println();
}
}
/**
* Prints a long integer and then terminates the line. This method behaves as though it invokes
* {@link #print(long)} and then {@link #println()}.
*
* @param x
* the long value to be printed
*/
public void println(long x) {
synchronized (this.lock) {
print(x);
println();
}
}
/**
* Prints a floating-point number and then terminates the line. This method behaves as though it invokes
* {@link #print(float)} and then {@link #println()}.
*
* @param x
* the float value to be printed
*/
public void println(float x) {
synchronized (this.lock) {
print(x);
println();
}
}
/**
* Prints a double-precision floating-point number and then terminates the line. This method behaves as though it
* invokes {@link
* #print(double)} and then {@link #println()}.
*
* @param x
* the double value to be printed
*/
public void println(double x) {
synchronized (this.lock) {
print(x);
println();
}
}
/**
* Prints an array of characters and then terminates the line. This method behaves as though it invokes
* {@link #print(char[])} and then {@link #println()}.
*
* @param x
* the array of char values to be printed
*/
public void println(char x[]) {
synchronized (this.lock) {
print(x);
println();
}
}
/**
* Prints a String and then terminates the line. This method behaves as though it invokes
* {@link #print(String)} and then {@link #println()}.
*
* @param x
* the String value to be printed
*/
public void println(String x) {
synchronized (this.lock) {
print(x);
println();
}
}
/**
* Prints an Object and then terminates the line. This method calls at first String.valueOf(x) to get the printed
* object's string value, then behaves as though it invokes {@link #print(String)} and then
* {@link #println()}.
*
* @param x
* The Object to be printed.
*/
public void println(Object x) {
String s = String.valueOf(x);
synchronized (this.lock) {
print(s);
println();
}
}
/**
* Appends the specified character sequence to this writer.
*
*
* An invocation of this method of the form out.append(csq) behaves in exactly the same way as the * invocation * *
* out.write(csq.toString()) ** *
* Depending on the specification of toString for the character sequence csq, the entire sequence * may not be appended. For instance, invoking the toString method of a character buffer will return a * subsequence whose content depends upon the buffer's position and limit. * * @param csq * The character sequence to append. If csq is null, then the four characters * "null" are appended to this writer. * * @return This writer * * @since 1.5 */ @Override public PrintWriter append(@Nullable CharSequence csq) { if (csq == null) { write("null"); } else { write(csq.toString()); } return this; } /** * Appends a subsequence of the specified character sequence to this writer. * *
* An invocation of this method of the form out.append(csq, start, * end) when csq is not null, behaves in exactly the same way as the invocation * *
* out.write(csq.subSequence(start, end).toString()) ** * @param csq * The character sequence from which a subsequence will be appended. If csq is null, * then characters will be appended as if csq contained the four characters "null". * * @param start * The index of the first character in the subsequence * * @param end * The index of the character following the last character in the subsequence * * @return This writer * * @throws IndexOutOfBoundsException * If start or end are negative, start is greater than end, or * end is greater than csq.length() * * @since 1.5 */ @Override public PrintWriter append(@Nullable CharSequence csq, int start, int end) { CharSequence cs = (csq == null ? "null" : csq); write(cs.subSequence(start, end).toString()); return this; } /** * Appends the specified character to this writer. * *
* An invocation of this method of the form out.append(c) behaves in exactly the same way as the invocation * *
* out.write(c) ** * @param c * The 16-bit character to append * * @return This writer * * @since 1.5 */ @Override public PrintWriter append(char c) { write(c); return this; } }