1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 *
19 */
20 package org.apache.mina.core.buffer;
21
22 import java.io.IOException;
23 import java.io.InputStream;
24 import java.io.OutputStream;
25 import java.nio.BufferOverflowException;
26 import java.nio.ByteBuffer;
27 import java.nio.ByteOrder;
28 import java.nio.CharBuffer;
29 import java.nio.DoubleBuffer;
30 import java.nio.FloatBuffer;
31 import java.nio.IntBuffer;
32 import java.nio.LongBuffer;
33 import java.nio.ShortBuffer;
34 import java.nio.charset.CharacterCodingException;
35 import java.nio.charset.CharsetDecoder;
36 import java.nio.charset.CharsetEncoder;
37 import java.util.EnumSet;
38 import java.util.Set;
39
40 import org.apache.mina.core.session.IoSession;
41
42 /**
43 * A byte buffer used by MINA applications.
44 * <p>
45 * This is a replacement for {@link ByteBuffer}. Please refer to
46 * {@link ByteBuffer} documentation for preliminary usage. MINA does
47 * not use NIO {@link ByteBuffer} directly for two reasons:
48 * <ul>
49 * <li>It doesn't provide useful getters and putters such as
50 * <code>fill</code>, <code>get/putString</code>, and
51 * <code>get/putAsciiInt()</code> enough.</li>
52 * <li>It is difficult to write variable-length data due to its fixed
53 * capacity</li>
54 * </ul>
55 * </p>
56 *
57 * <h2>Allocation</h2>
58 * <p>
59 * You can allocate a new heap buffer.
60 * <pre>
61 * IoBuffer buf = IoBuffer.allocate(1024, false);
62 * </pre>
63 * you can also allocate a new direct buffer:
64 * <pre>
65 * IoBuffer buf = IoBuffer.allocate(1024, true);
66 * </pre>
67 * or you can set the default buffer type.
68 * <pre>
69 * // Allocate heap buffer by default.
70 * IoBuffer.setUseDirectBuffer(false);
71 * // A new heap buffer is returned.
72 * IoBuffer buf = IoBuffer.allocate(1024);
73 * </pre>
74 * </p>
75 *
76 * <h2>Wrapping existing NIO buffers and arrays</h2>
77 * <p>
78 * This class provides a few <tt>wrap(...)</tt> methods that wraps
79 * any NIO buffers and byte arrays.
80 *
81 * <h2>AutoExpand</h2>
82 * <p>
83 * Writing variable-length data using NIO <tt>ByteBuffers</tt> is not really
84 * easy, and it is because its size is fixed. {@link IoBuffer} introduces
85 * <tt>autoExpand</tt> property. If <tt>autoExpand</tt> property is true, you
86 * never get {@link BufferOverflowException} or
87 * {@link IndexOutOfBoundsException} (except when index is negative).
88 * It automatically expands its capacity and limit value. For example:
89 * <pre>
90 * String greeting = messageBundle.getMessage( "hello" );
91 * IoBuffer buf = IoBuffer.allocate( 16 );
92 * // Turn on autoExpand (it is off by default)
93 * buf.setAutoExpand( true );
94 * buf.putString( greeting, utf8encoder );
95 * </pre>
96 * The underlying {@link ByteBuffer} is reallocated by {@link IoBuffer} behind
97 * the scene if the encoded data is larger than 16 bytes in the example above.
98 * Its capacity will double, and its limit will increase to the last position
99 * the string is written.
100 * </p>
101 *
102 * <h2>AutoShrink</h2>
103 * <p>
104 * You might also want to decrease the capacity of the buffer when most
105 * of the allocated memory area is not being used. {@link IoBuffer} provides
106 * <tt>autoShrink</tt> property to take care of this issue. If
107 * <tt>autoShrink</tt> is turned on, {@link IoBuffer} halves the capacity
108 * of the buffer when {@link #compact()} is invoked and only 1/4 or less of
109 * the current capacity is being used.
110 * <p>
111 * You can also {@link #shrink()} method manually to shrink the capacity of
112 * the buffer.
113 * <p>
114 * The underlying {@link ByteBuffer} is reallocated by {@link IoBuffer} behind
115 * the scene, and therefore {@link #buf()} will return a different
116 * {@link ByteBuffer} instance once capacity changes. Please also note
117 * {@link #compact()} or {@link #shrink()} will not decrease the capacity if
118 * the new capacity is less than the {@link #minimumCapacity()} of the buffer.
119 *
120 * <h2>Derived Buffers</h2>
121 * <p>
122 * Derived buffers are the buffers which were created by
123 * {@link #duplicate()}, {@link #slice()}, or {@link #asReadOnlyBuffer()}.
124 * They are useful especially when you broadcast the same messages to
125 * multiple {@link IoSession}s. Please note that the buffer derived from and
126 * its derived buffers are not both auto-expandable neither auto-shrinkable.
127 * Trying to call {@link #setAutoExpand(boolean)} or {@link #setAutoShrink(boolean)}
128 * with <tt>true</tt> parameter will raise an {@link IllegalStateException}.
129 * </p>
130 *
131 * <h2>Changing Buffer Allocation Policy</h2>
132 * <p>
133 * {@link IoBufferAllocator} interface lets you override the default buffer
134 * management behavior. There are two allocators provided out-of-the-box:
135 * <ul>
136 * <li>{@link SimpleBufferAllocator} (default)</li>
137 * <li>{@link CachedBufferAllocator}</li>
138 * </ul>
139 * You can implement your own allocator and use it by calling
140 * {@link #setAllocator(IoBufferAllocator)}.
141 * </p>
142 *
143 * @author The Apache MINA Project (dev@mina.apache.org)
144 */
145 public abstract class IoBuffer implements Comparable<IoBuffer> {
146 /** The allocator used to create new buffers */
147 private static IoBufferAllocator allocator = new SimpleBufferAllocator();
148
149 /** A flag indicating which type of buffer we are using : heap or direct */
150 private static boolean useDirectBuffer = false;
151
152 /**
153 * Returns the allocator used by existing and new buffers
154 */
155 public static IoBufferAllocator getAllocator() {
156 return allocator;
157 }
158
159 /**
160 * Sets the allocator used by existing and new buffers
161 */
162 public static void setAllocator(IoBufferAllocator newAllocator) {
163 if (newAllocator == null) {
164 throw new NullPointerException("allocator");
165 }
166
167 IoBufferAllocator oldAllocator = allocator;
168
169 allocator = newAllocator;
170
171 if (null != oldAllocator) {
172 oldAllocator.dispose();
173 }
174 }
175
176 /**
177 * Returns <tt>true</tt> if and only if a direct buffer is allocated
178 * by default when the type of the new buffer is not specified. The
179 * default value is <tt>false</tt>.
180 */
181 public static boolean isUseDirectBuffer() {
182 return useDirectBuffer;
183 }
184
185 /**
186 * Sets if a direct buffer should be allocated by default when the
187 * type of the new buffer is not specified. The default value is
188 * <tt>false</tt>.
189 */
190 public static void setUseDirectBuffer(boolean useDirectBuffer) {
191 IoBuffer.useDirectBuffer = useDirectBuffer;
192 }
193
194 /**
195 * Returns the direct or heap buffer which is capable to store the
196 * specified amount of bytes.
197 *
198 * @param capacity the capacity of the buffer
199 *
200 * @see #setUseDirectBuffer(boolean)
201 */
202 public static IoBuffer allocate(int capacity) {
203 return allocate(capacity, useDirectBuffer);
204 }
205
206 /**
207 * Returns the buffer which is capable of the specified size.
208 *
209 * @param capacity the capacity of the buffer
210 * @param direct <tt>true</tt> to get a direct buffer,
211 * <tt>false</tt> to get a heap buffer.
212 */
213 public static IoBuffer allocate(int capacity, boolean direct) {
214 if (capacity < 0) {
215 throw new IllegalArgumentException("capacity: " + capacity);
216 }
217
218 return allocator.allocate(capacity, direct);
219 }
220
221 /**
222 * Wraps the specified NIO {@link ByteBuffer} into MINA buffer.
223 */
224 public static IoBuffer wrap(ByteBuffer nioBuffer) {
225 return allocator.wrap(nioBuffer);
226 }
227
228 /**
229 * Wraps the specified byte array into MINA heap buffer.
230 */
231 public static IoBuffer wrap(byte[] byteArray) {
232 return wrap(ByteBuffer.wrap(byteArray));
233 }
234
235 /**
236 * Wraps the specified byte array into MINA heap buffer.
237 */
238 public static IoBuffer wrap(byte[] byteArray, int offset, int length) {
239 return wrap(ByteBuffer.wrap(byteArray, offset, length));
240 }
241
242 /**
243 * Normalizes the specified capacity of the buffer to power of 2,
244 * which is often helpful for optimal memory usage and performance.
245 * If it is greater than or equal to {@link Integer#MAX_VALUE}, it
246 * returns {@link Integer#MAX_VALUE}. If it is zero, it returns zero.
247 */
248 protected static int normalizeCapacity(int requestedCapacity) {
249 switch (requestedCapacity) {
250 case 0:
251 case 1 << 0:
252 case 1 << 1:
253 case 1 << 2:
254 case 1 << 3:
255 case 1 << 4:
256 case 1 << 5:
257 case 1 << 6:
258 case 1 << 7:
259 case 1 << 8:
260 case 1 << 9:
261 case 1 << 10:
262 case 1 << 11:
263 case 1 << 12:
264 case 1 << 13:
265 case 1 << 14:
266 case 1 << 15:
267 case 1 << 16:
268 case 1 << 17:
269 case 1 << 18:
270 case 1 << 19:
271 case 1 << 21:
272 case 1 << 22:
273 case 1 << 23:
274 case 1 << 24:
275 case 1 << 25:
276 case 1 << 26:
277 case 1 << 27:
278 case 1 << 28:
279 case 1 << 29:
280 case 1 << 30:
281 case Integer.MAX_VALUE:
282 return requestedCapacity;
283 }
284
285 int newCapacity = 1;
286 while (newCapacity < requestedCapacity) {
287 newCapacity <<= 1;
288 if (newCapacity < 0) {
289 return Integer.MAX_VALUE;
290 }
291 }
292 return newCapacity;
293 }
294
295 /**
296 * Creates a new instance. This is an empty constructor.
297 */
298 protected IoBuffer() {
299 // Do nothing
300 }
301
302 /**
303 * Declares this buffer and all its derived buffers are not used anymore
304 * so that it can be reused by some {@link IoBufferAllocator} implementations.
305 * It is not mandatory to call this method, but you might want to invoke this
306 * method for maximum performance.
307 */
308 public abstract void free();
309
310 /**
311 * Returns the underlying NIO buffer instance.
312 */
313 public abstract ByteBuffer buf();
314
315 /**
316 * @see ByteBuffer#isDirect()
317 */
318 public abstract boolean isDirect();
319
320 /**
321 * returns <tt>true</tt> if and only if this buffer is derived from other buffer
322 * via {@link #duplicate()}, {@link #slice()} or {@link #asReadOnlyBuffer()}.
323 */
324 public abstract boolean isDerived();
325
326 /**
327 * @see ByteBuffer#isReadOnly()
328 */
329 public abstract boolean isReadOnly();
330
331 /**
332 * Returns the minimum capacity of this buffer which is used to determine
333 * the new capacity of the buffer shrunk by {@link #compact()} and
334 * {@link #shrink()} operation. The default value is the initial capacity
335 * of the buffer.
336 */
337 public abstract int minimumCapacity();
338
339 /**
340 * Sets the minimum capacity of this buffer which is used to determine
341 * the new capacity of the buffer shrunk by {@link #compact()} and
342 * {@link #shrink()} operation. The default value is the initial capacity
343 * of the buffer.
344 */
345 public abstract IoBuffer minimumCapacity(int minimumCapacity);
346
347 /**
348 * @see ByteBuffer#capacity()
349 */
350 public abstract int capacity();
351
352 /**
353 * Increases the capacity of this buffer. If the new capacity is less than
354 * or equal to the current capacity, this method returns silently. If the
355 * new capacity is greater than the current capacity, the buffer is
356 * reallocated while retaining the position, limit, mark and the content
357 * of the buffer.
358 */
359 public abstract IoBuffer capacity(int newCapacity);
360
361 /**
362 * Returns <tt>true</tt> if and only if <tt>autoExpand</tt> is turned on.
363 */
364 public abstract boolean isAutoExpand();
365
366 /**
367 * Turns on or off <tt>autoExpand</tt>.
368 */
369 public abstract IoBuffer setAutoExpand(boolean autoExpand);
370
371 /**
372 * Returns <tt>true</tt> if and only if <tt>autoShrink</tt> is turned on.
373 */
374 public abstract boolean isAutoShrink();
375
376 /**
377 * Turns on or off <tt>autoShrink</tt>.
378 */
379 public abstract IoBuffer setAutoShrink(boolean autoShrink);
380
381 /**
382 * Changes the capacity and limit of this buffer so this buffer get
383 * the specified <tt>expectedRemaining</tt> room from the current position.
384 * This method works even if you didn't set <tt>autoExpand</tt> to
385 * <tt>true</tt>.
386 */
387 public abstract IoBuffer expand(int expectedRemaining);
388
389 /**
390 * Changes the capacity and limit of this buffer so this buffer get
391 * the specified <tt>expectedRemaining</tt> room from the specified
392 * <tt>position</tt>.
393 * This method works even if you didn't set <tt>autoExpand</tt> to
394 * <tt>true</tt>.
395 */
396 public abstract IoBuffer expand(int position, int expectedRemaining);
397
398 /**
399 * Changes the capacity of this buffer so this buffer occupies as less
400 * memory as possible while retaining the position, limit and the
401 * buffer content between the position and limit. The capacity of the
402 * buffer never becomes less than {@link #minimumCapacity()}.
403 * The mark is discarded once the capacity changes.
404 */
405 public abstract IoBuffer shrink();
406
407 /**
408 * @see java.nio.Buffer#position()
409 */
410 public abstract int position();
411
412 /**
413 * @see java.nio.Buffer#position(int)
414 */
415 public abstract IoBuffer position(int newPosition);
416
417 /**
418 * @see java.nio.Buffer#limit()
419 */
420 public abstract int limit();
421
422 /**
423 * @see java.nio.Buffer#limit(int)
424 */
425 public abstract IoBuffer limit(int newLimit);
426
427 /**
428 * @see java.nio.Buffer#mark()
429 */
430 public abstract IoBuffer mark();
431
432 /**
433 * Returns the position of the current mark. This method returns <tt>-1</tt> if no
434 * mark is set.
435 */
436 public abstract int markValue();
437
438 /**
439 * @see java.nio.Buffer#reset()
440 */
441 public abstract IoBuffer reset();
442
443 /**
444 * @see java.nio.Buffer#clear()
445 */
446 public abstract IoBuffer clear();
447
448 /**
449 * Clears this buffer and fills its content with <tt>NUL</tt>.
450 * The position is set to zero, the limit is set to the capacity,
451 * and the mark is discarded.
452 */
453 public abstract IoBuffer sweep();
454
455 /**double
456 * Clears this buffer and fills its content with <tt>value</tt>.
457 * The position is set to zero, the limit is set to the capacity,
458 * and the mark is discarded.
459 */
460 public abstract IoBuffer sweep(byte value);
461
462 /**
463 * @see java.nio.Buffer#flip()
464 */
465 public abstract IoBuffer flip();
466
467 /**
468 * @see java.nio.Buffer#rewind()
469 */
470 public abstract IoBuffer rewind();
471
472 /**
473 * @see java.nio.Buffer#remaining()
474 */
475 public abstract int remaining();
476
477 /**
478 * @see java.nio.Buffer#hasRemaining()
479 */
480 public abstract boolean hasRemaining();
481
482 /**
483 * @see ByteBuffer#duplicate()
484 */
485 public abstract IoBuffer duplicate();
486
487 /**
488 * @see ByteBuffer#slice()
489 */
490 public abstract IoBuffer slice();
491
492 /**
493 * @see ByteBuffer#asReadOnlyBuffer()
494 */
495 public abstract IoBuffer asReadOnlyBuffer();
496
497 /**
498 * @see ByteBuffer#hasArray()
499 */
500 public abstract boolean hasArray();
501
502 /**
503 * @see ByteBuffer#array()
504 */
505 public abstract byte[] array();
506
507 /**
508 * @see ByteBuffer#arrayOffset()
509 */
510 public abstract int arrayOffset();
511
512 /**
513 * @see ByteBuffer#get()
514 */
515 public abstract byte get();
516
517 /**
518 * Reads one unsigned byte as a short integer.
519 */
520 public abstract short getUnsigned();
521
522 /**
523 * @see ByteBuffer#put(byte)
524 */
525 public abstract IoBuffer put(byte b);
526
527 /**
528 * @see ByteBuffer#get(int)
529 */
530 public abstract byte get(int index);
531
532 /**
533 * Reads one byte as an unsigned short integer.
534 */
535 public abstract short getUnsigned(int index);
536
537 /**
538 * @see ByteBuffer#put(int, byte)
539 */
540 public abstract IoBuffer put(int index, byte b);
541
542 /**
543 * @see ByteBuffer#get(byte[], int, int)
544 */
545 public abstract IoBuffer get(byte[] dst, int offset, int length);
546
547 /**
548 * @see ByteBuffer#get(byte[])
549 */
550 public abstract IoBuffer get(byte[] dst);
551
552 /**
553 * TODO document me.
554 */
555 public abstract IoBuffer getSlice(int index, int length);
556
557 /**
558 * TODO document me.
559 */
560 public abstract IoBuffer getSlice(int length);
561
562 /**
563 * Writes the content of the specified <tt>src</tt> into this buffer.
564 */
565 public abstract IoBuffer put(ByteBuffer src);
566
567 /**
568 * Writes the content of the specified <tt>src</tt> into this buffer.
569 */
570 public abstract IoBuffer put(IoBuffer src);
571
572 /**
573 * @see ByteBuffer#put(byte[], int, int)
574 */
575 public abstract IoBuffer put(byte[] src, int offset, int length);
576
577 /**
578 * @see ByteBuffer#put(byte[])
579 */
580 public abstract IoBuffer put(byte[] src);
581
582 /**
583 * @see ByteBuffer#compact()
584 */
585 public abstract IoBuffer compact();
586
587 /**
588 * @see ByteBuffer#order()
589 */
590 public abstract ByteOrder order();
591
592 /**
593 * @see ByteBuffer#order(ByteOrder)
594 */
595 public abstract IoBuffer order(ByteOrder bo);
596
597 /**
598 * @see ByteBuffer#getChar()
599 */
600 public abstract char getChar();
601
602 /**
603 * @see ByteBuffer#putChar(char)
604 */
605 public abstract IoBuffer putChar(char value);
606
607 /**
608 * @see ByteBuffer#getChar(int)
609 */
610 public abstract char getChar(int index);
611
612 /**
613 * @see ByteBuffer#putChar(int, char)
614 */
615 public abstract IoBuffer putChar(int index, char value);
616
617 /**
618 * @see ByteBuffer#asCharBuffer()
619 */
620 public abstract CharBuffer asCharBuffer();
621
622 /**
623 * @see ByteBuffer#getShort()
624 */
625 public abstract short getShort();
626
627 /**
628 * Reads two bytes unsigned integer.
629 */
630 public abstract int getUnsignedShort();
631
632 /**
633 * @see ByteBuffer#putShort(short)
634 */
635 public abstract IoBuffer putShort(short value);
636
637 /**
638 * @see ByteBuffer#getShort()
639 */
640 public abstract short getShort(int index);
641
642 /**
643 * Reads two bytes unsigned integer.
644 */
645 public abstract int getUnsignedShort(int index);
646
647 /**
648 * @see ByteBuffer#putShort(int, short)
649 */
650 public abstract IoBuffer putShort(int index, short value);
651
652 /**
653 * @see ByteBuffer#asShortBuffer()
654 */
655 public abstract ShortBuffer asShortBuffer();
656
657 /**
658 * @see ByteBuffer#getInt()
659 */
660 public abstract int getInt();
661
662 /**
663 * Reads four bytes unsigned integer.
664 */
665 public abstract long getUnsignedInt();
666
667 /**
668 * Relative <i>get</i> method for reading a medium int value.
669 *
670 * <p> Reads the next three bytes at this buffer's current position,
671 * composing them into an int value according to the current byte order,
672 * and then increments the position by three.</p>
673 *
674 * @return The medium int value at the buffer's current position
675 */
676 public abstract int getMediumInt();
677
678 /**
679 * Relative <i>get</i> method for reading an unsigned medium int value.
680 *
681 * <p> Reads the next three bytes at this buffer's current position,
682 * composing them into an int value according to the current byte order,
683 * and then increments the position by three.</p>
684 *
685 * @return The unsigned medium int value at the buffer's current position
686 */
687 public abstract int getUnsignedMediumInt();
688
689 /**
690 * Absolute <i>get</i> method for reading a medium int value.
691 *
692 * <p> Reads the next three bytes at this buffer's current position,
693 * composing them into an int value according to the current byte order.</p>
694 *
695 * @param index The index from which the medium int will be read
696 * @return The medium int value at the given index
697 *
698 * @throws IndexOutOfBoundsException
699 * If <tt>index</tt> is negative
700 * or not smaller than the buffer's limit
701 */
702 public abstract int getMediumInt(int index);
703
704 /**
705 * Absolute <i>get</i> method for reading an unsigned medium int value.
706 *
707 * <p> Reads the next three bytes at this buffer's current position,
708 * composing them into an int value according to the current byte order.</p>
709 *
710 * @param index The index from which the unsigned medium int will be read
711 * @return The unsigned medium int value at the given index
712 *
713 * @throws IndexOutOfBoundsException
714 * If <tt>index</tt> is negative
715 * or not smaller than the buffer's limit
716 */
717 public abstract int getUnsignedMediumInt(int index);
718
719 /**
720 * Relative <i>put</i> method for writing a medium int
721 * value.
722 *
723 * <p> Writes three bytes containing the given int value, in the
724 * current byte order, into this buffer at the current position, and then
725 * increments the position by three.</p>
726 *
727 * @param value
728 * The medium int value to be written
729 *
730 * @return This buffer
731 *
732 * @throws BufferOverflowException
733 * If there are fewer than three bytes
734 * remaining in this buffer
735 *
736 * @throws ReadOnlyBufferException
737 * If this buffer is read-only
738 */
739 public abstract IoBuffer putMediumInt(int value);
740
741 /**
742 * Absolute <i>put</i> method for writing a medium int
743 * value.
744 *
745 * <p> Writes three bytes containing the given int value, in the
746 * current byte order, into this buffer at the given index.</p>
747 *
748 * @param index
749 * The index at which the bytes will be written
750 *
751 * @param value
752 * The medium int value to be written
753 *
754 * @return This buffer
755 *
756 * @throws IndexOutOfBoundsException
757 * If <tt>index</tt> is negative
758 * or not smaller than the buffer's limit,
759 * minus three
760 *
761 * @throws ReadOnlyBufferException
762 * If this buffer is read-only
763 */
764 public abstract IoBuffer putMediumInt(int index, int value);
765
766 /**
767 * @see ByteBuffer#putInt(int)
768 */
769 public abstract IoBuffer putInt(int value);
770
771 /**
772 * @see ByteBuffer#getInt(int)
773 */
774 public abstract int getInt(int index);
775
776 /**
777 * Reads four bytes unsigned integer.
778 */
779 public abstract long getUnsignedInt(int index);
780
781 /**
782 * @see ByteBuffer#putInt(int, int)
783 */
784 public abstract IoBuffer putInt(int index, int value);
785
786 /**
787 * @see ByteBuffer#asIntBuffer()
788 */
789 public abstract IntBuffer asIntBuffer();
790
791 /**
792 * @see ByteBuffer#getLong()
793 */
794 public abstract long getLong();
795
796 /**
797 * @see ByteBuffer#putLong(int, long)
798 */
799 public abstract IoBuffer putLong(long value);
800
801 /**
802 * @see ByteBuffer#getLong(int)
803 */
804 public abstract long getLong(int index);
805
806 /**
807 * @see ByteBuffer#putLong(int, long)
808 */
809 public abstract IoBuffer putLong(int index, long value);
810
811 /**
812 * @see ByteBuffer#asLongBuffer()
813 */
814 public abstract LongBuffer asLongBuffer();
815
816 /**
817 * @see ByteBuffer#getFloat()
818 */
819 public abstract float getFloat();
820
821 /**
822 * @see ByteBuffer#putFloat(float)
823 */
824 public abstract IoBuffer putFloat(float value);
825
826 /**
827 * @see ByteBuffer#getFloat(int)
828 */
829 public abstract float getFloat(int index);
830
831 /**
832 * @see ByteBuffer#putFloat(int, float)
833 */
834 public abstract IoBuffer putFloat(int index, float value);
835
836 /**
837 * @see ByteBuffer#asFloatBuffer()
838 */
839 public abstract FloatBuffer asFloatBuffer();
840
841 /**
842 * @see ByteBuffer#getDouble()
843 */
844 public abstract double getDouble();
845
846 /**
847 * @see ByteBuffer#putDouble(double)
848 */
849 public abstract IoBuffer putDouble(double value);
850
851 /**
852 * @see ByteBuffer#getDouble(int)
853 */
854 public abstract double getDouble(int index);
855
856 /**
857 * @see ByteBuffer#putDouble(int, double)
858 */
859 public abstract IoBuffer putDouble(int index, double value);
860
861 /**
862 * @see ByteBuffer#asDoubleBuffer()
863 */
864 public abstract DoubleBuffer asDoubleBuffer();
865
866 /**
867 * Returns an {@link InputStream} that reads the data from this buffer.
868 * {@link InputStream#read()} returns <tt>-1</tt> if the buffer position
869 * reaches to the limit.
870 */
871 public abstract InputStream asInputStream();
872
873 /**
874 * Returns an {@link OutputStream} that appends the data into this buffer.
875 * Please note that the {@link OutputStream#write(int)} will throw a
876 * {@link BufferOverflowException} instead of an {@link IOException}
877 * in case of buffer overflow. Please set <tt>autoExpand</tt> property by
878 * calling {@link #setAutoExpand(boolean)} to prevent the unexpected runtime
879 * exception.
880 */
881 public abstract OutputStream asOutputStream();
882
883 /**
884 * Returns hexdump of this buffer. The data and pointer are
885 * not changed as a result of this method call.
886 *
887 * @return
888 * hexidecimal representation of this buffer
889 */
890 public abstract String getHexDump();
891
892 /**
893 * Return hexdump of this buffer with limited length.
894 *
895 * @param lengthLimit The maximum number of bytes to dump from
896 * the current buffer position.
897 * @return
898 * hexidecimal representation of this buffer
899 */
900 public abstract String getHexDump(int lengthLimit);
901
902 ////////////////////////////////
903 // String getters and putters //
904 ////////////////////////////////
905
906 /**
907 * Reads a <code>NUL</code>-terminated string from this buffer using the
908 * specified <code>decoder</code> and returns it. This method reads
909 * until the limit of this buffer if no <tt>NUL</tt> is found.
910 */
911 public abstract String getString(CharsetDecoder decoder)
912 throws CharacterCodingException;
913
914 /**
915 * Reads a <code>NUL</code>-terminated string from this buffer using the
916 * specified <code>decoder</code> and returns it.
917 *
918 * @param fieldSize the maximum number of bytes to read
919 */
920 public abstract String getString(int fieldSize, CharsetDecoder decoder)
921 throws CharacterCodingException;
922
923 /**
924 * Writes the content of <code>in</code> into this buffer using the
925 * specified <code>encoder</code>. This method doesn't terminate
926 * string with <tt>NUL</tt>. You have to do it by yourself.
927 *
928 * @throws BufferOverflowException if the specified string doesn't fit
929 */
930 public abstract IoBuffer putString(CharSequence val, CharsetEncoder encoder)
931 throws CharacterCodingException;
932
933 /**
934 * Writes the content of <code>in</code> into this buffer as a
935 * <code>NUL</code>-terminated string using the specified
936 * <code>encoder</code>.
937 * <p>
938 * If the charset name of the encoder is UTF-16, you cannot specify
939 * odd <code>fieldSize</code>, and this method will append two
940 * <code>NUL</code>s as a terminator.
941 * <p>
942 * Please note that this method doesn't terminate with <code>NUL</code>
943 * if the input string is longer than <tt>fieldSize</tt>.
944 *
945 * @param fieldSize the maximum number of bytes to write
946 */
947 public abstract IoBuffer putString(CharSequence val, int fieldSize,
948 CharsetEncoder encoder) throws CharacterCodingException;
949
950 /**
951 * Reads a string which has a 16-bit length field before the actual
952 * encoded string, using the specified <code>decoder</code> and returns it.
953 * This method is a shortcut for <tt>getPrefixedString(2, decoder)</tt>.
954 */
955 public abstract String getPrefixedString(CharsetDecoder decoder)
956 throws CharacterCodingException;
957
958 /**
959 * Reads a string which has a length field before the actual
960 * encoded string, using the specified <code>decoder</code> and returns it.
961 *
962 * @param prefixLength the length of the length field (1, 2, or 4)
963 */
964 public abstract String getPrefixedString(int prefixLength, CharsetDecoder decoder)
965 throws CharacterCodingException;
966
967 /**
968 * Writes the content of <code>in</code> into this buffer as a
969 * string which has a 16-bit length field before the actual
970 * encoded string, using the specified <code>encoder</code>.
971 * This method is a shortcut for <tt>putPrefixedString(in, 2, 0, encoder)</tt>.
972 *
973 * @throws BufferOverflowException if the specified string doesn't fit
974 */
975 public abstract IoBuffer putPrefixedString(CharSequence in, CharsetEncoder encoder)
976 throws CharacterCodingException;
977
978 /**
979 * Writes the content of <code>in</code> into this buffer as a
980 * string which has a 16-bit length field before the actual
981 * encoded string, using the specified <code>encoder</code>.
982 * This method is a shortcut for <tt>putPrefixedString(in, prefixLength, 0, encoder)</tt>.
983 *
984 * @param prefixLength the length of the length field (1, 2, or 4)
985 *
986 * @throws BufferOverflowException if the specified string doesn't fit
987 */
988 public abstract IoBuffer putPrefixedString(CharSequence in, int prefixLength,
989 CharsetEncoder encoder) throws CharacterCodingException;
990
991 /**
992 * Writes the content of <code>in</code> into this buffer as a
993 * string which has a 16-bit length field before the actual
994 * encoded string, using the specified <code>encoder</code>.
995 * This method is a shortcut for <tt>putPrefixedString(in, prefixLength, padding, ( byte ) 0, encoder)</tt>.
996 *
997 * @param prefixLength the length of the length field (1, 2, or 4)
998 * @param padding the number of padded <tt>NUL</tt>s (1 (or 0), 2, or 4)
999 *
1000 * @throws BufferOverflowException if the specified string doesn't fit
1001 */
1002 public abstract IoBuffer putPrefixedString(CharSequence in, int prefixLength,
1003 int padding, CharsetEncoder encoder)
1004 throws CharacterCodingException;
1005
1006 /**
1007 * Writes the content of <code>in</code> into this buffer as a
1008 * string which has a 16-bit length field before the actual
1009 * encoded string, using the specified <code>encoder</code>.
1010 *
1011 * @param prefixLength the length of the length field (1, 2, or 4)
1012 * @param padding the number of padded bytes (1 (or 0), 2, or 4)
1013 * @param padValue the value of padded bytes
1014 *
1015 * @throws BufferOverflowException if the specified string doesn't fit
1016 */
1017 public abstract IoBuffer putPrefixedString(CharSequence val, int prefixLength,
1018 int padding, byte padValue, CharsetEncoder encoder)
1019 throws CharacterCodingException;
1020
1021 /**
1022 * Reads a Java object from the buffer using the context {@link ClassLoader}
1023 * of the current thread.
1024 */
1025 public abstract Object getObject() throws ClassNotFoundException;
1026
1027 /**
1028 * Reads a Java object from the buffer using the specified <tt>classLoader</tt>.
1029 */
1030 public abstract Object getObject(final ClassLoader classLoader)
1031 throws ClassNotFoundException;
1032
1033 /**
1034 * Writes the specified Java object to the buffer.
1035 */
1036 public abstract IoBuffer putObject(Object o);
1037
1038 /**
1039 * Returns <tt>true</tt> if this buffer contains a data which has a data
1040 * length as a prefix and the buffer has remaining data as enough as
1041 * specified in the data length field. This method is identical with
1042 * <tt>prefixedDataAvailable( prefixLength, Integer.MAX_VALUE )</tt>.
1043 * Please not that using this method can allow DoS (Denial of Service)
1044 * attack in case the remote peer sends too big data length value.
1045 * It is recommended to use {@link #prefixedDataAvailable(int, int)}
1046 * instead.
1047 *
1048 * @param prefixLength the length of the prefix field (1, 2, or 4)
1049 *
1050 * @throws IllegalArgumentException if prefixLength is wrong
1051 * @throws BufferDataException if data length is negative
1052 */
1053 public abstract boolean prefixedDataAvailable(int prefixLength);
1054
1055 /**
1056 * Returns <tt>true</tt> if this buffer contains a data which has a data
1057 * length as a prefix and the buffer has remaining data as enough as
1058 * specified in the data length field.
1059 *
1060 * @param prefixLength the length of the prefix field (1, 2, or 4)
1061 * @param maxDataLength the allowed maximum of the read data length
1062 *
1063 * @throws IllegalArgumentException if prefixLength is wrong
1064 * @throws BufferDataException if data length is negative or greater then <tt>maxDataLength</tt>
1065 */
1066 public abstract boolean prefixedDataAvailable(int prefixLength, int maxDataLength);
1067
1068 /////////////////////
1069 // IndexOf methods //
1070 /////////////////////
1071
1072 /**
1073 * Returns the first occurence position of the specified byte from the current position to
1074 * the current limit.
1075 *
1076 * @return <tt>-1</tt> if the specified byte is not found
1077 */
1078 public abstract int indexOf(byte b);
1079
1080 //////////////////////////
1081 // Skip or fill methods //
1082 //////////////////////////
1083
1084 /**
1085 * Forwards the position of this buffer as the specified <code>size</code>
1086 * bytes.
1087 */
1088 public abstract IoBuffer skip(int size);
1089
1090 /**
1091 * Fills this buffer with the specified value.
1092 * This method moves buffer position forward.
1093 */
1094 public abstract IoBuffer fill(byte value, int size);
1095
1096 /**
1097 * Fills this buffer with the specified value.
1098 * This method does not change buffer position.
1099 */
1100 public abstract IoBuffer fillAndReset(byte value, int size);
1101
1102 /**
1103 * Fills this buffer with <code>NUL (0x00)</code>.
1104 * This method moves buffer position forward.
1105 */
1106 public abstract IoBuffer fill(int size);
1107
1108 /**
1109 * Fills this buffer with <code>NUL (0x00)</code>.
1110 * This method does not change buffer position.
1111 */
1112 public abstract IoBuffer fillAndReset(int size);
1113
1114 //////////////////////////
1115 // Enum methods //
1116 //////////////////////////
1117
1118 /**
1119 * Reads a byte from the buffer and returns the correlating enum constant defined
1120 * by the specified enum type.
1121 *
1122 * @param <E> The enum type to return
1123 * @param enumClass The enum's class object
1124 */
1125 public abstract <E extends Enum<E>> E getEnum(Class<E> enumClass);
1126
1127 /**
1128 * Reads a byte from the buffer and returns the correlating enum constant defined
1129 * by the specified enum type.
1130 *
1131 * @param <E> The enum type to return
1132 * @param index the index from which the byte will be read
1133 * @param enumClass The enum's class object
1134 */
1135 public abstract <E extends Enum<E>> E getEnum(int index, Class<E> enumClass);
1136
1137 /**
1138 * Reads a short from the buffer and returns the correlating enum constant defined
1139 * by the specified enum type.
1140 *
1141 * @param <E> The enum type to return
1142 * @param enumClass The enum's class object
1143 */
1144 public abstract <E extends Enum<E>> E getEnumShort(Class<E> enumClass);
1145
1146 /**
1147 * Reads a short from the buffer and returns the correlating enum constant defined
1148 * by the specified enum type.
1149 *
1150 * @param <E> The enum type to return
1151 * @param index the index from which the bytes will be read
1152 * @param enumClass The enum's class object
1153 */
1154 public abstract <E extends Enum<E>> E getEnumShort(int index, Class<E> enumClass);
1155
1156 /**
1157 * Reads an int from the buffer and returns the correlating enum constant defined
1158 * by the specified enum type.
1159 *
1160 * @param <E> The enum type to return
1161 * @param enumClass The enum's class object
1162 */
1163 public abstract <E extends Enum<E>> E getEnumInt(Class<E> enumClass);
1164
1165 /**
1166 * Reads an int from the buffer and returns the correlating enum constant defined
1167 * by the specified enum type.
1168 *
1169 * @param <E> The enum type to return
1170 * @param index the index from which the bytes will be read
1171 * @param enumClass The enum's class object
1172 */
1173 public abstract <E extends Enum<E>> E getEnumInt(int index, Class<E> enumClass);
1174
1175 /**
1176 * Writes an enum's ordinal value to the buffer as a byte.
1177 *
1178 * @param e The enum to write to the buffer
1179 */
1180 public abstract IoBuffer putEnum(Enum<?> e);
1181
1182 /**
1183 * Writes an enum's ordinal value to the buffer as a byte.
1184 *
1185 * @param index The index at which the byte will be written
1186 * @param e The enum to write to the buffer
1187 */
1188 public abstract IoBuffer putEnum(int index, Enum<?> e);
1189
1190 /**
1191 * Writes an enum's ordinal value to the buffer as a short.
1192 *
1193 * @param e The enum to write to the buffer
1194 */
1195 public abstract IoBuffer putEnumShort(Enum<?> e);
1196
1197 /**
1198 * Writes an enum's ordinal value to the buffer as a short.
1199 *
1200 * @param index The index at which the bytes will be written
1201 * @param e The enum to write to the buffer
1202 */
1203 public abstract IoBuffer putEnumShort(int index, Enum<?> e);
1204
1205 /**
1206 * Writes an enum's ordinal value to the buffer as an integer.
1207 *
1208 * @param e The enum to write to the buffer
1209 */
1210 public abstract IoBuffer putEnumInt(Enum<?> e);
1211
1212 /**
1213 * Writes an enum's ordinal value to the buffer as an integer.
1214 *
1215 * @param index The index at which the bytes will be written
1216 * @param e The enum to write to the buffer
1217 */
1218 public abstract IoBuffer putEnumInt(int index, Enum<?> e);
1219
1220 //////////////////////////
1221 // EnumSet methods //
1222 //////////////////////////
1223
1224 /**
1225 * Reads a byte sized bit vector and converts it to an {@link EnumSet}.
1226 *
1227 * <p>Each bit is mapped to a value in the specified enum. The least significant
1228 * bit maps to the first entry in the specified enum and each subsequent bit maps
1229 * to each subsequent bit as mapped to the subsequent enum value.</p>
1230 *
1231 * @param <E> the enum type
1232 * @param enumClass the enum class used to create the EnumSet
1233 * @return the EnumSet representation of the bit vector
1234 */
1235 public abstract <E extends Enum<E>> EnumSet<E> getEnumSet(Class<E> enumClass);
1236
1237 /**
1238 * Reads a byte sized bit vector and converts it to an {@link EnumSet}.
1239 *
1240 * @see #getEnumSet(Class)
1241 * @param <E> the enum type
1242 * @param index the index from which the byte will be read
1243 * @param enumClass the enum class used to create the EnumSet
1244 * @return the EnumSet representation of the bit vector
1245 */
1246 public abstract <E extends Enum<E>> EnumSet<E> getEnumSet(int index,
1247 Class<E> enumClass);
1248
1249 /**
1250 * Reads a short sized bit vector and converts it to an {@link EnumSet}.
1251 *
1252 * @see #getEnumSet(Class)
1253 * @param <E> the enum type
1254 * @param enumClass the enum class used to create the EnumSet
1255 * @return the EnumSet representation of the bit vector
1256 */
1257 public abstract <E extends Enum<E>> EnumSet<E> getEnumSetShort(Class<E> enumClass);
1258
1259 /**
1260 * Reads a short sized bit vector and converts it to an {@link EnumSet}.
1261 *
1262 * @see #getEnumSet(Class)
1263 * @param <E> the enum type
1264 * @param index the index from which the bytes will be read
1265 * @param enumClass the enum class used to create the EnumSet
1266 * @return the EnumSet representation of the bit vector
1267 */
1268 public abstract <E extends Enum<E>> EnumSet<E> getEnumSetShort(int index,
1269 Class<E> enumClass);
1270
1271 /**
1272 * Reads an int sized bit vector and converts it to an {@link EnumSet}.
1273 *
1274 * @see #getEnumSet(Class)
1275 * @param <E> the enum type
1276 * @param enumClass the enum class used to create the EnumSet
1277 * @return the EnumSet representation of the bit vector
1278 */
1279 public abstract <E extends Enum<E>> EnumSet<E> getEnumSetInt(Class<E> enumClass);
1280
1281 /**
1282 * Reads an int sized bit vector and converts it to an {@link EnumSet}.
1283 *
1284 * @see #getEnumSet(Class)
1285 * @param <E> the enum type
1286 * @param index the index from which the bytes will be read
1287 * @param enumClass the enum class used to create the EnumSet
1288 * @return the EnumSet representation of the bit vector
1289 */
1290 public abstract <E extends Enum<E>> EnumSet<E> getEnumSetInt(int index,
1291 Class<E> enumClass);
1292
1293 /**
1294 * Reads a long sized bit vector and converts it to an {@link EnumSet}.
1295 *
1296 * @see #getEnumSet(Class)
1297 * @param <E> the enum type
1298 * @param enumClass the enum class used to create the EnumSet
1299 * @return the EnumSet representation of the bit vector
1300 */
1301 public abstract <E extends Enum<E>> EnumSet<E> getEnumSetLong(Class<E> enumClass);
1302
1303 /**
1304 * Reads a long sized bit vector and converts it to an {@link EnumSet}.
1305 *
1306 * @see #getEnumSet(Class)
1307 * @param <E> the enum type
1308 * @param index the index from which the bytes will be read
1309 * @param enumClass the enum class used to create the EnumSet
1310 * @return the EnumSet representation of the bit vector
1311 */
1312 public abstract <E extends Enum<E>> EnumSet<E> getEnumSetLong(int index,
1313 Class<E> enumClass);
1314
1315 /**
1316 * Writes the specified {@link Set} to the buffer as a byte sized bit vector.
1317 *
1318 * @param <E> the enum type of the Set
1319 * @param set the enum set to write to the buffer
1320 */
1321 public abstract <E extends Enum<E>> IoBuffer putEnumSet(Set<E> set);
1322
1323 /**
1324 * Writes the specified {@link Set} to the buffer as a byte sized bit vector.
1325 *
1326 * @param <E> the enum type of the Set
1327 * @param index the index at which the byte will be written
1328 * @param set the enum set to write to the buffer
1329 */
1330 public abstract <E extends Enum<E>> IoBuffer putEnumSet(int index, Set<E> set);
1331
1332 /**
1333 * Writes the specified {@link Set} to the buffer as a short sized bit vector.
1334 *
1335 * @param <E> the enum type of the Set
1336 * @param set the enum set to write to the buffer
1337 */
1338 public abstract <E extends Enum<E>> IoBuffer putEnumSetShort(Set<E> set);
1339
1340 /**
1341 * Writes the specified {@link Set} to the buffer as a short sized bit vector.
1342 *
1343 * @param <E> the enum type of the Set
1344 * @param index the index at which the bytes will be written
1345 * @param set the enum set to write to the buffer
1346 */
1347 public abstract <E extends Enum<E>> IoBuffer putEnumSetShort(int index, Set<E> set);
1348
1349 /**
1350 * Writes the specified {@link Set} to the buffer as an int sized bit vector.
1351 *
1352 * @param <E> the enum type of the Set
1353 * @param set the enum set to write to the buffer
1354 */
1355 public abstract <E extends Enum<E>> IoBuffer putEnumSetInt(Set<E> set);
1356
1357 /**
1358 * Writes the specified {@link Set} to the buffer as an int sized bit vector.
1359 *
1360 * @param <E> the enum type of the Set
1361 * @param index the index at which the bytes will be written
1362 * @param set the enum set to write to the buffer
1363 */
1364 public abstract <E extends Enum<E>> IoBuffer putEnumSetInt(int index, Set<E> set);
1365
1366 /**
1367 * Writes the specified {@link Set} to the buffer as a long sized bit vector.
1368 *
1369 * @param <E> the enum type of the Set
1370 * @param set the enum set to write to the buffer
1371 */
1372 public abstract <E extends Enum<E>> IoBuffer putEnumSetLong(Set<E> set);
1373
1374 /**
1375 * Writes the specified {@link Set} to the buffer as a long sized bit vector.
1376 *
1377 * @param <E> the enum type of the Set
1378 * @param index the index at which the bytes will be written
1379 * @param set the enum set to write to the buffer
1380 */
1381 public abstract <E extends Enum<E>> IoBuffer putEnumSetLong(int index, Set<E> set);
1382 }