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