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

    1   /*
    2    * Copyright (c) 1994, 2004, 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   /**
   29    * This abstract class is the superclass of all classes representing
   30    * an output stream of bytes. An output stream accepts output bytes
   31    * and sends them to some sink.
   32    * <p>
   33    * Applications that need to define a subclass of
   34    * <code>OutputStream</code> must always provide at least a method
   35    * that writes one byte of output.
   36    *
   37    * @author  Arthur van Hoff
   38    * @see     java.io.BufferedOutputStream
   39    * @see     java.io.ByteArrayOutputStream
   40    * @see     java.io.DataOutputStream
   41    * @see     java.io.FilterOutputStream
   42    * @see     java.io.InputStream
   43    * @see     java.io.OutputStream#write(int)
   44    * @since   JDK1.0
   45    */
   46   public abstract class OutputStream implements Closeable, Flushable {
   47       /**
   48        * Writes the specified byte to this output stream. The general
   49        * contract for <code>write</code> is that one byte is written
   50        * to the output stream. The byte to be written is the eight
   51        * low-order bits of the argument <code>b</code>. The 24
   52        * high-order bits of <code>b</code> are ignored.
   53        * <p>
   54        * Subclasses of <code>OutputStream</code> must provide an
   55        * implementation for this method.
   56        *
   57        * @param      b   the <code>byte</code>.
   58        * @exception  IOException  if an I/O error occurs. In particular,
   59        *             an <code>IOException</code> may be thrown if the
   60        *             output stream has been closed.
   61        */
   62       public abstract void write(int b) throws IOException;
   63   
   64       /**
   65        * Writes <code>b.length</code> bytes from the specified byte array
   66        * to this output stream. The general contract for <code>write(b)</code>
   67        * is that it should have exactly the same effect as the call
   68        * <code>write(b, 0, b.length)</code>.
   69        *
   70        * @param      b   the data.
   71        * @exception  IOException  if an I/O error occurs.
   72        * @see        java.io.OutputStream#write(byte[], int, int)
   73        */
   74       public void write(byte b[]) throws IOException {
   75           write(b, 0, b.length);
   76       }
   77   
   78       /**
   79        * Writes <code>len</code> bytes from the specified byte array
   80        * starting at offset <code>off</code> to this output stream.
   81        * The general contract for <code>write(b, off, len)</code> is that
   82        * some of the bytes in the array <code>b</code> are written to the
   83        * output stream in order; element <code>b[off]</code> is the first
   84        * byte written and <code>b[off+len-1]</code> is the last byte written
   85        * by this operation.
   86        * <p>
   87        * The <code>write</code> method of <code>OutputStream</code> calls
   88        * the write method of one argument on each of the bytes to be
   89        * written out. Subclasses are encouraged to override this method and
   90        * provide a more efficient implementation.
   91        * <p>
   92        * If <code>b</code> is <code>null</code>, a
   93        * <code>NullPointerException</code> is thrown.
   94        * <p>
   95        * If <code>off</code> is negative, or <code>len</code> is negative, or
   96        * <code>off+len</code> is greater than the length of the array
   97        * <code>b</code>, then an <tt>IndexOutOfBoundsException</tt> is thrown.
   98        *
   99        * @param      b     the data.
  100        * @param      off   the start offset in the data.
  101        * @param      len   the number of bytes to write.
  102        * @exception  IOException  if an I/O error occurs. In particular,
  103        *             an <code>IOException</code> is thrown if the output
  104        *             stream is closed.
  105        */
  106       public void write(byte b[], int off, int len) throws IOException {
  107           if (b == null) {
  108               throw new NullPointerException();
  109           } else if ((off < 0) || (off > b.length) || (len < 0) ||
  110                      ((off + len) > b.length) || ((off + len) < 0)) {
  111               throw new IndexOutOfBoundsException();
  112           } else if (len == 0) {
  113               return;
  114           }
  115           for (int i = 0 ; i < len ; i++) {
  116               write(b[off + i]);
  117           }
  118       }
  119   
  120       /**
  121        * Flushes this output stream and forces any buffered output bytes
  122        * to be written out. The general contract of <code>flush</code> is
  123        * that calling it is an indication that, if any bytes previously
  124        * written have been buffered by the implementation of the output
  125        * stream, such bytes should immediately be written to their
  126        * intended destination.
  127        * <p>
  128        * If the intended destination of this stream is an abstraction provided by
  129        * the underlying operating system, for example a file, then flushing the
  130        * stream guarantees only that bytes previously written to the stream are
  131        * passed to the operating system for writing; it does not guarantee that
  132        * they are actually written to a physical device such as a disk drive.
  133        * <p>
  134        * The <code>flush</code> method of <code>OutputStream</code> does nothing.
  135        *
  136        * @exception  IOException  if an I/O error occurs.
  137        */
  138       public void flush() throws IOException {
  139       }
  140   
  141       /**
  142        * Closes this output stream and releases any system resources
  143        * associated with this stream. The general contract of <code>close</code>
  144        * is that it closes the output stream. A closed stream cannot perform
  145        * output operations and cannot be reopened.
  146        * <p>
  147        * The <code>close</code> method of <code>OutputStream</code> does nothing.
  148        *
  149        * @exception  IOException  if an I/O error occurs.
  150        */
  151       public void close() throws IOException {
  152       }
  153   
  154   }

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