1 /* 2 * Copyright (C) 2014 The Android Open Source Project 3 * Copyright (c) 2000, 2008, Oracle and/or its affiliates. All rights reserved. 4 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 5 * 6 * This code is free software; you can redistribute it and/or modify it 7 * under the terms of the GNU General Public License version 2 only, as 8 * published by the Free Software Foundation. Oracle designates this 9 * particular file as subject to the "Classpath" exception as provided 10 * by Oracle in the LICENSE file that accompanied this code. 11 * 12 * This code is distributed in the hope that it will be useful, but WITHOUT 13 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 14 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 15 * version 2 for more details (a copy is included in the LICENSE file that 16 * accompanied this code). 17 * 18 * You should have received a copy of the GNU General Public License version 19 * 2 along with this work; if not, write to the Free Software Foundation, 20 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 21 * 22 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 23 * or visit www.oracle.com if you need additional information or have any 24 * questions. 25 */ 26 27 // -- This file was mechanically generated: Do not edit! -- // 28 29 package java.nio; 30 31 import libcore.io.Memory; 32 33 /** 34 * A byte buffer. 35 * 36 * <p> This class defines six categories of operations upon 37 * byte buffers: 38 * 39 * <ul> 40 * 41 * <li><p> Absolute and relative {@link #get() </code><i>get</i><code>} and 42 * {@link #put(byte) </code><i>put</i><code>} methods that read and write 43 * single bytes; </p></li> 44 * 45 * <li><p> Relative {@link #get(byte[]) </code><i>bulk get</i><code>} 46 * methods that transfer contiguous sequences of bytes from this buffer 47 * into an array; </p></li> 48 * 49 * <li><p> Relative {@link #put(byte[]) </code><i>bulk put</i><code>} 50 * methods that transfer contiguous sequences of bytes from a 51 * byte array or some other byte 52 * buffer into this buffer; </p></li> 53 * 54 * <li><p> Absolute and relative {@link #getChar() </code><i>get</i><code>} 55 * and {@link #putChar(char) </code><i>put</i><code>} methods that read and 56 * write values of other primitive types, translating them to and from 57 * sequences of bytes in a particular byte order; </p></li> 58 * 59 * <li><p> Methods for creating <i><a href="#views">view buffers</a></i>, 60 * which allow a byte buffer to be viewed as a buffer containing values of 61 * some other primitive type; and </p></li> 62 * 63 * 64 * 65 * <li><p> Methods for {@link #compact </code>compacting<code>}, {@link 66 * #duplicate </code>duplicating<code>}, and {@link #slice 67 * </code>slicing<code>} a byte buffer. </p></li> 68 * 69 * </ul> 70 * 71 * <p> Byte buffers can be created either by {@link #allocate 72 * </code><i>allocation</i><code>}, which allocates space for the buffer's 73 * content, or by {@link #wrap(byte[]) </code><i>wrapping</i><code>} an 74 * existing byte array into a buffer. 75 * 76 * <a name="direct"> 77 * <h4> Direct <i>vs.</i> non-direct buffers </h4> 78 * 79 * <p> A byte buffer is either <i>direct</i> or <i>non-direct</i>. Given a 80 * direct byte buffer, the Java virtual machine will make a best effort to 81 * perform native I/O operations directly upon it. That is, it will attempt to 82 * avoid copying the buffer's content to (or from) an intermediate buffer 83 * before (or after) each invocation of one of the underlying operating 84 * system's native I/O operations. 85 * 86 * <p> A direct byte buffer may be created by invoking the {@link 87 * #allocateDirect(int) allocateDirect} factory method of this class. The 88 * buffers returned by this method typically have somewhat higher allocation 89 * and deallocation costs than non-direct buffers. The contents of direct 90 * buffers may reside outside of the normal garbage-collected heap, and so 91 * their impact upon the memory footprint of an application might not be 92 * obvious. It is therefore recommended that direct buffers be allocated 93 * primarily for large, long-lived buffers that are subject to the underlying 94 * system's native I/O operations. In general it is best to allocate direct 95 * buffers only when they yield a measureable gain in program performance. 96 * 97 * <p> A direct byte buffer may also be created by {@link 98 * java.nio.channels.FileChannel#map </code>mapping<code>} a region of a file 99 * directly into memory. An implementation of the Java platform may optionally 100 * support the creation of direct byte buffers from native code via JNI. If an 101 * instance of one of these kinds of buffers refers to an inaccessible region 102 * of memory then an attempt to access that region will not change the buffer's 103 * content and will cause an unspecified exception to be thrown either at the 104 * time of the access or at some later time. 105 * 106 * <p> Whether a byte buffer is direct or non-direct may be determined by 107 * invoking its {@link #isDirect isDirect} method. This method is provided so 108 * that explicit buffer management can be done in performance-critical code. 109 * 110 * <a name="bin"> 111 * <h4> Access to binary data </h4> 112 * 113 * <p> This class defines methods for reading and writing values of all other 114 * primitive types, except <tt>boolean</tt>. Primitive values are translated 115 * to (or from) sequences of bytes according to the buffer's current byte 116 * order, which may be retrieved and modified via the {@link #order order} 117 * methods. Specific byte orders are represented by instances of the {@link 118 * ByteOrder} class. The initial order of a byte buffer is always {@link 119 * ByteOrder#BIG_ENDIAN BIG_ENDIAN}. 120 * 121 * <p> For access to heterogeneous binary data, that is, sequences of values of 122 * different types, this class defines a family of absolute and relative 123 * <i>get</i> and <i>put</i> methods for each type. For 32-bit floating-point 124 * values, for example, this class defines: 125 * 126 * <blockquote><pre> 127 * float {@link #getFloat()} 128 * float {@link #getFloat(int) getFloat(int index)} 129 * void {@link #putFloat(float) putFloat(float f)} 130 * void {@link #putFloat(int, float) putFloat(int index, float f)}</pre></blockquote> 131 * 132 * <p> Corresponding methods are defined for the types <tt>char</tt>, 133 * <tt>short</tt>, <tt>int</tt>, <tt>long</tt>, and <tt>double</tt>. The index 134 * parameters of the absolute <i>get</i> and <i>put</i> methods are in terms of 135 * bytes rather than of the type being read or written. 136 * 137 * <a name="views"> 138 * 139 * <p> For access to homogeneous binary data, that is, sequences of values of 140 * the same type, this class defines methods that can create <i>views</i> of a 141 * given byte buffer. A <i>view buffer</i> is simply another buffer whose 142 * content is backed by the byte buffer. Changes to the byte buffer's content 143 * will be visible in the view buffer, and vice versa; the two buffers' 144 * position, limit, and mark values are independent. The {@link 145 * #asFloatBuffer() asFloatBuffer} method, for example, creates an instance of 146 * the {@link FloatBuffer} class that is backed by the byte buffer upon which 147 * the method is invoked. Corresponding view-creation methods are defined for 148 * the types <tt>char</tt>, <tt>short</tt>, <tt>int</tt>, <tt>long</tt>, and 149 * <tt>double</tt>. 150 * 151 * <p> View buffers have three important advantages over the families of 152 * type-specific <i>get</i> and <i>put</i> methods described above: 153 * 154 * <ul> 155 * 156 * <li><p> A view buffer is indexed not in terms of bytes but rather in terms 157 * of the type-specific size of its values; </p></li> 158 * 159 * <li><p> A view buffer provides relative bulk <i>get</i> and <i>put</i> 160 * methods that can transfer contiguous sequences of values between a buffer 161 * and an array or some other buffer of the same type; and </p></li> 162 * 163 * <li><p> A view buffer is potentially much more efficient because it will 164 * be direct if, and only if, its backing byte buffer is direct. </p></li> 165 * 166 * </ul> 167 * 168 * <p> The byte order of a view buffer is fixed to be that of its byte buffer 169 * at the time that the view is created. </p> 170 * 171 * <h4> Invocation chaining </h4> 172 * 173 * <p> Methods in this class that do not otherwise have a value to return are 174 * specified to return the buffer upon which they are invoked. This allows 175 * method invocations to be chained. 176 * 177 * The sequence of statements 178 * 179 * <blockquote><pre> 180 * bb.putInt(0xCAFEBABE); 181 * bb.putShort(3); 182 * bb.putShort(45);</pre></blockquote> 183 * 184 * can, for example, be replaced by the single statement 185 * 186 * <blockquote><pre> 187 * bb.putInt(0xCAFEBABE).putShort(3).putShort(45);</pre></blockquote> 188 * 189 * @author Mark Reinhold 190 * @author JSR-51 Expert Group 191 * @since 1.4 192 */ 193 194 public abstract class ByteBuffer 195 extends Buffer 196 implements Comparable<ByteBuffer> { 197 198 // These fields are declared here rather than in Heap-X-Buffer in order to 199 // reduce the number of virtual method invocations needed to access these 200 // values, which is especially costly when coding small buffers. 201 // 202 final byte[] hb; // Non-null only for heap buffers 203 final int offset; 204 boolean isReadOnly; // Valid only for heap buffers 205 206 // Creates a new buffer with the given mark, position, limit, capacity, 207 // backing array, and array offset 208 // ByteBuffer(int mark, int pos, int lim, int cap, byte[] hb, int offset)209 ByteBuffer(int mark, int pos, int lim, int cap, // package-private 210 byte[] hb, int offset) { 211 super(mark, pos, lim, cap, 0); 212 this.hb = hb; 213 this.offset = offset; 214 } 215 216 // Creates a new buffer with the given mark, position, limit, and capacity 217 // ByteBuffer(int mark, int pos, int lim, int cap)218 ByteBuffer(int mark, int pos, int lim, int cap) { // package-private 219 this(mark, pos, lim, cap, null, 0); 220 } 221 222 223 /** 224 * Allocates a new direct byte buffer. 225 * 226 * <p> The new buffer's position will be zero, its limit will be its 227 * capacity, its mark will be undefined, and each of its elements will be 228 * initialized to zero. Whether or not it has a 229 * {@link #hasArray </code>backing array<code>} is unspecified. 230 * 231 * @param capacity The new buffer's capacity, in bytes 232 * @return The new byte buffer 233 * @throws IllegalArgumentException If the <tt>capacity</tt> is a negative integer 234 */ allocateDirect(int capacity)235 public static ByteBuffer allocateDirect(int capacity) { 236 if (capacity < 0) { 237 throw new IllegalArgumentException("capacity < 0: " + capacity); 238 } 239 240 DirectByteBuffer.MemoryRef memoryRef = new DirectByteBuffer.MemoryRef(capacity); 241 return new DirectByteBuffer(capacity, memoryRef); 242 } 243 244 245 /** 246 * Allocates a new byte buffer. 247 * 248 * <p> The new buffer's position will be zero, its limit will be its 249 * capacity, its mark will be undefined, and each of its elements will be 250 * initialized to zero. It will have a {@link #array 251 * </code>backing array<code>}, and its {@link #arrayOffset </code>array 252 * offset<code>} will be zero. 253 * 254 * @param capacity The new buffer's capacity, in bytes 255 * @return The new byte buffer 256 * @throws IllegalArgumentException If the <tt>capacity</tt> is a negative integer 257 */ allocate(int capacity)258 public static ByteBuffer allocate(int capacity) { 259 if (capacity < 0) 260 throw new IllegalArgumentException(); 261 return new HeapByteBuffer(capacity, capacity); 262 } 263 264 /** 265 * Wraps a byte array into a buffer. 266 * 267 * <p> The new buffer will be backed by the given byte array; 268 * that is, modifications to the buffer will cause the array to be modified 269 * and vice versa. The new buffer's capacity will be 270 * <tt>array.length</tt>, its position will be <tt>offset</tt>, its limit 271 * will be <tt>offset + length</tt>, and its mark will be undefined. Its 272 * {@link #array </code>backing array<code>} will be the given array, and 273 * its {@link #arrayOffset </code>array offset<code>} will be zero. </p> 274 * 275 * @param array The array that will back the new buffer 276 * @param offset The offset of the subarray to be used; must be non-negative and 277 * no larger than <tt>array.length</tt>. The new buffer's position 278 * will be set to this value. 279 * @param length The length of the subarray to be used; 280 * must be non-negative and no larger than 281 * <tt>array.length - offset</tt>. 282 * The new buffer's limit will be set to <tt>offset + length</tt>. 283 * @return The new byte buffer 284 * @throws IndexOutOfBoundsException If the preconditions on the <tt>offset</tt> and 285 * <tt>length</tt> 286 * parameters do not hold 287 */ wrap(byte[] array, int offset, int length)288 public static ByteBuffer wrap(byte[] array, 289 int offset, int length) { 290 try { 291 return new HeapByteBuffer(array, offset, length); 292 } catch (IllegalArgumentException x) { 293 throw new IndexOutOfBoundsException(); 294 } 295 } 296 297 /** 298 * Wraps a byte array into a buffer. 299 * 300 * <p> The new buffer will be backed by the given byte array; 301 * that is, modifications to the buffer will cause the array to be modified 302 * and vice versa. The new buffer's capacity and limit will be 303 * <tt>array.length</tt>, its position will be zero, and its mark will be 304 * undefined. Its {@link #array </code>backing array<code>} will be the 305 * given array, and its {@link #arrayOffset </code>array offset<code>} will 306 * be zero. </p> 307 * 308 * @param array The array that will back this buffer 309 * @return The new byte buffer 310 */ wrap(byte[] array)311 public static ByteBuffer wrap(byte[] array) { 312 return wrap(array, 0, array.length); 313 } 314 315 316 /** 317 * Creates a new byte buffer whose content is a shared subsequence of 318 * this buffer's content. 319 * 320 * <p> The content of the new buffer will start at this buffer's current 321 * position. Changes to this buffer's content will be visible in the new 322 * buffer, and vice versa; the two buffers' position, limit, and mark 323 * values will be independent. 324 * 325 * <p> The new buffer's position will be zero, its capacity and its limit 326 * will be the number of bytes remaining in this buffer, and its mark 327 * will be undefined. The new buffer will be direct if, and only if, this 328 * buffer is direct, and it will be read-only if, and only if, this buffer 329 * is read-only. </p> 330 * 331 * @return The new byte buffer 332 */ slice()333 public abstract ByteBuffer slice(); 334 335 /** 336 * Creates a new byte buffer that shares this buffer's content. 337 * 338 * <p> The content of the new buffer will be that of this buffer. Changes 339 * to this buffer's content will be visible in the new buffer, and vice 340 * versa; the two buffers' position, limit, and mark values will be 341 * independent. 342 * 343 * <p> The new buffer's capacity, limit, position, and mark values will be 344 * identical to those of this buffer. The new buffer will be direct if, 345 * and only if, this buffer is direct, and it will be read-only if, and 346 * only if, this buffer is read-only. </p> 347 * 348 * @return The new byte buffer 349 */ duplicate()350 public abstract ByteBuffer duplicate(); 351 352 /** 353 * Creates a new, read-only byte buffer that shares this buffer's 354 * content. 355 * 356 * <p> The content of the new buffer will be that of this buffer. Changes 357 * to this buffer's content will be visible in the new buffer; the new 358 * buffer itself, however, will be read-only and will not allow the shared 359 * content to be modified. The two buffers' position, limit, and mark 360 * values will be independent. 361 * 362 * <p> The new buffer's capacity, limit, position, and mark values will be 363 * identical to those of this buffer. 364 * 365 * <p> If this buffer is itself read-only then this method behaves in 366 * exactly the same way as the {@link #duplicate duplicate} method. </p> 367 * 368 * @return The new, read-only byte buffer 369 */ asReadOnlyBuffer()370 public abstract ByteBuffer asReadOnlyBuffer(); 371 372 373 // -- Singleton get/put methods -- 374 375 /** 376 * Relative <i>get</i> method. Reads the byte at this buffer's 377 * current position, and then increments the position. </p> 378 * 379 * @return The byte at the buffer's current position 380 * @throws BufferUnderflowException If the buffer's current position is not smaller than its 381 * limit 382 */ get()383 public abstract byte get(); 384 385 /** 386 * Relative <i>put</i> method <i>(optional operation)</i>. 387 * 388 * <p> Writes the given byte into this buffer at the current 389 * position, and then increments the position. </p> 390 * 391 * @param b The byte to be written 392 * @return This buffer 393 * @throws BufferOverflowException If this buffer's current position is not smaller than its 394 * limit 395 * @throws ReadOnlyBufferException If this buffer is read-only 396 */ put(byte b)397 public abstract ByteBuffer put(byte b); 398 399 /** 400 * Absolute <i>get</i> method. Reads the byte at the given 401 * index. </p> 402 * 403 * @param index The index from which the byte will be read 404 * @return The byte at the given index 405 * @throws IndexOutOfBoundsException If <tt>index</tt> is negative 406 * or not smaller than the buffer's limit 407 */ get(int index)408 public abstract byte get(int index); 409 410 /** 411 * Absolute <i>put</i> method <i>(optional operation)</i>. 412 * 413 * <p> Writes the given byte into this buffer at the given 414 * index. </p> 415 * 416 * @param index The index at which the byte will be written 417 * @param b The byte value to be written 418 * @return This buffer 419 * @throws IndexOutOfBoundsException If <tt>index</tt> is negative 420 * or not smaller than the buffer's limit 421 * @throws ReadOnlyBufferException If this buffer is read-only 422 */ put(int index, byte b)423 public abstract ByteBuffer put(int index, byte b); 424 425 426 // -- Bulk get operations -- 427 428 /** 429 * Relative bulk <i>get</i> method. 430 * 431 * <p> This method transfers bytes from this buffer into the given 432 * destination array. If there are fewer bytes remaining in the 433 * buffer than are required to satisfy the request, that is, if 434 * <tt>length</tt> <tt>></tt> <tt>remaining()</tt>, then no 435 * bytes are transferred and a {@link BufferUnderflowException} is 436 * thrown. 437 * 438 * <p> Otherwise, this method copies <tt>length</tt> bytes from this 439 * buffer into the given array, starting at the current position of this 440 * buffer and at the given offset in the array. The position of this 441 * buffer is then incremented by <tt>length</tt>. 442 * 443 * <p> In other words, an invocation of this method of the form 444 * <tt>src.get(dst, off, len)</tt> has exactly the same effect as 445 * the loop 446 * 447 * <pre> 448 * for (int i = off; i < off + len; i++) 449 * dst[i] = src.get(); </pre> 450 * 451 * except that it first checks that there are sufficient bytes in 452 * this buffer and it is potentially much more efficient. </p> 453 * 454 * @param dst The array into which bytes are to be written 455 * @param offset The offset within the array of the first byte to be 456 * written; must be non-negative and no larger than 457 * <tt>dst.length</tt> 458 * @param length The maximum number of bytes to be written to the given 459 * array; must be non-negative and no larger than 460 * <tt>dst.length - offset</tt> 461 * @return This buffer 462 * @throws BufferUnderflowException If there are fewer than <tt>length</tt> bytes 463 * remaining in this buffer 464 * @throws IndexOutOfBoundsException If the preconditions on the <tt>offset</tt> and 465 * <tt>length</tt> 466 * parameters do not hold 467 */ get(byte[] dst, int offset, int length)468 public ByteBuffer get(byte[] dst, int offset, int length) { 469 checkBounds(offset, length, dst.length); 470 if (length > remaining()) 471 throw new BufferUnderflowException(); 472 int end = offset + length; 473 for (int i = offset; i < end; i++) 474 dst[i] = get(); 475 return this; 476 } 477 478 /** 479 * Relative bulk <i>get</i> method. 480 * 481 * <p> This method transfers bytes from this buffer into the given 482 * destination array. An invocation of this method of the form 483 * <tt>src.get(a)</tt> behaves in exactly the same way as the invocation 484 * 485 * <pre> 486 * src.get(a, 0, a.length) </pre> 487 * 488 * @return This buffer 489 * @throws BufferUnderflowException If there are fewer than <tt>length</tt> bytes 490 * remaining in this buffer 491 */ get(byte[] dst)492 public ByteBuffer get(byte[] dst) { 493 return get(dst, 0, dst.length); 494 } 495 496 497 // -- Bulk put operations -- 498 499 /** 500 * Relative bulk <i>put</i> method <i>(optional operation)</i>. 501 * 502 * <p> This method transfers the bytes remaining in the given source 503 * buffer into this buffer. If there are more bytes remaining in the 504 * source buffer than in this buffer, that is, if 505 * <tt>src.remaining()</tt> <tt>></tt> <tt>remaining()</tt>, 506 * then no bytes are transferred and a {@link 507 * BufferOverflowException} is thrown. 508 * 509 * <p> Otherwise, this method copies 510 * <i>n</i> = <tt>src.remaining()</tt> bytes from the given 511 * buffer into this buffer, starting at each buffer's current position. 512 * The positions of both buffers are then incremented by <i>n</i>. 513 * 514 * <p> In other words, an invocation of this method of the form 515 * <tt>dst.put(src)</tt> has exactly the same effect as the loop 516 * 517 * <pre> 518 * while (src.hasRemaining()) 519 * dst.put(src.get()); </pre> 520 * 521 * except that it first checks that there is sufficient space in this 522 * buffer and it is potentially much more efficient. </p> 523 * 524 * @param src The source buffer from which bytes are to be read; 525 * must not be this buffer 526 * @return This buffer 527 * @throws BufferOverflowException If there is insufficient space in this buffer 528 * for the remaining bytes in the source buffer 529 * @throws IllegalArgumentException If the source buffer is this buffer 530 * @throws ReadOnlyBufferException If this buffer is read-only 531 */ put(ByteBuffer src)532 public ByteBuffer put(ByteBuffer src) { 533 if (!isAccessible()) { 534 throw new IllegalStateException("buffer is inaccessible"); 535 } 536 if (src == this) { 537 throw new IllegalArgumentException(); 538 } 539 if (isReadOnly) { 540 throw new ReadOnlyBufferException(); 541 } 542 int n = src.remaining(); 543 if (n > remaining()) { 544 throw new BufferOverflowException(); 545 } 546 547 // Note that we use offset instead of arrayOffset because arrayOffset is specified to 548 // throw for read only buffers. Our use of arrayOffset here is provably safe, we only 549 // use it to read *from* readOnly buffers. 550 if (this.hb != null && src.hb != null) { 551 // System.arraycopy is intrinsified by art and therefore tiny bit faster than memmove 552 System.arraycopy(src.hb, src.position() + src.offset, hb, position() + offset, n); 553 } else { 554 // Use the buffer object (and the raw memory address) if it's a direct buffer. Note that 555 // isDirect() doesn't imply !hasArray(), ByteBuffer.allocateDirect allocated buffer will 556 // have a backing, non-gc-movable byte array. JNI allocated direct byte buffers WILL NOT 557 // have a backing array. 558 final Object srcObject = src.isDirect() ? src : src.hb; 559 int srcOffset = src.position(); 560 if (!src.isDirect()) { 561 srcOffset += src.offset; 562 } 563 564 final ByteBuffer dst = this; 565 final Object dstObject = dst.isDirect() ? dst : dst.hb; 566 int dstOffset = dst.position(); 567 if (!dst.isDirect()) { 568 dstOffset += dst.offset; 569 } 570 Memory.memmove(dstObject, dstOffset, srcObject, srcOffset, n); 571 } 572 src.position(src.limit()); 573 this.position(this.position() + n); 574 return this; 575 } 576 577 /** 578 * Relative bulk <i>put</i> method <i>(optional operation)</i>. 579 * 580 * <p> This method transfers bytes into this buffer from the given 581 * source array. If there are more bytes to be copied from the array 582 * than remain in this buffer, that is, if 583 * <tt>length</tt> <tt>></tt> <tt>remaining()</tt>, then no 584 * bytes are transferred and a {@link BufferOverflowException} is 585 * thrown. 586 * 587 * <p> Otherwise, this method copies <tt>length</tt> bytes from the 588 * given array into this buffer, starting at the given offset in the array 589 * and at the current position of this buffer. The position of this buffer 590 * is then incremented by <tt>length</tt>. 591 * 592 * <p> In other words, an invocation of this method of the form 593 * <tt>dst.put(src, off, len)</tt> has exactly the same effect as 594 * the loop 595 * 596 * <pre> 597 * for (int i = off; i < off + len; i++) 598 * dst.put(a[i]); </pre> 599 * 600 * except that it first checks that there is sufficient space in this 601 * buffer and it is potentially much more efficient. </p> 602 * 603 * @param src The array from which bytes are to be read 604 * @param offset The offset within the array of the first byte to be read; 605 * must be non-negative and no larger than <tt>array.length</tt> 606 * @param length The number of bytes to be read from the given array; 607 * must be non-negative and no larger than 608 * <tt>array.length - offset</tt> 609 * @return This buffer 610 * @throws BufferOverflowException If there is insufficient space in this buffer 611 * @throws IndexOutOfBoundsException If the preconditions on the <tt>offset</tt> and 612 * <tt>length</tt> 613 * parameters do not hold 614 * @throws ReadOnlyBufferException If this buffer is read-only 615 */ put(byte[] src, int offset, int length)616 public ByteBuffer put(byte[] src, int offset, int length) { 617 checkBounds(offset, length, src.length); 618 if (length > remaining()) 619 throw new BufferOverflowException(); 620 int end = offset + length; 621 for (int i = offset; i < end; i++) 622 this.put(src[i]); 623 return this; 624 } 625 626 /** 627 * Relative bulk <i>put</i> method <i>(optional operation)</i>. 628 * 629 * <p> This method transfers the entire content of the given source 630 * byte array into this buffer. An invocation of this method of the 631 * form <tt>dst.put(a)</tt> behaves in exactly the same way as the 632 * invocation 633 * 634 * <pre> 635 * dst.put(a, 0, a.length) </pre> 636 * 637 * @return This buffer 638 * @throws BufferOverflowException If there is insufficient space in this buffer 639 * @throws ReadOnlyBufferException If this buffer is read-only 640 */ put(byte[] src)641 public final ByteBuffer put(byte[] src) { 642 return put(src, 0, src.length); 643 } 644 645 646 // -- Other stuff -- 647 648 /** 649 * Tells whether or not this buffer is backed by an accessible byte 650 * array. 651 * 652 * <p> If this method returns <tt>true</tt> then the {@link #array() array} 653 * and {@link #arrayOffset() arrayOffset} methods may safely be invoked. 654 * </p> 655 * 656 * @return <tt>true</tt> if, and only if, this buffer 657 * is backed by an array and is not read-only 658 */ hasArray()659 public final boolean hasArray() { 660 return (hb != null) && !isReadOnly(); 661 } 662 663 /** 664 * Returns the byte array that backs this 665 * buffer <i>(optional operation)</i>. 666 * 667 * <p> Modifications to this buffer's content will cause the returned 668 * array's content to be modified, and vice versa. 669 * 670 * <p> Invoke the {@link #hasArray hasArray} method before invoking this 671 * method in order to ensure that this buffer has an accessible backing 672 * array. </p> 673 * 674 * @return The array that backs this buffer 675 * @throws ReadOnlyBufferException If this buffer is backed by an array but is read-only 676 * @throws UnsupportedOperationException If this buffer is not backed by an accessible array 677 */ array()678 public final byte[] array() { 679 if (hb == null) 680 throw new UnsupportedOperationException(); 681 if (isReadOnly) 682 throw new ReadOnlyBufferException(); 683 return hb; 684 } 685 686 /** 687 * Returns the offset within this buffer's backing array of the first 688 * element of the buffer <i>(optional operation)</i>. 689 * 690 * <p> If this buffer is backed by an array then buffer position <i>p</i> 691 * corresponds to array index <i>p</i> + <tt>arrayOffset()</tt>. 692 * 693 * <p> Invoke the {@link #hasArray hasArray} method before invoking this 694 * method in order to ensure that this buffer has an accessible backing 695 * array. </p> 696 * 697 * @return The offset within this buffer's array 698 * of the first element of the buffer 699 * @throws ReadOnlyBufferException If this buffer is backed by an array but is read-only 700 * @throws UnsupportedOperationException If this buffer is not backed by an accessible array 701 */ arrayOffset()702 public final int arrayOffset() { 703 if (hb == null) 704 throw new UnsupportedOperationException(); 705 if (isReadOnly) 706 throw new ReadOnlyBufferException(); 707 return offset; 708 } 709 710 /** 711 * Compacts this buffer <i>(optional operation)</i>. 712 * 713 * <p> The bytes between the buffer's current position and its limit, 714 * if any, are copied to the beginning of the buffer. That is, the 715 * byte at index <i>p</i> = <tt>position()</tt> is copied 716 * to index zero, the byte at index <i>p</i> + 1 is copied 717 * to index one, and so forth until the byte at index 718 * <tt>limit()</tt> - 1 is copied to index 719 * <i>n</i> = <tt>limit()</tt> - <tt>1</tt> - <i>p</i>. 720 * The buffer's position is then set to <i>n+1</i> and its limit is set to 721 * its capacity. The mark, if defined, is discarded. 722 * 723 * <p> The buffer's position is set to the number of bytes copied, 724 * rather than to zero, so that an invocation of this method can be 725 * followed immediately by an invocation of another relative <i>put</i> 726 * method. </p> 727 * 728 * 729 * 730 * <p> Invoke this method after writing data from a buffer in case the 731 * write was incomplete. The following loop, for example, copies bytes 732 * from one channel to another via the buffer <tt>buf</tt>: 733 * 734 * <blockquote><pre> 735 * buf.clear(); // Prepare buffer for use 736 * while (in.read(buf) >= 0 || buf.position != 0) { 737 * buf.flip(); 738 * out.write(buf); 739 * buf.compact(); // In case of partial write 740 * }</pre></blockquote> 741 * 742 * @return This buffer 743 * @throws ReadOnlyBufferException If this buffer is read-only 744 */ compact()745 public abstract ByteBuffer compact(); 746 747 /** 748 * Tells whether or not this byte buffer is direct. </p> 749 * 750 * @return <tt>true</tt> if, and only if, this buffer is direct 751 */ isDirect()752 public abstract boolean isDirect(); 753 754 755 /** 756 * Returns a string summarizing the state of this buffer. </p> 757 * 758 * @return A summary string 759 */ toString()760 public String toString() { 761 StringBuffer sb = new StringBuffer(); 762 sb.append(getClass().getName()); 763 sb.append("[pos="); 764 sb.append(position()); 765 sb.append(" lim="); 766 sb.append(limit()); 767 sb.append(" cap="); 768 sb.append(capacity()); 769 sb.append("]"); 770 return sb.toString(); 771 } 772 773 774 /** 775 * Returns the current hash code of this buffer. 776 * 777 * <p> The hash code of a byte buffer depends only upon its remaining 778 * elements; that is, upon the elements from <tt>position()</tt> up to, and 779 * including, the element at <tt>limit()</tt> - <tt>1</tt>. 780 * 781 * <p> Because buffer hash codes are content-dependent, it is inadvisable 782 * to use buffers as keys in hash maps or similar data structures unless it 783 * is known that their contents will not change. </p> 784 * 785 * @return The current hash code of this buffer 786 */ hashCode()787 public int hashCode() { 788 int h = 1; 789 int p = position(); 790 for (int i = limit() - 1; i >= p; i--) 791 h = 31 * h + (int) get(i); 792 return h; 793 } 794 795 /** 796 * Tells whether or not this buffer is equal to another object. 797 * 798 * <p> Two byte buffers are equal if, and only if, 799 * 800 * <p><ol> 801 * 802 * <li><p> They have the same element type, </p></li> 803 * 804 * <li><p> They have the same number of remaining elements, and 805 * </p></li> 806 * 807 * <li><p> The two sequences of remaining elements, considered 808 * independently of their starting positions, are pointwise equal. 809 * 810 * 811 * 812 * 813 * 814 * 815 * 816 * </p></li> 817 * 818 * </ol> 819 * 820 * <p> A byte buffer is not equal to any other type of object. </p> 821 * 822 * @param ob The object to which this buffer is to be compared 823 * @return <tt>true</tt> if, and only if, this buffer is equal to the 824 * given object 825 */ equals(Object ob)826 public boolean equals(Object ob) { 827 if (this == ob) 828 return true; 829 if (!(ob instanceof ByteBuffer)) 830 return false; 831 ByteBuffer that = (ByteBuffer) ob; 832 if (this.remaining() != that.remaining()) 833 return false; 834 int p = this.position(); 835 for (int i = this.limit() - 1, j = that.limit() - 1; i >= p; i--, j--) 836 if (!equals(this.get(i), that.get(j))) 837 return false; 838 return true; 839 } 840 equals(byte x, byte y)841 private static boolean equals(byte x, byte y) { 842 843 844 return x == y; 845 846 } 847 848 /** 849 * Compares this buffer to another. 850 * 851 * <p> Two byte buffers are compared by comparing their sequences of 852 * remaining elements lexicographically, without regard to the starting 853 * position of each sequence within its corresponding buffer. 854 * 855 * 856 * 857 * 858 * 859 * 860 * 861 * 862 * Pairs of {@code byte} elements are compared as if by invoking 863 * {@link Byte#compare(byte, byte)}. 864 * 865 * 866 * <p> A byte buffer is not comparable to any other type of object. 867 * 868 * @return A negative integer, zero, or a positive integer as this buffer 869 * is less than, equal to, or greater than the given buffer 870 */ compareTo(ByteBuffer that)871 public int compareTo(ByteBuffer that) { 872 int n = this.position() + Math.min(this.remaining(), that.remaining()); 873 for (int i = this.position(), j = that.position(); i < n; i++, j++) { 874 int cmp = compare(this.get(i), that.get(j)); 875 if (cmp != 0) 876 return cmp; 877 } 878 return this.remaining() - that.remaining(); 879 } 880 compare(byte x, byte y)881 private static int compare(byte x, byte y) { 882 883 884 return Byte.compare(x, y); 885 886 } 887 888 // -- Other char stuff -- 889 890 891 // -- Other byte stuff: Access to binary data -- 892 893 894 boolean bigEndian // package-private 895 = true; 896 boolean nativeByteOrder // package-private 897 = (Bits.byteOrder() == ByteOrder.BIG_ENDIAN); 898 899 /** 900 * Retrieves this buffer's byte order. 901 * 902 * <p> The byte order is used when reading or writing multibyte values, and 903 * when creating buffers that are views of this byte buffer. The order of 904 * a newly-created byte buffer is always {@link ByteOrder#BIG_ENDIAN 905 * BIG_ENDIAN}. </p> 906 * 907 * @return This buffer's byte order 908 */ order()909 public final ByteOrder order() { 910 return bigEndian ? ByteOrder.BIG_ENDIAN : ByteOrder.LITTLE_ENDIAN; 911 } 912 913 /** 914 * Modifies this buffer's byte order. </p> 915 * 916 * @param bo The new byte order, 917 * either {@link ByteOrder#BIG_ENDIAN BIG_ENDIAN} 918 * or {@link ByteOrder#LITTLE_ENDIAN LITTLE_ENDIAN} 919 * @return This buffer 920 */ order(ByteOrder bo)921 public final ByteBuffer order(ByteOrder bo) { 922 bigEndian = (bo == ByteOrder.BIG_ENDIAN); 923 nativeByteOrder = 924 (bigEndian == (Bits.byteOrder() == ByteOrder.BIG_ENDIAN)); 925 return this; 926 } 927 928 // Unchecked accessors, for use by ByteBufferAs-X-Buffer classes 929 // _get(int i)930 abstract byte _get(int i); // package-private 931 _put(int i, byte b)932 abstract void _put(int i, byte b); // package-private 933 934 935 /** 936 * Relative <i>get</i> method for reading a char value. 937 * 938 * <p> Reads the next two bytes at this buffer's current position, 939 * composing them into a char value according to the current byte order, 940 * and then increments the position by two. </p> 941 * 942 * @return The char value at the buffer's current position 943 * @throws BufferUnderflowException If there are fewer than two bytes 944 * remaining in this buffer 945 */ getChar()946 public abstract char getChar(); 947 948 /** 949 * Relative <i>put</i> method for writing a char 950 * value <i>(optional operation)</i>. 951 * 952 * <p> Writes two bytes containing the given char value, in the 953 * current byte order, into this buffer at the current position, and then 954 * increments the position by two. </p> 955 * 956 * @param value The char value to be written 957 * @return This buffer 958 * @throws BufferOverflowException If there are fewer than two bytes 959 * remaining in this buffer 960 * @throws ReadOnlyBufferException If this buffer is read-only 961 */ putChar(char value)962 public abstract ByteBuffer putChar(char value); 963 964 /** 965 * Absolute <i>get</i> method for reading a char value. 966 * 967 * <p> Reads two bytes at the given index, composing them into a 968 * char value according to the current byte order. </p> 969 * 970 * @param index The index from which the bytes will be read 971 * @return The char value at the given index 972 * @throws IndexOutOfBoundsException If <tt>index</tt> is negative 973 * or not smaller than the buffer's limit, 974 * minus one 975 */ getChar(int index)976 public abstract char getChar(int index); 977 getCharUnchecked(int index)978 char getCharUnchecked(int index) { 979 throw new UnsupportedOperationException(); 980 } 981 getUnchecked(int pos, char[] dst, int dstOffset, int length)982 void getUnchecked(int pos, char[] dst, int dstOffset, int length) { 983 throw new UnsupportedOperationException(); 984 } 985 986 /** 987 * Absolute <i>put</i> method for writing a char 988 * value <i>(optional operation)</i>. 989 * 990 * <p> Writes two bytes containing the given char value, in the 991 * current byte order, into this buffer at the given index. </p> 992 * 993 * @param index The index at which the bytes will be written 994 * @param value The char value to be written 995 * @return This buffer 996 * @throws IndexOutOfBoundsException If <tt>index</tt> is negative 997 * or not smaller than the buffer's limit, 998 * minus one 999 * @throws ReadOnlyBufferException If this buffer is read-only 1000 */ putChar(int index, char value)1001 public abstract ByteBuffer putChar(int index, char value); 1002 putCharUnchecked(int index, char value)1003 void putCharUnchecked(int index, char value) { 1004 throw new UnsupportedOperationException(); 1005 } 1006 putUnchecked(int pos, char[] dst, int srcOffset, int length)1007 void putUnchecked(int pos, char[] dst, int srcOffset, int length) { 1008 throw new UnsupportedOperationException(); 1009 } 1010 1011 /** 1012 * Creates a view of this byte buffer as a char buffer. 1013 * 1014 * <p> The content of the new buffer will start at this buffer's current 1015 * position. Changes to this buffer's content will be visible in the new 1016 * buffer, and vice versa; the two buffers' position, limit, and mark 1017 * values will be independent. 1018 * 1019 * <p> The new buffer's position will be zero, its capacity and its limit 1020 * will be the number of bytes remaining in this buffer divided by 1021 * two, and its mark will be undefined. The new buffer will be direct 1022 * if, and only if, this buffer is direct, and it will be read-only if, and 1023 * only if, this buffer is read-only. </p> 1024 * 1025 * @return A new char buffer 1026 */ asCharBuffer()1027 public abstract CharBuffer asCharBuffer(); 1028 1029 1030 /** 1031 * Relative <i>get</i> method for reading a short value. 1032 * 1033 * <p> Reads the next two bytes at this buffer's current position, 1034 * composing them into a short value according to the current byte order, 1035 * and then increments the position by two. </p> 1036 * 1037 * @return The short value at the buffer's current position 1038 * @throws BufferUnderflowException If there are fewer than two bytes 1039 * remaining in this buffer 1040 */ getShort()1041 public abstract short getShort(); 1042 1043 /** 1044 * Relative <i>put</i> method for writing a short 1045 * value <i>(optional operation)</i>. 1046 * 1047 * <p> Writes two bytes containing the given short value, in the 1048 * current byte order, into this buffer at the current position, and then 1049 * increments the position by two. </p> 1050 * 1051 * @param value The short value to be written 1052 * @return This buffer 1053 * @throws BufferOverflowException If there are fewer than two bytes 1054 * remaining in this buffer 1055 * @throws ReadOnlyBufferException If this buffer is read-only 1056 */ putShort(short value)1057 public abstract ByteBuffer putShort(short value); 1058 1059 /** 1060 * Absolute <i>get</i> method for reading a short value. 1061 * 1062 * <p> Reads two bytes at the given index, composing them into a 1063 * short value according to the current byte order. </p> 1064 * 1065 * @param index The index from which the bytes will be read 1066 * @return The short value at the given index 1067 * @throws IndexOutOfBoundsException If <tt>index</tt> is negative 1068 * or not smaller than the buffer's limit, 1069 * minus one 1070 */ getShort(int index)1071 public abstract short getShort(int index); 1072 getShortUnchecked(int index)1073 short getShortUnchecked(int index) { 1074 throw new UnsupportedOperationException(); 1075 } 1076 getUnchecked(int pos, short[] dst, int dstOffset, int length)1077 void getUnchecked(int pos, short[] dst, int dstOffset, int length) { 1078 throw new UnsupportedOperationException(); 1079 } 1080 1081 /** 1082 * Absolute <i>put</i> method for writing a short 1083 * value <i>(optional operation)</i>. 1084 * 1085 * <p> Writes two bytes containing the given short value, in the 1086 * current byte order, into this buffer at the given index. </p> 1087 * 1088 * @param index The index at which the bytes will be written 1089 * @param value The short value to be written 1090 * @return This buffer 1091 * @throws IndexOutOfBoundsException If <tt>index</tt> is negative 1092 * or not smaller than the buffer's limit, 1093 * minus one 1094 * @throws ReadOnlyBufferException If this buffer is read-only 1095 */ putShort(int index, short value)1096 public abstract ByteBuffer putShort(int index, short value); 1097 putShortUnchecked(int index, short value)1098 void putShortUnchecked(int index, short value) { 1099 throw new UnsupportedOperationException(); 1100 } 1101 putUnchecked(int pos, short[] dst, int srcOffset, int length)1102 void putUnchecked(int pos, short[] dst, int srcOffset, int length) { 1103 throw new UnsupportedOperationException(); 1104 } 1105 1106 /** 1107 * Creates a view of this byte buffer as a short buffer. 1108 * 1109 * <p> The content of the new buffer will start at this buffer's current 1110 * position. Changes to this buffer's content will be visible in the new 1111 * buffer, and vice versa; the two buffers' position, limit, and mark 1112 * values will be independent. 1113 * 1114 * <p> The new buffer's position will be zero, its capacity and its limit 1115 * will be the number of bytes remaining in this buffer divided by 1116 * two, and its mark will be undefined. The new buffer will be direct 1117 * if, and only if, this buffer is direct, and it will be read-only if, and 1118 * only if, this buffer is read-only. </p> 1119 * 1120 * @return A new short buffer 1121 */ asShortBuffer()1122 public abstract ShortBuffer asShortBuffer(); 1123 1124 1125 /** 1126 * Relative <i>get</i> method for reading an int value. 1127 * 1128 * <p> Reads the next four bytes at this buffer's current position, 1129 * composing them into an int value according to the current byte order, 1130 * and then increments the position by four. </p> 1131 * 1132 * @return The int value at the buffer's current position 1133 * @throws BufferUnderflowException If there are fewer than four bytes 1134 * remaining in this buffer 1135 */ getInt()1136 public abstract int getInt(); 1137 1138 /** 1139 * Relative <i>put</i> method for writing an int 1140 * value <i>(optional operation)</i>. 1141 * 1142 * <p> Writes four bytes containing the given int value, in the 1143 * current byte order, into this buffer at the current position, and then 1144 * increments the position by four. </p> 1145 * 1146 * @param value The int value to be written 1147 * @return This buffer 1148 * @throws BufferOverflowException If there are fewer than four bytes 1149 * remaining in this buffer 1150 * @throws ReadOnlyBufferException If this buffer is read-only 1151 */ putInt(int value)1152 public abstract ByteBuffer putInt(int value); 1153 1154 /** 1155 * Absolute <i>get</i> method for reading an int value. 1156 * 1157 * <p> Reads four bytes at the given index, composing them into a 1158 * int value according to the current byte order. </p> 1159 * 1160 * @param index The index from which the bytes will be read 1161 * @return The int value at the given index 1162 * @throws IndexOutOfBoundsException If <tt>index</tt> is negative 1163 * or not smaller than the buffer's limit, 1164 * minus three 1165 */ getInt(int index)1166 public abstract int getInt(int index); 1167 getIntUnchecked(int index)1168 int getIntUnchecked(int index) { 1169 throw new UnsupportedOperationException(); 1170 } 1171 getUnchecked(int pos, int[] dst, int dstOffset, int length)1172 void getUnchecked(int pos, int[] dst, int dstOffset, int length) { 1173 throw new UnsupportedOperationException(); 1174 } 1175 1176 /** 1177 * Absolute <i>put</i> method for writing an int 1178 * value <i>(optional operation)</i>. 1179 * 1180 * <p> Writes four bytes containing the given int value, in the 1181 * current byte order, into this buffer at the given index. </p> 1182 * 1183 * @param index The index at which the bytes will be written 1184 * @param value The int value to be written 1185 * @return This buffer 1186 * @throws IndexOutOfBoundsException If <tt>index</tt> is negative 1187 * or not smaller than the buffer's limit, 1188 * minus three 1189 * @throws ReadOnlyBufferException If this buffer is read-only 1190 */ putInt(int index, int value)1191 public abstract ByteBuffer putInt(int index, int value); 1192 putIntUnchecked(int index, int value)1193 void putIntUnchecked(int index, int value) { 1194 throw new UnsupportedOperationException(); 1195 } 1196 putUnchecked(int pos, int[] dst, int srcOffset, int length)1197 void putUnchecked(int pos, int[] dst, int srcOffset, int length) { 1198 throw new UnsupportedOperationException(); 1199 } 1200 1201 /** 1202 * Creates a view of this byte buffer as an int buffer. 1203 * 1204 * <p> The content of the new buffer will start at this buffer's current 1205 * position. Changes to this buffer's content will be visible in the new 1206 * buffer, and vice versa; the two buffers' position, limit, and mark 1207 * values will be independent. 1208 * 1209 * <p> The new buffer's position will be zero, its capacity and its limit 1210 * will be the number of bytes remaining in this buffer divided by 1211 * four, and its mark will be undefined. The new buffer will be direct 1212 * if, and only if, this buffer is direct, and it will be read-only if, and 1213 * only if, this buffer is read-only. </p> 1214 * 1215 * @return A new int buffer 1216 */ asIntBuffer()1217 public abstract IntBuffer asIntBuffer(); 1218 1219 1220 /** 1221 * Relative <i>get</i> method for reading a long value. 1222 * 1223 * <p> Reads the next eight bytes at this buffer's current position, 1224 * composing them into a long value according to the current byte order, 1225 * and then increments the position by eight. </p> 1226 * 1227 * @return The long value at the buffer's current position 1228 * @throws BufferUnderflowException If there are fewer than eight bytes 1229 * remaining in this buffer 1230 */ getLong()1231 public abstract long getLong(); 1232 1233 /** 1234 * Relative <i>put</i> method for writing a long 1235 * value <i>(optional operation)</i>. 1236 * 1237 * <p> Writes eight bytes containing the given long value, in the 1238 * current byte order, into this buffer at the current position, and then 1239 * increments the position by eight. </p> 1240 * 1241 * @param value The long value to be written 1242 * @return This buffer 1243 * @throws BufferOverflowException If there are fewer than eight bytes 1244 * remaining in this buffer 1245 * @throws ReadOnlyBufferException If this buffer is read-only 1246 */ putLong(long value)1247 public abstract ByteBuffer putLong(long value); 1248 1249 /** 1250 * Absolute <i>get</i> method for reading a long value. 1251 * 1252 * <p> Reads eight bytes at the given index, composing them into a 1253 * long value according to the current byte order. </p> 1254 * 1255 * @param index The index from which the bytes will be read 1256 * @return The long value at the given index 1257 * @throws IndexOutOfBoundsException If <tt>index</tt> is negative 1258 * or not smaller than the buffer's limit, 1259 * minus seven 1260 */ getLong(int index)1261 public abstract long getLong(int index); 1262 getLongUnchecked(int index)1263 long getLongUnchecked(int index) { 1264 throw new UnsupportedOperationException(); 1265 } 1266 getUnchecked(int pos, long[] dst, int dstOffset, int length)1267 void getUnchecked(int pos, long[] dst, int dstOffset, int length) { 1268 throw new UnsupportedOperationException(); 1269 } 1270 1271 /** 1272 * Absolute <i>put</i> method for writing a long 1273 * value <i>(optional operation)</i>. 1274 * 1275 * <p> Writes eight bytes containing the given long value, in the 1276 * current byte order, into this buffer at the given index. </p> 1277 * 1278 * @param index The index at which the bytes will be written 1279 * @param value The long value to be written 1280 * @return This buffer 1281 * @throws IndexOutOfBoundsException If <tt>index</tt> is negative 1282 * or not smaller than the buffer's limit, 1283 * minus seven 1284 * @throws ReadOnlyBufferException If this buffer is read-only 1285 */ putLong(int index, long value)1286 public abstract ByteBuffer putLong(int index, long value); 1287 putLongUnchecked(int index, long value)1288 void putLongUnchecked(int index, long value) { 1289 throw new UnsupportedOperationException(); 1290 } 1291 putUnchecked(int pos, long[] dst, int srcOffset, int length)1292 void putUnchecked(int pos, long[] dst, int srcOffset, int length) { 1293 throw new UnsupportedOperationException(); 1294 } 1295 1296 /** 1297 * Creates a view of this byte buffer as a long buffer. 1298 * 1299 * <p> The content of the new buffer will start at this buffer's current 1300 * position. Changes to this buffer's content will be visible in the new 1301 * buffer, and vice versa; the two buffers' position, limit, and mark 1302 * values will be independent. 1303 * 1304 * <p> The new buffer's position will be zero, its capacity and its limit 1305 * will be the number of bytes remaining in this buffer divided by 1306 * eight, and its mark will be undefined. The new buffer will be direct 1307 * if, and only if, this buffer is direct, and it will be read-only if, and 1308 * only if, this buffer is read-only. </p> 1309 * 1310 * @return A new long buffer 1311 */ asLongBuffer()1312 public abstract LongBuffer asLongBuffer(); 1313 1314 1315 /** 1316 * Relative <i>get</i> method for reading a float value. 1317 * 1318 * <p> Reads the next four bytes at this buffer's current position, 1319 * composing them into a float value according to the current byte order, 1320 * and then increments the position by four. </p> 1321 * 1322 * @return The float value at the buffer's current position 1323 * @throws BufferUnderflowException If there are fewer than four bytes 1324 * remaining in this buffer 1325 */ getFloat()1326 public abstract float getFloat(); 1327 1328 /** 1329 * Relative <i>put</i> method for writing a float 1330 * value <i>(optional operation)</i>. 1331 * 1332 * <p> Writes four bytes containing the given float value, in the 1333 * current byte order, into this buffer at the current position, and then 1334 * increments the position by four. </p> 1335 * 1336 * @param value The float value to be written 1337 * @return This buffer 1338 * @throws BufferOverflowException If there are fewer than four bytes 1339 * remaining in this buffer 1340 * @throws ReadOnlyBufferException If this buffer is read-only 1341 */ putFloat(float value)1342 public abstract ByteBuffer putFloat(float value); 1343 1344 /** 1345 * Absolute <i>get</i> method for reading a float value. 1346 * 1347 * <p> Reads four bytes at the given index, composing them into a 1348 * float value according to the current byte order. </p> 1349 * 1350 * @param index The index from which the bytes will be read 1351 * @return The float value at the given index 1352 * @throws IndexOutOfBoundsException If <tt>index</tt> is negative 1353 * or not smaller than the buffer's limit, 1354 * minus three 1355 */ getFloat(int index)1356 public abstract float getFloat(int index); 1357 getFloatUnchecked(int index)1358 float getFloatUnchecked(int index) { 1359 throw new UnsupportedOperationException(); 1360 } 1361 getUnchecked(int pos, float[] dst, int dstOffset, int length)1362 void getUnchecked(int pos, float[] dst, int dstOffset, int length) { 1363 throw new UnsupportedOperationException(); 1364 } 1365 1366 /** 1367 * Absolute <i>put</i> method for writing a float 1368 * value <i>(optional operation)</i>. 1369 * 1370 * <p> Writes four bytes containing the given float value, in the 1371 * current byte order, into this buffer at the given index. </p> 1372 * 1373 * @param index The index at which the bytes will be written 1374 * @param value The float value to be written 1375 * @return This buffer 1376 * @throws IndexOutOfBoundsException If <tt>index</tt> is negative 1377 * or not smaller than the buffer's limit, 1378 * minus three 1379 * @throws ReadOnlyBufferException If this buffer is read-only 1380 */ putFloat(int index, float value)1381 public abstract ByteBuffer putFloat(int index, float value); 1382 putFloatUnchecked(int index, float value)1383 void putFloatUnchecked(int index, float value) { 1384 throw new UnsupportedOperationException(); 1385 } 1386 putUnchecked(int pos, float[] dst, int srcOffset, int length)1387 void putUnchecked(int pos, float[] dst, int srcOffset, int length) { 1388 throw new UnsupportedOperationException(); 1389 } 1390 1391 /** 1392 * Creates a view of this byte buffer as a float buffer. 1393 * 1394 * <p> The content of the new buffer will start at this buffer's current 1395 * position. Changes to this buffer's content will be visible in the new 1396 * buffer, and vice versa; the two buffers' position, limit, and mark 1397 * values will be independent. 1398 * 1399 * <p> The new buffer's position will be zero, its capacity and its limit 1400 * will be the number of bytes remaining in this buffer divided by 1401 * four, and its mark will be undefined. The new buffer will be direct 1402 * if, and only if, this buffer is direct, and it will be read-only if, and 1403 * only if, this buffer is read-only. </p> 1404 * 1405 * @return A new float buffer 1406 */ asFloatBuffer()1407 public abstract FloatBuffer asFloatBuffer(); 1408 1409 1410 /** 1411 * Relative <i>get</i> method for reading a double value. 1412 * 1413 * <p> Reads the next eight bytes at this buffer's current position, 1414 * composing them into a double value according to the current byte order, 1415 * and then increments the position by eight. </p> 1416 * 1417 * @return The double value at the buffer's current position 1418 * @throws BufferUnderflowException If there are fewer than eight bytes 1419 * remaining in this buffer 1420 */ getDouble()1421 public abstract double getDouble(); 1422 1423 /** 1424 * Relative <i>put</i> method for writing a double 1425 * value <i>(optional operation)</i>. 1426 * 1427 * <p> Writes eight bytes containing the given double value, in the 1428 * current byte order, into this buffer at the current position, and then 1429 * increments the position by eight. </p> 1430 * 1431 * @param value The double value to be written 1432 * @return This buffer 1433 * @throws BufferOverflowException If there are fewer than eight bytes 1434 * remaining in this buffer 1435 * @throws ReadOnlyBufferException If this buffer is read-only 1436 */ putDouble(double value)1437 public abstract ByteBuffer putDouble(double value); 1438 1439 /** 1440 * Absolute <i>get</i> method for reading a double value. 1441 * 1442 * <p> Reads eight bytes at the given index, composing them into a 1443 * double value according to the current byte order. </p> 1444 * 1445 * @param index The index from which the bytes will be read 1446 * @return The double value at the given index 1447 * @throws IndexOutOfBoundsException If <tt>index</tt> is negative 1448 * or not smaller than the buffer's limit, 1449 * minus seven 1450 */ getDouble(int index)1451 public abstract double getDouble(int index); 1452 getDoubleUnchecked(int index)1453 double getDoubleUnchecked(int index) { 1454 throw new UnsupportedOperationException(); 1455 } 1456 getUnchecked(int pos, double[] dst, int dstOffset, int length)1457 void getUnchecked(int pos, double[] dst, int dstOffset, int length) { 1458 throw new UnsupportedOperationException(); 1459 } 1460 1461 /** 1462 * Absolute <i>put</i> method for writing a double 1463 * value <i>(optional operation)</i>. 1464 * 1465 * <p> Writes eight bytes containing the given double value, in the 1466 * current byte order, into this buffer at the given index. </p> 1467 * 1468 * @param index The index at which the bytes will be written 1469 * @param value The double value to be written 1470 * @return This buffer 1471 * @throws IndexOutOfBoundsException If <tt>index</tt> is negative 1472 * or not smaller than the buffer's limit, 1473 * minus seven 1474 * @throws ReadOnlyBufferException If this buffer is read-only 1475 */ putDouble(int index, double value)1476 public abstract ByteBuffer putDouble(int index, double value); 1477 putDoubleUnchecked(int index, double value)1478 void putDoubleUnchecked(int index, double value) { 1479 throw new UnsupportedOperationException(); 1480 } 1481 putUnchecked(int pos, double[] dst, int srcOffset, int length)1482 void putUnchecked(int pos, double[] dst, int srcOffset, int length) { 1483 throw new UnsupportedOperationException(); 1484 } 1485 1486 /** 1487 * Creates a view of this byte buffer as a double buffer. 1488 * 1489 * <p> The content of the new buffer will start at this buffer's current 1490 * position. Changes to this buffer's content will be visible in the new 1491 * buffer, and vice versa; the two buffers' position, limit, and mark 1492 * values will be independent. 1493 * 1494 * <p> The new buffer's position will be zero, its capacity and its limit 1495 * will be the number of bytes remaining in this buffer divided by 1496 * eight, and its mark will be undefined. The new buffer will be direct 1497 * if, and only if, this buffer is direct, and it will be read-only if, and 1498 * only if, this buffer is read-only. </p> 1499 * 1500 * @return A new double buffer 1501 */ asDoubleBuffer()1502 public abstract DoubleBuffer asDoubleBuffer(); 1503 1504 /** 1505 * @hide 1506 */ isAccessible()1507 public boolean isAccessible() { 1508 return true; 1509 } 1510 1511 /** 1512 * @hide 1513 */ setAccessible(boolean value)1514 public void setAccessible(boolean value) { 1515 throw new UnsupportedOperationException(); 1516 } 1517 } 1518