* The buffer size may be specified, or the default size may be accepted. The default is large enough for most purposes. * *
* A newLine() method is provided, which uses the platform's own notion of line separator as defined by the system * property line.separator. Not all platforms use the newline character ('\n') to terminate lines. Calling this * method to terminate each output line is therefore preferred to writing a newline character directly. * *
* In general, a Writer sends its output immediately to the underlying character or byte stream. Unless prompt output is * required, it is advisable to wrap a BufferedWriter around any Writer whose write() operations may be costly, such as * FileWriters and OutputStreamWriters. For example, * *
* PrintWriter out = new PrintWriter(new BufferedWriter(new FileWriter("foo.out")));
*
*
* will buffer the PrintWriter's output to the file. Without buffering, each invocation of a print() method would cause
* characters to be converted into bytes that would then be written immediately to the file, which can be very
* inefficient.
*
* @see OutputStreamWriter
*
* @author Mark Reinhold
* @since JDK1.1
*/
public class BufferedWriter extends Writer {
@Nullable
private Writer out;
@Nullable
private char cb[];
private final int nChars;
private int nextChar;
private static int defaultCharBufferSize = 8192;
/**
* 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 buffered character-output stream that uses a default-sized output buffer.
*
* @param out
* A Writer
*/
public BufferedWriter(Writer out) {
this(out, defaultCharBufferSize);
}
/**
* Creates a new buffered character-output stream that uses an output buffer of the given size.
*
* @param out
* A Writer
* @param sz
* Output-buffer size, a positive integer
*
* @exception IllegalArgumentException
* If {@code sz <= 0}
*/
public BufferedWriter(Writer out, int sz) {
super(out);
if (sz <= 0) {
throw new IllegalArgumentException("Buffer size <= 0");
}
this.out = out;
this.cb = new char[sz];
this.nChars = sz;
this.nextChar = 0;
String lineSeparator = System.getProperty("line.separator");
assert lineSeparator != null; // line.separator is a built-in property and should not be null
this.lineSeparator = lineSeparator;
}
/** 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 output buffer to the underlying character stream, without flushing the stream itself. This method is
* non-private only so that it may be invoked by PrintStream.
*/
void flushBuffer() throws IOException {
synchronized (this.lock) {
ensureOpen();
Writer out = this.out;
assert out != null;
char[] cb = this.cb;
assert cb != null;
if (this.nextChar == 0) {
return;
}
out.write(cb, 0, this.nextChar);
this.nextChar = 0;
}
}
/**
* Writes a single character.
*
* @exception IOException
* If an I/O error occurs
*/
@Override
public void write(int c) throws IOException {
synchronized (this.lock) {
ensureOpen();
if (this.nextChar >= this.nChars) {
flushBuffer();
}
char[] cb = this.cb;
assert cb != null;
cb[this.nextChar++] = (char) c;
}
}
/**
* Our own little min method, to avoid loading java.lang.Math if we've run out of file descriptors and we're trying
* to print a stack trace.
*/
private int min(int a, int b) {
if (a < b) {
return a;
}
return b;
}
/**
* Writes a portion of an array of characters.
*
*
* Ordinarily this method stores characters from the given array into this stream's buffer, flushing the buffer to
* the underlying stream as needed. If the requested length is at least as large as the buffer, however, then this
* method will flush the buffer and write the characters directly to the underlying stream. Thus redundant
* BufferedWriters will not copy data unnecessarily.
*
* @param cbuf
* A character array
* @param off
* Offset from which to start reading characters
* @param len
* Number of characters to write
*
* @exception IOException
* If an I/O error occurs
*/
@Override
public void write(char cbuf[], int off, int len) throws IOException {
synchronized (this.lock) {
ensureOpen();
Writer out = this.out;
assert out != null;
char[] cb = this.cb;
assert cb != null;
if ((off < 0) || (off > cbuf.length) || (len < 0) || ((off + len) > cbuf.length) || ((off + len) < 0)) {
throw new IndexOutOfBoundsException();
} else if (len == 0) {
return;
}
if (len >= this.nChars) {
/*
* If the request length exceeds the size of the output buffer, flush the buffer and then write the data
* directly. In this way buffered streams will cascade harmlessly.
*/
flushBuffer();
out.write(cbuf, off, len);
return;
}
int b = off, t = off + len;
while (b < t) {
int d = min(this.nChars - this.nextChar, t - b);
System.arraycopy(cbuf, b, cb, this.nextChar, d);
b += d;
this.nextChar += d;
if (this.nextChar >= this.nChars) {
flushBuffer();
}
}
}
}
/**
* Writes a portion of a String.
*
*
* If the value of the len parameter is negative then no characters are written. This is contrary to the * specification of this method in the {@linkplain java.io.Writer#write(java.lang.String,int,int) superclass}, which * requires that an {@link IndexOutOfBoundsException} be thrown. * * @param s * String to be written * @param off * Offset from which to start reading characters * @param len * Number of characters to be written * * @exception IOException * If an I/O error occurs */ @Override public void write(String s, int off, int len) throws IOException { synchronized (this.lock) { ensureOpen(); char[] cb = this.cb; assert cb != null; int b = off, t = off + len; while (b < t) { int d = min(this.nChars - this.nextChar, t - b); s.getChars(b, b + d, cb, this.nextChar); b += d; this.nextChar += d; if (this.nextChar >= this.nChars) { flushBuffer(); } } } } /** * Writes a line separator. The line separator string is defined by the system property line.separator, and * is not necessarily a single newline ('\n') character. * * @exception IOException * If an I/O error occurs */ public void newLine() throws IOException { write(this.lineSeparator); } /** * Flushes the stream. * * @exception IOException * If an I/O error occurs */ @Override public void flush() throws IOException { synchronized (this.lock) { Writer out = this.out; assert out != null; flushBuffer(); out.flush(); } } @Override public void close() throws IOException { synchronized (this.lock) { Writer out = this.out; if (out == null) { return; } try (Writer w = out) { flushBuffer(); } finally { this.out = null; this.cb = null; } } } }