1 /*
   2  * Copyright (c) 2007, 2013, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package java.nio.channels;
  27 
  28 import java.net.InetAddress;
  29 import java.net.NetworkInterface;
  30 import java.io.IOException;
  31 import java.net.ProtocolFamily;             // javadoc
  32 import java.net.StandardProtocolFamily;     // javadoc
  33 import java.net.StandardSocketOptions;      // javadoc
  34 
  35 /**
  36  * A network channel that supports Internet Protocol (IP) multicasting.
  37  *
  38  * <p> IP multicasting is the transmission of IP datagrams to members of
  39  * a <em>group</em> that is zero or more hosts identified by a single destination
  40  * address.
  41  *
  42  * <p> In the case of a channel to an {@link StandardProtocolFamily#INET IPv4} socket,
  43  * the underlying operating system optionally supports
  44  * <a href="http://www.ietf.org/rfc/rfc2236.txt"> <i>RFC&nbsp;2236: Internet Group
  45  * Management Protocol, Version 2 (IGMPv2)</i></a>. When IGMPv2 is supported then
  46  * the operating system may additionally support source filtering as specified by
  47  * <a href="http://www.ietf.org/rfc/rfc3376.txt"> <i>RFC&nbsp;3376: Internet Group
  48  * Management Protocol, Version 3 (IGMPv3)</i></a>.
  49  * For channels to an {@link StandardProtocolFamily#INET6 IPv6} socket, the equivalent
  50  * standards are <a href="http://www.ietf.org/rfc/rfc2710.txt"> <i>RFC&nbsp;2710:
  51  * Multicast Listener Discovery (MLD) for IPv6</i></a> and <a
  52  * href="http://www.ietf.org/rfc/rfc3810.txt"> <i>RFC&nbsp;3810: Multicast Listener
  53  * Discovery Version 2 (MLDv2) for IPv6</i></a>.
  54  *
  55  * <p> The {@link #join(InetAddress,NetworkInterface)} method is used to
  56  * join a group and receive all multicast datagrams sent to the group. A channel
  57  * may join several multicast groups and may join the same group on several
  58  * {@link NetworkInterface interfaces}. Membership is dropped by invoking the {@link
  59  * MembershipKey#drop drop} method on the returned {@link MembershipKey}. If the
  60  * underlying platform supports source filtering then the {@link MembershipKey#block
  61  * block} and {@link MembershipKey#unblock unblock} methods can be used to block or
  62  * unblock multicast datagrams from particular source addresses.
  63  *
  64  * <p> The {@link #join(InetAddress,NetworkInterface,InetAddress)} method
  65  * is used to begin receiving datagrams sent to a group whose source address matches
  66  * a given source address. This method throws {@link UnsupportedOperationException}
  67  * if the underlying platform does not support source filtering.  Membership is
  68  * <em>cumulative</em> and this method may be invoked again with the same group
  69  * and interface to allow receiving datagrams from other source addresses. The
  70  * method returns a {@link MembershipKey} that represents membership to receive
  71  * datagrams from the given source address. Invoking the key's {@link
  72  * MembershipKey#drop drop} method drops membership so that datagrams from the
  73  * source address can no longer be received.
  74  *
  75  * <h2>Platform dependencies</h2>
  76  *
  77  * The multicast implementation is intended to map directly to the native
  78  * multicasting facility. Consequently, the following items should be considered
  79  * when developing an application that receives IP multicast datagrams:
  80  *
  81  * <ol>
  82  *
  83  * <li><p> The creation of the channel should specify the {@link ProtocolFamily}
  84  * that corresponds to the address type of the multicast groups that the channel
  85  * will join. There is no guarantee that a channel to a socket in one protocol
  86  * family can join and receive multicast datagrams when the address of the
  87  * multicast group corresponds to another protocol family. For example, it is
  88  * implementation specific if a channel to an {@link StandardProtocolFamily#INET6 IPv6}
  89  * socket can join an {@link StandardProtocolFamily#INET IPv4} multicast group and receive
  90  * multicast datagrams sent to the group. </p></li>
  91  *
  92  * <li><p> The channel's socket should be bound to the {@link
  93  * InetAddress#isAnyLocalAddress wildcard} address. If the socket is bound to
  94  * a specific address, rather than the wildcard address then it is implementation
  95  * specific if multicast datagrams are received by the socket. </p></li>
  96  *
  97  * <li><p> The {@link StandardSocketOptions#SO_REUSEADDR SO_REUSEADDR} option should be
  98  * enabled prior to {@link NetworkChannel#bind binding} the socket. This is
  99  * required to allow multiple members of the group to bind to the same
 100  * address. </p></li>
 101  *
 102  * </ol>
 103  *
 104  * <p> <b>Usage Example:</b>
 105  * <pre>
 106  *     // join multicast group on this interface, and also use this
 107  *     // interface for outgoing multicast datagrams
 108  *     NetworkInterface ni = NetworkInterface.getByName("hme0");
 109  *
 110  *     DatagramChannel dc = DatagramChannel.open(StandardProtocolFamily.INET)
 111  *         .setOption(StandardSocketOptions.SO_REUSEADDR, true)
 112  *         .bind(new InetSocketAddress(5000))
 113  *         .setOption(StandardSocketOptions.IP_MULTICAST_IF, ni);
 114  *
 115  *     InetAddress group = InetAddress.getByName("225.4.5.6");
 116  *
 117  *     MembershipKey key = dc.join(group, ni);
 118  * </pre>
 119  *
 120  * @since 1.7
 121  */
 122 
 123 public interface MulticastChannel
 124     extends NetworkChannel
 125 {
 126     /**
 127      * Closes this channel.
 128      *
 129      * <p> If the channel is a member of a multicast group then the membership
 130      * is {@link MembershipKey#drop dropped}. Upon return, the {@link
 131      * MembershipKey membership-key} will be {@link MembershipKey#isValid
 132      * invalid}.
 133      *
 134      * <p> This method otherwise behaves exactly as specified by the {@link
 135      * Channel} interface.
 136      *
 137      * @throws  IOException
 138      *          If an I/O error occurs
 139      */
 140     @Override void close() throws IOException;
 141 
 142     /**
 143      * Joins a multicast group to begin receiving all datagrams sent to the group,
 144      * returning a membership key.
 145      *
 146      * <p> If this channel is currently a member of the group on the given
 147      * interface to receive all datagrams then the membership key, representing
 148      * that membership, is returned. Otherwise this channel joins the group and
 149      * the resulting new membership key is returned. The resulting membership key
 150      * is not {@link MembershipKey#sourceAddress source-specific}.
 151      *
 152      * <p> A multicast channel may join several multicast groups, including
 153      * the same group on more than one interface. An implementation may impose a
 154      * limit on the number of groups that may be joined at the same time.
 155      *
 156      * @param   group
 157      *          The multicast address to join
 158      * @param   interf
 159      *          The network interface on which to join the group
 160      *
 161      * @return  The membership key
 162      *
 163      * @throws  IllegalArgumentException
 164      *          If the group parameter is not a {@link InetAddress#isMulticastAddress
 165      *          multicast} address, or the group parameter is an address type
 166      *          that is not supported by this channel
 167      * @throws  IllegalStateException
 168      *          If the channel already has source-specific membership of the
 169      *          group on the interface
 170      * @throws  UnsupportedOperationException
 171      *          If the channel's socket is not an Internet Protocol socket, or
 172      *          the platform does not support multicasting
 173      * @throws  ClosedChannelException
 174      *          If this channel is closed
 175      * @throws  IOException
 176      *          If an I/O error occurs
 177      * @throws  SecurityException
 178      *          If a security manager is set, and its
 179      *          {@link SecurityManager#checkMulticast(InetAddress) checkMulticast}
 180      *          method denies access to the multicast group
 181      */
 182     MembershipKey join(InetAddress group, NetworkInterface interf)
 183         throws IOException;
 184 
 185     /**
 186      * Joins a multicast group to begin receiving datagrams sent to the group
 187      * from a given source address.
 188      *
 189      * <p> If this channel is currently a member of the group on the given
 190      * interface to receive datagrams from the given source address then the
 191      * membership key, representing that membership, is returned. Otherwise this
 192      * channel joins the group and the resulting new membership key is returned.
 193      * The resulting membership key is {@link MembershipKey#sourceAddress
 194      * source-specific}.
 195      *
 196      * <p> Membership is <em>cumulative</em> and this method may be invoked
 197      * again with the same group and interface to allow receiving datagrams sent
 198      * by other source addresses to the group.
 199      *
 200      * @param   group
 201      *          The multicast address to join
 202      * @param   interf
 203      *          The network interface on which to join the group
 204      * @param   source
 205      *          The source address
 206      *
 207      * @return  The membership key
 208      *
 209      * @throws  IllegalArgumentException
 210      *          If the group parameter is not a {@link
 211      *          InetAddress#isMulticastAddress multicast} address, the
 212      *          source parameter is not a unicast address, the group
 213      *          parameter is an address type that is not supported by this channel,
 214      *          or the source parameter is not the same address type as the group
 215      * @throws  IllegalStateException
 216      *          If the channel is currently a member of the group on the given
 217      *          interface to receive all datagrams
 218      * @throws  UnsupportedOperationException
 219      *          If the channel's socket is not an Internet Protocol socket, or
 220      *          source filtering is not supported, or the platform does not
 221      *          support multicasting
 222      * @throws  ClosedChannelException
 223      *          If this channel is closed
 224      * @throws  IOException
 225      *          If an I/O error occurs
 226      * @throws  SecurityException
 227      *          If a security manager is set, and its
 228      *          {@link SecurityManager#checkMulticast(InetAddress) checkMulticast}
 229      *          method denies access to the multicast group
 230      */
 231     MembershipKey join(InetAddress group, NetworkInterface interf, InetAddress source)
 232         throws IOException;
 233 }