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 not use NIO
47 * {@link ByteBuffer} directly for two reasons:
48 * <ul>
49 * <li>It doesn't provide useful getters and putters such as <code>fill</code>,
50 * <code>get/putString</code>, and <code>get/putAsciiInt()</code> enough.</li>
51 * <li>It is difficult to write variable-length data due to its fixed capacity</li>
52 * </ul>
53 *
54 * <h2>Allocation</h2>
55 * <p>
56 * You can allocate a new heap buffer.
57 *
58 * <pre>
59 * IoBuffer buf = IoBuffer.allocate(1024, false);
60 * </pre>
61 *
62 * You can also allocate a new direct buffer:
63 *
64 * <pre>
65 * IoBuffer buf = IoBuffer.allocate(1024, true);
66 * </pre>
67 *
68 * or you can set the default buffer type.
69 *
70 * <pre>
71 * // Allocate heap buffer by default.
72 * IoBuffer.setUseDirectBuffer(false);
73 *
74 * // A new heap buffer is returned.
75 * IoBuffer buf = IoBuffer.allocate(1024);
76 * </pre>
77 *
78 * <h2>Wrapping existing NIO buffers and arrays</h2>
79 * <p>
80 * This class provides a few <tt>wrap(...)</tt> methods that wraps any NIO
81 * buffers and byte arrays.
82 *
83 * <h2>AutoExpand</h2>
84 * <p>
85 * Writing variable-length data using NIO <tt>ByteBuffers</tt> is not really
86 * easy, and it is because its size is fixed at allocation. {@link IoBuffer} introduces
87 * the <tt>autoExpand</tt> property. If <tt>autoExpand</tt> property is set to true,
88 * you never get a {@link BufferOverflowException} or
89 * an {@link IndexOutOfBoundsException} (except when index is negative). It
90 * automatically expands its capacity. For instance:
91 *
92 * <pre>
93 * String greeting = messageBundle.getMessage("hello");
94 * IoBuffer buf = IoBuffer.allocate(16);
95 * // Turn on autoExpand (it is off by default)
96 * buf.setAutoExpand(true);
97 * buf.putString(greeting, utf8encoder);
98 * </pre>
99 *
100 * The underlying {@link ByteBuffer} is reallocated by {@link IoBuffer} behind
101 * the scene if the encoded data is larger than 16 bytes in the example above.
102 * Its capacity will double, and its limit will increase to the last position
103 * the string is written.
104 *
105 * <h2>AutoShrink</h2>
106 * <p>
107 * You might also want to decrease the capacity of the buffer when most of the
108 * allocated memory area is not being used. {@link IoBuffer} provides
109 * <tt>autoShrink</tt> property to take care of this issue. If
110 * <tt>autoShrink</tt> is turned on, {@link IoBuffer} halves the capacity of the
111 * buffer when {@link #compact()} is invoked and only 1/4 or less of the current
112 * capacity is being used.
113 * <p>
114 * You can also call the {@link #shrink()} method manually to shrink the capacity of the
115 * buffer.
116 * <p>
117 * The underlying {@link ByteBuffer} is reallocated by the {@link IoBuffer} behind
118 * the scene, and therefore {@link #buf()} will return a different
119 * {@link ByteBuffer} instance once capacity changes. Please also note
120 * that the {@link #compact()} method or the {@link #shrink()} method
121 * will not decrease the capacity if the new capacity is less than the
122 * {@link #minimumCapacity()} of the buffer.
123 *
124 * <h2>Derived Buffers</h2>
125 * <p>
126 * Derived buffers are the buffers which were created by the {@link #duplicate()},
127 * {@link #slice()}, or {@link #asReadOnlyBuffer()} methods. They are useful especially
128 * when you broadcast the same messages to multiple {@link IoSession}s. Please
129 * note that the buffer derived from and its derived buffers are not
130 * auto-expandable nor auto-shrinkable. Trying to call
131 * {@link #setAutoExpand(boolean)} or {@link #setAutoShrink(boolean)} with
132 * <tt>true</tt> parameter will raise an {@link IllegalStateException}.
133 *
134 * <h2>Changing Buffer Allocation Policy</h2>
135 * <p>
136 * The {@link IoBufferAllocator} interface lets you override the default buffer
137 * management behavior. There are two allocators provided out-of-the-box:
138 * <ul>
139 * <li>{@link SimpleBufferAllocator} (default)</li>
140 * <li>{@link CachedBufferAllocator}</li>
141 * </ul>
142 * You can implement your own allocator and use it by calling
143 * {@link #setAllocator(IoBufferAllocator)}.
144 *
145 * @author <a href="http://mina.apache.org">Apache MINA Project</a>
146 */
147 public abstract class IoBuffer implements Comparable<IoBuffer> {
148 /** The allocator used to create new buffers */
149 private static IoBufferAllocator allocator = new SimpleBufferAllocator();
150
151 /** A flag indicating which type of buffer we are using : heap or direct */
152 private static boolean useDirectBuffer = false;
153
154 /**
155 * Creates a new instance. This is an empty constructor. It's protected,
156 * to forbid its usage by the users.
157 */
158 protected IoBuffer() {
159 // Do nothing
160 }
161
162 /**
163 * @return the allocator used by existing and new buffers
164 */
165 public static IoBufferAllocator getAllocator() {
166 return allocator;
167 }
168
169 /**
170 * Sets the allocator used by existing and new buffers
171 *
172 * @param newAllocator the new allocator to use
173 */
174 public static void setAllocator(IoBufferAllocator newAllocator) {
175 if (newAllocator == null) {
176 throw new IllegalArgumentException("allocator");
177 }
178
179 IoBufferAllocator oldAllocator = allocator;
180
181 allocator = newAllocator;
182
183 if (null != oldAllocator) {
184 oldAllocator.dispose();
185 }
186 }
187
188 /**
189 * @return <tt>true</tt> if and only if a direct buffer is allocated by
190 * default when the type of the new buffer is not specified. The default
191 * value is <tt>false</tt>.
192 */
193 public static boolean isUseDirectBuffer() {
194 return useDirectBuffer;
195 }
196
197 /**
198 * Sets if a direct buffer should be allocated by default when the type of
199 * the new buffer is not specified. The default value is <tt>false</tt>.
200 *
201 * @param useDirectBuffer Tells if direct buffers should be allocated
202 */
203 public static void setUseDirectBuffer(boolean useDirectBuffer) {
204 IoBuffer.useDirectBuffer = useDirectBuffer;
205 }
206
207 /**
208 * Returns the direct or heap buffer which is capable to store the specified
209 * amount of bytes.
210 *
211 * @param capacity the capacity of the buffer
212 * @return a IoBuffer which can hold up to capacity bytes
213 *
214 * @see #setUseDirectBuffer(boolean)
215 */
216 public static IoBuffer allocate(int capacity) {
217 return allocate(capacity, useDirectBuffer);
218 }
219
220 /**
221 * Returns a direct or heap IoBuffer which can contain the specified number of bytes.
222 *
223 * @param capacity the capacity of the buffer
224 * @param useDirectBuffer <tt>true</tt> to get a direct buffer, <tt>false</tt> to get a
225 * heap buffer.
226 * @return a direct or heap IoBuffer which can hold up to capacity bytes
227 */
228 public static IoBuffer allocate(int capacity, boolean useDirectBuffer) {
229 if (capacity < 0) {
230 throw new IllegalArgumentException("capacity: " + capacity);
231 }
232
233 return allocator.allocate(capacity, useDirectBuffer);
234 }
235
236 /**
237 * Wraps the specified NIO {@link ByteBuffer} into a MINA buffer (either direct or heap).
238 *
239 * @param nioBuffer The {@link ByteBuffer} to wrap
240 * @return a IoBuffer containing the bytes stored in the {@link ByteBuffer}
241 */
242 public static IoBuffer wrap(ByteBuffer nioBuffer) {
243 return allocator.wrap(nioBuffer);
244 }
245
246 /**
247 * Wraps the specified byte array into a MINA heap buffer. Note that
248 * the byte array is not copied, so any modification done on it will
249 * be visible by both sides.
250 *
251 * @param byteArray The byte array to wrap
252 * @return a heap IoBuffer containing the byte array
253 */
254 public static IoBuffer wrap(byte[] byteArray) {
255 return wrap(ByteBuffer.wrap(byteArray));
256 }
257
258 /**
259 * Wraps the specified byte array into MINA heap buffer. We just wrap the
260 * bytes starting from offset up to offset + length. Note that
261 * the byte array is not copied, so any modification done on it will
262 * be visible by both sides.
263 *
264 * @param byteArray The byte array to wrap
265 * @param offset The starting point in the byte array
266 * @param length The number of bytes to store
267 * @return a heap IoBuffer containing the selected part of the byte array
268 */
269 public static IoBuffer wrap(byte[] byteArray, int offset, int length) {
270 return wrap(ByteBuffer.wrap(byteArray, offset, length));
271 }
272
273 /**
274 * Normalizes the specified capacity of the buffer to power of 2, which is
275 * often helpful for optimal memory usage and performance. If it is greater
276 * than or equal to {@link Integer#MAX_VALUE}, it returns
277 * {@link Integer#MAX_VALUE}. If it is zero, it returns zero.
278 *
279 * @param requestedCapacity The IoBuffer capacity we want to be able to store
280 * @return The power of 2 strictly superior to the requested capacity
281 */
282 protected static int normalizeCapacity(int requestedCapacity) {
283 if (requestedCapacity < 0) {
284 return Integer.MAX_VALUE;
285 }
286
287 int newCapacity = Integer.highestOneBit(requestedCapacity);
288 newCapacity <<= (newCapacity < requestedCapacity ? 1 : 0);
289
290 return newCapacity < 0 ? Integer.MAX_VALUE : newCapacity;
291 }
292
293 /**
294 * Declares this buffer and all its derived buffers are not used anymore so
295 * that it can be reused by some {@link IoBufferAllocator} implementations.
296 * It is not mandatory to call this method, but you might want to invoke
297 * this method for maximum performance.
298 */
299 public abstract void free();
300
301 /**
302 * @return the underlying NIO {@link ByteBuffer} instance.
303 */
304 public abstract ByteBuffer buf();
305
306 /**
307 * @see ByteBuffer#isDirect()
308 *
309 * @return <tt>True</tt> if this is a direct buffer
310 */
311 public abstract boolean isDirect();
312
313 /**
314 * @return <tt>true</tt> if and only if this buffer is derived from another
315 * buffer via one of the {@link #duplicate()}, {@link #slice()} or
316 * {@link #asReadOnlyBuffer()} methods.
317 */
318 public abstract boolean isDerived();
319
320 /**
321 * @see ByteBuffer#isReadOnly()
322 *
323 * @return <tt>true</tt> if the buffer is readOnly
324 */
325 public abstract boolean isReadOnly();
326
327 /**
328 * @return the minimum capacity of this buffer which is used to determine
329 * the new capacity of the buffer shrunk by the {@link #compact()} and
330 * {@link #shrink()} operation. The default value is the initial capacity of
331 * the buffer.
332 */
333 public abstract int minimumCapacity();
334
335 /**
336 * Sets the minimum capacity of this buffer which is used to determine the
337 * new capacity of the buffer shrunk by {@link #compact()} and
338 * {@link #shrink()} operation. The default value is the initial capacity of
339 * the buffer.
340 *
341 * @param minimumCapacity the wanted minimum capacity
342 * @return the underlying NIO {@link ByteBuffer} instance.
343 */
344 public abstract IoBuffer minimumCapacity(int minimumCapacity);
345
346 /**
347 * @see ByteBuffer#capacity()
348 *
349 * @return the buffer capacity
350 */
351 public abstract int capacity();
352
353 /**
354 * Increases the capacity of this buffer. If the new capacity is less than
355 * or equal to the current capacity, this method returns the original buffer.
356 * If the new capacity is greater than the current capacity, the buffer is
357 * reallocated while retaining the position, limit, mark and the content of
358 * the buffer.
359 * <br>
360 * Note that the IoBuffer is replaced, it's not copied.
361 * <br>
362 * Assuming a buffer contains N bytes, its position is 0 and its current capacity is C,
363 * here are the resulting buffer if we set the new capacity to a value V < C and V > C :
364 *
365 * <pre>
366 * Initial buffer :
367 *
368 * 0 L C
369 * +--------+----------+
370 * |XXXXXXXX| |
371 * +--------+----------+
372 * ^ ^ ^
373 * | | |
374 * pos limit capacity
375 *
376 * V <= C :
377 *
378 * 0 L C
379 * +--------+----------+
380 * |XXXXXXXX| |
381 * +--------+----------+
382 * ^ ^ ^
383 * | | |
384 * pos limit newCapacity
385 *
386 * V > C :
387 *
388 * 0 L C V
389 * +--------+-----------------------+
390 * |XXXXXXXX| : |
391 * +--------+-----------------------+
392 * ^ ^ ^ ^
393 * | | | |
394 * pos limit oldCapacity newCapacity
395 *
396 * The buffer has been increased.
397 *
398 * </pre>
399 *
400 * @param newCapacity the wanted capacity
401 * @return the underlying NIO {@link ByteBuffer} instance.
402 */
403 public abstract IoBuffer capacity(int newCapacity);
404
405 /**
406 * @return <tt>true</tt> if and only if <tt>autoExpand</tt> is turned on.
407 */
408 public abstract boolean isAutoExpand();
409
410 /**
411 * Turns on or off <tt>autoExpand</tt>.
412 *
413 * @param autoExpand The flag value to set
414 * @return The modified IoBuffer instance
415 */
416 public abstract IoBuffer setAutoExpand(boolean autoExpand);
417
418 /**
419 * @return <tt>true</tt> if and only if <tt>autoShrink</tt> is turned on.
420 */
421 public abstract boolean isAutoShrink();
422
423 /**
424 * Turns on or off <tt>autoShrink</tt>.
425 *
426 * @param autoShrink The flag value to set
427 * @return The modified IoBuffer instance
428 */
429 public abstract IoBuffer setAutoShrink(boolean autoShrink);
430
431 /**
432 * Changes the capacity and limit of this buffer so this buffer get the
433 * specified <tt>expectedRemaining</tt> room from the current position. This
434 * method works even if you didn't set <tt>autoExpand</tt> to <tt>true</tt>.
435 * <br>
436 * Assuming a buffer contains N bytes, its position is P and its current capacity is C,
437 * here are the resulting buffer if we call the expand method with a expectedRemaining
438 * value V :
439 *
440 * <pre>
441 * Initial buffer :
442 *
443 * 0 L C
444 * +--------+----------+
445 * |XXXXXXXX| |
446 * +--------+----------+
447 * ^ ^ ^
448 * | | |
449 * pos limit capacity
450 *
451 * ( pos + V ) <= L, no change :
452 *
453 * 0 L C
454 * +--------+----------+
455 * |XXXXXXXX| |
456 * +--------+----------+
457 * ^ ^ ^
458 * | | |
459 * pos limit newCapacity
460 *
461 * You can still put ( L - pos ) bytes in the buffer
462 *
463 * ( pos + V ) > L & ( pos + V ) <= C :
464 *
465 * 0 L C
466 * +------------+------+
467 * |XXXXXXXX:...| |
468 * +------------+------+
469 * ^ ^ ^
470 * | | |
471 * pos newlimit newCapacity
472 *
473 * You can now put ( L - pos + V ) bytes in the buffer.
474 *
475 *
476 * ( pos + V ) > C
477 *
478 * 0 L C
479 * +-------------------+----+
480 * |XXXXXXXX:..........:....|
481 * +------------------------+
482 * ^ ^
483 * | |
484 * pos +-- newlimit
485 * |
486 * +-- newCapacity
487 *
488 * You can now put ( L - pos + V ) bytes in the buffer, which limit is now
489 * equals to the capacity.
490 * </pre>
491 *
492 * Note that the expecting remaining bytes starts at the current position. In all
493 * those examples, the position is 0.
494 *
495 * @param expectedRemaining The expected remaining bytes in the buffer
496 * @return The modified IoBuffer instance
497 */
498 public abstract IoBuffer expand(int expectedRemaining);
499
500 /**
501 * Changes the capacity and limit of this buffer so this buffer get the
502 * specified <tt>expectedRemaining</tt> room from the specified
503 * <tt>position</tt>. This method works even if you didn't set
504 * <tt>autoExpand</tt> to <tt>true</tt>.
505 * Assuming a buffer contains N bytes, its position is P and its current capacity is C,
506 * here are the resulting buffer if we call the expand method with a expectedRemaining
507 * value V :
508 *
509 * <pre>
510 * Initial buffer :
511 *
512 * P L C
513 * +--------+----------+
514 * |XXXXXXXX| |
515 * +--------+----------+
516 * ^ ^ ^
517 * | | |
518 * pos limit capacity
519 *
520 * ( pos + V ) <= L, no change :
521 *
522 * P L C
523 * +--------+----------+
524 * |XXXXXXXX| |
525 * +--------+----------+
526 * ^ ^ ^
527 * | | |
528 * pos limit newCapacity
529 *
530 * You can still put ( L - pos ) bytes in the buffer
531 *
532 * ( pos + V ) > L & ( pos + V ) <= C :
533 *
534 * P L C
535 * +------------+------+
536 * |XXXXXXXX:...| |
537 * +------------+------+
538 * ^ ^ ^
539 * | | |
540 * pos newlimit newCapacity
541 *
542 * You can now put ( L - pos + V) bytes in the buffer.
543 *
544 *
545 * ( pos + V ) > C
546 *
547 * P L C
548 * +-------------------+----+
549 * |XXXXXXXX:..........:....|
550 * +------------------------+
551 * ^ ^
552 * | |
553 * pos +-- newlimit
554 * |
555 * +-- newCapacity
556 *
557 * You can now put ( L - pos + V ) bytes in the buffer, which limit is now
558 * equals to the capacity.
559 * </pre>
560 *
561 * Note that the expecting remaining bytes starts at the current position. In all
562 * those examples, the position is P.
563 *
564 * @param position The starting position from which we want to define a remaining
565 * number of bytes
566 * @param expectedRemaining The expected remaining bytes in the buffer
567 * @return The modified IoBuffer instance
568 */
569 public abstract IoBuffer expand(int position, int expectedRemaining);
570
571 /**
572 * Changes the capacity of this buffer so this buffer occupies as less
573 * memory as possible while retaining the position, limit and the buffer
574 * content between the position and limit.
575 * <br>
576 * <b>The capacity of the buffer never becomes less than {@link #minimumCapacity()}</b>
577 * <br>.
578 * The mark is discarded once the capacity changes.
579 * <br>
580 * Typically, a call to this method tries to remove as much unused bytes
581 * as possible, dividing by two the initial capacity until it can't without
582 * obtaining a new capacity lower than the {@link #minimumCapacity()}. For instance, if
583 * the limit is 7 and the capacity is 36, with a minimum capacity of 8,
584 * shrinking the buffer will left a capacity of 9 (we go down from 36 to 18, then from 18 to 9).
585 *
586 * <pre>
587 * Initial buffer :
588 *
589 * +--------+----------+
590 * |XXXXXXXX| |
591 * +--------+----------+
592 * ^ ^ ^ ^
593 * | | | |
594 * pos | | capacity
595 * | |
596 * | +-- minimumCapacity
597 * |
598 * +-- limit
599 *
600 * Resulting buffer :
601 *
602 * +--------+--+-+
603 * |XXXXXXXX| | |
604 * +--------+--+-+
605 * ^ ^ ^ ^
606 * | | | |
607 * | | | +-- new capacity
608 * | | |
609 * pos | +-- minimum capacity
610 * |
611 * +-- limit
612 * </pre>
613 *
614 * @return The modified IoBuffer instance
615 */
616 public abstract IoBuffer shrink();
617
618 /**
619 * @see java.nio.Buffer#position()
620 * @return The current position in the buffer
621 */
622 public abstract int position();
623
624 /**
625 * @see java.nio.Buffer#position(int)
626 *
627 * @param newPosition Sets the new position in the buffer
628 * @return the modified IoBuffer
629
630 */
631 public abstract IoBuffer position(int newPosition);
632
633 /**
634 * @see java.nio.Buffer#limit()
635 *
636 * @return the modified IoBuffer
637 's limit
638 */
639 public abstract int limit();
640
641 /**
642 * @see java.nio.Buffer#limit(int)
643 *
644 * @param newLimit The new buffer's limit
645 * @return the modified IoBuffer
646
647 */
648 public abstract IoBuffer limit(int newLimit);
649
650 /**
651 * @see java.nio.Buffer#mark()
652 *
653 * @return the modified IoBuffer
654
655 */
656 public abstract IoBuffer mark();
657
658 /**
659 * @return the position of the current mark. This method returns <tt>-1</tt>
660 * if no mark is set.
661 */
662 public abstract int markValue();
663
664 /**
665 * @see java.nio.Buffer#reset()
666 *
667 * @return the modified IoBuffer
668
669 */
670 public abstract IoBuffer reset();
671
672 /**
673 * @see java.nio.Buffer#clear()
674 *
675 * @return the modified IoBuffer
676
677 */
678 public abstract IoBuffer clear();
679
680 /**
681 * Clears this buffer and fills its content with <tt>NUL</tt>. The position
682 * is set to zero, the limit is set to the capacity, and the mark is
683 * discarded.
684 *
685 * @return the modified IoBuffer
686
687 */
688 public abstract IoBuffer sweep();
689
690 /**
691 * double Clears this buffer and fills its content with <tt>value</tt>. The
692 * position is set to zero, the limit is set to the capacity, and the mark
693 * is discarded.
694 *
695 * @param value The value to put in the buffer
696 * @return the modified IoBuffer
697
698 */
699 public abstract IoBuffer sweep(byte value);
700
701 /**
702 * @see java.nio.Buffer#flip()
703 *
704 * @return the modified IoBuffer
705
706 */
707 public abstract IoBuffer flip();
708
709 /**
710 * @see java.nio.Buffer#rewind()
711 *
712 * @return the modified IoBuffer
713
714 */
715 public abstract IoBuffer rewind();
716
717 /**
718 * @see java.nio.Buffer#remaining()
719 *
720 * @return The remaining bytes in the buffer
721 */
722 public abstract int remaining();
723
724 /**
725 * @see java.nio.Buffer#hasRemaining()
726 *
727 * @return <tt>true</tt> if there are some remaining bytes in the buffer
728 */
729 public abstract boolean hasRemaining();
730
731 /**
732 * @see ByteBuffer#duplicate()
733 *
734 * @return the modified IoBuffer
735
736 */
737 public abstract IoBuffer duplicate();
738
739 /**
740 * @see ByteBuffer#slice()
741 *
742 * @return the modified IoBuffer
743
744 */
745 public abstract IoBuffer slice();
746
747 /**
748 * @see ByteBuffer#asReadOnlyBuffer()
749 *
750 * @return the modified IoBuffer
751
752 */
753 public abstract IoBuffer asReadOnlyBuffer();
754
755 /**
756 * @see ByteBuffer#hasArray()
757 *
758 * @return <tt>true</tt> if the {@link #array()} method will return a byte[]
759 */
760 public abstract boolean hasArray();
761
762 /**
763 * @see ByteBuffer#array()
764 *
765 * @return A byte[] if this IoBuffer supports it
766 */
767 public abstract byte[] array();
768
769 /**
770 * @see ByteBuffer#arrayOffset()
771 *
772 * @return The offset in the returned byte[] when the {@link #array()} method is called
773 */
774 public abstract int arrayOffset();
775
776 /**
777 * @see ByteBuffer#get()
778 *
779 * @return The byte at the current position
780 */
781 public abstract byte get();
782
783 /**
784 * Reads one unsigned byte as a short integer.
785 *
786 * @return the unsigned short at the current position
787 */
788 public abstract short getUnsigned();
789
790 /**
791 * @see ByteBuffer#put(byte)
792 *
793 * @param b The byte to put in the buffer
794 * @return the modified IoBuffer
795
796 */
797 public abstract IoBuffer put(byte b);
798
799 /**
800 * @see ByteBuffer#get(int)
801 *
802 * @param index The position for which we want to read a byte
803 * @return the byte at the given position
804 */
805 public abstract byte get(int index);
806
807 /**
808 * Reads one byte as an unsigned short integer.
809 *
810 * @param index The position for which we want to read an unsigned byte
811 * @return the unsigned byte at the given position
812 */
813 public abstract short getUnsigned(int index);
814
815 /**
816 * @see ByteBuffer#put(int, byte)
817 *
818 * @param index The position where the byte will be put
819 * @param b The byte to put
820 * @return the modified IoBuffer
821
822 */
823 public abstract IoBuffer put(int index, byte b);
824
825 /**
826 * @see ByteBuffer#get(byte[], int, int)
827 *
828 * @param dst The destination buffer
829 * @param offset The position in the original buffer
830 * @param length The number of bytes to copy
831 * @return the modified IoBuffer
832 */
833 public abstract IoBuffer get(byte[] dst, int offset, int length);
834
835 /**
836 * @see ByteBuffer#get(byte[])
837 *
838 * @param dst The byte[] that will contain the read bytes
839 * @return the IoBuffer
840 */
841 public abstract IoBuffer get(byte[] dst);
842
843 /**
844 * Get a new IoBuffer containing a slice of the current buffer
845 *
846 * @param index The position in the buffer
847 * @param length The number of bytes to copy
848 * @return the new IoBuffer
849 */
850 public abstract IoBuffer getSlice(int index, int length);
851
852 /**
853 * Get a new IoBuffer containing a slice of the current buffer
854 *
855 * @param length The number of bytes to copy
856 * @return the new IoBuffer
857 */
858 public abstract IoBuffer getSlice(int length);
859
860 /**
861 * Writes the content of the specified <tt>src</tt> into this buffer.
862 *
863 * @param src The source ByteBuffer
864 * @return the modified IoBuffer
865 */
866 public abstract IoBuffer put(ByteBuffer src);
867
868 /**
869 * Writes the content of the specified <tt>src</tt> into this buffer.
870 *
871 * @param src The source IoBuffer
872 * @return the modified IoBuffer
873 */
874 public abstract IoBufferef="../../../../../org/apache/mina/core/buffer/IoBuffer.html#IoBuffer">IoBuffer put(IoBuffer src);
875
876 /**
877 * @see ByteBuffer#put(byte[], int, int)
878 *
879 * @param src The byte[] to put
880 * @param offset The position in the source
881 * @param length The number of bytes to copy
882 * @return the modified IoBuffer
883 */
884 public abstract IoBuffer put(byte[] src, int offset, int length);
885
886 /**
887 * @see ByteBuffer#put(byte[])
888 *
889 * @param src The byte[] to put
890 * @return the modified IoBuffer
891 */
892 public abstract IoBuffer put(byte[] src);
893
894 /**
895 * @see ByteBuffer#compact()
896 *
897 * @return the modified IoBuffer
898 */
899 public abstract IoBuffer compact();
900
901 /**
902 * @see ByteBuffer#order()
903 *
904 * @return the IoBuffer ByteOrder
905 */
906 public abstract ByteOrder order();
907
908 /**
909 * @see ByteBuffer#order(ByteOrder)
910 *
911 * @param bo The new ByteBuffer to use for this IoBuffer
912 * @return the modified IoBuffer
913 */
914 public abstract IoBuffer order(ByteOrder bo);
915
916 /**
917 * @see ByteBuffer#getChar()
918 *
919 * @return The char at the current position
920 */
921 public abstract char getChar();
922
923 /**
924 * @see ByteBuffer#putChar(char)
925 *
926 * @param value The char to put at the current position
927 * @return the modified IoBuffer
928 */
929 public abstract IoBuffer putChar(char value);
930
931 /**
932 * @see ByteBuffer#getChar(int)
933 *
934 * @param index The index in the IoBuffer where we will read a char from
935 * @return the char at 'index' position
936 */
937 public abstract char getChar(int index);
938
939 /**
940 * @see ByteBuffer#putChar(int, char)
941 *
942 * @param index The index in the IoBuffer where we will put a char in
943 * @param value The char to put at the current position
944 * @return the modified IoBuffer
945 */
946 public abstract IoBuffer putChar(int index, char value);
947
948 /**
949 * @see ByteBuffer#asCharBuffer()
950 *
951 * @return a new CharBuffer
952 */
953 public abstract CharBuffer asCharBuffer();
954
955 /**
956 * @see ByteBuffer#getShort()
957 *
958 * @return The read short
959 */
960 public abstract short getShort();
961
962 /**
963 * Reads two bytes unsigned integer.
964 *
965 * @return The read unsigned short
966 */
967 public abstract int getUnsignedShort();
968
969 /**
970 * @see ByteBuffer#putShort(short)
971 *
972 * @param value The short to put at the current position
973 * @return the modified IoBuffer
974 */
975 public abstract IoBuffer putShort(short value);
976
977 /**
978 * @see ByteBuffer#getShort()
979 *
980 * @param index The index in the IoBuffer where we will read a short from
981 * @return The read short
982 */
983 public abstract short getShort(int index);
984
985 /**
986 * Reads two bytes unsigned integer.
987 *
988 * @param index The index in the IoBuffer where we will read an unsigned short from
989 * @return the unsigned short at the given position
990 */
991 public abstract int getUnsignedShort(int index);
992
993 /**
994 * @see ByteBuffer#putShort(int, short)
995 *
996 * @param index The position at which the short should be written
997 * @param value The short to put at the current position
998 * @return the modified IoBuffer
999 */
1000 public abstract IoBuffer putShort(int index, short value);
1001
1002 /**
1003 * @see ByteBuffer#asShortBuffer()
1004 *
1005 * @return A ShortBuffer from this IoBuffer
1006 */
1007 public abstract ShortBuffer asShortBuffer();
1008
1009 /**
1010 * @see ByteBuffer#getInt()
1011 *
1012 * @return The int read
1013 */
1014 public abstract int getInt();
1015
1016 /**
1017 * Reads four bytes unsigned integer.
1018 *
1019 * @return The unsigned int read
1020 */
1021 public abstract long getUnsignedInt();
1022
1023 /**
1024 * Relative <i>get</i> method for reading a medium int value.
1025 *
1026 * <p>
1027 * Reads the next three bytes at this buffer's current position, composing
1028 * them into an int value according to the current byte order, and then
1029 * increments the position by three.
1030 *
1031 * @return The medium int value at the buffer's current position
1032 */
1033 public abstract int getMediumInt();
1034
1035 /**
1036 * Relative <i>get</i> method for reading an unsigned medium int value.
1037 *
1038 * <p>
1039 * Reads the next three bytes at this buffer's current position, composing
1040 * them into an int value according to the current byte order, and then
1041 * increments the position by three.
1042 *
1043 * @return The unsigned medium int value at the buffer's current position
1044 */
1045 public abstract int getUnsignedMediumInt();
1046
1047 /**
1048 * Absolute <i>get</i> method for reading a medium int value.
1049 *
1050 * <p>
1051 * Reads the next three bytes at this buffer's current position, composing
1052 * them into an int value according to the current byte order.
1053 *
1054 * @param index The index from which the medium int will be read
1055 * @return The medium int value at the given index
1056 *
1057 * @throws IndexOutOfBoundsException
1058 * If <tt>index</tt> is negative or not smaller than the
1059 * buffer's limit
1060 */
1061 public abstract int getMediumInt(int index);
1062
1063 /**
1064 * Absolute <i>get</i> method for reading an unsigned medium int value.
1065 *
1066 * <p>
1067 * Reads the next three bytes at this buffer's current position, composing
1068 * them into an int value according to the current byte order.
1069 *
1070 * @param index The index from which the unsigned medium int will be read
1071 * @return The unsigned medium int value at the given index
1072 *
1073 * @throws IndexOutOfBoundsException
1074 * If <tt>index</tt> is negative or not smaller than the
1075 * buffer's limit
1076 */
1077 public abstract int getUnsignedMediumInt(int index);
1078
1079 /**
1080 * Relative <i>put</i> method for writing a medium int value.
1081 *
1082 * <p>
1083 * Writes three bytes containing the given int value, in the current byte
1084 * order, into this buffer at the current position, and then increments the
1085 * position by three.
1086 *
1087 * @param value The medium int value to be written
1088 *
1089 * @return the modified IoBuffer
1090 */
1091 public abstract IoBuffer putMediumInt(int value);
1092
1093 /**
1094 * Absolute <i>put</i> method for writing a medium int value.
1095 *
1096 * <p>
1097 * Writes three bytes containing the given int value, in the current byte
1098 * order, into this buffer at the given index.
1099 *
1100 * @param index The index at which the bytes will be written
1101 *
1102 * @param value The medium int value to be written
1103 *
1104 * @return the modified IoBuffer
1105 *
1106 * @throws IndexOutOfBoundsException
1107 * If <tt>index</tt> is negative or not smaller than the
1108 * buffer's limit, minus three
1109 */
1110 public abstract IoBuffer putMediumInt(int index, int value);
1111
1112 /**
1113 * @see ByteBuffer#putInt(int)
1114 *
1115 * @param value The int to put at the current position
1116 * @return the modified IoBuffer
1117 */
1118 public abstract IoBuffer putInt(int value);
1119
1120 /**
1121 * Writes an unsigned byte into the ByteBuffer
1122 *
1123 * @param value the byte to write
1124 *
1125 * @return the modified IoBuffer
1126 */
1127 public abstract IoBuffer putUnsigned(byte value);
1128
1129 /**
1130 * Writes an unsigned byte into the ByteBuffer at a specified position
1131 *
1132 * @param index the position in the buffer to write the value
1133 * @param value the byte to write
1134 *
1135 * @return the modified IoBuffer
1136 */
1137 public abstract IoBuffer putUnsigned(int index, byte value);
1138
1139 /**
1140 * Writes an unsigned byte into the ByteBuffer
1141 *
1142 * @param value the short to write
1143 *
1144 * @return the modified IoBuffer
1145 */
1146 public abstract IoBuffer putUnsigned(short value);
1147
1148 /**
1149 * Writes an unsigned byte into the ByteBuffer at a specified position
1150 *
1151 * @param index the position in the buffer to write the value
1152 * @param value the short to write
1153 *
1154 * @return the modified IoBuffer
1155 */
1156 public abstract IoBuffer putUnsigned(int index, short value);
1157
1158 /**
1159 * Writes an unsigned byte into the ByteBuffer
1160 *
1161 * @param value the int to write
1162 *
1163 * @return the modified IoBuffer
1164 */
1165 public abstract IoBuffer putUnsigned(int value);
1166
1167 /**
1168 * Writes an unsigned byte into the ByteBuffer at a specified position
1169 *
1170 * @param index the position in the buffer to write the value
1171 * @param value the int to write
1172 *
1173 * @return the modified IoBuffer
1174 */
1175 public abstract IoBuffer putUnsigned(int index, int value);
1176
1177 /**
1178 * Writes an unsigned byte into the ByteBuffer
1179 *
1180 * @param value the long to write
1181 *
1182 * @return the modified IoBuffer
1183 */
1184 public abstract IoBuffer putUnsigned(long value);
1185
1186 /**
1187 * Writes an unsigned byte into the ByteBuffer at a specified position
1188 *
1189 * @param index the position in the buffer to write the value
1190 * @param value the long to write
1191 *
1192 * @return the modified IoBuffer
1193 */
1194 public abstract IoBuffer putUnsigned(int index, long value);
1195
1196 /**
1197 * Writes an unsigned int into the ByteBuffer
1198 * @param value the byte to write
1199 *
1200 * @return the modified IoBuffer
1201 */
1202 public abstract IoBuffer putUnsignedInt(byte value);
1203
1204 /**
1205 * Writes an unsigned int into the ByteBuffer at a specified position
1206 *
1207 * @param index the position in the buffer to write the value
1208 * @param value the byte to write
1209 *
1210 * @return the modified IoBuffer
1211 */
1212 public abstract IoBuffer putUnsignedInt(int index, byte value);
1213
1214 /**
1215 * Writes an unsigned int into the ByteBuffer
1216 *
1217 * @param value the short to write
1218 *
1219 * @return the modified IoBuffer
1220 */
1221 public abstract IoBuffer putUnsignedInt(short value);
1222
1223 /**
1224 * Writes an unsigned int into the ByteBuffer at a specified position
1225 *
1226 * @param index the position in the buffer to write the value
1227 * @param value the short to write
1228 *
1229 * @return the modified IoBuffer
1230 */
1231 public abstract IoBuffer putUnsignedInt(int index, short value);
1232
1233 /**
1234 * Writes an unsigned int into the ByteBuffer
1235 *
1236 * @param value the int to write
1237 *
1238 * @return the modified IoBuffer
1239 */
1240 public abstract IoBuffer putUnsignedInt(int value);
1241
1242 /**
1243 * Writes an unsigned int into the ByteBuffer at a specified position
1244 *
1245 * @param index the position in the buffer to write the value
1246 * @param value the int to write
1247 *
1248 * @return the modified IoBuffer
1249 */
1250 public abstract IoBuffer putUnsignedInt(int index, int value);
1251
1252 /**
1253 * Writes an unsigned int into the ByteBuffer
1254 *
1255 * @param value the long to write
1256 *
1257 * @return the modified IoBuffer
1258 */
1259 public abstract IoBuffer putUnsignedInt(long value);
1260
1261 /**
1262 * Writes an unsigned int into the ByteBuffer at a specified position
1263 *
1264 * @param index the position in the buffer to write the value
1265 * @param value the long to write
1266 *
1267 * @return the modified IoBuffer
1268 */
1269 public abstract IoBuffer putUnsignedInt(int index, long value);
1270
1271 /**
1272 * Writes an unsigned short into the ByteBuffer
1273 *
1274 * @param value the byte to write
1275 *
1276 * @return the modified IoBuffer
1277 */
1278 public abstract IoBuffer putUnsignedShort(byte value);
1279
1280 /**
1281 * Writes an unsigned Short into the ByteBuffer at a specified position
1282 *
1283 * @param index the position in the buffer to write the value
1284 * @param value the byte to write
1285 *
1286 * @return the modified IoBuffer
1287 */
1288 public abstract IoBuffer putUnsignedShort(int index, byte value);
1289
1290 /**
1291 * Writes an unsigned Short into the ByteBuffer
1292 *
1293 * @param value the short to write
1294 *
1295 * @return the modified IoBuffer
1296 */
1297 public abstract IoBuffer putUnsignedShort(short value);
1298
1299 /**
1300 * Writes an unsigned Short into the ByteBuffer at a specified position
1301 *
1302 * @param index the position in the buffer to write the unsigned short
1303 * @param value the unsigned short to write
1304 *
1305 * @return the modified IoBuffer
1306 */
1307 public abstract IoBuffer putUnsignedShort(int index, short value);
1308
1309 /**
1310 * Writes an unsigned Short into the ByteBuffer
1311 *
1312 * @param value the int to write
1313 *
1314 * @return the modified IoBuffer
1315 */
1316 public abstract IoBuffer putUnsignedShort(int value);
1317
1318 /**
1319 * Writes an unsigned Short into the ByteBuffer at a specified position
1320 *
1321 * @param index the position in the buffer to write the value
1322 * @param value the int to write
1323 * @return the modified IoBuffer
1324 */
1325 public abstract IoBuffer putUnsignedShort(int index, int value);
1326
1327 /**
1328 * Writes an unsigned Short into the ByteBuffer
1329 *
1330 * @param value the long to write
1331 *
1332 * @return the modified IoBuffer
1333 */
1334 public abstract IoBuffer putUnsignedShort(long value);
1335
1336 /**
1337 * Writes an unsigned Short into the ByteBuffer at a specified position
1338 *
1339 * @param index the position in the buffer to write the short
1340 * @param value the long to write
1341 *
1342 * @return the modified IoBuffer
1343 */
1344 public abstract IoBuffer putUnsignedShort(int index, long value);
1345
1346 /**
1347 * @see ByteBuffer#getInt(int)
1348 * @param index The index in the IoBuffer where we will read an int from
1349 * @return the int at the given position
1350 */
1351 public abstract int getInt(int index);
1352
1353 /**
1354 * Reads four bytes unsigned integer.
1355 * @param index The index in the IoBuffer where we will read an unsigned int from
1356 * @return The long at the given position
1357 */
1358 public abstract long getUnsignedInt(int index);
1359
1360 /**
1361 * @see ByteBuffer#putInt(int, int)
1362 *
1363 * @param index The position where to put the int
1364 * @param value The int to put in the IoBuffer
1365 * @return the modified IoBuffer
1366 */
1367 public abstract IoBuffer putInt(int index, int value);
1368
1369 /**
1370 * @see ByteBuffer#asIntBuffer()
1371 *
1372 * @return the modified IoBuffer
1373 */
1374 public abstract IntBuffer asIntBuffer();
1375
1376 /**
1377 * @see ByteBuffer#getLong()
1378 *
1379 * @return The long at the current position
1380 */
1381 public abstract long getLong();
1382
1383 /**
1384 * @see ByteBuffer#putLong(int, long)
1385 *
1386 * @param value The log to put in the IoBuffer
1387 * @return the modified IoBuffer
1388 */
1389 public abstract IoBuffer putLong(long value);
1390
1391 /**
1392 * @see ByteBuffer#getLong(int)
1393 *
1394 * @param index The index in the IoBuffer where we will read a long from
1395 * @return the long at the given position
1396 */
1397 public abstract long getLong(int index);
1398
1399 /**
1400 * @see ByteBuffer#putLong(int, long)
1401 *
1402 * @param index The position where to put the long
1403 * @param value The long to put in the IoBuffer
1404 * @return the modified IoBuffer
1405 */
1406 public abstract IoBuffer putLong(int index, long value);
1407
1408 /**
1409 * @see ByteBuffer#asLongBuffer()
1410 *
1411 * @return a LongBuffer from this IoBffer
1412 */
1413 public abstract LongBuffer asLongBuffer();
1414
1415 /**
1416 * @see ByteBuffer#getFloat()
1417 *
1418 * @return the float at the current position
1419 */
1420 public abstract float getFloat();
1421
1422 /**
1423 * @see ByteBuffer#putFloat(float)
1424 *
1425 * @param value The float to put in the IoBuffer
1426 * @return the modified IoBuffer
1427 */
1428 public abstract IoBuffer putFloat(float value);
1429
1430 /**
1431 * @see ByteBuffer#getFloat(int)
1432 *
1433 * @param index The index in the IoBuffer where we will read a float from
1434 * @return The float at the given position
1435 */
1436 public abstract float getFloat(int index);
1437
1438 /**
1439 * @see ByteBuffer#putFloat(int, float)
1440 *
1441 * @param index The position where to put the float
1442 * @param value The float to put in the IoBuffer
1443 * @return the modified IoBuffer
1444 */
1445 public abstract IoBuffer putFloat(int index, float value);
1446
1447 /**
1448 * @see ByteBuffer#asFloatBuffer()
1449 *
1450 * @return A FloatBuffer from this IoBuffer
1451 */
1452 public abstract FloatBuffer asFloatBuffer();
1453
1454 /**
1455 * @see ByteBuffer#getDouble()
1456 *
1457 * @return the double at the current position
1458 */
1459 public abstract double getDouble();
1460
1461 /**
1462 * @see ByteBuffer#putDouble(double)
1463 *
1464 * @param value The double to put at the IoBuffer current position
1465 * @return the modified IoBuffer
1466 */
1467 public abstract IoBuffer putDouble(double value);
1468
1469 /**
1470 * @see ByteBuffer#getDouble(int)
1471 *
1472 * @param index The position where to get the double from
1473 * @return The double at the given position
1474 */
1475 public abstract double getDouble(int index);
1476
1477 /**
1478 * @see ByteBuffer#putDouble(int, double)
1479 *
1480 * @param index The position where to put the double
1481 * @param value The double to put in the IoBuffer
1482 * @return the modified IoBuffer
1483 */
1484 public abstract IoBuffer putDouble(int index, double value);
1485
1486 /**
1487 * @see ByteBuffer#asDoubleBuffer()
1488 *
1489 * @return A buffer containing Double
1490 */
1491 public abstract DoubleBuffer asDoubleBuffer();
1492
1493 /**
1494 * @return an {@link InputStream} that reads the data from this buffer.
1495 * {@link InputStream#read()} returns <tt>-1</tt> if the buffer position
1496 * reaches to the limit.
1497 */
1498 public abstract InputStream asInputStream();
1499
1500 /**
1501 * @return an {@link OutputStream} that appends the data into this buffer.
1502 * Please note that the {@link OutputStream#write(int)} will throw a
1503 * {@link BufferOverflowException} instead of an {@link IOException} in case
1504 * of buffer overflow. Please set <tt>autoExpand</tt> property by calling
1505 * {@link #setAutoExpand(boolean)} to prevent the unexpected runtime
1506 * exception.
1507 */
1508 public abstract OutputStream asOutputStream();
1509
1510 /**
1511 * Returns hexdump of this buffer. The data and pointer are not changed as a
1512 * result of this method call.
1513 *
1514 * @return hexidecimal representation of this buffer
1515 */
1516 public abstract String getHexDump();
1517
1518 /**
1519 * Return hexdump of this buffer with limited length.
1520 *
1521 * @param lengthLimit
1522 * The maximum number of bytes to dump from the current buffer
1523 * position.
1524 * @return hexidecimal representation of this buffer
1525 */
1526 public abstract String getHexDump(int lengthLimit);
1527
1528 // //////////////////////////////
1529 // String getters and putters //
1530 // //////////////////////////////
1531
1532 /**
1533 * Reads a <code>NUL</code>-terminated string from this buffer using the
1534 * specified <code>decoder</code> and returns it. This method reads until
1535 * the limit of this buffer if no <tt>NUL</tt> is found.
1536 *
1537 * @param decoder The {@link CharsetDecoder} to use
1538 * @return the read String
1539 * @exception CharacterCodingException Thrown when an error occurred while decoding the buffer
1540 */
1541 public abstract String getString(CharsetDecoder decoder) throws CharacterCodingException;
1542
1543 /**
1544 * Reads a <code>NUL</code>-terminated string from this buffer using the
1545 * specified <code>decoder</code> and returns it.
1546 *
1547 * @param fieldSize the maximum number of bytes to read
1548 * @param decoder The {@link CharsetDecoder} to use
1549 * @return the read String
1550 * @exception CharacterCodingException Thrown when an error occurred while decoding the buffer
1551 */
1552 public abstract String getString(int fieldSize, CharsetDecoder decoder) throws CharacterCodingException;
1553
1554 /**
1555 * Writes the content of <code>in</code> into this buffer using the
1556 * specified <code>encoder</code>. This method doesn't terminate string with
1557 * <tt>NUL</tt>. You have to do it by yourself.
1558 *
1559 * @param val The CharSequence to put in the IoBuffer
1560 * @param encoder The CharsetEncoder to use
1561 * @return The modified IoBuffer
1562 * @throws CharacterCodingException When we have an error while decoding the String
1563 */
1564 public abstract IoBuffer putString(CharSequence val, CharsetEncoder encoder) throws CharacterCodingException;
1565
1566 /**
1567 * Writes the content of <code>in</code> into this buffer as a
1568 * <code>NUL</code>-terminated string using the specified
1569 * <code>encoder</code>.
1570 * <p>
1571 * If the charset name of the encoder is UTF-16, you cannot specify odd
1572 * <code>fieldSize</code>, and this method will append two <code>NUL</code>s
1573 * as a terminator.
1574 * <p>
1575 * Please note that this method doesn't terminate with <code>NUL</code> if
1576 * the input string is longer than <tt>fieldSize</tt>.
1577 *
1578 * @param val The CharSequence to put in the IoBuffer
1579 * @param fieldSize the maximum number of bytes to write
1580 * @param encoder The CharsetEncoder to use
1581 * @return The modified IoBuffer
1582 * @throws CharacterCodingException When we have an error while decoding the String
1583 */
1584 public abstract IoBuffer putString(CharSequence val, int fieldSize, CharsetEncoder encoder)
1585 throws CharacterCodingException;
1586
1587 /**
1588 * Reads a string which has a 16-bit length field before the actual encoded
1589 * string, using the specified <code>decoder</code> and returns it. This
1590 * method is a shortcut for <tt>getPrefixedString(2, decoder)</tt>.
1591 *
1592 * @param decoder The CharsetDecoder to use
1593 * @return The read String
1594 *
1595 * @throws CharacterCodingException When we have an error while decoding the String
1596 */
1597 public abstract String getPrefixedString(CharsetDecoder decoder) throws CharacterCodingException;
1598
1599 /**
1600 * Reads a string which has a length field before the actual encoded string,
1601 * using the specified <code>decoder</code> and returns it.
1602 *
1603 * @param prefixLength the length of the length field (1, 2, or 4)
1604 * @param decoder The CharsetDecoder to use
1605 * @return The read String
1606 *
1607 * @throws CharacterCodingException When we have an error while decoding the String
1608 */
1609 public abstract String getPrefixedString(int prefixLength, CharsetDecoder decoder) throws CharacterCodingException;
1610
1611 /**
1612 * Writes the content of <code>in</code> into this buffer as a string which
1613 * has a 16-bit length field before the actual encoded string, using the
1614 * specified <code>encoder</code>. This method is a shortcut for
1615 * <tt>putPrefixedString(in, 2, 0, encoder)</tt>.
1616 *
1617 * @param in The CharSequence to put in the IoBuffer
1618 * @param encoder The CharsetEncoder to use
1619 * @return The modified IoBuffer
1620 *
1621 * @throws CharacterCodingException When we have an error while decoding the CharSequence
1622 */
1623 public abstract IoBuffer putPrefixedString(CharSequence in, CharsetEncoder encoder) throws CharacterCodingException;
1624
1625 /**
1626 * Writes the content of <code>in</code> into this buffer as a string which
1627 * has a 16-bit length field before the actual encoded string, using the
1628 * specified <code>encoder</code>. This method is a shortcut for
1629 * <tt>putPrefixedString(in, prefixLength, 0, encoder)</tt>.
1630 *
1631 * @param in The CharSequence to put in the IoBuffer
1632 * @param prefixLength the length of the length field (1, 2, or 4)
1633 * @param encoder The CharsetEncoder to use
1634 * @return The modified IoBuffer
1635 *
1636 * @throws CharacterCodingException When we have an error while decoding the CharSequence
1637 */
1638 public abstract IoBuffer putPrefixedString(CharSequence in, int prefixLength, CharsetEncoder encoder)
1639 throws CharacterCodingException;
1640
1641 /**
1642 * Writes the content of <code>in</code> into this buffer as a string which
1643 * has a 16-bit length field before the actual encoded string, using the
1644 * specified <code>encoder</code>. This method is a shortcut for
1645 * <tt>putPrefixedString(in, prefixLength, padding, ( byte ) 0, encoder)</tt>
1646 *
1647 * @param in The CharSequence to put in the IoBuffer
1648 * @param prefixLength the length of the length field (1, 2, or 4)
1649 * @param padding the number of padded <tt>NUL</tt>s (1 (or 0), 2, or 4)
1650 * @param encoder The CharsetEncoder to use
1651 * @return The modified IoBuffer
1652 *
1653 * @throws CharacterCodingException When we have an error while decoding the CharSequence
1654 */
1655 public abstract IoBuffer putPrefixedString(CharSequence in, int prefixLength, int padding, CharsetEncoder encoder)
1656 throws CharacterCodingException;
1657
1658 /**
1659 * Writes the content of <code>val</code> into this buffer as a string which
1660 * has a 16-bit length field before the actual encoded string, using the
1661 * specified <code>encoder</code>.
1662 *
1663 * @param val The CharSequence to put in teh IoBuffer
1664 * @param prefixLength the length of the length field (1, 2, or 4)
1665 * @param padding the number of padded bytes (1 (or 0), 2, or 4)
1666 * @param padValue the value of padded bytes
1667 * @param encoder The CharsetEncoder to use
1668 * @return The modified IoBuffer
1669 * @throws CharacterCodingException When we have an error while decoding the CharSequence
1670 */
1671 public abstract IoBuffer putPrefixedString(CharSequence val, int prefixLength, int padding, byte padValue,
1672 CharsetEncoder encoder) throws CharacterCodingException;
1673
1674 /**
1675 * Reads a Java object from the buffer using the context {@link ClassLoader}
1676 * of the current thread.
1677 *
1678 * @return The read Object
1679 * @throws ClassNotFoundException thrown when we can't find the Class to use
1680 */
1681 public abstract Object getObject() throws ClassNotFoundException;
1682
1683 /**
1684 * Reads a Java object from the buffer using the specified
1685 * <tt>classLoader</tt>.
1686 *
1687 * @param classLoader The classLoader to use to read an Object from the IoBuffer
1688 * @return The read Object
1689 * @throws ClassNotFoundException thrown when we can't find the Class to use
1690 */
1691 public abstract Object getObject(final ClassLoader classLoader) throws ClassNotFoundException;
1692
1693 /**
1694 * Writes the specified Java object to the buffer.
1695 *
1696 * @param o The Object to write in the IoBuffer
1697 * @return The modified IoBuffer
1698 */
1699 public abstract IoBuffer putObject(Object o);
1700
1701 /**
1702 *
1703 * @param prefixLength the length of the prefix field (1, 2, or 4)
1704 * @return <tt>true</tt> if this buffer contains a data which has a data
1705 * length as a prefix and the buffer has remaining data as enough as
1706 * specified in the data length field. This method is identical with
1707 * <tt>prefixedDataAvailable( prefixLength, Integer.MAX_VALUE )</tt>. Please
1708 * not that using this method can allow DoS (Denial of Service) attack in
1709 * case the remote peer sends too big data length value. It is recommended
1710 * to use {@link #prefixedDataAvailable(int, int)} instead.
1711 * @throws IllegalArgumentException if prefixLength is wrong
1712 * @throws BufferDataException if data length is negative
1713 */
1714 public abstract boolean prefixedDataAvailable(int prefixLength);
1715
1716 /**
1717 * @param prefixLength the length of the prefix field (1, 2, or 4)
1718 * @param maxDataLength the allowed maximum of the read data length
1719 * @return <tt>true</tt> if this buffer contains a data which has a data
1720 * length as a prefix and the buffer has remaining data as enough as
1721 * specified in the data length field.
1722 * @throws IllegalArgumentException
1723 * if prefixLength is wrong
1724 * @throws BufferDataException
1725 * if data length is negative or greater then
1726 * <tt>maxDataLength</tt>
1727 */
1728 public abstract boolean prefixedDataAvailable(int prefixLength, int maxDataLength);
1729
1730 // ///////////////////
1731 // IndexOf methods //
1732 // ///////////////////
1733
1734 /**
1735 * Returns the first occurrence position of the specified byte from the
1736 * current position to the current limit.
1737 *
1738 * @param b The byte we are looking for
1739 * @return <tt>-1</tt> if the specified byte is not found
1740 */
1741 public abstract int indexOf(byte b);
1742
1743 // ////////////////////////
1744 // Skip or fill methods //
1745 // ////////////////////////
1746
1747 /**
1748 * Forwards the position of this buffer as the specified <code>size</code>
1749 * bytes.
1750 *
1751 * @param size The added size
1752 * @return The modified IoBuffer
1753 */
1754 public abstract IoBuffer skip(int size);
1755
1756 /**
1757 * Fills this buffer with the specified value. This method moves buffer
1758 * position forward.
1759 *
1760 * @param value The value to fill the IoBuffer with
1761 * @param size The added size
1762 * @return The modified IoBuffer
1763 */
1764 public abstract IoBuffer fill(byte value, int size);
1765
1766 /**
1767 * Fills this buffer with the specified value. This method does not change
1768 * buffer position.
1769 *
1770 * @param value The value to fill the IoBuffer with
1771 * @param size The added size
1772 * @return The modified IoBuffer
1773 */
1774 public abstract IoBuffer fillAndReset(byte value, int size);
1775
1776 /**
1777 * Fills this buffer with <code>NUL (0x00)</code>. This method moves buffer
1778 * position forward.
1779 *
1780 * @param size The added size
1781 * @return The modified IoBuffer
1782 */
1783 public abstract IoBuffer fill(int size);
1784
1785 /**
1786 * Fills this buffer with <code>NUL (0x00)</code>. This method does not
1787 * change buffer position.
1788 *
1789 * @param size The added size
1790 * @return The modified IoBuffer
1791 */
1792 public abstract IoBuffer fillAndReset(int size);
1793
1794 // ////////////////////////
1795 // Enum methods //
1796 // ////////////////////////
1797
1798 /**
1799 * Reads a byte from the buffer and returns the correlating enum constant
1800 * defined by the specified enum type.
1801 *
1802 * @param <E> The enum type to return
1803 * @param enumClass The enum's class object
1804 * @return The correlated enum constant
1805 */
1806 public abstract <E extends Enum<E>> E getEnum(Class<E> enumClass);
1807
1808 /**
1809 * Reads a byte from the buffer and returns the correlating enum constant
1810 * defined by the specified enum type.
1811 *
1812 * @param <E> The enum type to return
1813 * @param index the index from which the byte will be read
1814 * @param enumClass The enum's class object
1815 * @return The correlated enum constant
1816 */
1817 public abstract <E extends Enum<E>> E getEnum(int index, Class<E> enumClass);
1818
1819 /**
1820 * Reads a short from the buffer and returns the correlating enum constant
1821 * defined by the specified enum type.
1822 *
1823 * @param <E> The enum type to return
1824 * @param enumClass The enum's class object
1825 * @return The correlated enum constant
1826 */
1827 public abstract <E extends Enum<E>> E getEnumShort(Class<E> enumClass);
1828
1829 /**
1830 * Reads a short from the buffer and returns the correlating enum constant
1831 * defined by the specified enum type.
1832 *
1833 * @param <E> The enum type to return
1834 * @param index the index from which the bytes will be read
1835 * @param enumClass The enum's class object
1836 * @return The correlated enum constant
1837 */
1838 public abstract <E extends Enum<E>> E getEnumShort(int index, Class<E> enumClass);
1839
1840 /**
1841 * Reads an int from the buffer and returns the correlating enum constant
1842 * defined by the specified enum type.
1843 *
1844 * @param <E> The enum type to return
1845 * @param enumClass The enum's class object
1846 * @return The correlated enum constant
1847 */
1848 public abstract <E extends Enum<E>> E getEnumInt(Class<E> enumClass);
1849
1850 /**
1851 * Reads an int from the buffer and returns the correlating enum constant
1852 * defined by the specified enum type.
1853 *
1854 * @param <E> The enum type to return
1855 * @param index the index from which the bytes will be read
1856 * @param enumClass The enum's class object
1857 * @return The correlated enum constant
1858 */
1859 public abstract <E extends Enum<E>> E getEnumInt(int index, Class<E> enumClass);
1860
1861 /**
1862 * Writes an enum's ordinal value to the buffer as a byte.
1863 *
1864 * @param e The enum to write to the buffer
1865 * @return The modified IoBuffer
1866 */
1867 public abstract IoBuffer putEnum(Enum<?> e);
1868
1869 /**
1870 * Writes an enum's ordinal value to the buffer as a byte.
1871 *
1872 * @param index The index at which the byte will be written
1873 * @param e The enum to write to the buffer
1874 * @return The modified IoBuffer
1875 */
1876 public abstract IoBuffer putEnum(int index, Enum<?> e);
1877
1878 /**
1879 * Writes an enum's ordinal value to the buffer as a short.
1880 *
1881 * @param e The enum to write to the buffer
1882 * @return The modified IoBuffer
1883 */
1884 public abstract IoBuffer putEnumShort(Enum<?> e);
1885
1886 /**
1887 * Writes an enum's ordinal value to the buffer as a short.
1888 *
1889 * @param index The index at which the bytes will be written
1890 * @param e The enum to write to the buffer
1891 * @return The modified IoBuffer
1892 */
1893 public abstract IoBuffer putEnumShort(int index, Enum<?> e);
1894
1895 /**
1896 * Writes an enum's ordinal value to the buffer as an integer.
1897 *
1898 * @param e The enum to write to the buffer
1899 * @return The modified IoBuffer
1900 */
1901 public abstract IoBuffer putEnumInt(Enum<?> e);
1902
1903 /**
1904 * Writes an enum's ordinal value to the buffer as an integer.
1905 *
1906 * @param index The index at which the bytes will be written
1907 * @param e The enum to write to the buffer
1908 * @return The modified IoBuffer
1909 */
1910 public abstract IoBuffer putEnumInt(int index, Enum<?> e);
1911
1912 // ////////////////////////
1913 // EnumSet methods //
1914 // ////////////////////////
1915
1916 /**
1917 * Reads a byte sized bit vector and converts it to an {@link EnumSet}.
1918 *
1919 * <p>
1920 * Each bit is mapped to a value in the specified enum. The least
1921 * significant bit maps to the first entry in the specified enum and each
1922 * subsequent bit maps to each subsequent bit as mapped to the subsequent
1923 * enum value.
1924 *
1925 * @param <E> the enum type
1926 * @param enumClass the enum class used to create the EnumSet
1927 * @return the EnumSet representation of the bit vector
1928 */
1929 public abstract <E extends Enum<E>> Set<E> getEnumSet(Class<E> enumClass);
1930
1931 /**
1932 * Reads a byte sized bit vector and converts it to an {@link EnumSet}.
1933 *
1934 * @see #getEnumSet(Class)
1935 * @param <E> the enum type
1936 * @param index the index from which the byte will be read
1937 * @param enumClass the enum class used to create the EnumSet
1938 * @return the EnumSet representation of the bit vector
1939 */
1940 public abstract <E extends Enum<E>> Set<E> getEnumSet(int index, Class<E> enumClass);
1941
1942 /**
1943 * Reads a short sized bit vector and converts it to an {@link EnumSet}.
1944 *
1945 * @see #getEnumSet(Class)
1946 * @param <E> the enum type
1947 * @param enumClass the enum class used to create the EnumSet
1948 * @return the EnumSet representation of the bit vector
1949 */
1950 public abstract <E extends Enum<E>> Set<E> getEnumSetShort(Class<E> enumClass);
1951
1952 /**
1953 * Reads a short sized bit vector and converts it to an {@link EnumSet}.
1954 *
1955 * @see #getEnumSet(Class)
1956 * @param <E> the enum type
1957 * @param index the index from which the bytes will be read
1958 * @param enumClass the enum class used to create the EnumSet
1959 * @return the EnumSet representation of the bit vector
1960 */
1961 public abstract <E extends Enum<E>> Set<E> getEnumSetShort(int index, Class<E> enumClass);
1962
1963 /**
1964 * Reads an int sized bit vector and converts it to an {@link EnumSet}.
1965 *
1966 * @see #getEnumSet(Class)
1967 * @param <E> the enum type
1968 * @param enumClass the enum class used to create the EnumSet
1969 * @return the EnumSet representation of the bit vector
1970 */
1971 public abstract <E extends Enum<E>> Set<E> getEnumSetInt(Class<E> enumClass);
1972
1973 /**
1974 * Reads an int sized bit vector and converts it to an {@link EnumSet}.
1975 *
1976 * @see #getEnumSet(Class)
1977 * @param <E> the enum type
1978 * @param index the index from which the bytes will be read
1979 * @param enumClass the enum class used to create the EnumSet
1980 * @return the EnumSet representation of the bit vector
1981 */
1982 public abstract <E extends Enum<E>> Set<E> getEnumSetInt(int index, Class<E> enumClass);
1983
1984 /**
1985 * Reads a long sized bit vector and converts it to an {@link EnumSet}.
1986 *
1987 * @see #getEnumSet(Class)
1988 * @param <E> the enum type
1989 * @param enumClass the enum class used to create the EnumSet
1990 * @return the EnumSet representation of the bit vector
1991 */
1992 public abstract <E extends Enum<E>> Set<E> getEnumSetLong(Class<E> enumClass);
1993
1994 /**
1995 * Reads a long sized bit vector and converts it to an {@link EnumSet}.
1996 *
1997 * @see #getEnumSet(Class)
1998 * @param <E> the enum type
1999 * @param index the index from which the bytes will be read
2000 * @param enumClass the enum class used to create the EnumSet
2001 * @return the EnumSet representation of the bit vector
2002 */
2003 public abstract <E extends Enum<E>> Set<E> getEnumSetLong(int index, Class<E> enumClass);
2004
2005 /**
2006 * Writes the specified {@link Set} to the buffer as a byte sized bit
2007 * vector.
2008 *
2009 * @param <E> the enum type of the Set
2010 * @param set the enum set to write to the buffer
2011 * @return the modified IoBuffer
2012 */
2013 public abstract <E extends Enum<E>> IoBuffer putEnumSet(Set<E> set);
2014
2015 /**
2016 * Writes the specified {@link Set} to the buffer as a byte sized bit
2017 * vector.
2018 *
2019 * @param <E> the enum type of the Set
2020 * @param index the index at which the byte will be written
2021 * @param set the enum set to write to the buffer
2022 * @return the modified IoBuffer
2023 */
2024 public abstract <E extends Enum<E>> IoBuffer putEnumSet(int index, Set<E> set);
2025
2026 /**
2027 * Writes the specified {@link Set} to the buffer as a short sized bit
2028 * vector.
2029 *
2030 * @param <E> the enum type of the Set
2031 * @param set the enum set to write to the buffer
2032 * @return the modified IoBuffer
2033 */
2034 public abstract <E extends Enum<E>> IoBuffer putEnumSetShort(Set<E> set);
2035
2036 /**
2037 * Writes the specified {@link Set} to the buffer as a short sized bit
2038 * vector.
2039 *
2040 * @param <E> the enum type of the Set
2041 * @param index the index at which the bytes will be written
2042 * @param set the enum set to write to the buffer
2043 * @return the modified IoBuffer
2044 */
2045 public abstract <E extends Enum<E>> IoBuffer putEnumSetShort(int index, Set<E> set);
2046
2047 /**
2048 * Writes the specified {@link Set} to the buffer as an int sized bit
2049 * vector.
2050 *
2051 * @param <E> the enum type of the Set
2052 * @param set the enum set to write to the buffer
2053 * @return the modified IoBuffer
2054 */
2055 public abstract <E extends Enum<E>> IoBuffer putEnumSetInt(Set<E> set);
2056
2057 /**
2058 * Writes the specified {@link Set} to the buffer as an int sized bit
2059 * vector.
2060 *
2061 * @param <E> the enum type of the Set
2062 * @param index the index at which the bytes will be written
2063 * @param set the enum set to write to the buffer
2064 * @return the modified IoBuffer
2065 */
2066 public abstract <E extends Enum<E>> IoBuffer putEnumSetInt(int index, Set<E> set);
2067
2068 /**
2069 * Writes the specified {@link Set} to the buffer as a long sized bit
2070 * vector.
2071 *
2072 * @param <E> the enum type of the Set
2073 * @param set the enum set to write to the buffer
2074 * @return the modified IoBuffer
2075 */
2076 public abstract <E extends Enum<E>> IoBuffer putEnumSetLong(Set<E> set);
2077
2078 /**
2079 * Writes the specified {@link Set} to the buffer as a long sized bit
2080 * vector.
2081 *
2082 * @param <E> the enum type of the Set
2083 * @param index the index at which the bytes will be written
2084 * @param set the enum set to write to the buffer
2085 * @return the modified IoBuffer
2086 */
2087 public abstract <E extends Enum<E>> IoBuffer putEnumSetLong(int index, Set<E> set);
2088 }