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