1 /*
   2  * Copyright (c) 2001, 2017, 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 /**
  27  * Defines channels, which represent connections to entities that are capable of
  28  * performing I/O operations, such as files and sockets; defines selectors, for
  29  * multiplexed, non-blocking I/O operations.
  30  *
  31  * <a id="channels"></a>
  32  *
  33  * <blockquote><table class="borderless">
  34  *     <caption style="display:none">Lists channels and their descriptions</caption>
  35  * <tr><th style="text-align:left">Channels</th>
  36  *     <th style="text-align:left">Description</th></tr>
  37  * <tr><td style="vertical-align:top"><i>{@link java.nio.channels.Channel}</i></td>
  38  *     <td>A nexus for I/O operations</td></tr>
  39  * <tr><td style="vertical-align:top">
  40  *     &nbsp;&nbsp;<i>{@link java.nio.channels.ReadableByteChannel}</i></td>
  41  *     <td>Can read into a buffer</td></tr>
  42  * <tr><td style="vertical-align:top">
  43  *     &nbsp;&nbsp;&nbsp;&nbsp;<i>{@link java.nio.channels.ScatteringByteChannel}&nbsp;&nbsp;</i></td>
  44  *     <td>Can read into a sequence of&nbsp;buffers</td></tr>
  45  * <tr><td style="vertical-align:top">
  46  *     &nbsp;&nbsp;<i>{@link java.nio.channels.WritableByteChannel}</i></td>
  47  *     <td>Can write from a buffer</td></tr>
  48  * <tr><td style="vertical-align:top">
  49  *     &nbsp;&nbsp;&nbsp;&nbsp;<i>{@link java.nio.channels.GatheringByteChannel}</i></td>
  50  *     <td>Can write from a sequence of&nbsp;buffers</td></tr>
  51  * <tr><td style="vertical-align:top">
  52  *     &nbsp;&nbsp;<i>{@link java.nio.channels.ByteChannel}</i></td>
  53  *     <td>Can read/write to/from a&nbsp;buffer</td></tr>
  54  * <tr><td style="vertical-align:top">
  55  *     &nbsp;&nbsp;&nbsp;&nbsp;<i>{@link java.nio.channels.SeekableByteChannel}</i></td>
  56  *     <td>A {@code ByteChannel} connected to an entity that contains a variable-length
  57  *         sequence of bytes</td></tr>
  58  * <tr><td style="vertical-align:top">
  59  *     &nbsp;&nbsp;<i>{@link java.nio.channels.AsynchronousChannel}</i></td>
  60  *     <td>Supports asynchronous I/O operations.</td></tr>
  61  * <tr><td style="vertical-align:top">
  62  *     &nbsp;&nbsp;&nbsp;&nbsp;<i>{@link java.nio.channels.AsynchronousByteChannel}</i></td>
  63  *     <td>Can read and write bytes asynchronously</td></tr>
  64  * <tr><td style="vertical-align:top">
  65  *     &nbsp;&nbsp;<i>{@link java.nio.channels.NetworkChannel}</i></td>
  66  *     <td>A channel to a network socket</td></tr>
  67  * <tr><td style="vertical-align:top">
  68  *     &nbsp;&nbsp;&nbsp;&nbsp;<i>{@link java.nio.channels.MulticastChannel}</i></td>
  69  *     <td>Can join Internet Protocol (IP) multicast groups</td></tr>
  70  * <tr><td style="vertical-align:top">{@link java.nio.channels.Channels}</td>
  71  *     <td>Utility methods for channel/stream interoperation</td></tr>
  72  * </table></blockquote>
  73  *
  74  * <p> A <i>channel</i> represents an open connection to an entity such as a
  75  * hardware device, a file, a network socket, or a program component that is
  76  * capable of performing one or more distinct I/O operations, for example reading
  77  * or writing.  As specified in the {@link java.nio.channels.Channel} interface,
  78  * channels are either open or closed, and they are both <i>asynchronously
  79  * closeable</i> and <i>interruptible</i>.
  80  *
  81  * <p> The {@link java.nio.channels.Channel} interface is extended by several
  82  * other interfaces.
  83  *
  84  * <p> The {@link java.nio.channels.ReadableByteChannel} interface specifies a
  85  * {@link java.nio.channels.ReadableByteChannel#read read} method that reads bytes
  86  * from the channel into a buffer; similarly, the {@link
  87  * java.nio.channels.WritableByteChannel} interface specifies a {@link
  88  * java.nio.channels.WritableByteChannel#write write} method that writes bytes
  89  * from a buffer to the channel. The {@link java.nio.channels.ByteChannel}
  90  * interface unifies these two interfaces for the common case of channels that can
  91  * both read and write bytes. The {@link java.nio.channels.SeekableByteChannel}
  92  * interface extends the {@code ByteChannel} interface with methods to {@link
  93  * java.nio.channels.SeekableByteChannel#position() query} and {@link
  94  * java.nio.channels.SeekableByteChannel#position(long) modify} the channel's
  95  * current position, and its {@link java.nio.channels.SeekableByteChannel#size
  96  * size}.
  97  *
  98  * <p> The {@link java.nio.channels.ScatteringByteChannel} and {@link
  99  * java.nio.channels.GatheringByteChannel} interfaces extend the {@link
 100  * java.nio.channels.ReadableByteChannel} and {@link
 101  * java.nio.channels.WritableByteChannel} interfaces, respectively, adding {@link
 102  * java.nio.channels.ScatteringByteChannel#read read} and {@link
 103  * java.nio.channels.GatheringByteChannel#write write} methods that take a
 104  * sequence of buffers rather than a single buffer.
 105  *
 106  * <p> The {@link java.nio.channels.NetworkChannel} interface specifies methods
 107  * to {@link java.nio.channels.NetworkChannel#bind bind} the channel's socket,
 108  * obtain the address to which the socket is bound, and methods to {@link
 109  * java.nio.channels.NetworkChannel#getOption get} and {@link
 110  * java.nio.channels.NetworkChannel#setOption set} socket options. The {@link
 111  * java.nio.channels.MulticastChannel} interface specifies methods to join
 112  * Internet Protocol (IP) multicast groups.
 113  *
 114  * <p> The {@link java.nio.channels.Channels} utility class defines static methods
 115  * that support the interoperation of the stream classes of the {@link
 116  * java.io} package with the channel classes of this package.  An appropriate
 117  * channel can be constructed from an {@link java.io.InputStream} or an {@link
 118  * java.io.OutputStream}, and conversely an {@link java.io.InputStream} or an
 119  * {@link java.io.OutputStream} can be constructed from a channel.  A {@link
 120  * java.io.Reader} can be constructed that uses a given charset to decode bytes
 121  * from a given readable byte channel, and conversely a {@link java.io.Writer} can
 122  * be constructed that uses a given charset to encode characters into bytes and
 123  * write them to a given writable byte channel.
 124  *
 125  * <blockquote><table class="borderless">
 126  *     <caption style="display:none">
 127  *         Lists file channels and their descriptions</caption>
 128  * <tr><th style="text-align:left">File channels</th>
 129  *     <th style="text-align:left">Description</th></tr>
 130  * <tr><td style="vertical-align:top">
 131  *     {@link java.nio.channels.FileChannel}</td>
 132  *     <td>Reads, writes, maps, and manipulates files</td></tr>
 133  * <tr><td style="vertical-align:top">
 134  *     {@link java.nio.channels.FileLock}</td>
 135  *     <td>A lock on a (region of a) file</td></tr>
 136  * <tr><td style="vertical-align:top">
 137  *     {@link java.nio.MappedByteBuffer}&nbsp;&nbsp;</td>
 138  *     <td>A direct byte buffer mapped to a region of a&nbsp;file</td></tr>
 139  * </table></blockquote>
 140  *
 141  * <p> The {@link java.nio.channels.FileChannel} class supports the usual
 142  * operations of reading bytes from, and writing bytes to, a channel connected to
 143  * a file, as well as those of querying and modifying the current file position
 144  * and truncating the file to a specific size.  It defines methods for acquiring
 145  * locks on the whole file or on a specific region of a file; these methods return
 146  * instances of the {@link java.nio.channels.FileLock} class.  Finally, it defines
 147  * methods for forcing updates to the file to be written to the storage device that
 148  * contains it, for efficiently transferring bytes between the file and other
 149  * channels, and for mapping a region of the file directly into memory.
 150  *
 151  * <p> A {@code FileChannel} is created by invoking one of its static {@link
 152  * java.nio.channels.FileChannel#open open} methods, or by invoking the {@code
 153  * getChannel} method of a {@link java.io.FileInputStream}, {@link
 154  * java.io.FileOutputStream}, or {@link java.io.RandomAccessFile} to return a
 155  * file channel connected to the same underlying file as the {@link java.io}
 156  * class.
 157  *
 158  * <a id="multiplex"></a>
 159  * <blockquote><table class="borderless">
 160  *     <caption style="display:none">
 161  *         Lists multiplexed, non-blocking channels and their descriptions</caption>
 162  * <tr><th style="text-align:left">Multiplexed, non-blocking I/O</th>
 163  *     <th style="text-align:left">Description</th></tr>
 164  * <tr><td style="vertical-align:top">{@link java.nio.channels.SelectableChannel}</td>
 165  *     <td>A channel that can be multiplexed</td></tr>
 166  * <tr><td style="vertical-align:top">
 167  *     &nbsp;&nbsp;{@link java.nio.channels.DatagramChannel}</td>
 168  *     <td>A channel to a datagram-oriented socket</td></tr>
 169  * <tr><td style="vertical-align:top">
 170  *     &nbsp;&nbsp;{@link java.nio.channels.Pipe.SinkChannel}</td>
 171  *     <td>The write end of a pipe</td></tr>
 172  * <tr><td style="vertical-align:top">
 173  *     &nbsp;&nbsp;{@link java.nio.channels.Pipe.SourceChannel}</td>
 174  *     <td>The read end of a pipe</td></tr>
 175  * <tr><td style="vertical-align:top">
 176  *     &nbsp;&nbsp;{@link java.nio.channels.ServerSocketChannel}&nbsp;&nbsp;</td>
 177  *     <td>A channel to a stream-oriented listening socket</td></tr>
 178  * <tr><td style="vertical-align:top">
 179  *     &nbsp;&nbsp;{@link java.nio.channels.SocketChannel}</td>
 180  *     <td>A channel for a stream-oriented connecting socket</td></tr>
 181  * <tr><td style="vertical-align:top">{@link java.nio.channels.Selector}</td>
 182  *     <td>A multiplexor of selectable channels</td></tr>
 183  * <tr><td style="vertical-align:top">{@link java.nio.channels.SelectionKey}</td>
 184  *     <td>A token representing the registration <br> of a channel
 185  *     with&nbsp;a&nbsp;selector</td></tr>
 186  * <tr><td style="vertical-align:top">{@link java.nio.channels.Pipe}</td>
 187  *     <td>Two channels that form a unidirectional&nbsp;pipe</td></tr>
 188  * </table></blockquote>
 189  *
 190  * <p> Multiplexed, non-blocking I/O, which is much more scalable than
 191  * thread-oriented, blocking I/O, is provided by <i>selectors</i>, <i>selectable
 192  * channels</i>, and <i>selection keys</i>.
 193  *
 194  * <p> A <a href="Selector.html"><i>selector</i></a> is a multiplexor of <a
 195  * href="SelectableChannel.html"><i>selectable channels</i></a>, which in turn are
 196  * a special type of channel that can be put into <a
 197  * href="SelectableChannel.html#bm"><i>non-blocking mode</i></a>.  To perform
 198  * multiplexed I/O operations, one or more selectable channels are first created,
 199  * put into non-blocking mode, and {@link
 200  * java.nio.channels.SelectableChannel#register <i>registered</i>}
 201  * with a selector.  Registering a channel specifies the set of I/O operations
 202  * that will be tested for readiness by the selector, and returns a <a
 203  * href="SelectionKey.html"><i>selection key</i></a> that represents the
 204  * registration.
 205  *
 206  * <p> Once some channels have been registered with a selector, a <a
 207  * href="Selector.html#selop"><i>selection operation</i></a> can be performed in
 208  * order to discover which channels, if any, have become ready to perform one or
 209  * more of the operations in which interest was previously declared.  If a channel
 210  * is ready then the key returned when it was registered will be added to the
 211  * selector's <i>selected-key set</i>.  The key set, and the keys within it, can
 212  * be examined in order to determine the operations for which each channel is
 213  * ready.  From each key one can retrieve the corresponding channel in order to
 214  * perform whatever I/O operations are required.
 215  *
 216  * <p> That a selection key indicates that its channel is ready for some operation
 217  * is a hint, but not a guarantee, that such an operation can be performed by a
 218  * thread without causing the thread to block.  It is imperative that code that
 219  * performs multiplexed I/O be written so as to ignore these hints when they prove
 220  * to be incorrect.
 221  *
 222  * <p> This package defines selectable-channel classes corresponding to the {@link
 223  * java.net.DatagramSocket}, {@link java.net.ServerSocket}, and {@link
 224  * java.net.Socket} classes defined in the {@link java.net} package.
 225  * Minor changes to these classes have been made in order to support sockets that
 226  * are associated with channels.  This package also defines a simple class that
 227  * implements unidirectional pipes.  In all cases, a new selectable channel is
 228  * created by invoking the static {@code open} method of the corresponding class.
 229  * If a channel needs an associated socket then a socket will be created as a side
 230  * effect of this operation.
 231  *
 232  * <p> The implementation of selectors, selectable channels, and selection keys
 233  * can be replaced by "plugging in" an alternative definition or instance of the
 234  * {@link java.nio.channels.spi.SelectorProvider} class defined in the {@link
 235  * java.nio.channels.spi} package.  It is not expected that many developers
 236  * will actually make use of this facility; it is provided primarily so that
 237  * sophisticated users can take advantage of operating-system-specific
 238  * I/O-multiplexing mechanisms when very high performance is required.
 239  *
 240  * <p> Much of the bookkeeping and synchronization required to implement the
 241  * multiplexed-I/O abstractions is performed by the {@link
 242  * java.nio.channels.spi.AbstractInterruptibleChannel}, {@link
 243  * java.nio.channels.spi.AbstractSelectableChannel}, {@link
 244  * java.nio.channels.spi.AbstractSelectionKey}, and {@link
 245  * java.nio.channels.spi.AbstractSelector} classes in the {@link
 246  * java.nio.channels.spi} package.  When defining a custom selector provider,
 247  * only the {@link java.nio.channels.spi.AbstractSelector} and {@link
 248  * java.nio.channels.spi.AbstractSelectionKey} classes should be subclassed
 249  * directly; custom channel classes should extend the appropriate {@link
 250  * java.nio.channels.SelectableChannel} subclasses defined in this package.
 251  *
 252  * <a id="async"></a>
 253  *
 254  * <blockquote><table class="borderless">
 255  *     <caption style="display:none">
 256  *         Lists asynchronous channels and their descriptions</caption>
 257  * <tr><th style="text-align:left">
 258  *     Asynchronous I/O</th><th style="text-align:left">Description</th></tr>
 259  * <tr><td style="vertical-align:top">
 260  *     {@link java.nio.channels.AsynchronousFileChannel}</td>
 261  *     <td>An asynchronous channel for reading, writing, and manipulating a file</td></tr>
 262  * <tr><td style="vertical-align:top">
 263  *     {@link java.nio.channels.AsynchronousSocketChannel}</td>
 264  *     <td>An asynchronous channel to a stream-oriented connecting socket</td></tr>
 265  * <tr><td style="vertical-align:top">
 266  *     {@link java.nio.channels.AsynchronousServerSocketChannel}&nbsp;&nbsp;</td>
 267  *     <td>An asynchronous channel to a stream-oriented listening socket</td></tr>
 268  * <tr><td style="vertical-align:top">
 269  *     {@link java.nio.channels.CompletionHandler}</td>
 270  *     <td>A handler for consuming the result of an asynchronous operation</td></tr>
 271  * <tr><td style="vertical-align:top">
 272  *     {@link java.nio.channels.AsynchronousChannelGroup}</td>
 273  *     <td>A grouping of asynchronous channels for the purpose of resource sharing</td></tr>
 274  * </table></blockquote>
 275  *
 276  * <p> {@link java.nio.channels.AsynchronousChannel Asynchronous channels} are a
 277  * special type of channel capable of asynchronous I/O operations. Asynchronous
 278  * channels are non-blocking and define methods to initiate asynchronous
 279  * operations, returning a {@link java.util.concurrent.Future} representing the
 280  * pending result of each operation. The {@code Future} can be used to poll or
 281  * wait for the result of the operation. Asynchronous I/O operations can also
 282  * specify a {@link java.nio.channels.CompletionHandler} to invoke when the
 283  * operation completes. A completion handler is user provided code that is executed
 284  * to consume the result of I/O operation.
 285  *
 286  * <p> This package defines asynchronous-channel classes that are connected to
 287  * a stream-oriented connecting or listening socket, or a datagram-oriented socket.
 288  * It also defines the {@link java.nio.channels.AsynchronousFileChannel} class
 289  * for asynchronous reading, writing, and manipulating a file. As with the {@link
 290  * java.nio.channels.FileChannel} it supports operations to truncate the file
 291  * to a specific size, force updates to the file to be written to the storage
 292  * device, or acquire locks on the whole file or on a specific region of the file.
 293  * Unlike the {@code FileChannel} it does not define methods for mapping a
 294  * region of the file directly into memory. Where memory mapped I/O is required,
 295  * then a {@code FileChannel} can be used.
 296  *
 297  * <p> Asynchronous channels are bound to an asynchronous channel group for the
 298  * purpose of resource sharing. A group has an associated {@link
 299  * java.util.concurrent.ExecutorService} to which tasks are submitted to handle
 300  * I/O events and dispatch to completion handlers that consume the result of
 301  * asynchronous operations performed on channels in the group. The group can
 302  * optionally be specified when creating the channel or the channel can be bound
 303  * to a <em>default group</em>. Sophisticated users may wish to create their
 304  * own asynchronous channel groups or configure the {@code ExecutorService}
 305  * that will be used for the default group.
 306  *
 307  * <p> As with selectors, the implementation of asynchronous channels can be
 308  * replaced by "plugging in" an alternative definition or instance of the {@link
 309  * java.nio.channels.spi.AsynchronousChannelProvider} class defined in the
 310  * {@link java.nio.channels.spi} package.  It is not expected that many
 311  * developers will actually make use of this facility; it is provided primarily
 312  * so that sophisticated users can take advantage of operating-system-specific
 313  * asynchronous I/O mechanisms when very high performance is required.
 314  *
 315  * <p> Unless otherwise noted, passing a {@code null} argument to a constructor
 316  * or method in any class or interface in this package will cause a {@link
 317  * java.lang.NullPointerException NullPointerException} to be thrown.
 318  *
 319  * @since 1.4
 320  * @author Mark Reinhold
 321  * @author JSR-51 Expert Group
 322  */
 323 
 324 package java.nio.channels;