View Javadoc
1   /*
2    * Copyright (c) 1996, 2013, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  
26  package java.io;
27  
28  import java.nio.charset.Charset;
29  import java.nio.charset.CharsetEncoder;
30  import sun.nio.cs.StreamEncoder;
31  
32  
33  /**
34   * An OutputStreamWriter is a bridge from character streams to byte streams:
35   * Characters written to it are encoded into bytes using a specified {@link
36   * java.nio.charset.Charset charset}.  The charset that it uses
37   * may be specified by name or may be given explicitly, or the platform's
38   * default charset may be accepted.
39   *
40   * <p> Each invocation of a write() method causes the encoding converter to be
41   * invoked on the given character(s).  The resulting bytes are accumulated in a
42   * buffer before being written to the underlying output stream.  The size of
43   * this buffer may be specified, but by default it is large enough for most
44   * purposes.  Note that the characters passed to the write() methods are not
45   * buffered.
46   *
47   * <p> For top efficiency, consider wrapping an OutputStreamWriter within a
48   * BufferedWriter so as to avoid frequent converter invocations.  For example:
49   *
50   * <pre>
51   * Writer out
52   *   = new BufferedWriter(new OutputStreamWriter(System.out));
53   * </pre>
54   *
55   * <p> A <i>surrogate pair</i> is a character represented by a sequence of two
56   * <tt>char</tt> values: A <i>high</i> surrogate in the range '&#92;uD800' to
57   * '&#92;uDBFF' followed by a <i>low</i> surrogate in the range '&#92;uDC00' to
58   * '&#92;uDFFF'.
59   *
60   * <p> A <i>malformed surrogate element</i> is a high surrogate that is not
61   * followed by a low surrogate or a low surrogate that is not preceded by a
62   * high surrogate.
63   *
64   * <p> This class always replaces malformed surrogate elements and unmappable
65   * character sequences with the charset's default <i>substitution sequence</i>.
66   * The {@linkplain java.nio.charset.CharsetEncoder} class should be used when more
67   * control over the encoding process is required.
68   *
69   * @see BufferedWriter
70   * @see OutputStream
71   * @see java.nio.charset.Charset
72   *
73   * @author      Mark Reinhold
74   * @since       JDK1.1
75   */
76  
77  public class OutputStreamWriter extends Writer {
78  
79      private final StreamEncoder se;
80  
81      /**
82       * Creates an OutputStreamWriter that uses the named charset.
83       *
84       * @param  out
85       *         An OutputStream
86       *
87       * @param  charsetName
88       *         The name of a supported
89       *         {@link java.nio.charset.Charset charset}
90       *
91       * @exception  UnsupportedEncodingException
92       *             If the named encoding is not supported
93       */
94      public OutputStreamWriter(OutputStream out, String charsetName)
95          throws UnsupportedEncodingException
96      {
97          super(out);
98          if (charsetName == null)
99              throw new NullPointerException("charsetName");
100         se = StreamEncoder.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, (String)null);
112         } catch (UnsupportedEncodingException e) {
113             throw new Error(e);
114         }
115     }
116 
117     /**
118      * Creates an OutputStreamWriter that uses the given charset.
119      *
120      * @param  out
121      *         An OutputStream
122      *
123      * @param  cs
124      *         A charset
125      *
126      * @since 1.4
127      * @spec JSR-51
128      */
129     public OutputStreamWriter(OutputStream out, Charset cs) {
130         super(out);
131         if (cs == null)
132             throw new NullPointerException("charset");
133         se = StreamEncoder.forOutputStreamWriter(out, this, cs);
134     }
135 
136     /**
137      * Creates an OutputStreamWriter that uses the given charset encoder.
138      *
139      * @param  out
140      *         An OutputStream
141      *
142      * @param  enc
143      *         A charset encoder
144      *
145      * @since 1.4
146      * @spec JSR-51
147      */
148     public OutputStreamWriter(OutputStream out, CharsetEncoder enc) {
149         super(out);
150         if (enc == null)
151             throw new NullPointerException("charset encoder");
152         se = StreamEncoder.forOutputStreamWriter(out, this, enc);
153     }
154 
155     /**
156      * Returns the name of the character encoding being used by this stream.
157      *
158      * <p> If the encoding has an historical name then that name is returned;
159      * otherwise the encoding's canonical name is returned.
160      *
161      * <p> If this instance was created with the {@link
162      * #OutputStreamWriter(OutputStream, String)} constructor then the returned
163      * name, being unique for the encoding, may differ from the name passed to
164      * the constructor.  This method may return <tt>null</tt> if the stream has
165      * been closed. </p>
166      *
167      * @return The historical name of this encoding, or possibly
168      *         <code>null</code> if the stream has been closed
169      *
170      * @see java.nio.charset.Charset
171      *
172      * @revised 1.4
173      * @spec JSR-51
174      */
175     public String getEncoding() {
176         return se.getEncoding();
177     }
178 
179     /**
180      * Flushes the output buffer to the underlying byte stream, without flushing
181      * the byte stream itself.  This method is non-private only so that it may
182      * be invoked by PrintStream.
183      */
184     void flushBuffer() throws IOException {
185         se.flushBuffer();
186     }
187 
188     /**
189      * Writes a single character.
190      *
191      * @exception  IOException  If an I/O error occurs
192      */
193     public void write(int c) throws IOException {
194         se.write(c);
195     }
196 
197     /**
198      * Writes a portion of an array of characters.
199      *
200      * @param  cbuf  Buffer of characters
201      * @param  off   Offset from which to start writing characters
202      * @param  len   Number of characters to write
203      *
204      * @exception  IOException  If an I/O error occurs
205      */
206     public void write(char cbuf[], int off, int len) throws IOException {
207         se.write(cbuf, off, len);
208     }
209 
210     /**
211      * Writes a portion of a string.
212      *
213      * @param  str  A String
214      * @param  off  Offset from which to start writing characters
215      * @param  len  Number of characters to write
216      *
217      * @exception  IOException  If an I/O error occurs
218      */
219     public void write(String str, int off, int len) throws IOException {
220         se.write(str, off, len);
221     }
222 
223     /**
224      * Flushes the stream.
225      *
226      * @exception  IOException  If an I/O error occurs
227      */
228     public void flush() throws IOException {
229         se.flush();
230     }
231 
232     public void close() throws IOException {
233         se.close();
234     }
235 }