--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/jdk/src/share/classes/java/nio/package.html Sat Dec 01 00:00:00 2007 +0000
@@ -0,0 +1,139 @@
+<!--
+ Copyright 2000-2004 Sun Microsystems, Inc. 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. Sun designates this
+ particular file as subject to the "Classpath" exception as provided
+ by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
+ CA 95054 USA or visit www.sun.com if you need additional information or
+ have any questions.
+-->
+
+<!doctype html public "-//IETF//DTD HTML//EN">
+<html>
+<body bgcolor="white">
+
+Defines buffers, which are containers for data, and provides an overview of the
+other NIO packages.
+
+
+<p> The central abstractions of the NIO APIs are: </p>
+
+<ul>
+
+ <li><p> <a href="#buffers"><i>Buffers</i></a>, which are containers for data;
+ </p></li>
+
+ <li><p> <a href="charset/package-summary.html"><i>Charsets</i></a> and their
+ associated <i>decoders</i> and <i>encoders</i>, <br> which translate between
+ bytes and Unicode characters; </p></li>
+
+ <li><p> <a href="channels/package-summary.html"><i>Channels</i></a> of
+ various types, which represent connections <br> to entities capable of
+ performing I/O operations; and </p></li>
+
+ <li><p> <i>Selectors</i> and <i>selection keys</i>, which together with <br>
+ <i>selectable channels</i> define a <a
+ href="channels/package-summary.html#multiplex">multiplexed, non-blocking <br>
+ I/O</a> facility. </p></li>
+
+</ul>
+
+<p> The <tt>java.nio</tt> package defines the buffer classes, which are used
+throughout the NIO APIs. The charset API is defined in the {@link
+java.nio.charset} package, and the channel and selector APIs are defined in the
+{@link java.nio.channels} package. Each of these subpackages has its own
+service-provider (SPI) subpackage, the contents of which can be used to extend
+the platform's default implementations or to construct alternative
+implementations.
+
+
+<a name="buffers">
+
+<blockquote><table cellspacing=1 cellpadding=0 summary="Description of the various buffers">
+ <tr><th><p align="left">Buffers</p></th><th><p align="left">Description</p></th></tr>
+ <tr><td valign=top><tt>{@link java.nio.Buffer}</tt></td>
+ <td>Position, limit, and capacity;
+ <br>clear, flip, rewind, and mark/reset</td></tr>
+ <tr><td valign=top><tt> {@link java.nio.ByteBuffer}</tt></td>
+ <td>Get/put, compact, views; allocate, wrap</td></tr>
+ <tr><td valign=top><tt> {@link java.nio.MappedByteBuffer} </tt></td>
+ <td>A byte buffer mapped to a file</td></tr>
+ <tr><td valign=top><tt> {@link java.nio.CharBuffer}</tt></td>
+ <td>Get/put, compact; allocate, wrap</td></tr>
+ <tr><td valign=top><tt> {@link java.nio.DoubleBuffer}</tt></td>
+ <td> ' '</td></tr>
+ <tr><td valign=top><tt> {@link java.nio.FloatBuffer}</tt></td>
+ <td> ' '</td></tr>
+ <tr><td valign=top><tt> {@link java.nio.IntBuffer}</tt></td>
+ <td> ' '</td></tr>
+ <tr><td valign=top><tt> {@link java.nio.LongBuffer}</tt></td>
+ <td> ' '</td></tr>
+ <tr><td valign=top><tt> {@link java.nio.ShortBuffer}</tt></td>
+ <td> ' '</td></tr>
+ <tr><td valign=top><tt>{@link java.nio.ByteOrder}</tt></td>
+ <td>Typesafe enumeration for byte orders</td></tr>
+</table></blockquote>
+
+<p> A <i>buffer</i> is a container for a fixed amount of data of a specific
+primitive type. In addition to its content a buffer has a <i>position</i>,
+which is the index of the next element to be read or written, and a
+<i>limit</i>, which is the index of the first element that should not be read
+or written. The base {@link java.nio.Buffer} class defines these properties as
+well as methods for <i>clearing</i>, <i>flipping</i>, and <i>rewinding</i>, for
+<i>marking</i> the current position, and for <i>resetting</i> the position to
+the previous mark.
+
+<p> There is a buffer class for each non-boolean primitive type. Each class
+defines a family of <i>get</i> and <i>put</i> methods for moving data out of
+and in to a buffer, methods for <i>compacting</i>, <i>duplicating</i>, and
+<i>slicing</i> a buffer, and static methods for <i>allocating</i> a new buffer
+as well as for <i>wrapping</i> an existing array into a buffer.
+
+<p> Byte buffers are distinguished in that they can be used as the sources and
+targets of I/O operations. They also support several features not found in the
+other buffer classes:
+
+<ul>
+
+ <li><p> A byte buffer can be allocated as a <a href="ByteBuffer.html#direct">
+ <i>direct</i></a> buffer, in which case the Java virtual machine will make a
+ best effort to perform native I/O operations directly upon it. </p></li>
+
+ <li><p> A byte buffer can be created by {@link
+ java.nio.channels.FileChannel#map </code><i>mapping</i><code>} a region of a
+ file directly into memory, in which case a few additional file-related
+ operations defined in the {@link java.nio.MappedByteBuffer} class are
+ available. </p></li>
+
+ <li><p> A byte buffer provides access to its content as either a heterogeneous
+ or homogeneous sequence of <a href="ByteBuffer.html#bin">binary data</i></a>
+ of any non-boolean primitive type, in either big-endian or little-endian <a
+ href="ByteOrder.html">byte order</a>. </p></li>
+
+</ul>
+
+<p> Unless otherwise noted, passing a <tt>null</tt> argument to a constructor
+or method in any class or interface in this package will cause a {@link
+java.lang.NullPointerException NullPointerException} to be thrown.
+
+@since 1.4
+@author Mark Reinhold
+@author JSR-51 Expert Group
+
+</body>
+</html>