1 /*
   2  * Copyright (c) 1994, 2018, 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.ArrayList;
  29 import java.util.Arrays;
  30 import java.util.List;
  31 import java.util.Objects;
  32 
  33 /**
  34  * This abstract class is the superclass of all classes representing
  35  * an input stream of bytes.
  36  *
  37  * <p> Applications that need to define a subclass of <code>InputStream</code>
  38  * must always provide a method that returns the next byte of input.
  39  *
  40  * @author  Arthur van Hoff
  41  * @see     java.io.BufferedInputStream
  42  * @see     java.io.ByteArrayInputStream
  43  * @see     java.io.DataInputStream
  44  * @see     java.io.FilterInputStream
  45  * @see     java.io.InputStream#read()
  46  * @see     java.io.OutputStream
  47  * @see     java.io.PushbackInputStream
  48  * @since   1.0
  49  */
  50 public abstract class InputStream implements Closeable {
  51 
  52     // MAX_SKIP_BUFFER_SIZE is used to determine the maximum buffer size to
  53     // use when skipping.
  54     private static final int MAX_SKIP_BUFFER_SIZE = 2048;
  55 
  56     private static final int DEFAULT_BUFFER_SIZE = 8192;
  57 
  58     /**
  59      * Returns a new {@code InputStream} that reads no bytes. The returned
  60      * stream is initially open.  The stream is closed by calling the
  61      * {@code close()} method.  Subsequent calls to {@code close()} have no
  62      * effect.
  63      *
  64      * <p> While the stream is open, the {@code available()}, {@code read()},
  65      * {@code read(byte[])}, {@code read(byte[], int, int)},
  66      * {@code readAllBytes()}, {@code readNBytes(byte[], int, int)},
  67      * {@code readNBytes(int)}, {@code skip()}, and
  68      * {@code transferTo()} methods all behave as if end of stream has been
  69      * reached.  After the stream has been closed, these methods all throw
  70      * {@code IOException}.
  71      *
  72      * <p> The {@code markSupported()} method returns {@code false}.  The
  73      * {@code mark()} method does nothing, and the {@code reset()} method
  74      * throws {@code IOException}.
  75      *
  76      * @return an {@code InputStream} which contains no bytes
  77      *
  78      * @since 11
  79      */
  80     public static InputStream nullInputStream() {
  81         return new InputStream() {
  82             private volatile boolean closed;
  83 
  84             private void ensureOpen() throws IOException {
  85                 if (closed) {
  86                     throw new IOException("Stream closed");
  87                 }
  88             }
  89 
  90             @Override
  91             public int available () throws IOException {
  92                 ensureOpen();
  93                 return 0;
  94             }
  95 
  96             @Override
  97             public int read() throws IOException {
  98                 ensureOpen();
  99                 return -1;
 100             }
 101 
 102             @Override
 103             public int read(byte[] b, int off, int len) throws IOException {
 104                 Objects.checkFromIndexSize(off, len, b.length);
 105                 if (len == 0) {
 106                     return 0;
 107                 }
 108                 ensureOpen();
 109                 return -1;
 110             }
 111 
 112             @Override
 113             public byte[] readAllBytes() throws IOException {
 114                 ensureOpen();
 115                 return new byte[0];
 116             }
 117 
 118             @Override
 119             public int readNBytes(byte[] b, int off, int len)
 120                 throws IOException {
 121                 Objects.checkFromIndexSize(off, len, b.length);
 122                 ensureOpen();
 123                 return 0;
 124             }
 125 
 126             @Override
 127             public byte[] readNBytes(int len)
 128                 throws IOException {
 129                 if (len < 0) {
 130                     throw new IllegalArgumentException("len < 0");
 131                 }
 132                 ensureOpen();
 133                 return new byte[0];
 134             }
 135 
 136             @Override
 137             public long skip(long n) throws IOException {
 138                 ensureOpen();
 139                 return 0L;
 140             }
 141 
 142             @Override
 143             public long transferTo(OutputStream out) throws IOException {
 144                 Objects.requireNonNull(out);
 145                 ensureOpen();
 146                 return 0L;
 147             }
 148 
 149             @Override
 150             public void close() throws IOException {
 151                 closed = true;
 152             }
 153         };
 154     }
 155 
 156     /**
 157      * Reads the next byte of data from the input stream. The value byte is
 158      * returned as an <code>int</code> in the range <code>0</code> to
 159      * <code>255</code>. If no byte is available because the end of the stream
 160      * has been reached, the value <code>-1</code> is returned. This method
 161      * blocks until input data is available, the end of the stream is detected,
 162      * or an exception is thrown.
 163      *
 164      * <p> A subclass must provide an implementation of this method.
 165      *
 166      * @return     the next byte of data, or <code>-1</code> if the end of the
 167      *             stream is reached.
 168      * @exception  IOException  if an I/O error occurs.
 169      */
 170     public abstract int read() throws IOException;
 171 
 172     /**
 173      * Reads some number of bytes from the input stream and stores them into
 174      * the buffer array <code>b</code>. The number of bytes actually read is
 175      * returned as an integer.  This method blocks until input data is
 176      * available, end of file is detected, or an exception is thrown.
 177      *
 178      * <p> If the length of <code>b</code> is zero, then no bytes are read and
 179      * <code>0</code> is returned; otherwise, there is an attempt to read at
 180      * least one byte. If no byte is available because the stream is at the
 181      * end of the file, the value <code>-1</code> is returned; otherwise, at
 182      * least one byte is read and stored into <code>b</code>.
 183      *
 184      * <p> The first byte read is stored into element <code>b[0]</code>, the
 185      * next one into <code>b[1]</code>, and so on. The number of bytes read is,
 186      * at most, equal to the length of <code>b</code>. Let <i>k</i> be the
 187      * number of bytes actually read; these bytes will be stored in elements
 188      * <code>b[0]</code> through <code>b[</code><i>k</i><code>-1]</code>,
 189      * leaving elements <code>b[</code><i>k</i><code>]</code> through
 190      * <code>b[b.length-1]</code> unaffected.
 191      *
 192      * <p> The <code>read(b)</code> method for class <code>InputStream</code>
 193      * has the same effect as: <pre><code> read(b, 0, b.length) </code></pre>
 194      *
 195      * @param      b   the buffer into which the data is read.
 196      * @return     the total number of bytes read into the buffer, or
 197      *             <code>-1</code> if there is no more data because the end of
 198      *             the stream has been reached.
 199      * @exception  IOException  If the first byte cannot be read for any reason
 200      * other than the end of the file, if the input stream has been closed, or
 201      * if some other I/O error occurs.
 202      * @exception  NullPointerException  if <code>b</code> is <code>null</code>.
 203      * @see        java.io.InputStream#read(byte[], int, int)
 204      */
 205     public int read(byte b[]) throws IOException {
 206         return read(b, 0, b.length);
 207     }
 208 
 209     /**
 210      * Reads up to <code>len</code> bytes of data from the input stream into
 211      * an array of bytes.  An attempt is made to read as many as
 212      * <code>len</code> bytes, but a smaller number may be read.
 213      * The number of bytes actually read is returned as an integer.
 214      *
 215      * <p> This method blocks until input data is available, end of file is
 216      * detected, or an exception is thrown.
 217      *
 218      * <p> If <code>len</code> is zero, then no bytes are read and
 219      * <code>0</code> is returned; otherwise, there is an attempt to read at
 220      * least one byte. If no byte is available because the stream is at end of
 221      * file, the value <code>-1</code> is returned; otherwise, at least one
 222      * byte is read and stored into <code>b</code>.
 223      *
 224      * <p> The first byte read is stored into element <code>b[off]</code>, the
 225      * next one into <code>b[off+1]</code>, and so on. The number of bytes read
 226      * is, at most, equal to <code>len</code>. Let <i>k</i> be the number of
 227      * bytes actually read; these bytes will be stored in elements
 228      * <code>b[off]</code> through <code>b[off+</code><i>k</i><code>-1]</code>,
 229      * leaving elements <code>b[off+</code><i>k</i><code>]</code> through
 230      * <code>b[off+len-1]</code> unaffected.
 231      *
 232      * <p> In every case, elements <code>b[0]</code> through
 233      * <code>b[off]</code> and elements <code>b[off+len]</code> through
 234      * <code>b[b.length-1]</code> are unaffected.
 235      *
 236      * <p> The <code>read(b,</code> <code>off,</code> <code>len)</code> method
 237      * for class <code>InputStream</code> simply calls the method
 238      * <code>read()</code> repeatedly. If the first such call results in an
 239      * <code>IOException</code>, that exception is returned from the call to
 240      * the <code>read(b,</code> <code>off,</code> <code>len)</code> method.  If
 241      * any subsequent call to <code>read()</code> results in a
 242      * <code>IOException</code>, the exception is caught and treated as if it
 243      * were end of file; the bytes read up to that point are stored into
 244      * <code>b</code> and the number of bytes read before the exception
 245      * occurred is returned. The default implementation of this method blocks
 246      * until the requested amount of input data <code>len</code> has been read,
 247      * end of file is detected, or an exception is thrown. Subclasses are
 248      * encouraged to provide a more efficient implementation of this method.
 249      *
 250      * @param      b     the buffer into which the data is read.
 251      * @param      off   the start offset in array <code>b</code>
 252      *                   at which the data is written.
 253      * @param      len   the maximum number of bytes to read.
 254      * @return     the total number of bytes read into the buffer, or
 255      *             <code>-1</code> if there is no more data because the end of
 256      *             the stream has been reached.
 257      * @exception  IOException If the first byte cannot be read for any reason
 258      * other than end of file, or if the input stream has been closed, or if
 259      * some other I/O error occurs.
 260      * @exception  NullPointerException If <code>b</code> is <code>null</code>.
 261      * @exception  IndexOutOfBoundsException If <code>off</code> is negative,
 262      * <code>len</code> is negative, or <code>len</code> is greater than
 263      * <code>b.length - off</code>
 264      * @see        java.io.InputStream#read()
 265      */
 266     public int read(byte b[], int off, int len) throws IOException {
 267         Objects.checkFromIndexSize(off, len, b.length);
 268         if (len == 0) {
 269             return 0;
 270         }
 271 
 272         int c = read();
 273         if (c == -1) {
 274             return -1;
 275         }
 276         b[off] = (byte)c;
 277 
 278         int i = 1;
 279         try {
 280             for (; i < len ; i++) {
 281                 c = read();
 282                 if (c == -1) {
 283                     break;
 284                 }
 285                 b[off + i] = (byte)c;
 286             }
 287         } catch (IOException ee) {
 288         }
 289         return i;
 290     }
 291 
 292     /**
 293      * The maximum size of array to allocate.
 294      * Some VMs reserve some header words in an array.
 295      * Attempts to allocate larger arrays may result in
 296      * OutOfMemoryError: Requested array size exceeds VM limit
 297      */
 298     private static final int MAX_BUFFER_SIZE = Integer.MAX_VALUE - 8;
 299 
 300     /**
 301      * Reads a number of bytes from the input stream. The number of bytes to
 302      * read is specified by the {@code len} parameter which is interpreted as
 303      * an inclusive upper bound on the number to read. This method blocks
 304      * until the requested number of bytes have been read, end of stream is
 305      * detected, or an exception is thrown. This method does not close the
 306      * input stream.
 307      *
 308      * <p> If {@code len} is zero, then no bytes are read and an empty byte
 309      * array is returned.
 310      *
 311      * <p> When this stream reaches end of stream, further invocations of this
 312      * method will return an empty byte array.
 313      *
 314      * <p> Note that this method is intended for simple cases where it is
 315      * convenient to read the specified number of bytes into a byte array. It
 316      * is not intended for reading large amounts of data.
 317      *
 318      * <p> The behavior for the case where the input stream is <i>asynchronously
 319      * closed</i>, or the thread interrupted during the read, is highly input
 320      * stream specific, and therefore not specified.
 321      *
 322      * <p> If an I/O error occurs reading from the input stream, then it may do
 323      * so after some, but not all, bytes have been read. Consequently the input
 324      * stream may not be at end of stream and may be in an inconsistent state.
 325      * It is strongly recommended that the stream be promptly closed if an I/O
 326      * error occurs.
 327      *
 328      * @param len the maximum number of bytes to read
 329      * @return a byte array containing the bytes read from this input stream
 330      * @throws IllegalArgumentException if {@code len} is negative
 331      * @throws IOException if an I/O error occurs
 332      * @throws OutOfMemoryError if an array of the required size cannot be
 333      *         allocated. For example, if an array larger than {@code 2GB} would
 334      *         be required to store the bytes.
 335      *
 336      * @since 11
 337      */
 338     private byte[] readAtMostNBytes(int len)
 339         throws IOException {
 340         if (len < 0) {
 341             throw new IllegalArgumentException("len < 0");
 342         }
 343 
 344         List<byte[]> bufs = null;
 345         byte[] result = null;
 346         int total = 0;
 347         int remaining = len;
 348         int n;
 349         do {
 350             byte[] buf = new byte[Math.min(len, DEFAULT_BUFFER_SIZE)];
 351             int nread = 0;
 352 
 353             // read to EOF which may read more or less than buffer size
 354             while ((n = read(buf, nread,
 355                 Math.min(buf.length - nread, remaining))) > 0) {
 356                 nread += n;
 357                 remaining -= n;
 358             }
 359 
 360             if (nread > 0) {
 361                 if (MAX_BUFFER_SIZE - total < nread) {
 362                     throw new OutOfMemoryError("Required array size too large");
 363                 }
 364                 total += nread;
 365                 if (result == null) {
 366                     result = buf;
 367                 } else {
 368                     if (bufs == null) {
 369                         bufs = new ArrayList<>();
 370                         bufs.add(result);
 371                     }
 372                     bufs.add(buf);
 373                 }
 374             }
 375             // if the last call to read returned -1 or the number of bytes
 376             // requested have been read then break
 377         } while (n >= 0 && remaining > 0);
 378 
 379         if (bufs == null) {
 380             if (result == null) {
 381                 return new byte[0];
 382             }
 383             return result.length == total ?
 384                 result : Arrays.copyOf(result, total);
 385         }
 386 
 387         result = new byte[total];
 388         int offset = 0;
 389         remaining = total;
 390         for (byte[] b : bufs) {
 391             int count = Math.min(b.length, remaining);
 392             System.arraycopy(b, 0, result, offset, count);
 393             offset += count;
 394             remaining -= count;
 395         }
 396 
 397         return result;
 398     }
 399 
 400     /**
 401      * Reads all remaining bytes from the input stream. This method blocks until
 402      * all remaining bytes have been read and end of stream is detected, or an
 403      * exception is thrown. This method does not close the input stream.
 404      *
 405      * <p> When this stream reaches end of stream, further invocations of this
 406      * method will return an empty byte array.
 407      *
 408      * <p> Note that this method is intended for simple cases where it is
 409      * convenient to read all bytes into a byte array. It is not intended for
 410      * reading input streams with large amounts of data.
 411      *
 412      * <p> The behavior for the case where the input stream is <i>asynchronously
 413      * closed</i>, or the thread interrupted during the read, is highly input
 414      * stream specific, and therefore not specified.
 415      *
 416      * <p> If an I/O error occurs reading from the input stream, then it may do
 417      * so after some, but not all, bytes have been read. Consequently the input
 418      * stream may not be at end of stream and may be in an inconsistent state.
 419      * It is strongly recommended that the stream be promptly closed if an I/O
 420      * error occurs.
 421      *
 422      * @return a byte array containing the bytes read from this input stream
 423      * @throws IOException if an I/O error occurs
 424      * @throws OutOfMemoryError if an array of the required size cannot be
 425      *         allocated. For example, if an array larger than {@code 2GB} would
 426      *         be required to store the bytes.
 427      *
 428      * @since 9
 429      */
 430     public byte[] readAllBytes() throws IOException {
 431         return readAtMostNBytes(Integer.MAX_VALUE);
 432     }
 433 
 434     /**
 435      * Reads up to a specified number of bytes from the input stream. This
 436      * method blocks until the requested number of bytes have been read, end
 437      * of stream is detected, or an exception is thrown. This method does not
 438      * close the input stream.
 439      *
 440      * <p> The length of the returned array equals the number of bytes read
 441      * from the stream. If {@code len} is zero, then no bytes are read and
 442      * an empty byte array is returned. Otherwise, up to {@code len} bytes
 443      * are read from the stream. Fewer than {@code len} bytes may be read if
 444      * end of stream is encountered.
 445      *
 446      * <p> When this stream reaches end of stream, further invocations of this
 447      * method will return an empty byte array.
 448      *
 449      * <p> Note that this method is intended for simple cases where it is
 450      * convenient to read the specified number of bytes into a byte array. It
 451      * is not intended for reading large amounts of data.
 452      *
 453      * <p> The behavior for the case where the input stream is <i>asynchronously
 454      * closed</i>, or the thread interrupted during the read, is highly input
 455      * stream specific, and therefore not specified.
 456      *
 457      * <p> If an I/O error occurs reading from the input stream, then it may do
 458      * so after some, but not all, bytes have been read. Consequently the input
 459      * stream may not be at end of stream and may be in an inconsistent state.
 460      * It is strongly recommended that the stream be promptly closed if an I/O
 461      * error occurs.
 462      *
 463      * @param len the maximum number of bytes to read
 464      * @return a byte array containing the bytes read from this input stream
 465      * @throws IllegalArgumentException if {@code length} is negative
 466      * @throws IOException if an I/O error occurs
 467      * @throws OutOfMemoryError if an array of the required size cannot be
 468      *         allocated. For example, if an array larger than {@code 2GB} would
 469      *         be required to store the bytes.
 470      *
 471      * @since 11
 472      */
 473     public byte[] readNBytes(int len) throws IOException {
 474         return readAtMostNBytes(len);
 475     }
 476 
 477     /**
 478      * Reads the requested number of bytes from the input stream into the given
 479      * byte array. This method blocks until {@code len} bytes of input data have
 480      * been read, end of stream is detected, or an exception is thrown. The
 481      * number of bytes actually read, possibly zero, is returned. This method
 482      * does not close the input stream.
 483      *
 484      * <p> In the case where end of stream is reached before {@code len} bytes
 485      * have been read, then the actual number of bytes read will be returned.
 486      * When this stream reaches end of stream, further invocations of this
 487      * method will return zero.
 488      *
 489      * <p> If {@code len} is zero, then no bytes are read and {@code 0} is
 490      * returned; otherwise, there is an attempt to read up to {@code len} bytes.
 491      *
 492      * <p> The first byte read is stored into element {@code b[off]}, the next
 493      * one in to {@code b[off+1]}, and so on. The number of bytes read is, at
 494      * most, equal to {@code len}. Let <i>k</i> be the number of bytes actually
 495      * read; these bytes will be stored in elements {@code b[off]} through
 496      * {@code b[off+}<i>k</i>{@code -1]}, leaving elements {@code b[off+}<i>k</i>
 497      * {@code ]} through {@code b[off+len-1]} unaffected.
 498      *
 499      * <p> The behavior for the case where the input stream is <i>asynchronously
 500      * closed</i>, or the thread interrupted during the read, is highly input
 501      * stream specific, and therefore not specified.
 502      *
 503      * <p> If an I/O error occurs reading from the input stream, then it may do
 504      * so after some, but not all, bytes of {@code b} have been updated with
 505      * data from the input stream. Consequently the input stream and {@code b}
 506      * may be in an inconsistent state. It is strongly recommended that the
 507      * stream be promptly closed if an I/O error occurs.
 508      *
 509      * @param  b the byte array into which the data is read
 510      * @param  off the start offset in {@code b} at which the data is written
 511      * @param  len the maximum number of bytes to read
 512      * @return the actual number of bytes read into the buffer
 513      * @throws IOException if an I/O error occurs
 514      * @throws NullPointerException if {@code b} is {@code null}
 515      * @throws IndexOutOfBoundsException If {@code off} is negative, {@code len}
 516      *         is negative, or {@code len} is greater than {@code b.length - off}
 517      *
 518      * @since 9
 519      */
 520     public int readNBytes(byte[] b, int off, int len) throws IOException {
 521         Objects.checkFromIndexSize(off, len, b.length);
 522 
 523         int n = 0;
 524         while (n < len) {
 525             int count = read(b, off + n, len - n);
 526             if (count < 0)
 527                 break;
 528             n += count;
 529         }
 530         return n;
 531     }
 532 
 533     /**
 534      * Skips over and discards <code>n</code> bytes of data from this input
 535      * stream. The <code>skip</code> method may, for a variety of reasons, end
 536      * up skipping over some smaller number of bytes, possibly <code>0</code>.
 537      * This may result from any of a number of conditions; reaching end of file
 538      * before <code>n</code> bytes have been skipped is only one possibility.
 539      * The actual number of bytes skipped is returned. If {@code n} is
 540      * negative, the {@code skip} method for class {@code InputStream} always
 541      * returns 0, and no bytes are skipped. Subclasses may handle the negative
 542      * value differently.
 543      *
 544      * <p> The <code>skip</code> method implementation of this class creates a
 545      * byte array and then repeatedly reads into it until <code>n</code> bytes
 546      * have been read or the end of the stream has been reached. Subclasses are
 547      * encouraged to provide a more efficient implementation of this method.
 548      * For instance, the implementation may depend on the ability to seek.
 549      *
 550      * @param      n   the number of bytes to be skipped.
 551      * @return     the actual number of bytes skipped.
 552      * @throws     IOException  if an I/O error occurs.
 553      */
 554     public long skip(long n) throws IOException {
 555 
 556         long remaining = n;
 557         int nr;
 558 
 559         if (n <= 0) {
 560             return 0;
 561         }
 562 
 563         int size = (int)Math.min(MAX_SKIP_BUFFER_SIZE, remaining);
 564         byte[] skipBuffer = new byte[size];
 565         while (remaining > 0) {
 566             nr = read(skipBuffer, 0, (int)Math.min(size, remaining));
 567             if (nr < 0) {
 568                 break;
 569             }
 570             remaining -= nr;
 571         }
 572 
 573         return n - remaining;
 574     }
 575 
 576     /**
 577      * Returns an estimate of the number of bytes that can be read (or
 578      * skipped over) from this input stream without blocking by the next
 579      * invocation of a method for this input stream. The next invocation
 580      * might be the same thread or another thread.  A single read or skip of this
 581      * many bytes will not block, but may read or skip fewer bytes.
 582      *
 583      * <p> Note that while some implementations of {@code InputStream} will return
 584      * the total number of bytes in the stream, many will not.  It is
 585      * never correct to use the return value of this method to allocate
 586      * a buffer intended to hold all data in this stream.
 587      *
 588      * <p> A subclass' implementation of this method may choose to throw an
 589      * {@link IOException} if this input stream has been closed by
 590      * invoking the {@link #close()} method.
 591      *
 592      * <p> The {@code available} method for class {@code InputStream} always
 593      * returns {@code 0}.
 594      *
 595      * <p> This method should be overridden by subclasses.
 596      *
 597      * @return     an estimate of the number of bytes that can be read (or skipped
 598      *             over) from this input stream without blocking or {@code 0} when
 599      *             it reaches the end of the input stream.
 600      * @exception  IOException if an I/O error occurs.
 601      */
 602     public int available() throws IOException {
 603         return 0;
 604     }
 605 
 606     /**
 607      * Closes this input stream and releases any system resources associated
 608      * with the stream.
 609      *
 610      * <p> The <code>close</code> method of <code>InputStream</code> does
 611      * nothing.
 612      *
 613      * @exception  IOException  if an I/O error occurs.
 614      */
 615     public void close() throws IOException {}
 616 
 617     /**
 618      * Marks the current position in this input stream. A subsequent call to
 619      * the <code>reset</code> method repositions this stream at the last marked
 620      * position so that subsequent reads re-read the same bytes.
 621      *
 622      * <p> The <code>readlimit</code> arguments tells this input stream to
 623      * allow that many bytes to be read before the mark position gets
 624      * invalidated.
 625      *
 626      * <p> The general contract of <code>mark</code> is that, if the method
 627      * <code>markSupported</code> returns <code>true</code>, the stream somehow
 628      * remembers all the bytes read after the call to <code>mark</code> and
 629      * stands ready to supply those same bytes again if and whenever the method
 630      * <code>reset</code> is called.  However, the stream is not required to
 631      * remember any data at all if more than <code>readlimit</code> bytes are
 632      * read from the stream before <code>reset</code> is called.
 633      *
 634      * <p> Marking a closed stream should not have any effect on the stream.
 635      *
 636      * <p> The <code>mark</code> method of <code>InputStream</code> does
 637      * nothing.
 638      *
 639      * @param   readlimit   the maximum limit of bytes that can be read before
 640      *                      the mark position becomes invalid.
 641      * @see     java.io.InputStream#reset()
 642      */
 643     public synchronized void mark(int readlimit) {}
 644 
 645     /**
 646      * Repositions this stream to the position at the time the
 647      * <code>mark</code> method was last called on this input stream.
 648      *
 649      * <p> The general contract of <code>reset</code> is:
 650      *
 651      * <ul>
 652      * <li> If the method <code>markSupported</code> returns
 653      * <code>true</code>, then:
 654      *
 655      *     <ul><li> If the method <code>mark</code> has not been called since
 656      *     the stream was created, or the number of bytes read from the stream
 657      *     since <code>mark</code> was last called is larger than the argument
 658      *     to <code>mark</code> at that last call, then an
 659      *     <code>IOException</code> might be thrown.
 660      *
 661      *     <li> If such an <code>IOException</code> is not thrown, then the
 662      *     stream is reset to a state such that all the bytes read since the
 663      *     most recent call to <code>mark</code> (or since the start of the
 664      *     file, if <code>mark</code> has not been called) will be resupplied
 665      *     to subsequent callers of the <code>read</code> method, followed by
 666      *     any bytes that otherwise would have been the next input data as of
 667      *     the time of the call to <code>reset</code>. </ul>
 668      *
 669      * <li> If the method <code>markSupported</code> returns
 670      * <code>false</code>, then:
 671      *
 672      *     <ul><li> The call to <code>reset</code> may throw an
 673      *     <code>IOException</code>.
 674      *
 675      *     <li> If an <code>IOException</code> is not thrown, then the stream
 676      *     is reset to a fixed state that depends on the particular type of the
 677      *     input stream and how it was created. The bytes that will be supplied
 678      *     to subsequent callers of the <code>read</code> method depend on the
 679      *     particular type of the input stream. </ul></ul>
 680      *
 681      * <p>The method <code>reset</code> for class <code>InputStream</code>
 682      * does nothing except throw an <code>IOException</code>.
 683      *
 684      * @exception  IOException  if this stream has not been marked or if the
 685      *               mark has been invalidated.
 686      * @see     java.io.InputStream#mark(int)
 687      * @see     java.io.IOException
 688      */
 689     public synchronized void reset() throws IOException {
 690         throw new IOException("mark/reset not supported");
 691     }
 692 
 693     /**
 694      * Tests if this input stream supports the <code>mark</code> and
 695      * <code>reset</code> methods. Whether or not <code>mark</code> and
 696      * <code>reset</code> are supported is an invariant property of a
 697      * particular input stream instance. The <code>markSupported</code> method
 698      * of <code>InputStream</code> returns <code>false</code>.
 699      *
 700      * @return  <code>true</code> if this stream instance supports the mark
 701      *          and reset methods; <code>false</code> otherwise.
 702      * @see     java.io.InputStream#mark(int)
 703      * @see     java.io.InputStream#reset()
 704      */
 705     public boolean markSupported() {
 706         return false;
 707     }
 708 
 709     /**
 710      * Reads all bytes from this input stream and writes the bytes to the
 711      * given output stream in the order that they are read. On return, this
 712      * input stream will be at end of stream. This method does not close either
 713      * stream.
 714      * <p>
 715      * This method may block indefinitely reading from the input stream, or
 716      * writing to the output stream. The behavior for the case where the input
 717      * and/or output stream is <i>asynchronously closed</i>, or the thread
 718      * interrupted during the transfer, is highly input and output stream
 719      * specific, and therefore not specified.
 720      * <p>
 721      * If an I/O error occurs reading from the input stream or writing to the
 722      * output stream, then it may do so after some bytes have been read or
 723      * written. Consequently the input stream may not be at end of stream and
 724      * one, or both, streams may be in an inconsistent state. It is strongly
 725      * recommended that both streams be promptly closed if an I/O error occurs.
 726      *
 727      * @param  out the output stream, non-null
 728      * @return the number of bytes transferred
 729      * @throws IOException if an I/O error occurs when reading or writing
 730      * @throws NullPointerException if {@code out} is {@code null}
 731      *
 732      * @since 9
 733      */
 734     public long transferTo(OutputStream out) throws IOException {
 735         Objects.requireNonNull(out, "out");
 736         long transferred = 0;
 737         byte[] buffer = new byte[DEFAULT_BUFFER_SIZE];
 738         int read;
 739         while ((read = this.read(buffer, 0, DEFAULT_BUFFER_SIZE)) >= 0) {
 740             out.write(buffer, 0, read);
 741             transferred += read;
 742         }
 743         return transferred;
 744     }
 745 }