https://openjdk.java.net/ 
/*
 * Copyright (c) 1995, 2019, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package java.net;

import java.io.IOException;
import java.util.Collections;
import java.util.Enumeration;
import java.util.Set;

The multicast datagram socket class is useful for sending
and receiving IP multicast packets. A MulticastSocket is
a (UDP) DatagramSocket, with additional capabilities for
joining "groups" of other multicast hosts on the internet.

 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 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(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 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. In addition to the socket options supported by DatagramSocket, a MulticastSocket supports the following socket options: 




Socket options

  

    Option Name
    Description
  



  

     IP_MULTICAST_IF 
     The network interface for Internet Protocol (IP) multicast datagrams 
  

  

     
      IP_MULTICAST_TTL 
     The time-to-live for Internet Protocol (IP) multicast
      datagrams 
  

  

     
      IP_MULTICAST_LOOP 
     Loopback for Internet Protocol (IP) multicast datagrams 
  






Additional (implementation specific) options may also be supported.

Author:Pavani Diwanji
Since:1.1
/**
 * The multicast datagram socket class is useful for sending
 * and receiving IP multicast packets. A MulticastSocket is
 * a (UDP) DatagramSocket, with additional capabilities for
 * joining "groups" of other multicast hosts on the internet.
 * <P>
 * 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.
 * <P>
 * One would join a multicast group by first creating a MulticastSocket
 * with the desired port, then invoking the
 * <CODE>joinGroup(InetAddress groupAddr)</CODE>
 * method:
 * <PRE>
 * // 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);
 * </PRE>
 *
 * When one sends a message to a multicast group, <B>all</B> 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.
 * <P>
 * 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.
 * <B>Multiple MulticastSockets</B> may subscribe to a multicast group
 * and port concurrently, and they will all receive group datagrams.
 *
 * <p> 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
 * <a href="DatagramSocket.html#SocketOptions">{@code DatagramSocket}</a>, a
 * {@code MulticastSocket} supports the following socket options:
 * <blockquote>
 * <a id="MulticastOptions"></a>
 * <table class="striped">
 * <caption style="display:none">Socket options</caption>
 * <thead>
 *   <tr>
 *     <th scope="col">Option Name</th>
 *     <th scope="col">Description</th>
 *   </tr>
 * </thead>
 * <tbody>
 *   <tr>
 *     <th scope="row"> {@link java.net.StandardSocketOptions#IP_MULTICAST_IF IP_MULTICAST_IF} </th>
 *     <td> The network interface for Internet Protocol (IP) multicast datagrams </td>
 *   </tr>
 *   <tr>
 *     <th scope="row"> {@link java.net.StandardSocketOptions#IP_MULTICAST_TTL
 *       IP_MULTICAST_TTL} </th>
 *     <td> The <em>time-to-live</em> for Internet Protocol (IP) multicast
 *       datagrams </td>
 *   </tr>
 *   <tr>
 *     <th scope="row"> {@link java.net.StandardSocketOptions#IP_MULTICAST_LOOP
 *       IP_MULTICAST_LOOP} </th>
 *     <td> Loopback for Internet Protocol (IP) multicast datagrams </td>
 *   </tr>
 * </tbody>
 * </table>
 * </blockquote>
 * Additional (implementation specific) options may also be supported.
 *
 * @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.

/**
     * Used on some platforms to record if an outgoing interface
     * has been set for this socket.
     */
    private boolean interfaceSet;

    
Create a multicast socket.

 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. 
Throws:
  • IOException – if an I/O exception occurs while creating the
MulticastSocket
  • SecurityException – if a security manager exists and its checkListen method doesn't allow the operation.
See Also:
/**
     * Create a multicast socket.
     *
     * <p>
     * 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.
     * <p>
     * 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 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. 
Params:
  • port – port to use
Throws:
  • IOException – if an I/O exception occurs
           while creating the MulticastSocket
  • SecurityException –  if a security manager exists and its checkListen method doesn't allow the operation.
See Also:
/**
     * Create a multicast socket and bind it to a specific port.
     *
     * <p>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.
     * <p>
     * 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 null, create an unbound socket. 
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. 
Params:
  • bindaddr – Socket address to bind to, or null for an unbound socket.
Throws:
  • IOException – if an I/O exception occurs
          while creating the MulticastSocket
  • SecurityException –  if a security manager exists and its checkListen method doesn't allow the operation.
See Also:
Since:1.4
/**
     * Create a MulticastSocket bound to the specified socket address.
     * <p>
     * Or, if the address is {@code null}, create an unbound socket.
     *
     * <p>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.
     * <p>
     * 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);

        // 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).

/**
     * 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

/**
     * 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

/**
     * 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 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 . 
Params:
  • ttl – the time-to-live
Throws:
  • IOException – if an I/O exception occurs
            while setting the default time-to-live value
See Also:
Deprecated:use the setTimeToLive method instead, which uses
            int instead of byte as the type for 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.
     *
     * <p>The ttl is an <b>unsigned</b> 8-bit quantity, and so <B>must</B> 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
     *             <b>int</b> instead of <b>byte</b> 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 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. 
Params:
  • ttl – 
        the time-to-live
Throws:
  • IOException – 
         if an I/O exception occurs while setting the
         default time-to-live value
See Also:
/**
     * Set the default time-to-live for multicast packets sent out
     * on this {@code MulticastSocket} in order to control the
     * scope of the multicasts.
     *
     * <P> The ttl <B>must</B> 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()
     */
    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
See Also:
Returns:the default time-to-live value
Deprecated:use the getTimeToLive method instead, which returns
an int instead of a byte.
/**
     * 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 <b>int</b> instead of a <b>byte</b>.
     * @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
See Also:
Returns:the default time-to-live value
/**
     * 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)
     */
    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 setInterface or setNetworkInterface. 
If there is a security manager, this method first calls its checkMulticast method with the mcastaddr argument as its argument. 
Params:
  • 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
  • SecurityException – if a security manager exists and its checkMulticast method doesn't allow the join.
See Also:
Deprecated:This method does not accept the network interface on which to join the multicast group. Use joinGroup(SocketAddress, NetworkInterface) instead.
/**
     * Joins a multicast group. Its behavior may be affected by
     * {@code setInterface} or {@code setNetworkInterface}.
     *
     * <p>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 setInterface or setNetworkInterface. 
If there is a security manager, this method first calls its checkMulticast method with the mcastaddr argument as its argument. 
Params:
  • mcastaddr – is the multicast address to leave
Throws:
  • 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.
See Also:
Deprecated:This method does not accept the network interface on which to leave the multicast group. Use leaveGroup(SocketAddress, NetworkInterface) instead.
/**
     * Leave a multicast group. Its behavior may be affected by
     * {@code setInterface} or {@code setNetworkInterface}.
     *
     * <p>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 checkMulticast method with the mcastaddr argument as its argument. 
Params:
  • mcastaddr – is the multicast address to join
  • netIf – specifies the local interface to receive multicast datagram packets, or null to defer to the interface set by setInterface(InetAddress) or setNetworkInterface(NetworkInterface). 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.
Throws:
  • IOException – if there is an error joining, or when the address
        is not a multicast address, or the platform does not support
        multicasting
  • SecurityException – 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 socket
See Also:
Since: 1.4
/**
     * Joins the specified multicast group at the specified interface.
     *
     * <p>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)
     * @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 checkMulticast method with the mcastaddr argument as its argument. 
Params:
  • mcastaddr – is the multicast address to leave
  • netIf – specifies the local interface or null to defer to the interface set by setInterface(InetAddress) or setNetworkInterface(NetworkInterface). 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.
Throws:
  • 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.
See Also:
Since: 1.4
/**
     * Leave a multicast group on a specified local interface.
     *
     * <p>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.

Params:
  • inf – the InetAddress
Throws:
  • SocketException – if there is an error in
            the underlying protocol, such as a TCP error.
See Also:
Deprecated:The InetAddress may not uniquely identify the network interface. Use setNetworkInterface(NetworkInterface) instead.
/**
     * 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.

Throws:
  • SocketException – if there is an error in the
            underlying protocol, such as a TCP error.
See Also:
Returns: An 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.
Deprecated:The network interface may not be uniquely identified by the InetAddress returned. Use getNetworkInterface() instead.
/**
     * 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<InetAddress> addrs = ni.getInetAddresses();
                while (addrs.hasMoreElements()) {
                    InetAddress addr = addrs.nextElement();
                    if (addr.equals(infAddress)) {
                        return infAddress;
                    }
                }

                /**
                 * No match so reset infAddress to indicate that the
                 * interface has changed via means
                 */
                infAddress = null;
                return ia;
            } catch (Exception e) {
                return ia;
            }
        }
    }

    
Specify the network interface for outgoing multicast datagrams
sent on this socket.

Params:
  • netIf – the interface
Throws:
  • SocketException – if there is an error in
the underlying protocol, such as a TCP error.
See Also:
Since:1.4
/**
     * Specify the network interface for outgoing multicast datagrams
     * sent on this socket.
     *
     * @param netIf the interface
     * @throws    SocketException if there is an error in
     * the underlying protocol, such as a TCP error.
     * @see #getNetworkInterface()
     * @since 1.4
     */
    public void setNetworkInterface(NetworkInterface netIf)
        throws SocketException {

        synchronized (infLock) {
            getImpl().setOption(SocketOptions.IP_MULTICAST_IF2, netIf);
            infAddress = null;
            interfaceSet = true;
        }
    }

    
Get the multicast network interface set.

Throws:
  • SocketException – if there is an error in
        the underlying protocol, such as a TCP error.
See Also:
Returns:The multicast NetworkInterface currently set. A placeholder NetworkInterface is returned when there is no interface set; it has a single InetAddress to represent any local address.
Since: 1.4
/**
     * Get the multicast network interface set.
     *
     * @throws SocketException if there is an error in
     *         the underlying protocol, such as a TCP error.
     * @return The multicast {@code NetworkInterface} currently set. A placeholder
     *         NetworkInterface is returned when there is no interface set; it has
     *         a single InetAddress to represent any local address.
     * @see    #setNetworkInterface(NetworkInterface)
     * @since  1.4
     */
    public NetworkInterface getNetworkInterface() throws SocketException {
        NetworkInterface ni
            = (NetworkInterface)getImpl().getOption(SocketOptions.IP_MULTICAST_IF2);
        if (ni == null) {
            InetAddress[] addrs = new InetAddress[1];
            addrs[0] = InetAddress.anyLocalAddress();
            return new NetworkInterface(addrs[0].getHostName(), 0, addrs);
        } else {
            return ni;
        }
    }

    
Disable/Enable local loopback of multicast datagrams
The option is used by the platform's networking code as a hint
for setting whether multicast data will be looped back to
the local socket.

Because this option is a hint, applications that want to verify what loopback mode is set to should call getLoopbackMode() 
Params:
  • disable – true to disable the LoopbackMode
Throws:
See Also:
Since:     1.4
Deprecated:Use DatagramSocket.setOption(SocketOption<Object>, Object) with StandardSocketOptions.IP_MULTICAST_LOOP instead. The loopback mode is enabled by default, MulticastSocket.setOption(StandardSocketOptions.IP_MULTICAST_LOOP, false) disables it.
/**
     * Disable/Enable local loopback of multicast datagrams
     * The option is used by the platform's networking code as a hint
     * for setting whether multicast data will be looped back to
     * the local socket.
     *
     * <p>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
See Also:
Returns:    true if the LoopbackMode has been disabled
Since:     1.4
Deprecated:Use DatagramSocket.getOption(SocketOption<Object>) with StandardSocketOptions.IP_MULTICAST_LOOP instead.
/**
     * 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 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. 
Params:
  • 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.
Throws:
  • 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.
See Also:
Deprecated:Use the following code or its equivalent instead:
 ......
 int ttl = mcastSocket.getTimeToLive();
 mcastSocket.setTimeToLive(newttl);
 mcastSocket.send(p);
 mcastSocket.setTimeToLive(ttl);
 ......
/**
     * 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 <B>not
     * </B> alter the default TTL for the socket. Its behavior may be
     * affected by {@code setInterface}.
     *
     * <p>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.
     *
     *
     * @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();
                    checkAddress(packetAddress, "send");
                    if (connectState == ST_NOT_CONNECTED) {
                        if (packetAddress == null) {
                            throw new IllegalArgumentException("Address not set");
                        }
                        // 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(),
                                                      p.getPort());
                            }
                        }
                    } else {
                        // we're connected
                        if (packetAddress == null) {
                            p.setAddress(connectedAddress);
                            p.setPort(connectedPort);
                        } else if ((!packetAddress.equals(connectedAddress)) ||
                                   p.getPort() != 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

    private static Set<SocketOption<?>> options;
    private static boolean optionsSet = false;

    @Override
    public Set<SocketOption<?>> supportedOptions() {
        synchronized (MulticastSocket.class) {
            if (optionsSet) {
                return options;
            }
            try {
                DatagramSocketImpl impl = getImpl();
                options = Collections.unmodifiableSet(impl.supportedOptions());
            } catch (SocketException ex) {
                options = Collections.emptySet();
            }
            optionsSet = true;
            return options;
        }
    }
}