Класс 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
См. также:: BufferedInputStream, ByteArrayInputStream, DataInputStream, FilterInputStream, read(), OutputStream, PushbackInputStream

Краткое описание конструкторов

Конструктор	Описание
`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` байтов данных из этого потока ввода.
`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), и transferTo() ведут себя так, как если бы конец потока был достигнут. После закрытия потока эти методы выбрасывают IOException.

Метод markSupported() возвращает false. Метод mark() ничего не делает, а метод reset() выбрасывает IOException.

Возвращает:: a InputStream, содержащий не байтов
С момента:: 11

read

public abstract int read()
                  throws IOException

Считывает следующий байт данных из потока ввода. Значение байта возвращается как int в диапазоне 0 до 255. Если байт недоступен из-за достижения конца потока, возвращается значение -1. Этот метод блокируется до тех пор, пока данные ввода не станут доступными, не будет обнаружен конец потока или не будет выброшено исключение.

Подкласс должен предоставить реализацию этого метода.

Возвращает:: следующий байт данных или -1, если достигнут конец потока.
Выбрасывает:: IOException - если произошла ошибка ввода-вывода.

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] неизменными.

Метод read(b) для класса InputStream имеет тот же эффект, что и:

read(b, 0, b.length)

Параметры:: b - буфер, в который считываются данные.
Возвращает:: общее количество байтов, прочитанных в буфер, или -1, если больше нет данных из-за достижения конца потока.
Выбрасывает:: IOException - если первый байт не может быть прочитан по какой-либо причине, кроме конца файла, если поток ввода закрыт или произошла ошибка ввода-вывода.; NullPointerException - если b равен null.
См. также:: read(byte[], int, int)

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] и элементы b[off+len] через b[b.length-1] остаются неизменными.

Метод read(b, off, len) для класса InputStream просто многократно вызывает метод read(). Если первый такой вызов приводит к IOException, то это исключение возвращается из вызова метода read(b, off, len). Если любой последующий вызов read() приводит к IOException, исключение перехватывается и обрабатывается как конец файла; прочитанные до этого момента байты сохраняются в b, а количество байтов, прочитанных до возникновения исключения, возвращается. По умолчанию реализация этого метода блокируется до тех пор, пока не будет прочитано необходимое количество входных данных len, не будет обнаружен конец файла или не будет выброшено исключение. Подклассы рекомендуются предоставить более эффективную реализацию этого метода.

Параметры:: b - буфер, в который считываются данные.; off - начальный смещение в массиве b для записи данных.; len - максимальное количество байтов для чтения.
Возвращает:: общее количество байтов, прочитанных в буфер, или -1, если больше нет данных из-за достижения конца потока.
Выбрасывает:: IOException - Если первый байт не может быть прочитан по какой-либо причине, кроме конца файла, или если поток ввода закрыт, или произошла другая ошибка ввода-вывода.; NullPointerException - Если b равно null.; IndexOutOfBoundsException - Если off отрицательно, len отрицательно или len больше b.length - off.
См. также:: read()

readAllBytes

public byte[] readAllBytes()
                    throws IOException

Считывает все оставшиеся байты из потока ввода. Этот метод блокируется до тех пор, пока все оставшиеся байты не будут прочитаны и не будет обнаружен конец потока, или не будет выброшено исключение. Этот метод не закрывает поток ввода.

Когда этот поток достигает конца потока, дальнейшие вызовы этого метода будут возвращать пустой массив байтов.

Обратите внимание, что этот метод предназначен для простых случаев, когда удобно прочитать все байты в массив байтов. Он не предназначен для чтения потоков ввода с большим объемом данных.

Поведение в случае, когда поток ввода асинхронно закрыт, или поток прерван во время чтения, сильно зависит от конкретного потока ввода и поэтому не определено.

Если при чтении из потока ввода произошла ошибка ввода-вывода, то это может произойти после чтения некоторых, но не всех, байтов. Следовательно, поток ввода может не находиться в конце потока и может быть в несогласованном состоянии. Сильно рекомендуется немедленно закрыть поток, если произошла ошибка ввода-вывода.

Требования к реализации:: Этот метод вызывает readNBytes(int) с длиной Integer.MAX_VALUE.
Возвращает:: массив байтов, содержащий байты, прочитанные из этого потока ввода
Выбрасывает:: IOException - если произошла ошибка ввода-вывода; OutOfMemoryError - если массив требуемого размера не может быть выделен.
С момента:: 9

readNBytes

public byte[] readNBytes(int len)
                  throws IOException

Считывает до указанного количества байтов из потока ввода. Этот метод блокируется до тех пор, пока не будет прочитано запрошенное количество байтов, не будет обнаружен конец потока или не будет выброшено исключение. Этот метод не закрывает поток ввода.

Длина возвращаемого массива равна количеству прочитанных байтов из потока. Если len равно нулю, то байты не считываются и возвращается пустой массив байтов. В противном случае считывается до len байтов из потока. Меньше чем len байтов может быть прочитано, если встречен конец потока.

Обратите внимание, что этот метод предназначен для простых случаев, когда удобно прочитать указанное количество байтов в массив байтов. Общий объем памяти, выделяемый этим методом, пропорционален количеству прочитанных байтов из потока, который ограничен len. Таким образом, метод можно безопасно вызывать с очень большими значениями len при условии достаточного объема памяти.

Примечание по реализации:: Количество байтов, выделенных для чтения данных из этого потока и возвращения результата, ограничено 2*(long)len, включительно.
Параметры:: len - максимальное количество байтов для чтения
Возвращает:: массив байтов, содержащий байты, прочитанные из этого потока ввода
Выбрасывает:: IllegalArgumentException - если length отрицательно; IOException - если произошла ошибка ввода-вывода; 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] неизменными.

Поведение в случае, когда входной поток асинхронно закрывается или поток прерывается во время чтения, сильно зависит от входного потока и поэтому не определено.

Если при чтении из входного потока возникает ошибка ввода-вывода, она может произойти после обновления некоторых, но не всех, байтов b данными из входного потока. В результате входной поток и b могут оказаться в несогласованном состоянии. Сильно рекомендуется немедленно закрыть поток, если произошла ошибка ввода-вывода.

Параметры:: b - массив байтов, в который считываются данные; off - начальный смещение в b , где записываются данные; len - максимальное количество байтов для чтения
Возвращает:: фактическое количество байтов, прочитанных в буфер
Выбрасывает:: IOException - если произошла ошибка ввода-вывода; NullPointerException - если b равно null; IndexOutOfBoundsException - Если off отрицательно, len отрицательно или len больше b.length - off
С:: 9

skip

public long skip(long n)
          throws IOException

Пропускает и отбрасывает n байтов данных из этого входного потока. Метод skip может по различным причинам пропустить меньшее количество байтов, возможно 0. Это может произойти по ряду причин; достижение конца файла до того, как было пропущено n байтов, — лишь один из вариантов. Возвращается фактическое количество пропущенных байтов. Если n отрицательно, метод skip для класса InputStream всегда возвращает 0, и байты не пропускаются. Подклассы могут обрабатывать отрицательное значение по-разному.

Реализация метода skip этого класса создает массив байтов, а затем многократно считывает в него данные, пока не будет прочитано n байтов или не будет достигнут конец потока. Подклассам рекомендуется предоставить более эффективную реализацию этого метода. Например, реализация может зависеть от возможности поиска.

Параметры:: n - количество байтов, которые нужно пропустить.
Возвращает:: фактическое количество пропущенных байтов.
Выбрасывает:: IOException - если произошла ошибка ввода-вывода.

available

public int available()
              throws IOException

Возвращает оценку количества байтов, которые можно прочитать (или пропустить) из этого входного потока без блокировки, что может быть 0, или 0, когда обнаружен конец потока. Чтение может происходить в том же потоке или в другом потоке. Одно чтение или пропуск такого количества байтов не заблокирует, но может прочитать или пропустить меньше байтов.

Обратите внимание, что хотя некоторые реализации InputStream вернут общее количество байтов в потоке, многие не сделают этого. Никогда не следует использовать значение возврата этого метода для выделения буфера, предназначенного для хранения всех данных в этом потоке.

Реализация этого метода подклассом может выбрать выбросить IOException, если этот входной поток был закрыт вызовом метода close().

Метод available класса InputStream всегда возвращает 0.

Этот метод должен быть переопределен подклассами.

Возвращает:: оценка количества байтов, которые можно прочитать (или пропустить) из этого входного потока без блокировки, или 0, когда достигается конец входного потока.
Выбрасывает:: IOException - если произошла ошибка ввода-вывода.

close

public void close()
           throws IOException

Закрывает этот входной поток и освобождает все системные ресурсы, связанные с потоком.

Метод close класса InputStream ничего не делает.

Определено:: close в интерфейсе AutoCloseable
Определено:: close в интерфейсе Closeable
Выбрасывает:: IOException - если произошла ошибка ввода-вывода.

mark

public void mark(int readlimit)

Помечает текущую позицию в этом входном потоке. Последующий вызов метода reset переместит этот поток в последнюю помеченную позицию, чтобы последующие чтения повторно считали те же байты.

Аргумент readlimit сообщает этому входному потоку разрешить чтение указанного количества байтов до того, как позиция метки станет недействительной.

Общая спецификация mark заключается в том, что если метод markSupported возвращает true, поток как-то запоминает все прочитанные байты после вызова mark и готов предоставить эти же байты снова при вызове метода reset. Однако поток не обязан запоминать какие-либо данные, если из потока было прочитано более readlimit байтов до вызова reset.

Пометка закрытого потока не должна оказывать никакого влияния на поток.

Метод mark класса InputStream ничего не делает.

Параметры:: readlimit - максимальное ограничение байтов, которые могут быть прочитаны, прежде чем позиция метки станет недействительной.
См. также:: reset()

reset

public void reset()
           throws IOException

Перемещает этот поток в позицию на момент последнего вызова метода mark для этого входного потока.

Общая спецификация reset:

Если метод markSupported возвращает true, то:
- Если метод mark не вызывался с момента создания потока или количество прочитанных байтов из потока с момента последнего вызова mark больше аргумента mark в этом вызове, может быть выброшено исключение IOException.
- Если такое исключение не выброшено, то поток сбрасывается в такое состояние, что все байты, прочитанные с момента последнего вызова mark (или с начала файла, если mark не вызывался), будут повторно представлены последующим вызовам метода read, после чего — любые байты, которые в противном случае были бы следующими входными данными на момент вызова reset.
Если метод markSupported возвращает false, то:
- Вызов reset может выбросить исключение IOException.
- Если исключение не выброшено, то поток сбрасывается в фиксированное состояние, которое зависит от конкретного типа входного потока и способа его создания. Байты, которые будут представлены последующим вызовам метода read, зависят от конкретного типа входного потока.

Метод reset для класса InputStream ничего не делает, кроме как выбросить IOException.

Выбрасывает:: IOException - если этот поток не был помечен или метка была аннулирована.
См. также:: mark(int), IOException

markSupported

public boolean markSupported()

Проверяет, поддерживает ли этот входной поток методы mark и reset. Поддержка методов mark и reset является неизменным свойством конкретного экземпляра входного потока. Метод markSupported класса InputStream возвращает false.

Возвращает:: true если этот поток поддерживает методы mark и reset; false в противном случае.
См. также:: mark(int), reset()

transferTo

public long transferTo(OutputStream out)
                throws IOException

Считывает все байты из этого входного потока и записывает байты в заданный выходной поток в порядке их чтения. По возвращении этот входной поток будет находиться в конце потока. Этот метод не закрывает ни один поток.

Этот метод может блокироваться неопределенно долго, считывая данные из входного потока или записывая данные в выходной поток. Поведение в случае асинхронного закрытия входного и/или выходного потока или прерывания потока во время передачи определяется входным и выходным потоками и поэтому не определено.

Если при чтении из входного потока или записи в выходной поток возникает ошибка ввода-вывода, она может произойти после того, как некоторые байты были прочитаны или записаны. В результате входной поток может не находиться в конце потока, и один или оба потока могут быть в несогласованном состоянии. Сильно рекомендуется немедленно закрыть оба потока, если произошла ошибка ввода-вывода.

Параметры:: out - выходной поток, не null
Возвращает:: количество переданных байтов
Выбрасывает:: IOException - если произошла ошибка ввода-вывода при чтении или записи; NullPointerException - если out равно null
С:: 9

© 1993, 2020, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/io/InputStream.html