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

    1   /*
    2    * Copyright (c) 1994, 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   /**
   29    * This abstract class is the superclass of all classes representing
   30    * an input stream of bytes.
   31    *
   32    * <p> Applications that need to define a subclass of <code>InputStream</code>
   33    * must always provide a method that returns the next byte of input.
   34    *
   35    * @author  Arthur van Hoff
   36    * @see     java.io.BufferedInputStream
   37    * @see     java.io.ByteArrayInputStream
   38    * @see     java.io.DataInputStream
   39    * @see     java.io.FilterInputStream
   40    * @see     java.io.InputStream#read()
   41    * @see     java.io.OutputStream
   42    * @see     java.io.PushbackInputStream
   43    * @since   JDK1.0
   44    */
   45   public abstract class InputStream implements Closeable {
   46   
   47       // SKIP_BUFFER_SIZE is used to determine the size of skipBuffer
   48       private static final int SKIP_BUFFER_SIZE = 2048;
   49       // skipBuffer is initialized in skip(long), if needed.
   50       private static byte[] skipBuffer;
   51   
   52       /**
   53        * Reads the next byte of data from the input stream. The value byte is
   54        * returned as an <code>int</code> in the range <code>0</code> to
   55        * <code>255</code>. If no byte is available because the end of the stream
   56        * has been reached, the value <code>-1</code> is returned. This method
   57        * blocks until input data is available, the end of the stream is detected,
   58        * or an exception is thrown.
   59        *
   60        * <p> A subclass must provide an implementation of this method.
   61        *
   62        * @return     the next byte of data, or <code>-1</code> if the end of the
   63        *             stream is reached.
   64        * @exception  IOException  if an I/O error occurs.
   65        */
   66       public abstract int read() throws IOException;
   67   
   68       /**
   69        * Reads some number of bytes from the input stream and stores them into
   70        * the buffer array <code>b</code>. The number of bytes actually read is
   71        * returned as an integer.  This method blocks until input data is
   72        * available, end of file is detected, or an exception is thrown.
   73        *
   74        * <p> If the length of <code>b</code> is zero, then no bytes are read and
   75        * <code>0</code> is returned; otherwise, there is an attempt to read at
   76        * least one byte. If no byte is available because the stream is at the
   77        * end of the file, the value <code>-1</code> is returned; otherwise, at
   78        * least one byte is read and stored into <code>b</code>.
   79        *
   80        * <p> The first byte read is stored into element <code>b[0]</code>, the
   81        * next one into <code>b[1]</code>, and so on. The number of bytes read is,
   82        * at most, equal to the length of <code>b</code>. Let <i>k</i> be the
   83        * number of bytes actually read; these bytes will be stored in elements
   84        * <code>b[0]</code> through <code>b[</code><i>k</i><code>-1]</code>,
   85        * leaving elements <code>b[</code><i>k</i><code>]</code> through
   86        * <code>b[b.length-1]</code> unaffected.
   87        *
   88        * <p> The <code>read(b)</code> method for class <code>InputStream</code>
   89        * has the same effect as: <pre><code> read(b, 0, b.length) </code></pre>
   90        *
   91        * @param      b   the buffer into which the data is read.
   92        * @return     the total number of bytes read into the buffer, or
   93        *             <code>-1</code> if there is no more data because the end of
   94        *             the stream has been reached.
   95        * @exception  IOException  If the first byte cannot be read for any reason
   96        * other than the end of the file, if the input stream has been closed, or
   97        * if some other I/O error occurs.
   98        * @exception  NullPointerException  if <code>b</code> is <code>null</code>.
   99        * @see        java.io.InputStream#read(byte[], int, int)
  100        */
  101       public int read(byte b[]) throws IOException {
  102           return read(b, 0, b.length);
  103       }
  104   
  105       /**
  106        * Reads up to <code>len</code> bytes of data from the input stream into
  107        * an array of bytes.  An attempt is made to read as many as
  108        * <code>len</code> bytes, but a smaller number may be read.
  109        * The number of bytes actually read is returned as an integer.
  110        *
  111        * <p> This method blocks until input data is available, end of file is
  112        * detected, or an exception is thrown.
  113        *
  114        * <p> If <code>len</code> is zero, then no bytes are read and
  115        * <code>0</code> is returned; otherwise, there is an attempt to read at
  116        * least one byte. If no byte is available because the stream is at end of
  117        * file, the value <code>-1</code> is returned; otherwise, at least one
  118        * byte is read and stored into <code>b</code>.
  119        *
  120        * <p> The first byte read is stored into element <code>b[off]</code>, the
  121        * next one into <code>b[off+1]</code>, and so on. The number of bytes read
  122        * is, at most, equal to <code>len</code>. Let <i>k</i> be the number of
  123        * bytes actually read; these bytes will be stored in elements
  124        * <code>b[off]</code> through <code>b[off+</code><i>k</i><code>-1]</code>,
  125        * leaving elements <code>b[off+</code><i>k</i><code>]</code> through
  126        * <code>b[off+len-1]</code> unaffected.
  127        *
  128        * <p> In every case, elements <code>b[0]</code> through
  129        * <code>b[off]</code> and elements <code>b[off+len]</code> through
  130        * <code>b[b.length-1]</code> are unaffected.
  131        *
  132        * <p> The <code>read(b,</code> <code>off,</code> <code>len)</code> method
  133        * for class <code>InputStream</code> simply calls the method
  134        * <code>read()</code> repeatedly. If the first such call results in an
  135        * <code>IOException</code>, that exception is returned from the call to
  136        * the <code>read(b,</code> <code>off,</code> <code>len)</code> method.  If
  137        * any subsequent call to <code>read()</code> results in a
  138        * <code>IOException</code>, the exception is caught and treated as if it
  139        * were end of file; the bytes read up to that point are stored into
  140        * <code>b</code> and the number of bytes read before the exception
  141        * occurred is returned. The default implementation of this method blocks
  142        * until the requested amount of input data <code>len</code> has been read,
  143        * end of file is detected, or an exception is thrown. Subclasses are encouraged
  144        * to provide a more efficient implementation of this method.
  145        *
  146        * @param      b     the buffer into which the data is read.
  147        * @param      off   the start offset in array <code>b</code>
  148        *                   at which the data is written.
  149        * @param      len   the maximum number of bytes to read.
  150        * @return     the total number of bytes read into the buffer, or
  151        *             <code>-1</code> if there is no more data because the end of
  152        *             the stream has been reached.
  153        * @exception  IOException If the first byte cannot be read for any reason
  154        * other than end of file, or if the input stream has been closed, or if
  155        * some other I/O error occurs.
  156        * @exception  NullPointerException If <code>b</code> is <code>null</code>.
  157        * @exception  IndexOutOfBoundsException If <code>off</code> is negative,
  158        * <code>len</code> is negative, or <code>len</code> is greater than
  159        * <code>b.length - off</code>
  160        * @see        java.io.InputStream#read()
  161        */
  162       public int read(byte b[], int off, int len) throws IOException {
  163           if (b == null) {
  164               throw new NullPointerException();
  165           } else if (off < 0 || len < 0 || len > b.length - off) {
  166               throw new IndexOutOfBoundsException();
  167           } else if (len == 0) {
  168               return 0;
  169           }
  170   
  171           int c = read();
  172           if (c == -1) {
  173               return -1;
  174           }
  175           b[off] = (byte)c;
  176   
  177           int i = 1;
  178           try {
  179               for (; i < len ; i++) {
  180                   c = read();
  181                   if (c == -1) {
  182                       break;
  183                   }
  184                   b[off + i] = (byte)c;
  185               }
  186           } catch (IOException ee) {
  187           }
  188           return i;
  189       }
  190   
  191       /**
  192        * Skips over and discards <code>n</code> bytes of data from this input
  193        * stream. The <code>skip</code> method may, for a variety of reasons, end
  194        * up skipping over some smaller number of bytes, possibly <code>0</code>.
  195        * This may result from any of a number of conditions; reaching end of file
  196        * before <code>n</code> bytes have been skipped is only one possibility.
  197        * The actual number of bytes skipped is returned.  If <code>n</code> is
  198        * negative, no bytes are skipped.
  199        *
  200        * <p> The <code>skip</code> method of this class creates a
  201        * byte array and then repeatedly reads into it until <code>n</code> bytes
  202        * have been read or the end of the stream has been reached. Subclasses are
  203        * encouraged to provide a more efficient implementation of this method.
  204        * For instance, the implementation may depend on the ability to seek.
  205        *
  206        * @param      n   the number of bytes to be skipped.
  207        * @return     the actual number of bytes skipped.
  208        * @exception  IOException  if the stream does not support seek,
  209        *                          or if some other I/O error occurs.
  210        */
  211       public long skip(long n) throws IOException {
  212   
  213           long remaining = n;
  214           int nr;
  215           if (skipBuffer == null)
  216               skipBuffer = new byte[SKIP_BUFFER_SIZE];
  217   
  218           byte[] localSkipBuffer = skipBuffer;
  219   
  220           if (n <= 0) {
  221               return 0;
  222           }
  223   
  224           while (remaining > 0) {
  225               nr = read(localSkipBuffer, 0,
  226                         (int) Math.min(SKIP_BUFFER_SIZE, remaining));
  227               if (nr < 0) {
  228                   break;
  229               }
  230               remaining -= nr;
  231           }
  232   
  233           return n - remaining;
  234       }
  235   
  236       /**
  237        * Returns an estimate of the number of bytes that can be read (or
  238        * skipped over) from this input stream without blocking by the next
  239        * invocation of a method for this input stream. The next invocation
  240        * might be the same thread or another thread.  A single read or skip of this
  241        * many bytes will not block, but may read or skip fewer bytes.
  242        *
  243        * <p> Note that while some implementations of {@code InputStream} will return
  244        * the total number of bytes in the stream, many will not.  It is
  245        * never correct to use the return value of this method to allocate
  246        * a buffer intended to hold all data in this stream.
  247        *
  248        * <p> A subclass' implementation of this method may choose to throw an
  249        * {@link IOException} if this input stream has been closed by
  250        * invoking the {@link #close()} method.
  251        *
  252        * <p> The {@code available} method for class {@code InputStream} always
  253        * returns {@code 0}.
  254        *
  255        * <p> This method should be overridden by subclasses.
  256        *
  257        * @return     an estimate of the number of bytes that can be read (or skipped
  258        *             over) from this input stream without blocking or {@code 0} when
  259        *             it reaches the end of the input stream.
  260        * @exception  IOException if an I/O error occurs.
  261        */
  262       public int available() throws IOException {
  263           return 0;
  264       }
  265   
  266       /**
  267        * Closes this input stream and releases any system resources associated
  268        * with the stream.
  269        *
  270        * <p> The <code>close</code> method of <code>InputStream</code> does
  271        * nothing.
  272        *
  273        * @exception  IOException  if an I/O error occurs.
  274        */
  275       public void close() throws IOException {}
  276   
  277       /**
  278        * Marks the current position in this input stream. A subsequent call to
  279        * the <code>reset</code> method repositions this stream at the last marked
  280        * position so that subsequent reads re-read the same bytes.
  281        *
  282        * <p> The <code>readlimit</code> arguments tells this input stream to
  283        * allow that many bytes to be read before the mark position gets
  284        * invalidated.
  285        *
  286        * <p> The general contract of <code>mark</code> is that, if the method
  287        * <code>markSupported</code> returns <code>true</code>, the stream somehow
  288        * remembers all the bytes read after the call to <code>mark</code> and
  289        * stands ready to supply those same bytes again if and whenever the method
  290        * <code>reset</code> is called.  However, the stream is not required to
  291        * remember any data at all if more than <code>readlimit</code> bytes are
  292        * read from the stream before <code>reset</code> is called.
  293        *
  294        * <p> Marking a closed stream should not have any effect on the stream.
  295        *
  296        * <p> The <code>mark</code> method of <code>InputStream</code> does
  297        * nothing.
  298        *
  299        * @param   readlimit   the maximum limit of bytes that can be read before
  300        *                      the mark position becomes invalid.
  301        * @see     java.io.InputStream#reset()
  302        */
  303       public synchronized void mark(int readlimit) {}
  304   
  305       /**
  306        * Repositions this stream to the position at the time the
  307        * <code>mark</code> method was last called on this input stream.
  308        *
  309        * <p> The general contract of <code>reset</code> is:
  310        *
  311        * <p><ul>
  312        *
  313        * <li> If the method <code>markSupported</code> returns
  314        * <code>true</code>, then:
  315        *
  316        *     <ul><li> If the method <code>mark</code> has not been called since
  317        *     the stream was created, or the number of bytes read from the stream
  318        *     since <code>mark</code> was last called is larger than the argument
  319        *     to <code>mark</code> at that last call, then an
  320        *     <code>IOException</code> might be thrown.
  321        *
  322        *     <li> If such an <code>IOException</code> is not thrown, then the
  323        *     stream is reset to a state such that all the bytes read since the
  324        *     most recent call to <code>mark</code> (or since the start of the
  325        *     file, if <code>mark</code> has not been called) will be resupplied
  326        *     to subsequent callers of the <code>read</code> method, followed by
  327        *     any bytes that otherwise would have been the next input data as of
  328        *     the time of the call to <code>reset</code>. </ul>
  329        *
  330        * <li> If the method <code>markSupported</code> returns
  331        * <code>false</code>, then:
  332        *
  333        *     <ul><li> The call to <code>reset</code> may throw an
  334        *     <code>IOException</code>.
  335        *
  336        *     <li> If an <code>IOException</code> is not thrown, then the stream
  337        *     is reset to a fixed state that depends on the particular type of the
  338        *     input stream and how it was created. The bytes that will be supplied
  339        *     to subsequent callers of the <code>read</code> method depend on the
  340        *     particular type of the input stream. </ul></ul>
  341        *
  342        * <p>The method <code>reset</code> for class <code>InputStream</code>
  343        * does nothing except throw an <code>IOException</code>.
  344        *
  345        * @exception  IOException  if this stream has not been marked or if the
  346        *               mark has been invalidated.
  347        * @see     java.io.InputStream#mark(int)
  348        * @see     java.io.IOException
  349        */
  350       public synchronized void reset() throws IOException {
  351           throw new IOException("mark/reset not supported");
  352       }
  353   
  354       /**
  355        * Tests if this input stream supports the <code>mark</code> and
  356        * <code>reset</code> methods. Whether or not <code>mark</code> and
  357        * <code>reset</code> are supported is an invariant property of a
  358        * particular input stream instance. The <code>markSupported</code> method
  359        * of <code>InputStream</code> returns <code>false</code>.
  360        *
  361        * @return  <code>true</code> if this stream instance supports the mark
  362        *          and reset methods; <code>false</code> otherwise.
  363        * @see     java.io.InputStream#mark(int)
  364        * @see     java.io.InputStream#reset()
  365        */
  366       public boolean markSupported() {
  367           return false;
  368       }
  369   
  370   }

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