/* * @(#)Writer.java 1.26 04/07/16 * * Copyright 2004 Sun Microsystems, Inc. All rights reserved. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms. */ package java.io; /** * Abstract class for writing to character streams. The only methods that a * subclass must implement are write(char[], int, int), flush(), and close(). * Most subclasses, however, will override some of the methods defined here in * order to provide higher efficiency, additional functionality, or both. * * @see Writer * @see BufferedWriter * @see CharArrayWriter * @see FilterWriter * @see OutputStreamWriter * @see FileWriter * @see PipedWriter * @see PrintWriter * @see StringWriter * @see Reader * * @version 1.26, 04/07/16 * @author Mark Reinhold * @since JDK1.1 */ public abstract class Writer implements Appendable, Closeable, Flushable { /** * Temporary buffer used to hold writes of strings and single characters */ private char[] writeBuffer; /** * Size of writeBuffer, must be >= 1 */ private final int writeBufferSize = 1024; /** * The object used to synchronize operations on this stream. For * efficiency, a character-stream object may use an object other than * itself to protect critical sections. A subclass should therefore use * the object in this field rather than this or a synchronized * method. */ protected Object lock; /** * Create a new character-stream writer whose critical sections will * synchronize on the writer itself. */ protected Writer() { this.lock = this; } /** * Create a new character-stream writer whose critical sections will * synchronize on the given object. * * @param lock Object to synchronize on. */ protected Writer(Object lock) { if (lock == null) { throw new NullPointerException(); } this.lock = lock; } /** * Write a single character. The character to be written is contained in * the 16 low-order bits of the given integer value; the 16 high-order bits * are ignored. * *

Subclasses that intend to support efficient single-character output * should override this method. * * @param c int specifying a character to be written. * @exception IOException If an I/O error occurs */ public void write(int c) throws IOException { synchronized (lock) { if (writeBuffer == null){ writeBuffer = new char[writeBufferSize]; } writeBuffer[0] = (char) c; write(writeBuffer, 0, 1); } } /** * Write an array of characters. * * @param cbuf Array of characters to be written * * @exception IOException If an I/O error occurs */ public void write(char cbuf[]) throws IOException { write(cbuf, 0, cbuf.length); } /** * Write a portion of an array of characters. * * @param cbuf Array of characters * @param off Offset from which to start writing characters * @param len Number of characters to write * * @exception IOException If an I/O error occurs */ abstract public void write(char cbuf[], int off, int len) throws IOException; /** * Write a string. * * @param str String to be written * * @exception IOException If an I/O error occurs */ public void write(String str) throws IOException { write(str, 0, str.length()); } /** * Write a portion of a string. * * @param str A String * @param off Offset from which to start writing characters * @param len Number of characters to write * * @exception IOException If an I/O error occurs */ public void write(String str, int off, int len) throws IOException { synchronized (lock) { char cbuf[]; if (len <= writeBufferSize) { if (writeBuffer == null) { writeBuffer = new char[writeBufferSize]; } cbuf = writeBuffer; } else { // Don't permanently allocate very large buffers. cbuf = new char[len]; } str.getChars(off, (off + len), cbuf, 0); write(cbuf, 0, len); } } /** * 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 * * @throws IOException * If an I/O error occurs * * @since 1.5 */ public Writer append(CharSequence csq) throws IOException { if (csq == null) write("null"); else write(csq.toString()); return this; } /** * Appends a subsequence of the specified character sequence to this writer. * Appendable. * *

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() * * @throws IOException * If an I/O error occurs * * @since 1.5 */ public Writer append(CharSequence csq, int start, int end) throws IOException { 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 * * @throws IOException * If an I/O error occurs * * @since 1.5 */ public Writer append(char c) throws IOException { write(c); return this; } /** * Flush the stream. If the stream has saved any characters from the * various write() methods in a buffer, write them immediately to their * intended destination. Then, if that destination is another character or * byte stream, flush it. Thus one flush() invocation will flush all the * buffers in a chain of Writers and OutputStreams. *

* If the intended destination of this stream is an abstraction provided by * the underlying operating system, for example a file, then flushing the * stream guarantees only that bytes previously written to the stream are * passed to the operating system for writing; it does not guarantee that * they are actually written to a physical device such as a disk drive. * * @exception IOException If an I/O error occurs */ abstract public void flush() throws IOException; /** * Close the stream, flushing it first. Once a stream has been closed, * further write() or flush() invocations will cause an IOException to be * thrown. Closing a previously-closed stream, however, has no effect. * * @exception IOException If an I/O error occurs */ abstract public void close() throws IOException; }