KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > io > Writer


1 /*
2  * @(#)Writer.java 1.26 04/07/16
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7
8 package java.io;
9
10
11 /**
12  * Abstract class for writing to character streams. The only methods that a
13  * subclass must implement are write(char[], int, int), flush(), and close().
14  * Most subclasses, however, will override some of the methods defined here in
15  * order to provide higher efficiency, additional functionality, or both.
16  *
17  * @see Writer
18  * @see BufferedWriter
19  * @see CharArrayWriter
20  * @see FilterWriter
21  * @see OutputStreamWriter
22  * @see FileWriter
23  * @see PipedWriter
24  * @see PrintWriter
25  * @see StringWriter
26  * @see Reader
27  *
28  * @version 1.26, 04/07/16
29  * @author Mark Reinhold
30  * @since JDK1.1
31  */
32
33 public abstract class Writer implements Appendable JavaDoc, Closeable JavaDoc, Flushable JavaDoc {
34
35     /**
36      * Temporary buffer used to hold writes of strings and single characters
37      */
38     private char[] writeBuffer;
39
40     /**
41      * Size of writeBuffer, must be >= 1
42      */
43     private final int writeBufferSize = 1024;
44
45     /**
46      * The object used to synchronize operations on this stream. For
47      * efficiency, a character-stream object may use an object other than
48      * itself to protect critical sections. A subclass should therefore use
49      * the object in this field rather than <tt>this</tt> or a synchronized
50      * method.
51      */
52     protected Object JavaDoc lock;
53
54     /**
55      * Create a new character-stream writer whose critical sections will
56      * synchronize on the writer itself.
57      */
58     protected Writer() {
59     this.lock = this;
60     }
61
62     /**
63      * Create a new character-stream writer whose critical sections will
64      * synchronize on the given object.
65      *
66      * @param lock Object to synchronize on.
67      */
68     protected Writer(Object JavaDoc lock) {
69     if (lock == null) {
70         throw new NullPointerException JavaDoc();
71     }
72     this.lock = lock;
73     }
74
75     /**
76      * Write a single character. The character to be written is contained in
77      * the 16 low-order bits of the given integer value; the 16 high-order bits
78      * are ignored.
79      *
80      * <p> Subclasses that intend to support efficient single-character output
81      * should override this method.
82      *
83      * @param c int specifying a character to be written.
84      * @exception IOException If an I/O error occurs
85      */
86     public void write(int c) throws IOException JavaDoc {
87     synchronized (lock) {
88         if (writeBuffer == null){
89         writeBuffer = new char[writeBufferSize];
90         }
91         writeBuffer[0] = (char) c;
92         write(writeBuffer, 0, 1);
93     }
94     }
95
96     /**
97      * Write an array of characters.
98      *
99      * @param cbuf Array of characters to be written
100      *
101      * @exception IOException If an I/O error occurs
102      */
103     public void write(char cbuf[]) throws IOException JavaDoc {
104     write(cbuf, 0, cbuf.length);
105     }
106
107     /**
108      * Write a portion of an array of characters.
109      *
110      * @param cbuf Array of characters
111      * @param off Offset from which to start writing characters
112      * @param len Number of characters to write
113      *
114      * @exception IOException If an I/O error occurs
115      */
116     abstract public void write(char cbuf[], int off, int len) throws IOException JavaDoc;
117
118     /**
119      * Write a string.
120      *
121      * @param str String to be written
122      *
123      * @exception IOException If an I/O error occurs
124      */
125     public void write(String JavaDoc str) throws IOException JavaDoc {
126     write(str, 0, str.length());
127     }
128
129     /**
130      * Write a portion of a string.
131      *
132      * @param str A String
133      * @param off Offset from which to start writing characters
134      * @param len Number of characters to write
135      *
136      * @exception IOException If an I/O error occurs
137      */
138     public void write(String JavaDoc str, int off, int len) throws IOException JavaDoc {
139     synchronized (lock) {
140         char cbuf[];
141         if (len <= writeBufferSize) {
142         if (writeBuffer == null) {
143             writeBuffer = new char[writeBufferSize];
144         }
145         cbuf = writeBuffer;
146         } else { // Don't permanently allocate very large buffers.
147 cbuf = new char[len];
148         }
149         str.getChars(off, (off + len), cbuf, 0);
150         write(cbuf, 0, len);
151     }
152     }
153
154     /**
155      * Appends the specified character sequence to this writer.
156      *
157      * <p> An invocation of this method of the form <tt>out.append(csq)</tt>
158      * behaves in exactly the same way as the invocation
159      *
160      * <pre>
161      * out.write(csq.toString()) </pre>
162      *
163      * <p> Depending on the specification of <tt>toString</tt> for the
164      * character sequence <tt>csq</tt>, the entire sequence may not be
165      * appended. For instance, invoking the <tt>toString</tt> method of a
166      * character buffer will return a subsequence whose content depends upon
167      * the buffer's position and limit.
168      *
169      * @param csq
170      * The character sequence to append. If <tt>csq</tt> is
171      * <tt>null</tt>, then the four characters <tt>"null"</tt> are
172      * appended to this writer.
173      *
174      * @return This writer
175      *
176      * @throws IOException
177      * If an I/O error occurs
178      *
179      * @since 1.5
180      */
181     public Writer JavaDoc append(CharSequence JavaDoc csq) throws IOException JavaDoc {
182     if (csq == null)
183         write("null");
184     else
185         write(csq.toString());
186         return this;
187     }
188
189     /**
190      * Appends a subsequence of the specified character sequence to this writer.
191      * <tt>Appendable</tt>.
192      *
193      * <p> An invocation of this method of the form <tt>out.append(csq, start,
194      * end)</tt> when <tt>csq</tt> is not <tt>null</tt> behaves in exactly the
195      * same way as the invocation
196      *
197      * <pre>
198      * out.write(csq.subSequence(start, end).toString()) </pre>
199      *
200      * @param csq
201      * The character sequence from which a subsequence will be
202      * appended. If <tt>csq</tt> is <tt>null</tt>, then characters
203      * will be appended as if <tt>csq</tt> contained the four
204      * characters <tt>"null"</tt>.
205      *
206      * @param start
207      * The index of the first character in the subsequence
208      *
209      * @param end
210      * The index of the character following the last character in the
211      * subsequence
212      *
213      * @return This writer
214      *
215      * @throws IndexOutOfBoundsException
216      * If <tt>start</tt> or <tt>end</tt> are negative, <tt>start</tt>
217      * is greater than <tt>end</tt>, or <tt>end</tt> is greater than
218      * <tt>csq.length()</tt>
219      *
220      * @throws IOException
221      * If an I/O error occurs
222      *
223      * @since 1.5
224      */
225     public Writer JavaDoc append(CharSequence JavaDoc csq, int start, int end) throws IOException JavaDoc {
226     CharSequence JavaDoc cs = (csq == null ? "null" : csq);
227     write(cs.subSequence(start, end).toString());
228     return this;
229     }
230
231     /**
232      * Appends the specified character to this writer.
233      *
234      * <p> An invocation of this method of the form <tt>out.append(c)</tt>
235      * behaves in exactly the same way as the invocation
236      *
237      * <pre>
238      * out.write(c) </pre>
239      *
240      * @param c
241      * The 16-bit character to append
242      *
243      * @return This writer
244      *
245      * @throws IOException
246      * If an I/O error occurs
247      *
248      * @since 1.5
249      */
250     public Writer JavaDoc append(char c) throws IOException JavaDoc {
251     write(c);
252     return this;
253     }
254
255     /**
256      * Flush the stream. If the stream has saved any characters from the
257      * various write() methods in a buffer, write them immediately to their
258      * intended destination. Then, if that destination is another character or
259      * byte stream, flush it. Thus one flush() invocation will flush all the
260      * buffers in a chain of Writers and OutputStreams.
261      * <p>
262      * If the intended destination of this stream is an abstraction provided by
263      * the underlying operating system, for example a file, then flushing the
264      * stream guarantees only that bytes previously written to the stream are
265      * passed to the operating system for writing; it does not guarantee that
266      * they are actually written to a physical device such as a disk drive.
267      *
268      * @exception IOException If an I/O error occurs
269      */
270     abstract public void flush() throws IOException JavaDoc;
271
272     /**
273      * Close the stream, flushing it first. Once a stream has been closed,
274      * further write() or flush() invocations will cause an IOException to be
275      * thrown. Closing a previously-closed stream, however, has no effect.
276      *
277      * @exception IOException If an I/O error occurs
278      */
279     abstract public void close() throws IOException JavaDoc;
280
281 }
282
Popular Tags