Класс DatagramChannel

java.nio.channels.DatagramChannel

Все реализуемые интерфейсы:: Closeable, AutoCloseable, ByteChannel, Channel, GatheringByteChannel, InterruptibleChannel, MulticastChannel, NetworkChannel, ReadableByteChannel, ScatteringByteChannel, WritableByteChannel

public abstract class DatagramChannel extends AbstractSelectableChannel implements ByteChannel, ScatteringByteChannel, GatheringByteChannel, MulticastChannel

Выбираемый канал для сокетов, ориентированных на датаграммы.

Канал датаграмм создается вызовом одного из методов open этого класса. Создать канал для произвольного существующего сокета датаграмм невозможно. Вновь созданный канал датаграмм открыт, но не подключен. Канал датаграмм не обязательно должен быть подключен, чтобы использовать методы send и receive. Канал датаграмм можно подключить вызовом метода connect, чтобы избежать накладных расходов на проверки, выполняемые при каждой операции отправки и получения. Канал датаграмм должен быть подключен для использования методов read и write, поскольку эти методы не принимают и не возвращают адреса сокетов.

После подключения канал датаграмм остается подключенным, пока не будет отключен или закрыт. Узнать, подключен ли канал датаграмм, можно вызовом метода isConnected.

Параметры сокета настраиваются с помощью метода setOption. Канал датаграмм для сокета Internet Protocol поддерживает следующие параметры:

Параметры сокета

Название параметра Описание

SO_SNDBUF Размер буфера отправки сокета

SO_RCVBUF Размер буфера приема сокета

SO_REUSEADDR Повторное использование адреса

SO_BROADCAST Разрешить передачу широковещательных датаграмм

IP_TOS Октет типа обслуживания (ToS) в заголовке Internet Protocol (IP)

IP_MULTICAST_IF Сетевой интерфейс для многоадресных датаграмм Internet Protocol (IP)

IP_MULTICAST_TTL Время жизни многоадресных датаграмм Internet Protocol (IP)

IP_MULTICAST_LOOP Обратная передача многоадресных датаграмм Internet Protocol (IP)

Параметры сокета
Название параметра	Описание
`SO_SNDBUF`	Размер буфера отправки сокета
`SO_RCVBUF`	Размер буфера приема сокета
`SO_REUSEADDR`	Повторное использование адреса
`SO_BROADCAST`	Разрешить передачу широковещательных датаграмм
`IP_TOS`	Октет типа обслуживания (ToS) в заголовке Internet Protocol (IP)
`IP_MULTICAST_IF`	Сетевой интерфейс для многоадресных датаграмм Internet Protocol (IP)
`IP_MULTICAST_TTL`	Время жизни многоадресных датаграмм Internet Protocol (IP)
`IP_MULTICAST_LOOP`	Обратная передача многоадресных датаграмм Internet Protocol (IP)

Также могут поддерживаться дополнительные параметры, зависящие от реализации.

Каналы датаграмм безопасны для использования несколькими параллельными потоками. Они поддерживают одновременное чтение и запись, однако в каждый момент времени чтение может выполнять не более одного потока, а запись — не более одного потока.

Начиная с:: 1.4

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

DatagramChannel(SelectorProvider provider)

Модификатор	Конструктор	Описание
`protected`	Инициализирует новый экземпляр этого класса.

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

Модификатор и тип	Метод	Описание
`abstract DatagramChannel`	`bind(SocketAddress local)`	Привязывает сокет канала к локальному адресу.
`abstract DatagramChannel`	`connect(SocketAddress remote)`	Подключает сокет этого канала.
`abstract DatagramChannel`	`disconnect()`	Отключает сокет этого канала.
`abstract SocketAddress`	`getLocalAddress()`	Возвращает адрес сокета, к которому привязан этот канал.
`abstract SocketAddress`	`getRemoteAddress()`	Возвращает удаленный адрес, к которому подключен сокет этого канала.
`abstract boolean`	`isConnected()`	Сообщает, подключен ли сокет этого канала.
`static DatagramChannel`	`open()`	Открывает канал датаграмм.
`static DatagramChannel`	`open(ProtocolFamily family)`	Открывает канал датаграмм.
`abstract int`	`read(ByteBuffer dst)`	Читает датаграмму из этого канала.
`final long`	`read(ByteBuffer[] dsts)`	Читает датаграмму из этого канала.
`abstract long`	`read(ByteBuffer[] dsts, int offset, int length)`	Читает датаграмму из этого канала.
`abstract SocketAddress`	`receive(ByteBuffer dst)`	Принимает датаграмму через этот канал.
`abstract int`	`send(ByteBuffer src, SocketAddress target)`	Отправляет датаграмму через этот канал.
`abstract <T> DatagramChannel`	`setOption(SocketOption<T> name, T value)`	Задает значение параметра сокета.
`abstract DatagramSocket`	`socket()`	Возвращает сокет датаграмм, связанный с этим каналом.
`final int`	`validOps()`	Возвращает набор операций, определяющий поддерживаемые этим каналом операции.
`abstract int`	`write(ByteBuffer src)`	Записывает датаграмму в этот канал.
`final long`	`write(ByteBuffer[] srcs)`	Записывает датаграмму в этот канал.
`abstract long`	`write(ByteBuffer[] srcs, int offset, int length)`	Записывает датаграмму в этот канал.

Методы, объявленные в классе AbstractSelectableChannel

blockingLock, configureBlocking, implCloseChannel, implCloseSelectableChannel, implConfigureBlocking, isBlocking, isRegistered, keyFor, provider, register

Методы, объявленные в классе SelectableChannel

register

Методы, объявленные в классе AbstractInterruptibleChannel

begin, close, end, isOpen

Методы, объявленные в классе Object

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

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

isOpen

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

close, join, join

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

getOption, supportedOptions

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

DatagramChannel

protected DatagramChannel(SelectorProvider provider)

Инициализирует новый экземпляр этого класса.

Параметры:: provider — поставщик, создавший этот канал

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

open

public static DatagramChannel open() throws IOException

Открывает канал датаграмм.

Новый канал создается вызовом метода openDatagramChannel объекта SelectorProvider, используемого по умолчанию во всей системе. Канал не будет подключен.

Семейство протоколов ProtocolFamily для сокета канала зависит от платформы (и, возможно, от конфигурации), поэтому не определено. Метод open позволяет выбрать семейство протоколов при открытии канала датаграмм; его следует использовать для открытия каналов датаграмм, предназначенных для многоадресной рассылки по интернет-протоколу.

Возвращает:

Новый канал датаграмм

Вызывает исключение:

IOException — если произошла ошибка ввода-вывода

См. также:

open

public static DatagramChannel open(ProtocolFamily family) throws IOException

Открывает канал датаграмм.

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

Примечание к API:

Сокеты домена Unix не поддерживаются.

Параметры:

family — семейство протоколов

Возвращает:

Новый канал датаграмм

Вызывает исключение:

UnsupportedOperationException — если указанное семейство протоколов не поддерживается. Например, если параметр указан как StandardProtocolFamily.INET6, но IPv6 на платформе не включен.

IOException — если произошла ошибка ввода-вывода

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

1.7

См. также:

validOps

public final int validOps()

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

Каналы датаграмм поддерживают чтение и запись, поэтому этот метод возвращает (SelectionKey.OP_READ | SelectionKey.OP_WRITE).

Определено в:: validOps в классе SelectableChannel
Возвращает:: Набор допустимых операций

bind

public abstract DatagramChannel bind(SocketAddress local) throws IOException

Описание скопировано из интерфейса: NetworkChannel

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

Этот метод используется для установления связи между сокетом и локальным адресом. После установления связи сокет остается привязанным до закрытия канала. Если параметр local имеет значение null, сокет будет привязан к адресу, назначенному автоматически.

Определено в:

bind в интерфейсе NetworkChannel

Параметры:

local — адрес для привязки сокета или null для привязки сокета к автоматически назначенному адресу сокета

Возвращает:

Этот канал

Вызывает исключение:

AlreadyBoundException — если сокет уже привязан

UnsupportedAddressTypeException — если тип указанного адреса не поддерживается

ClosedChannelException — если канал закрыт

IOException — если произошла другая ошибка ввода-вывода

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

1.7

См. также:

setOption

public abstract <T> DatagramChannel setOption(SocketOption<T> name, T value) throws IOException

Описание скопировано из интерфейса: NetworkChannel

Устанавливает значение параметра сокета.

Определено в:

setOption в интерфейсе NetworkChannel

Параметры типа:

T — тип значения параметра сокета

Параметры:

name — параметр сокета

value — значение параметра сокета. Значение null может быть допустимым для некоторых параметров сокета.

Возвращает:

Этот канал

Вызывает исключение:

UnsupportedOperationException — если этот канал не поддерживает параметр сокета

IllegalArgumentException — если значение недопустимо для этого параметра сокета

ClosedChannelException — если этот канал закрыт

IOException — если произошла ошибка ввода-вывода

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

1.7

См. также:

socket

public abstract DatagramSocket socket()

Возвращает сокет датаграмм, связанный с этим каналом.

Возвращает:: Сокет датаграмм, связанный с этим каналом

isConnected

public abstract boolean isConnected()

Показывает, подключен ли сокет этого канала.

Возвращает:: true тогда и только тогда, когда сокет этого канала open и подключен

connect

public abstract DatagramChannel connect(SocketAddress remote) throws IOException

Подключает сокет этого канала.

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

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

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

disconnect

public abstract DatagramChannel disconnect() throws IOException

Отключает сокет этого канала.

Сокет канала настраивается так, чтобы получать датаграммы с любого удаленного адреса и отправлять датаграммы на любой удаленный адрес.

Если сокет этого канала не подключен или канал закрыт, вызов этого метода не оказывает никакого действия.

Примечание к API:: Если этот метод выбрасывает исключение IOException, сокет канала может остаться в неопределенном состоянии. Настоятельно рекомендуется закрыть канал, если отключение не удалось.
Возвращает:: Этот канал датаграмм
Вызывает исключение:: IOException — если произошла другая ошибка ввода-вывода

getRemoteAddress

public abstract SocketAddress getRemoteAddress() throws IOException

Возвращает удаленный адрес, к которому подключен сокет этого канала.

Возвращает:: Удаленный адрес; null, если сокет канала не подключен
Вызывает исключение:: ClosedChannelException — если канал закрыт; IOException — если произошла ошибка ввода-вывода
Начиная с версии:: 1.7

receive

public abstract SocketAddress receive(ByteBuffer dst) throws IOException

Получает датаграмму через этот канал.

Если датаграмма доступна немедленно или если этот канал работает в блокирующем режиме и датаграмма становится доступна позднее, она копируется в указанный байтовый буфер, а адрес источника возвращается. Если канал работает в неблокирующем режиме и датаграмма немедленно недоступна, этот метод сразу возвращает null.

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

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

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

send

public abstract int send(ByteBuffer src, SocketAddress target) throws IOException

Отправляет датаграмму через этот канал.

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

Датаграмма передается из байтового буфера как при обычной операции write.

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

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

read

public abstract int read(ByteBuffer dst) throws IOException

Читает датаграмму из этого канала.

Этот метод можно вызывать, только если сокет этого канала подключен; он принимает датаграммы только от узла-партнера сокета. Если в датаграмме больше байтов, чем помещается в оставшуюся часть указанного буфера, оставшаяся часть датаграммы отбрасывается без уведомления. В противном случае этот метод работает точно так, как указано в интерфейсе ReadableByteChannel.

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

read

public abstract long read(ByteBuffer[] dsts, int offset, int length) throws IOException

Читает датаграмму из этого канала.

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

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

read

public final long read(ByteBuffer[] dsts) throws IOException

Читает датаграмму из этого канала.

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

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

write

public abstract int write(ByteBuffer src) throws IOException

Записывает датаграмму в этот канал.

Этот метод можно вызывать, только если сокет этого канала подключен; в этом случае датаграммы отправляются непосредственно узлу-партнеру сокета. В противном случае метод работает точно так, как указано в интерфейсе WritableByteChannel.

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

write

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

Записывает датаграмму в этот канал.

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

write

public final long write(ByteBuffer[] srcs) throws IOException

Записывает датаграмму в этот канал.

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

getLocalAddress

public abstract SocketAddress getLocalAddress() throws IOException

Возвращает адрес сокета, к которому привязан сокет этого канала.

Если канал bound к адресу сокета интернет-протокола, возвращаемое этим методом значение имеет тип InetSocketAddress.

Если сокет канала изначально был привязан к адресу-шаблону и теперь connected, возвращенный адрес может быть локальным адресом, выбранным в качестве исходного для датаграмм, отправляемых через этот канал, а не адресом-шаблоном. При вызове disconnect() привязанный адрес возвращается к адресу-шаблону.

Определено в:: getLocalAddress в интерфейсе NetworkChannel
Возвращает:: SocketAddress, к которому привязан сокет; null, если сокет канала не привязан
Вызывает исключение:: ClosedChannelException — если канал закрыт; 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/DatagramChannel.html