* A 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 {@code 224.0.0.0} to {@code 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(InetAddress groupAddr)
* method:
*
* // 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, port);
* NetworkInterface netIf = NetworkInterface.getByName("bge0");
* MulticastSocket s = new MulticastSocket(6789);
*
* s.joinGroup(group, netIf);
* byte[] msgBytes = msg.getBytes(StandardCharsets.UTF_8);
* DatagramPacket hi = new DatagramPacket(msgBytes, msgBytes.length,
* group, 6789);
* 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 {@code DatagramSocket} and {@code MulticastSocket} * classes define convenience methods to set and get several * socket options. Like {@code DatagramSocket} this class also * supports the {@link #setOption(SocketOption, Object) setOption} * and {@link #getOption(SocketOption) getOption} methods to set * and query socket options. * In addition to the socket options supported by * {@code DatagramSocket}, a * {@code MulticastSocket} supports the following socket options: *
* ** Additional (implementation specific) options may also be supported. * * @apiNote {@link DatagramChannel} implements the {@link MulticastChannel} interface * and provides an alternative API for sending and receiving multicast datagrams. * The {@link MulticastChannel} API supports both {@linkplain * MulticastChannel#join(InetAddress, NetworkInterface) any-source} and * {@linkplain MulticastChannel#join(InetAddress, NetworkInterface, InetAddress) * source-specific} multicast. * * @author Pavani Diwanji * @since 1.1 */ public class MulticastSocket extends DatagramSocket { /** * Used on some platforms to record if an outgoing interface * has been set for this socket. */ private boolean interfaceSet; /** * Create a multicast socket. * ** * *
** * * *Option Name *Description ** *{@link java.net.StandardSocketOptions#IP_MULTICAST_IF IP_MULTICAST_IF} *The network interface for Internet Protocol (IP) multicast datagrams ** *{@link java.net.StandardSocketOptions#IP_MULTICAST_TTL * IP_MULTICAST_TTL} *The time-to-live for Internet Protocol (IP) multicast * datagrams ** * *{@link java.net.StandardSocketOptions#IP_MULTICAST_LOOP * IP_MULTICAST_LOOP} *Loopback for Internet Protocol (IP) multicast datagrams *
* If there is a security manager, its {@code 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 * {@link DatagramSocket#setReuseAddress(boolean)} method is called to * enable the SO_REUSEADDR socket option. * * @throws IOException if an I/O exception occurs while creating the * MulticastSocket * @throws SecurityException if a security manager exists and its * {@code checkListen} method doesn't allow the operation. * @see SecurityManager#checkListen * @see java.net.DatagramSocket#setReuseAddress(boolean) * @see java.net.DatagramSocketImpl#setOption(SocketOption, Object) */ public MulticastSocket() throws IOException { this(new InetSocketAddress(0)); } /** * Create a multicast socket and bind it to a specific port. * *
If there is a security manager, * its {@code checkListen} method is first called * with the {@code port} argument * as its argument to ensure the operation is allowed. * This could result in a SecurityException. *
* When the socket is created the * {@link DatagramSocket#setReuseAddress(boolean)} method is * called to enable the SO_REUSEADDR socket option. * * @param port port to use * @throws IOException if an I/O exception occurs * while creating the MulticastSocket * @throws SecurityException if a security manager exists and its * {@code checkListen} method doesn't allow the operation. * @see SecurityManager#checkListen * @see java.net.DatagramSocket#setReuseAddress(boolean) */ public MulticastSocket(int port) throws IOException { this(new InetSocketAddress(port)); } /** * Create a MulticastSocket bound to the specified socket address. *
* Or, if the address is {@code null}, create an unbound socket. * *
If there is a security manager, * its {@code 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 * {@link DatagramSocket#setReuseAddress(boolean)} method is * called to enable the SO_REUSEADDR socket option. * * @param bindaddr Socket address to bind to, or {@code null} for * an unbound socket. * @throws IOException if an I/O exception occurs * while creating the MulticastSocket * @throws SecurityException if a security manager exists and its * {@code checkListen} method doesn't allow the operation. * @see SecurityManager#checkListen * @see java.net.DatagramSocket#setReuseAddress(boolean) * * @since 1.4 */ public MulticastSocket(SocketAddress bindaddr) throws IOException { super((SocketAddress) null); // No further initialization when this is a DatagramChannel socket adaptor if (this instanceof sun.nio.ch.DatagramSocketAdaptor) return; // Enable SO_REUSEADDR before binding setReuseAddress(true); if (bindaddr != null) { try { bind(bindaddr); } finally { if (!isBound()) { close(); } } } } /** * The lock on the socket's TTL. This is for set/getTTL and * send(packet,ttl). */ private Object ttlLock = new Object(); /** * The lock on the socket's interface - used by setInterface * and getInterface */ private Object infLock = new Object(); /** * The "last" interface set by setInterface on this MulticastSocket */ private InetAddress infAddress = null; /** * Set the default time-to-live for multicast packets sent out * on this {@code 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 {@code 0 <= ttl <= 0xFF }. * * @param ttl the time-to-live * @throws IOException if an I/O exception occurs * while setting the default time-to-live value * @deprecated use the setTimeToLive method instead, which uses * int instead of byte as the type for ttl. * @see #getTTL() */ @Deprecated public void setTTL(byte ttl) throws IOException { if (isClosed()) throw new SocketException("Socket is closed"); getImpl().setTTL(ttl); } /** * Set the default time-to-live for multicast packets sent out * on this {@code MulticastSocket} in order to control the * scope of the multicasts. * *
The ttl must be in the range {@code 0 <= ttl <= * 255} or an {@code IllegalArgumentException} will be thrown. * Multicast packets sent with a TTL of {@code 0} are not transmitted * on the network but may be delivered locally. * * @param ttl * the time-to-live * * @throws IOException * if an I/O exception occurs while setting the * default time-to-live value * * @see #getTimeToLive() * @since 1.2 */ public void setTimeToLive(int ttl) throws IOException { if (ttl < 0 || ttl > 255) { throw new IllegalArgumentException("ttl out of range"); } if (isClosed()) throw new SocketException("Socket is closed"); getImpl().setTimeToLive(ttl); } /** * Get the default time-to-live for multicast packets sent out on * the socket. * * @throws IOException if an I/O exception occurs * while getting the default time-to-live value * @return the default time-to-live value * @deprecated use the getTimeToLive method instead, which returns * an int instead of a byte. * @see #setTTL(byte) */ @Deprecated public byte getTTL() throws IOException { if (isClosed()) throw new SocketException("Socket is closed"); return getImpl().getTTL(); } /** * Get the default time-to-live for multicast packets sent out on * the socket. * @throws IOException if an I/O exception occurs while * getting the default time-to-live value * @return the default time-to-live value * @see #setTimeToLive(int) * @since 1.2 */ public int getTimeToLive() throws IOException { if (isClosed()) throw new SocketException("Socket is closed"); return getImpl().getTimeToLive(); } /** * Joins a multicast group. Its behavior may be affected by * {@code setInterface} or {@code setNetworkInterface}. * *
If there is a security manager, this method first * calls its {@code checkMulticast} method with the * {@code mcastaddr} argument as its argument. * * @param mcastaddr is the multicast address to join * @throws IOException if there is an error joining, * or when the address is not a multicast address, * or the platform does not support multicasting * @throws SecurityException if a security manager exists and its * {@code checkMulticast} method doesn't allow the join. * @deprecated This method does not accept the network interface on * which to join the multicast group. Use * {@link #joinGroup(SocketAddress, NetworkInterface)} instead. * @see SecurityManager#checkMulticast(InetAddress) */ @Deprecated(since="14") public void joinGroup(InetAddress mcastaddr) throws IOException { if (isClosed()) { throw new SocketException("Socket is closed"); } checkAddress(mcastaddr, "joinGroup"); SecurityManager security = System.getSecurityManager(); if (security != null) { security.checkMulticast(mcastaddr); } if (!mcastaddr.isMulticastAddress()) { throw new SocketException("Not a multicast address"); } /** * required for some platforms where it's not possible to join * a group without setting the interface first. */ NetworkInterface defaultInterface = NetworkInterface.getDefault(); if (!interfaceSet && defaultInterface != null) { setNetworkInterface(defaultInterface); } getImpl().join(mcastaddr); } /** * Leave a multicast group. Its behavior may be affected by * {@code setInterface} or {@code setNetworkInterface}. * *
If there is a security manager, this method first * calls its {@code checkMulticast} method with the * {@code mcastaddr} argument as its argument. * * @param mcastaddr is the multicast address to leave * @throws IOException if there is an error leaving * or when the address is not a multicast address. * @throws SecurityException if a security manager exists and its * {@code checkMulticast} method doesn't allow the operation. * @deprecated This method does not accept the network interface on which * to leave the multicast group. Use * {@link #leaveGroup(SocketAddress, NetworkInterface)} instead. * @see SecurityManager#checkMulticast(InetAddress) */ @Deprecated(since="14") public void leaveGroup(InetAddress mcastaddr) throws IOException { if (isClosed()) { throw new SocketException("Socket is closed"); } checkAddress(mcastaddr, "leaveGroup"); SecurityManager security = System.getSecurityManager(); if (security != null) { security.checkMulticast(mcastaddr); } if (!mcastaddr.isMulticastAddress()) { throw new SocketException("Not a multicast address"); } getImpl().leave(mcastaddr); } /** * Joins the specified multicast group at the specified interface. * *
If there is a security manager, this method first * calls its {@code checkMulticast} method * with the {@code mcastaddr} argument * as its argument. * * @param mcastaddr is the multicast address to join * @param netIf specifies the local interface to receive multicast * datagram packets, or {@code null} to defer to the interface set by * {@link MulticastSocket#setInterface(InetAddress)} or * {@link MulticastSocket#setNetworkInterface(NetworkInterface)}. * If {@code null}, and no interface has been set, the behaviour is * unspecified: any interface may be selected or the operation may fail * with a {@code SocketException}. * @throws IOException if there is an error joining, or when the address * is not a multicast address, or the platform does not support * multicasting * @throws SecurityException if a security manager exists and its * {@code checkMulticast} method doesn't allow the join. * @throws IllegalArgumentException if mcastaddr is {@code null} or is a * SocketAddress subclass not supported by this socket * @see SecurityManager#checkMulticast(InetAddress) * @see DatagramChannel#join(InetAddress, NetworkInterface) * @since 1.4 */ public void joinGroup(SocketAddress mcastaddr, NetworkInterface netIf) throws IOException { if (isClosed()) throw new SocketException("Socket is closed"); if (mcastaddr == null || !(mcastaddr instanceof InetSocketAddress)) throw new IllegalArgumentException("Unsupported address type"); if (oldImpl) throw new UnsupportedOperationException(); checkAddress(((InetSocketAddress)mcastaddr).getAddress(), "joinGroup"); SecurityManager security = System.getSecurityManager(); if (security != null) { security.checkMulticast(((InetSocketAddress)mcastaddr).getAddress()); } if (!((InetSocketAddress)mcastaddr).getAddress().isMulticastAddress()) { throw new SocketException("Not a multicast address"); } getImpl().joinGroup(mcastaddr, netIf); } /** * Leave a multicast group on a specified local interface. * *
If there is a security manager, this method first
* calls its {@code checkMulticast} method with the
* {@code mcastaddr} argument as its argument.
*
* @param mcastaddr is the multicast address to leave
* @param netIf specifies the local interface or {@code null} to defer
* to the interface set by
* {@link MulticastSocket#setInterface(InetAddress)} or
* {@link MulticastSocket#setNetworkInterface(NetworkInterface)}.
* If {@code null}, and no interface has been set, the behaviour
* is unspecified: any interface may be selected or the operation
* may fail with a {@code SocketException}.
* @throws IOException if there is an error leaving or when the address
* is not a multicast address.
* @throws SecurityException if a security manager exists and its
* {@code checkMulticast} method doesn't allow the operation.
* @throws IllegalArgumentException if mcastaddr is {@code null} or is a
* SocketAddress subclass not supported by this socket.
* @see SecurityManager#checkMulticast(InetAddress)
* @since 1.4
*/
public void leaveGroup(SocketAddress mcastaddr, NetworkInterface netIf)
throws IOException {
if (isClosed())
throw new SocketException("Socket is closed");
if (mcastaddr == null || !(mcastaddr instanceof InetSocketAddress))
throw new IllegalArgumentException("Unsupported address type");
if (oldImpl)
throw new UnsupportedOperationException();
checkAddress(((InetSocketAddress)mcastaddr).getAddress(), "leaveGroup");
SecurityManager security = System.getSecurityManager();
if (security != null) {
security.checkMulticast(((InetSocketAddress)mcastaddr).getAddress());
}
if (!((InetSocketAddress)mcastaddr).getAddress().isMulticastAddress()) {
throw new SocketException("Not a multicast address");
}
getImpl().leaveGroup(mcastaddr, netIf);
}
/**
* Set the multicast network interface used by methods
* whose behavior would be affected by the value of the
* network interface. Useful for multihomed hosts.
*
* @param inf the InetAddress
* @throws SocketException if there is an error in
* the underlying protocol, such as a TCP error.
* @deprecated The InetAddress may not uniquely identify
* the network interface. Use
* {@link #setNetworkInterface(NetworkInterface)} instead.
* @see #getInterface()
*/
@Deprecated(since="14")
public void setInterface(InetAddress inf) throws SocketException {
if (isClosed()) {
throw new SocketException("Socket is closed");
}
checkAddress(inf, "setInterface");
synchronized (infLock) {
getImpl().setOption(SocketOptions.IP_MULTICAST_IF, inf);
infAddress = inf;
interfaceSet = true;
}
}
/**
* Retrieve the address of the network interface used for
* multicast packets.
*
* @return An {@code InetAddress} representing the address
* of the network interface used for multicast packets,
* or if no interface has been set, an {@code InetAddress}
* representing any local address.
* @throws SocketException if there is an error in the
* underlying protocol, such as a TCP error.
* @deprecated The network interface may not be uniquely identified by
* the InetAddress returned.
* Use {@link #getNetworkInterface()} instead.
* @see #setInterface(java.net.InetAddress)
*/
@Deprecated(since="14")
public InetAddress getInterface() throws SocketException {
if (isClosed()) {
throw new SocketException("Socket is closed");
}
synchronized (infLock) {
InetAddress ia =
(InetAddress)getImpl().getOption(SocketOptions.IP_MULTICAST_IF);
/**
* No previous setInterface or interface can be
* set using setNetworkInterface
*/
if (infAddress == null) {
return ia;
}
/**
* Same interface set with setInterface?
*/
if (ia.equals(infAddress)) {
return ia;
}
/**
* Different InetAddress from what we set with setInterface
* so enumerate the current interface to see if the
* address set by setInterface is bound to this interface.
*/
try {
NetworkInterface ni = NetworkInterface.getByInetAddress(ia);
Enumeration Because this option is a hint, applications that want to
* verify what loopback mode is set to should call
* {@link #getLoopbackMode()}
* @param disable {@code true} to disable the LoopbackMode
* @throws SocketException if an error occurs while setting the value
* @since 1.4
* @deprecated Use {@link #setOption(SocketOption, Object)} with
* {@link java.net.StandardSocketOptions#IP_MULTICAST_LOOP}
* instead. The loopback mode is enabled by default,
* {@code MulticastSocket.setOption(StandardSocketOptions.IP_MULTICAST_LOOP, false)}
* disables it.
* @see #getLoopbackMode
*/
@Deprecated(since="14")
public void setLoopbackMode(boolean disable) throws SocketException {
getImpl().setOption(SocketOptions.IP_MULTICAST_LOOP, Boolean.valueOf(disable));
}
/**
* Get the setting for local loopback of multicast datagrams.
*
* @throws SocketException if an error occurs while getting the value
* @return true if the LoopbackMode has been disabled
* @since 1.4
* @deprecated Use {@link #getOption(SocketOption)} with
* {@link java.net.StandardSocketOptions#IP_MULTICAST_LOOP}
* instead.
* @see #setLoopbackMode
*/
@Deprecated(since="14")
public boolean getLoopbackMode() throws SocketException {
return ((Boolean)getImpl().getOption(SocketOptions.IP_MULTICAST_LOOP)).booleanValue();
}
/**
* Sends a datagram packet to the destination, with a TTL (time-
* to-live) other than the default for the socket. This method
* need only be used in instances where a particular TTL is desired;
* otherwise it is preferable to set a TTL once on the socket, and
* use that default TTL for all packets. This method does not
* alter the default TTL for the socket. Its behavior may be
* affected by {@code setInterface}.
*
* If there is a security manager, this method first performs some
* security checks. First, if {@code p.getAddress().isMulticastAddress()}
* is true, this method calls the
* security manager's {@code checkMulticast} method
* with {@code p.getAddress()} and {@code ttl} as its arguments.
* If the evaluation of that expression is false,
* this method instead calls the security manager's
* {@code checkConnect} method with arguments
* {@code p.getAddress().getHostAddress()} and
* {@code p.getPort()}. Each call to a security manager method
* could result in a SecurityException if the operation is not allowed.
*
* @param 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.
* @param ttl optional time to live for multicast packet.
* default ttl is 1.
*
* @throws IOException is raised if an error occurs i.e
* error while setting ttl.
* @throws SecurityException if a security manager exists and its
* {@code checkMulticast} or {@code checkConnect}
* method doesn't allow the send.
* @throws 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.
* @throws 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.
*
*
* @deprecated Use the following code or its equivalent instead:
* ......
* int ttl = mcastSocket.getTimeToLive();
* mcastSocket.setTimeToLive(newttl);
* mcastSocket.send(p);
* mcastSocket.setTimeToLive(ttl);
* ......
*
* @see DatagramSocket#send
* @see DatagramSocket#receive
* @see SecurityManager#checkMulticast(java.net.InetAddress, byte)
* @see SecurityManager#checkConnect
*/
@Deprecated
public void send(DatagramPacket p, byte ttl)
throws IOException {
if (isClosed())
throw new SocketException("Socket is closed");
synchronized(ttlLock) {
synchronized(p) {
InetAddress packetAddress = p.getAddress();
int packetPort = p.getPort();
checkAddress(packetAddress, "send");
if (connectState == ST_NOT_CONNECTED) {
if (packetAddress == null) {
throw new IllegalArgumentException("Address not set");
}
if (packetPort < 0 || packetPort > 0xFFFF)
throw new IllegalArgumentException("port out of range:" + packetPort);
// Security manager makes sure that the multicast address
// is allowed one and that the ttl used is less
// than the allowed maxttl.
SecurityManager security = System.getSecurityManager();
if (security != null) {
if (packetAddress.isMulticastAddress()) {
security.checkMulticast(packetAddress, ttl);
} else {
security.checkConnect(packetAddress.getHostAddress(),
packetPort);
}
}
} else {
// we're connected
if (packetAddress == null) {
p.setAddress(connectedAddress);
p.setPort(connectedPort);
} else if ((!packetAddress.equals(connectedAddress)) ||
packetPort != connectedPort) {
throw new IllegalArgumentException("connected address and packet address" +
" differ");
}
}
byte dttl = getTTL();
try {
if (ttl != dttl) {
// set the ttl
getImpl().setTTL(ttl);
}
// call the datagram method to send
getImpl().send(p);
} finally {
// set it back to default
if (ttl != dttl) {
getImpl().setTTL(dttl);
}
}
} // synch p
} //synch ttl
} //method
}