View Javadoc
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&nbsp;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&nbsp;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&nbsp;2710:
50   * Multicast Listener Discovery (MLD) for IPv6</i></a> and <a
51   * href="http://www.ietf.org/rfc/rfc3810.txt"> <i>RFC&nbsp;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 }