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

    1   /*
    2    * Copyright (c) 1994, 2010, 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    * A <code>ByteArrayInputStream</code> contains
   30    * an internal buffer that contains bytes that
   31    * may be read from the stream. An internal
   32    * counter keeps track of the next byte to
   33    * be supplied by the <code>read</code> method.
   34    * <p>
   35    * Closing a <tt>ByteArrayInputStream</tt> has no effect. The methods in
   36    * this class can be called after the stream has been closed without
   37    * generating an <tt>IOException</tt>.
   38    *
   39    * @author  Arthur van Hoff
   40    * @see     java.io.StringBufferInputStream
   41    * @since   JDK1.0
   42    */
   43   public
   44   class ByteArrayInputStream extends InputStream {
   45   
   46       /**
   47        * An array of bytes that was provided
   48        * by the creator of the stream. Elements <code>buf[0]</code>
   49        * through <code>buf[count-1]</code> are the
   50        * only bytes that can ever be read from the
   51        * stream;  element <code>buf[pos]</code> is
   52        * the next byte to be read.
   53        */
   54       protected byte buf[];
   55   
   56       /**
   57        * The index of the next character to read from the input stream buffer.
   58        * This value should always be nonnegative
   59        * and not larger than the value of <code>count</code>.
   60        * The next byte to be read from the input stream buffer
   61        * will be <code>buf[pos]</code>.
   62        */
   63       protected int pos;
   64   
   65       /**
   66        * The currently marked position in the stream.
   67        * ByteArrayInputStream objects are marked at position zero by
   68        * default when constructed.  They may be marked at another
   69        * position within the buffer by the <code>mark()</code> method.
   70        * The current buffer position is set to this point by the
   71        * <code>reset()</code> method.
   72        * <p>
   73        * If no mark has been set, then the value of mark is the offset
   74        * passed to the constructor (or 0 if the offset was not supplied).
   75        *
   76        * @since   JDK1.1
   77        */
   78       protected int mark = 0;
   79   
   80       /**
   81        * The index one greater than the last valid character in the input
   82        * stream buffer.
   83        * This value should always be nonnegative
   84        * and not larger than the length of <code>buf</code>.
   85        * It  is one greater than the position of
   86        * the last byte within <code>buf</code> that
   87        * can ever be read  from the input stream buffer.
   88        */
   89       protected int count;
   90   
   91       /**
   92        * Creates a <code>ByteArrayInputStream</code>
   93        * so that it  uses <code>buf</code> as its
   94        * buffer array.
   95        * The buffer array is not copied.
   96        * The initial value of <code>pos</code>
   97        * is <code>0</code> and the initial value
   98        * of  <code>count</code> is the length of
   99        * <code>buf</code>.
  100        *
  101        * @param   buf   the input buffer.
  102        */
  103       public ByteArrayInputStream(byte buf[]) {
  104           this.buf = buf;
  105           this.pos = 0;
  106           this.count = buf.length;
  107       }
  108   
  109       /**
  110        * Creates <code>ByteArrayInputStream</code>
  111        * that uses <code>buf</code> as its
  112        * buffer array. The initial value of <code>pos</code>
  113        * is <code>offset</code> and the initial value
  114        * of <code>count</code> is the minimum of <code>offset+length</code>
  115        * and <code>buf.length</code>.
  116        * The buffer array is not copied. The buffer's mark is
  117        * set to the specified offset.
  118        *
  119        * @param   buf      the input buffer.
  120        * @param   offset   the offset in the buffer of the first byte to read.
  121        * @param   length   the maximum number of bytes to read from the buffer.
  122        */
  123       public ByteArrayInputStream(byte buf[], int offset, int length) {
  124           this.buf = buf;
  125           this.pos = offset;
  126           this.count = Math.min(offset + length, buf.length);
  127           this.mark = offset;
  128       }
  129   
  130       /**
  131        * Reads the next byte of data from this input stream. The value
  132        * byte is returned as an <code>int</code> in the range
  133        * <code>0</code> to <code>255</code>. If no byte is available
  134        * because the end of the stream has been reached, the value
  135        * <code>-1</code> is returned.
  136        * <p>
  137        * This <code>read</code> method
  138        * cannot block.
  139        *
  140        * @return  the next byte of data, or <code>-1</code> if the end of the
  141        *          stream has been reached.
  142        */
  143       public synchronized int read() {
  144           return (pos < count) ? (buf[pos++] & 0xff) : -1;
  145       }
  146   
  147       /**
  148        * Reads up to <code>len</code> bytes of data into an array of bytes
  149        * from this input stream.
  150        * If <code>pos</code> equals <code>count</code>,
  151        * then <code>-1</code> is returned to indicate
  152        * end of file. Otherwise, the  number <code>k</code>
  153        * of bytes read is equal to the smaller of
  154        * <code>len</code> and <code>count-pos</code>.
  155        * If <code>k</code> is positive, then bytes
  156        * <code>buf[pos]</code> through <code>buf[pos+k-1]</code>
  157        * are copied into <code>b[off]</code>  through
  158        * <code>b[off+k-1]</code> in the manner performed
  159        * by <code>System.arraycopy</code>. The
  160        * value <code>k</code> is added into <code>pos</code>
  161        * and <code>k</code> is returned.
  162        * <p>
  163        * This <code>read</code> method cannot block.
  164        *
  165        * @param   b     the buffer into which the data is read.
  166        * @param   off   the start offset in the destination array <code>b</code>
  167        * @param   len   the maximum number of bytes read.
  168        * @return  the total number of bytes read into the buffer, or
  169        *          <code>-1</code> if there is no more data because the end of
  170        *          the stream has been reached.
  171        * @exception  NullPointerException If <code>b</code> is <code>null</code>.
  172        * @exception  IndexOutOfBoundsException If <code>off</code> is negative,
  173        * <code>len</code> is negative, or <code>len</code> is greater than
  174        * <code>b.length - off</code>
  175        */
  176       public synchronized int read(byte b[], int off, int len) {
  177           if (b == null) {
  178               throw new NullPointerException();
  179           } else if (off < 0 || len < 0 || len > b.length - off) {
  180               throw new IndexOutOfBoundsException();
  181           }
  182   
  183           if (pos >= count) {
  184               return -1;
  185           }
  186   
  187           int avail = count - pos;
  188           if (len > avail) {
  189               len = avail;
  190           }
  191           if (len <= 0) {
  192               return 0;
  193           }
  194           System.arraycopy(buf, pos, b, off, len);
  195           pos += len;
  196           return len;
  197       }
  198   
  199       /**
  200        * Skips <code>n</code> bytes of input from this input stream. Fewer
  201        * bytes might be skipped if the end of the input stream is reached.
  202        * The actual number <code>k</code>
  203        * of bytes to be skipped is equal to the smaller
  204        * of <code>n</code> and  <code>count-pos</code>.
  205        * The value <code>k</code> is added into <code>pos</code>
  206        * and <code>k</code> is returned.
  207        *
  208        * @param   n   the number of bytes to be skipped.
  209        * @return  the actual number of bytes skipped.
  210        */
  211       public synchronized long skip(long n) {
  212           long k = count - pos;
  213           if (n < k) {
  214               k = n < 0 ? 0 : n;
  215           }
  216   
  217           pos += k;
  218           return k;
  219       }
  220   
  221       /**
  222        * Returns the number of remaining bytes that can be read (or skipped over)
  223        * from this input stream.
  224        * <p>
  225        * The value returned is <code>count&nbsp;- pos</code>,
  226        * which is the number of bytes remaining to be read from the input buffer.
  227        *
  228        * @return  the number of remaining bytes that can be read (or skipped
  229        *          over) from this input stream without blocking.
  230        */
  231       public synchronized int available() {
  232           return count - pos;
  233       }
  234   
  235       /**
  236        * Tests if this <code>InputStream</code> supports mark/reset. The
  237        * <code>markSupported</code> method of <code>ByteArrayInputStream</code>
  238        * always returns <code>true</code>.
  239        *
  240        * @since   JDK1.1
  241        */
  242       public boolean markSupported() {
  243           return true;
  244       }
  245   
  246       /**
  247        * Set the current marked position in the stream.
  248        * ByteArrayInputStream objects are marked at position zero by
  249        * default when constructed.  They may be marked at another
  250        * position within the buffer by this method.
  251        * <p>
  252        * If no mark has been set, then the value of the mark is the
  253        * offset passed to the constructor (or 0 if the offset was not
  254        * supplied).
  255        *
  256        * <p> Note: The <code>readAheadLimit</code> for this class
  257        *  has no meaning.
  258        *
  259        * @since   JDK1.1
  260        */
  261       public void mark(int readAheadLimit) {
  262           mark = pos;
  263       }
  264   
  265       /**
  266        * Resets the buffer to the marked position.  The marked position
  267        * is 0 unless another position was marked or an offset was specified
  268        * in the constructor.
  269        */
  270       public synchronized void reset() {
  271           pos = mark;
  272       }
  273   
  274       /**
  275        * Closing a <tt>ByteArrayInputStream</tt> has no effect. The methods in
  276        * this class can be called after the stream has been closed without
  277        * generating an <tt>IOException</tt>.
  278        * <p>
  279        */
  280       public void close() throws IOException {
  281       }
  282   
  283   }

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