java nio MulticastChannel源码分析

package java.nio.channels;

import java.net.InetAddress;
import java.net.NetworkInterface;
import java.io.IOException;
import java.net.ProtocolFamily;             // javadoc
import java.net.StandardProtocolFamily;     // javadoc
import java.net.StandardSocketOptions;      // javadoc

/**
 * 一种网络通道，它支持Internet协议(IP)组播。
 *
 * <p>IP多播是IP数据报的传输到由一个单一目的地址标识的0或多个主机的组的成员。
 *
 * <p> 在连接到IPv4套接字的通道的情况下，底层操作系统支持RFC 2236: 
 * Internet Group Management Protocol, Version 2 (IGMPv2)。
 * 它可以支持RFC 3376: Internet GroupManagement Protocol, Version 3 (IGMPv3)指定的源过滤。
 * 对于到IPv6套接字的通道，对应的标准是IPv6的RFC 2710:组播侦听器发现(MLD)和IPv6的RFC 3810:组播侦听器发现版本2 (MLDv2)。
 *
 * <p>  join(InetAddress, NetworkInterface)方法用于加入一个组，并接收发送到组的所有多播数据报。
 * 一个通道可以加入几个多播组，也可以在几个接口上加入同一个组。
 * 通过调用返回的MembershipKey上的drop方法来删除成员身份。
 * 如果底层平台支持源过滤，那么块和非块方法可以用来阻塞或不阻塞来自特定源地址的多播数据报。
 *
 * <p> join(InetAddress, NetworkInterface, InetAddress)方法用于开始接收发送到源地址与给定源地址匹配的组的数据报。
 * 此方法抛出UnsupportedOperationExceptionif底层平台不支持源过滤。
 * 成员关系是累积的，可以使用相同的组和接口再次调用此方法，以允许从其他源地址接收数据报。
 * 该方法返回一个MembershipKey，表示从给定源地址接收数据报的成员关系。
 * 调用键的drop方法将删除成员关系，以便不再接收来自源地址的数据报。
 *
 * <h2>平台的依赖</h2>
 *
 * 多播实现的目的是直接映射到本地的多播设施。
 * 因此，当开发一个接收IP多播数据报的应用程序时，应考虑以下事项:
 *
 * <ol>
 *
 * <li><p> 通道的创建应该指定对应于通道将要加入的多播组的地址类型的协议族。
 * 当一个组播组的地址对应于另一个协议族时，不能保证一个到套接字的通道可以连接和接收组播数据报。
 * 例如，如果一个到IPv6socket的通道可以加入一个IPv4组播组并接收发送到组播组的多播数据报，它是具体实现的。</p></li>
 *
 * <li><p>通道的套接字应该绑定到通配符地址。
 * 如果套接字绑定到一个特定的地址，而不是通配符地址，那么如果套接字接收多播数据报，它是实现特定的。 </p></li>
 *
 * <li><p> 在绑定套接字之前应该启用SO_REUSEADDR选项。这是允许组的多个成员绑定到同一个地址所必需的。</p></li>
 *
 * </ol>
 *
 * <p> <b>Usage Example:</b>
 * <pre>
 *     // join multicast group on this interface, and also use this
 *     // interface for outgoing multicast datagrams
 *     NetworkInterface ni = NetworkInterface.getByName("hme0");
 *
 *     DatagramChannel dc = DatagramChannel.open(StandardProtocolFamily.INET)
 *         .setOption(StandardSocketOptions.SO_REUSEADDR, true)
 *         .bind(new InetSocketAddress(5000))
 *         .setOption(StandardSocketOptions.IP_MULTICAST_IF, ni);
 *
 *     InetAddress group = InetAddress.getByName("225.4.5.6");
 *
 *     MembershipKey key = dc.join(group, ni);
 * </pre>
 *
 * @since 1.7
 */

public interface MulticastChannel
    extends NetworkChannel
{
    /**
     * 关闭这个通道。
     *
     * <p> 如果通道是多播组成员，则删除成员关系。返回时，会员密钥将无效。
     *
     * <p> 否则，此方法的行为与通道接口指定的完全一致。
     *
     * @throws  IOException
     *          If an I/O error occurs
     */
    @Override void close() throws IOException;

    /**
     * 加入多播组以开始接收发送到该组的所有数据报，并返回成员密钥。
     *
     * <p> 如果该通道目前是给定接口上接收所有数据报的组的成员，则返回代表该成员关系的成员密钥。
     * 否则，该通道将加入组，并返回产生的新成员关系密钥。产生的成员关系键不是特定于源的。
     *
     * <p> 一个多播通道可以加入几个多播组，包括多个接口上的同一组。
     * 一个实现可以对可能同时加入的组的数量施加限制。
     *
     * @param   group
     *          The multicast address to join
     * @param   interf
     *          The network interface on which to join the group
     *
     * @return  The membership key
     *
     * @throws  IllegalArgumentException
     *          If the group parameter is not a {@link InetAddress#isMulticastAddress
     *          multicast} address, or the group parameter is an address type
     *          that is not supported by this channel
     * @throws  IllegalStateException
     *          If the channel already has source-specific membership of the
     *          group on the interface
     * @throws  UnsupportedOperationException
     *          If the channel's socket is not an Internet Protocol socket
     * @throws  ClosedChannelException
     *          If this channel is closed
     * @throws  IOException
     *          If an I/O error occurs
     * @throws  SecurityException
     *          If a security manager is set, and its
     *          {@link SecurityManager#checkMulticast(InetAddress) checkMulticast}
     *          method denies access to the multiast group
     */
    MembershipKey join(InetAddress group, NetworkInterface interf)
        throws IOException;

    /**
     * 加入多播组，开始接收从给定源地址发送到组的数据报。
     *
     * <p> 如果该通道目前是给定接口上从给定源地址接收数据报的组的成员，则返回代表该成员关系的成员关系键。
     * 否则，该通道将加入组，并返回产生的新成员关系密钥。产生的成员关系键是特定于源的。
     *
     * <p> 成员关系是累积的，这个方法可以用相同的组和接口再次调用，以允许接收由其他源地址发送到组的数据报。
     *
     * @param   group
     *          The multicast address to join
     * @param   interf
     *          The network interface on which to join the group
     * @param   source
     *          The source address
     *
     * @return  The membership key
     *
     * @throws  IllegalArgumentException
     *          If the group parameter is not a {@link
     *          InetAddress#isMulticastAddress multicast} address, the
     *          source parameter is not a unicast address, the group
     *          parameter is an address type that is not supported by this channel,
     *          or the source parameter is not the same address type as the group
     * @throws  IllegalStateException
     *          If the channel is currently a member of the group on the given
     *          interface to receive all datagrams
     * @throws  UnsupportedOperationException
     *          If the channel's socket is not an Internet Protocol socket or
     *          source filtering is not supported
     * @throws  ClosedChannelException
     *          If this channel is closed
     * @throws  IOException
     *          If an I/O error occurs
     * @throws  SecurityException
     *          If a security manager is set, and its
     *          {@link SecurityManager#checkMulticast(InetAddress) checkMulticast}
     *          method denies access to the multiast group
     */
    MembershipKey join(InetAddress group, NetworkInterface interf, InetAddress source)
        throws IOException;
}