1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18 package java.nio;
19
20 import org.apache.harmony.luni.platform.Endianness;
21
22 /**
23 * A buffer for bytes.
24 * <p>
25 * A byte buffer can be created in either one of the following ways:
26 * <ul>
27 * <li>{@link #allocate(int) Allocate} a new byte array and create a buffer
28 * based on it;</li>
29 * <li>{@link #allocateDirect(int) Allocate} a memory block and create a direct
30 * buffer based on it;</li>
31 * <li>{@link #wrap(byte[]) Wrap} an existing byte array to create a new
32 * buffer.</li>
33 * </ul>
34 *
35 */
36 public abstract class ByteBuffer extends Buffer implements
37 Comparable<ByteBuffer> {
38
39 /**
40 * Creates a byte buffer based on a newly allocated byte array.
41 *
42 * @param capacity
43 * the capacity of the new buffer
44 * @return the created byte buffer.
45 * @throws IllegalArgumentException
46 * if {@code capacity < 0}.
47 */
48 public static ByteBuffer allocate(int capacity) {
49 if (capacity < 0) {
50 throw new IllegalArgumentException();
51 }
52 return BufferFactory.newByteBuffer(capacity);
53 }
54
55 /**
56 * Creates a direct byte buffer based on a newly allocated memory block.
57 *
58 * @param capacity
59 * the capacity of the new buffer
60 * @return the created byte buffer.
61 * @throws IllegalArgumentException
62 * if {@code capacity < 0}.
63 */
64 public static ByteBuffer allocateDirect(int capacity) {
65 if (capacity < 0) {
66 throw new IllegalArgumentException();
67 }
68 return BufferFactory.newDirectByteBuffer(capacity);
69 }
70
71 /**
72 * Creates a new byte buffer by wrapping the given byte array.
73 * <p>
74 * Calling this method has the same effect as
75 * {@code wrap(array, 0, array.length)}.
76 *
77 * @param array
78 * the byte array which the new buffer will be based on
79 * @return the created byte buffer.
80 */
81 public static ByteBuffer wrap(byte[] array) {
82 return BufferFactory.newByteBuffer(array);
83 }
84
85 /**
86 * Creates a new byte buffer by wrapping the given byte array.
87 * <p>
88 * The new buffer's position will be {@code start}, limit will be
89 * {@code start + len}, capacity will be the length of the array.
90 *
91 * @param array
92 * the byte array which the new buffer will be based on.
93 * @param start
94 * the start index, must not be negative and not greater than
95 * {@code array.length}.
96 * @param len
97 * the length, must not be negative and not greater than
98 * {@code array.length - start}.
99 * @return the created byte buffer.
100 * @exception IndexOutOfBoundsException
101 * if either {@code start} or {@code len} is invalid.
102 */
103 public static ByteBuffer wrap(byte[] array, int start, int len) {
104 int length = array.length;
105 if ((start < 0) || (len < 0) || ((long) start + (long) len > length)) {
106 throw new IndexOutOfBoundsException();
107 }
108
109 ByteBuffer buf = BufferFactory.newByteBuffer(array);
110 buf.position = start;
111 buf.limit = start + len;
112
113 return buf;
114 }
115
116 /**
117 * The byte order of this buffer, default is {@code BIG_ENDIAN}.
118 */
119 Endianness order = Endianness.BIG_ENDIAN;
120
121 /**
122 * Constructs a {@code ByteBuffer} with given capacity.
123 *
124 * @param capacity
125 * the capacity of the buffer.
126 */
127 ByteBuffer(int capacity) {
128 super(capacity);
129 }
130
131 /**
132 * Returns the byte array which this buffer is based on, if there is one.
133 *
134 * @return the byte array which this buffer is based on.
135 * @exception ReadOnlyBufferException
136 * if this buffer is based on a read-only array.
137 * @exception UnsupportedOperationException
138 * if this buffer is not based on an array.
139 */
140 public final byte[] array() {
141 return protectedArray();
142 }
143
144 /**
145 * Returns the offset of the byte array which this buffer is based on, if
146 * there is one.
147 * <p>
148 * The offset is the index of the array which corresponds to the zero
149 * position of the buffer.
150 *
151 * @return the offset of the byte array which this buffer is based on.
152 * @exception ReadOnlyBufferException
153 * if this buffer is based on a read-only array.
154 * @exception UnsupportedOperationException
155 * if this buffer is not based on an array.
156 */
157 public final int arrayOffset() {
158 return protectedArrayOffset();
159 }
160
161 /**
162 * Returns a char buffer which is based on the remaining content of this
163 * byte buffer.
164 * <p>
165 * The new buffer's position is zero, its limit and capacity is the number
166 * of remaining bytes divided by two, and its mark is not set. The new
167 * buffer's read-only property and byte order are the same as this buffer's.
168 * The new buffer is direct if this byte buffer is direct.
169 * <p>
170 * The new buffer shares its content with this buffer, which means either
171 * buffer's change of content will be visible to the other. The two buffer's
172 * position, limit and mark are independent.
173 *
174 * @return a char buffer which is based on the content of this byte buffer.
175 */
176 public abstract CharBuffer asCharBuffer();
177
178 /**
179 * Returns a double buffer which is based on the remaining content of this
180 * byte buffer.
181 * <p>
182 * The new buffer's position is zero, its limit and capacity is the number
183 * of remaining bytes divided by eight, and its mark is not set. The new
184 * buffer's read-only property and byte order are the same as this buffer's.
185 * The new buffer is direct if this byte buffer is direct.
186 * <p>
187 * The new buffer shares its content with this buffer, which means either
188 * buffer's change of content will be visible to the other. The two buffer's
189 * position, limit and mark are independent.
190 *
191 * @return a double buffer which is based on the content of this byte
192 * buffer.
193 */
194 public abstract DoubleBuffer asDoubleBuffer();
195
196 /**
197 * Returns a float buffer which is based on the remaining content of this
198 * byte buffer.
199 * <p>
200 * The new buffer's position is zero, its limit and capacity is the number
201 * of remaining bytes divided by four, and its mark is not set. The new
202 * buffer's read-only property and byte order are the same as this buffer's.
203 * The new buffer is direct if this byte buffer is direct.
204 * <p>
205 * The new buffer shares its content with this buffer, which means either
206 * buffer's change of content will be visible to the other. The two buffer's
207 * position, limit and mark are independent.
208 *
209 * @return a float buffer which is based on the content of this byte buffer.
210 */
211 public abstract FloatBuffer asFloatBuffer();
212
213 /**
214 * Returns a int buffer which is based on the remaining content of this byte
215 * buffer.
216 * <p>
217 * The new buffer's position is zero, its limit and capacity is the number
218 * of remaining bytes divided by four, and its mark is not set. The new
219 * buffer's read-only property and byte order are the same as this buffer's.
220 * The new buffer is direct if this byte buffer is direct.
221 * <p>
222 * The new buffer shares its content with this buffer, which means either
223 * buffer's change of content will be visible to the other. The two buffer's
224 * position, limit and mark are independent.
225 *
226 * @return a int buffer which is based on the content of this byte buffer.
227 */
228 public abstract IntBuffer asIntBuffer();
229
230 /**
231 * Returns a long buffer which is based on the remaining content of this
232 * byte buffer.
233 * <p>
234 * The new buffer's position is zero, its limit and capacity is the number
235 * of remaining bytes divided by eight, and its mark is not set. The new
236 * buffer's read-only property and byte order are the same as this buffer's.
237 * The new buffer is direct if this byte buffer is direct.
238 * <p>
239 * The new buffer shares its content with this buffer, which means either
240 * buffer's change of content will be visible to the other. The two buffer's
241 * position, limit and mark are independent.
242 *
243 * @return a long buffer which is based on the content of this byte buffer.
244 */
245 public abstract LongBuffer asLongBuffer();
246
247 /**
248 * Returns a read-only buffer that shares its content with this buffer.
249 * <p>
250 * The returned buffer is guaranteed to be a new instance, even if this
251 * buffer is read-only itself. The new buffer's position, limit, capacity
252 * and mark are the same as this buffer.
253 * <p>
254 * The new buffer shares its content with this buffer, which means this
255 * buffer's change of content will be visible to the new buffer. The two
256 * buffer's position, limit and mark are independent.
257 *
258 * @return a read-only version of this buffer.
259 */
260 public abstract ByteBuffer asReadOnlyBuffer();
261
262 /**
263 * Returns a short buffer which is based on the remaining content of this
264 * byte buffer.
265 * <p>
266 * The new buffer's position is zero, its limit and capacity is the number
267 * of remaining bytes divided by two, and its mark is not set. The new
268 * buffer's read-only property and byte order are the same as this buffer's.
269 * The new buffer is direct if this byte buffer is direct.
270 * <p>
271 * The new buffer shares its content with this buffer, which means either
272 * buffer's change of content will be visible to the other. The two buffer's
273 * position, limit and mark are independent.
274 *
275 * @return a short buffer which is based on the content of this byte buffer.
276 */
277 public abstract ShortBuffer asShortBuffer();
278
279 /**
280 * Compacts this byte buffer.
281 * <p>
282 * The remaining bytes will be moved to the head of the
283 * buffer, starting from position zero. Then the position is set to
284 * {@code remaining()}; the limit is set to capacity; the mark is
285 * cleared.
286 *
287 * @return this buffer.
288 * @exception ReadOnlyBufferException
289 * if no changes may be made to the contents of this buffer.
290 */
291 public abstract ByteBuffer compact();
292
293 /**
294 * Compares the remaining bytes of this buffer to another byte buffer's
295 * remaining bytes.
296 *
297 * @param otherBuffer
298 * another byte buffer.
299 * @return a negative value if this is less than {@code other}; 0 if this
300 * equals to {@code other}; a positive value if this is greater
301 * than {@code other}.
302 * @exception ClassCastException
303 * if {@code other} is not a byte buffer.
304 */
305 public int compareTo(ByteBuffer otherBuffer) {
306 int compareRemaining = (remaining() < otherBuffer.remaining()) ? remaining()
307 : otherBuffer.remaining();
308 int thisPos = position;
309 int otherPos = otherBuffer.position;
310 byte thisByte, otherByte;
311 while (compareRemaining > 0) {
312 thisByte = get(thisPos);
313 otherByte = otherBuffer.get(otherPos);
314 if (thisByte != otherByte) {
315 return thisByte < otherByte ? -1 : 1;
316 }
317 thisPos++;
318 otherPos++;
319 compareRemaining--;
320 }
321 return remaining() - otherBuffer.remaining();
322 }
323
324 /**
325 * Returns a duplicated buffer that shares its content with this buffer.
326 * <p>
327 * The duplicated buffer's position, limit, capacity and mark are the same
328 * as this buffer's. The duplicated buffer's read-only property and byte
329 * order are the same as this buffer's too.
330 * <p>
331 * The new buffer shares its content with this buffer, which means either
332 * buffer's change of content will be visible to the other. The two buffer's
333 * position, limit and mark are independent.
334 *
335 * @return a duplicated buffer that shares its content with this buffer.
336 */
337 public abstract ByteBuffer duplicate();
338
339 /**
340 * Checks whether this byte buffer is equal to another object.
341 * <p>
342 * If {@code other} is not a byte buffer then {@code false} is returned. Two
343 * byte buffers are equal if and only if their remaining bytes are exactly
344 * the same. Position, limit, capacity and mark are not considered.
345 *
346 * @param other
347 * the object to compare with this byte buffer.
348 * @return {@code true} if this byte buffer is equal to {@code other},
349 * {@code false} otherwise.
350 */
351 @Override
352 public boolean equals(Object other) {
353 if (!(other instanceof ByteBuffer)) {
354 return false;
355 }
356 ByteBuffer otherBuffer = (ByteBuffer) other;
357
358 if (remaining() != otherBuffer.remaining()) {
359 return false;
360 }
361
362 int myPosition = position;
363 int otherPosition = otherBuffer.position;
364 boolean equalSoFar = true;
365 while (equalSoFar && (myPosition < limit)) {
366 equalSoFar = get(myPosition++) == otherBuffer.get(otherPosition++);
367 }
368
369 return equalSoFar;
370 }
371
372 /**
373 * Returns the byte at the current position and increases the position by 1.
374 *
375 * @return the byte at the current position.
376 * @exception BufferUnderflowException
377 * if the position is equal or greater than limit.
378 */
379 public abstract byte get();
380
381 /**
382 * Reads bytes from the current position into the specified byte array and
383 * increases the position by the number of bytes read.
384 * <p>
385 * Calling this method has the same effect as
386 * {@code get(dest, 0, dest.length)}.
387 *
388 * @param dest
389 * the destination byte array.
390 * @return this buffer.
391 * @exception BufferUnderflowException
392 * if {@code dest.length} is greater than {@code remaining()}.
393 */
394 public ByteBuffer get(byte[] dest) {
395 return get(dest, 0, dest.length);
396 }
397
398 /**
399 * Reads bytes from the current position into the specified byte array,
400 * starting at the specified offset, and increases the position by the
401 * number of bytes read.
402 *
403 * @param dest
404 * the target byte array.
405 * @param off
406 * the offset of the byte array, must not be negative and
407 * not greater than {@code dest.length}.
408 * @param len
409 * the number of bytes to read, must not be negative and not
410 * greater than {@code dest.length - off}
411 * @return this buffer.
412 * @exception IndexOutOfBoundsException
413 * if either {@code off} or {@code len} is invalid.
414 * @exception BufferUnderflowException
415 * if {@code len} is greater than {@code remaining()}.
416 */
417 public ByteBuffer get(byte[] dest, int off, int len) {
418 int length = dest.length;
419 if ((off < 0) || (len < 0) || ((long) off + (long) len > length)) {
420 throw new IndexOutOfBoundsException();
421 }
422
423 if (len > remaining()) {
424 throw new BufferUnderflowException();
425 }
426 for (int i = off; i < off + len; i++) {
427 dest[i] = get();
428 }
429 return this;
430 }
431
432 /**
433 * Returns the byte at the specified index and does not change the position.
434 *
435 * @param index
436 * the index, must not be negative and less than limit.
437 * @return the byte at the specified index.
438 * @exception IndexOutOfBoundsException
439 * if index is invalid.
440 */
441 public abstract byte get(int index);
442
443 /**
444 * Returns the char at the current position and increases the position by 2.
445 * <p>
446 * The 2 bytes starting at the current position are composed into a char
447 * according to the current byte order and returned.
448 *
449 * @return the char at the current position.
450 * @exception BufferUnderflowException
451 * if the position is greater than {@code limit - 2}.
452 */
453 public abstract char getChar();
454
455 /**
456 * Returns the char at the specified index.
457 * <p>
458 * The 2 bytes starting from the specified index are composed into a char
459 * according to the current byte order and returned. The position is not
460 * changed.
461 *
462 * @param index
463 * the index, must not be negative and equal or less than
464 * {@code limit - 2}.
465 * @return the char at the specified index.
466 * @exception IndexOutOfBoundsException
467 * if {@code index} is invalid.
468 */
469 public abstract char getChar(int index);
470
471 /**
472 * Returns the double at the current position and increases the position by
473 * 8.
474 * <p>
475 * The 8 bytes starting from the current position are composed into a double
476 * according to the current byte order and returned.
477 *
478 * @return the double at the current position.
479 * @exception BufferUnderflowException
480 * if the position is greater than {@code limit - 8}.
481 */
482 public abstract double getDouble();
483
484 /**
485 * Returns the double at the specified index.
486 * <p>
487 * The 8 bytes starting at the specified index are composed into a double
488 * according to the current byte order and returned. The position is not
489 * changed.
490 *
491 * @param index
492 * the index, must not be negative and equal or less than
493 * {@code limit - 8}.
494 * @return the double at the specified index.
495 * @exception IndexOutOfBoundsException
496 * if {@code index} is invalid.
497 */
498 public abstract double getDouble(int index);
499
500 /**
501 * Returns the float at the current position and increases the position by
502 * 4.
503 * <p>
504 * The 4 bytes starting at the current position are composed into a float
505 * according to the current byte order and returned.
506 *
507 * @return the float at the current position.
508 * @exception BufferUnderflowException
509 * if the position is greater than {@code limit - 4}.
510 */
511 public abstract float getFloat();
512
513 /**
514 * Returns the float at the specified index.
515 * <p>
516 * The 4 bytes starting at the specified index are composed into a float
517 * according to the current byte order and returned. The position is not
518 * changed.
519 *
520 * @param index
521 * the index, must not be negative and equal or less than
522 * {@code limit - 4}.
523 * @return the float at the specified index.
524 * @exception IndexOutOfBoundsException
525 * if {@code index} is invalid.
526 */
527 public abstract float getFloat(int index);
528
529 /**
530 * Returns the int at the current position and increases the position by 4.
531 * <p>
532 * The 4 bytes starting at the current position are composed into a int
533 * according to the current byte order and returned.
534 *
535 * @return the int at the current position.
536 * @exception BufferUnderflowException
537 * if the position is greater than {@code limit - 4}.
538 */
539 public abstract int getInt();
540
541 /**
542 * Returns the int at the specified index.
543 * <p>
544 * The 4 bytes starting at the specified index are composed into a int
545 * according to the current byte order and returned. The position is not
546 * changed.
547 *
548 * @param index
549 * the index, must not be negative and equal or less than
550 * {@code limit - 4}.
551 * @return the int at the specified index.
552 * @exception IndexOutOfBoundsException
553 * if {@code index} is invalid.
554 */
555 public abstract int getInt(int index);
556
557 /**
558 * Returns the long at the current position and increases the position by 8.
559 * <p>
560 * The 8 bytes starting at the current position are composed into a long
561 * according to the current byte order and returned.
562 *
563 * @return the long at the current position.
564 * @exception BufferUnderflowException
565 * if the position is greater than {@code limit - 8}.
566 */
567 public abstract long getLong();
568
569 /**
570 * Returns the long at the specified index.
571 * <p>
572 * The 8 bytes starting at the specified index are composed into a long
573 * according to the current byte order and returned. The position is not
574 * changed.
575 *
576 * @param index
577 * the index, must not be negative and equal or less than
578 * {@code limit - 8}.
579 * @return the long at the specified index.
580 * @exception IndexOutOfBoundsException
581 * if {@code index} is invalid.
582 */
583 public abstract long getLong(int index);
584
585 /**
586 * Returns the short at the current position and increases the position by 2.
587 * <p>
588 * The 2 bytes starting at the current position are composed into a short
589 * according to the current byte order and returned.
590 *
591 * @return the short at the current position.
592 * @exception BufferUnderflowException
593 * if the position is greater than {@code limit - 2}.
594 */
595 public abstract short getShort();
596
597 /**
598 * Returns the short at the specified index.
599 * <p>
600 * The 2 bytes starting at the specified index are composed into a short
601 * according to the current byte order and returned. The position is not
602 * changed.
603 *
604 * @param index
605 * the index, must not be negative and equal or less than
606 * {@code limit - 2}.
607 * @return the short at the specified index.
608 * @exception IndexOutOfBoundsException
609 * if {@code index} is invalid.
610 */
611 public abstract short getShort(int index);
612
613 /**
614 * Indicates whether this buffer is based on a byte array and provides
615 * read/write access.
616 *
617 * @return {@code true} if this buffer is based on a byte array and provides
618 * read/write access, {@code false} otherwise.
619 */
620 public final boolean hasArray() {
621 return protectedHasArray();
622 }
623
624 /**
625 * Calculates this buffer's hash code from the remaining chars. The
626 * position, limit, capacity and mark don't affect the hash code.
627 *
628 * @return the hash code calculated from the remaining bytes.
629 */
630 @Override
631 public int hashCode() {
632 int myPosition = position;
633 int hash = 0;
634 while (myPosition < limit) {
635 hash = hash + get(myPosition++);
636 }
637 return hash;
638 }
639
640 /**
641 * Indicates whether this buffer is direct.
642 *
643 * @return {@code true} if this buffer is direct, {@code false} otherwise.
644 */
645 public abstract boolean isDirect();
646
647 /**
648 * Returns the byte order used by this buffer when converting bytes from/to
649 * other primitive types.
650 * <p>
651 * The default byte order of byte buffer is always
652 * {@link ByteOrder#BIG_ENDIAN BIG_ENDIAN}
653 *
654 * @return the byte order used by this buffer when converting bytes from/to
655 * other primitive types.
656 */
657 public final ByteOrder order() {
658 return order == Endianness.BIG_ENDIAN ? ByteOrder.BIG_ENDIAN
659 : ByteOrder.LITTLE_ENDIAN;
660 }
661
662 /**
663 * Sets the byte order of this buffer.
664 *
665 * @param byteOrder
666 * the byte order to set. If {@code null} then the order
667 * will be {@link ByteOrder#LITTLE_ENDIAN LITTLE_ENDIAN}.
668 * @return this buffer.
669 * @see ByteOrder
670 */
671 public final ByteBuffer order(ByteOrder byteOrder) {
672 return orderImpl(byteOrder);
673 }
674
675 ByteBuffer orderImpl(ByteOrder byteOrder) {
676 order = byteOrder == ByteOrder.BIG_ENDIAN ? Endianness.BIG_ENDIAN
677 : Endianness.LITTLE_ENDIAN;
678 return this;
679 }
680
681 /**
682 * Child class implements this method to realize {@code array()}.
683 *
684 * @see #array()
685 */
686 abstract byte[] protectedArray();
687
688 /**
689 * Child class implements this method to realize {@code arrayOffset()}.
690 *
691 * @see #arrayOffset()
692 */
693 abstract int protectedArrayOffset();
694
695 /**
696 * Child class implements this method to realize {@code hasArray()}.
697 *
698 * @see #hasArray()
699 */
700 abstract boolean protectedHasArray();
701
702 /**
703 * Writes the given byte to the current position and increases the position
704 * by 1.
705 *
706 * @param b
707 * the byte to write.
708 * @return this buffer.
709 * @exception BufferOverflowException
710 * if position is equal or greater than limit.
711 * @exception ReadOnlyBufferException
712 * if no changes may be made to the contents of this buffer.
713 */
714 public abstract ByteBuffer put(byte b);
715
716 /**
717 * Writes bytes in the given byte array to the current position and
718 * increases the position by the number of bytes written.
719 * <p>
720 * Calling this method has the same effect as
721 * {@code put(src, 0, src.length)}.
722 *
723 * @param src
724 * the source byte array.
725 * @return this buffer.
726 * @exception BufferOverflowException
727 * if {@code remaining()} is less than {@code src.length}.
728 * @exception ReadOnlyBufferException
729 * if no changes may be made to the contents of this buffer.
730 */
731 public final ByteBuffer put(byte[] src) {
732 return put(src, 0, src.length);
733 }
734
735 /**
736 * Writes bytes in the given byte array, starting from the specified offset,
737 * to the current position and increases the position by the number of bytes
738 * written.
739 *
740 * @param src
741 * the source byte array.
742 * @param off
743 * the offset of byte array, must not be negative and not greater
744 * than {@code src.length}.
745 * @param len
746 * the number of bytes to write, must not be negative and not
747 * greater than {@code src.length - off}.
748 * @return this buffer.
749 * @exception BufferOverflowException
750 * if {@code remaining()} is less than {@code len}.
751 * @exception IndexOutOfBoundsException
752 * if either {@code off} or {@code len} is invalid.
753 * @exception ReadOnlyBufferException
754 * if no changes may be made to the contents of this buffer.
755 */
756 public ByteBuffer put(byte[] src, int off, int len) {
757 int length = src.length;
758 if ((off < 0 ) || (len < 0) || ((long)off + (long)len > length)) {
759 throw new IndexOutOfBoundsException();
760 }
761
762 if (len > remaining()) {
763 throw new BufferOverflowException();
764 }
765 for (int i = off; i < off + len; i++) {
766 put(src[i]);
767 }
768 return this;
769 }
770
771 /**
772 * Writes all the remaining bytes of the {@code src} byte buffer to this
773 * buffer's current position, and increases both buffers' position by the
774 * number of bytes copied.
775 *
776 * @param src
777 * the source byte buffer.
778 * @return this buffer.
779 * @exception BufferOverflowException
780 * if {@code src.remaining()} is greater than this buffer's
781 * {@code remaining()}.
782 * @exception IllegalArgumentException
783 * if {@code src} is this buffer.
784 * @exception ReadOnlyBufferException
785 * if no changes may be made to the contents of this buffer.
786 */
787 public ByteBuffer put(ByteBuffer src) {
788 if (src == this) {
789 throw new IllegalArgumentException();
790 }
791 if (src.remaining() > remaining()) {
792 throw new BufferOverflowException();
793 }
794 byte[] contents = new byte[src.remaining()];
795 src.get(contents);
796 put(contents);
797 return this;
798 }
799
800 /**
801 * Write a byte to the specified index of this buffer without changing the
802 * position.
803 *
804 * @param index
805 * the index, must not be negative and less than the limit.
806 * @param b
807 * the byte to write.
808 * @return this buffer.
809 * @exception IndexOutOfBoundsException
810 * if {@code index} is invalid.
811 * @exception ReadOnlyBufferException
812 * if no changes may be made to the contents of this buffer.
813 */
814 public abstract ByteBuffer put(int index, byte b);
815
816 /**
817 * Writes the given char to the current position and increases the position
818 * by 2.
819 * <p>
820 * The char is converted to bytes using the current byte order.
821 *
822 * @param value
823 * the char to write.
824 * @return this buffer.
825 * @exception BufferOverflowException
826 * if position is greater than {@code limit - 2}.
827 * @exception ReadOnlyBufferException
828 * if no changes may be made to the contents of this buffer.
829 */
830 public abstract ByteBuffer putChar(char value);
831
832 /**
833 * Writes the given char to the specified index of this buffer.
834 * <p>
835 * The char is converted to bytes using the current byte order. The position
836 * is not changed.
837 *
838 * @param index
839 * the index, must not be negative and equal or less than
840 * {@code limit - 2}.
841 * @param value
842 * the char to write.
843 * @return this buffer.
844 * @exception IndexOutOfBoundsException
845 * if {@code index} is invalid.
846 * @exception ReadOnlyBufferException
847 * if no changes may be made to the contents of this buffer.
848 */
849 public abstract ByteBuffer putChar(int index, char value);
850
851 /**
852 * Writes the given double to the current position and increases the position
853 * by 8.
854 * <p>
855 * The double is converted to bytes using the current byte order.
856 *
857 * @param value
858 * the double to write.
859 * @return this buffer.
860 * @exception BufferOverflowException
861 * if position is greater than {@code limit - 8}.
862 * @exception ReadOnlyBufferException
863 * if no changes may be made to the contents of this buffer.
864 */
865 public abstract ByteBuffer putDouble(double value);
866
867 /**
868 * Writes the given double to the specified index of this buffer.
869 * <p>
870 * The double is converted to bytes using the current byte order. The
871 * position is not changed.
872 *
873 * @param index
874 * the index, must not be negative and equal or less than
875 * {@code limit - 8}.
876 * @param value
877 * the double to write.
878 * @return this buffer.
879 * @exception IndexOutOfBoundsException
880 * if {@code index} is invalid.
881 * @exception ReadOnlyBufferException
882 * if no changes may be made to the contents of this buffer.
883 */
884 public abstract ByteBuffer putDouble(int index, double value);
885
886 /**
887 * Writes the given float to the current position and increases the position
888 * by 4.
889 * <p>
890 * The float is converted to bytes using the current byte order.
891 *
892 * @param value
893 * the float to write.
894 * @return this buffer.
895 * @exception BufferOverflowException
896 * if position is greater than {@code limit - 4}.
897 * @exception ReadOnlyBufferException
898 * if no changes may be made to the contents of this buffer.
899 */
900 public abstract ByteBuffer putFloat(float value);
901
902 /**
903 * Writes the given float to the specified index of this buffer.
904 * <p>
905 * The float is converted to bytes using the current byte order. The
906 * position is not changed.
907 *
908 * @param index
909 * the index, must not be negative and equal or less than
910 * {@code limit - 4}.
911 * @param value
912 * the float to write.
913 * @return this buffer.
914 * @exception IndexOutOfBoundsException
915 * if {@code index} is invalid.
916 * @exception ReadOnlyBufferException
917 * if no changes may be made to the contents of this buffer.
918 */
919 public abstract ByteBuffer putFloat(int index, float value);
920
921 /**
922 * Writes the given int to the current position and increases the position by
923 * 4.
924 * <p>
925 * The int is converted to bytes using the current byte order.
926 *
927 * @param value
928 * the int to write.
929 * @return this buffer.
930 * @exception BufferOverflowException
931 * if position is greater than {@code limit - 4}.
932 * @exception ReadOnlyBufferException
933 * if no changes may be made to the contents of this buffer.
934 */
935 public abstract ByteBuffer putInt(int value);
936
937 /**
938 * Writes the given int to the specified index of this buffer.
939 * <p>
940 * The int is converted to bytes using the current byte order. The position
941 * is not changed.
942 *
943 * @param index
944 * the index, must not be negative and equal or less than
945 * {@code limit - 4}.
946 * @param value
947 * the int to write.
948 * @return this buffer.
949 * @exception IndexOutOfBoundsException
950 * if {@code index} is invalid.
951 * @exception ReadOnlyBufferException
952 * if no changes may be made to the contents of this buffer.
953 */
954 public abstract ByteBuffer putInt(int index, int value);
955
956 /**
957 * Writes the given long to the current position and increases the position
958 * by 8.
959 * <p>
960 * The long is converted to bytes using the current byte order.
961 *
962 * @param value
963 * the long to write.
964 * @return this buffer.
965 * @exception BufferOverflowException
966 * if position is greater than {@code limit - 8}.
967 * @exception ReadOnlyBufferException
968 * if no changes may be made to the contents of this buffer.
969 */
970 public abstract ByteBuffer putLong(long value);
971
972 /**
973 * Writes the given long to the specified index of this buffer.
974 * <p>
975 * The long is converted to bytes using the current byte order. The position
976 * is not changed.
977 *
978 * @param index
979 * the index, must not be negative and equal or less than
980 * {@code limit - 8}.
981 * @param value
982 * the long to write.
983 * @return this buffer.
984 * @exception IndexOutOfBoundsException
985 * if {@code index} is invalid.
986 * @exception ReadOnlyBufferException
987 * if no changes may be made to the contents of this buffer.
988 */
989 public abstract ByteBuffer putLong(int index, long value);
990
991 /**
992 * Writes the given short to the current position and increases the position
993 * by 2.
994 * <p>
995 * The short is converted to bytes using the current byte order.
996 *
997 * @param value
998 * the short to write.
999 * @return this buffer.
1000 * @exception BufferOverflowException
1001 * if position is greater than {@code limit - 2}.
1002 * @exception ReadOnlyBufferException
1003 * if no changes may be made to the contents of this buffer.
1004 */
1005 public abstract ByteBuffer putShort(short value);
1006
1007 /**
1008 * Writes the given short to the specified index of this buffer.
1009 * <p>
1010 * The short is converted to bytes using the current byte order. The
1011 * position is not changed.
1012 *
1013 * @param index
1014 * the index, must not be negative and equal or less than
1015 * {@code limit - 2}.
1016 * @param value
1017 * the short to write.
1018 * @return this buffer.
1019 * @exception IndexOutOfBoundsException
1020 * if {@code index} is invalid.
1021 * @exception ReadOnlyBufferException
1022 * if no changes may be made to the contents of this buffer.
1023 */
1024 public abstract ByteBuffer putShort(int index, short value);
1025
1026 /**
1027 * Returns a sliced buffer that shares its content with this buffer.
1028 * <p>
1029 * The sliced buffer's capacity will be this buffer's
1030 * {@code remaining()}, and it's zero position will correspond to
1031 * this buffer's current position. The new buffer's position will be 0,
1032 * limit will be its capacity, and its mark is cleared. The new buffer's
1033 * read-only property and byte order are the same as this buffer's.
1034 * <p>
1035 * The new buffer shares its content with this buffer, which means either
1036 * buffer's change of content will be visible to the other. The two buffer's
1037 * position, limit and mark are independent.
1038 *
1039 * @return a sliced buffer that shares its content with this buffer.
1040 */
1041 public abstract ByteBuffer slice();
1042
1043 /**
1044 * Returns a string representing the state of this byte buffer.
1045 *
1046 * @return a string representing the state of this byte buffer.
1047 */
1048 @Override
1049 public String toString() {
1050 StringBuilder buf = new StringBuilder();
1051 buf.append(getClass().getName());
1052 buf.append(", status: capacity="); //$NON-NLS-1$
1053 buf.append(capacity());
1054 buf.append(" position="); //$NON-NLS-1$
1055 buf.append(position());
1056 buf.append(" limit="); //$NON-NLS-1$
1057 buf.append(limit());
1058 return buf.toString();
1059 }
1060 }
Save This Page