001: /*
002: *
003: *
004: * Copyright 1990-2007 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: */
026:
027: package java.io;
028:
029: /**
030: * Abstract class for writing to character streams. The only methods that a
031: * subclass must implement are write(char[], int, int), flush(), and close().
032: * Most subclasses, however, will override some of the methods defined here in
033: * order to provide higher efficiency, additional functionality, or both.
034: *
035: * @version 12/17/01 (CLDC 1.1)
036: * @since JDK1.1, CLDC 1.0
037: * @see java.io.OutputStreamWriter
038: * @see java.io.Reader
039: */
040:
041: public abstract class Writer {
042:
043: /**
044: * Temporary buffer used to hold writes of strings and single characters
045: */
046: private char[] writeBuffer;
047:
048: /**
049: * Size of writeBuffer, must be >= 1
050: */
051: private final int writeBufferSize = 1024;
052:
053: /**
054: * The object used to synchronize operations on this stream. For
055: * efficiency, a character-stream object may use an object other than
056: * itself to protect critical sections. A subclass should therefore use
057: * the object in this field rather than <tt>this</tt> or a synchronized
058: * method.
059: */
060: protected Object lock;
061:
062: /**
063: * Create a new character-stream writer whose critical sections will
064: * synchronize on the writer itself.
065: */
066: protected Writer() {
067: this .lock = this ;
068: }
069:
070: /**
071: * Create a new character-stream writer whose critical sections will
072: * synchronize on the given object.
073: *
074: * @param lock Object to synchronize on.
075: */
076: protected Writer(Object lock) {
077: if (lock == null) {
078: throw new NullPointerException();
079: }
080: this .lock = lock;
081: }
082:
083: /**
084: * Write a single character. The character to be written is contained in
085: * the 16 low-order bits of the given integer value; the 16 high-order bits
086: * are ignored.
087: *
088: * <p> Subclasses that intend to support efficient single-character output
089: * should override this method.
090: *
091: * @param c int specifying a character to be written.
092: * @exception IOException If an I/O error occurs
093: */
094: public void write(int c) throws IOException {
095: synchronized (lock) {
096: if (writeBuffer == null) {
097: writeBuffer = new char[writeBufferSize];
098: }
099: writeBuffer[0] = (char) c;
100: write(writeBuffer, 0, 1);
101: }
102: }
103:
104: /**
105: * Write an array of characters.
106: *
107: * @param cbuf Array of characters to be written
108: *
109: * @exception IOException If an I/O error occurs
110: */
111: public void write(char cbuf[]) throws IOException {
112: write(cbuf, 0, cbuf.length);
113: }
114:
115: /**
116: * Write a portion of an array of characters.
117: *
118: * @param cbuf Array of characters
119: * @param off Offset from which to start writing characters
120: * @param len Number of characters to write
121: *
122: * @exception IOException If an I/O error occurs
123: */
124: abstract public void write(char cbuf[], int off, int len)
125: throws IOException;
126:
127: /**
128: * Write a string.
129: *
130: * @param str String to be written
131: *
132: * @exception IOException If an I/O error occurs
133: */
134: public void write(String str) throws IOException {
135: write(str, 0, str.length());
136: }
137:
138: /**
139: * Write a portion of a string.
140: *
141: * @param str A String
142: * @param off Offset from which to start writing characters
143: * @param len Number of characters to write
144: *
145: * @exception IOException If an I/O error occurs
146: */
147: public void write(String str, int off, int len) throws IOException {
148: synchronized (lock) {
149: char cbuf[];
150: if (len <= writeBufferSize) {
151: if (writeBuffer == null) {
152: writeBuffer = new char[writeBufferSize];
153: }
154: cbuf = writeBuffer;
155: } else { // Don't permanently allocate very large buffers.
156: cbuf = new char[len];
157: }
158: str.getChars(off, (off + len), cbuf, 0);
159: write(cbuf, 0, len);
160: }
161: }
162:
163: /**
164: * Flush the stream. If the stream has saved any characters from the
165: * various write() methods in a buffer, write them immediately to their
166: * intended destination. Then, if that destination is another character or
167: * byte stream, flush it. Thus one flush() invocation will flush all the
168: * buffers in a chain of Writers and OutputStreams.
169: *
170: * @exception IOException If an I/O error occurs
171: */
172: abstract public void flush() throws IOException;
173:
174: /**
175: * Close the stream, flushing it first. Once a stream has been closed,
176: * further write() or flush() invocations will cause an IOException to be
177: * thrown. Closing a previously-closed stream, however, has no effect.
178: *
179: * @exception IOException If an I/O error occurs
180: */
181: abstract public void close() throws IOException;
182:
183: }
|