【给JDK IO源码加点注释】01 InputStream、OutputStream

InputStream

package java.io;

import java.util.Arrays;
import java.util.Objects;
抽象方法实现了closeable接口，可以在try with resource中使用。
public abstract class InputStream implements Closeable {
    跳过缓存数组的最大值
    private static final int MAX_SKIP_BUFFER_SIZE = 2048;
    默认缓存数组大小
    private static final int DEFAULT_BUFFER_SIZE = 8192;

    /**
     *读取流中下一个字节（0-255）。如果读完返回-1.此方法会导致阻塞。
     *
     * 抽象方法，子类必须提供此方法的实现.
     *
     * @return     流中下一个字节或者-1（当读取完时）
     *
     * @exception  IOException  if an I/O error occurs.
     */
    public abstract int read() throws IOException;

    /**
     
　    *试图读入多个字节，存入字节数组b，返回实际读入的字节数。
        *如果传递的是一个空数组（注意数组长度可以为0，即空数组。比如 byte[] b = new  byte[0]; 或者byte[] b = {};）
        *那么什么也没读入，返回0.
　　 *如果到达流尾部，没有字节可读，返回-1；如果上面两种情况都没有出现，并且没有I/O错误，则至少有1个字节被读入，存储到字节数组b中。
        *实际读入的第一个字节存在b[0]，往后一次存入数组，读入的字节数最多不能超过数组b的长度。
        *如果读入的字节数小于b的长度，剩余的数组元素保持不 变。具体地，如果读入的字节数为k，则k个字节分别存在 b[0]到b[k-1]，而b[k]到                        *b[b.length-1]保持原来的数据。
     *
     * 此方法与read(b, 0, b.length)效果相同
     *
     * @param      存储读取字节的数组
     * @return     0 如果传入的数组为空
     *             -1 此输入流没有字节可读取了
     *             int 实际读取的字节数
     * @exception  IOException 
     * @exception  NullPointerException  传入数组b[]没有初始化
     */
    public int read(byte b[]) throws IOException {
        return read(b, 0, b.length);
    }

    /**
     *读入的数据存储到b数组是从off开始。len是试图读入的字节数，返回的是实际读入的字节数。
         *如果len=0，则什么也不读入，返回0；如果遇到流尾部，返回-1.否则至少读入一个字节。
     *
     * 第一个读取的字节存储到 b[off]中 , 下一个在b[off+1]，直到b[off+len-1]（数据量大于len时）.
     *
     *
     * @param      b     存储读取字节的数组
     * @param      off   开始存放第一个读取数据的位置
     *                   
     * @param      len   最大的字节数.
     * @return     0    如果len为0
     *             -1    流中已经没有数据。
     *             int    实际读取的字节数（最大为len）
     * @exception  IOException 
     * @exception  NullPointerException b[]为null
     * @exception  IndexOutOfBoundsException off，len为负数 或者 len大于b.length - off
         */
    public int read(byte b[], int off, int len) throws IOException {
        if (b == null) {
            throw new NullPointerException();
        } else if (off < 0 || len < 0 || len > b.length - off) {
            throw new IndexOutOfBoundsException();
        } else if (len == 0) {
            return 0;
        }

        int c = read();
        if (c == -1) {
            return -1;
        }
        b[off] = (byte)c;

        int i = 1;
        try {
            for (; i < len ; i++) {
                c = read();
                if (c == -1) {
                    break;
                }
                b[off + i] = (byte)c;
            }
        } catch (IOException ee) {
        }
        return i;
    }

    /**
     * 缓存数组最大值
     */
    private static final int MAX_BUFFER_SIZE = Integer.MAX_VALUE - 8;

    /**
     * 读取流中剩下的全部字节
     *
     * 当流中没有数据时返回空的数组
     *
     *
     * @return byte[] 流中全部字节
     * @throws IOException if an I/O error occurs
     * @throws OutOfMemoryError 当流中字节数大于Integer.MAX_VALUE - 8时，即数据大于2gb
     *
     * jdk9新增的方法
     */
    public byte[] readAllBytes() throws IOException {
        //创建一个缓存数组，用于存放读取的数据。
        byte[] buf = new byte[DEFAULT_BUFFER_SIZE];
        //读取的数据量
        int capacity = buf.length;
        //已经读取数据量
        int nread = 0;
        //一次读取的数量
        int n;
        //死循环读取数据相当于while(true)
        for (;;) {
            // 当流中还有数据，缓存数组未读满时，调用read方法读取数据到buf中
            while ((n = read(buf, nread, capacity - nread)) > 0)
                nread += n;

            // 流中数据已读完，跳出死循环
            if (n < 0)
                break;

            // 未跳出说明缓存数组已满需要扩大数组
            if (capacity <= MAX_BUFFER_SIZE - capacity) {
                capacity = capacity << 1;
            } else {
                if (capacity == MAX_BUFFER_SIZE)
                    throw new OutOfMemoryError("Required array size too large");
                capacity = MAX_BUFFER_SIZE;
            }
            buf = Arrays.copyOf(buf, capacity);
        }
        //返回
        return (capacity == nread) ? buf : Arrays.copyOf(buf, nread);
    }

    /**
     *  从 InputStream 中读取指定数量的字节到数组中与read(byte[] b,int off ,int len)相似
     */
    public int readNBytes(byte[] b, int off, int len) throws IOException {
        Objects.requireNonNull(b);
        if (off < 0 || len < 0 || len > b.length - off)
            throw new IndexOutOfBoundsException();
        int n = 0;
        while (n < len) {
            int count = read(b, off + n, len - n);
            if (count < 0)
                break;
            n += count;
        }
        return n;
    }

    /**
     * 试图跳过n个字节，返回实际跳过字节数的方法
     * 例如流中只有6个字节，传入7只能跳过6，所以返回6.
     * @param      n   试图跳过的字节数.
     * @return     the 实际跳过的字节数.
     * @throws     IOException .
     */
    public long skip(long n) throws IOException {
        
        long remaining = n;
        int nr;

        if (n <= 0) {
            return 0;
        }

        int size = (int)Math.min(MAX_SKIP_BUFFER_SIZE, remaining);
        byte[] skipBuffer = new byte[size];
        while (remaining > 0) {
            nr = read(skipBuffer, 0, (int)Math.min(size, remaining));
            if (nr < 0) {
                break;
            }
            remaining -= nr;
        }

        return n - remaining;
    }

    /**
     * 返回流中可读取的字节数，具体由子类实现
     */
    public int available() throws IOException {
        return 0;
    }

    /**
     * 关闭流
     * @exception  IOException  if an I/O error occurs.
     */
    public void close() throws IOException {}

    /**
     * 在当前位置定义一个标记，使用reset可以会到标记处，可以进行数据的重复读取。
     * 
     *
     * <p> Marking a closed stream should not have any effect on the stream.
     *
     * <p> The <code>mark</code> method of <code>InputStream</code> does
     * nothing.
     *
     * @param   readlimit   在标记后最大可读取数，超过此数字，标记过期，不允许reset。
     *                      
     * @see     java.io.InputStream#reset()
     */
    public synchronized void mark(int readlimit) {}

    /**
     * 用于重定位到最近的标记。如果在这之前mark方法从来没被调用，或者标记已经无效，在抛出IOException。
         *   如果没有抛出这个异常，将当前位置重新定位到最近的标记位置。
     *
     * @exception  如果流未被标记。
     * @see     java.io.InputStream#mark(int)
     * @see     java.io.IOException
     */
    public synchronized void reset() throws IOException {
        throw new IOException("mark/reset not supported");
    }

    /**
     *返回流是否支持标记，默认未false。
     */
    public boolean markSupported() {
        return false;
    }

    /**
     * 读取流中所有数据并写入到传入的输出流中
     * @param  目标输出流
     * @return 写入到输出流中的数据量
     * @throws IOException 
     * @throws NullPointerException 当out为null时
     *
     * @since 9
     */
    public long transferTo(OutputStream out) throws IOException {
        Objects.requireNonNull(out, "out");
        long transferred = 0;
        byte[] buffer = new byte[DEFAULT_BUFFER_SIZE];
        int read;
        while ((read = this.read(buffer, 0, DEFAULT_BUFFER_SIZE)) >= 0) {
            out.write(buffer, 0, read);
            transferred += read;
        }
        return transferred;
    }
}

OutputStream

package java.io;
/**
* 输出字节流抽象类
*/
public abstract class OutputStream implements Closeable, Flushable {
    /**
     * 向流中写入特定的字节，截取低8位，忽略高24位。
     *
     * @param      b   待写入字节。
     * @exception  IOException  
     */
    public abstract void write(int b) throws IOException;

    /**
     * 向流中写入一个字节数组。
     *
     * @param      b   待写入字节数组。
     * @exception  IOException  
     * @see        java.io.OutputStream#write(byte[], int, int)
     */
    public void write(byte b[]) throws IOException {
        write(b, 0, b.length);
    }

    /**
     * 将 b[]中off开始len个字节写入输出流中，即b[off]到b[off+len-1]。
     * <p>
     * 如果b为null会抛出空指针异常
     * 如果off，len为负,或者off+len比数组的长度大将抛出IndexOutOfBoundsException
     *
     * @param      b     字节数组
     * @param      off   写入的其实位置
     * @param      len   写入的字节数
     * @exception  IOException 
     */
    public void write(byte b[], int off, int len) throws IOException {
        if (b == null) {
            throw new NullPointerException();
        } else if ((off < 0) || (off > b.length) || (len < 0) ||
                   ((off + len) > b.length) || ((off + len) < 0)) {
            throw new IndexOutOfBoundsException();
        } else if (len == 0) {
            return;
        }
        for (int i = 0 ; i < len ; i++) {
            write(b[off + i]);
        }
    }


    public void flush() throws IOException {
    }

    /**
     * 关闭此输出流并释放资源。
     * @exception  IOException
     */
    public void close() throws IOException {
    }

}