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 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 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 2710: 51 * Multicast Listener Discovery (MLD) for IPv6</i></a> and <a 52 * href="http://www.ietf.org/rfc/rfc3810.txt"> <i>RFC 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 */ close()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 multiast group 181 */ join(InetAddress group, NetworkInterface interf)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 multiast group 230 */ join(InetAddress group, NetworkInterface interf, InetAddress source)231 MembershipKey join(InetAddress group, NetworkInterface interf, InetAddress source) 232 throws IOException; 233 } 234