jaroslav@1258: /* jaroslav@1258: * Copyright (c) 1996, 2005, Oracle and/or its affiliates. All rights reserved. jaroslav@1258: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. jaroslav@1258: * jaroslav@1258: * This code is free software; you can redistribute it and/or modify it jaroslav@1258: * under the terms of the GNU General Public License version 2 only, as jaroslav@1258: * published by the Free Software Foundation. Oracle designates this jaroslav@1258: * particular file as subject to the "Classpath" exception as provided jaroslav@1258: * by Oracle in the LICENSE file that accompanied this code. jaroslav@1258: * jaroslav@1258: * This code is distributed in the hope that it will be useful, but WITHOUT jaroslav@1258: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or jaroslav@1258: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License jaroslav@1258: * version 2 for more details (a copy is included in the LICENSE file that jaroslav@1258: * accompanied this code). jaroslav@1258: * jaroslav@1258: * You should have received a copy of the GNU General Public License version jaroslav@1258: * 2 along with this work; if not, write to the Free Software Foundation, jaroslav@1258: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. jaroslav@1258: * jaroslav@1258: * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA jaroslav@1258: * or visit www.oracle.com if you need additional information or have any jaroslav@1258: * questions. jaroslav@1258: */ jaroslav@1258: jaroslav@1258: package java.io; jaroslav@1258: jaroslav@1258: jaroslav@1258: /** jaroslav@1258: * Abstract class for writing to character streams. The only methods that a jaroslav@1258: * subclass must implement are write(char[], int, int), flush(), and close(). jaroslav@1258: * Most subclasses, however, will override some of the methods defined here in jaroslav@1258: * order to provide higher efficiency, additional functionality, or both. jaroslav@1258: * jaroslav@1258: * @see Writer jaroslav@1258: * @see BufferedWriter jaroslav@1258: * @see CharArrayWriter jaroslav@1258: * @see FilterWriter jaroslav@1258: * @see OutputStreamWriter jaroslav@1258: * @see FileWriter jaroslav@1258: * @see PipedWriter jaroslav@1258: * @see PrintWriter jaroslav@1258: * @see StringWriter jaroslav@1258: * @see Reader jaroslav@1258: * jaroslav@1258: * @author Mark Reinhold jaroslav@1258: * @since JDK1.1 jaroslav@1258: */ jaroslav@1258: jaroslav@1258: public abstract class Writer implements Appendable, Closeable, Flushable { jaroslav@1258: jaroslav@1258: /** jaroslav@1258: * Temporary buffer used to hold writes of strings and single characters jaroslav@1258: */ jaroslav@1258: private char[] writeBuffer; jaroslav@1258: jaroslav@1258: /** jaroslav@1258: * Size of writeBuffer, must be >= 1 jaroslav@1258: */ jaroslav@1258: private final int writeBufferSize = 1024; jaroslav@1258: jaroslav@1258: /** jaroslav@1258: * The object used to synchronize operations on this stream. For jaroslav@1258: * efficiency, a character-stream object may use an object other than jaroslav@1258: * itself to protect critical sections. A subclass should therefore use jaroslav@1258: * the object in this field rather than this or a synchronized jaroslav@1258: * method. jaroslav@1258: */ jaroslav@1258: protected Object lock; jaroslav@1258: jaroslav@1258: /** jaroslav@1258: * Creates a new character-stream writer whose critical sections will jaroslav@1258: * synchronize on the writer itself. jaroslav@1258: */ jaroslav@1258: protected Writer() { jaroslav@1258: this.lock = this; jaroslav@1258: } jaroslav@1258: jaroslav@1258: /** jaroslav@1258: * Creates a new character-stream writer whose critical sections will jaroslav@1258: * synchronize on the given object. jaroslav@1258: * jaroslav@1258: * @param lock jaroslav@1258: * Object to synchronize on jaroslav@1258: */ jaroslav@1258: protected Writer(Object lock) { jaroslav@1258: if (lock == null) { jaroslav@1258: throw new NullPointerException(); jaroslav@1258: } jaroslav@1258: this.lock = lock; jaroslav@1258: } jaroslav@1258: jaroslav@1258: /** jaroslav@1258: * Writes a single character. The character to be written is contained in jaroslav@1258: * the 16 low-order bits of the given integer value; the 16 high-order bits jaroslav@1258: * are ignored. jaroslav@1258: * jaroslav@1258: *

Subclasses that intend to support efficient single-character output jaroslav@1258: * should override this method. jaroslav@1258: * jaroslav@1258: * @param c jaroslav@1258: * int specifying a character to be written jaroslav@1258: * jaroslav@1258: * @throws IOException jaroslav@1258: * If an I/O error occurs jaroslav@1258: */ jaroslav@1258: public void write(int c) throws IOException { jaroslav@1258: synchronized (lock) { jaroslav@1258: if (writeBuffer == null){ jaroslav@1258: writeBuffer = new char[writeBufferSize]; jaroslav@1258: } jaroslav@1258: writeBuffer[0] = (char) c; jaroslav@1258: write(writeBuffer, 0, 1); jaroslav@1258: } jaroslav@1258: } jaroslav@1258: jaroslav@1258: /** jaroslav@1258: * Writes an array of characters. jaroslav@1258: * jaroslav@1258: * @param cbuf jaroslav@1258: * Array of characters to be written jaroslav@1258: * jaroslav@1258: * @throws IOException jaroslav@1258: * If an I/O error occurs jaroslav@1258: */ jaroslav@1258: public void write(char cbuf[]) throws IOException { jaroslav@1258: write(cbuf, 0, cbuf.length); jaroslav@1258: } jaroslav@1258: jaroslav@1258: /** jaroslav@1258: * Writes a portion of an array of characters. jaroslav@1258: * jaroslav@1258: * @param cbuf jaroslav@1258: * Array of characters jaroslav@1258: * jaroslav@1258: * @param off jaroslav@1258: * Offset from which to start writing characters jaroslav@1258: * jaroslav@1258: * @param len jaroslav@1258: * Number of characters to write jaroslav@1258: * jaroslav@1258: * @throws IOException jaroslav@1258: * If an I/O error occurs jaroslav@1258: */ jaroslav@1258: abstract public void write(char cbuf[], int off, int len) throws IOException; jaroslav@1258: jaroslav@1258: /** jaroslav@1258: * Writes a string. jaroslav@1258: * jaroslav@1258: * @param str jaroslav@1258: * String to be written jaroslav@1258: * jaroslav@1258: * @throws IOException jaroslav@1258: * If an I/O error occurs jaroslav@1258: */ jaroslav@1258: public void write(String str) throws IOException { jaroslav@1258: write(str, 0, str.length()); jaroslav@1258: } jaroslav@1258: jaroslav@1258: /** jaroslav@1258: * Writes a portion of a string. jaroslav@1258: * jaroslav@1258: * @param str jaroslav@1258: * A String jaroslav@1258: * jaroslav@1258: * @param off jaroslav@1258: * Offset from which to start writing characters jaroslav@1258: * jaroslav@1258: * @param len jaroslav@1258: * Number of characters to write jaroslav@1258: * jaroslav@1258: * @throws IndexOutOfBoundsException jaroslav@1258: * If off is negative, or len is negative, jaroslav@1258: * or off+len is negative or greater than the length jaroslav@1258: * of the given string jaroslav@1258: * jaroslav@1258: * @throws IOException jaroslav@1258: * If an I/O error occurs jaroslav@1258: */ jaroslav@1258: public void write(String str, int off, int len) throws IOException { jaroslav@1258: synchronized (lock) { jaroslav@1258: char cbuf[]; jaroslav@1258: if (len <= writeBufferSize) { jaroslav@1258: if (writeBuffer == null) { jaroslav@1258: writeBuffer = new char[writeBufferSize]; jaroslav@1258: } jaroslav@1258: cbuf = writeBuffer; jaroslav@1258: } else { // Don't permanently allocate very large buffers. jaroslav@1258: cbuf = new char[len]; jaroslav@1258: } jaroslav@1258: str.getChars(off, (off + len), cbuf, 0); jaroslav@1258: write(cbuf, 0, len); jaroslav@1258: } jaroslav@1258: } jaroslav@1258: jaroslav@1258: /** jaroslav@1258: * Appends the specified character sequence to this writer. jaroslav@1258: * jaroslav@1258: *

An invocation of this method of the form out.append(csq) jaroslav@1258: * behaves in exactly the same way as the invocation jaroslav@1258: * jaroslav@1258: * 

jaroslav@1258:      *     out.write(csq.toString())
jaroslav@1258: * jaroslav@1258: *

Depending on the specification of toString for the jaroslav@1258: * character sequence csq, the entire sequence may not be jaroslav@1258: * appended. For instance, invoking the toString method of a jaroslav@1258: * character buffer will return a subsequence whose content depends upon jaroslav@1258: * the buffer's position and limit. jaroslav@1258: * jaroslav@1258: * @param csq jaroslav@1258: * The character sequence to append. If csq is jaroslav@1258: * null, then the four characters "null" are jaroslav@1258: * appended to this writer. jaroslav@1258: * jaroslav@1258: * @return This writer jaroslav@1258: * jaroslav@1258: * @throws IOException jaroslav@1258: * If an I/O error occurs jaroslav@1258: * jaroslav@1258: * @since 1.5 jaroslav@1258: */ jaroslav@1258: public Writer append(CharSequence csq) throws IOException { jaroslav@1258: if (csq == null) jaroslav@1258: write("null"); jaroslav@1258: else jaroslav@1258: write(csq.toString()); jaroslav@1258: return this; jaroslav@1258: } jaroslav@1258: jaroslav@1258: /** jaroslav@1258: * Appends a subsequence of the specified character sequence to this writer. jaroslav@1258: * Appendable. jaroslav@1258: * jaroslav@1258: *

An invocation of this method of the form out.append(csq, start, jaroslav@1258: * end) when csq is not null behaves in exactly the jaroslav@1258: * same way as the invocation jaroslav@1258: * jaroslav@1258: * 

jaroslav@1258:      *     out.write(csq.subSequence(start, end).toString())
jaroslav@1258: * jaroslav@1258: * @param csq jaroslav@1258: * The character sequence from which a subsequence will be jaroslav@1258: * appended. If csq is null, then characters jaroslav@1258: * will be appended as if csq contained the four jaroslav@1258: * characters "null". jaroslav@1258: * jaroslav@1258: * @param start jaroslav@1258: * The index of the first character in the subsequence jaroslav@1258: * jaroslav@1258: * @param end jaroslav@1258: * The index of the character following the last character in the jaroslav@1258: * subsequence jaroslav@1258: * jaroslav@1258: * @return This writer jaroslav@1258: * jaroslav@1258: * @throws IndexOutOfBoundsException jaroslav@1258: * If start or end are negative, start jaroslav@1258: * is greater than end, or end is greater than jaroslav@1258: * csq.length() jaroslav@1258: * jaroslav@1258: * @throws IOException jaroslav@1258: * If an I/O error occurs jaroslav@1258: * jaroslav@1258: * @since 1.5 jaroslav@1258: */ jaroslav@1258: public Writer append(CharSequence csq, int start, int end) throws IOException { jaroslav@1258: CharSequence cs = (csq == null ? "null" : csq); jaroslav@1258: write(cs.subSequence(start, end).toString()); jaroslav@1258: return this; jaroslav@1258: } jaroslav@1258: jaroslav@1258: /** jaroslav@1258: * Appends the specified character to this writer. jaroslav@1258: * jaroslav@1258: *

An invocation of this method of the form out.append(c) jaroslav@1258: * behaves in exactly the same way as the invocation jaroslav@1258: * jaroslav@1258: * 

jaroslav@1258:      *     out.write(c)
jaroslav@1258: * jaroslav@1258: * @param c jaroslav@1258: * The 16-bit character to append jaroslav@1258: * jaroslav@1258: * @return This writer jaroslav@1258: * jaroslav@1258: * @throws IOException jaroslav@1258: * If an I/O error occurs jaroslav@1258: * jaroslav@1258: * @since 1.5 jaroslav@1258: */ jaroslav@1258: public Writer append(char c) throws IOException { jaroslav@1258: write(c); jaroslav@1258: return this; jaroslav@1258: } jaroslav@1258: jaroslav@1258: /** jaroslav@1258: * Flushes the stream. If the stream has saved any characters from the jaroslav@1258: * various write() methods in a buffer, write them immediately to their jaroslav@1258: * intended destination. Then, if that destination is another character or jaroslav@1258: * byte stream, flush it. Thus one flush() invocation will flush all the jaroslav@1258: * buffers in a chain of Writers and OutputStreams. jaroslav@1258: * jaroslav@1258: *

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