Closeable
, AutoCloseable
public class MulticastSocket extends DatagramSocket
MulticastSocket
is a datagram socket that is convenient for sending and receiving IP multicast datagrams. The MulticastSocket
constructors create a socket with appropriate socket options enabled that make it suitable for receiving multicast datagrams. The MulticastSocket
class additionally defines convenient setter and getter methods for socket options that are commonly used by multicasting applications. Joining one or more multicast groups makes it possible to receive multicast datagrams sent to these groups.
An IPv4 multicast group is specified by a class D IP address and by a standard UDP port number. Class D IP addresses are in the range 224.0.0.0
to 239.255.255.255
, inclusive. The address 224.0.0.0 is reserved and should not be used.
One would join a multicast group by first creating a MulticastSocket with the desired port, then invoking the joinGroup
method, specifying the group address and the network interface through which multicast datagrams will be received:
// join a Multicast group and send the group salutations
...
String msg = "Hello";
InetAddress mcastaddr = InetAddress.getByName("228.5.6.7");
InetSocketAddress group = new InetSocketAddress(mcastaddr, 6789);
NetworkInterface netIf = NetworkInterface.getByName("bge0");
MulticastSocket s = new MulticastSocket(6789);
s.joinGroup(new InetSocketAddress(mcastaddr, 0), netIf);
byte[] msgBytes = msg.getBytes(StandardCharsets.UTF_8);
DatagramPacket hi = new DatagramPacket(msgBytes, msgBytes.length, group);
s.send(hi);
// get their responses!
byte[] buf = new byte[1000];
DatagramPacket recv = new DatagramPacket(buf, buf.length);
s.receive(recv);
...
// OK, I'm done talking - leave the group...
s.leaveGroup(group, netIf);
When one sends a message to a multicast group, all subscribing recipients to that host and port receive the message (within the time-to-live range of the packet, see below). The socket needn't be a member of the multicast group to send messages to it. When a socket subscribes to a multicast group/port, it receives datagrams sent by other hosts to the group/port, as do all other members of the group and port. A socket relinquishes membership in a group by the leaveGroup(SocketAddress mcastaddr, NetworkInterface netIf) method. Multiple MulticastSockets may subscribe to a multicast group and port concurrently, and they will all receive group datagrams.
The DatagramSocket
and MulticastSocket
classes define convenience methods to set and get several socket options. Like DatagramSocket
this class also supports the setOption
and getOption
methods to set and query socket options. The set of supported socket options is defined in DatagramSocket
. Additional (implementation specific) options may also be supported.
DatagramSocket
may be used directly for sending and receiving multicast datagrams. 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.Constructor | Description |
---|---|
MulticastSocket() |
Constructs a multicast socket and binds it to any available port on the local host machine. |
MulticastSocket |
Constructs a multicast socket and binds it to the specified port on the local host machine. |
MulticastSocket |
Creates a multicast socket, bound to the specified local socket address. |
Modifier and Type | Method | Description |
---|---|---|
InetAddress |
getInterface() |
Deprecated. The network interface may not be uniquely identified by the InetAddress returned. |
boolean |
getLoopbackMode() |
Deprecated. |
NetworkInterface |
getNetworkInterface() |
Get the multicast network interface set for outgoing multicast datagrams sent from this socket. |
int |
getTimeToLive() |
Get the default time-to-live for multicast packets sent out on the socket. |
byte |
getTTL() |
Deprecated. use the getTimeToLive() method instead, which returns an int instead of a byte. |
void |
joinGroup |
Deprecated. This method does not accept the network interface on which to join the multicast group. |
void |
joinGroup |
Joins a multicast group. |
void |
leaveGroup |
Deprecated. This method does not accept the network interface on which to leave the multicast group. |
void |
leaveGroup |
Leave a multicast group on a specified local interface. |
void |
send |
Deprecated. Use the following code or its equivalent instead: |
void |
setInterface |
Deprecated. The InetAddress may not uniquely identify the network interface. |
void |
setLoopbackMode |
Deprecated. |
void |
setNetworkInterface |
Specify the network interface for outgoing multicast datagrams sent on this socket. |
void |
setTimeToLive |
Set the default time-to-live for multicast packets sent out on this MulticastSocket in order to control the scope of the multicasts. |
void |
setTTL |
Deprecated. use the setTimeToLive(int) method instead, which uses int instead of byte as the type for ttl. |
bind, close, connect, connect, disconnect, getBroadcast, getChannel, getInetAddress, getLocalAddress, getLocalPort, getLocalSocketAddress, getOption, getPort, getReceiveBufferSize, getRemoteSocketAddress, getReuseAddress, getSendBufferSize, getSoTimeout, getTrafficClass, isBound, isClosed, isConnected, receive, send, setBroadcast, setDatagramSocketImplFactory, setOption, setReceiveBufferSize, setReuseAddress, setSendBufferSize, setSoTimeout, setTrafficClass, supportedOptions
public MulticastSocket() throws IOException
wildcard
address. If there is a security manager, its checkListen
method is first called with 0 as its argument to ensure the operation is allowed. This could result in a SecurityException.
When the socket is created the DatagramSocket.setReuseAddress(boolean)
method is called to enable the SO_REUSEADDR socket option.
IOException
- if an I/O exception occurs while creating the MulticastSocketSecurityException
- if a security manager exists and its checkListen
method doesn't allow the operation.public MulticastSocket(int port) throws IOException
wildcard
address. If there is a security manager, its checkListen
method is first called with the port
argument as its argument to ensure the operation is allowed. This could result in a SecurityException.
When the socket is created the DatagramSocket.setReuseAddress(boolean)
method is called to enable the SO_REUSEADDR socket option.
port
- port to useIOException
- if an I/O exception occurs while creating the MulticastSocketSecurityException
- if a security manager exists and its checkListen
method doesn't allow the operation.IllegalArgumentException
- if port is out of range.
public MulticastSocket(SocketAddress bindaddr) throws IOException
If the address is null
an unbound socket will be created.
If there is a security manager, its checkListen
method is first called with the SocketAddress port as its argument to ensure the operation is allowed. This could result in a SecurityException.
When the socket is created the DatagramSocket.setReuseAddress(boolean)
method is called to enable the SO_REUSEADDR socket option.
bindaddr
- Socket address to bind to, or null
for an unbound socket.IOException
- if an I/O exception occurs while creating the MulticastSocketSecurityException
- if a security manager exists and its checkListen
method doesn't allow the operation.@Deprecated public void setTTL(byte ttl) throws IOException
setTimeToLive(int)
method instead, which uses int instead of byte as the type for ttl.MulticastSocket
in order to control the scope of the multicasts. The ttl is an unsigned 8-bit quantity, and so must be in the range 0 <= ttl <= 0xFF
.
ttl
- the time-to-liveIOException
- if an I/O exception occurs while setting the default time-to-live valuepublic void setTimeToLive(int ttl) throws IOException
MulticastSocket
in order to control the scope of the multicasts. The ttl must be in the range 0 <= ttl <=
255
or an IllegalArgumentException
will be thrown. Multicast packets sent with a TTL of 0
are not transmitted on the network but may be delivered locally.
setOption(StandardSocketOptions.IP_MULTICAST_TTL, ttl)
.ttl
- the time-to-liveIOException
- if an I/O exception occurs while setting the default time-to-live value@Deprecated public byte getTTL() throws IOException
getTimeToLive()
method instead, which returns an int instead of a byte.IOException
- if an I/O exception occurs while getting the default time-to-live valuepublic int getTimeToLive() throws IOException
getOption(StandardSocketOptions.IP_MULTICAST_TTL)
.IOException
- if an I/O exception occurs while getting the default time-to-live value@Deprecated(since="14") public void joinGroup(InetAddress mcastaddr) throws IOException
joinGroup(SocketAddress, NetworkInterface)
instead.setInterface
or setNetworkInterface
. If there is a security manager, this method first calls its checkMulticast
method with the mcastaddr
argument as its argument.
joinGroup(new InetSocketAddress(mcastaddr, 0), null)
.mcastaddr
- is the multicast address to joinIOException
- if there is an error joining, or when the address is not a multicast address, or the platform does not support multicastingSecurityException
- if a security manager exists and its checkMulticast
method doesn't allow the join.@Deprecated(since="14") public void leaveGroup(InetAddress mcastaddr) throws IOException
leaveGroup(SocketAddress, NetworkInterface)
instead.setInterface
or setNetworkInterface
. If there is a security manager, this method first calls its checkMulticast
method with the mcastaddr
argument as its argument.
leaveGroup(new InetSocketAddress(mcastaddr, 0), null)
.mcastaddr
- is the multicast address to leaveIOException
- if there is an error leaving or when the address is not a multicast address.SecurityException
- if a security manager exists and its checkMulticast
method doesn't allow the operation.public void joinGroup(SocketAddress mcastaddr, NetworkInterface netIf) throws IOException
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.
mcastaddr
argument indicates the IP address of the multicast group to join. For historical reasons this is specified as a SocketAddress
. The default implementation only supports InetSocketAddress
and the port
information is ignored. netIf
argument specifies the local interface to receive multicast datagram packets, or 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
. 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 IOException
will be thrown.
If there is a security manager, this method first calls its checkMulticast
method with the mcastaddr
argument as its argument.
joinGroup
in class DatagramSocket
mcastaddr
- indicates the multicast address to join.netIf
- specifies the local interface to receive multicast datagram packets, or null
.IOException
- if there is an error joining, or when the address is not a multicast address, or the platform does not support multicastingSecurityException
- if a security manager exists and its checkMulticast
method doesn't allow the join.IllegalArgumentException
- if mcastaddr is null
or is a SocketAddress subclass not supported by this socketpublic void leaveGroup(SocketAddress mcastaddr, NetworkInterface netIf) throws IOException
If there is a security manager, this method first calls its checkMulticast
method with the mcastaddr
argument as its argument.
leaveGroup
in class DatagramSocket
mcastaddr
and netIf
arguments should identify a multicast group that was previously joined by this DatagramSocket
. 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 IOException
will be thrown.
mcastaddr
- is the multicast address to leave. This should contain the same IP address than that used for joining the group.netIf
- specifies the local interface or 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
.IOException
- if there is an error leaving or when the address is not a multicast address.SecurityException
- if a security manager exists and its checkMulticast
method doesn't allow the operation.IllegalArgumentException
- if mcastaddr is null
or is a SocketAddress subclass not supported by this socket.@Deprecated(since="14") public void setInterface(InetAddress inf) throws SocketException
setNetworkInterface(NetworkInterface)
instead.inf
- the InetAddressSocketException
- if there is an error in the underlying protocol, such as a TCP error.@Deprecated(since="14") public InetAddress getInterface() throws SocketException
getNetworkInterface()
instead.InetAddress
representing the address of the network interface used for multicast packets, or if no interface has been set, an InetAddress
representing any local address.SocketException
- if there is an error in the underlying protocol, such as a TCP error.public void setNetworkInterface(NetworkInterface netIf) throws SocketException
setOption(StandardSocketOptions.IP_MULTICAST_IF, netIf)
.netIf
- the interfaceSocketException
- if there is an error in the underlying protocol, such as a TCP error.public NetworkInterface getNetworkInterface() throws SocketException
getOption(StandardSocketOptions.IP_MULTICAST_IF)
.NetworkInterface
currently set. A placeholder NetworkInterface is returned when there is no interface set; it has a single InetAddress to represent any local address.SocketException
- if there is an error in the underlying protocol, such as a TCP error.@Deprecated(since="14") public void setLoopbackMode(boolean disable) throws SocketException
DatagramSocket.setOption(SocketOption, Object)
with StandardSocketOptions.IP_MULTICAST_LOOP
instead. The loopback mode is enabled by default, MulticastSocket.setOption(StandardSocketOptions.IP_MULTICAST_LOOP, false)
disables it.Because this option is a hint, applications that want to verify what loopback mode is set to should call getLoopbackMode()
disable
- true
to disable the LoopbackModeSocketException
- if an error occurs while setting the value@Deprecated(since="14") public boolean getLoopbackMode() throws SocketException
SocketException
- if an error occurs while getting the value@Deprecated public void send(DatagramPacket p, byte ttl) throws IOException
......
int ttl = mcastSocket.getOption(StandardSocketOptions.IP_MULTICAST_TTL);
mcastSocket.setOption(StandardSocketOptions.IP_MULTICAST_TTL, newttl);
mcastSocket.send(p);
mcastSocket.setOption(StandardSocketOptions.IP_MULTICAST_TTL, ttl);
......
setInterface
. If there is a security manager, this method first performs some security checks. First, if p.getAddress().isMulticastAddress()
is true, this method calls the security manager's checkMulticast
method with p.getAddress()
and ttl
as its arguments. If the evaluation of that expression is false, this method instead calls the security manager's checkConnect
method with arguments p.getAddress().getHostAddress()
and p.getPort()
. Each call to a security manager method could result in a SecurityException if the operation is not allowed.
p
- is the packet to be sent. The packet should contain the destination multicast ip address and the data to be sent. One does not need to be the member of the group to send packets to a destination multicast address.ttl
- optional time to live for multicast packet. default ttl is 1.IOException
- is raised if an error occurs i.e error while setting ttl.SecurityException
- if a security manager exists and its checkMulticast
or checkConnect
method doesn't allow the send.PortUnreachableException
- may be thrown if the socket is connected to a currently unreachable destination. Note, there is no guarantee that the exception will be thrown.IllegalArgumentException
- if the socket is connected, and connected address and packet address differ, or if the socket is not connected and the packet address is not set or if its port is out of range.
© 1993, 2023, 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/21/docs/api/java.base/java/net/MulticastSocket.html