| /* |
| * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved. |
| * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
| * |
| * This code is free software; you can redistribute it and/or modify it |
| * under the terms of the GNU General Public License version 2 only, as |
| * published by the Free Software Foundation. Oracle designates this |
| * particular file as subject to the "Classpath" exception as provided |
| * by Oracle in the LICENSE file that accompanied this code. |
| * |
| * This code is distributed in the hope that it will be useful, but WITHOUT |
| * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
| * version 2 for more details (a copy is included in the LICENSE file that |
| * accompanied this code). |
| * |
| * You should have received a copy of the GNU General Public License version |
| * 2 along with this work; if not, write to the Free Software Foundation, |
| * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
| * |
| * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
| * or visit www.oracle.com if you need additional information or have any |
| * questions. |
| */ |
| |
| package java.nio.channels; |
| |
| import java.io.IOException; |
| import java.net.ProtocolFamily; |
| import java.net.DatagramSocket; |
| import java.net.SocketOption; |
| import java.net.SocketAddress; |
| import java.nio.ByteBuffer; |
| import java.nio.channels.spi.AbstractSelectableChannel; |
| import java.nio.channels.spi.SelectorProvider; |
| |
| /** |
| * A selectable channel for datagram-oriented sockets. |
| * |
| * <p> A datagram channel is created by invoking one of the {@link #open open} methods |
| * of this class. It is not possible to create a channel for an arbitrary, |
| * pre-existing datagram socket. A newly-created datagram channel is open but not |
| * connected. A datagram channel need not be connected in order for the {@link #send |
| * send} and {@link #receive receive} methods to be used. A datagram channel may be |
| * connected, by invoking its {@link #connect connect} method, in order to |
| * avoid the overhead of the security checks are otherwise performed as part of |
| * every send and receive operation. A datagram channel must be connected in |
| * order to use the {@link #read(java.nio.ByteBuffer) read} and {@link |
| * #write(java.nio.ByteBuffer) write} methods, since those methods do not |
| * accept or return socket addresses. |
| * |
| * <p> Once connected, a datagram channel remains connected until it is |
| * disconnected or closed. Whether or not a datagram channel is connected may |
| * be determined by invoking its {@link #isConnected isConnected} method. |
| * |
| * <p> Socket options are configured using the {@link #setOption(SocketOption,Object) |
| * setOption} method. A datagram channel to an Internet Protocol socket supports |
| * the following options: |
| * <blockquote> |
| * <table border summary="Socket options"> |
| * <tr> |
| * <th>Option Name</th> |
| * <th>Description</th> |
| * </tr> |
| * <tr> |
| * <td> {@link java.net.StandardSocketOptions#SO_SNDBUF SO_SNDBUF} </td> |
| * <td> The size of the socket send buffer </td> |
| * </tr> |
| * <tr> |
| * <td> {@link java.net.StandardSocketOptions#SO_RCVBUF SO_RCVBUF} </td> |
| * <td> The size of the socket receive buffer </td> |
| * </tr> |
| * <tr> |
| * <td> {@link java.net.StandardSocketOptions#SO_REUSEADDR SO_REUSEADDR} </td> |
| * <td> Re-use address </td> |
| * </tr> |
| * <tr> |
| * <td> {@link java.net.StandardSocketOptions#SO_BROADCAST SO_BROADCAST} </td> |
| * <td> Allow transmission of broadcast datagrams </td> |
| * </tr> |
| * <tr> |
| * <td> {@link java.net.StandardSocketOptions#IP_TOS IP_TOS} </td> |
| * <td> The Type of Service (ToS) octet in the Internet Protocol (IP) header </td> |
| * </tr> |
| * <tr> |
| * <td> {@link java.net.StandardSocketOptions#IP_MULTICAST_IF IP_MULTICAST_IF} </td> |
| * <td> The network interface for Internet Protocol (IP) multicast datagrams </td> |
| * </tr> |
| * <tr> |
| * <td> {@link java.net.StandardSocketOptions#IP_MULTICAST_TTL |
| * IP_MULTICAST_TTL} </td> |
| * <td> The <em>time-to-live</em> for Internet Protocol (IP) multicast |
| * datagrams </td> |
| * </tr> |
| * <tr> |
| * <td> {@link java.net.StandardSocketOptions#IP_MULTICAST_LOOP |
| * IP_MULTICAST_LOOP} </td> |
| * <td> Loopback for Internet Protocol (IP) multicast datagrams </td> |
| * </tr> |
| * </table> |
| * </blockquote> |
| * Additional (implementation specific) options may also be supported. |
| * |
| * <p> Datagram channels are safe for use by multiple concurrent threads. They |
| * support concurrent reading and writing, though at most one thread may be |
| * reading and at most one thread may be writing at any given time. </p> |
| * |
| * @author Mark Reinhold |
| * @author JSR-51 Expert Group |
| * @since 1.4 |
| */ |
| |
| public abstract class DatagramChannel |
| extends AbstractSelectableChannel |
| implements ByteChannel, ScatteringByteChannel, GatheringByteChannel, MulticastChannel |
| { |
| |
| /** |
| * Initializes a new instance of this class. |
| * |
| * @param provider |
| * The provider that created this channel |
| */ |
| protected DatagramChannel(SelectorProvider provider) { |
| super(provider); |
| } |
| |
| /** |
| * Opens a datagram channel. |
| * |
| * <p> The new channel is created by invoking the {@link |
| * java.nio.channels.spi.SelectorProvider#openDatagramChannel() |
| * openDatagramChannel} method of the system-wide default {@link |
| * java.nio.channels.spi.SelectorProvider} object. The channel will not be |
| * connected. |
| * |
| * <p> The {@link ProtocolFamily ProtocolFamily} of the channel's socket |
| * is platform (and possibly configuration) dependent and therefore unspecified. |
| * The {@link #open(ProtocolFamily) open} allows the protocol family to be |
| * selected when opening a datagram channel, and should be used to open |
| * datagram channels that are intended for Internet Protocol multicasting. |
| * |
| * @return A new datagram channel |
| * |
| * @throws IOException |
| * If an I/O error occurs |
| */ |
| public static DatagramChannel open() throws IOException { |
| return SelectorProvider.provider().openDatagramChannel(); |
| } |
| |
| /** |
| * Opens a datagram channel. |
| * |
| * <p> The {@code family} parameter is used to specify the {@link |
| * ProtocolFamily}. If the datagram channel is to be used for IP multicasting |
| * then this should correspond to the address type of the multicast groups |
| * that this channel will join. |
| * |
| * <p> The new channel is created by invoking the {@link |
| * java.nio.channels.spi.SelectorProvider#openDatagramChannel(ProtocolFamily) |
| * openDatagramChannel} method of the system-wide default {@link |
| * java.nio.channels.spi.SelectorProvider} object. The channel will not be |
| * connected. |
| * |
| * @param family |
| * The protocol family |
| * |
| * @return A new datagram channel |
| * |
| * @throws UnsupportedOperationException |
| * If the specified protocol family is not supported. For example, |
| * suppose the parameter is specified as {@link |
| * java.net.StandardProtocolFamily#INET6 StandardProtocolFamily.INET6} |
| * but IPv6 is not enabled on the platform. |
| * @throws IOException |
| * If an I/O error occurs |
| * |
| * @since 1.7 |
| */ |
| public static DatagramChannel open(ProtocolFamily family) throws IOException { |
| return SelectorProvider.provider().openDatagramChannel(family); |
| } |
| |
| /** |
| * Returns an operation set identifying this channel's supported |
| * operations. |
| * |
| * <p> Datagram channels support reading and writing, so this method |
| * returns <tt>(</tt>{@link SelectionKey#OP_READ} <tt>|</tt> {@link |
| * SelectionKey#OP_WRITE}<tt>)</tt>. </p> |
| * |
| * @return The valid-operation set |
| */ |
| public final int validOps() { |
| return (SelectionKey.OP_READ |
| | SelectionKey.OP_WRITE); |
| } |
| |
| |
| // -- Socket-specific operations -- |
| |
| /** |
| * @throws AlreadyBoundException {@inheritDoc} |
| * @throws UnsupportedAddressTypeException {@inheritDoc} |
| * @throws ClosedChannelException {@inheritDoc} |
| * @throws IOException {@inheritDoc} |
| * @throws SecurityException |
| * If a security manager has been installed and its {@link |
| * SecurityManager#checkListen checkListen} method denies the |
| * operation |
| * |
| * @since 1.7 |
| */ |
| public abstract DatagramChannel bind(SocketAddress local) |
| throws IOException; |
| |
| /** |
| * @throws UnsupportedOperationException {@inheritDoc} |
| * @throws IllegalArgumentException {@inheritDoc} |
| * @throws ClosedChannelException {@inheritDoc} |
| * @throws IOException {@inheritDoc} |
| * |
| * @since 1.7 |
| */ |
| public abstract <T> DatagramChannel setOption(SocketOption<T> name, T value) |
| throws IOException; |
| |
| /** |
| * Retrieves a datagram socket associated with this channel. |
| * |
| * <p> The returned object will not declare any public methods that are not |
| * declared in the {@link java.net.DatagramSocket} class. </p> |
| * |
| * @return A datagram socket associated with this channel |
| */ |
| public abstract DatagramSocket socket(); |
| |
| /** |
| * Tells whether or not this channel's socket is connected. |
| * |
| * @return {@code true} if, and only if, this channel's socket |
| * is {@link #isOpen open} and connected |
| */ |
| public abstract boolean isConnected(); |
| |
| /** |
| * Connects this channel's socket. |
| * |
| * <p> The channel's socket is configured so that it only receives |
| * datagrams from, and sends datagrams to, the given remote <i>peer</i> |
| * address. Once connected, datagrams may not be received from or sent to |
| * any other address. A datagram socket remains connected until it is |
| * explicitly disconnected or until it is closed. |
| * |
| * <p> This method performs exactly the same security checks as the {@link |
| * java.net.DatagramSocket#connect connect} method of the {@link |
| * java.net.DatagramSocket} class. That is, if a security manager has been |
| * installed then this method verifies that its {@link |
| * java.lang.SecurityManager#checkAccept checkAccept} and {@link |
| * java.lang.SecurityManager#checkConnect checkConnect} methods permit |
| * datagrams to be received from and sent to, respectively, the given |
| * remote address. |
| * |
| * <p> This method may be invoked at any time. It will not have any effect |
| * on read or write operations that are already in progress at the moment |
| * that it is invoked. If this channel's socket is not bound then this method |
| * will first cause the socket to be bound to an address that is assigned |
| * automatically, as if invoking the {@link #bind bind} method with a |
| * parameter of {@code null}. </p> |
| * |
| * @param remote |
| * The remote address to which this channel is to be connected |
| * |
| * @return This datagram channel |
| * |
| * @throws ClosedChannelException |
| * If this channel is closed |
| * |
| * @throws AsynchronousCloseException |
| * If another thread closes this channel |
| * while the connect operation is in progress |
| * |
| * @throws ClosedByInterruptException |
| * If another thread interrupts the current thread |
| * while the connect operation is in progress, thereby |
| * closing the channel and setting the current thread's |
| * interrupt status |
| * |
| * @throws SecurityException |
| * If a security manager has been installed |
| * and it does not permit access to the given remote address |
| * |
| * @throws IOException |
| * If some other I/O error occurs |
| */ |
| public abstract DatagramChannel connect(SocketAddress remote) |
| throws IOException; |
| |
| /** |
| * Disconnects this channel's socket. |
| * |
| * <p> The channel's socket is configured so that it can receive datagrams |
| * from, and sends datagrams to, any remote address so long as the security |
| * manager, if installed, permits it. |
| * |
| * <p> This method may be invoked at any time. It will not have any effect |
| * on read or write operations that are already in progress at the moment |
| * that it is invoked. |
| * |
| * <p> If this channel's socket is not connected, or if the channel is |
| * closed, then invoking this method has no effect. </p> |
| * |
| * @return This datagram channel |
| * |
| * @throws IOException |
| * If some other I/O error occurs |
| */ |
| public abstract DatagramChannel disconnect() throws IOException; |
| |
| /** |
| * Returns the remote address to which this channel's socket is connected. |
| * |
| * @return The remote address; {@code null} if the channel's socket is not |
| * connected |
| * |
| * @throws ClosedChannelException |
| * If the channel is closed |
| * @throws IOException |
| * If an I/O error occurs |
| * |
| * @since 1.7 |
| */ |
| public abstract SocketAddress getRemoteAddress() throws IOException; |
| |
| /** |
| * Receives a datagram via this channel. |
| * |
| * <p> If a datagram is immediately available, or if this channel is in |
| * blocking mode and one eventually becomes available, then the datagram is |
| * copied into the given byte buffer and its source address is returned. |
| * If this channel is in non-blocking mode and a datagram is not |
| * immediately available then this method immediately returns |
| * <tt>null</tt>. |
| * |
| * <p> The datagram is transferred into the given byte buffer starting at |
| * its current position, as if by a regular {@link |
| * ReadableByteChannel#read(java.nio.ByteBuffer) read} operation. If there |
| * are fewer bytes remaining in the buffer than are required to hold the |
| * datagram then the remainder of the datagram is silently discarded. |
| * |
| * <p> This method performs exactly the same security checks as the {@link |
| * java.net.DatagramSocket#receive receive} method of the {@link |
| * java.net.DatagramSocket} class. That is, if the socket is not connected |
| * to a specific remote address and a security manager has been installed |
| * then for each datagram received this method verifies that the source's |
| * address and port number are permitted by the security manager's {@link |
| * java.lang.SecurityManager#checkAccept checkAccept} method. The overhead |
| * of this security check can be avoided by first connecting the socket via |
| * the {@link #connect connect} method. |
| * |
| * <p> This method may be invoked at any time. If another thread has |
| * already initiated a read operation upon this channel, however, then an |
| * invocation of this method will block until the first operation is |
| * complete. If this channel's socket is not bound then this method will |
| * first cause the socket to be bound to an address that is assigned |
| * automatically, as if invoking the {@link #bind bind} method with a |
| * parameter of {@code null}. </p> |
| * |
| * @param dst |
| * The buffer into which the datagram is to be transferred |
| * |
| * @return The datagram's source address, |
| * or <tt>null</tt> if this channel is in non-blocking mode |
| * and no datagram was immediately available |
| * |
| * @throws ClosedChannelException |
| * If this channel is closed |
| * |
| * @throws AsynchronousCloseException |
| * If another thread closes this channel |
| * while the read operation is in progress |
| * |
| * @throws ClosedByInterruptException |
| * If another thread interrupts the current thread |
| * while the read operation is in progress, thereby |
| * closing the channel and setting the current thread's |
| * interrupt status |
| * |
| * @throws SecurityException |
| * If a security manager has been installed |
| * and it does not permit datagrams to be accepted |
| * from the datagram's sender |
| * |
| * @throws IOException |
| * If some other I/O error occurs |
| */ |
| public abstract SocketAddress receive(ByteBuffer dst) throws IOException; |
| |
| /** |
| * Sends a datagram via this channel. |
| * |
| * <p> If this channel is in non-blocking mode and there is sufficient room |
| * in the underlying output buffer, or if this channel is in blocking mode |
| * and sufficient room becomes available, then the remaining bytes in the |
| * given buffer are transmitted as a single datagram to the given target |
| * address. |
| * |
| * <p> The datagram is transferred from the byte buffer as if by a regular |
| * {@link WritableByteChannel#write(java.nio.ByteBuffer) write} operation. |
| * |
| * <p> This method performs exactly the same security checks as the {@link |
| * java.net.DatagramSocket#send send} method of the {@link |
| * java.net.DatagramSocket} class. That is, if the socket is not connected |
| * to a specific remote address and a security manager has been installed |
| * then for each datagram sent this method verifies that the target address |
| * and port number are permitted by the security manager's {@link |
| * java.lang.SecurityManager#checkConnect checkConnect} method. The |
| * overhead of this security check can be avoided by first connecting the |
| * socket via the {@link #connect connect} method. |
| * |
| * <p> This method may be invoked at any time. If another thread has |
| * already initiated a write operation upon this channel, however, then an |
| * invocation of this method will block until the first operation is |
| * complete. If this channel's socket is not bound then this method will |
| * first cause the socket to be bound to an address that is assigned |
| * automatically, as if by invoking the {@link #bind bind} method with a |
| * parameter of {@code null}. </p> |
| * |
| * @param src |
| * The buffer containing the datagram to be sent |
| * |
| * @param target |
| * The address to which the datagram is to be sent |
| * |
| * @return The number of bytes sent, which will be either the number |
| * of bytes that were remaining in the source buffer when this |
| * method was invoked or, if this channel is non-blocking, may be |
| * zero if there was insufficient room for the datagram in the |
| * underlying output buffer |
| * |
| * @throws ClosedChannelException |
| * If this channel is closed |
| * |
| * @throws AsynchronousCloseException |
| * If another thread closes this channel |
| * while the read operation is in progress |
| * |
| * @throws ClosedByInterruptException |
| * If another thread interrupts the current thread |
| * while the read operation is in progress, thereby |
| * closing the channel and setting the current thread's |
| * interrupt status |
| * |
| * @throws SecurityException |
| * If a security manager has been installed |
| * and it does not permit datagrams to be sent |
| * to the given address |
| * |
| * @throws IOException |
| * If some other I/O error occurs |
| */ |
| public abstract int send(ByteBuffer src, SocketAddress target) |
| throws IOException; |
| |
| |
| // -- ByteChannel operations -- |
| |
| /** |
| * Reads a datagram from this channel. |
| * |
| * <p> This method may only be invoked if this channel's socket is |
| * connected, and it only accepts datagrams from the socket's peer. If |
| * there are more bytes in the datagram than remain in the given buffer |
| * then the remainder of the datagram is silently discarded. Otherwise |
| * this method behaves exactly as specified in the {@link |
| * ReadableByteChannel} interface. </p> |
| * |
| * @throws NotYetConnectedException |
| * If this channel's socket is not connected |
| */ |
| public abstract int read(ByteBuffer dst) throws IOException; |
| |
| /** |
| * Reads a datagram from this channel. |
| * |
| * <p> This method may only be invoked if this channel's socket is |
| * connected, and it only accepts datagrams from the socket's peer. If |
| * there are more bytes in the datagram than remain in the given buffers |
| * then the remainder of the datagram is silently discarded. Otherwise |
| * this method behaves exactly as specified in the {@link |
| * ScatteringByteChannel} interface. </p> |
| * |
| * @throws NotYetConnectedException |
| * If this channel's socket is not connected |
| */ |
| public abstract long read(ByteBuffer[] dsts, int offset, int length) |
| throws IOException; |
| |
| /** |
| * Reads a datagram from this channel. |
| * |
| * <p> This method may only be invoked if this channel's socket is |
| * connected, and it only accepts datagrams from the socket's peer. If |
| * there are more bytes in the datagram than remain in the given buffers |
| * then the remainder of the datagram is silently discarded. Otherwise |
| * this method behaves exactly as specified in the {@link |
| * ScatteringByteChannel} interface. </p> |
| * |
| * @throws NotYetConnectedException |
| * If this channel's socket is not connected |
| */ |
| public final long read(ByteBuffer[] dsts) throws IOException { |
| return read(dsts, 0, dsts.length); |
| } |
| |
| /** |
| * Writes a datagram to this channel. |
| * |
| * <p> This method may only be invoked if this channel's socket is |
| * connected, in which case it sends datagrams directly to the socket's |
| * peer. Otherwise it behaves exactly as specified in the {@link |
| * WritableByteChannel} interface. </p> |
| * |
| * @throws NotYetConnectedException |
| * If this channel's socket is not connected |
| */ |
| public abstract int write(ByteBuffer src) throws IOException; |
| |
| /** |
| * Writes a datagram to this channel. |
| * |
| * <p> This method may only be invoked if this channel's socket is |
| * connected, in which case it sends datagrams directly to the socket's |
| * peer. Otherwise it behaves exactly as specified in the {@link |
| * GatheringByteChannel} interface. </p> |
| * |
| * @return The number of bytes sent, which will be either the number |
| * of bytes that were remaining in the source buffer when this |
| * method was invoked or, if this channel is non-blocking, may be |
| * zero if there was insufficient room for the datagram in the |
| * underlying output buffer |
| * |
| * @throws NotYetConnectedException |
| * If this channel's socket is not connected |
| */ |
| public abstract long write(ByteBuffer[] srcs, int offset, int length) |
| throws IOException; |
| |
| /** |
| * Writes a datagram to this channel. |
| * |
| * <p> This method may only be invoked if this channel's socket is |
| * connected, in which case it sends datagrams directly to the socket's |
| * peer. Otherwise it behaves exactly as specified in the {@link |
| * GatheringByteChannel} interface. </p> |
| * |
| * @return The number of bytes sent, which will be either the number |
| * of bytes that were remaining in the source buffer when this |
| * method was invoked or, if this channel is non-blocking, may be |
| * zero if there was insufficient room for the datagram in the |
| * underlying output buffer |
| * |
| * @throws NotYetConnectedException |
| * If this channel's socket is not connected |
| */ |
| public final long write(ByteBuffer[] srcs) throws IOException { |
| return write(srcs, 0, srcs.length); |
| } |
| |
| /** |
| * {@inheritDoc} |
| * <p> |
| * If there is a security manager set, its {@code checkConnect} method is |
| * called with the local address and {@code -1} as its arguments to see |
| * if the operation is allowed. If the operation is not allowed, |
| * a {@code SocketAddress} representing the |
| * {@link java.net.InetAddress#getLoopbackAddress loopback} address and the |
| * local port of the channel's socket is returned. |
| * |
| * @return The {@code SocketAddress} that the socket is bound to, or the |
| * {@code SocketAddress} representing the loopback address if |
| * denied by the security manager, or {@code null} if the |
| * channel's socket is not bound |
| * |
| * @throws ClosedChannelException {@inheritDoc} |
| * @throws IOException {@inheritDoc} |
| */ |
| @Override |
| public abstract SocketAddress getLocalAddress() throws IOException; |
| |
| } |
