ByteBuffer.java revision 9a4a5c7df68495cce39ed2cbfe27615714c72535
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 29package java.nio; 30 31import 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 194public 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 // 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 // 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 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 */ 532 public ByteBuffer put(ByteBuffer src) { 533 if (!isAccessible()) { 534 throw new IllegalStateException("buffer is inaccessible"); 535 } 536 if (isReadOnly) { 537 throw new ReadOnlyBufferException(); 538 } 539 if (src == this) { 540 throw new IllegalArgumentException(); 541 } 542 int n = src.remaining(); 543 if (n > remaining()) { 544 throw new BufferOverflowException(); 545 } 546 547 if (this.hb != null && src.hb != null) { 548 // System.arraycopy is intrinsified by art and therefore tiny bit faster than memmove 549 System.arraycopy(src.hb, src.position() + src.arrayOffset(), 550 hb, position() + arrayOffset(), n); 551 } else { 552 // Use the buffer object (and the raw memory address) if it's direct buffer. 553 // Note that isDirect() doesn't imply !hasArray(), ByteBuffer.allocateDirect allocated 554 // bufferwill have a backing, non-gc-movable byte array. JNI allocated direct byte 555 // buffers WILL NOT have backing array. 556 final Object srcObject = src.isDirect() ? src : src.array(); 557 int srcOffset = src.position(); 558 if (!src.isDirect()) { 559 srcOffset += src.arrayOffset(); 560 } 561 562 final ByteBuffer dst = this; 563 final Object dstObject = dst.isDirect() ? dst : dst.array(); 564 int dstOffset = dst.position(); 565 if (!dst.isDirect()) { 566 dstOffset += dst.arrayOffset(); 567 } 568 Memory.memmove(dstObject, dstOffset, srcObject, srcOffset, n); 569 } 570 src.position(src.limit()); 571 this.position(this.position() + n); 572 return this; 573 } 574 575 /** 576 * Relative bulk <i>put</i> method <i>(optional operation)</i>. 577 * 578 * <p> This method transfers bytes into this buffer from the given 579 * source array. If there are more bytes to be copied from the array 580 * than remain in this buffer, that is, if 581 * <tt>length</tt> <tt>></tt> <tt>remaining()</tt>, then no 582 * bytes are transferred and a {@link BufferOverflowException} is 583 * thrown. 584 * 585 * <p> Otherwise, this method copies <tt>length</tt> bytes from the 586 * given array into this buffer, starting at the given offset in the array 587 * and at the current position of this buffer. The position of this buffer 588 * is then incremented by <tt>length</tt>. 589 * 590 * <p> In other words, an invocation of this method of the form 591 * <tt>dst.put(src, off, len)</tt> has exactly the same effect as 592 * the loop 593 * 594 * <pre> 595 * for (int i = off; i < off + len; i++) 596 * dst.put(a[i]); </pre> 597 * 598 * except that it first checks that there is sufficient space in this 599 * buffer and it is potentially much more efficient. </p> 600 * 601 * @param src The array from which bytes are to be read 602 * @param offset The offset within the array of the first byte to be read; 603 * must be non-negative and no larger than <tt>array.length</tt> 604 * @param length The number of bytes to be read from the given array; 605 * must be non-negative and no larger than 606 * <tt>array.length - offset</tt> 607 * @return This buffer 608 * @throws BufferOverflowException If there is insufficient space in this buffer 609 * @throws IndexOutOfBoundsException If the preconditions on the <tt>offset</tt> and 610 * <tt>length</tt> 611 * parameters do not hold 612 * @throws ReadOnlyBufferException If this buffer is read-only 613 */ 614 public ByteBuffer put(byte[] src, int offset, int length) { 615 checkBounds(offset, length, src.length); 616 if (length > remaining()) 617 throw new BufferOverflowException(); 618 int end = offset + length; 619 for (int i = offset; i < end; i++) 620 this.put(src[i]); 621 return this; 622 } 623 624 /** 625 * Relative bulk <i>put</i> method <i>(optional operation)</i>. 626 * 627 * <p> This method transfers the entire content of the given source 628 * byte array into this buffer. An invocation of this method of the 629 * form <tt>dst.put(a)</tt> behaves in exactly the same way as the 630 * invocation 631 * 632 * <pre> 633 * dst.put(a, 0, a.length) </pre> 634 * 635 * @return This buffer 636 * @throws BufferOverflowException If there is insufficient space in this buffer 637 * @throws ReadOnlyBufferException If this buffer is read-only 638 */ 639 public final ByteBuffer put(byte[] src) { 640 return put(src, 0, src.length); 641 } 642 643 644 // -- Other stuff -- 645 646 /** 647 * Tells whether or not this buffer is backed by an accessible byte 648 * array. 649 * 650 * <p> If this method returns <tt>true</tt> then the {@link #array() array} 651 * and {@link #arrayOffset() arrayOffset} methods may safely be invoked. 652 * </p> 653 * 654 * @return <tt>true</tt> if, and only if, this buffer 655 * is backed by an array and is not read-only 656 */ 657 public final boolean hasArray() { 658 return (hb != null) && !isReadOnly(); 659 } 660 661 /** 662 * Returns the byte array that backs this 663 * buffer <i>(optional operation)</i>. 664 * 665 * <p> Modifications to this buffer's content will cause the returned 666 * array's content to be modified, and vice versa. 667 * 668 * <p> Invoke the {@link #hasArray hasArray} method before invoking this 669 * method in order to ensure that this buffer has an accessible backing 670 * array. </p> 671 * 672 * @return The array that backs this buffer 673 * @throws ReadOnlyBufferException If this buffer is backed by an array but is read-only 674 * @throws UnsupportedOperationException If this buffer is not backed by an accessible array 675 */ 676 public final byte[] array() { 677 if (hb == null) 678 throw new UnsupportedOperationException(); 679 if (isReadOnly) 680 throw new ReadOnlyBufferException(); 681 return hb; 682 } 683 684 /** 685 * Returns the offset within this buffer's backing array of the first 686 * element of the buffer <i>(optional operation)</i>. 687 * 688 * <p> If this buffer is backed by an array then buffer position <i>p</i> 689 * corresponds to array index <i>p</i> + <tt>arrayOffset()</tt>. 690 * 691 * <p> Invoke the {@link #hasArray hasArray} method before invoking this 692 * method in order to ensure that this buffer has an accessible backing 693 * array. </p> 694 * 695 * @return The offset within this buffer's array 696 * of the first element of the buffer 697 * @throws ReadOnlyBufferException If this buffer is backed by an array but is read-only 698 * @throws UnsupportedOperationException If this buffer is not backed by an accessible array 699 */ 700 public final int arrayOffset() { 701 if (hb == null) 702 throw new UnsupportedOperationException(); 703 if (isReadOnly) 704 throw new ReadOnlyBufferException(); 705 return offset; 706 } 707 708 /** 709 * Compacts this buffer <i>(optional operation)</i>. 710 * 711 * <p> The bytes between the buffer's current position and its limit, 712 * if any, are copied to the beginning of the buffer. That is, the 713 * byte at index <i>p</i> = <tt>position()</tt> is copied 714 * to index zero, the byte at index <i>p</i> + 1 is copied 715 * to index one, and so forth until the byte at index 716 * <tt>limit()</tt> - 1 is copied to index 717 * <i>n</i> = <tt>limit()</tt> - <tt>1</tt> - <i>p</i>. 718 * The buffer's position is then set to <i>n+1</i> and its limit is set to 719 * its capacity. The mark, if defined, is discarded. 720 * 721 * <p> The buffer's position is set to the number of bytes copied, 722 * rather than to zero, so that an invocation of this method can be 723 * followed immediately by an invocation of another relative <i>put</i> 724 * method. </p> 725 * 726 * 727 * 728 * <p> Invoke this method after writing data from a buffer in case the 729 * write was incomplete. The following loop, for example, copies bytes 730 * from one channel to another via the buffer <tt>buf</tt>: 731 * 732 * <blockquote><pre> 733 * buf.clear(); // Prepare buffer for use 734 * while (in.read(buf) >= 0 || buf.position != 0) { 735 * buf.flip(); 736 * out.write(buf); 737 * buf.compact(); // In case of partial write 738 * }</pre></blockquote> 739 * 740 * @return This buffer 741 * @throws ReadOnlyBufferException If this buffer is read-only 742 */ 743 public abstract ByteBuffer compact(); 744 745 /** 746 * Tells whether or not this byte buffer is direct. </p> 747 * 748 * @return <tt>true</tt> if, and only if, this buffer is direct 749 */ 750 public abstract boolean isDirect(); 751 752 753 /** 754 * Returns a string summarizing the state of this buffer. </p> 755 * 756 * @return A summary string 757 */ 758 public String toString() { 759 StringBuffer sb = new StringBuffer(); 760 sb.append(getClass().getName()); 761 sb.append("[pos="); 762 sb.append(position()); 763 sb.append(" lim="); 764 sb.append(limit()); 765 sb.append(" cap="); 766 sb.append(capacity()); 767 sb.append("]"); 768 return sb.toString(); 769 } 770 771 772 /** 773 * Returns the current hash code of this buffer. 774 * 775 * <p> The hash code of a byte buffer depends only upon its remaining 776 * elements; that is, upon the elements from <tt>position()</tt> up to, and 777 * including, the element at <tt>limit()</tt> - <tt>1</tt>. 778 * 779 * <p> Because buffer hash codes are content-dependent, it is inadvisable 780 * to use buffers as keys in hash maps or similar data structures unless it 781 * is known that their contents will not change. </p> 782 * 783 * @return The current hash code of this buffer 784 */ 785 public int hashCode() { 786 int h = 1; 787 int p = position(); 788 for (int i = limit() - 1; i >= p; i--) 789 h = 31 * h + (int) get(i); 790 return h; 791 } 792 793 /** 794 * Tells whether or not this buffer is equal to another object. 795 * 796 * <p> Two byte buffers are equal if, and only if, 797 * 798 * <p><ol> 799 * 800 * <li><p> They have the same element type, </p></li> 801 * 802 * <li><p> They have the same number of remaining elements, and 803 * </p></li> 804 * 805 * <li><p> The two sequences of remaining elements, considered 806 * independently of their starting positions, are pointwise equal. 807 * 808 * 809 * 810 * 811 * 812 * 813 * 814 * </p></li> 815 * 816 * </ol> 817 * 818 * <p> A byte buffer is not equal to any other type of object. </p> 819 * 820 * @param ob The object to which this buffer is to be compared 821 * @return <tt>true</tt> if, and only if, this buffer is equal to the 822 * given object 823 */ 824 public boolean equals(Object ob) { 825 if (this == ob) 826 return true; 827 if (!(ob instanceof ByteBuffer)) 828 return false; 829 ByteBuffer that = (ByteBuffer) ob; 830 if (this.remaining() != that.remaining()) 831 return false; 832 int p = this.position(); 833 for (int i = this.limit() - 1, j = that.limit() - 1; i >= p; i--, j--) 834 if (!equals(this.get(i), that.get(j))) 835 return false; 836 return true; 837 } 838 839 private static boolean equals(byte x, byte y) { 840 841 842 return x == y; 843 844 } 845 846 /** 847 * Compares this buffer to another. 848 * 849 * <p> Two byte buffers are compared by comparing their sequences of 850 * remaining elements lexicographically, without regard to the starting 851 * position of each sequence within its corresponding buffer. 852 * 853 * 854 * 855 * 856 * 857 * 858 * 859 * 860 * Pairs of {@code byte} elements are compared as if by invoking 861 * {@link Byte#compare(byte, byte)}. 862 * 863 * 864 * <p> A byte buffer is not comparable to any other type of object. 865 * 866 * @return A negative integer, zero, or a positive integer as this buffer 867 * is less than, equal to, or greater than the given buffer 868 */ 869 public int compareTo(ByteBuffer that) { 870 int n = this.position() + Math.min(this.remaining(), that.remaining()); 871 for (int i = this.position(), j = that.position(); i < n; i++, j++) { 872 int cmp = compare(this.get(i), that.get(j)); 873 if (cmp != 0) 874 return cmp; 875 } 876 return this.remaining() - that.remaining(); 877 } 878 879 private static int compare(byte x, byte y) { 880 881 882 return Byte.compare(x, y); 883 884 } 885 886 // -- Other char stuff -- 887 888 889 // -- Other byte stuff: Access to binary data -- 890 891 892 boolean bigEndian // package-private 893 = true; 894 boolean nativeByteOrder // package-private 895 = (Bits.byteOrder() == ByteOrder.BIG_ENDIAN); 896 897 /** 898 * Retrieves this buffer's byte order. 899 * 900 * <p> The byte order is used when reading or writing multibyte values, and 901 * when creating buffers that are views of this byte buffer. The order of 902 * a newly-created byte buffer is always {@link ByteOrder#BIG_ENDIAN 903 * BIG_ENDIAN}. </p> 904 * 905 * @return This buffer's byte order 906 */ 907 public final ByteOrder order() { 908 return bigEndian ? ByteOrder.BIG_ENDIAN : ByteOrder.LITTLE_ENDIAN; 909 } 910 911 /** 912 * Modifies this buffer's byte order. </p> 913 * 914 * @param bo The new byte order, 915 * either {@link ByteOrder#BIG_ENDIAN BIG_ENDIAN} 916 * or {@link ByteOrder#LITTLE_ENDIAN LITTLE_ENDIAN} 917 * @return This buffer 918 */ 919 public final ByteBuffer order(ByteOrder bo) { 920 bigEndian = (bo == ByteOrder.BIG_ENDIAN); 921 nativeByteOrder = 922 (bigEndian == (Bits.byteOrder() == ByteOrder.BIG_ENDIAN)); 923 return this; 924 } 925 926 // Unchecked accessors, for use by ByteBufferAs-X-Buffer classes 927 // 928 abstract byte _get(int i); // package-private 929 930 abstract void _put(int i, byte b); // package-private 931 932 933 /** 934 * Relative <i>get</i> method for reading a char value. 935 * 936 * <p> Reads the next two bytes at this buffer's current position, 937 * composing them into a char value according to the current byte order, 938 * and then increments the position by two. </p> 939 * 940 * @return The char value at the buffer's current position 941 * @throws BufferUnderflowException If there are fewer than two bytes 942 * remaining in this buffer 943 */ 944 public abstract char getChar(); 945 946 /** 947 * Relative <i>put</i> method for writing a char 948 * value <i>(optional operation)</i>. 949 * 950 * <p> Writes two bytes containing the given char value, in the 951 * current byte order, into this buffer at the current position, and then 952 * increments the position by two. </p> 953 * 954 * @param value The char value to be written 955 * @return This buffer 956 * @throws BufferOverflowException If there are fewer than two bytes 957 * remaining in this buffer 958 * @throws ReadOnlyBufferException If this buffer is read-only 959 */ 960 public abstract ByteBuffer putChar(char value); 961 962 /** 963 * Absolute <i>get</i> method for reading a char value. 964 * 965 * <p> Reads two bytes at the given index, composing them into a 966 * char value according to the current byte order. </p> 967 * 968 * @param index The index from which the bytes will be read 969 * @return The char value at the given index 970 * @throws IndexOutOfBoundsException If <tt>index</tt> is negative 971 * or not smaller than the buffer's limit, 972 * minus one 973 */ 974 public abstract char getChar(int index); 975 976 char getCharUnchecked(int index) { 977 throw new UnsupportedOperationException(); 978 } 979 980 void getUnchecked(int pos, char[] dst, int dstOffset, int length) { 981 throw new UnsupportedOperationException(); 982 } 983 984 /** 985 * Absolute <i>put</i> method for writing a char 986 * value <i>(optional operation)</i>. 987 * 988 * <p> Writes two bytes containing the given char value, in the 989 * current byte order, into this buffer at the given index. </p> 990 * 991 * @param index The index at which the bytes will be written 992 * @param value The char value to be written 993 * @return This buffer 994 * @throws IndexOutOfBoundsException If <tt>index</tt> is negative 995 * or not smaller than the buffer's limit, 996 * minus one 997 * @throws ReadOnlyBufferException If this buffer is read-only 998 */ 999 public abstract ByteBuffer putChar(int index, char value); 1000 1001 void putCharUnchecked(int index, char value) { 1002 throw new UnsupportedOperationException(); 1003 } 1004 1005 void putUnchecked(int pos, char[] dst, int srcOffset, int length) { 1006 throw new UnsupportedOperationException(); 1007 } 1008 1009 /** 1010 * Creates a view of this byte buffer as a char buffer. 1011 * 1012 * <p> The content of the new buffer will start at this buffer's current 1013 * position. Changes to this buffer's content will be visible in the new 1014 * buffer, and vice versa; the two buffers' position, limit, and mark 1015 * values will be independent. 1016 * 1017 * <p> The new buffer's position will be zero, its capacity and its limit 1018 * will be the number of bytes remaining in this buffer divided by 1019 * two, and its mark will be undefined. The new buffer will be direct 1020 * if, and only if, this buffer is direct, and it will be read-only if, and 1021 * only if, this buffer is read-only. </p> 1022 * 1023 * @return A new char buffer 1024 */ 1025 public abstract CharBuffer asCharBuffer(); 1026 1027 1028 /** 1029 * Relative <i>get</i> method for reading a short value. 1030 * 1031 * <p> Reads the next two bytes at this buffer's current position, 1032 * composing them into a short value according to the current byte order, 1033 * and then increments the position by two. </p> 1034 * 1035 * @return The short value at the buffer's current position 1036 * @throws BufferUnderflowException If there are fewer than two bytes 1037 * remaining in this buffer 1038 */ 1039 public abstract short getShort(); 1040 1041 /** 1042 * Relative <i>put</i> method for writing a short 1043 * value <i>(optional operation)</i>. 1044 * 1045 * <p> Writes two bytes containing the given short value, in the 1046 * current byte order, into this buffer at the current position, and then 1047 * increments the position by two. </p> 1048 * 1049 * @param value The short value to be written 1050 * @return This buffer 1051 * @throws BufferOverflowException If there are fewer than two bytes 1052 * remaining in this buffer 1053 * @throws ReadOnlyBufferException If this buffer is read-only 1054 */ 1055 public abstract ByteBuffer putShort(short value); 1056 1057 /** 1058 * Absolute <i>get</i> method for reading a short value. 1059 * 1060 * <p> Reads two bytes at the given index, composing them into a 1061 * short value according to the current byte order. </p> 1062 * 1063 * @param index The index from which the bytes will be read 1064 * @return The short value at the given index 1065 * @throws IndexOutOfBoundsException If <tt>index</tt> is negative 1066 * or not smaller than the buffer's limit, 1067 * minus one 1068 */ 1069 public abstract short getShort(int index); 1070 1071 short getShortUnchecked(int index) { 1072 throw new UnsupportedOperationException(); 1073 } 1074 1075 void getUnchecked(int pos, short[] dst, int dstOffset, int length) { 1076 throw new UnsupportedOperationException(); 1077 } 1078 1079 /** 1080 * Absolute <i>put</i> method for writing a short 1081 * value <i>(optional operation)</i>. 1082 * 1083 * <p> Writes two bytes containing the given short value, in the 1084 * current byte order, into this buffer at the given index. </p> 1085 * 1086 * @param index The index at which the bytes will be written 1087 * @param value The short value to be written 1088 * @return This buffer 1089 * @throws IndexOutOfBoundsException If <tt>index</tt> is negative 1090 * or not smaller than the buffer's limit, 1091 * minus one 1092 * @throws ReadOnlyBufferException If this buffer is read-only 1093 */ 1094 public abstract ByteBuffer putShort(int index, short value); 1095 1096 void putShortUnchecked(int index, short value) { 1097 throw new UnsupportedOperationException(); 1098 } 1099 1100 void putUnchecked(int pos, short[] dst, int srcOffset, int length) { 1101 throw new UnsupportedOperationException(); 1102 } 1103 1104 /** 1105 * Creates a view of this byte buffer as a short buffer. 1106 * 1107 * <p> The content of the new buffer will start at this buffer's current 1108 * position. Changes to this buffer's content will be visible in the new 1109 * buffer, and vice versa; the two buffers' position, limit, and mark 1110 * values will be independent. 1111 * 1112 * <p> The new buffer's position will be zero, its capacity and its limit 1113 * will be the number of bytes remaining in this buffer divided by 1114 * two, and its mark will be undefined. The new buffer will be direct 1115 * if, and only if, this buffer is direct, and it will be read-only if, and 1116 * only if, this buffer is read-only. </p> 1117 * 1118 * @return A new short buffer 1119 */ 1120 public abstract ShortBuffer asShortBuffer(); 1121 1122 1123 /** 1124 * Relative <i>get</i> method for reading an int value. 1125 * 1126 * <p> Reads the next four bytes at this buffer's current position, 1127 * composing them into an int value according to the current byte order, 1128 * and then increments the position by four. </p> 1129 * 1130 * @return The int value at the buffer's current position 1131 * @throws BufferUnderflowException If there are fewer than four bytes 1132 * remaining in this buffer 1133 */ 1134 public abstract int getInt(); 1135 1136 /** 1137 * Relative <i>put</i> method for writing an int 1138 * value <i>(optional operation)</i>. 1139 * 1140 * <p> Writes four bytes containing the given int value, in the 1141 * current byte order, into this buffer at the current position, and then 1142 * increments the position by four. </p> 1143 * 1144 * @param value The int value to be written 1145 * @return This buffer 1146 * @throws BufferOverflowException If there are fewer than four bytes 1147 * remaining in this buffer 1148 * @throws ReadOnlyBufferException If this buffer is read-only 1149 */ 1150 public abstract ByteBuffer putInt(int value); 1151 1152 /** 1153 * Absolute <i>get</i> method for reading an int value. 1154 * 1155 * <p> Reads four bytes at the given index, composing them into a 1156 * int value according to the current byte order. </p> 1157 * 1158 * @param index The index from which the bytes will be read 1159 * @return The int value at the given index 1160 * @throws IndexOutOfBoundsException If <tt>index</tt> is negative 1161 * or not smaller than the buffer's limit, 1162 * minus three 1163 */ 1164 public abstract int getInt(int index); 1165 1166 int getIntUnchecked(int index) { 1167 throw new UnsupportedOperationException(); 1168 } 1169 1170 void getUnchecked(int pos, int[] dst, int dstOffset, int length) { 1171 throw new UnsupportedOperationException(); 1172 } 1173 1174 /** 1175 * Absolute <i>put</i> method for writing an int 1176 * value <i>(optional operation)</i>. 1177 * 1178 * <p> Writes four bytes containing the given int value, in the 1179 * current byte order, into this buffer at the given index. </p> 1180 * 1181 * @param index The index at which the bytes will be written 1182 * @param value The int value to be written 1183 * @return This buffer 1184 * @throws IndexOutOfBoundsException If <tt>index</tt> is negative 1185 * or not smaller than the buffer's limit, 1186 * minus three 1187 * @throws ReadOnlyBufferException If this buffer is read-only 1188 */ 1189 public abstract ByteBuffer putInt(int index, int value); 1190 1191 void putIntUnchecked(int index, int value) { 1192 throw new UnsupportedOperationException(); 1193 } 1194 1195 void putUnchecked(int pos, int[] dst, int srcOffset, int length) { 1196 throw new UnsupportedOperationException(); 1197 } 1198 1199 /** 1200 * Creates a view of this byte buffer as an int buffer. 1201 * 1202 * <p> The content of the new buffer will start at this buffer's current 1203 * position. Changes to this buffer's content will be visible in the new 1204 * buffer, and vice versa; the two buffers' position, limit, and mark 1205 * values will be independent. 1206 * 1207 * <p> The new buffer's position will be zero, its capacity and its limit 1208 * will be the number of bytes remaining in this buffer divided by 1209 * four, and its mark will be undefined. The new buffer will be direct 1210 * if, and only if, this buffer is direct, and it will be read-only if, and 1211 * only if, this buffer is read-only. </p> 1212 * 1213 * @return A new int buffer 1214 */ 1215 public abstract IntBuffer asIntBuffer(); 1216 1217 1218 /** 1219 * Relative <i>get</i> method for reading a long value. 1220 * 1221 * <p> Reads the next eight bytes at this buffer's current position, 1222 * composing them into a long value according to the current byte order, 1223 * and then increments the position by eight. </p> 1224 * 1225 * @return The long value at the buffer's current position 1226 * @throws BufferUnderflowException If there are fewer than eight bytes 1227 * remaining in this buffer 1228 */ 1229 public abstract long getLong(); 1230 1231 /** 1232 * Relative <i>put</i> method for writing a long 1233 * value <i>(optional operation)</i>. 1234 * 1235 * <p> Writes eight bytes containing the given long value, in the 1236 * current byte order, into this buffer at the current position, and then 1237 * increments the position by eight. </p> 1238 * 1239 * @param value The long value to be written 1240 * @return This buffer 1241 * @throws BufferOverflowException If there are fewer than eight bytes 1242 * remaining in this buffer 1243 * @throws ReadOnlyBufferException If this buffer is read-only 1244 */ 1245 public abstract ByteBuffer putLong(long value); 1246 1247 /** 1248 * Absolute <i>get</i> method for reading a long value. 1249 * 1250 * <p> Reads eight bytes at the given index, composing them into a 1251 * long value according to the current byte order. </p> 1252 * 1253 * @param index The index from which the bytes will be read 1254 * @return The long value at the given index 1255 * @throws IndexOutOfBoundsException If <tt>index</tt> is negative 1256 * or not smaller than the buffer's limit, 1257 * minus seven 1258 */ 1259 public abstract long getLong(int index); 1260 1261 long getLongUnchecked(int index) { 1262 throw new UnsupportedOperationException(); 1263 } 1264 1265 void getUnchecked(int pos, long[] dst, int dstOffset, int length) { 1266 throw new UnsupportedOperationException(); 1267 } 1268 1269 /** 1270 * Absolute <i>put</i> method for writing a long 1271 * value <i>(optional operation)</i>. 1272 * 1273 * <p> Writes eight bytes containing the given long value, in the 1274 * current byte order, into this buffer at the given index. </p> 1275 * 1276 * @param index The index at which the bytes will be written 1277 * @param value The long value to be written 1278 * @return This buffer 1279 * @throws IndexOutOfBoundsException If <tt>index</tt> is negative 1280 * or not smaller than the buffer's limit, 1281 * minus seven 1282 * @throws ReadOnlyBufferException If this buffer is read-only 1283 */ 1284 public abstract ByteBuffer putLong(int index, long value); 1285 1286 void putLongUnchecked(int index, long value) { 1287 throw new UnsupportedOperationException(); 1288 } 1289 1290 void putUnchecked(int pos, long[] dst, int srcOffset, int length) { 1291 throw new UnsupportedOperationException(); 1292 } 1293 1294 /** 1295 * Creates a view of this byte buffer as a long buffer. 1296 * 1297 * <p> The content of the new buffer will start at this buffer's current 1298 * position. Changes to this buffer's content will be visible in the new 1299 * buffer, and vice versa; the two buffers' position, limit, and mark 1300 * values will be independent. 1301 * 1302 * <p> The new buffer's position will be zero, its capacity and its limit 1303 * will be the number of bytes remaining in this buffer divided by 1304 * eight, and its mark will be undefined. The new buffer will be direct 1305 * if, and only if, this buffer is direct, and it will be read-only if, and 1306 * only if, this buffer is read-only. </p> 1307 * 1308 * @return A new long buffer 1309 */ 1310 public abstract LongBuffer asLongBuffer(); 1311 1312 1313 /** 1314 * Relative <i>get</i> method for reading a float value. 1315 * 1316 * <p> Reads the next four bytes at this buffer's current position, 1317 * composing them into a float value according to the current byte order, 1318 * and then increments the position by four. </p> 1319 * 1320 * @return The float value at the buffer's current position 1321 * @throws BufferUnderflowException If there are fewer than four bytes 1322 * remaining in this buffer 1323 */ 1324 public abstract float getFloat(); 1325 1326 /** 1327 * Relative <i>put</i> method for writing a float 1328 * value <i>(optional operation)</i>. 1329 * 1330 * <p> Writes four bytes containing the given float value, in the 1331 * current byte order, into this buffer at the current position, and then 1332 * increments the position by four. </p> 1333 * 1334 * @param value The float value to be written 1335 * @return This buffer 1336 * @throws BufferOverflowException If there are fewer than four bytes 1337 * remaining in this buffer 1338 * @throws ReadOnlyBufferException If this buffer is read-only 1339 */ 1340 public abstract ByteBuffer putFloat(float value); 1341 1342 /** 1343 * Absolute <i>get</i> method for reading a float value. 1344 * 1345 * <p> Reads four bytes at the given index, composing them into a 1346 * float value according to the current byte order. </p> 1347 * 1348 * @param index The index from which the bytes will be read 1349 * @return The float value at the given index 1350 * @throws IndexOutOfBoundsException If <tt>index</tt> is negative 1351 * or not smaller than the buffer's limit, 1352 * minus three 1353 */ 1354 public abstract float getFloat(int index); 1355 1356 float getFloatUnchecked(int index) { 1357 throw new UnsupportedOperationException(); 1358 } 1359 1360 void getUnchecked(int pos, float[] dst, int dstOffset, int length) { 1361 throw new UnsupportedOperationException(); 1362 } 1363 1364 /** 1365 * Absolute <i>put</i> method for writing a float 1366 * value <i>(optional operation)</i>. 1367 * 1368 * <p> Writes four bytes containing the given float value, in the 1369 * current byte order, into this buffer at the given index. </p> 1370 * 1371 * @param index The index at which the bytes will be written 1372 * @param value The float value to be written 1373 * @return This buffer 1374 * @throws IndexOutOfBoundsException If <tt>index</tt> is negative 1375 * or not smaller than the buffer's limit, 1376 * minus three 1377 * @throws ReadOnlyBufferException If this buffer is read-only 1378 */ 1379 public abstract ByteBuffer putFloat(int index, float value); 1380 1381 void putFloatUnchecked(int index, float value) { 1382 throw new UnsupportedOperationException(); 1383 } 1384 1385 void putUnchecked(int pos, float[] dst, int srcOffset, int length) { 1386 throw new UnsupportedOperationException(); 1387 } 1388 1389 /** 1390 * Creates a view of this byte buffer as a float buffer. 1391 * 1392 * <p> The content of the new buffer will start at this buffer's current 1393 * position. Changes to this buffer's content will be visible in the new 1394 * buffer, and vice versa; the two buffers' position, limit, and mark 1395 * values will be independent. 1396 * 1397 * <p> The new buffer's position will be zero, its capacity and its limit 1398 * will be the number of bytes remaining in this buffer divided by 1399 * four, and its mark will be undefined. The new buffer will be direct 1400 * if, and only if, this buffer is direct, and it will be read-only if, and 1401 * only if, this buffer is read-only. </p> 1402 * 1403 * @return A new float buffer 1404 */ 1405 public abstract FloatBuffer asFloatBuffer(); 1406 1407 1408 /** 1409 * Relative <i>get</i> method for reading a double value. 1410 * 1411 * <p> Reads the next eight bytes at this buffer's current position, 1412 * composing them into a double value according to the current byte order, 1413 * and then increments the position by eight. </p> 1414 * 1415 * @return The double value at the buffer's current position 1416 * @throws BufferUnderflowException If there are fewer than eight bytes 1417 * remaining in this buffer 1418 */ 1419 public abstract double getDouble(); 1420 1421 /** 1422 * Relative <i>put</i> method for writing a double 1423 * value <i>(optional operation)</i>. 1424 * 1425 * <p> Writes eight bytes containing the given double value, in the 1426 * current byte order, into this buffer at the current position, and then 1427 * increments the position by eight. </p> 1428 * 1429 * @param value The double value to be written 1430 * @return This buffer 1431 * @throws BufferOverflowException If there are fewer than eight bytes 1432 * remaining in this buffer 1433 * @throws ReadOnlyBufferException If this buffer is read-only 1434 */ 1435 public abstract ByteBuffer putDouble(double value); 1436 1437 /** 1438 * Absolute <i>get</i> method for reading a double value. 1439 * 1440 * <p> Reads eight bytes at the given index, composing them into a 1441 * double value according to the current byte order. </p> 1442 * 1443 * @param index The index from which the bytes will be read 1444 * @return The double value at the given index 1445 * @throws IndexOutOfBoundsException If <tt>index</tt> is negative 1446 * or not smaller than the buffer's limit, 1447 * minus seven 1448 */ 1449 public abstract double getDouble(int index); 1450 1451 double getDoubleUnchecked(int index) { 1452 throw new UnsupportedOperationException(); 1453 } 1454 1455 void getUnchecked(int pos, double[] dst, int dstOffset, int length) { 1456 throw new UnsupportedOperationException(); 1457 } 1458 1459 /** 1460 * Absolute <i>put</i> method for writing a double 1461 * value <i>(optional operation)</i>. 1462 * 1463 * <p> Writes eight bytes containing the given double value, in the 1464 * current byte order, into this buffer at the given index. </p> 1465 * 1466 * @param index The index at which the bytes will be written 1467 * @param value The double value to be written 1468 * @return This buffer 1469 * @throws IndexOutOfBoundsException If <tt>index</tt> is negative 1470 * or not smaller than the buffer's limit, 1471 * minus seven 1472 * @throws ReadOnlyBufferException If this buffer is read-only 1473 */ 1474 public abstract ByteBuffer putDouble(int index, double value); 1475 1476 void putDoubleUnchecked(int index, double value) { 1477 throw new UnsupportedOperationException(); 1478 } 1479 1480 void putUnchecked(int pos, double[] dst, int srcOffset, int length) { 1481 throw new UnsupportedOperationException(); 1482 } 1483 1484 /** 1485 * Creates a view of this byte buffer as a double buffer. 1486 * 1487 * <p> The content of the new buffer will start at this buffer's current 1488 * position. Changes to this buffer's content will be visible in the new 1489 * buffer, and vice versa; the two buffers' position, limit, and mark 1490 * values will be independent. 1491 * 1492 * <p> The new buffer's position will be zero, its capacity and its limit 1493 * will be the number of bytes remaining in this buffer divided by 1494 * eight, and its mark will be undefined. The new buffer will be direct 1495 * if, and only if, this buffer is direct, and it will be read-only if, and 1496 * only if, this buffer is read-only. </p> 1497 * 1498 * @return A new double buffer 1499 */ 1500 public abstract DoubleBuffer asDoubleBuffer(); 1501 1502 /** 1503 * @hide 1504 */ 1505 public boolean isAccessible() { 1506 return true; 1507 } 1508 1509 /** 1510 * @hide 1511 */ 1512 public void setAccessible(boolean value) { 1513 throw new UnsupportedOperationException(); 1514 } 1515} 1516