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