A datagram socket is the sending or receiving point for a packet delivery service. Each packet sent or received on a datagram socket is individually addressed and routed. Multiple packets sent from one machine to another may be routed differently, and may arrive in any order.
Where possible, a newly constructed DatagramSocket has the
SO_BROADCAST socket option enabled so as
to allow the transmission of broadcast datagrams. In order to receive
broadcast packets a DatagramSocket should be bound to the wildcard address.
In some implementations, broadcast packets may also be received when
a DatagramSocket is bound to a more specific address.
Example:
DatagramSocket s = new DatagramSocket(null);
s.bind(new InetSocketAddress(8888));
DatagramSocket s = new DatagramSocket(8888);
The DatagramSocket class defines convenience
methods to set and get several socket options. This class also
defines the setOption
and getOption methods to set
and query socket options.
A DatagramSocket supports the following socket options:
Option Name Description SO_SNDBUFThe size of the socket send buffer in bytes SO_RCVBUFThe size of the socket receive buffer in bytes SO_REUSEADDRRe-use address SO_BROADCASTAllow transmission of broadcast datagrams IP_TOSThe Type of Service (ToS) octet in the Internet Protocol (IP) header
In addition, the DatagramSocket class defines methods to join and leave a multicast group, and
supports multicast options which
are useful when joining,
leaving, or sending datagrams
to a multicast group.
The following multicast options are supported:
An implementation may also support additional options.
Option Name Description IP_MULTICAST_IFThe network interface for Internet Protocol (IP) multicast datagrams IP_MULTICAST_TTLThe time-to-live for Internet Protocol (IP) multicast datagrams IP_MULTICAST_LOOPLoopback for Internet Protocol (IP) multicast datagrams
API Note
Multicasting with DatagramSocket
DatagramChannel implements the MulticastChannel interface
and provides an alternative API for sending and receiving multicast datagrams.
The MulticastChannel API supports both any-source and
source-specific multicast. Consider using DatagramChannel for
multicasting.
DatagramSocket can be used directly for multicasting. However,
contrarily to MulticastSocket, DatagramSocket doesn't call the
DatagramSocket#setReuseAddress(boolean) method to enable the SO_REUSEADDR
socket option by default. If creating a DatagramSocket intended to
later join a multicast group, the caller should consider explicitly enabling
the SO_REUSEADDR option.
An instance of DatagramSocket can be used to send or
receive multicast datagram packets. It is not necessary to join a multicast
group in order to send multicast datagrams. Before sending out multicast
datagram packets however, the default outgoing interface for sending
multicast datagram should first be configured using
setOption and
StandardSocketOptions#IP_MULTICAST_IF:
DatagramSocket sender = new DatagramSocket(new InetSocketAddress(0));
NetworkInterface outgoingIf = NetworkInterface.getByName("en0");
sender.setOption(StandardSocketOptions.IP_MULTICAST_IF, outgoingIf);
// optionally configure multicast TTL; the TTL defines the scope of a
// multicast datagram, for example, confining it to host local (0) or
// link local (1) etc...
int ttl = ...; // a number between 0 and 255
sender.setOption(StandardSocketOptions.IP_MULTICAST_TTL, ttl);
// send a packet to a multicast group
byte[] msgBytes = ...;
InetAddress mcastaddr = InetAddress.getByName("228.5.6.7");
int port = 6789;
InetSocketAddress dest = new InetSocketAddress(mcastaddr, port);
DatagramPacket hi = new DatagramPacket(msgBytes, msgBytes.length, dest);
sender.send(hi);
An instance of DatagramSocket can also be used to receive
multicast datagram packets. A DatagramSocket that is created
with the intent of receiving multicast datagrams should be created
unbound. Before binding the socket, setReuseAddress(true) should be configured:
DatagramSocket socket = new DatagramSocket(null); // unbound
socket.setReuseAddress(true); // set reuse address before binding
socket.bind(new InetSocketAddress(6789)); // bind
// joinGroup 228.5.6.7
InetAddress mcastaddr = InetAddress.getByName("228.5.6.7");
InetSocketAddress group = new InetSocketAddress(mcastaddr, 0);
NetworkInterface netIf = NetworkInterface.getByName("en0");
socket.joinGroup(group, netIf);
byte[] msgBytes = new byte[1024]; // up to 1024 bytes
DatagramPacket packet = new DatagramPacket(msgBytes, msgBytes.length);
socket.receive(packet);
....
// eventually leave group
socket.leaveGroup(group, netIf);
The multicast implementation is intended to map directly to the native multicasting facility. Consequently, the following items should be considered when developing an application that receives IP multicast datagrams:
DatagramChannel, the constructors of DatagramSocket
do not allow to specify the ProtocolFamily of the underlying socket.
Consequently, the protocol family of the underlying socket may not
correspond to the protocol family of the multicast groups that
the DatagramSocket will attempt to join.
DatagramSocket with an underlying
socket created in one protocol family can join and receive multicast
datagrams when the address of the multicast group corresponds to
another protocol family. For example, it is implementation specific if a
DatagramSocket to an IPv6 socket can join an IPv4 multicast group
and receive multicast datagrams sent to the group.
DatagramSocket should be
bound to the wildcard address.
If the socket is bound to a specific address, rather than the wildcard address
then it is implementation specific if multicast datagrams are received
by the socket.
java.net.DatagramPacket , java.nio.channels.DatagramChannel
| Modifier and Type | Field and Description |
|---|---|
| private final DatagramSocket | |
| private static volatile DatagramSocketImplFactory | factory
User defined factory for all datagram sockets. |
| private static final SocketAddress |
| Access | Constructor and Description |
|---|---|
| pack-priv | DatagramSocket(DatagramSocket
The wrapped DatagramSocket implementation, or null. delegate)All constructors eventually call this one. |
| public | DatagramSocket()
Constructs a datagram socket and binds it to any available port on the local host machine. |
| protected | DatagramSocket(DatagramSocketImpl
an instance of a DatagramSocketImpl
the subclass wishes to use on the DatagramSocket. impl)Creates an unbound datagram socket with the specified DatagramSocketImpl. |
| public | DatagramSocket(SocketAddress
local socket address to bind, or bindaddr)null
for an unbound socket.Creates a datagram socket, bound to the specified local socket address. |
| public | DatagramSocket(int
local port to use in the bind operation. port)Constructs a datagram socket and binds it to the specified port on the local host machine. |
| public | DatagramSocket(int
local port to use in the bind operation. port, InetAddress local address to bind (can be laddr)null)Creates a datagram socket, bound to the specified local address. |
| Modifier and Type | Method and Description |
|---|---|
| public void | bind(SocketAddress
The address and port to bind to. addr)Binds this DatagramSocket to a specific address and port. |
| public void | |
| public void | connect(InetAddress
the remote address for the socket address, int the remote port for the socket. port)Connects the socket to a remote address for this socket. |
| public void | connect(SocketAddress
The remote address. addr)Connects this socket to a remote socket address (IP address + port number). |
| pack-priv static < The target type for which the delegate is created.
This is either T extends DatagramSocket> Tjava.net.DatagramSocket or
java.net.MulticastSocket. | Returns: null if bindaddr == NO_DELEGATE, otherwise returns a
delegate for the requested type.An address to bind to, or bindaddr, Class<T> null if creating an unbound
socket.This is either type)MulticastSocket.class, if the delegate needs
to support joining multicast groups, or DatagramSocket.class,
if it doesn't. Typically, this will be DatagramSocket.class
when creating a delegate for DatagramSocket, and
MulticastSocket.class when creating a delegate for
MulticastSocket.Creates a delegate for the specific requested |
| pack-priv DatagramSocket | |
| public void | |
| public boolean | Returns: aboolean indicating whether or not SO_BROADCAST is enabled.Tests if SO_BROADCAST is enabled. |
| public DatagramChannel | Returns: the datagram channel associated with this datagram socket, ornull if this socket was not created for a channelReturns the unique |
| public InetAddress | Returns: the address to which this socket is connected.Returns the address to which this socket is connected. |
| public InetAddress | Returns: the local address to which the socket is bound,null if the socket is closed, or
an InetAddress representing
wildcard
address if the socket is not boundGets the local address to which the socket is bound. |
| public int | Returns: the port number on the local host to which this socket is bound,-1 if the socket is closed, or
0 if it is not bound yet.Returns the port number on the local host to which this socket is bound. |
| public SocketAddress | Returns: aSocketAddress representing the local endpoint of this
socket, or null if it is closed or not bound yet.Returns the address of the endpoint this socket is bound to. |
| public < The type of the socket option value T> T | Returns: The value of the socket option.The socket option name)Returns the value of a socket option. |
| public int | Returns: the port number to which this socket is connected.Returns the port number to which this socket is connected. |
| public int | Returns: the value of the SO_RCVBUF option for thisDatagramSocketGet value of the SO_RCVBUF option for this |
| public SocketAddress | Returns: aSocketAddress representing the remote
endpoint of this socket, or null if it is
not connected yet.Returns the address of the endpoint this socket is connected to, or
|
| public boolean | Returns: aboolean indicating whether or not SO_REUSEADDR is enabled.Tests if SO_REUSEADDR is enabled. |
| public int | Returns: the value of the SO_SNDBUF option for thisDatagramSocketGet value of the SO_SNDBUF option for this |
| public int | |
| public int | Returns: the traffic class or type-of-service already setGets traffic class or type-of-service in the IP datagram header for packets sent from this DatagramSocket. |
| public boolean | Returns: true if the socket successfully bound to an addressReturns the binding state of the socket. |
| public boolean | |
| public boolean | Returns: true if the socket successfully connected to a serverReturns the connection state of the socket. |
| public void | joinGroup(SocketAddress
indicates the multicast address to join. mcastaddr, NetworkInterface specifies the local interface to receive multicast
datagram packets, or netIf)null.Joins a multicast group. |
| public void | leaveGroup(SocketAddress
is the multicast address to leave. This should
contain the same IP address than that used for joining
the group. mcastaddr, NetworkInterface specifies the local interface or netIf)null to defer
to the interface set for outgoing multicast datagrams.
If null, and no interface has been set, the behaviour
is unspecified: any interface may be selected or the operation
may fail with a SocketException.Leave a multicast group on a specified local interface. |
| public void | receive(DatagramPacket
the p)DatagramPacket into which to place
the incoming data.Receives a datagram packet from this socket. |
| public void | |
| public void | |
| public static synchronized void | setDatagramSocketImplFactory(DatagramSocketImplFactory
the desired factory. fac)
Deprecated
since 17. Use
DatagramChannel, or subclass DatagramSocket
directly.
Sets the datagram socket implementation factory for the application. |
| public < The type of the socket option value T> DatagramSocket | Returns: this DatagramSocketThe socket option name, T The value of the socket option. A value of value)null
may be valid for some options.Sets the value of a socket option. |
| public void | setReceiveBufferSize(int
the size to which to set the receive buffer
size, in bytes. This value must be greater than 0. size)Sets the SO_RCVBUF option to the specified value for this
|
| public void | setReuseAddress(boolean
whether to enable or disable the on)Enable/disable the SO_REUSEADDR socket option. |
| public void | setSendBufferSize(int
the size to which to set the send buffer
size, in bytes. This value must be greater than 0. size)Sets the SO_SNDBUF option to the specified value for this
|
| public void | setSoTimeout(int
the specified timeout in milliseconds. timeout)Enable/disable SO_TIMEOUT with the specified timeout, in milliseconds. |
| public void | setTrafficClass(int
an tc)int value for the bitset.Sets traffic class or type-of-service octet in the IP datagram header for datagrams sent from this DatagramSocket. |
| public Set | Returns: A set of the socket options supported by this socket. This set may be empty if the socket's DatagramSocketImpl cannot be created.Returns a set of the socket options supported by this socket. |
| private static SocketException | Returns: an instance ofSocketExceptionan instance of e)IOExceptionBest effort to convert an |
| delegate | back to summary |
|---|---|
| private final DatagramSocket delegate | |
| factory | back to summary |
|---|---|
| private static volatile DatagramSocketImplFactory factory User defined factory for all datagram sockets. | |
| NO_DELEGATE | back to summary |
|---|---|
| private static final SocketAddress NO_DELEGATE | |
| DatagramSocket | back to summary |
|---|---|
| pack-priv DatagramSocket(DatagramSocket delegate) All constructors eventually call this one.
| |
| DatagramSocket | back to summary |
|---|---|
| public DatagramSocket() throws SocketException Constructs a datagram socket and binds it to any available port
on the local host machine. The socket will be bound to the
| |
| DatagramSocket | back to summary |
|---|---|
| protected DatagramSocket(DatagramSocketImpl impl) Creates an unbound datagram socket with the specified DatagramSocketImpl.
| |
| DatagramSocket | back to summary |
|---|---|
| public DatagramSocket(SocketAddress bindaddr) throws SocketException Creates a datagram socket, bound to the specified local socket address.
If the address is
| |
| DatagramSocket | back to summary |
|---|---|
| public DatagramSocket(int port) throws SocketException Constructs a datagram socket and binds it to the specified port
on the local host machine. The socket will be bound to the
| |
| DatagramSocket | back to summary |
|---|---|
| public DatagramSocket(int port, InetAddress laddr) throws SocketException Creates a datagram socket, bound to the specified local address. The local port must be between 0 and
65535 inclusive. A port number of
If the IP address is a
| |
| bind | back to summary |
|---|---|
| public void bind(SocketAddress addr) throws SocketException Binds this DatagramSocket to a specific address and port.
If the address is
| |
| close | back to summary |
|---|---|
| public void close() Implements java. Closes this datagram socket.
Any thread currently blocked in If this socket has an associated channel then the channel is closed as well. Once closed, several of the methods defined by this class will throw an exception if invoked on the closed socket. | |
| connect | back to summary |
|---|---|
| public void connect(InetAddress address, int port) Connects the socket to a remote address for this socket. When a socket is connected to a remote address, packets may only be sent to or received from that address. By default a datagram socket is not connected. If the socket is already closed, then this method has no effect. If this socket is not bound then this method will first cause the
socket to be bound to an address that is assigned automatically,
as if invoking the If this socket is already connected, then this method will attempt to connect to the given address. If this connect fails then the state of this socket is unknown - it may or may not be connected to the address that it was previously connected to. When the socket is connected, the send method checks that the packet's address matches the remote address that the socket is connected to. A socket connected to a multicast address may only be used to send packets. Datagrams in the socket's socket receive buffer, which have not been received before invoking this method, may be discarded.
| |
| connect | back to summary |
|---|---|
| public void connect(SocketAddress addr) throws SocketException Connects this socket to a remote socket address (IP address + port number). If given an If this socket is already connected, then this method will attempt to connect to the given address. If this connect fails then the state of this socket is unknown - it may or may not be connected to the address that it was previously connected to.
| |
| createDelegate | back to summary |
|---|---|
| pack-priv static <T extends DatagramSocket> T createDelegate(SocketAddress bindaddr, Class<T> type) throws SocketException Creates a delegate for the specific requested
| |
| delegate | back to summary |
|---|---|
| pack-priv DatagramSocket delegate() | |
| disconnect | back to summary |
|---|---|
| public void disconnect() Disconnects the socket. If the socket is closed or not connected, then this method has no effect. API Note If this method throws an UncheckedIOException, the socket may be left in an unspecified state. It is strongly recommended that the socket be closed when disconnect fails.
| |
| getBroadcast | back to summary |
|---|---|
| public boolean getBroadcast() throws SocketException Tests if SO_BROADCAST is enabled. API Note This method is equivalent to calling
| |
| getChannel | back to summary |
|---|---|
| public DatagramChannel getChannel() Returns the unique A datagram socket will have a channel if, and only if, the channel
itself was created via the
| |
| getInetAddress | back to summary |
|---|---|
| public InetAddress getInetAddress() Returns the address to which this socket is connected. Returns
If the socket was connected prior to being
| |
| getLocalAddress | back to summary |
|---|---|
| public InetAddress getLocalAddress() Gets the local address to which the socket is bound. If the socket was initially bound to the wildcard address and
is now
| |
| getLocalPort | back to summary |
|---|---|
| public int getLocalPort() Returns the port number on the local host to which this socket is bound.
| |
| getLocalSocketAddress | back to summary |
|---|---|
| public SocketAddress getLocalSocketAddress() Returns the address of the endpoint this socket is bound to. If the socket was initially bound to the wildcard address and
is now
| |
| getOption | back to summary |
|---|---|
| public <T> T getOption(SocketOption<T> name) throws IOException Returns the value of a socket option.
| |
| getPort | back to summary |
|---|---|
| public int getPort() Returns the port number to which this socket is connected.
Returns
If the socket was connected prior to being
| |
| getReceiveBufferSize | back to summary |
|---|---|
| public int getReceiveBufferSize() throws SocketException Get value of the SO_RCVBUF option for this API Note This method is equivalent to calling
| |
| getRemoteSocketAddress | back to summary |
|---|---|
| public SocketAddress getRemoteSocketAddress() Returns the address of the endpoint this socket is connected to, or
If the socket was connected prior to being
| |
| getReuseAddress | back to summary |
|---|---|
| public boolean getReuseAddress() throws SocketException Tests if SO_REUSEADDR is enabled. API Note This method is equivalent to calling
| |
| getSendBufferSize | back to summary |
|---|---|
| public int getSendBufferSize() throws SocketException Get value of the SO_SNDBUF option for this API Note This method is equivalent to calling
| |
| getSoTimeout | back to summary |
|---|---|
| public int getSoTimeout() throws SocketException Retrieve setting for SO_TIMEOUT. 0 returns implies that the option is disabled (i.e., timeout of infinity).
| |
| getTrafficClass | back to summary |
|---|---|
| public int getTrafficClass() throws SocketException Gets traffic class or type-of-service in the IP datagram header for packets sent from this DatagramSocket.
As the underlying network implementation may ignore the
traffic class or type-of-service set using API Note This method is equivalent to calling
| |
| isBound | back to summary |
|---|---|
| public boolean isBound() Returns the binding state of the socket.
If the socket was bound prior to being
| |
| isClosed | back to summary |
|---|---|
| public boolean isClosed() Returns whether the socket is closed or not.
| |
| isConnected | back to summary |
|---|---|
| public boolean isConnected() Returns the connection state of the socket.
If the socket was connected prior to being
| |
| joinGroup | back to summary |
|---|---|
| public void joinGroup(SocketAddress mcastaddr, NetworkInterface netIf) throws IOException Joins a multicast group. In order to join a multicast group, the caller should specify the IP address of the multicast group to join, and the local network interface to receive multicast packets from.
It is possible to call this method several times to join
several different multicast groups, or join the same group
in several different networks. However, if the socket is already a
member of the group, an API Note The default interface for sending outgoing multicast datagrams
can be configured with
| |
| leaveGroup | back to summary |
|---|---|
| public void leaveGroup(SocketAddress mcastaddr, NetworkInterface netIf) throws IOException Leave a multicast group on a specified local interface. API Note The It is possible to call this method several times to leave
multiple different multicast groups previously joined, or leave
the same group previously joined in multiple different networks.
However, if the socket is not a member of the specified group
in the specified network, an
| |
| receive | back to summary |
|---|---|
| public void receive(DatagramPacket p) throws IOException Receives a datagram packet from this socket. This method blocks until a
datagram is received.
When this method returns, the This method is interruptible in the following circumstances:
| |
| send | back to summary |
|---|---|
| public void send(DatagramPacket p) throws IOException Sends a datagram packet from this socket. The
| |
| setBroadcast | back to summary |
|---|---|
| public void setBroadcast(boolean on) throws SocketException Enable/disable SO_BROADCAST. Some operating systems may require that the Java virtual machine be started with implementation specific privileges to enable this option or send broadcast datagrams. API Note This method is equivalent to calling
| |
| setDatagramSocketImplFactory | back to summary |
|---|---|
| public static synchronized void setDatagramSocketImplFactory(DatagramSocketImplFactory fac) throws IOException
Deprecated since 17. Use Sets the datagram socket implementation factory for the application. The factory can be specified only once.
When an application creates a new datagram socket, the socket
implementation factory's
Passing
| |
| setOption | back to summary |
|---|---|
| public <T> DatagramSocket setOption(SocketOption<T> name, T value) throws IOException Sets the value of a socket option.
| |
| setReceiveBufferSize | back to summary |
|---|---|
| public void setReceiveBufferSize(int size) throws SocketException Sets the SO_RCVBUF option to the specified value for this
Because SO_RCVBUF is a hint, applications that want to
verify what size the buffers were set to should call
Increasing SO_RCVBUF may allow the network implementation
to buffer multiple packets when packets arrive faster than
are being received using Note It is implementation specific if a packet larger than SO_RCVBUF can be received. API Note If
| |
| setReuseAddress | back to summary |
|---|---|
| public void setReuseAddress(boolean on) throws SocketException Enable/disable the SO_REUSEADDR socket option.
For UDP sockets it may be necessary to bind more than one
socket to the same socket address. This is typically for the
purpose of receiving multicast packets
(See Note This functionality is not supported by all existing platforms,
so it is implementation specific whether this option will be ignored
or not. However, if it is not supported then
When a
The behaviour when API Note This method is equivalent to calling
| |
| setSendBufferSize | back to summary |
|---|---|
| public void setSendBufferSize(int size) throws SocketException Sets the SO_SNDBUF option to the specified value for this
As SO_SNDBUF is a hint, applications that want to verify
what size the buffer is should call Increasing the buffer size may allow multiple outgoing packets to be queued by the network implementation when the send rate is high. Note If API Note If
| |
| setSoTimeout | back to summary |
|---|---|
| public void setSoTimeout(int timeout) throws SocketException Enable/disable SO_TIMEOUT with the specified timeout, in milliseconds. With this option set to a positive timeout value, a call to receive() for this DatagramSocket will block for only this amount of time. If the timeout expires, a java.net.SocketTimeoutException is raised, though the DatagramSocket is still valid. A timeout of zero is interpreted as an infinite timeout. The option must be enabled prior to entering the blocking operation to have effect.
| |
| setTrafficClass | back to summary |
|---|---|
| public void setTrafficClass(int tc) throws SocketException Sets traffic class or type-of-service octet in the IP datagram header for datagrams sent from this DatagramSocket. As the underlying network implementation may ignore this value applications should consider it a hint. The tc must be in the range Notes For Internet Protocol v4 the value consists of an
Setting bits in the precedence field may result in a SocketException indicating that the operation is not permitted.
for Internet Protocol v6 API Note This method is equivalent to calling
| |
| supportedOptions | back to summary |
|---|---|
| public Set Returns a set of the socket options supported by this socket. This method will continue to return the set of options even after the socket has been closed.
| |
| toSocketException | back to summary |
|---|---|
| private static SocketException toSocketException(IOException e) Best effort to convert an
| |