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 supports <a href="http://www.ietf.org/rfc/rfc2236.txt">
44 * <i>RFC 2236: Internet Group Management Protocol, Version 2 (IGMPv2)</i></a>.
45 * It may optionally support source filtering as specified by <a
46 * href="http://www.ietf.org/rfc/rfc3376.txt"> <i>RFC 3376: Internet Group
47 * Management Protocol, Version 3 (IGMPv3)</i></a>.
48 * For channels to an {@link StandardProtocolFamily#INET6 IPv6} socket, the equivalent
49 * standards are <a href="http://www.ietf.org/rfc/rfc2710.txt"> <i>RFC 2710:
50 * Multicast Listener Discovery (MLD) for IPv6</i></a> and <a
51 * href="http://www.ietf.org/rfc/rfc3810.txt"> <i>RFC 3810: Multicast Listener
52 * Discovery Version 2 (MLDv2) for IPv6</i></a>.
53 *
54 * <p> The {@link #join(InetAddress,NetworkInterface)} method is used to
55 * join a group and receive all multicast datagrams sent to the group. A channel
56 * may join several multicast groups and may join the same group on several
57 * {@link NetworkInterface interfaces}. Membership is dropped by invoking the {@link
58 * MembershipKey#drop drop} method on the returned {@link MembershipKey}. If the
59 * underlying platform supports source filtering then the {@link MembershipKey#block
60 * block} and {@link MembershipKey#unblock unblock} methods can be used to block or
61 * unblock multicast datagrams from particular source addresses.
62 *
63 * <p> The {@link #join(InetAddress,NetworkInterface,InetAddress)} method
64 * is used to begin receiving datagrams sent to a group whose source address matches
65 * a given source address. This method throws {@link UnsupportedOperationException}
66 * if the underlying platform does not support source filtering. Membership is
67 * <em>cumulative</em> and this method may be invoked again with the same group
68 * and interface to allow receiving datagrams from other source addresses. The
69 * method returns a {@link MembershipKey} that represents membership to receive
70 * datagrams from the given source address. Invoking the key's {@link
71 * MembershipKey#drop drop} method drops membership so that datagrams from the
72 * source address can no longer be received.
73 *
74 * <h2>Platform dependencies</h2>
75 *
76 * The multicast implementation is intended to map directly to the native
77 * multicasting facility. Consequently, the following items should be considered
78 * when developing an application that receives IP multicast datagrams:
79 *
80 * <ol>
81 *
82 * <li><p> The creation of the channel should specify the {@link ProtocolFamily}
83 * that corresponds to the address type of the multicast groups that the channel
84 * will join. There is no guarantee that a channel to a socket in one protocol
85 * family can join and receive multicast datagrams when the address of the
86 * multicast group corresponds to another protocol family. For example, it is
87 * implementation specific if a channel to an {@link StandardProtocolFamily#INET6 IPv6}
88 * socket can join an {@link StandardProtocolFamily#INET IPv4} multicast group and receive
89 * multicast datagrams sent to the group. </p></li>
90 *
91 * <li><p> The channel's socket should be bound to the {@link
92 * InetAddress#isAnyLocalAddress wildcard} address. If the socket is bound to
93 * a specific address, rather than the wildcard address then it is implementation
94 * specific if multicast datagrams are received by the socket. </p></li>
95 *
96 * <li><p> The {@link StandardSocketOptions#SO_REUSEADDR SO_REUSEADDR} option should be
97 * enabled prior to {@link NetworkChannel#bind binding} the socket. This is
98 * required to allow multiple members of the group to bind to the same
99 * address. </p></li>
100 *
101 * </ol>
102 *
103 * <p> <b>Usage Example:</b>
104 * <pre>
105 * // join multicast group on this interface, and also use this
106 * // interface for outgoing multicast datagrams
107 * NetworkInterface ni = NetworkInterface.getByName("hme0");
108 *
109 * DatagramChannel dc = DatagramChannel.open(StandardProtocolFamily.INET)
110 * .setOption(StandardSocketOptions.SO_REUSEADDR, true)
111 * .bind(new InetSocketAddress(5000))
112 * .setOption(StandardSocketOptions.IP_MULTICAST_IF, ni);
113 *
114 * InetAddress group = InetAddress.getByName("225.4.5.6");
115 *
116 * MembershipKey key = dc.join(group, ni);
117 * </pre>
118 *
119 * @since 1.7
120 */
121
122 public interface MulticastChannel
123 extends NetworkChannel
124 {
125 /**
126 * Closes this channel.
127 *
128 * <p> If the channel is a member of a multicast group then the membership
129 * is {@link MembershipKey#drop dropped}. Upon return, the {@link
130 * MembershipKey membership-key} will be {@link MembershipKey#isValid
131 * invalid}.
132 *
133 * <p> This method otherwise behaves exactly as specified by the {@link
134 * Channel} interface.
135 *
136 * @throws IOException
137 * If an I/O error occurs
138 */
139 @Override void close() throws IOException;
140
141 /**
142 * Joins a multicast group to begin receiving all datagrams sent to the group,
143 * returning a membership key.
144 *
145 * <p> If this channel is currently a member of the group on the given
146 * interface to receive all datagrams then the membership key, representing
147 * that membership, is returned. Otherwise this channel joins the group and
148 * the resulting new membership key is returned. The resulting membership key
149 * is not {@link MembershipKey#sourceAddress source-specific}.
150 *
151 * <p> A multicast channel may join several multicast groups, including
152 * the same group on more than one interface. An implementation may impose a
153 * limit on the number of groups that may be joined at the same time.
154 *
155 * @param group
156 * The multicast address to join
157 * @param interf
158 * The network interface on which to join the group
159 *
160 * @return The membership key
161 *
162 * @throws IllegalArgumentException
163 * If the group parameter is not a {@link InetAddress#isMulticastAddress
164 * multicast} address, or the group parameter is an address type
165 * that is not supported by this channel
166 * @throws IllegalStateException
167 * If the channel already has source-specific membership of the
168 * group on the interface
169 * @throws UnsupportedOperationException
170 * If the channel's socket is not an Internet Protocol socket
171 * @throws ClosedChannelException
172 * If this channel is closed
173 * @throws IOException
174 * If an I/O error occurs
175 * @throws SecurityException
176 * If a security manager is set, and its
177 * {@link SecurityManager#checkMulticast(InetAddress) checkMulticast}
178 * method denies access to the multiast group
179 */
180 MembershipKey join(InetAddress group, NetworkInterface interf)
181 throws IOException;
182
183 /**
184 * Joins a multicast group to begin receiving datagrams sent to the group
185 * from a given source address.
186 *
187 * <p> If this channel is currently a member of the group on the given
188 * interface to receive datagrams from the given source address then the
189 * membership key, representing that membership, is returned. Otherwise this
190 * channel joins the group and the resulting new membership key is returned.
191 * The resulting membership key is {@link MembershipKey#sourceAddress
192 * source-specific}.
193 *
194 * <p> Membership is <em>cumulative</em> and this method may be invoked
195 * again with the same group and interface to allow receiving datagrams sent
196 * by other source addresses to the group.
197 *
198 * @param group
199 * The multicast address to join
200 * @param interf
201 * The network interface on which to join the group
202 * @param source
203 * The source address
204 *
205 * @return The membership key
206 *
207 * @throws IllegalArgumentException
208 * If the group parameter is not a {@link
209 * InetAddress#isMulticastAddress multicast} address, the
210 * source parameter is not a unicast address, the group
211 * parameter is an address type that is not supported by this channel,
212 * or the source parameter is not the same address type as the group
213 * @throws IllegalStateException
214 * If the channel is currently a member of the group on the given
215 * interface to receive all datagrams
216 * @throws UnsupportedOperationException
217 * If the channel's socket is not an Internet Protocol socket or
218 * source filtering is not supported
219 * @throws ClosedChannelException
220 * If this channel is closed
221 * @throws IOException
222 * If an I/O error occurs
223 * @throws SecurityException
224 * If a security manager is set, and its
225 * {@link SecurityManager#checkMulticast(InetAddress) checkMulticast}
226 * method denies access to the multiast group
227 */
228 MembershipKey join(InetAddress group, NetworkInterface interf, InetAddress source)
229 throws IOException;
230 }