Showing the changes to java/pkg/java/nio/package.html (1 of 18352 files). Show all
Unified · Split
| @@ -0,0 +1,139 @@ | ||
| 1 | +<!-- | |
| 2 | + Copyright (c) 2000, 2004, 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 | +<!doctype html public "-//IETF//DTD HTML//EN"> | |
| 27 | +<html> | |
| 28 | +<body bgcolor="white"> | |
| 29 | + | |
| 30 | +Defines buffers, which are containers for data, and provides an overview of the | |
| 31 | +other NIO packages. | |
| 32 | + | |
| 33 | + | |
| 34 | +<p> The central abstractions of the NIO APIs are: </p> | |
| 35 | + | |
| 36 | +<ul> | |
| 37 | + | |
| 38 | + <li><p> <a href="#buffers"><i>Buffers</i></a>, which are containers for data; | |
| 39 | + </p></li> | |
| 40 | + | |
| 41 | + <li><p> <a href="charset/package-summary.html"><i>Charsets</i></a> and their | |
| 42 | + associated <i>decoders</i> and <i>encoders</i>, <br> which translate between | |
| 43 | + bytes and Unicode characters; </p></li> | |
| 44 | + | |
| 45 | + <li><p> <a href="channels/package-summary.html"><i>Channels</i></a> of | |
| 46 | + various types, which represent connections <br> to entities capable of | |
| 47 | + performing I/O operations; and </p></li> | |
| 48 | + | |
| 49 | + <li><p> <i>Selectors</i> and <i>selection keys</i>, which together with <br> | |
| 50 | + <i>selectable channels</i> define a <a | |
| 51 | + href="channels/package-summary.html#multiplex">multiplexed, non-blocking <br> | |
| 52 | + I/O</a> facility. </p></li> | |
| 53 | + | |
| 54 | +</ul> | |
| 55 | + | |
| 56 | +<p> The <tt>java.nio</tt> package defines the buffer classes, which are used | |
| 57 | +throughout the NIO APIs. The charset API is defined in the {@link | |
| 58 | +java.nio.charset} package, and the channel and selector APIs are defined in the | |
| 59 | +{@link java.nio.channels} package. Each of these subpackages has its own | |
| 60 | +service-provider (SPI) subpackage, the contents of which can be used to extend | |
| 61 | +the platform's default implementations or to construct alternative | |
| 62 | +implementations. | |
| 63 | + | |
| 64 | + | |
| 65 | +<a name="buffers"> | |
| 66 | + | |
| 67 | +<blockquote><table cellspacing=1 cellpadding=0 summary="Description of the various buffers"> | |
| 68 | + <tr><th><p align="left">Buffers</p></th><th><p align="left">Description</p></th></tr> | |
| 69 | + <tr><td valign=top><tt>{@link java.nio.Buffer}</tt></td> | |
| 70 | + <td>Position, limit, and capacity; | |
| 71 | + <br>clear, flip, rewind, and mark/reset</td></tr> | |
| 72 | + <tr><td valign=top><tt> {@link java.nio.ByteBuffer}</tt></td> | |
| 73 | + <td>Get/put, compact, views; allocate, wrap</td></tr> | |
| 74 | + <tr><td valign=top><tt> {@link java.nio.MappedByteBuffer} </tt></td> | |
| 75 | + <td>A byte buffer mapped to a file</td></tr> | |
| 76 | + <tr><td valign=top><tt> {@link java.nio.CharBuffer}</tt></td> | |
| 77 | + <td>Get/put, compact; allocate, wrap</td></tr> | |
| 78 | + <tr><td valign=top><tt> {@link java.nio.DoubleBuffer}</tt></td> | |
| 79 | + <td> ' '</td></tr> | |
| 80 | + <tr><td valign=top><tt> {@link java.nio.FloatBuffer}</tt></td> | |
| 81 | + <td> ' '</td></tr> | |
| 82 | + <tr><td valign=top><tt> {@link java.nio.IntBuffer}</tt></td> | |
| 83 | + <td> ' '</td></tr> | |
| 84 | + <tr><td valign=top><tt> {@link java.nio.LongBuffer}</tt></td> | |
| 85 | + <td> ' '</td></tr> | |
| 86 | + <tr><td valign=top><tt> {@link java.nio.ShortBuffer}</tt></td> | |
| 87 | + <td> ' '</td></tr> | |
| 88 | + <tr><td valign=top><tt>{@link java.nio.ByteOrder}</tt></td> | |
| 89 | + <td>Typesafe enumeration for byte orders</td></tr> | |
| 90 | +</table></blockquote> | |
| 91 | + | |
| 92 | +<p> A <i>buffer</i> is a container for a fixed amount of data of a specific | |
| 93 | +primitive type. In addition to its content a buffer has a <i>position</i>, | |
| 94 | +which is the index of the next element to be read or written, and a | |
| 95 | +<i>limit</i>, which is the index of the first element that should not be read | |
| 96 | +or written. The base {@link java.nio.Buffer} class defines these properties as | |
| 97 | +well as methods for <i>clearing</i>, <i>flipping</i>, and <i>rewinding</i>, for | |
| 98 | +<i>marking</i> the current position, and for <i>resetting</i> the position to | |
| 99 | +the previous mark. | |
| 100 | + | |
| 101 | +<p> There is a buffer class for each non-boolean primitive type. Each class | |
| 102 | +defines a family of <i>get</i> and <i>put</i> methods for moving data out of | |
| 103 | +and in to a buffer, methods for <i>compacting</i>, <i>duplicating</i>, and | |
| 104 | +<i>slicing</i> a buffer, and static methods for <i>allocating</i> a new buffer | |
| 105 | +as well as for <i>wrapping</i> an existing array into a buffer. | |
| 106 | + | |
| 107 | +<p> Byte buffers are distinguished in that they can be used as the sources and | |
| 108 | +targets of I/O operations. They also support several features not found in the | |
| 109 | +other buffer classes: | |
| 110 | + | |
| 111 | +<ul> | |
| 112 | + | |
| 113 | + <li><p> A byte buffer can be allocated as a <a href="ByteBuffer.html#direct"> | |
| 114 | + <i>direct</i></a> buffer, in which case the Java virtual machine will make a | |
| 115 | + best effort to perform native I/O operations directly upon it. </p></li> | |
| 116 | + | |
| 117 | + <li><p> A byte buffer can be created by {@link | |
| 118 | + java.nio.channels.FileChannel#map </code><i>mapping</i><code>} a region of a | |
| 119 | + file directly into memory, in which case a few additional file-related | |
| 120 | + operations defined in the {@link java.nio.MappedByteBuffer} class are | |
| 121 | + available. </p></li> | |
| 122 | + | |
| 123 | + <li><p> A byte buffer provides access to its content as either a heterogeneous | |
| 124 | + or homogeneous sequence of <a href="ByteBuffer.html#bin">binary data</i></a> | |
| 125 | + of any non-boolean primitive type, in either big-endian or little-endian <a | |
| 126 | + href="ByteOrder.html">byte order</a>. </p></li> | |
| 127 | + | |
| 128 | +</ul> | |
| 129 | + | |
| 130 | +<p> Unless otherwise noted, passing a <tt>null</tt> argument to a constructor | |
| 131 | +or method in any class or interface in this package will cause a {@link | |
| 132 | +java.lang.NullPointerException NullPointerException} to be thrown. | |
| 133 | + | |
| 134 | +@since 1.4 | |
| 135 | +@author Mark Reinhold | |
| 136 | +@author JSR-51 Expert Group | |
| 137 | + | |
| 138 | +</body> | |
| 139 | +</html> | |