author | lana |
Thu, 26 Dec 2013 12:04:16 -0800 | |
changeset 23010 | 6dadb192ad81 |
parent 18574 | 4aeaeb541678 |
permissions | -rw-r--r-- |
1152 | 1 |
/* |
23010
6dadb192ad81
8029235: Update copyright year to match last edit in jdk8 jdk repository for 2013
lana
parents:
18574
diff
changeset
|
2 |
* Copyright (c) 2007, 2013, Oracle and/or its affiliates. All rights reserved. |
1152 | 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 |
|
5506 | 7 |
* published by the Free Software Foundation. Oracle designates this |
1152 | 8 |
* particular file as subject to the "Classpath" exception as provided |
5506 | 9 |
* by Oracle in the LICENSE file that accompanied this code. |
1152 | 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 |
* |
|
5506 | 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. |
|
1152 | 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 |
|
9679
d98ae8bc45fc
7042979: Rename StandardSocketOption and StandardWatchEventKind
alanb
parents:
5506
diff
changeset
|
33 |
import java.net.StandardSocketOptions; // javadoc |
1152 | 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 |
* |
|
18574
4aeaeb541678
8019380: doclint warnings in java.nio, java.nio.file.**, java.nio.channels.**
alanb
parents:
14342
diff
changeset
|
74 |
* <h2>Platform dependencies</h2> |
1152 | 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 |
* |
|
9679
d98ae8bc45fc
7042979: Rename StandardSocketOption and StandardWatchEventKind
alanb
parents:
5506
diff
changeset
|
96 |
* <li><p> The {@link StandardSocketOptions#SO_REUSEADDR SO_REUSEADDR} option should be |
1152 | 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) |
|
9679
d98ae8bc45fc
7042979: Rename StandardSocketOption and StandardWatchEventKind
alanb
parents:
5506
diff
changeset
|
110 |
* .setOption(StandardSocketOptions.SO_REUSEADDR, true) |
1152 | 111 |
* .bind(new InetSocketAddress(5000)) |
9679
d98ae8bc45fc
7042979: Rename StandardSocketOption and StandardWatchEventKind
alanb
parents:
5506
diff
changeset
|
112 |
* .setOption(StandardSocketOptions.IP_MULTICAST_IF, ni); |
1152 | 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 |
/** |
|
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
1152
diff
changeset
|
126 |
* Closes this channel. |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
1152
diff
changeset
|
127 |
* |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
1152
diff
changeset
|
128 |
* <p> If the channel is a member of a multicast group then the membership |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
1152
diff
changeset
|
129 |
* is {@link MembershipKey#drop dropped}. Upon return, the {@link |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
1152
diff
changeset
|
130 |
* MembershipKey membership-key} will be {@link MembershipKey#isValid |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
1152
diff
changeset
|
131 |
* invalid}. |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
1152
diff
changeset
|
132 |
* |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
1152
diff
changeset
|
133 |
* <p> This method otherwise behaves exactly as specified by the {@link |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
1152
diff
changeset
|
134 |
* Channel} interface. |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
1152
diff
changeset
|
135 |
* |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
1152
diff
changeset
|
136 |
* @throws IOException |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
1152
diff
changeset
|
137 |
* If an I/O error occurs |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
1152
diff
changeset
|
138 |
*/ |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
1152
diff
changeset
|
139 |
@Override void close() throws IOException; |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
1152
diff
changeset
|
140 |
|
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
1152
diff
changeset
|
141 |
/** |
1152 | 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 |
|
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
1152
diff
changeset
|
149 |
* is not {@link MembershipKey#sourceAddress source-specific}. |
1152 | 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 |
|
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
1152
diff
changeset
|
169 |
* @throws UnsupportedOperationException |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
1152
diff
changeset
|
170 |
* If the channel's socket is not an Internet Protocol socket |
1152 | 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. |
|
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
1152
diff
changeset
|
191 |
* The resulting membership key is {@link MembershipKey#sourceAddress |
1152 | 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 |
|
2057
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
1152
diff
changeset
|
217 |
* If the channel's socket is not an Internet Protocol socket or |
3acf8e5e2ca0
6781363: New I/O: Update socket-channel API to jsr203/nio2-b99
alanb
parents:
1152
diff
changeset
|
218 |
* source filtering is not supported |
1152 | 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 |
} |