Интерфейс GatheringByteChannel

Все суперинтерфейсы:: AutoCloseable, Channel, Closeable, WritableByteChannel

Все известные реализующие классы:: DatagramChannel, FileChannel, Pipe.SinkChannel, SocketChannel

public interface GatheringByteChannel extends WritableByteChannel

Канал, который может записывать байты из последовательности буферов.

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

Начиная с версии:: 1.4

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

Модификатор и тип	Метод	Описание
`long`	`write(ByteBuffer[] srcs)`	Записывает последовательность байтов в этот канал из заданных буферов.
`long`	`write(ByteBuffer[] srcs, int offset, int length)`	Записывает последовательность байтов в этот канал из подпоследовательности заданных буферов.

Методы, объявленные в интерфейсе Channel

close, isOpen

Методы, объявленные в интерфейсе WritableByteChannel

write

Подробное описание методов

write

long write(ByteBuffer[] srcs, int offset, int length) throws IOException

Записывает последовательность байтов в этот канал из подпоследовательности заданных буферов.

Выполняется попытка записать в этот канал до r байтов, где r — общее количество оставшихся байтов в указанной подпоследовательности заданного массива буферов, то есть

    srcs[offset].remaining()
        + srcs[offset+1].remaining()
        + ... + srcs[offset+length-1].remaining()

на момент вызова этого метода.

Предположим, что записывается последовательность байтов длиной n, где 0 <= n <= r. Первые srcs[offset].remaining() байтов этой последовательности записываются из буфера srcs[offset], следующие srcs[offset+1].remaining() байтов — из буфера srcs[offset+1] и так далее, пока не будет записана вся последовательность байтов. Из каждого буфера записывается максимально возможное количество байтов, поэтому конечная позиция каждого обновлённого буфера, кроме последнего обновлённого буфера, гарантированно совпадает с пределом этого буфера.

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

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

Параметры:: srcs — буферы, из которых следует извлечь байты; offset — смещение в массиве буферов, указывающее на первый буфер, из которого следует извлечь байты; должно быть неотрицательным и не превышать srcs.length; length — максимальное количество буферов, к которым можно обратиться; должно быть неотрицательным и не превышать srcs.length - offset
Возвращает:: Количество записанных байтов, возможно, ноль
Выбрасывает:: IndexOutOfBoundsException — если не выполнены предварительные условия для параметров offset и length; NonWritableChannelException — если этот канал не был открыт для записи; ClosedChannelException — если этот канал закрыт; AsynchronousCloseException — если другой поток закрывает этот канал во время выполнения операции записи; ClosedByInterruptException — если другой поток прерывает текущий поток во время выполнения операции записи, тем самым закрывая канал и устанавливая статус прерывания текущего потока; IOException — если произошла другая ошибка ввода-вывода

write

long write(ByteBuffer[] srcs) throws IOException

Записывает последовательность байтов в этот канал из заданных буферов.

Вызов этого метода в форме c.write(srcs) выполняется точно так же, как вызов

    c.write(srcs, 0, srcs.length);

Параметры:: srcs — буферы, из которых следует извлечь байты
Возвращает:: Количество записанных байтов, возможно, ноль
Выбрасывает:: NonWritableChannelException — если этот канал не был открыт для записи; ClosedChannelException — если этот канал закрыт; AsynchronousCloseException — если другой поток закрывает этот канал во время выполнения операции записи; ClosedByInterruptException — если другой поток прерывает текущий поток во время выполнения операции записи, тем самым закрывая канал и устанавливая статус прерывания текущего потока; IOException — если произошла другая ошибка ввода-вывода

© 1993, 2025, 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/25/docs/api/java.base/java/nio/channels/GatheringByteChannel.html