Adding JavaDoc - part 2

Author: frsyuki

msgpack-core/src/main/java/org/msgpack/core/MessageBufferPacker.java

@@ -23,7 +23,11 @@
 import java.util.List;
 
 /**
- * MessagePacker that is useful to produce byte array output
+ * MessagePacker that is useful to produce byte array output.
+ * <p>
+ * This class allocates a new buffer instead of resizing the buffer when data doesn't fit in the initial capacity.
+ * This is faster than ByteArrayOutputStream especially when size of written bytes is large because resizing a buffer
+ * usually needs to copy contents of the buffer.
  */
 public class MessageBufferPacker
         extends MessagePacker
@@ -52,11 +56,22 @@ private ArrayBufferOutput getArrayBufferOut()
         return (ArrayBufferOutput) out;
     }
 
+    /**
+     * Clears the written data.
+     */
     public void clear()
     {
         getArrayBufferOut().clear();
     }
 
+    /**
+     * Gets copy of the written data as a byte array.
+     * <p>
+     * If your application needs better performance and smaller memory consumption, you may prefer
+     * {@link #toMessageBuffer()} or {@link #toBufferList()} to avoid copying.
+     *
+     * @return the byte array
+     */
     public byte[] toByteArray()
     {
         try {
@@ -69,6 +84,14 @@ public byte[] toByteArray()
         return getArrayBufferOut().toByteArray();
     }
 
+    /**
+     * Gets the written data as a MessageBuffer.
+     * <p>
+     * Unlike {@link #toByteArray()}, this method omits copy of the contents if size of the written data is smaller
+     * than a single buffer capacity.
+     *
+     * @return the MessageBuffer instance
+     */
     public MessageBuffer toMessageBuffer()
     {
         try {
@@ -81,6 +104,14 @@ public MessageBuffer toMessageBuffer()
         return getArrayBufferOut().toMessageBuffer();
     }
 
+    /**
+     * Returns the written data as a list of MessageBuffer.
+     * <p>
+     * Unlike {@link #toByteArray()} or {@link #toMessageBuffer()}, this is the fastest method that doesn't
+     * copy contents in any cases.
+     *
+     * @return the list of MessageBuffer instances
+     */
     public List<MessageBuffer> toBufferList()
     {
         try {

msgpack-core/src/main/java/org/msgpack/core/MessagePack.java

@@ -35,7 +35,7 @@
 /**
  * Convenience class to build packer and unpacker classes.
  *
- * You may choose factory method as following
+ * You can select an appropriate factory method as following.
  *
  * <p>
  * Deserializing objects from binary:
@@ -70,12 +70,12 @@ public class MessagePack
     public static final Charset UTF8 = Charset.forName("UTF-8");
 
     /**
-     * Configuration of a {@link MessagePacker} created by {@link #newDefaultPacker(MessageBufferOutput)} and {@link #newDefaultBufferPacker()} methods.
+     * Configuration of a {@link MessagePacker} used by {@link #newDefaultPacker(MessageBufferOutput)} and {@link #newDefaultBufferPacker()} methods.
      */
     public static final PackerConfig DEFAULT_PACKER_CONFIG = new PackerConfig();
 
     /**
-     * Configuration of a {@link MessageUnpacker} created by {@link #newDefaultUnpacker(MessageBufferInput)} methods.
+     * Configuration of a {@link MessageUnpacker} used by {@link #newDefaultUnpacker(MessageBufferInput)} methods.
      */
     public static final UnpackerConfig DEFAULT_UNPACKER_CONFIG = new UnpackerConfig();
 

msgpack-core/src/main/java/org/msgpack/core/MessagePacker.java

@@ -72,7 +72,7 @@
  * an instance.
  * <p>
  * This class provides following primitive methods to write MessagePack values. These primitive methods write
- * short bytes (1 to 7 bytes) to the internal buffer at once. There also some complex methods for convenience.
+ * short bytes (1 to 7 bytes) to the internal buffer at once. There are also some complex methods for convenience.
  * <p>
  * Primitive methods:
  *
@@ -110,13 +110,13 @@
  *
  * <p>
  * To write a List, Collection or array, first you call {@link #packArrayHeader(int)} method with the number of
- * elements. Then, you call packer methods for each element. You don't have to call anything at the end of
+ * elements. Then, you call packer methods for each element.
  * iteration.
  *
  * <p>
  * To write a Map, first you call {@link #packMapHeader(int)} method with size of the map. Then, for each pair,
  * you call packer methods for key first, and then value. You will call packer methods twice as many time as the
- * size of the map. You don't have to call anything at the end of iteration.
+ * size of the map.
  *
  * <p>
  * Note that packXxxHeader methods don't validate number of elements. You must call packer methods for correct

msgpack-core/src/main/java/org/msgpack/core/MessageUnpacker.java

@@ -139,12 +139,12 @@
  *
  * <p>
  * To read an Array type, first you call {@link #unpackArrayHeader()} method to get number of elements. Then,
- * you call unpacker methods for each element. You don't have to call anything at the end of iteration.
+ * you call unpacker methods for each element.
  *
  * <p>
  * To read a Map, first you call {@link #unpackMapHeader(int)} method to get number of pairs of the map. Then,
  * for each pair, you call unpacker methods for key first, and then value. You will call unpacker methods twice
- * as many time as the returned count. You don't have to call anything at the end of iteration.
+ * as many time as the returned count.
  *
  */
 public class MessageUnpacker

msgpack-core/src/main/java/org/msgpack/core/buffer/ArrayBufferOutput.java

@@ -19,7 +19,11 @@
 import java.util.ArrayList;
 
 /**
- * MessageBufferOutput adapter that packs data into list of byte arrays.
+ * MessageBufferOutput adapter that writes data into a list of byte arrays.
+ * <p>
+ * This class allocates a new buffer instead of resizing the buffer when data doesn't fit in the initial capacity.
+ * This is faster than ByteArrayOutputStream especially when size of written bytes is large because resizing a buffer
+ * usually needs to copy contents of the buffer.
  */
 public class ArrayBufferOutput
         implements MessageBufferOutput
@@ -39,6 +43,11 @@ public ArrayBufferOutput(int bufferSize)
         this.list = new ArrayList<MessageBuffer>();
     }
 
+    /**
+     * Gets size of the written data.
+     *
+     * @return number of bytes
+     */
     public int getSize()
     {
         int size = 0;
@@ -48,6 +57,14 @@ public int getSize()
         return size;
     }
 
+    /**
+     * Gets copy of the written data as a byte array.
+     * <p>
+     * If your application needs better performance and smaller memory consumption, you may prefer
+     * {@link #toMessageBuffer()} or {@link #toBufferList()} to avoid copying.
+     *
+     * @return the byte array
+     */
     public byte[] toByteArray()
     {
         byte[] data = new byte[getSize()];
@@ -59,6 +76,14 @@ public byte[] toByteArray()
         return data;
     }
 
+    /**
+     * Gets the written data as a MessageBuffer.
+     * <p>
+     * Unlike {@link #toByteArray()}, this method omits copy of the contents if size of the written data is smaller
+     * than a single buffer capacity.
+     *
+     * @return the MessageBuffer instance
+     */
     public MessageBuffer toMessageBuffer()
     {
         if (list.size() == 1) {
@@ -72,13 +97,21 @@ else if (list.isEmpty()) {
         }
     }
 
+    /**
+     * Returns the written data as a list of MessageBuffer.
+     * <p>
+     * Unlike {@link #toByteArray()} or {@link #toMessageBuffer()}, this is the fastest method that doesn't
+     * copy contents in any cases.
+     *
+     * @return the list of MessageBuffer instances
+     */
     public List<MessageBuffer> toBufferList()
     {
         return new ArrayList<MessageBuffer>(list);
     }
 
     /**
-     * Clears the internal buffers
+     * Clears the written data.
      */
     public void clear()
     {

msgpack-core/src/main/java/org/msgpack/core/buffer/MessageBuffer.java

@@ -28,12 +28,20 @@
 import static org.msgpack.core.Preconditions.checkNotNull;
 
 /**
- * MessageBuffer class is an abstraction of memory for reading/writing message packed data.
- * This MessageBuffers ensures short/int/float/long/double values are written in the big-endian order.
- * <p/>
- * This class is optimized for fast memory access, so many methods are
- * implemented without using any interface method that produces invokeinterface call in JVM.
- * Compared to invokevirtual, invokeinterface is 30% slower in general because it needs to find a target function from the table.
+ * MessageBuffer class is an abstraction of memory with fast methods to serialize and deserialize primitive values
+ * to/from the memory. All MessageBuffer implementations ensure short/int/float/long/double values are written in
+ * big-endian order.
+ * <p>
+ * Applications can allocate a new buffer using {@link #allocate(int)} method, or wrap an byte array or ByteBuffer
+ * using {@link wrap(byte[], int, int)} methods. {@link wrap(ByteBuffer)} method supports both direct buffers and
+ * array-backed buffers.
+ * <p>
+ * MessageBuffer class itself is optimized for little-endian CPU archtectures so that JVM (HotSpot) can take advantage
+ * of the fastest JIT format which skips TypeProfile checking. To ensure this performance, applications must not load
+ * unnecessary classes such as MessagePackBE. On big-endian CPU archtectures, implementation uses subclass that
+ * includes TypeProfile overhead but still faster than ByteBuffer. On JVMs older than Java 7 and JVMs without Unsafe
+ * API (such as Android), implementation falls back to a universal implementation that uses standard ByteBuffer class
+ * internally.
  */
 public class MessageBuffer
 {
@@ -69,8 +77,7 @@ public class MessageBuffer
                 try {
                     int major = Integer.parseInt(javaVersion.substring(0, dotPos));
                     int minor = Integer.parseInt(javaVersion.substring(dotPos + 1));
-                    isJavaAtLeast7 = major > 1 || (major == 1 && minor >= 7);
-                }
+                    isJavaAtLeast7 = major > 1 || (major == 1 && minor >= 7); }
                 catch (NumberFormatException e) {
                     e.printStackTrace(System.err);
                 }

msgpack-core/src/main/java/org/msgpack/core/buffer/MessageBufferInput.java

@@ -19,19 +19,38 @@
 import java.io.IOException;
 
 /**
- * Provides a sequence of MessageBuffers that contains message packed data.
+ * Provides a sequence of MessageBuffer instances.
+ *
+ * A MessageBufferInput implementation has control of lifecycle of the memory so that it can reuse previously
+ * allocated memory, use memory pools, or use memory-mapped files.
  */
 public interface MessageBufferInput
         extends Closeable
 {
     /**
-     * Get a next buffer to read.
+     * Returns a next buffer to read.
      * <p>
-     * When this method is called, the formally allocated buffer can be safely discarded.
+     * This method should return a MessageBuffer instance that has data filled in. When this method is called twice,
+     * the previously returned buffer is no longer used. Thus implementation of this method can safely discard it.
+     * This is useful when it uses a memory pool.
      *
      * @return the next MessageBuffer, or return null if no more buffer is available.
-     * @throws IOException when error occurred when reading the data
+     * @throws IOException when IO error occurred when reading the data
      */
     MessageBuffer next()
             throws IOException;
+
+    /**
+     * Closes the input.
+     * <p>
+     * When this method is called, the buffer previously returned from {@link next()} method is no longer used.
+     * Thus implementation of this method can safely discard it.
+     * <p>
+     * If the input is already closed then invoking this method has no effect.
+     *
+     * @throws IOException when IO error occurred when closing the data source
+     */
+    @Override
+    void close()
+            throws IOException;
 }

msgpack-core/src/main/java/org/msgpack/core/buffer/MessageBufferOutput.java

@@ -20,29 +20,40 @@
 import java.io.Flushable;
 
 /**
- * Provides a buffered output stream for packing objects
+ * Provides a buffered output stream that writes sequence of MessageBuffer instances.
+ *
+ * A MessageBufferOutput implementation has total control of the buffer memory so that it can reuse buffer memory,
+ * use buffer pools, or use memory-mapped files.
  */
 public interface MessageBufferOutput
         extends Closeable, Flushable
 {
     /**
-     * Allocates the next buffer for writing message packed data.
-     * If the previously allocated buffer is not flushed yet, this next method should discard
-     * it without writing it.
+     * Allocates the next buffer to write.
+     * <p>
+     * This method should return a MessageBuffer instance that has at least specified size of capacity.
+     * <p>
+     * When this method is called twice, the previously returned buffer is no longer used. This method may be called
+     * twice without call of {@link writeBuffer(MessageBuffer)} in between. In this case, the buffer should be
+     * discarded without flushing it to the output.
      *
      * @param minimumSize the mimium required buffer size to allocate
-     * @return
+     * @return the MessageBuffer instance with at least minimumSize bytes of capacity
      * @throws IOException
      */
     MessageBuffer next(int minimumSize)
             throws IOException;
 
     /**
-     * Flushes the previously allocated buffer.
-     * This method is not always called because next method also flushes previously allocated buffer.
-     * This method is called when write method is called or application wants to control the timing of flush.
+     * Writes the previously allocated buffer.
+     * <p>
+     * This method should write the buffer previously returned from {@link next(int)} method until specified number of
+     * bytes. Once the buffer is written, the buffer is no longer used.
+     * <p>
+     * This method is not always called for each {@link next(int)} call. In this case, the buffer should be discarded
+     * without flushing it to the output.
      *
-     * @param length the size of buffer to flush
+     * @param length the number of bytes to write
      * @throws IOException
      */
     void writeBuffer(int length)
@@ -63,7 +74,10 @@ void write(byte[] buffer, int offset, int length)
 
     /**
      * Writes an external payload data.
-     * This buffer is given - this MessageBufferOutput owns the buffer and may modify contents of the buffer. Contents of this buffer won't be modified by the caller.
+     * <p>
+     * Unlike {@link #write(byte[], int, int)} method, the buffer is given - this MessageBufferOutput implementation
+     * gets ownership of the buffer and may modify contents of the buffer. Contents of this buffer won't be modified
+     * by the caller.
      *
      * @param buffer the data to add
      * @param offset the start offset in the data

msgpack-core/src/main/java/org/msgpack/value/ArrayValue.java

@@ -19,7 +19,7 @@
 import java.util.List;
 
 /**
- * The interface {@code ArrayValue} represents MessagePack's Array type.
+ * Representation of MessagePack's Array type.
  *
  * MessagePack's Array type can represent sequence of values.
  */

msgpack-core/src/main/java/org/msgpack/value/BinaryValue.java

@@ -16,7 +16,7 @@
 package org.msgpack.value;
 
 /**
- * The interface {@code BinaryValue} represents MessagePack's Binary type.
+ * Representation of MessagePack's Binary type.
  *
  * MessagePack's Binary type can represent a byte array at most 2<sup>64</sup>-1 bytes.
  *