Source Home >> Java Source 1.6.0 >> java.io.OutputStreamWriter V 0.09

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