/* * Copyright (c) 2000, 2008, Oracle and/or its affiliates. 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.  Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ // -- This file was mechanically generated: Do not edit! -- // package java.nio;     /** * A byte buffer. * * <p> This class defines six categories of operations upon * byte buffers: * * <ul> * *   <li><p> Absolute and relative {@link #get() </code><i>get</i><code>} and *   {@link #put(byte) </code><i>put</i><code>} methods that read and write *   single bytes; </p></li> * *   <li><p> Relative {@link #get(byte[]) </code><i>bulk get</i><code>} *   methods that transfer contiguous sequences of bytes from this buffer *   into an array; </p></li> * *   <li><p> Relative {@link #put(byte[]) </code><i>bulk put</i><code>} *   methods that transfer contiguous sequences of bytes from a *   byte array or some other byte *   buffer into this buffer; </p></li> *  * *   <li><p> Absolute and relative {@link #getChar() </code><i>get</i><code>} *   and {@link #putChar(char) </code><i>put</i><code>} methods that read and *   write values of other primitive types, translating them to and from *   sequences of bytes in a particular byte order; </p></li> * *   <li><p> Methods for creating <i><a href="#views">view buffers</a></i>, *   which allow a byte buffer to be viewed as a buffer containing values of *   some other primitive type; and </p></li> *  * *   <li><p> Methods for {@link #compact </code>compacting<code>}, {@link *   #duplicate </code>duplicating<code>}, and {@link #slice *   </code>slicing<code>} a byte buffer.  </p></li> * * </ul> * * <p> Byte buffers can be created either by {@link #allocate * </code><i>allocation</i><code>}, which allocates space for the buffer's *  * * content, or by {@link #wrap(byte[]) </code><i>wrapping</i><code>} an * existing byte array  into a buffer. *        *  * * <a name="direct"> * <h4> Direct <i>vs.</i> non-direct buffers </h4> * * <p> A byte buffer is either <i>direct</i> or <i>non-direct</i>.  Given a * direct byte buffer, the Java virtual machine will make a best effort to * perform native I/O operations directly upon it.  That is, it will attempt to * avoid copying the buffer's content to (or from) an intermediate buffer * before (or after) each invocation of one of the underlying operating * system's native I/O operations. * * <p> A direct byte buffer may be created by invoking the {@link * #allocateDirect(int) allocateDirect} factory method of this class.  The * buffers returned by this method typically have somewhat higher allocation * and deallocation costs than non-direct buffers.  The contents of direct * buffers may reside outside of the normal garbage-collected heap, and so * their impact upon the memory footprint of an application might not be * obvious.  It is therefore recommended that direct buffers be allocated * primarily for large, long-lived buffers that are subject to the underlying * system's native I/O operations.  In general it is best to allocate direct * buffers only when they yield a measureable gain in program performance. * * <p> A direct byte buffer may also be created by {@link * java.nio.channels.FileChannel#map </code>mapping<code>} a region of a file * directly into memory.  An implementation of the Java platform may optionally * support the creation of direct byte buffers from native code via JNI.  If an * instance of one of these kinds of buffers refers to an inaccessible region * of memory then an attempt to access that region will not change the buffer's * content and will cause an unspecified exception to be thrown either at the * time of the access or at some later time. * * <p> Whether a byte buffer is direct or non-direct may be determined by * invoking its {@link #isDirect isDirect} method.  This method is provided so * that explicit buffer management can be done in performance-critical code. * * * <a name="bin"> * <h4> Access to binary data </h4> * * <p> This class defines methods for reading and writing values of all other * primitive types, except <tt>boolean</tt>.  Primitive values are translated * to (or from) sequences of bytes according to the buffer's current byte * order, which may be retrieved and modified via the {@link #order order} * methods.  Specific byte orders are represented by instances of the {@link * ByteOrder} class.  The initial order of a byte buffer is always {@link * ByteOrder#BIG_ENDIAN BIG_ENDIAN}. * * <p> For access to heterogeneous binary data, that is, sequences of values of * different types, this class defines a family of absolute and relative * <i>get</i> and <i>put</i> methods for each type.  For 32-bit floating-point * values, for example, this class defines: * * <blockquote><pre> * float  {@link #getFloat()} * float  {@link #getFloat(int) getFloat(int index)} *  void  {@link #putFloat(float) putFloat(float f)} *  void  {@link #putFloat(int,float) putFloat(int index, float f)}</pre></blockquote> * * <p> Corresponding methods are defined for the types <tt>char</tt>, * <tt>short</tt>, <tt>int</tt>, <tt>long</tt>, and <tt>double</tt>.  The index * parameters of the absolute <i>get</i> and <i>put</i> methods are in terms of * bytes rather than of the type being read or written. * * <a name="views"> * * <p> For access to homogeneous binary data, that is, sequences of values of * the same type, this class defines methods that can create <i>views</i> of a * given byte buffer.  A <i>view buffer</i> is simply another buffer whose * content is backed by the byte buffer.  Changes to the byte buffer's content * will be visible in the view buffer, and vice versa; the two buffers' * position, limit, and mark values are independent.  The {@link * #asFloatBuffer() asFloatBuffer} method, for example, creates an instance of * the {@link FloatBuffer} class that is backed by the byte buffer upon which * the method is invoked.  Corresponding view-creation methods are defined for * the types <tt>char</tt>, <tt>short</tt>, <tt>int</tt>, <tt>long</tt>, and * <tt>double</tt>. * * <p> View buffers have three important advantages over the families of * type-specific <i>get</i> and <i>put</i> methods described above: * * <ul> * *   <li><p> A view buffer is indexed not in terms of bytes but rather in terms *   of the type-specific size of its values;  </p></li> * *   <li><p> A view buffer provides relative bulk <i>get</i> and <i>put</i> *   methods that can transfer contiguous sequences of values between a buffer *   and an array or some other buffer of the same type; and  </p></li> * *   <li><p> A view buffer is potentially much more efficient because it will *   be direct if, and only if, its backing byte buffer is direct.  </p></li> * * </ul> * * <p> The byte order of a view buffer is fixed to be that of its byte buffer * at the time that the view is created.  </p> * *           *         *  * <h4> Invocation chaining </h4>  * * <p> Methods in this class that do not otherwise have a value to return are * specified to return the buffer upon which they are invoked.  This allows * method invocations to be chained. *  * * The sequence of statements * * <blockquote><pre> * bb.putInt(0xCAFEBABE); * bb.putShort(3); * bb.putShort(45);</pre></blockquote> * * can, for example, be replaced by the single statement * * <blockquote><pre> * bb.putInt(0xCAFEBABE).putShort(3).putShort(45);</pre></blockquote> *                  * * * @author Mark Reinhold * @author JSR-51 Expert Group * @since 1.4 */ public abstract class ByteBuffer    extends Buffer    implements Comparable<ByteBuffer>{     // These fields are declared here rather than in Heap-X-Buffer in order to    // reduce the number of virtual method invocations needed to access these    // values, which is especially costly when coding small buffers.    //    final byte[] hb;                  // Non-null only for heap buffers    final int offset;    boolean isReadOnly;                 // Valid only for heap buffers     // Creates a new buffer with the given mark, position, limit, capacity,    // backing array, and array offset    //    ByteBuffer(int mark, int pos, int lim, int cap,   // package-private                 byte[] hb, int offset)    {        super(mark, pos, lim, cap);        this.hb = hb;        this.offset = offset;    }     // Creates a new buffer with the given mark, position, limit, and capacity    //    ByteBuffer(int mark, int pos, int lim, int cap) { // package-private        this(mark, pos, lim, cap, null, 0);    }       /**     * Allocates a new direct byte buffer.     *     * <p> The new buffer's position will be zero, its limit will be its     * capacity, its mark will be undefined, and each of its elements will be     * initialized to zero.  Whether or not it has a     * {@link #hasArray </code>backing array<code>} is unspecified.     *     * @param  capacity     *         The new buffer's capacity, in bytes     *     * @return  The new byte buffer     *     * @throws  IllegalArgumentException     *          If the <tt>capacity</tt> is a negative integer     */    public static ByteBuffer allocateDirect(int capacity) {        return new DirectByteBuffer(capacity);    }       /**     * Allocates a new byte buffer.     *     * <p> The new buffer's position will be zero, its limit will be its     * capacity, its mark will be undefined, and each of its elements will be     * initialized to zero.  It will have a {@link #array     * </code>backing array<code>}, and its {@link #arrayOffset </code>array     * offset<code>} will be zero.     *     * @param  capacity     *         The new buffer's capacity, in bytes     *     * @return  The new byte buffer     *     * @throws  IllegalArgumentException     *          If the <tt>capacity</tt> is a negative integer     */    public static ByteBuffer allocate(int capacity) {        if (capacity < 0)            throw new IllegalArgumentException();        return new HeapByteBuffer(capacity, capacity);    }     /**     * Wraps a byte array into a buffer.     *     * <p> The new buffer will be backed by the given byte array;     * that is, modifications to the buffer will cause the array to be modified     * and vice versa.  The new buffer's capacity will be     * <tt>array.length</tt>, its position will be <tt>offset</tt>, its limit     * will be <tt>offset + length</tt>, and its mark will be undefined.  Its     * {@link #array </code>backing array<code>} will be the given array, and     * its {@link #arrayOffset </code>array offset<code>} will be zero.  </p>     *     * @param  array     *         The array that will back the new buffer     *     * @param  offset     *         The offset of the subarray to be used; must be non-negative and     *         no larger than <tt>array.length</tt>.  The new buffer's position     *         will be set to this value.     *     * @param  length     *         The length of the subarray to be used;     *         must be non-negative and no larger than     *         <tt>array.length - offset</tt>.     *         The new buffer's limit will be set to <tt>offset + length</tt>.     *     * @return  The new byte buffer     *     * @throws  IndexOutOfBoundsException     *          If the preconditions on the <tt>offset</tt> and <tt>length</tt>     *          parameters do not hold     */    public static ByteBuffer wrap(byte[] array,                                    int offset, int length)    {        try {            return new HeapByteBuffer(array, offset, length);        } catch (IllegalArgumentException x) {            throw new IndexOutOfBoundsException();        }    }     /**     * Wraps a byte array into a buffer.     *     * <p> The new buffer will be backed by the given byte array;     * that is, modifications to the buffer will cause the array to be modified     * and vice versa.  The new buffer's capacity and limit will be     * <tt>array.length</tt>, its position will be zero, and its mark will be     * undefined.  Its {@link #array </code>backing array<code>} will be the     * given array, and its {@link #arrayOffset </code>array offset<code>} will     * be zero.  </p>     *     * @param  array     *         The array that will back this buffer     *     * @return  The new byte buffer     */    public static ByteBuffer wrap(byte[] array) {        return wrap(array, 0, array.length);    }                                                                                                  /**     * Creates a new byte buffer whose content is a shared subsequence of     * this buffer's content.     *     * <p> The content of the new buffer will start at this buffer's current     * position.  Changes to this buffer's content will be visible in the new     * buffer, and vice versa; the two buffers' position, limit, and mark     * values will be independent.     *     * <p> The new buffer's position will be zero, its capacity and its limit     * will be the number of bytes remaining in this buffer, and its mark     * will be undefined.  The new buffer will be direct if, and only if, this     * buffer is direct, and it will be read-only if, and only if, this buffer

Lines 1–500 of 2046. Load more