JDK8/Java8源码在线阅读
/*
* 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
/**代码未完, 请加载全部代码(NowJava.com).**/
关注时代Java
关注时代Java