001: /*
002: * Copyright 1996-2006 Sun Microsystems, Inc. All Rights Reserved.
003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004: *
005: * This code is free software; you can redistribute it and/or modify it
006: * under the terms of the GNU General Public License version 2 only, as
007: * published by the Free Software Foundation. Sun designates this
008: * particular file as subject to the "Classpath" exception as provided
009: * by Sun in the LICENSE file that accompanied this code.
010: *
011: * This code is distributed in the hope that it will be useful, but WITHOUT
012: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014: * version 2 for more details (a copy is included in the LICENSE file that
015: * accompanied this code).
016: *
017: * You should have received a copy of the GNU General Public License version
018: * 2 along with this work; if not, write to the Free Software Foundation,
019: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022: * CA 95054 USA or visit www.sun.com if you need additional information or
023: * have any questions.
024: */
025:
026: package java.io;
027:
028: import java.nio.charset.Charset;
029: import java.nio.charset.CharsetEncoder;
030: import sun.nio.cs.StreamEncoder;
031:
032: /**
033: * An OutputStreamWriter is a bridge from character streams to byte streams:
034: * Characters written to it are encoded into bytes using a specified {@link
035: * java.nio.charset.Charset <code>charset</code>}. The charset that it uses
036: * may be specified by name or may be given explicitly, or the platform's
037: * default charset may be accepted.
038: *
039: * <p> Each invocation of a write() method causes the encoding converter to be
040: * invoked on the given character(s). The resulting bytes are accumulated in a
041: * buffer before being written to the underlying output stream. The size of
042: * this buffer may be specified, but by default it is large enough for most
043: * purposes. Note that the characters passed to the write() methods are not
044: * buffered.
045: *
046: * <p> For top efficiency, consider wrapping an OutputStreamWriter within a
047: * BufferedWriter so as to avoid frequent converter invocations. For example:
048: *
049: * <pre>
050: * Writer out
051: * = new BufferedWriter(new OutputStreamWriter(System.out));
052: * </pre>
053: *
054: * <p> A <i>surrogate pair</i> is a character represented by a sequence of two
055: * <tt>char</tt> values: A <i>high</i> surrogate in the range '\uD800' to
056: * '\uDBFF' followed by a <i>low</i> surrogate in the range '\uDC00' to
057: * '\uDFFF'.
058: *
059: * <p> A <i>malformed surrogate element</i> is a high surrogate that is not
060: * followed by a low surrogate or a low surrogate that is not preceded by a
061: * high surrogate.
062: *
063: * <p> This class always replaces malformed surrogate elements and unmappable
064: * character sequences with the charset's default <i>substitution sequence</i>.
065: * The {@linkplain java.nio.charset.CharsetEncoder} class should be used when more
066: * control over the encoding process is required.
067: *
068: * @see BufferedWriter
069: * @see OutputStream
070: * @see java.nio.charset.Charset
071: *
072: * @version 1.56, 07/05/05
073: * @author Mark Reinhold
074: * @since JDK1.1
075: */
076:
077: public class OutputStreamWriter extends Writer {
078:
079: private final StreamEncoder se;
080:
081: /**
082: * Creates an OutputStreamWriter that uses the named charset.
083: *
084: * @param out
085: * An OutputStream
086: *
087: * @param charsetName
088: * The name of a supported
089: * {@link java.nio.charset.Charset </code>charset<code>}
090: *
091: * @exception UnsupportedEncodingException
092: * If the named encoding is not supported
093: */
094: public OutputStreamWriter(OutputStream out, String charsetName)
095: throws UnsupportedEncodingException {
096: super(out);
097: if (charsetName == null)
098: throw new NullPointerException("charsetName");
099: se = StreamEncoder
100: .forOutputStreamWriter(out, this, charsetName);
101: }
102:
103: /**
104: * Creates an OutputStreamWriter that uses the default character encoding.
105: *
106: * @param out An OutputStream
107: */
108: public OutputStreamWriter(OutputStream out) {
109: super(out);
110: try {
111: se = StreamEncoder.forOutputStreamWriter(out, this,
112: (String) null);
113: } catch (UnsupportedEncodingException e) {
114: throw new Error(e);
115: }
116: }
117:
118: /**
119: * Creates an OutputStreamWriter that uses the given charset. </p>
120: *
121: * @param out
122: * An OutputStream
123: *
124: * @param cs
125: * A charset
126: *
127: * @since 1.4
128: * @spec JSR-51
129: */
130: public OutputStreamWriter(OutputStream out, Charset cs) {
131: super(out);
132: if (cs == null)
133: throw new NullPointerException("charset");
134: se = StreamEncoder.forOutputStreamWriter(out, this, cs);
135: }
136:
137: /**
138: * Creates an OutputStreamWriter that uses the given charset encoder. </p>
139: *
140: * @param out
141: * An OutputStream
142: *
143: * @param enc
144: * A charset encoder
145: *
146: * @since 1.4
147: * @spec JSR-51
148: */
149: public OutputStreamWriter(OutputStream out, CharsetEncoder enc) {
150: super(out);
151: if (enc == null)
152: throw new NullPointerException("charset encoder");
153: se = StreamEncoder.forOutputStreamWriter(out, this, enc);
154: }
155:
156: /**
157: * Returns the name of the character encoding being used by this stream.
158: *
159: * <p> If the encoding has an historical name then that name is returned;
160: * otherwise the encoding's canonical name is returned.
161: *
162: * <p> If this instance was created with the {@link
163: * #OutputStreamWriter(OutputStream, String)} constructor then the returned
164: * name, being unique for the encoding, may differ from the name passed to
165: * the constructor. This method may return <tt>null</tt> if the stream has
166: * been closed. </p>
167: *
168: * @return The historical name of this encoding, or possibly
169: * <code>null</code> if the stream has been closed
170: *
171: * @see java.nio.charset.Charset
172: *
173: * @revised 1.4
174: * @spec JSR-51
175: */
176: public String getEncoding() {
177: return se.getEncoding();
178: }
179:
180: /**
181: * Flushes the output buffer to the underlying byte stream, without flushing
182: * the byte stream itself. This method is non-private only so that it may
183: * be invoked by PrintStream.
184: */
185: void flushBuffer() throws IOException {
186: se.flushBuffer();
187: }
188:
189: /**
190: * Writes a single character.
191: *
192: * @exception IOException If an I/O error occurs
193: */
194: public void write(int c) throws IOException {
195: se.write(c);
196: }
197:
198: /**
199: * Writes a portion of an array of characters.
200: *
201: * @param cbuf Buffer of characters
202: * @param off Offset from which to start writing characters
203: * @param len Number of characters to write
204: *
205: * @exception IOException If an I/O error occurs
206: */
207: public void write(char cbuf[], int off, int len) throws IOException {
208: se.write(cbuf, off, len);
209: }
210:
211: /**
212: * Writes a portion of a string.
213: *
214: * @param str A String
215: * @param off Offset from which to start writing characters
216: * @param len Number of characters to write
217: *
218: * @exception IOException If an I/O error occurs
219: */
220: public void write(String str, int off, int len) throws IOException {
221: se.write(str, off, len);
222: }
223:
224: /**
225: * Flushes the stream.
226: *
227: * @exception IOException If an I/O error occurs
228: */
229: public void flush() throws IOException {
230: se.flush();
231: }
232:
233: public void close() throws IOException {
234: se.close();
235: }
236: }
| 