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

[tr...@apache.org]

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 {@link BufferOverflowException} or
+ * {@link 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 (trustin@apache.org)
  * @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();

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

[Enrique Rodriguez <er...@apache.org>]

Collections API javadocs use the term 'resize' and that appears 
elsewhere (AWT).  Maybe:

public void setResizable(boolean resizable)

... and ...

public boolean isResizable()

-enrique


Alex Karasulu wrote:
> Ok I see what autoExpand is for now a buffer that can grow 
> automatically.  This is why slice() and other operations may not seem 
> reasonable anymore from an implementation perspective.
> Makes sense but 'autoExpand' there has to be a better name out there.  I 
> did not get it until I read the docs.  Perhaps there's a name that you 
> can use that better expressess the functionality without requireing the 
> user to have  to hit the javadocs.
> 
> Just my $0.02,
> Alex

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

[Alex Karasulu <ao...@bellsouth.net>]

Ok I see what autoExpand is for now a buffer that can grow 
automatically.  This is why slice() and other operations may not seem 
reasonable anymore from an implementation perspective. 

Makes sense but 'autoExpand' there has to be a better name out there.  I 
did not get it until I read the docs.  Perhaps there's a name that you 
can use that better expressess the functionality without requireing the 
user to have  to hit the javadocs.

Just my $0.02,
Alex