Home » openjdk-7 » java » io » [javadoc | source]

    1   /*
    2    * Copyright (c) 1996, 2006, 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 <code>charset</code>}.  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 </code>charset<code>}
   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. </p>
  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.  </p>
  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   }

Home » openjdk-7 » java » io » [javadoc | source]