Класс 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. Канал дейтаграмм для сокета Интернет-протокола поддерживает следующие параметры:

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

Имя параметра Описание

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

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

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

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

IP_TOS Байты типа обслуживания (ToS) в заголовке Интернет-протокола (IP)

IP_MULTICAST_IF Сетевой интерфейс для дейтаграмм интернет-протокола (IP)

IP_MULTICAST_TTL Время жизни (time-to-live) для дейтаграмм интернет-протокола (IP)

IP_MULTICAST_LOOP Возврат для дейтаграмм интернет-протокола (IP)

Параметры сокета
Имя параметра	Описание
`SO_SNDBUF`	Размер буфера отправки сокета
`SO_RCVBUF`	Размер буфера приема сокета
`SO_REUSEADDR`	Повторное использование адреса
`SO_BROADCAST`	Разрешить передачу широковещательных дейтаграмм
`IP_TOS`	Байты типа обслуживания (ToS) в заголовке Интернет-протокола (IP)
`IP_MULTICAST_IF`	Сетевой интерфейс для дейтаграмм интернет-протокола (IP)
`IP_MULTICAST_TTL`	Время жизни (time-to-live) для дейтаграмм интернет-протокола (IP)
`IP_MULTICAST_LOOP`	Возврат для дейтаграмм интернет-протокола (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)`	Записывает дейтаграмму в этот канал.

Методы, объявленные в классе java.nio.channels.spi.AbstractSelectableChannel

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

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

register

Методы, объявленные в классе java.nio.channels.spi.AbstractInterruptibleChannel

begin, close, end, isOpen

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

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

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

isOpen

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

close, join, join

Методы, объявленные в интерфейсе java.nio.channels.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, то он должен соответствовать типу адреса многоадресных групп, к которым будет присоединяться этот канал.

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

Примечание 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

END_OF_DOCUMENT_MARKER

получить

public abstract SocketAddress receive(ByteBuffer dst) throws IOException

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

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

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

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

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

отправить

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

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

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

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

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

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

читать

public abstract int read(ByteBuffer dst) throws IOException

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

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

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

читать

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 - Если произошла какая-либо другая ошибка ввода-вывода

читать

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

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

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

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

записать

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

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

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

Specified by:: write в интерфейсе GatheringByteChannel
Parameters:: srcs - Буферы, из которых необходимо извлечь байты; offset - Смещение в массиве буферов первого буфера, из которого необходимо извлечь байты; должно быть неотрицательным и не превышать srcs.length; length - Максимальное количество буферов для доступа; должно быть неотрицательным и не превышать srcs.length - offset
Returns:: Количество отправленных байтов, которое будет равно количеству оставшихся байтов в исходном буфере, когда был вызван этот метод, или, если этот канал является неблокирующим, может быть равно нулю, если в базовом буфере вывода не было достаточно места для датаграммы
Throws:: NotYetConnectedException - Если сокет этого канала не подключен; ClosedChannelException - Если этот канал закрыт; AsynchronousCloseException - Если другой поток закрывает этот канал во время выполнения операции записи; ClosedByInterruptException - Если другой поток прерывает текущий поток во время выполнения операции записи, тем самым закрывая канал и устанавливая статус прерывания текущего потока; IOException - Если происходит какая-либо другая ошибка ввода-вывода

write

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

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

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

getLocalAddress

public abstract SocketAddress getLocalAddress() throws IOException

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

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

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

Specified by:: getLocalAddress в интерфейсе NetworkChannel
Returns:: SocketAddress, к которому привязан сокет; null если сокет канала не привязан
Throws:: 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://download.java.net/java/early_access/jdk24/docs/api/java.base/java/nio/channels/DatagramChannel.html