Класс InputStream

public InputStream()

Конструктор для вызова подклассами.

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.

public abstract int read() throws IOException

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

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

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) 

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] остаются без изменений.

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

public byte[] readAllBytes() throws IOException

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

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

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

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

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

public byte[] readNBytes(int len) throws IOException

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

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

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

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

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

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

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 могут быть в несогласованном состоянии. Сильно рекомендуется немедленно закрыть поток, если произошла ошибка ввода-вывода.

public long skip(long n) throws IOException

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

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

public void skipNBytes(long n) throws IOException

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

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

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

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

public int available() throws IOException

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

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

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

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

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

public void close() throws IOException

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

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

public void mark(int readlimit)

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

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

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

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

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

public void reset() throws IOException

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

Общий контракт метода reset:

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

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

public boolean markSupported()

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

public long transferTo(OutputStream out) throws IOException

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

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

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