1 /*
2 * Copyright (c) 2000, 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.io.IOException;
29 import java.net.ProtocolFamily;
30 import java.net.DatagramSocket;
31 import java.net.SocketOption;
32 import java.net.SocketAddress;
33 import java.nio.ByteBuffer;
34 import java.nio.channels.spi.AbstractSelectableChannel;
35 import java.nio.channels.spi.SelectorProvider;
36
37 /**
38 * A selectable channel for datagram-oriented sockets.
39 *
40 * <p> A datagram channel is created by invoking one of the {@link #open open} methods
41 * of this class. It is not possible to create a channel for an arbitrary,
42 * pre-existing datagram socket. A newly-created datagram channel is open but not
43 * connected. A datagram channel need not be connected in order for the {@link #send
44 * send} and {@link #receive receive} methods to be used. A datagram channel may be
45 * connected, by invoking its {@link #connect connect} method, in order to
46 * avoid the overhead of the security checks are otherwise performed as part of
47 * every send and receive operation. A datagram channel must be connected in
48 * order to use the {@link #read(java.nio.ByteBuffer) read} and {@link
49 * #write(java.nio.ByteBuffer) write} methods, since those methods do not
50 * accept or return socket addresses.
51 *
52 * <p> Once connected, a datagram channel remains connected until it is
53 * disconnected or closed. Whether or not a datagram channel is connected may
54 * be determined by invoking its {@link #isConnected isConnected} method.
55 *
56 * <p> Socket options are configured using the {@link #setOption(SocketOption,Object)
57 * setOption} method. A datagram channel to an Internet Protocol socket supports
58 * the following options:
59 * <blockquote>
60 * <table border summary="Socket options">
61 * <tr>
62 * <th>Option Name</th>
63 * <th>Description</th>
64 * </tr>
65 * <tr>
66 * <td> {@link java.net.StandardSocketOptions#SO_SNDBUF SO_SNDBUF} </td>
67 * <td> The size of the socket send buffer </td>
68 * </tr>
69 * <tr>
70 * <td> {@link java.net.StandardSocketOptions#SO_RCVBUF SO_RCVBUF} </td>
71 * <td> The size of the socket receive buffer </td>
72 * </tr>
73 * <tr>
74 * <td> {@link java.net.StandardSocketOptions#SO_REUSEADDR SO_REUSEADDR} </td>
75 * <td> Re-use address </td>
76 * </tr>
77 * <tr>
78 * <td> {@link java.net.StandardSocketOptions#SO_BROADCAST SO_BROADCAST} </td>
79 * <td> Allow transmission of broadcast datagrams </td>
80 * </tr>
81 * <tr>
82 * <td> {@link java.net.StandardSocketOptions#IP_TOS IP_TOS} </td>
83 * <td> The Type of Service (ToS) octet in the Internet Protocol (IP) header </td>
84 * </tr>
85 * <tr>
86 * <td> {@link java.net.StandardSocketOptions#IP_MULTICAST_IF IP_MULTICAST_IF} </td>
87 * <td> The network interface for Internet Protocol (IP) multicast datagrams </td>
88 * </tr>
89 * <tr>
90 * <td> {@link java.net.StandardSocketOptions#IP_MULTICAST_TTL
91 * IP_MULTICAST_TTL} </td>
92 * <td> The <em>time-to-live</em> for Internet Protocol (IP) multicast
93 * datagrams </td>
94 * </tr>
95 * <tr>
96 * <td> {@link java.net.StandardSocketOptions#IP_MULTICAST_LOOP
97 * IP_MULTICAST_LOOP} </td>
98 * <td> Loopback for Internet Protocol (IP) multicast datagrams </td>
99 * </tr>
100 * </table>
101 * </blockquote>
102 * Additional (implementation specific) options may also be supported.
103 *
104 * <p> Datagram channels are safe for use by multiple concurrent threads. They
105 * support concurrent reading and writing, though at most one thread may be
106 * reading and at most one thread may be writing at any given time. </p>
107 *
108 * @author Mark Reinhold
109 * @author JSR-51 Expert Group
110 * @since 1.4
111 */
112
113 public abstract class DatagramChannel
114 extends AbstractSelectableChannel
115 implements ByteChannel, ScatteringByteChannel, GatheringByteChannel, MulticastChannel
116 {
117
118 /**
119 * Initializes a new instance of this class.
120 *
121 * @param provider
122 * The provider that created this channel
123 */
124 protected DatagramChannel(SelectorProvider provider) {
125 super(provider);
126 }
127
128 /**
129 * Opens a datagram channel.
130 *
131 * <p> The new channel is created by invoking the {@link
132 * java.nio.channels.spi.SelectorProvider#openDatagramChannel()
133 * openDatagramChannel} method of the system-wide default {@link
134 * java.nio.channels.spi.SelectorProvider} object. The channel will not be
135 * connected.
136 *
137 * <p> The {@link ProtocolFamily ProtocolFamily} of the channel's socket
138 * is platform (and possibly configuration) dependent and therefore unspecified.
139 * The {@link #open(ProtocolFamily) open} allows the protocol family to be
140 * selected when opening a datagram channel, and should be used to open
141 * datagram channels that are intended for Internet Protocol multicasting.
142 *
143 * @return A new datagram channel
144 *
145 * @throws IOException
146 * If an I/O error occurs
147 */
148 public static DatagramChannel open() throws IOException {
149 return SelectorProvider.provider().openDatagramChannel();
150 }
151
152 /**
153 * Opens a datagram channel.
154 *
155 * <p> The {@code family} parameter is used to specify the {@link
156 * ProtocolFamily}. If the datagram channel is to be used for IP multicasting
157 * then this should correspond to the address type of the multicast groups
158 * that this channel will join.
159 *
160 * <p> The new channel is created by invoking the {@link
161 * java.nio.channels.spi.SelectorProvider#openDatagramChannel(ProtocolFamily)
162 * openDatagramChannel} method of the system-wide default {@link
163 * java.nio.channels.spi.SelectorProvider} object. The channel will not be
164 * connected.
165 *
166 * @param family
167 * The protocol family
168 *
169 * @return A new datagram channel
170 *
171 * @throws UnsupportedOperationException
172 * If the specified protocol family is not supported. For example,
173 * suppose the parameter is specified as {@link
174 * java.net.StandardProtocolFamily#INET6 StandardProtocolFamily.INET6}
175 * but IPv6 is not enabled on the platform.
176 * @throws IOException
177 * If an I/O error occurs
178 *
179 * @since 1.7
180 */
181 public static DatagramChannel open(ProtocolFamily family) throws IOException {
182 return SelectorProvider.provider().openDatagramChannel(family);
183 }
184
185 /**
186 * Returns an operation set identifying this channel's supported
187 * operations.
188 *
189 * <p> Datagram channels support reading and writing, so this method
190 * returns {@code (}{@link SelectionKey#OP_READ} {@code |} {@link
191 * SelectionKey#OP_WRITE}{@code )}.
192 *
193 * @return The valid-operation set
194 */
195 public final int validOps() {
196 return (SelectionKey.OP_READ
197 | SelectionKey.OP_WRITE);
198 }
199
200
201 // -- Socket-specific operations --
202
203 /**
204 * @throws AlreadyBoundException {@inheritDoc}
205 * @throws UnsupportedAddressTypeException {@inheritDoc}
206 * @throws ClosedChannelException {@inheritDoc}
207 * @throws IOException {@inheritDoc}
208 * @throws SecurityException
209 * If a security manager has been installed and its {@link
210 * SecurityManager#checkListen checkListen} method denies the
211 * operation
212 *
213 * @since 1.7
214 */
215 public abstract DatagramChannel bind(SocketAddress local)
216 throws IOException;
217
218 /**
219 * @throws UnsupportedOperationException {@inheritDoc}
220 * @throws IllegalArgumentException {@inheritDoc}
221 * @throws ClosedChannelException {@inheritDoc}
222 * @throws IOException {@inheritDoc}
223 *
224 * @since 1.7
225 */
226 public abstract <T> DatagramChannel setOption(SocketOption<T> name, T value)
227 throws IOException;
228
229 /**
230 * Retrieves a datagram socket associated with this channel.
231 *
232 * <p> The returned object will not declare any public methods that are not
233 * declared in the {@link java.net.DatagramSocket} class. </p>
234 *
235 * @return A datagram socket associated with this channel
236 */
237 public abstract DatagramSocket socket();
238
239 /**
240 * Tells whether or not this channel's socket is connected.
241 *
242 * @return {@code true} if, and only if, this channel's socket
243 * is {@link #isOpen open} and connected
244 */
245 public abstract boolean isConnected();
246
247 /**
248 * Connects this channel's socket.
249 *
250 * <p> The channel's socket is configured so that it only receives
251 * datagrams from, and sends datagrams to, the given remote <i>peer</i>
252 * address. Once connected, datagrams may not be received from or sent to
253 * any other address. A datagram socket remains connected until it is
254 * explicitly disconnected or until it is closed.
255 *
256 * <p> This method performs exactly the same security checks as the {@link
257 * java.net.DatagramSocket#connect connect} method of the {@link
258 * java.net.DatagramSocket} class. That is, if a security manager has been
259 * installed then this method verifies that its {@link
260 * java.lang.SecurityManager#checkAccept checkAccept} and {@link
261 * java.lang.SecurityManager#checkConnect checkConnect} methods permit
262 * datagrams to be received from and sent to, respectively, the given
263 * remote address.
264 *
265 * <p> This method may be invoked at any time. It will not have any effect
266 * on read or write operations that are already in progress at the moment
267 * that it is invoked. If this channel's socket is not bound then this method
268 * will first cause the socket to be bound to an address that is assigned
269 * automatically, as if invoking the {@link #bind bind} method with a
270 * parameter of {@code null}. </p>
271 *
272 * @param remote
273 * The remote address to which this channel is to be connected
274 *
275 * @return This datagram channel
276 *
277 * @throws ClosedChannelException
278 * If this channel is closed
279 *
280 * @throws AsynchronousCloseException
281 * If another thread closes this channel
282 * while the connect operation is in progress
283 *
284 * @throws ClosedByInterruptException
285 * If another thread interrupts the current thread
286 * while the connect operation is in progress, thereby
287 * closing the channel and setting the current thread's
288 * interrupt status
289 *
290 * @throws SecurityException
291 * If a security manager has been installed
292 * and it does not permit access to the given remote address
293 *
294 * @throws IOException
295 * If some other I/O error occurs
296 */
297 public abstract DatagramChannel connect(SocketAddress remote)
298 throws IOException;
299
300 /**
301 * Disconnects this channel's socket.
302 *
303 * <p> The channel's socket is configured so that it can receive datagrams
304 * from, and sends datagrams to, any remote address so long as the security
305 * manager, if installed, permits it.
306 *
307 * <p> This method may be invoked at any time. It will not have any effect
308 * on read or write operations that are already in progress at the moment
309 * that it is invoked.
310 *
311 * <p> If this channel's socket is not connected, or if the channel is
312 * closed, then invoking this method has no effect. </p>
313 *
314 * @return This datagram channel
315 *
316 * @throws IOException
317 * If some other I/O error occurs
318 */
319 public abstract DatagramChannel disconnect() throws IOException;
320
321 /**
322 * Returns the remote address to which this channel's socket is connected.
323 *
324 * @return The remote address; {@code null} if the channel's socket is not
325 * connected
326 *
327 * @throws ClosedChannelException
328 * If the channel is closed
329 * @throws IOException
330 * If an I/O error occurs
331 *
332 * @since 1.7
333 */
334 public abstract SocketAddress getRemoteAddress() throws IOException;
335
336 /**
337 * Receives a datagram via this channel.
338 *
339 * <p> If a datagram is immediately available, or if this channel is in
340 * blocking mode and one eventually becomes available, then the datagram is
341 * copied into the given byte buffer and its source address is returned.
342 * If this channel is in non-blocking mode and a datagram is not
343 * immediately available then this method immediately returns
344 * {@code null}.
345 *
346 * <p> The datagram is transferred into the given byte buffer starting at
347 * its current position, as if by a regular {@link
348 * ReadableByteChannel#read(java.nio.ByteBuffer) read} operation. If there
349 * are fewer bytes remaining in the buffer than are required to hold the
350 * datagram then the remainder of the datagram is silently discarded.
351 *
352 * <p> This method performs exactly the same security checks as the {@link
353 * java.net.DatagramSocket#receive receive} method of the {@link
354 * java.net.DatagramSocket} class. That is, if the socket is not connected
355 * to a specific remote address and a security manager has been installed
356 * then for each datagram received this method verifies that the source's
357 * address and port number are permitted by the security manager's {@link
358 * java.lang.SecurityManager#checkAccept checkAccept} method. The overhead
359 * of this security check can be avoided by first connecting the socket via
360 * the {@link #connect connect} method.
361 *
362 * <p> This method may be invoked at any time. If another thread has
363 * already initiated a read operation upon this channel, however, then an
364 * invocation of this method will block until the first operation is
365 * complete. If this channel's socket is not bound then this method will
366 * first cause the socket to be bound to an address that is assigned
367 * automatically, as if invoking the {@link #bind bind} method with a
368 * parameter of {@code null}. </p>
369 *
370 * @param dst
371 * The buffer into which the datagram is to be transferred
372 *
373 * @return The datagram's source address,
374 * or {@code null} if this channel is in non-blocking mode
375 * and no datagram was immediately available
376 *
377 * @throws ClosedChannelException
378 * If this channel is closed
379 *
380 * @throws AsynchronousCloseException
381 * If another thread closes this channel
382 * while the read operation is in progress
383 *
384 * @throws ClosedByInterruptException
385 * If another thread interrupts the current thread
386 * while the read operation is in progress, thereby
387 * closing the channel and setting the current thread's
388 * interrupt status
389 *
390 * @throws SecurityException
391 * If a security manager has been installed
392 * and it does not permit datagrams to be accepted
393 * from the datagram's sender
394 *
395 * @throws IOException
396 * If some other I/O error occurs
397 */
398 public abstract SocketAddress receive(ByteBuffer dst) throws IOException;
399
400 /**
401 * Sends a datagram via this channel.
402 *
403 * <p> If this channel is in non-blocking mode and there is sufficient room
404 * in the underlying output buffer, or if this channel is in blocking mode
405 * and sufficient room becomes available, then the remaining bytes in the
406 * given buffer are transmitted as a single datagram to the given target
407 * address.
408 *
409 * <p> The datagram is transferred from the byte buffer as if by a regular
410 * {@link WritableByteChannel#write(java.nio.ByteBuffer) write} operation.
411 *
412 * <p> This method performs exactly the same security checks as the {@link
413 * java.net.DatagramSocket#send send} method of the {@link
414 * java.net.DatagramSocket} class. That is, if the socket is not connected
415 * to a specific remote address and a security manager has been installed
416 * then for each datagram sent this method verifies that the target address
417 * and port number are permitted by the security manager's {@link
418 * java.lang.SecurityManager#checkConnect checkConnect} method. The
419 * overhead of this security check can be avoided by first connecting the
420 * socket via the {@link #connect connect} method.
421 *
422 * <p> This method may be invoked at any time. If another thread has
423 * already initiated a write operation upon this channel, however, then an
424 * invocation of this method will block until the first operation is
425 * complete. If this channel's socket is not bound then this method will
426 * first cause the socket to be bound to an address that is assigned
427 * automatically, as if by invoking the {@link #bind bind} method with a
428 * parameter of {@code null}. </p>
429 *
430 * @param src
431 * The buffer containing the datagram to be sent
432 *
433 * @param target
434 * The address to which the datagram is to be sent
435 *
436 * @return The number of bytes sent, which will be either the number
437 * of bytes that were remaining in the source buffer when this
438 * method was invoked or, if this channel is non-blocking, may be
439 * zero if there was insufficient room for the datagram in the
440 * underlying output buffer
441 *
442 * @throws ClosedChannelException
443 * If this channel is closed
444 *
445 * @throws AsynchronousCloseException
446 * If another thread closes this channel
447 * while the read operation is in progress
448 *
449 * @throws ClosedByInterruptException
450 * If another thread interrupts the current thread
451 * while the read operation is in progress, thereby
452 * closing the channel and setting the current thread's
453 * interrupt status
454 *
455 * @throws SecurityException
456 * If a security manager has been installed
457 * and it does not permit datagrams to be sent
458 * to the given address
459 *
460 * @throws IOException
461 * If some other I/O error occurs
462 */
463 public abstract int send(ByteBuffer src, SocketAddress target)
464 throws IOException;
465
466
467 // -- ByteChannel operations --
468
469 /**
470 * Reads a datagram from this channel.
471 *
472 * <p> This method may only be invoked if this channel's socket is
473 * connected, and it only accepts datagrams from the socket's peer. If
474 * there are more bytes in the datagram than remain in the given buffer
475 * then the remainder of the datagram is silently discarded. Otherwise
476 * this method behaves exactly as specified in the {@link
477 * ReadableByteChannel} interface. </p>
478 *
479 * @throws NotYetConnectedException
480 * If this channel's socket is not connected
481 */
482 public abstract int read(ByteBuffer dst) throws IOException;
483
484 /**
485 * Reads a datagram from this channel.
486 *
487 * <p> This method may only be invoked if this channel's socket is
488 * connected, and it only accepts datagrams from the socket's peer. If
489 * there are more bytes in the datagram than remain in the given buffers
490 * then the remainder of the datagram is silently discarded. Otherwise
491 * this method behaves exactly as specified in the {@link
492 * ScatteringByteChannel} interface. </p>
493 *
494 * @throws NotYetConnectedException
495 * If this channel's socket is not connected
496 */
497 public abstract long read(ByteBuffer[] dsts, int offset, int length)
498 throws IOException;
499
500 /**
501 * Reads a datagram from this channel.
502 *
503 * <p> This method may only be invoked if this channel's socket is
504 * connected, and it only accepts datagrams from the socket's peer. If
505 * there are more bytes in the datagram than remain in the given buffers
506 * then the remainder of the datagram is silently discarded. Otherwise
507 * this method behaves exactly as specified in the {@link
508 * ScatteringByteChannel} interface. </p>
509 *
510 * @throws NotYetConnectedException
511 * If this channel's socket is not connected
512 */
513 public final long read(ByteBuffer[] dsts) throws IOException {
514 return read(dsts, 0, dsts.length);
515 }
516
517 /**
518 * Writes a datagram to this channel.
519 *
520 * <p> This method may only be invoked if this channel's socket is
521 * connected, in which case it sends datagrams directly to the socket's
522 * peer. Otherwise it behaves exactly as specified in the {@link
523 * WritableByteChannel} interface. </p>
524 *
525 * @throws NotYetConnectedException
526 * If this channel's socket is not connected
527 */
528 public abstract int write(ByteBuffer src) throws IOException;
529
530 /**
531 * Writes a datagram to this channel.
532 *
533 * <p> This method may only be invoked if this channel's socket is
534 * connected, in which case it sends datagrams directly to the socket's
535 * peer. Otherwise it behaves exactly as specified in the {@link
536 * GatheringByteChannel} interface. </p>
537 *
538 * @return The number of bytes sent, which will be either the number
539 * of bytes that were remaining in the source buffer when this
540 * method was invoked or, if this channel is non-blocking, may be
541 * zero if there was insufficient room for the datagram in the
542 * underlying output buffer
543 *
544 * @throws NotYetConnectedException
545 * If this channel's socket is not connected
546 */
547 public abstract long write(ByteBuffer[] srcs, int offset, int length)
548 throws IOException;
549
550 /**
551 * Writes a datagram to this channel.
552 *
553 * <p> This method may only be invoked if this channel's socket is
554 * connected, in which case it sends datagrams directly to the socket's
555 * peer. Otherwise it behaves exactly as specified in the {@link
556 * GatheringByteChannel} interface. </p>
557 *
558 * @return The number of bytes sent, which will be either the number
559 * of bytes that were remaining in the source buffer when this
560 * method was invoked or, if this channel is non-blocking, may be
561 * zero if there was insufficient room for the datagram in the
562 * underlying output buffer
563 *
564 * @throws NotYetConnectedException
565 * If this channel's socket is not connected
566 */
567 public final long write(ByteBuffer[] srcs) throws IOException {
568 return write(srcs, 0, srcs.length);
569 }
570
571 /**
572 * {@inheritDoc}
573 * <p>
574 * If there is a security manager set, its {@code checkConnect} method is
575 * called with the local address and {@code -1} as its arguments to see
576 * if the operation is allowed. If the operation is not allowed,
577 * a {@code SocketAddress} representing the
578 * {@link java.net.InetAddress#getLoopbackAddress loopback} address and the
579 * local port of the channel's socket is returned.
580 *
581 * @return The {@code SocketAddress} that the socket is bound to, or the
582 * {@code SocketAddress} representing the loopback address if
583 * denied by the security manager, or {@code null} if the
584 * channel's socket is not bound
585 *
586 * @throws ClosedChannelException {@inheritDoc}
587 * @throws IOException {@inheritDoc}
588 */
589 @Override
590 public abstract SocketAddress getLocalAddress() throws IOException;
591
592 }