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