ByteBuffer.java revision fde0200e844b5c508b628da74a15eff193f31745
1/* 2 * Copyright (c) 2000, 2008, 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// -- This file was mechanically generated: Do not edit! -- // 27 28package java.nio; 29 30 31 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 55 * 56 * <li><p> Absolute and relative {@link #getChar() </code><i>get</i><code>} 57 * and {@link #putChar(char) </code><i>put</i><code>} methods that read and 58 * write values of other primitive types, translating them to and from 59 * sequences of bytes in a particular byte order; </p></li> 60 * 61 * <li><p> Methods for creating <i><a href="#views">view buffers</a></i>, 62 * which allow a byte buffer to be viewed as a buffer containing values of 63 * some other primitive type; and </p></li> 64 * 65 66 * 67 * <li><p> Methods for {@link #compact </code>compacting<code>}, {@link 68 * #duplicate </code>duplicating<code>}, and {@link #slice 69 * </code>slicing<code>} a byte buffer. </p></li> 70 * 71 * </ul> 72 * 73 * <p> Byte buffers can be created either by {@link #allocate 74 * </code><i>allocation</i><code>}, which allocates space for the buffer's 75 * 76 77 * 78 * content, or by {@link #wrap(byte[]) </code><i>wrapping</i><code>} an 79 * existing byte array into a buffer. 80 * 81 82 83 84 85 86 87 88 * 89 90 * 91 * <a name="direct"> 92 * <h4> Direct <i>vs.</i> non-direct buffers </h4> 93 * 94 * <p> A byte buffer is either <i>direct</i> or <i>non-direct</i>. Given a 95 * direct byte buffer, the Java virtual machine will make a best effort to 96 * perform native I/O operations directly upon it. That is, it will attempt to 97 * avoid copying the buffer's content to (or from) an intermediate buffer 98 * before (or after) each invocation of one of the underlying operating 99 * system's native I/O operations. 100 * 101 * <p> A direct byte buffer may be created by invoking the {@link 102 * #allocateDirect(int) allocateDirect} factory method of this class. The 103 * buffers returned by this method typically have somewhat higher allocation 104 * and deallocation costs than non-direct buffers. The contents of direct 105 * buffers may reside outside of the normal garbage-collected heap, and so 106 * their impact upon the memory footprint of an application might not be 107 * obvious. It is therefore recommended that direct buffers be allocated 108 * primarily for large, long-lived buffers that are subject to the underlying 109 * system's native I/O operations. In general it is best to allocate direct 110 * buffers only when they yield a measureable gain in program performance. 111 * 112 * <p> A direct byte buffer may also be created by {@link 113 * java.nio.channels.FileChannel#map </code>mapping<code>} a region of a file 114 * directly into memory. An implementation of the Java platform may optionally 115 * support the creation of direct byte buffers from native code via JNI. If an 116 * instance of one of these kinds of buffers refers to an inaccessible region 117 * of memory then an attempt to access that region will not change the buffer's 118 * content and will cause an unspecified exception to be thrown either at the 119 * time of the access or at some later time. 120 * 121 * <p> Whether a byte buffer is direct or non-direct may be determined by 122 * invoking its {@link #isDirect isDirect} method. This method is provided so 123 * that explicit buffer management can be done in performance-critical code. 124 * 125 * 126 * <a name="bin"> 127 * <h4> Access to binary data </h4> 128 * 129 * <p> This class defines methods for reading and writing values of all other 130 * primitive types, except <tt>boolean</tt>. Primitive values are translated 131 * to (or from) sequences of bytes according to the buffer's current byte 132 * order, which may be retrieved and modified via the {@link #order order} 133 * methods. Specific byte orders are represented by instances of the {@link 134 * ByteOrder} class. The initial order of a byte buffer is always {@link 135 * ByteOrder#BIG_ENDIAN BIG_ENDIAN}. 136 * 137 * <p> For access to heterogeneous binary data, that is, sequences of values of 138 * different types, this class defines a family of absolute and relative 139 * <i>get</i> and <i>put</i> methods for each type. For 32-bit floating-point 140 * values, for example, this class defines: 141 * 142 * <blockquote><pre> 143 * float {@link #getFloat()} 144 * float {@link #getFloat(int) getFloat(int index)} 145 * void {@link #putFloat(float) putFloat(float f)} 146 * void {@link #putFloat(int,float) putFloat(int index, float f)}</pre></blockquote> 147 * 148 * <p> Corresponding methods are defined for the types <tt>char</tt>, 149 * <tt>short</tt>, <tt>int</tt>, <tt>long</tt>, and <tt>double</tt>. The index 150 * parameters of the absolute <i>get</i> and <i>put</i> methods are in terms of 151 * bytes rather than of the type being read or written. 152 * 153 * <a name="views"> 154 * 155 * <p> For access to homogeneous binary data, that is, sequences of values of 156 * the same type, this class defines methods that can create <i>views</i> of a 157 * given byte buffer. A <i>view buffer</i> is simply another buffer whose 158 * content is backed by the byte buffer. Changes to the byte buffer's content 159 * will be visible in the view buffer, and vice versa; the two buffers' 160 * position, limit, and mark values are independent. The {@link 161 * #asFloatBuffer() asFloatBuffer} method, for example, creates an instance of 162 * the {@link FloatBuffer} class that is backed by the byte buffer upon which 163 * the method is invoked. Corresponding view-creation methods are defined for 164 * the types <tt>char</tt>, <tt>short</tt>, <tt>int</tt>, <tt>long</tt>, and 165 * <tt>double</tt>. 166 * 167 * <p> View buffers have three important advantages over the families of 168 * type-specific <i>get</i> and <i>put</i> methods described above: 169 * 170 * <ul> 171 * 172 * <li><p> A view buffer is indexed not in terms of bytes but rather in terms 173 * of the type-specific size of its values; </p></li> 174 * 175 * <li><p> A view buffer provides relative bulk <i>get</i> and <i>put</i> 176 * methods that can transfer contiguous sequences of values between a buffer 177 * and an array or some other buffer of the same type; and </p></li> 178 * 179 * <li><p> A view buffer is potentially much more efficient because it will 180 * be direct if, and only if, its backing byte buffer is direct. </p></li> 181 * 182 * </ul> 183 * 184 * <p> The byte order of a view buffer is fixed to be that of its byte buffer 185 * at the time that the view is created. </p> 186 * 187 188* 189 190 191 192 193 194 195 196 197 198 199 200* 201 202 203 204 205 206 207 208 209 * 210 211 * <h4> Invocation chaining </h4> 212 213 * 214 * <p> Methods in this class that do not otherwise have a value to return are 215 * specified to return the buffer upon which they are invoked. This allows 216 * method invocations to be chained. 217 * 218 219 * 220 * The sequence of statements 221 * 222 * <blockquote><pre> 223 * bb.putInt(0xCAFEBABE); 224 * bb.putShort(3); 225 * bb.putShort(45);</pre></blockquote> 226 * 227 * can, for example, be replaced by the single statement 228 * 229 * <blockquote><pre> 230 * bb.putInt(0xCAFEBABE).putShort(3).putShort(45);</pre></blockquote> 231 * 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 * 250 * 251 * @author Mark Reinhold 252 * @author JSR-51 Expert Group 253 * @since 1.4 254 */ 255 256public abstract class ByteBuffer 257 extends Buffer 258 implements Comparable<ByteBuffer> 259{ 260 261 // These fields are declared here rather than in Heap-X-Buffer in order to 262 // reduce the number of virtual method invocations needed to access these 263 // values, which is especially costly when coding small buffers. 264 // 265 final byte[] hb; // Non-null only for heap buffers 266 final int offset; 267 boolean isReadOnly; // Valid only for heap buffers 268 269 // Creates a new buffer with the given mark, position, limit, capacity, 270 // backing array, and array offset 271 // 272 ByteBuffer(int mark, int pos, int lim, int cap, // package-private 273 byte[] hb, int offset) 274 { 275 super(mark, pos, lim, cap, 0); 276 this.hb = hb; 277 this.offset = offset; 278 } 279 280 // Creates a new buffer with the given mark, position, limit, and capacity 281 // 282 ByteBuffer(int mark, int pos, int lim, int cap) { // package-private 283 this(mark, pos, lim, cap, null, 0); 284 } 285 286 287 /** 288 * Allocates a new direct byte buffer. 289 * 290 * <p> The new buffer's position will be zero, its limit will be its 291 * capacity, its mark will be undefined, and each of its elements will be 292 * initialized to zero. Whether or not it has a 293 * {@link #hasArray </code>backing array<code>} is unspecified. 294 * 295 * @param capacity 296 * The new buffer's capacity, in bytes 297 * 298 * @return The new byte buffer 299 * 300 * @throws IllegalArgumentException 301 * If the <tt>capacity</tt> is a negative integer 302 */ 303 public static ByteBuffer allocateDirect(int capacity) { 304 if (capacity < 0) { 305 throw new IllegalArgumentException("capacity < 0: " + capacity); 306 } 307 return new DirectByteBuffer(capacity); 308 } 309 310 311 312 /** 313 * Allocates a new byte buffer. 314 * 315 * <p> The new buffer's position will be zero, its limit will be its 316 * capacity, its mark will be undefined, and each of its elements will be 317 * initialized to zero. It will have a {@link #array 318 * </code>backing array<code>}, and its {@link #arrayOffset </code>array 319 * offset<code>} will be zero. 320 * 321 * @param capacity 322 * The new buffer's capacity, in bytes 323 * 324 * @return The new byte buffer 325 * 326 * @throws IllegalArgumentException 327 * If the <tt>capacity</tt> is a negative integer 328 */ 329 public static ByteBuffer allocate(int capacity) { 330 if (capacity < 0) 331 throw new IllegalArgumentException(); 332 return new HeapByteBuffer(capacity, capacity); 333 } 334 335 /** 336 * Wraps a byte array into a buffer. 337 * 338 * <p> The new buffer will be backed by the given byte array; 339 * that is, modifications to the buffer will cause the array to be modified 340 * and vice versa. The new buffer's capacity will be 341 * <tt>array.length</tt>, its position will be <tt>offset</tt>, its limit 342 * will be <tt>offset + length</tt>, and its mark will be undefined. Its 343 * {@link #array </code>backing array<code>} will be the given array, and 344 * its {@link #arrayOffset </code>array offset<code>} will be zero. </p> 345 * 346 * @param array 347 * The array that will back the new buffer 348 * 349 * @param offset 350 * The offset of the subarray to be used; must be non-negative and 351 * no larger than <tt>array.length</tt>. The new buffer's position 352 * will be set to this value. 353 * 354 * @param length 355 * The length of the subarray to be used; 356 * must be non-negative and no larger than 357 * <tt>array.length - offset</tt>. 358 * The new buffer's limit will be set to <tt>offset + length</tt>. 359 * 360 * @return The new byte buffer 361 * 362 * @throws IndexOutOfBoundsException 363 * If the preconditions on the <tt>offset</tt> and <tt>length</tt> 364 * parameters do not hold 365 */ 366 public static ByteBuffer wrap(byte[] array, 367 int offset, int length) 368 { 369 try { 370 return new HeapByteBuffer(array, offset, length); 371 } catch (IllegalArgumentException x) { 372 throw new IndexOutOfBoundsException(); 373 } 374 } 375 376 /** 377 * Wraps a byte array into a buffer. 378 * 379 * <p> The new buffer will be backed by the given byte array; 380 * that is, modifications to the buffer will cause the array to be modified 381 * and vice versa. The new buffer's capacity and limit will be 382 * <tt>array.length</tt>, its position will be zero, and its mark will be 383 * undefined. Its {@link #array </code>backing array<code>} will be the 384 * given array, and its {@link #arrayOffset </code>array offset<code>} will 385 * be zero. </p> 386 * 387 * @param array 388 * The array that will back this buffer 389 * 390 * @return The new byte buffer 391 */ 392 public static ByteBuffer wrap(byte[] array) { 393 return wrap(array, 0, array.length); 394 } 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 /** 490 * Creates a new byte buffer whose content is a shared subsequence of 491 * this buffer's content. 492 * 493 * <p> The content of the new buffer will start at this buffer's current 494 * position. Changes to this buffer's content will be visible in the new 495 * buffer, and vice versa; the two buffers' position, limit, and mark 496 * values will be independent. 497 * 498 * <p> The new buffer's position will be zero, its capacity and its limit 499 * will be the number of bytes remaining in this buffer, and its mark 500 * will be undefined. The new buffer will be direct if, and only if, this 501 * buffer is direct, and it will be read-only if, and only if, this buffer 502 * is read-only. </p> 503 * 504 * @return The new byte buffer 505 */ 506 public abstract ByteBuffer slice(); 507 508 /** 509 * Creates a new byte buffer that shares this buffer's content. 510 * 511 * <p> The content of the new buffer will be that of this buffer. Changes 512 * to this buffer's content will be visible in the new buffer, and vice 513 * versa; the two buffers' position, limit, and mark values will be 514 * independent. 515 * 516 * <p> The new buffer's capacity, limit, position, and mark values will be 517 * identical to those of this buffer. The new buffer will be direct if, 518 * and only if, this buffer is direct, and it will be read-only if, and 519 * only if, this buffer is read-only. </p> 520 * 521 * @return The new byte buffer 522 */ 523 public abstract ByteBuffer duplicate(); 524 525 /** 526 * Creates a new, read-only byte buffer that shares this buffer's 527 * content. 528 * 529 * <p> The content of the new buffer will be that of this buffer. Changes 530 * to this buffer's content will be visible in the new buffer; the new 531 * buffer itself, however, will be read-only and will not allow the shared 532 * content to be modified. The two buffers' position, limit, and mark 533 * values will be independent. 534 * 535 * <p> The new buffer's capacity, limit, position, and mark values will be 536 * identical to those of this buffer. 537 * 538 * <p> If this buffer is itself read-only then this method behaves in 539 * exactly the same way as the {@link #duplicate duplicate} method. </p> 540 * 541 * @return The new, read-only byte buffer 542 */ 543 public abstract ByteBuffer asReadOnlyBuffer(); 544 545 546 // -- Singleton get/put methods -- 547 548 /** 549 * Relative <i>get</i> method. Reads the byte at this buffer's 550 * current position, and then increments the position. </p> 551 * 552 * @return The byte at the buffer's current position 553 * 554 * @throws BufferUnderflowException 555 * If the buffer's current position is not smaller than its limit 556 */ 557 public abstract byte get(); 558 559 /** 560 * Relative <i>put</i> method <i>(optional operation)</i>. 561 * 562 * <p> Writes the given byte into this buffer at the current 563 * position, and then increments the position. </p> 564 * 565 * @param b 566 * The byte to be written 567 * 568 * @return This buffer 569 * 570 * @throws BufferOverflowException 571 * If this buffer's current position is not smaller than its limit 572 * 573 * @throws ReadOnlyBufferException 574 * If this buffer is read-only 575 */ 576 public abstract ByteBuffer put(byte b); 577 578 /** 579 * Absolute <i>get</i> method. Reads the byte at the given 580 * index. </p> 581 * 582 * @param index 583 * The index from which the byte will be read 584 * 585 * @return The byte at the given index 586 * 587 * @throws IndexOutOfBoundsException 588 * If <tt>index</tt> is negative 589 * or not smaller than the buffer's limit 590 */ 591 public abstract byte get(int index); 592 593 /** 594 * Absolute <i>put</i> method <i>(optional operation)</i>. 595 * 596 * <p> Writes the given byte into this buffer at the given 597 * index. </p> 598 * 599 * @param index 600 * The index at which the byte will be written 601 * 602 * @param b 603 * The byte value to be written 604 * 605 * @return This buffer 606 * 607 * @throws IndexOutOfBoundsException 608 * If <tt>index</tt> is negative 609 * or not smaller than the buffer's limit 610 * 611 * @throws ReadOnlyBufferException 612 * If this buffer is read-only 613 */ 614 public abstract ByteBuffer put(int index, byte b); 615 616 617 // -- Bulk get operations -- 618 619 /** 620 * Relative bulk <i>get</i> method. 621 * 622 * <p> This method transfers bytes from this buffer into the given 623 * destination array. If there are fewer bytes remaining in the 624 * buffer than are required to satisfy the request, that is, if 625 * <tt>length</tt> <tt>></tt> <tt>remaining()</tt>, then no 626 * bytes are transferred and a {@link BufferUnderflowException} is 627 * thrown. 628 * 629 * <p> Otherwise, this method copies <tt>length</tt> bytes from this 630 * buffer into the given array, starting at the current position of this 631 * buffer and at the given offset in the array. The position of this 632 * buffer is then incremented by <tt>length</tt>. 633 * 634 * <p> In other words, an invocation of this method of the form 635 * <tt>src.get(dst, off, len)</tt> has exactly the same effect as 636 * the loop 637 * 638 * <pre> 639 * for (int i = off; i < off + len; i++) 640 * dst[i] = src.get(); </pre> 641 * 642 * except that it first checks that there are sufficient bytes in 643 * this buffer and it is potentially much more efficient. </p> 644 * 645 * @param dst 646 * The array into which bytes are to be written 647 * 648 * @param offset 649 * The offset within the array of the first byte to be 650 * written; must be non-negative and no larger than 651 * <tt>dst.length</tt> 652 * 653 * @param length 654 * The maximum number of bytes to be written to the given 655 * array; must be non-negative and no larger than 656 * <tt>dst.length - offset</tt> 657 * 658 * @return This buffer 659 * 660 * @throws BufferUnderflowException 661 * If there are fewer than <tt>length</tt> bytes 662 * remaining in this buffer 663 * 664 * @throws IndexOutOfBoundsException 665 * If the preconditions on the <tt>offset</tt> and <tt>length</tt> 666 * parameters do not hold 667 */ 668 public ByteBuffer get(byte[] dst, int offset, int length) { 669 checkBounds(offset, length, dst.length); 670 if (length > remaining()) 671 throw new BufferUnderflowException(); 672 int end = offset + length; 673 for (int i = offset; i < end; i++) 674 dst[i] = get(); 675 return this; 676 } 677 678 /** 679 * Relative bulk <i>get</i> method. 680 * 681 * <p> This method transfers bytes from this buffer into the given 682 * destination array. An invocation of this method of the form 683 * <tt>src.get(a)</tt> behaves in exactly the same way as the invocation 684 * 685 * <pre> 686 * src.get(a, 0, a.length) </pre> 687 * 688 * @return This buffer 689 * 690 * @throws BufferUnderflowException 691 * If there are fewer than <tt>length</tt> bytes 692 * remaining in this buffer 693 */ 694 public ByteBuffer get(byte[] dst) { 695 return get(dst, 0, dst.length); 696 } 697 698 699 // -- Bulk put operations -- 700 701 /** 702 * Relative bulk <i>put</i> method <i>(optional operation)</i>. 703 * 704 * <p> This method transfers the bytes remaining in the given source 705 * buffer into this buffer. If there are more bytes remaining in the 706 * source buffer than in this buffer, that is, if 707 * <tt>src.remaining()</tt> <tt>></tt> <tt>remaining()</tt>, 708 * then no bytes are transferred and a {@link 709 * BufferOverflowException} is thrown. 710 * 711 * <p> Otherwise, this method copies 712 * <i>n</i> = <tt>src.remaining()</tt> bytes from the given 713 * buffer into this buffer, starting at each buffer's current position. 714 * The positions of both buffers are then incremented by <i>n</i>. 715 * 716 * <p> In other words, an invocation of this method of the form 717 * <tt>dst.put(src)</tt> has exactly the same effect as the loop 718 * 719 * <pre> 720 * while (src.hasRemaining()) 721 * dst.put(src.get()); </pre> 722 * 723 * except that it first checks that there is sufficient space in this 724 * buffer and it is potentially much more efficient. </p> 725 * 726 * @param src 727 * The source buffer from which bytes are to be read; 728 * must not be this buffer 729 * 730 * @return This buffer 731 * 732 * @throws BufferOverflowException 733 * If there is insufficient space in this buffer 734 * for the remaining bytes in the source buffer 735 * 736 * @throws IllegalArgumentException 737 * If the source buffer is this buffer 738 * 739 * @throws ReadOnlyBufferException 740 * If this buffer is read-only 741 */ 742 public ByteBuffer put(ByteBuffer src) { 743 if (src == this) 744 throw new IllegalArgumentException(); 745 int n = src.remaining(); 746 if (n > remaining()) 747 throw new BufferOverflowException(); 748 for (int i = 0; i < n; i++) 749 put(src.get()); 750 return this; 751 } 752 753 /** 754 * Relative bulk <i>put</i> method <i>(optional operation)</i>. 755 * 756 * <p> This method transfers bytes into this buffer from the given 757 * source array. If there are more bytes to be copied from the array 758 * than remain in this buffer, that is, if 759 * <tt>length</tt> <tt>></tt> <tt>remaining()</tt>, then no 760 * bytes are transferred and a {@link BufferOverflowException} is 761 * thrown. 762 * 763 * <p> Otherwise, this method copies <tt>length</tt> bytes from the 764 * given array into this buffer, starting at the given offset in the array 765 * and at the current position of this buffer. The position of this buffer 766 * is then incremented by <tt>length</tt>. 767 * 768 * <p> In other words, an invocation of this method of the form 769 * <tt>dst.put(src, off, len)</tt> has exactly the same effect as 770 * the loop 771 * 772 * <pre> 773 * for (int i = off; i < off + len; i++) 774 * dst.put(a[i]); </pre> 775 * 776 * except that it first checks that there is sufficient space in this 777 * buffer and it is potentially much more efficient. </p> 778 * 779 * @param src 780 * The array from which bytes are to be read 781 * 782 * @param offset 783 * The offset within the array of the first byte to be read; 784 * must be non-negative and no larger than <tt>array.length</tt> 785 * 786 * @param length 787 * The number of bytes to be read from the given array; 788 * must be non-negative and no larger than 789 * <tt>array.length - offset</tt> 790 * 791 * @return This buffer 792 * 793 * @throws BufferOverflowException 794 * If there is insufficient space in this buffer 795 * 796 * @throws IndexOutOfBoundsException 797 * If the preconditions on the <tt>offset</tt> and <tt>length</tt> 798 * parameters do not hold 799 * 800 * @throws ReadOnlyBufferException 801 * If this buffer is read-only 802 */ 803 public ByteBuffer put(byte[] src, int offset, int length) { 804 checkBounds(offset, length, src.length); 805 if (length > remaining()) 806 throw new BufferOverflowException(); 807 int end = offset + length; 808 for (int i = offset; i < end; i++) 809 this.put(src[i]); 810 return this; 811 } 812 813 /** 814 * Relative bulk <i>put</i> method <i>(optional operation)</i>. 815 * 816 * <p> This method transfers the entire content of the given source 817 * byte array into this buffer. An invocation of this method of the 818 * form <tt>dst.put(a)</tt> behaves in exactly the same way as the 819 * invocation 820 * 821 * <pre> 822 * dst.put(a, 0, a.length) </pre> 823 * 824 * @return This buffer 825 * 826 * @throws BufferOverflowException 827 * If there is insufficient space in this buffer 828 * 829 * @throws ReadOnlyBufferException 830 * If this buffer is read-only 831 */ 832 public final ByteBuffer put(byte[] src) { 833 return put(src, 0, src.length); 834 } 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 // -- Other stuff -- 923 924 /** 925 * Tells whether or not this buffer is backed by an accessible byte 926 * array. 927 * 928 * <p> If this method returns <tt>true</tt> then the {@link #array() array} 929 * and {@link #arrayOffset() arrayOffset} methods may safely be invoked. 930 * </p> 931 * 932 * @return <tt>true</tt> if, and only if, this buffer 933 * is backed by an array and is not read-only 934 */ 935 public final boolean hasArray() { 936 return (hb != null) && !isReadOnly; 937 } 938 939 /** 940 * Returns the byte array that backs this 941 * buffer <i>(optional operation)</i>. 942 * 943 * <p> Modifications to this buffer's content will cause the returned 944 * array's content to be modified, and vice versa. 945 * 946 * <p> Invoke the {@link #hasArray hasArray} method before invoking this 947 * method in order to ensure that this buffer has an accessible backing 948 * array. </p> 949 * 950 * @return The array that backs this buffer 951 * 952 * @throws ReadOnlyBufferException 953 * If this buffer is backed by an array but is read-only 954 * 955 * @throws UnsupportedOperationException 956 * If this buffer is not backed by an accessible array 957 */ 958 public final byte[] array() { 959 if (hb == null) 960 throw new UnsupportedOperationException(); 961 if (isReadOnly) 962 throw new ReadOnlyBufferException(); 963 return hb; 964 } 965 966 /** 967 * Returns the offset within this buffer's backing array of the first 968 * element of the buffer <i>(optional operation)</i>. 969 * 970 * <p> If this buffer is backed by an array then buffer position <i>p</i> 971 * corresponds to array index <i>p</i> + <tt>arrayOffset()</tt>. 972 * 973 * <p> Invoke the {@link #hasArray hasArray} method before invoking this 974 * method in order to ensure that this buffer has an accessible backing 975 * array. </p> 976 * 977 * @return The offset within this buffer's array 978 * of the first element of the buffer 979 * 980 * @throws ReadOnlyBufferException 981 * If this buffer is backed by an array but is read-only 982 * 983 * @throws UnsupportedOperationException 984 * If this buffer is not backed by an accessible array 985 */ 986 public final int arrayOffset() { 987 if (hb == null) 988 throw new UnsupportedOperationException(); 989 if (isReadOnly) 990 throw new ReadOnlyBufferException(); 991 return offset; 992 } 993 994 /** 995 * Compacts this buffer <i>(optional operation)</i>. 996 * 997 * <p> The bytes between the buffer's current position and its limit, 998 * if any, are copied to the beginning of the buffer. That is, the 999 * byte at index <i>p</i> = <tt>position()</tt> is copied 1000 * to index zero, the byte at index <i>p</i> + 1 is copied 1001 * to index one, and so forth until the byte at index 1002 * <tt>limit()</tt> - 1 is copied to index 1003 * <i>n</i> = <tt>limit()</tt> - <tt>1</tt> - <i>p</i>. 1004 * The buffer's position is then set to <i>n+1</i> and its limit is set to 1005 * its capacity. The mark, if defined, is discarded. 1006 * 1007 * <p> The buffer's position is set to the number of bytes copied, 1008 * rather than to zero, so that an invocation of this method can be 1009 * followed immediately by an invocation of another relative <i>put</i> 1010 * method. </p> 1011 * 1012 1013 * 1014 * <p> Invoke this method after writing data from a buffer in case the 1015 * write was incomplete. The following loop, for example, copies bytes 1016 * from one channel to another via the buffer <tt>buf</tt>: 1017 * 1018 * <blockquote><pre> 1019 * buf.clear(); // Prepare buffer for use 1020 * while (in.read(buf) >= 0 || buf.position != 0) { 1021 * buf.flip(); 1022 * out.write(buf); 1023 * buf.compact(); // In case of partial write 1024 * }</pre></blockquote> 1025 * 1026 1027 * 1028 * @return This buffer 1029 * 1030 * @throws ReadOnlyBufferException 1031 * If this buffer is read-only 1032 */ 1033 public abstract ByteBuffer compact(); 1034 1035 /** 1036 * Tells whether or not this byte buffer is direct. </p> 1037 * 1038 * @return <tt>true</tt> if, and only if, this buffer is direct 1039 */ 1040 public abstract boolean isDirect(); 1041 1042 1043 1044 /** 1045 * Returns a string summarizing the state of this buffer. </p> 1046 * 1047 * @return A summary string 1048 */ 1049 public String toString() { 1050 StringBuffer sb = new StringBuffer(); 1051 sb.append(getClass().getName()); 1052 sb.append("[pos="); 1053 sb.append(position()); 1054 sb.append(" lim="); 1055 sb.append(limit()); 1056 sb.append(" cap="); 1057 sb.append(capacity()); 1058 sb.append("]"); 1059 return sb.toString(); 1060 } 1061 1062 1063 1064 1065 1066 1067 /** 1068 * Returns the current hash code of this buffer. 1069 * 1070 * <p> The hash code of a byte buffer depends only upon its remaining 1071 * elements; that is, upon the elements from <tt>position()</tt> up to, and 1072 * including, the element at <tt>limit()</tt> - <tt>1</tt>. 1073 * 1074 * <p> Because buffer hash codes are content-dependent, it is inadvisable 1075 * to use buffers as keys in hash maps or similar data structures unless it 1076 * is known that their contents will not change. </p> 1077 * 1078 * @return The current hash code of this buffer 1079 */ 1080 public int hashCode() { 1081 int h = 1; 1082 int p = position(); 1083 for (int i = limit() - 1; i >= p; i--) 1084 h = 31 * h + (int)get(i); 1085 return h; 1086 } 1087 1088 /** 1089 * Tells whether or not this buffer is equal to another object. 1090 * 1091 * <p> Two byte buffers are equal if, and only if, 1092 * 1093 * <p><ol> 1094 * 1095 * <li><p> They have the same element type, </p></li> 1096 * 1097 * <li><p> They have the same number of remaining elements, and 1098 * </p></li> 1099 * 1100 * <li><p> The two sequences of remaining elements, considered 1101 * independently of their starting positions, are pointwise equal. 1102 1103 1104 1105 1106 1107 1108 1109 * </p></li> 1110 * 1111 * </ol> 1112 * 1113 * <p> A byte buffer is not equal to any other type of object. </p> 1114 * 1115 * @param ob The object to which this buffer is to be compared 1116 * 1117 * @return <tt>true</tt> if, and only if, this buffer is equal to the 1118 * given object 1119 */ 1120 public boolean equals(Object ob) { 1121 if (this == ob) 1122 return true; 1123 if (!(ob instanceof ByteBuffer)) 1124 return false; 1125 ByteBuffer that = (ByteBuffer)ob; 1126 if (this.remaining() != that.remaining()) 1127 return false; 1128 int p = this.position(); 1129 for (int i = this.limit() - 1, j = that.limit() - 1; i >= p; i--, j--) 1130 if (!equals(this.get(i), that.get(j))) 1131 return false; 1132 return true; 1133 } 1134 1135 private static boolean equals(byte x, byte y) { 1136 1137 1138 1139 return x == y; 1140 1141 } 1142 1143 /** 1144 * Compares this buffer to another. 1145 * 1146 * <p> Two byte buffers are compared by comparing their sequences of 1147 * remaining elements lexicographically, without regard to the starting 1148 * position of each sequence within its corresponding buffer. 1149 1150 1151 1152 1153 1154 1155 1156 1157 * Pairs of {@code byte} elements are compared as if by invoking 1158 * {@link Byte#compare(byte,byte)}. 1159 1160 * 1161 * <p> A byte buffer is not comparable to any other type of object. 1162 * 1163 * @return A negative integer, zero, or a positive integer as this buffer 1164 * is less than, equal to, or greater than the given buffer 1165 */ 1166 public int compareTo(ByteBuffer that) { 1167 int n = this.position() + Math.min(this.remaining(), that.remaining()); 1168 for (int i = this.position(), j = that.position(); i < n; i++, j++) { 1169 int cmp = compare(this.get(i), that.get(j)); 1170 if (cmp != 0) 1171 return cmp; 1172 } 1173 return this.remaining() - that.remaining(); 1174 } 1175 1176 private static int compare(byte x, byte y) { 1177 1178 1179 1180 1181 1182 1183 return Byte.compare(x, y); 1184 1185 } 1186 1187 // -- Other char stuff -- 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 // -- Other byte stuff: Access to binary data -- 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 boolean bigEndian // package-private 1405 = true; 1406 boolean nativeByteOrder // package-private 1407 = (Bits.byteOrder() == ByteOrder.BIG_ENDIAN); 1408 1409 /** 1410 * Retrieves this buffer's byte order. 1411 * 1412 * <p> The byte order is used when reading or writing multibyte values, and 1413 * when creating buffers that are views of this byte buffer. The order of 1414 * a newly-created byte buffer is always {@link ByteOrder#BIG_ENDIAN 1415 * BIG_ENDIAN}. </p> 1416 * 1417 * @return This buffer's byte order 1418 */ 1419 public final ByteOrder order() { 1420 return bigEndian ? ByteOrder.BIG_ENDIAN : ByteOrder.LITTLE_ENDIAN; 1421 } 1422 1423 /** 1424 * Modifies this buffer's byte order. </p> 1425 * 1426 * @param bo 1427 * The new byte order, 1428 * either {@link ByteOrder#BIG_ENDIAN BIG_ENDIAN} 1429 * or {@link ByteOrder#LITTLE_ENDIAN LITTLE_ENDIAN} 1430 * 1431 * @return This buffer 1432 */ 1433 public final ByteBuffer order(ByteOrder bo) { 1434 bigEndian = (bo == ByteOrder.BIG_ENDIAN); 1435 nativeByteOrder = 1436 (bigEndian == (Bits.byteOrder() == ByteOrder.BIG_ENDIAN)); 1437 return this; 1438 } 1439 1440 // Unchecked accessors, for use by ByteBufferAs-X-Buffer classes 1441 // 1442 abstract byte _get(int i); // package-private 1443 abstract void _put(int i, byte b); // package-private 1444 1445 1446 /** 1447 * Relative <i>get</i> method for reading a char value. 1448 * 1449 * <p> Reads the next two bytes at this buffer's current position, 1450 * composing them into a char value according to the current byte order, 1451 * and then increments the position by two. </p> 1452 * 1453 * @return The char value at the buffer's current position 1454 * 1455 * @throws BufferUnderflowException 1456 * If there are fewer than two bytes 1457 * remaining in this buffer 1458 */ 1459 public abstract char getChar(); 1460 1461 /** 1462 * Relative <i>put</i> method for writing a char 1463 * value <i>(optional operation)</i>. 1464 * 1465 * <p> Writes two bytes containing the given char value, in the 1466 * current byte order, into this buffer at the current position, and then 1467 * increments the position by two. </p> 1468 * 1469 * @param value 1470 * The char value to be written 1471 * 1472 * @return This buffer 1473 * 1474 * @throws BufferOverflowException 1475 * If there are fewer than two bytes 1476 * remaining in this buffer 1477 * 1478 * @throws ReadOnlyBufferException 1479 * If this buffer is read-only 1480 */ 1481 public abstract ByteBuffer putChar(char value); 1482 1483 /** 1484 * Absolute <i>get</i> method for reading a char value. 1485 * 1486 * <p> Reads two bytes at the given index, composing them into a 1487 * char value according to the current byte order. </p> 1488 * 1489 * @param index 1490 * The index from which the bytes will be read 1491 * 1492 * @return The char value at the given index 1493 * 1494 * @throws IndexOutOfBoundsException 1495 * If <tt>index</tt> is negative 1496 * or not smaller than the buffer's limit, 1497 * minus one 1498 */ 1499 public abstract char getChar(int index); 1500 1501 /** 1502 * Absolute <i>put</i> method for writing a char 1503 * value <i>(optional operation)</i>. 1504 * 1505 * <p> Writes two bytes containing the given char value, in the 1506 * current byte order, into this buffer at the given index. </p> 1507 * 1508 * @param index 1509 * The index at which the bytes will be written 1510 * 1511 * @param value 1512 * The char value to be written 1513 * 1514 * @return This buffer 1515 * 1516 * @throws IndexOutOfBoundsException 1517 * If <tt>index</tt> is negative 1518 * or not smaller than the buffer's limit, 1519 * minus one 1520 * 1521 * @throws ReadOnlyBufferException 1522 * If this buffer is read-only 1523 */ 1524 public abstract ByteBuffer putChar(int index, char value); 1525 1526 /** 1527 * Creates a view of this byte buffer as a char buffer. 1528 * 1529 * <p> The content of the new buffer will start at this buffer's current 1530 * position. Changes to this buffer's content will be visible in the new 1531 * buffer, and vice versa; the two buffers' position, limit, and mark 1532 * values will be independent. 1533 * 1534 * <p> The new buffer's position will be zero, its capacity and its limit 1535 * will be the number of bytes remaining in this buffer divided by 1536 * two, and its mark will be undefined. The new buffer will be direct 1537 * if, and only if, this buffer is direct, and it will be read-only if, and 1538 * only if, this buffer is read-only. </p> 1539 * 1540 * @return A new char buffer 1541 */ 1542 public abstract CharBuffer asCharBuffer(); 1543 1544 1545 /** 1546 * Relative <i>get</i> method for reading a short value. 1547 * 1548 * <p> Reads the next two bytes at this buffer's current position, 1549 * composing them into a short value according to the current byte order, 1550 * and then increments the position by two. </p> 1551 * 1552 * @return The short value at the buffer's current position 1553 * 1554 * @throws BufferUnderflowException 1555 * If there are fewer than two bytes 1556 * remaining in this buffer 1557 */ 1558 public abstract short getShort(); 1559 1560 /** 1561 * Relative <i>put</i> method for writing a short 1562 * value <i>(optional operation)</i>. 1563 * 1564 * <p> Writes two bytes containing the given short value, in the 1565 * current byte order, into this buffer at the current position, and then 1566 * increments the position by two. </p> 1567 * 1568 * @param value 1569 * The short value to be written 1570 * 1571 * @return This buffer 1572 * 1573 * @throws BufferOverflowException 1574 * If there are fewer than two bytes 1575 * remaining in this buffer 1576 * 1577 * @throws ReadOnlyBufferException 1578 * If this buffer is read-only 1579 */ 1580 public abstract ByteBuffer putShort(short value); 1581 1582 /** 1583 * Absolute <i>get</i> method for reading a short value. 1584 * 1585 * <p> Reads two bytes at the given index, composing them into a 1586 * short value according to the current byte order. </p> 1587 * 1588 * @param index 1589 * The index from which the bytes will be read 1590 * 1591 * @return The short value at the given index 1592 * 1593 * @throws IndexOutOfBoundsException 1594 * If <tt>index</tt> is negative 1595 * or not smaller than the buffer's limit, 1596 * minus one 1597 */ 1598 public abstract short getShort(int index); 1599 1600 /** 1601 * Absolute <i>put</i> method for writing a short 1602 * value <i>(optional operation)</i>. 1603 * 1604 * <p> Writes two bytes containing the given short value, in the 1605 * current byte order, into this buffer at the given index. </p> 1606 * 1607 * @param index 1608 * The index at which the bytes will be written 1609 * 1610 * @param value 1611 * The short value to be written 1612 * 1613 * @return This buffer 1614 * 1615 * @throws IndexOutOfBoundsException 1616 * If <tt>index</tt> is negative 1617 * or not smaller than the buffer's limit, 1618 * minus one 1619 * 1620 * @throws ReadOnlyBufferException 1621 * If this buffer is read-only 1622 */ 1623 public abstract ByteBuffer putShort(int index, short value); 1624 1625 /** 1626 * Creates a view of this byte buffer as a short buffer. 1627 * 1628 * <p> The content of the new buffer will start at this buffer's current 1629 * position. Changes to this buffer's content will be visible in the new 1630 * buffer, and vice versa; the two buffers' position, limit, and mark 1631 * values will be independent. 1632 * 1633 * <p> The new buffer's position will be zero, its capacity and its limit 1634 * will be the number of bytes remaining in this buffer divided by 1635 * two, and its mark will be undefined. The new buffer will be direct 1636 * if, and only if, this buffer is direct, and it will be read-only if, and 1637 * only if, this buffer is read-only. </p> 1638 * 1639 * @return A new short buffer 1640 */ 1641 public abstract ShortBuffer asShortBuffer(); 1642 1643 1644 /** 1645 * Relative <i>get</i> method for reading an int value. 1646 * 1647 * <p> Reads the next four bytes at this buffer's current position, 1648 * composing them into an int value according to the current byte order, 1649 * and then increments the position by four. </p> 1650 * 1651 * @return The int value at the buffer's current position 1652 * 1653 * @throws BufferUnderflowException 1654 * If there are fewer than four bytes 1655 * remaining in this buffer 1656 */ 1657 public abstract int getInt(); 1658 1659 /** 1660 * Relative <i>put</i> method for writing an int 1661 * value <i>(optional operation)</i>. 1662 * 1663 * <p> Writes four bytes containing the given int value, in the 1664 * current byte order, into this buffer at the current position, and then 1665 * increments the position by four. </p> 1666 * 1667 * @param value 1668 * The int value to be written 1669 * 1670 * @return This buffer 1671 * 1672 * @throws BufferOverflowException 1673 * If there are fewer than four bytes 1674 * remaining in this buffer 1675 * 1676 * @throws ReadOnlyBufferException 1677 * If this buffer is read-only 1678 */ 1679 public abstract ByteBuffer putInt(int value); 1680 1681 /** 1682 * Absolute <i>get</i> method for reading an int value. 1683 * 1684 * <p> Reads four bytes at the given index, composing them into a 1685 * int value according to the current byte order. </p> 1686 * 1687 * @param index 1688 * The index from which the bytes will be read 1689 * 1690 * @return The int value at the given index 1691 * 1692 * @throws IndexOutOfBoundsException 1693 * If <tt>index</tt> is negative 1694 * or not smaller than the buffer's limit, 1695 * minus three 1696 */ 1697 public abstract int getInt(int index); 1698 1699 /** 1700 * Absolute <i>put</i> method for writing an int 1701 * value <i>(optional operation)</i>. 1702 * 1703 * <p> Writes four bytes containing the given int value, in the 1704 * current byte order, into this buffer at the given index. </p> 1705 * 1706 * @param index 1707 * The index at which the bytes will be written 1708 * 1709 * @param value 1710 * The int value to be written 1711 * 1712 * @return This buffer 1713 * 1714 * @throws IndexOutOfBoundsException 1715 * If <tt>index</tt> is negative 1716 * or not smaller than the buffer's limit, 1717 * minus three 1718 * 1719 * @throws ReadOnlyBufferException 1720 * If this buffer is read-only 1721 */ 1722 public abstract ByteBuffer putInt(int index, int value); 1723 1724 /** 1725 * Creates a view of this byte buffer as an int buffer. 1726 * 1727 * <p> The content of the new buffer will start at this buffer's current 1728 * position. Changes to this buffer's content will be visible in the new 1729 * buffer, and vice versa; the two buffers' position, limit, and mark 1730 * values will be independent. 1731 * 1732 * <p> The new buffer's position will be zero, its capacity and its limit 1733 * will be the number of bytes remaining in this buffer divided by 1734 * four, and its mark will be undefined. The new buffer will be direct 1735 * if, and only if, this buffer is direct, and it will be read-only if, and 1736 * only if, this buffer is read-only. </p> 1737 * 1738 * @return A new int buffer 1739 */ 1740 public abstract IntBuffer asIntBuffer(); 1741 1742 1743 /** 1744 * Relative <i>get</i> method for reading a long value. 1745 * 1746 * <p> Reads the next eight bytes at this buffer's current position, 1747 * composing them into a long value according to the current byte order, 1748 * and then increments the position by eight. </p> 1749 * 1750 * @return The long value at the buffer's current position 1751 * 1752 * @throws BufferUnderflowException 1753 * If there are fewer than eight bytes 1754 * remaining in this buffer 1755 */ 1756 public abstract long getLong(); 1757 1758 /** 1759 * Relative <i>put</i> method for writing a long 1760 * value <i>(optional operation)</i>. 1761 * 1762 * <p> Writes eight bytes containing the given long value, in the 1763 * current byte order, into this buffer at the current position, and then 1764 * increments the position by eight. </p> 1765 * 1766 * @param value 1767 * The long value to be written 1768 * 1769 * @return This buffer 1770 * 1771 * @throws BufferOverflowException 1772 * If there are fewer than eight bytes 1773 * remaining in this buffer 1774 * 1775 * @throws ReadOnlyBufferException 1776 * If this buffer is read-only 1777 */ 1778 public abstract ByteBuffer putLong(long value); 1779 1780 /** 1781 * Absolute <i>get</i> method for reading a long value. 1782 * 1783 * <p> Reads eight bytes at the given index, composing them into a 1784 * long value according to the current byte order. </p> 1785 * 1786 * @param index 1787 * The index from which the bytes will be read 1788 * 1789 * @return The long value at the given index 1790 * 1791 * @throws IndexOutOfBoundsException 1792 * If <tt>index</tt> is negative 1793 * or not smaller than the buffer's limit, 1794 * minus seven 1795 */ 1796 public abstract long getLong(int index); 1797 1798 /** 1799 * Absolute <i>put</i> method for writing a long 1800 * value <i>(optional operation)</i>. 1801 * 1802 * <p> Writes eight bytes containing the given long value, in the 1803 * current byte order, into this buffer at the given index. </p> 1804 * 1805 * @param index 1806 * The index at which the bytes will be written 1807 * 1808 * @param value 1809 * The long value to be written 1810 * 1811 * @return This buffer 1812 * 1813 * @throws IndexOutOfBoundsException 1814 * If <tt>index</tt> is negative 1815 * or not smaller than the buffer's limit, 1816 * minus seven 1817 * 1818 * @throws ReadOnlyBufferException 1819 * If this buffer is read-only 1820 */ 1821 public abstract ByteBuffer putLong(int index, long value); 1822 1823 /** 1824 * Creates a view of this byte buffer as a long buffer. 1825 * 1826 * <p> The content of the new buffer will start at this buffer's current 1827 * position. Changes to this buffer's content will be visible in the new 1828 * buffer, and vice versa; the two buffers' position, limit, and mark 1829 * values will be independent. 1830 * 1831 * <p> The new buffer's position will be zero, its capacity and its limit 1832 * will be the number of bytes remaining in this buffer divided by 1833 * eight, and its mark will be undefined. The new buffer will be direct 1834 * if, and only if, this buffer is direct, and it will be read-only if, and 1835 * only if, this buffer is read-only. </p> 1836 * 1837 * @return A new long buffer 1838 */ 1839 public abstract LongBuffer asLongBuffer(); 1840 1841 1842 /** 1843 * Relative <i>get</i> method for reading a float value. 1844 * 1845 * <p> Reads the next four bytes at this buffer's current position, 1846 * composing them into a float value according to the current byte order, 1847 * and then increments the position by four. </p> 1848 * 1849 * @return The float value at the buffer's current position 1850 * 1851 * @throws BufferUnderflowException 1852 * If there are fewer than four bytes 1853 * remaining in this buffer 1854 */ 1855 public abstract float getFloat(); 1856 1857 /** 1858 * Relative <i>put</i> method for writing a float 1859 * value <i>(optional operation)</i>. 1860 * 1861 * <p> Writes four bytes containing the given float value, in the 1862 * current byte order, into this buffer at the current position, and then 1863 * increments the position by four. </p> 1864 * 1865 * @param value 1866 * The float value to be written 1867 * 1868 * @return This buffer 1869 * 1870 * @throws BufferOverflowException 1871 * If there are fewer than four bytes 1872 * remaining in this buffer 1873 * 1874 * @throws ReadOnlyBufferException 1875 * If this buffer is read-only 1876 */ 1877 public abstract ByteBuffer putFloat(float value); 1878 1879 /** 1880 * Absolute <i>get</i> method for reading a float value. 1881 * 1882 * <p> Reads four bytes at the given index, composing them into a 1883 * float value according to the current byte order. </p> 1884 * 1885 * @param index 1886 * The index from which the bytes will be read 1887 * 1888 * @return The float value at the given index 1889 * 1890 * @throws IndexOutOfBoundsException 1891 * If <tt>index</tt> is negative 1892 * or not smaller than the buffer's limit, 1893 * minus three 1894 */ 1895 public abstract float getFloat(int index); 1896 1897 /** 1898 * Absolute <i>put</i> method for writing a float 1899 * value <i>(optional operation)</i>. 1900 * 1901 * <p> Writes four bytes containing the given float value, in the 1902 * current byte order, into this buffer at the given index. </p> 1903 * 1904 * @param index 1905 * The index at which the bytes will be written 1906 * 1907 * @param value 1908 * The float value to be written 1909 * 1910 * @return This buffer 1911 * 1912 * @throws IndexOutOfBoundsException 1913 * If <tt>index</tt> is negative 1914 * or not smaller than the buffer's limit, 1915 * minus three 1916 * 1917 * @throws ReadOnlyBufferException 1918 * If this buffer is read-only 1919 */ 1920 public abstract ByteBuffer putFloat(int index, float value); 1921 1922 /** 1923 * Creates a view of this byte buffer as a float buffer. 1924 * 1925 * <p> The content of the new buffer will start at this buffer's current 1926 * position. Changes to this buffer's content will be visible in the new 1927 * buffer, and vice versa; the two buffers' position, limit, and mark 1928 * values will be independent. 1929 * 1930 * <p> The new buffer's position will be zero, its capacity and its limit 1931 * will be the number of bytes remaining in this buffer divided by 1932 * four, and its mark will be undefined. The new buffer will be direct 1933 * if, and only if, this buffer is direct, and it will be read-only if, and 1934 * only if, this buffer is read-only. </p> 1935 * 1936 * @return A new float buffer 1937 */ 1938 public abstract FloatBuffer asFloatBuffer(); 1939 1940 1941 /** 1942 * Relative <i>get</i> method for reading a double value. 1943 * 1944 * <p> Reads the next eight bytes at this buffer's current position, 1945 * composing them into a double value according to the current byte order, 1946 * and then increments the position by eight. </p> 1947 * 1948 * @return The double value at the buffer's current position 1949 * 1950 * @throws BufferUnderflowException 1951 * If there are fewer than eight bytes 1952 * remaining in this buffer 1953 */ 1954 public abstract double getDouble(); 1955 1956 /** 1957 * Relative <i>put</i> method for writing a double 1958 * value <i>(optional operation)</i>. 1959 * 1960 * <p> Writes eight bytes containing the given double value, in the 1961 * current byte order, into this buffer at the current position, and then 1962 * increments the position by eight. </p> 1963 * 1964 * @param value 1965 * The double value to be written 1966 * 1967 * @return This buffer 1968 * 1969 * @throws BufferOverflowException 1970 * If there are fewer than eight bytes 1971 * remaining in this buffer 1972 * 1973 * @throws ReadOnlyBufferException 1974 * If this buffer is read-only 1975 */ 1976 public abstract ByteBuffer putDouble(double value); 1977 1978 /** 1979 * Absolute <i>get</i> method for reading a double value. 1980 * 1981 * <p> Reads eight bytes at the given index, composing them into a 1982 * double value according to the current byte order. </p> 1983 * 1984 * @param index 1985 * The index from which the bytes will be read 1986 * 1987 * @return The double value at the given index 1988 * 1989 * @throws IndexOutOfBoundsException 1990 * If <tt>index</tt> is negative 1991 * or not smaller than the buffer's limit, 1992 * minus seven 1993 */ 1994 public abstract double getDouble(int index); 1995 1996 /** 1997 * Absolute <i>put</i> method for writing a double 1998 * value <i>(optional operation)</i>. 1999 * 2000 * <p> Writes eight bytes containing the given double value, in the 2001 * current byte order, into this buffer at the given index. </p> 2002 * 2003 * @param index 2004 * The index at which the bytes will be written 2005 * 2006 * @param value 2007 * The double value to be written 2008 * 2009 * @return This buffer 2010 * 2011 * @throws IndexOutOfBoundsException 2012 * If <tt>index</tt> is negative 2013 * or not smaller than the buffer's limit, 2014 * minus seven 2015 * 2016 * @throws ReadOnlyBufferException 2017 * If this buffer is read-only 2018 */ 2019 public abstract ByteBuffer putDouble(int index, double value); 2020 2021 /** 2022 * Creates a view of this byte buffer as a double buffer. 2023 * 2024 * <p> The content of the new buffer will start at this buffer's current 2025 * position. Changes to this buffer's content will be visible in the new 2026 * buffer, and vice versa; the two buffers' position, limit, and mark 2027 * values will be independent. 2028 * 2029 * <p> The new buffer's position will be zero, its capacity and its limit 2030 * will be the number of bytes remaining in this buffer divided by 2031 * eight, and its mark will be undefined. The new buffer will be direct 2032 * if, and only if, this buffer is direct, and it will be read-only if, and 2033 * only if, this buffer is read-only. </p> 2034 * 2035 * @return A new double buffer 2036 */ 2037 public abstract DoubleBuffer asDoubleBuffer(); 2038 2039 // ----- BEGIN android ----- 2040 // TODO(pszczepaniak): Remove these after adding this functionality 2041 // in the framework 2042 /** 2043 * @hide 2044 */ 2045 public boolean isAccessible() { 2046 return true; 2047 } 2048 /** 2049 * @hide 2050 */ 2051 public void setAccessible(boolean value) { 2052 throw new UnsupportedOperationException(); 2053 } 2054 // ----- END android ----- 2055} 2056