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