Module java.base
Package java.io

Class 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
参见:

  • Constructor Summary

    Constructors
    Constructor
    Description
    InputStream()
    子类调用的构造函数。

  • Method Summary

    Modifier and Type
    Method
    Description
    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)
    从此输入流中读取所有字节，并按照读取顺序将字节写入给定的输出流。

    Methods declared in class java.lang.Object

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

  • Constructor Details

    • InputStream

      public InputStream()
      子类调用的构造函数。

  • Method Details

    • 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错误时立即关闭流。

      实现注意事项:
      从此类的skip方法使用长度为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。
      返回值:
      如果此流实例支持mark和reset方法，则返回true；否则返回false。
      参见:

    • transferTo

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

      此方法可能会无限期地阻塞从输入流读取，或向输出流写入。在输入和/或输出流异步关闭或传输过程中线程中断的情况下的行为是高度依赖于输入和输出流的具体情况，因此未指定。

      如果传输的总字节数大于Long.MAX_VALUE，则将返回Long.MAX_VALUE。

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

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