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 '\uD800' to 57 * '\uDBFF' followed by a <i>low</i> surrogate in the range '\uDC00' to 58 * '\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 */ OutputStreamWriter(OutputStream out, String charsetName)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 */ OutputStreamWriter(OutputStream out)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 */ OutputStreamWriter(OutputStream out, Charset cs)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 */ OutputStreamWriter(OutputStream out, CharsetEncoder enc)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 */ getEncoding()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 */ flushBuffer()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 */ write(int c)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 */ write(char cbuf[], int off, int len)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 */ write(String str, int off, int len)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 */ flush()228 public void flush() throws IOException { 229 se.flush(); 230 } 231 close()232 public void close() throws IOException { 233 se.close(); 234 } 235 } 236