Back to index...

	/*
	* Copyright (c) 2000, 2018, 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 class="striped">
	* <caption style="display:none">Socket options</caption>
	* <thead>
	* <tr>
	* <th scope="col">Option Name</th>
	* <th scope="col">Description</th>
	* </tr>
	* </thead>
	* <tbody>
	* <tr>
	* <th scope="row"> {@link java.net.StandardSocketOptions#SO_SNDBUF SO_SNDBUF} </th>
	* <td> The size of the socket send buffer </td>
	* </tr>
	* <tr>
	* <th scope="row"> {@link java.net.StandardSocketOptions#SO_RCVBUF SO_RCVBUF} </th>
	* <td> The size of the socket receive buffer </td>
	* </tr>
	* <tr>
	* <th scope="row"> {@link java.net.StandardSocketOptions#SO_REUSEADDR SO_REUSEADDR} </th>
	* <td> Re-use address </td>
	* </tr>
	* <tr>
	* <th scope="row"> {@link java.net.StandardSocketOptions#SO_BROADCAST SO_BROADCAST} </th>
	* <td> Allow transmission of broadcast datagrams </td>
	* </tr>
	* <tr>
	* <th scope="row"> {@link java.net.StandardSocketOptions#IP_TOS IP_TOS} </th>
	* <td> The Type of Service (ToS) octet in the Internet Protocol (IP) header </td>
	* </tr>
	* <tr>
	* <th scope="row"> {@link java.net.StandardSocketOptions#IP_MULTICAST_IF IP_MULTICAST_IF} </th>
	* <td> The network interface for Internet Protocol (IP) multicast datagrams </td>
	* </tr>
	* <tr>
	* <th scope="row"> {@link java.net.StandardSocketOptions#IP_MULTICAST_TTL
	* IP_MULTICAST_TTL} </th>
	* <td> The <em>time-to-live</em> for Internet Protocol (IP) multicast
	* datagrams </td>
	* </tr>
	* <tr>
	* <th scope="row"> {@link java.net.StandardSocketOptions#IP_MULTICAST_LOOP
	* IP_MULTICAST_LOOP} </th>
	* <td> Loopback for Internet Protocol (IP) multicast datagrams </td>
	* </tr>
	* </tbody>
	* </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 {@code (}{@link SelectionKey#OP_READ} {@code \|} {@link
	* SelectionKey#OP_WRITE}{@code )}.
	*
	* @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 AlreadyConnectedException
	* If this channel is already connected
	*
	* @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 UnresolvedAddressException
	* If the given remote address is not fully resolved
	*
	* @throws UnsupportedAddressTypeException
	* If the type of the given remote address is not supported
	*
	* @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
	* {@code null}.
	*
	* <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 {@code null} 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 AlreadyConnectedException
	* If this channel is connected to a different address
	* from that specified by {@code target}
	*
	* @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 UnresolvedAddressException
	* If the given remote address is not fully resolved
	*
	* @throws UnsupportedAddressTypeException
	* If the type of the given remote address is not supported
	*
	* @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;

	}

Back to index...