模块  java.base
软件包  java.io

Class InputStream

    • 构造方法摘要

      构造方法  
      构造器 描述
      InputStream()  
    • 方法摘要

      所有方法  静态方法  实例方法 抽象方法  具体的方法 
      变量和类型 方法 描述
      int available()
      返回可以从此输入流中无阻塞地读取(或跳过)的字节数的估计值,可以是0,或者在检测到流结束时为0。
      void close()
      关闭此输入流并释放与该流关联的所有系统资源。
      void mark​(int readlimit)
      标记此输入流中的当前位置。
      boolean markSupported()
      测试此输入流是否支持 markreset方法。
      static InputStream nullInputStream()
      返回一个不读取任何字节的新 InputStream
      abstract int read()
      从输入流中读取下一个数据字节。
      int read​(byte[] b)
      从输入流中读取一些字节数并将它们存储到缓冲区数组 b
      int read​(byte[] b, int off, int len)
      从输入流 len最多 len字节的数据读入一个字节数组。
      byte[] readAllBytes()
      从输入流中读取所有剩余字节。
      int readNBytes​(byte[] b, int off, int len)
      从输入流中读取请求的字节数到给定的字节数组中。
      byte[] readNBytes​(int len)
      从输入流中读取指定的字节数。
      void reset()
      将此流重新定位到上次在此输入流上调用 mark方法时的位置。
      long skip​(long n)
      跳过并丢弃此输入流中的 n字节数据。
      long transferTo​(OutputStream out)
      从该输入流中读取所有字节,并按读取顺序将字节写入给定的输出流。
    • 构造方法详细信息

      • 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)transferTo()方法的行为都好像流的末尾已到达。 关闭流后,这些方法全部抛出IOException

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

        结果
        InputStream ,不包含任何字节
        从以下版本开始:
        11
      • read

        public abstract int read()
                          throws IOException
        从输入流中读取下一个数据字节。 值字节返回int ,范围为0255 如果由于到达流末尾而没有可用字节,则返回值-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]不受影响。

        InputStreamread(b)方法具有与以下相同的效果:

           read(b, 0, b.length)  
        参数
        b - 读取数据的缓冲区。
        结果
        读入缓冲区的总字节数,如果由于已到达流末尾而没有更多数据, -1
        异常
        IOException - 如果由于文件末尾以外的任何原因无法读取第一个字节,如果输入流已关闭,或者发生某些其他I / O错误。
        NullPointerException - 如果 bnull
        另请参见:
        read(byte[], int, int)
      • read

        public int read​(byte[] b,
                        int off,
                        int len)
                 throws IOException
        从输入流len最多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]和元素b[off+len]b[b.length-1]不受影响。

        InputStreamread(b, off, len)方法只是重复调用方法read() 如果第一个此类调用导致IOException ,则从调用read(b, off, len)方法返回该异常。 如果对read()任何后续调用导致IOException ,则会捕获该异常并将其视为文件结束; 读取到该点的字节存储在b并返回异常发生前读取的字节数。 此方法的默认实现将阻塞,直到读取了所请求的输入数据量len ,检测到文件结尾或抛出异常为止。 鼓励子类提供更有效的此方法实现。

        参数
        b - 读取数据的缓冲区。
        off - 数据写入的数组 b中的起始偏移量。
        len - 要读取的最大字节数。
        结果
        读入缓冲区的总字节数,如果由于已到达流末尾而没有更多数据, -1
        异常
        IOException - 如果由于文件结尾以外的任何原因无法读取第一个字节,或者输入流已关闭,或者发生某些其他I / O错误。
        NullPointerException - 如果 bnull
        IndexOutOfBoundsException - 如果 off为负数,则 len为负数,或 len为大于 b.length - off
        另请参见:
        read()
      • readAllBytes

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

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

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

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

        如果从输入流中读取I / O错误,则可能在读取了一些但不是全部字节后执行此操作。 因此,输入流可能不在流的末尾并且可能处于不一致状态。 如果发生I / O错误,强烈建议立即关闭流。

        实现要求:
        此方法调用 readNBytes(int) ,长度为 Integer.MAX_VALUE
        结果
        包含从此输入流中读取的字节的字节数组
        异常
        IOException - 如果发生I / O错误
        OutOfMemoryError - 如果无法分配所需大小的数组。
        从以下版本开始:
        9
      • readNBytes

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

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

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

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

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

        如果从输入流中读取I / O错误,则可能在读取了一些但不是全部字节后执行此操作。 因此,输入流可能不在流的末尾并且可能处于不一致状态。 如果发生I / O错误,强烈建议立即关闭流。

        Implementation Note:
        分配给从此流中读取数据并返回结果的字节数由 2*(long)len (包括 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此操作。 因此,输入流和b可能处于不一致状态。 如果发生I / O错误,强烈建议立即关闭流。

        参数
        b - 读取数据的字节数组
        off - 写入数据的 b中的起始偏移量
        len - 要读取的最大字节数
        结果
        读入缓冲区的实际字节数
        异常
        IOException - 如果发生I / O错误
        NullPointerException - 如果 bnull
        IndexOutOfBoundsException - 如果 off是负数, len是负数,或 len是大于 b.length - off
        从以下版本开始:
        9
      • skip

        public long skip​(long n)
                  throws IOException
        跳过并从此输入流中丢弃n字节的数据。 出于各种原因, skip方法可能最终跳过一些较小数量的字节,可能是0 这可能是由许多条件造成的; 在跳过n个字节之前到达文件n只有一种可能性。 返回跳过的实际字节数。 如果n为负数,则类InputStreamskip方法始终返回0,并且不会跳过任何字节。 子类可以不同地处理负值。

        skip方法实现创建一个字节数组,然后重复读入它,直到读取了n个字节或已到达流的末尾。 鼓励子类提供更有效的此方法实现。 例如,实施可能取决于寻求的能力。

        参数
        n - 要跳过的字节数。
        结果
        跳过的实际字节数。
        异常
        IOException - 如果发生I / O错误。
      • available

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

        请注意,虽然InputStream某些实现将返回流中的总字节数,但许多实现不会。 使用此方法的返回值来分配用于保存此流中所有数据的缓冲区绝对不正确。

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

        available的方法InputStream总是返回0

        子类应该重写此方法。

        结果
        估计可以从此输入流中无阻塞地读取(或跳过)的字节数,或者当达到输入流末尾时可以读取 0
        异常
        IOException - 如果发生I / O错误。
      • close

        public void close()
                   throws IOException
        关闭此输入流并释放与该流关联的所有系统资源。

        close的方法InputStream什么都不做。

        Specified by:
        close在接口 AutoCloseable
        Specified by:
        close在接口 Closeable
        异常
        IOException - 如果发生I / O错误。
      • mark

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

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

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

        标记封闭流不应对流产生任何影响。

        mark的方法InputStream什么都不做。

        参数
        readlimit - 标记位置变为无效之前可读取的最大字节数限制。
        另请参见:
        reset()
      • 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方法的后续调用方的read取决于输入流的特定类型。

        InputStream的方法reset除了抛出IOException之外什么都不IOException

        异常
        IOException - 如果此流未标记或标记已失效。
        另请参见:
        mark(int)IOException
      • markSupported

        public boolean markSupported()
        测试此输入流是否支持markreset方法。 是否支持markreset是特定输入流实例的不变属性。 markSupported的方法InputStream返回false
        结果
        true此流实例是否支持mark和reset方法; 否则为false
        另请参见:
        mark(int)reset()
      • transferTo

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

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

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

        参数
        out - 输出流,非空
        结果
        传输的字节数
        异常
        IOException - 如果在读取或写入时发生I / O错误
        NullPointerException - 如果 outnull
        从以下版本开始:
        9