View Javadoc
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(&quot;hello&quot;);
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 &lt; C and V &gt; 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 &lt;= C :
377      * 
378      *   0       L          C
379      *  +--------+----------+
380      *  |XXXXXXXX|          |
381      *  +--------+----------+
382      *   ^       ^          ^
383      *   |       |          |
384      *  pos    limit   newCapacity
385      *  
386      * V &gt; 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 )  &lt;= 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 ) &gt; L &amp; ( pos + V ) &lt;= 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 ) &gt; 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 )  &lt;= 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 ) &gt; L &amp; ( pos + V ) &lt;= 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 ) &gt; 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 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 }