模块 java.base
包 java.io

类 InputStream

java.lang.Object
java.io.InputStream
所有已实现的接口：
Closeable , AutoCloseable
已知子类：
AudioInputStream , ByteArrayInputStream , FileInputStream , FilterInputStream , ObjectInputStream , PipedInputStream , SequenceInputStream , StringBufferInputStream
public abstract class InputStream extends Object implements Closeable
这个抽象类是所有表示字节输入流的类的超类。

需要定义 InputStream 子类的应用程序必须始终提供返回下一个输入字节的方法。

自从：
1.0
参见：

  • 构造方法总结

    构造方法
    构造方法
    描述
    InputStream()
    子类调用的构造方法。

  • 方法总结

    修饰符和类型
    方法
    描述
    int
    available()
    返回可以从此输入流读取（或跳过）而不阻塞的字节数的估计值，它可能是 0，或者当检测到流结束时为 0。
    void
    close()
    关闭此输入流并释放与该流关联的所有系统资源。
    void
    mark(int readlimit)
    标记此输入流中的当前位置。
    boolean
    markSupported()
    测试此输入流是否支持 mark 和 reset 方法。
    static InputStream
    nullInputStream()
    返回一个不读取任何字节的新 InputStream。
    abstract int
    read()
    从输入流中读取下一个字节的数据。
    int
    read(byte[] b)
    从输入流中读取一定数量的字节并将它们存储到缓冲区数组 b 中。
    int
    read(byte[] b, int off, int len)
    从输入流中读取最多 len 字节的数据到字节数组中。
    byte[]
    readAllBytes()
    从输入流中读取所有剩余字节。
    int
    readNBytes(byte[] b, int off, int len)
    从输入流中将请求的字节数读取到给定的字节数组中。
    byte[]
    readNBytes(int len)
    从输入流中读取指定数量的字节。
    void
    reset()
    将此流重新定位到上次对此输入流调用 mark 方法时的位置。
    long
    skip(long n)
    跳过并丢弃此输入流中的 n 字节数据。
    void
    skipNBytes(long n)
    跳过并丢弃来自该输入流的 n 个字节的数据。
    long
    transferTo(OutputStream out)
    从此输入流中读取所有字节，并按照读取顺序将字节写入给定的输出流。

    在类 java.lang.Object 中声明的方法

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • 构造方法详细信息

    • InputStream

      public InputStream()
      子类调用的构造方法。

  • 方法详情

    • nullInputStream

      public static InputStream  nullInputStream()
      返回一个不读取任何字节的新 InputStream。返回的流最初是打开的。通过调用 close() 方法关闭流。对 close() 的后续调用无效。

      当流打开时，available()、read()、read(byte[])、read(byte[], int, int)、readAllBytes()、readNBytes(byte[], int, int)、readNBytes(int)、skip(long)、skipNBytes(long)和transferTo() 方法都表现得好像已到达流的末尾。流关闭后，这些方法都会抛出 IOException 。

      markSupported() 方法返回 false 。 mark() 方法什么都不做，reset() 方法抛出 IOException 。

      返回：
      一个不包含字节的 InputStream
      自从：
      11

    • read

      public abstract int read() throws IOException
      从输入流中读取下一个字节的数据。值字节作为 int 在 0 到 255 范围内返回。如果因为已到达流的末尾而没有可用字节，则返回值 -1。此方法会阻塞，直到输入数据可用、检测到流结束或抛出异常为止。
      返回：
      下一个数据字节，如果到达流的末尾则为 -1。
      抛出：
      IOException - 如果发生 I/O 错误。

    • read

      public int read(byte[] b) throws IOException
      从输入流中读取一定数量的字节并将它们存储到缓冲区数组 b 中。实际读取的字节数作为整数返回。此方法会阻塞，直到输入数据可用、检测到文件结尾或抛出异常为止。

      如果 b 的长度为零，则不读取任何字节并返回 0；否则，将尝试读取至少一个字节。如果由于流位于文件末尾而没有可用字节，则返回值 -1；否则，至少读取一个字节并将其存储到 b 中。

      读取的第一个字节存储到元素 b[0] 中，下一个字节存储到 b[1] 中，依此类推。读取的字节数最多等于 b 的长度。让k是实际读取的字节数；这些字节将存储在元素 b[0] 到 b[ 中k-1]，留下元素 b[k] 到 b[b.length-1] 不受影响。

      实现要求：
      类 InputStream 的 read(b) 方法具有与以下相同的效果： 
       read(b, 0, b.length)
      参数：
      b - 读取数据的缓冲区。
      返回：
      读入缓冲区的字节总数，如果因为已到达流的末尾而没有更多数据，则为 -1。
      抛出：
      IOException - 如果第一个字节由于文件末尾以外的任何原因无法读取，如果输入流已关闭，或者如果发生其他一些 I/O 错误。
      NullPointerException - 如果 b 是 null。
      参见：

    • read

      public int read(byte[] b, int off, int len) throws IOException
      从输入流中读取最多 len 字节的数据到字节数组中。尝试读取多达 len 个字节，但可能会读取较小的数字。实际读取的字节数作为整数返回。

      此方法会阻塞，直到输入数据可用、检测到文件结尾或抛出异常为止。

      如果 len 为零，则不读取任何字节并返回 0；否则，将尝试读取至少一个字节。如果由于流位于文件末尾而没有可用字节，则返回值 -1；否则，至少读取一个字节并将其存储到 b 中。

      读取的第一个字节存储到元素 b[off] 中，下一个字节存储到 b[off+1] 中，依此类推。读取的字节数最多等于 len 。让k是实际读取的字节数；这些字节将存储在元素 b[off] 到 b[off+ 中k-1]，留下元素 b[off+k] 到 b[off+len-1] 不受影响。

      在每种情况下，元素 b[0] 到 b[off-1] 和元素 b[off+len] 到 b[b.length-1] 都不受影响。

      实现要求：
      类 InputStream 的 read(b, off, len) 方法只是重复调用方法 read()。如果第一个此类调用导致 IOException ，则从对 read(b, off, len) 方法的调用返回该异常。如果对 read() 的任何后续调用导致 IOException ，异常将被捕获并被视为文件末尾；到该点为止读取的字节存储到 b 中，并返回异常发生前读取的字节数。此方法的默认实现会阻塞，直到读取了请求的输入数据量 len、检测到文件末尾或抛出异常。鼓励子类提供此方法的更有效实现。
      参数：
      b - 读取数据的缓冲区。
      off - 写入数据的数组 b 中的起始偏移量。
      len - 要读取的最大字节数。
      返回：
      读入缓冲区的字节总数，如果因为已到达流的末尾而没有更多数据，则为 -1。
      抛出：
      IOException - 如果第一个字节由于文件末尾以外的任何原因无法读取，或者输入流已关闭，或者发生其他一些 I/O 错误。
      NullPointerException - 如果 b 是 null。
      IndexOutOfBoundsException - 如果 off 为负，len 为负，或者 len 大于 b.length - off
      参见：

    • readAllBytes

      public byte[] readAllBytes() throws IOException
      从输入流中读取所有剩余字节。此方法会阻塞，直到读取完所有剩余字节并检测到流结束，或者抛出异常。此方法不会关闭输入流。

      当此流到达流的末尾时，进一步调用此方法将返回一个空字节数组。

      请注意，此方法适用于方便将所有字节读入字节数组的简单情况。它不适用于读取具有大量数据的输入流。

      输入流为异步关闭，或读取期间中断的线程，是高度特定于输入流的，因此未指定。

      如果从输入流读取时发生 I/O 错误，那么它可能会在读取了一些（但不是全部）字节后这样做。因此，输入流可能不在流的末尾并且可能处于不一致状态。强烈建议在发生 I/O 错误时立即关闭流。

      实现要求：
      此方法调用长度为 Integer.MAX_VALUE 的 readNBytes(int) 。
      返回：
      包含从此输入流读取的字节的字节数组
      抛出：
      IOException - 如果发生 I/O 错误
      OutOfMemoryError - 如果无法分配所需大小的数组。
      自从：
      9

    • readNBytes

      public byte[] readNBytes(int len) throws IOException
      从输入流中读取指定数量的字节。此方法会阻塞，直到已读取请求的字节数、检测到流结尾或抛出异常。此方法不会关闭输入流。

      返回数组的长度等于从流中读取的字节数。如果 len 为零，则不读取任何字节并返回一个空字节数组。否则，最多会从流中读取 len 个字节。如果遇到流结尾，可能会读取少于 len 个字节。

      当此流到达流的末尾时，进一步调用此方法将返回一个空字节数组。

      请注意，此方法适用于方便将指定数量的字节读入字节数组的简单情况。此方法分配的内存总量与从 len 限定的流中读取的字节数成正比。因此，如果有足够的可用内存，可以使用非常大的 len 值安全地调用该方法。

      输入流为异步关闭，或读取期间中断的线程，是高度特定于输入流的，因此未指定。

      如果从输入流读取时发生 I/O 错误，那么它可能会在读取了一些（但不是全部）字节后这样做。因此，输入流可能不在流的末尾并且可能处于不一致状态。强烈建议在发生 I/O 错误时立即关闭流。

      实现注意事项：
      分配用于从此流中读取数据并返回结果的字节数受 2*(long)len 限制（含）。
      参数：
      len - 要读取的最大字节数
      返回：
      包含从此输入流读取的字节的字节数组
      抛出：
      IllegalArgumentException - 如果 length 为负
      IOException - 如果发生 I/O 错误
      OutOfMemoryError - 如果无法分配所需大小的数组。
      自从：
      11

    • readNBytes

      public int readNBytes(byte[] b, int off, int len) throws IOException
      从输入流中将请求的字节数读取到给定的字节数组中。此方法会阻塞，直到读取了 len 字节的输入数据、检测到流结束或抛出异常。返回实际读取的字节数，可能为零。此方法不会关闭输入流。

      如果在读取 len 字节之前到达流末尾，则将返回读取的实际字节数。当此流到达流的末尾时，此方法的进一步调用将返回零。

      如果 len 为零，则不读取任何字节并返回 0；否则，将尝试读取最多 len 个字节。

      读取的第一个字节存储到元素 b[off] 中，下一个字节存储到 b[off+1] 中，依此类推。读取的字节数最多等于 len 。让k是实际读取的字节数；这些字节将存储在元素 b[off] 到 b[off+ 中k-1]，留下元素 b[off+k] 到 b[off+len-1] 不受影响。

      输入流为异步关闭，或读取期间中断的线程，是高度特定于输入流的，因此未指定。

      如果从输入流读取时发生 I/O 错误，那么它可能会在 b 的一些（但不是全部）字节已用输入流中的数据更新后执行此操作。因此，输入流和 b 可能处于不一致状态。强烈建议在发生 I/O 错误时立即关闭流。

      参数：
      b - 读取数据的字节数组
      off - 写入数据的 b 中的起始偏移量
      len - 要读取的最大字节数
      返回：
      读入缓冲区的实际字节数
      抛出：
      IOException - 如果发生 I/O 错误
      NullPointerException - 如果 b 是 null
      IndexOutOfBoundsException - 如果 off 为负，len 为负，或者 len 大于 b.length - off
      自从：
      9

    • skip

      public long skip(long n) throws IOException
      跳过并丢弃此输入流中的 n 字节数据。由于各种原因，skip 方法可能最终会跳过一些较少的字节，可能是 0。这可能是由多种情况中的任何一种引起的；在跳过 n 字节之前到达文件末尾只是一种可能性。返回实际跳过的字节数。如果 n 为负，则类 InputStream 的 skip 方法始终返回 0，并且不会跳过任何字节。子类可能会以不同方式处理负值。
      实现要求：
      此类的 skip 方法实现创建一个字节数组，然后重复读入它，直到读取了 n 个字节或到达流的末尾。鼓励子类提供此方法的更有效实现。例如，实施可能取决于寻求的能力。
      参数：
      n - 要跳过的字节数。
      返回：
      实际跳过的字节数可能为零。
      抛出：
      IOException - 如果发生 I/O 错误。
      参见：

    • skipNBytes

      public void skipNBytes(long n) throws IOException
      跳过并丢弃来自该输入流的 n 个字节的数据。如果n 为零，则不会跳过任何字节。如果 n 为负，则不会跳过任何字节。子类可能会以不同方式处理负值。

      此方法会阻塞，直到跳过请求的字节数、到达文件末尾或抛出异常。

      如果在流到达所需位置之前到达流末尾，则会抛出 EOFException。

      如果发生 I/O 错误，则输入流可能处于不一致状态。强烈建议在发生 I/O 错误时立即关闭流。

      实现要求：
      如果 n 为零或负数，则不会跳过任何字节。如果 n 为正，则此方法的默认实现重复调用 skip() ，其参数等于要跳过的剩余字节数，直到已跳过请求的字节数或发生错误情况。如果在任何时候 skip() 的返回值是负数或大于要跳过的剩余字节数，则抛出 IOException。如果 skip() 返回零，则调用 read() 读取单个字节，如果它返回 -1，则抛出 EOFException。 skip() 或 read() 抛出的任何异常都将被传播。
      实现注意事项：
      鼓励子类提供此方法的更有效实现。
      参数：
      n - 要跳过的字节数。
      抛出：
      EOFException - 如果在调用此方法时将流定位到超出其位置 n 字节之前遇到流末尾。
      IOException - 如果流无法正确定位或发生 I/O 错误。
      自从：
      12
      参见：

    • available

      public int available() throws IOException
      返回可以从此输入流读取（或跳过）而不阻塞的字节数的估计值，它可能是 0，或者当检测到流结束时为 0。读取可能在同一个线程或另一个线程上。单次读取或跳过这么多字节不会阻塞，但可能会读取或跳过更少的字节。

      请注意，虽然 InputStream 的某些实现会返回流中的总字节数，但很多不会。使用此方法的返回值来分配旨在保存此流中所有数据的缓冲区是永远不正确的。

      如果此输入流已通过调用 close() 方法关闭，则此方法的子类实现可以选择抛出 IOException 。

      API 注意：
      这个方法应该被子类重写。
      实现要求：
      InputStream 的 available 方法总是返回 0 。
      返回：
      可以从此输入流中读取（或跳过）的字节数的估计值，而不会阻塞或0当它到达输入流的末尾时。
      抛出：
      IOException - 如果发生 I/O 错误。

    • close

      public void close() throws IOException
      关闭此输入流并释放与该流关联的所有系统资源。
      指定者：
      close 在接口 AutoCloseable 中
      指定者：
      close 在接口 Closeable 中
      实现要求：
      InputStream 的 close 方法什么都不做。
      抛出：
      IOException - 如果发生 I/O 错误。

    • mark

      public void mark(int readlimit)
      标记此输入流中的当前位置。对 reset 方法的后续调用将此流重新定位在最后标记的位置，以便后续读取重新读取相同的字节。

      readlimit 参数告诉此输入流允许在标记位置失效之前读取那么多字节。

      mark 的一般契约是，如果方法 markSupported 返回 true ，流会以某种方式记住调用 mark 后读取的所有字节，并随时准备在调用方法 reset 时再次提供这些相同的字节。但是，如果在调用 reset 之前从流中读取了超过 readlimit 个字节，则流根本不需要记住任何数据。

      标记一个关闭的流不应该对流有任何影响。

      实现要求：
      InputStream 的 mark 方法什么都不做。
      参数：
      readlimit - 在标记位置变为无效之前可以读取的最大字节数限制。
      参见：

    • reset

      public void reset() throws IOException
      将此流重新定位到上次对此输入流调用 mark 方法时的位置。

      reset的总合同为：

      • 如果方法 markSupported 返回 true ，那么：
        • 如果自创建流以来尚未调用方法 mark，或者自上次调用 mark 以来从流中读取的字节数大于上次调用时 mark 的参数，则可能会抛出 IOException。
        • 如果没有抛出这样的 IOException，则流将重置为这样一种状态，即自最近调用 mark（或自文件开始，如果未调用 mark）以来读取的所有字节将被重新提供给后续read 方法的调用者，后跟任何字节，否则这些字节将成为调用 reset 时的下一个输入数据。
      • 如果方法 markSupported 返回 false ，那么：
        • 调用 reset 可能会抛出一个 IOException 。
        • 如果未抛出 IOException，则流将重置为固定状态，该状态取决于输入流的特定类型及其创建方式。将提供给 read 方法的后续调用者的字节取决于输入流的特定类型。
      实现要求：
      类 InputStream 的方法 reset 除了抛出一个 IOException 之外什么都不做。
      抛出：
      IOException - 如果此流未被标记或标记已失效。
      参见：

    • markSupported

      public boolean markSupported()
      测试此输入流是否支持 mark 和 reset 方法。是否支持 mark 和 reset 是特定输入流实例的不变属性。
      实现要求：
      InputStream 的 markSupported 方法返回 false 。
      返回：
      true 如果这个流实例支持标记和重置方法； false否则。
      参见：

    • transferTo

      public long transferTo(OutputStream  out) throws IOException
      从此输入流中读取所有字节，并按照读取顺序将字节写入给定的输出流。返回时，此输入流将位于流的末尾。此方法不会关闭任何一个流。

      此方法可能会无限期地阻止从输入流读取或写入输出流。输入和/或输出流为异步关闭，或传输期间中断的线程，是高度输入和输出流特定的，因此未指定。

      如果从输入流读取或写入输出流发生 I/O 错误，那么它可能会在读取或写入一些字节后发生错误。因此，输入流可能不在流的末尾，并且一个或两个流可能处于不一致状态。强烈建议在发生 I/O 错误时立即关闭两个流。

      参数：
      out - 输出流，非空
      返回：
      传输的字节数
      抛出：
      IOException - 如果读取或写入时发生 I/O 错误
      NullPointerException - 如果 out 是 null
      自从：
      9