svn commit: r161903 - directory/network/trunk/src/java/org/apache/mina/common/ByteBuffer.java

[trustin]

Author: trustin
Date: Tue Apr 19 08:14:14 2005
New Revision: 161903

URL: http://svn.apache.org/viewcvs?view=rev&rev=161903
Log:
Added documentation about autoExpand

Modified:
    directory/network/trunk/src/java/org/apache/mina/common/ByteBuffer.java

Modified: 
directory/network/trunk/src/java/org/apache/mina/common/ByteBuffer.java
URL: 
http://svn.apache.org/viewcvs/directory/network/trunk/src/java/org/apache/mina/common/ByteBuffer.java?view=diff&r1=161902&r2=161903
==============================================================================
--- directory/network/trunk/src/java/org/apache/mina/common/ByteBuffer.java 
(original)
+++ directory/network/trunk/src/java/org/apache/mina/common/ByteBuffer.java Tue 
Apr 19 08:14:14 2005
@@ -47,16 +47,26 @@
  *       <code>get/putAsciiInt()</code> enough.</li>
  *   <li>It is hard to distinguish if the buffer is created from MINA buffer
  *       pool or not.  MINA have to return used buffers back to pool.</li>
+ *   <li>It is difficult to write variable-length data due to its fixed
+ *       capacity</li>
  * </ul>
+ * 
+ * <h2>Allocation</h2>
  * <p>
  * You can get a heap buffer from buffer pool:
  * <pre>
- * ByteBuffer buf = ByteBuffer.allocate(1024);
+ * ByteBuffer buf = ByteBuffer.allocate(1024, false);
  * </pre>
- * or you can get a direct buffer from buffer pool:
+ * you can also get a direct buffer from buffer pool:
  * <pre>
- * ByteBuffer buf = ByteBuffer.allocate(1024, false);
+ * ByteBuffer buf = ByteBuffer.allocate(1024, true);
  * </pre>
+ * or you can let MINA choose:
+ * <pre>
+ * ByteBuffer buf = ByteBuffer.allocate(1024);
+ * </pre>
+ * 
+ * <h2>Acquire/Release</h2>
  * <p>
  * <b>Please note that you never need to release the allocated buffer because
  * MINA will release it automatically.</b>  But, if you didn't pass it to MINA
@@ -65,6 +75,26 @@
  * ByteBuffer.release(buf);
  * </pre>
  * 
+ * <h2>AutoExpand</h2>
+ * <p>
+ * Writing variable-length data using NIO <tt>ByteBuffers</tt> is not really
+ * easy, and it is because its size is fixed.  MINA <tt>ByteBuffer</tt>
+ * introduces <tt>autoExpand</tt> property.  If <tt>autoExpand</tt> property
+ * is true, you never get [EMAIL PROTECTED] BufferOverflowException} or
+ * [EMAIL PROTECTED] IndexOutOfBoundsException} (except when index is 
negative).
+ * It automatically expands its capacity and limit value.  For example:
+ * <pre>
+ * String greeting = messageBundle.getMessage( "hello" );
+ * ByteBuffer buf = ByteBuffer.allocate( 16 );
+ * // Turn on autoExpand (it is off by default)
+ * buf.setAutoExpand( true );
+ * buf.putString( greeting, utf8encoder );
+ * </pre>
+ * NIO <tt>ByteBuffer</tt> is reallocated by MINA <tt>ByteBuffer</tt> behind
+ * the scene if the encoded data is larger than 16 bytes.  Its capacity will
+ * increase by two times, and its limit will increase to the last position
+ * the string is written.
+ * 
  * @author Trustin Lee ([EMAIL PROTECTED])
  * @version $Rev$, $Date$
  */
@@ -234,8 +264,14 @@
     
     public abstract int capacity();
     
+    /**
+     * Returns <tt>true</tt> if and only if <tt>autoExpand</tt> is turned on.
+     */
     public abstract boolean isAutoExpand();
     
+    /**
+     * Turns on or off <tt>autoExpand</tt>.
+     */
     public abstract ByteBuffer setAutoExpand( boolean autoExpand );
     
     public abstract int position();