1 /*

     2  * Copyright 2001-2005 Sun Microsystems, Inc.  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.  Sun designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

    22  * CA 95054 USA or visit www.sun.com if you need additional information or

    23  * have any 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 name="channels"></a>

    32  *

    33  * <blockquote><table cellspacing=1 cellpadding=0 summary="Lists channels and their descriptions">

    34  * <tr><th><p align="left">Channels</p></th><th><p align="left">Description</p></th></tr>

    35  * <tr><td valign=top><tt><i>{@link java.nio.channels.Channel}</i></tt></td>

    36  *     <td>A nexus for I/O operations</td></tr>

    37  * <tr><td valign=top><tt>&nbsp;&nbsp;<i>{@link java.nio.channels.ReadableByteChannel}</i></tt></td>

    38  *     <td>Can read into a buffer</td></tr>

    39  * <tr><td valign=top><tt>&nbsp;&nbsp;&nbsp;&nbsp;<i>{@link java.nio.channels.ScatteringByteChannel}&nbsp;&nbsp;</i></tt></td>

    40  *     <td>Can read into a sequence of&nbsp;buffers</td></tr>

    41  * <tr><td valign=top><tt>&nbsp;&nbsp;<i>{@link java.nio.channels.WritableByteChannel}</i></tt></td>

    42  *     <td>Can write from a buffer</td></tr>

    43  * <tr><td valign=top><tt>&nbsp;&nbsp;&nbsp;&nbsp;<i>{@link java.nio.channels.GatheringByteChannel}</i></tt></td>

    44  *     <td>Can write from a sequence of&nbsp;buffers</td></tr>

    45  * <tr><td valign=top><tt>&nbsp;&nbsp;<i>{@link java.nio.channels.ByteChannel}</i></tt></td>

    46  *     <td>Can read/write to/from a&nbsp;buffer</td></tr>

    47  * <tr><td valign=top><tt>&nbsp;&nbsp;&nbsp;&nbsp;<i>{@link java.nio.channels.SeekableByteChannel}</i></tt></td>

    48  *     <td>A {@code ByteChannel} connected to an entity that contains a variable-length sequence of bytes</td></tr>

    49  * <tr><td valign=top><tt>&nbsp;&nbsp;<i>{@link java.nio.channels.NetworkChannel}</i></tt></td>

    50  *     <td>A channel to a network socket</td></tr>

    51  * <tr><td valign=top><tt>&nbsp;&nbsp;&nbsp;&nbsp;<i>{@link java.nio.channels.MulticastChannel}</i></tt></td>

    52  *     <td>Can join Internet Protocol (IP) multicast groups</td></tr>

    53  * <tr><td valign=top><tt>{@link java.nio.channels.Channels}</tt></td>

    54  *     <td>Utility methods for channel/stream interoperation</td></tr>

    55  * </table></blockquote>

    56  *

    57  * <p> A <i>channel</i> represents an open connection to an entity such as a

    58  * hardware device, a file, a network socket, or a program component that is

    59  * capable of performing one or more distinct I/O operations, for example reading

    60  * or writing.  As specified in the {@link java.nio.channels.Channel} interface,

    61  * channels are either open or closed, and they are both <i>asynchronously

    62  * closeable</i> and <i>interruptible</i>.

    63  *

    64  * <p> The {@link java.nio.channels.Channel} interface is extended by several

    65  * other interfaces.

    66  *

    67  * <p> The {@link java.nio.channels.ReadableByteChannel} interface specifies a

    68  * {@link java.nio.channels.ReadableByteChannel#read read} method that reads bytes

    69  * from the channel into a buffer; similarly, the {@link

    70  * java.nio.channels.WritableByteChannel} interface specifies a {@link

    71  * java.nio.channels.WritableByteChannel#write write} method that writes bytes

    72  * from a buffer to the channel. The {@link java.nio.channels.ByteChannel}

    73  * interface unifies these two interfaces for the common case of channels that can

    74  * both read and write bytes. The {@link java.nio.channels.SeekableByteChannel}

    75  * interface extends the {@code ByteChannel} interface with methods to {@link

    76  * java.nio.channels.SeekableByteChannel#position() query} and {@link

    77  * java.nio.channels.SeekableByteChannel#position(long) modify} the channel's

    78  * current position, and its {@link java.nio.channels.SeekableByteChannel#size

    79  * size}.

    80  *

    81  * <p> The {@link java.nio.channels.ScatteringByteChannel} and {@link

    82  * java.nio.channels.GatheringByteChannel} interfaces extend the {@link

    83  * java.nio.channels.ReadableByteChannel} and {@link

    84  * java.nio.channels.WritableByteChannel} interfaces, respectively, adding {@link

    85  * java.nio.channels.ScatteringByteChannel#read read} and {@link

    86  * java.nio.channels.GatheringByteChannel#write write} methods that take a

    87  * sequence of buffers rather than a single buffer.

    88  *

    89  * <p> The {@link java.nio.channels.NetworkChannel} interface specifies methods

    90  * to {@link java.nio.channels.NetworkChannel#bind bind} the channel's socket,

    91  * obtain the address to which the socket is bound, and methods to {@link

    92  * java.nio.channels.NetworkChannel#getOption get} and {@link

    93  * java.nio.channels.NetworkChannel#setOption set} socket options. The {@link

    94  * java.nio.channels.MulticastChannel} interface specifies methods to join

    95  * Internet Protocol (IP) multicast groups.

    96  *

    97  * <p> The {@link java.nio.channels.Channels} utility class defines static methods

    98  * that support the interoperation of the stream classes of the <tt>{@link

    99  * java.io}</tt> package with the channel classes of this package.  An appropriate

   100  * channel can be constructed from an {@link java.io.InputStream} or an {@link

   101  * java.io.OutputStream}, and conversely an {@link java.io.InputStream} or an

   102  * {@link java.io.OutputStream} can be constructed from a channel.  A {@link

   103  * java.io.Reader} can be constructed that uses a given charset to decode bytes

   104  * from a given readable byte channel, and conversely a {@link java.io.Writer} can

   105  * be constructed that uses a given charset to encode characters into bytes and

   106  * write them to a given writable byte channel.

   107  *

   108  * <blockquote><table cellspacing=1 cellpadding=0 summary="Lists file channels and their descriptions">

   109  * <tr><th><p align="left">File channels</p></th><th><p align="left">Description</p></th></tr>

   110  * <tr><td valign=top><tt>{@link java.nio.channels.FileChannel}</tt></td>

   111  *     <td>Reads, writes, maps, and manipulates files</td></tr>

   112  * <tr><td valign=top><tt>{@link java.nio.channels.FileLock}</tt></td>

   113  *     <td>A lock on a (region of a) file</td></tr>

   114  * <tr><td valign=top><tt>{@link java.nio.MappedByteBuffer}/{@link java.nio.MappedBigByteBuffer}&nbsp;&nbsp;</tt></td>

   115  *     <td>A direct byte buffer or big byte buffer mapped to a region of a&nbsp;file</td></tr>

   116  * </table></blockquote>

   117  *

   118  * <p> The {@link java.nio.channels.FileChannel} class supports the usual

   119  * operations of reading bytes from, and writing bytes to, a channel connected to

   120  * a file, as well as those of querying and modifying the current file position

   121  * and truncating the file to a specific size.  It defines methods for acquiring

   122  * locks on the whole file or on a specific region of a file; these methods return

   123  * instances of the {@link java.nio.channels.FileLock} class.  Finally, it defines

   124  * methods for forcing updates to the file to be written to the storage device that

   125  * contains it, for efficiently transferring bytes between the file and other

   126  * channels, and for mapping a region of the file directly into memory.

   127  *

   128  * <p> A {@code FileChannel} is created by invoking one of its static {@link

   129  * java.nio.channels.FileChannel#open open} methods, or by invoking the {@code

   130  * getChannel} method of a {@link java.io.FileInputStream}, {@link

   131  * java.io.FileOutputStream}, or {@link java.io.RandomAccessFile} to return a

   132  * file channel connected to the same underlying file as the <tt>{@link java.io}</tt>

   133  * class.

   134  *

   135  * <a name="multiplex"></a>

   136  * <blockquote><table cellspacing=1 cellpadding=0 summary="Lists multiplexed, non-blocking channels and their descriptions">

   137  * <tr><th><p align="left">Multiplexed, non-blocking I/O</p></th><th><p align="left">Description</p></th></tr>

   138  * <tr><td valign=top><tt>{@link java.nio.channels.SelectableChannel}</tt></td>

   139  *     <td>A channel that can be multiplexed</td></tr>

   140  * <tr><td valign=top><tt>&nbsp;&nbsp;{@link java.nio.channels.DatagramChannel}</tt></td>

   141  *     <td>A channel to a datagram-oriented socket</td></tr>

   142  * <tr><td valign=top><tt>&nbsp;&nbsp;{@link java.nio.channels.Pipe.SinkChannel}</tt></td>

   143  *     <td>The write end of a pipe</td></tr>

   144  * <tr><td valign=top><tt>&nbsp;&nbsp;{@link java.nio.channels.Pipe.SourceChannel}</tt></td>

   145  *     <td>The read end of a pipe</td></tr>

   146  * <tr><td valign=top><tt>&nbsp;&nbsp;{@link java.nio.channels.ServerSocketChannel}&nbsp;&nbsp;</tt></td>

   147  *     <td>A channel to a stream-oriented listening socket</td></tr>

   148  * <tr><td valign=top><tt>&nbsp;&nbsp;{@link java.nio.channels.SocketChannel}</tt></td>

   149  *     <td>A channel for a stream-oriented connecting socket</td></tr>

   150  * <tr><td valign=top><tt>{@link java.nio.channels.Selector}</tt></td>

   151  *     <td>A multiplexor of selectable channels</td></tr>

   152  * <tr><td valign=top><tt>{@link java.nio.channels.SelectionKey}</tt></td>

   153  *     <td>A token representing the registration <br> of a channel

   154  *     with&nbsp;a&nbsp;selector</td></tr>

   155  * <tr><td valign=top><tt>{@link java.nio.channels.Pipe}</tt></td>

   156  *     <td>Two channels that form a unidirectional&nbsp;pipe</td></tr>

   157  * </table></blockquote>

   158  *

   159  * <p> Multiplexed, non-blocking I/O, which is much more scalable than

   160  * thread-oriented, blocking I/O, is provided by <i>selectors</i>, <i>selectable

   161  * channels</i>, and <i>selection keys</i>.

   162  *

   163  * <p> A <a href="Selector.html"><i>selector</i></a> is a multiplexor of <a

   164  * href="SelectableChannel.html"><i>selectable channels</i></a>, which in turn are

   165  * a special type of channel that can be put into <a

   166  * href="SelectableChannel.html#bm"><i>non-blocking mode</i></a>.  To perform

   167  * multiplexed I/O operations, one or more selectable channels are first created,

   168  * put into non-blocking mode, and {@link

   169  * java.nio.channels.SelectableChannel#register <i>registered</i>}

   170  * with a selector.  Registering a channel specifies the set of I/O operations

   171  * that will be tested for readiness by the selector, and returns a <a

   172  * href="SelectionKey.html"><i>selection key</i></a> that represents the

   173  * registration.

   174  *

   175  * <p> Once some channels have been registered with a selector, a <a

   176  * href="Selector.html#selop"><i>selection operation</i></a> can be performed in

   177  * order to discover which channels, if any, have become ready to perform one or

   178  * more of the operations in which interest was previously declared.  If a channel

   179  * is ready then the key returned when it was registered will be added to the

   180  * selector's <i>selected-key set</i>.  The key set, and the keys within it, can

   181  * be examined in order to determine the operations for which each channel is

   182  * ready.  From each key one can retrieve the corresponding channel in order to

   183  * perform whatever I/O operations are required.

   184  *

   185  * <p> That a selection key indicates that its channel is ready for some operation

   186  * is a hint, but not a guarantee, that such an operation can be performed by a

   187  * thread without causing the thread to block.  It is imperative that code that

   188  * performs multiplexed I/O be written so as to ignore these hints when they prove

   189  * to be incorrect.

   190  *

   191  * <p> This package defines selectable-channel classes corresponding to the {@link

   192  * java.net.DatagramSocket}, {@link java.net.ServerSocket}, and {@link

   193  * java.net.Socket} classes defined in the <tt>{@link java.net}</tt> package.

   194  * Minor changes to these classes have been made in order to support sockets that

   195  * are associated with channels.  This package also defines a simple class that

   196  * implements unidirectional pipes.  In all cases, a new selectable channel is

   197  * created by invoking the static <tt>open</tt> method of the corresponding class.

   198  * If a channel needs an associated socket then a socket will be created as a side

   199  * effect of this operation.

   200  *

   201  * <p> The implementation of selectors, selectable channels, and selection keys

   202  * can be replaced by "plugging in" an alternative definition or instance of the

   203  * {@link java.nio.channels.spi.SelectorProvider} class defined in the <tt>{@link

   204  * java.nio.channels.spi}</tt> package.  It is not expected that many developers

   205  * will actually make use of this facility; it is provided primarily so that

   206  * sophisticated users can take advantage of operating-system-specific

   207  * I/O-multiplexing mechanisms when very high performance is required.

   208  *

   209  * <p> Much of the bookkeeping and synchronization required to implement the

   210  * multiplexed-I/O abstractions is performed by the {@link

   211  * java.nio.channels.spi.AbstractInterruptibleChannel}, {@link

   212  * java.nio.channels.spi.AbstractSelectableChannel}, {@link

   213  * java.nio.channels.spi.AbstractSelectionKey}, and {@link

   214  * java.nio.channels.spi.AbstractSelector} classes in the <tt>{@link

   215  * java.nio.channels.spi}</tt> package.  When defining a custom selector provider,

   216  * only the {@link java.nio.channels.spi.AbstractSelector} and {@link

   217  * java.nio.channels.spi.AbstractSelectionKey} classes should be subclassed

   218  * directly; custom channel classes should extend the appropriate {@link

   219  * java.nio.channels.SelectableChannel} subclasses defined in this package.

   220  *

   221  * <hr width="80%">

   222  * <p> Unless otherwise noted, passing a <tt>null</tt> argument to a constructor

   223  * or method in any class or interface in this package will cause a {@link

   224  * java.lang.NullPointerException NullPointerException} to be thrown.

   225  *

   226  * @since 1.4

   227  * @author Mark Reinhold

   228  * @author JSR-51 Expert Group

   229  */

   230 

   231 package java.nio.channels;