OutputStreamWriter


1   /*
2    * @(#)OutputStreamWriter.java  1.47 04/01/12
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  import java.nio.charset.Charset  ;
11  import java.nio.charset.CharsetEncoder  ;
12  import sun.nio.cs.StreamEncoder;
13  
14  
15  /**
16   * An OutputStreamWriter is a bridge from character streams to byte streams:
17   * Characters written to it are encoded into bytes using a specified {@link
18   * java.nio.charset.Charset <code>charset</code>}.  The charset that it uses
19   * may be specified by name or may be given explicitly, or the platform's
20   * default charset may be accepted.
21   *
22   * <p> Each invocation of a write() method causes the encoding converter to be
23   * invoked on the given character(s).  The resulting bytes are accumulated in a
24   * buffer before being written to the underlying output stream.  The size of
25   * this buffer may be specified, but by default it is large enough for most
26   * purposes.  Note that the characters passed to the write() methods are not
27   * buffered.
28   *
29   * <p> For top efficiency, consider wrapping an OutputStreamWriter within a
30   * BufferedWriter so as to avoid frequent converter invocations.  For example:
31   *
32   * <pre>
33   * Writer out
34   *   = new BufferedWriter(new OutputStreamWriter(System.out));
35   * </pre>
36   *
37   * <p> A <i>surrogate pair</i> is a character represented by a sequence of two
38   * <tt>char</tt> values: A <i>high</i> surrogate in the range '&#92;uD800' to
39   * '&#92;uDBFF' followed by a <i>low</i> surrogate in the range '&#92;uDC00' to
40   * '&#92;uDFFF'.  If the character represented by a surrogate pair cannot be
41   * encoded by a given charset then a charset-dependent <i>substitution
42   * sequence</i> is written to the output stream.
43   *
44   * <p> A <i>malformed surrogate element</i> is a high surrogate that is not
45   * followed by a low surrogate or a low surrogate that is not preceded by a
46   * high surrogate.  It is illegal to attempt to write a character stream
47   * containing malformed surrogate elements.  The behavior of an instance of
48   * this class when a malformed surrogate element is written is not specified.
49   *
50   * @see BufferedWriter
51   * @see OutputStream
52   * @see java.nio.charset.Charset
53   *
54   * @version     1.47, 04/01/12
55   * @author  Mark Reinhold
56   * @since   JDK1.1
57   */
58  
59  public class OutputStreamWriter extends Writer   {
60  
61      private final StreamEncoder se;
62  
63      /**
64       * Create an OutputStreamWriter that uses the named charset.
65       *
66       * @param  out
67       *         An OutputStream
68       *
69       * @param  charsetName
70       *         The name of a supported
71       *         {@link java.nio.charset.Charset </code>charset<code>}
72       *
73       * @exception  UnsupportedEncodingException
74       *             If the named encoding is not supported
75       */
76      public OutputStreamWriter(OutputStream   out, String   charsetName)
77      throws UnsupportedEncodingException  
78      {
79      super(out);
80      if (charsetName == null)
81          throw new NullPointerException  ("charsetName");
82      se = StreamEncoder.forOutputStreamWriter(out, this, charsetName);
83      }
84  
85      /**
86       * Create an OutputStreamWriter that uses the default character encoding.
87       *
88       * @param  out  An OutputStream
89       */
90      public OutputStreamWriter(OutputStream   out) {
91      super(out);
92      try {
93          se = StreamEncoder.forOutputStreamWriter(out, this, (String  )null);
94      } catch (UnsupportedEncodingException   e) {
95          throw new Error  (e);
96          }
97      }
98  
99      /**
100      * Create an OutputStreamWriter that uses the given charset. </p>
101      *
102      * @param  out
103      *         An OutputStream
104      *
105      * @param  cs
106      *         A charset
107      *
108      * @since 1.4
109      * @spec JSR-51
110      */
111     public OutputStreamWriter(OutputStream   out, Charset   cs) {
112     super(out);
113     if (cs == null)
114         throw new NullPointerException  ("charset");
115     se = StreamEncoder.forOutputStreamWriter(out, this, cs);
116     }
117 
118     /**
119      * Create an OutputStreamWriter that uses the given charset encoder.  </p>
120      *
121      * @param  out
122      *         An OutputStream
123      *
124      * @param  enc
125      *         A charset encoder
126      *
127      * @since 1.4
128      * @spec JSR-51
129      */
130     public OutputStreamWriter(OutputStream   out, CharsetEncoder   enc) {
131     super(out);
132     if (enc == null)
133         throw new NullPointerException  ("charset encoder");
134     se = StreamEncoder.forOutputStreamWriter(out, this, enc);
135     }
136 
137     /**
138      * Return the name of the character encoding being used by this stream.
139      *
140      * <p> If the encoding has an historical name then that name is returned;
141      * otherwise the encoding's canonical name is returned.
142      *
143      * <p> If this instance was created with the {@link
144      * #OutputStreamWriter(OutputStream, String)} constructor then the returned
145      * name, being unique for the encoding, may differ from the name passed to
146      * the constructor.  This method may return <tt>null</tt> if the stream has
147      * been closed. </p>
148      *
149      * @return The historical name of this encoding, or possibly
150      *         <code>null</code> if the stream has been closed
151      *
152      * @see java.nio.charset.Charset
153      *
154      * @revised 1.4
155      * @spec JSR-51
156      */
157     public String   getEncoding() {
158     return se.getEncoding();
159     }
160 
161 
162 
163     /**
164      * Flush the output buffer to the underlying byte stream, without flushing
165      * the byte stream itself.  This method is non-private only so that it may
166      * be invoked by PrintStream.
167      */
168     void flushBuffer() throws IOException   {
169     se.flushBuffer();
170     }
171 
172     /**
173      * Write a single character.
174      *
175      * @exception  IOException  If an I/O error occurs
176      */
177     public void write(int c) throws IOException   {
178     se.write(c);
179     }
180 
181     /**
182      * Write a portion of an array of characters.
183      *
184      * @param  cbuf  Buffer of characters
185      * @param  off   Offset from which to start writing characters
186      * @param  len   Number of characters to write
187      *
188      * @exception  IOException  If an I/O error occurs
189      */
190     public void write(char cbuf[], int off, int len) throws IOException   {
191     se.write(cbuf, off, len);
192     }
193 
194     /**
195      * Write a portion of a string.
196      *
197      * @param  str  A String
198      * @param  off  Offset from which to start writing characters
199      * @param  len  Number of characters to write
200      *
201      * @exception  IOException  If an I/O error occurs
202      */
203     public void write(String   str, int off, int len) throws IOException   {
204     se.write(str, off, len);
205     }
206 
207     /**
208      * Flush the stream.
209      *
210      * @exception  IOException  If an I/O error occurs
211      */
212     public void flush() throws IOException   {
213     se.flush();
214     }
215 
216     /**
217      * Close the stream.
218      *
219      * @exception  IOException  If an I/O error occurs
220      */
221     public void close() throws IOException   {
222     se.close();
223     }
224 
225 }
226
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags