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 }