Use simple naming for classes

Author: xerial

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

@@ -14,7 +14,7 @@
 
 /**
  * MessageBuffer class is an abstraction of memory for reading/writing message packed data.
- * This MessageBuffers ensures integers (31-bit singed) are written in the big-endian order.
+ * This MessageBuffers ensures short/int/float/long/double values are written in the big-endian order.
  *
  * This class is optimized for fast memory access, so many methods are
  * implemented without using any interface method that produces invokeinterface call in JVM.
@@ -24,7 +24,7 @@
 public class MessageBuffer {
 
     static final Unsafe unsafe;
-    static final Constructor byteBufferCC;
+    static final Constructor byteBufferConstructor;
 
     static {
         try {
@@ -44,8 +44,8 @@ public class MessageBuffer {
 
             // Find the hidden constructor for DirectByteBuffer
             Class<?> directByteBufferClass = ClassLoader.getSystemClassLoader().loadClass("java.nio.DirectByteBuffer");
-            byteBufferCC = directByteBufferClass.getDeclaredConstructor(long.class, int.class, Object.class);
-            byteBufferCC.setAccessible(true);
+            byteBufferConstructor = directByteBufferClass.getDeclaredConstructor(long.class, int.class, Object.class);
+            byteBufferConstructor.setAccessible(true);
 
             // Check the endian of this CPU
             boolean isLittleEndian = true;
@@ -375,12 +375,18 @@ public void putByteBuffer(int index, ByteBuffer src, int len) {
     }
 
 
+    /**
+     * Create a ByteBuffer view of the range [index, index+length) of this memory
+     * @param index
+     * @param length
+     * @return
+     */
     public ByteBuffer toByteBuffer(int index, int length) {
         if(base instanceof byte[]) {
             return ByteBuffer.wrap((byte[]) base, (int) ((address-ARRAY_BYTE_BASE_OFFSET) + index), length);
         }
         try {
-            return (ByteBuffer) byteBufferCC.newInstance(address + index, length, reference);
+            return (ByteBuffer) byteBufferConstructor.newInstance(address + index, length, reference);
         } catch(Throwable e) {
             // Convert checked exception to unchecked exception
             throw new RuntimeException(e);
@@ -391,6 +397,13 @@ public void relocate(int offset, int length, int dst) {
         unsafe.copyMemory(base, address + offset, base, address+dst, length);
     }
 
+    /**
+     * Copy this buffer contents to another MessageBuffer
+     * @param index
+     * @param dst
+     * @param offset
+     * @param length
+     */
     public void copyTo(int index, MessageBuffer dst, int offset, int length) {
         unsafe.copyMemory(base, address + index, dst.base, dst.address + offset, length);
     }

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

@@ -3,7 +3,8 @@
 import java.nio.ByteBuffer;
 
 /**
- * MessageBuffer class tailored to the big-endian machine. Message pack specification demands writing short/int/float/long/double values in big-endian format.
+ * MessageBufferBE is a {@link MessageBuffer} implementation tailored to big-endian machines.
+ * The specification of Message Pack demands writing short/int/float/long/double values in the big-endian format.
  * In the big-endian machine, we do not need to swap the byte order.
  */
 public class MessageBufferBE extends MessageBuffer {

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

@@ -16,9 +16,9 @@
 package org.msgpack.core;
 
 /**
- * When the message pack format is invalid
+ * Thrown when the input message pack format is invalid
  */
-public class MessageFormatException extends MessageException {
+public class MessageFormatException extends MessagePackException {
     public MessageFormatException(String message) {
         super(message);
     }

msgpack-core/src/main/java/org/msgpack/core/IntegerOverflowException.java renamed to msgpack-core/src/main/java/org/msgpack/core/MessageIntegerOverflowException.java

@@ -17,15 +17,21 @@
 
 import java.math.BigInteger;
 
-public class IntegerOverflowException extends MessageTypeException {
+
+/**
+ * This error is thrown when the user tries to read an integer value
+ * using a smaller types. For example, calling MessageUnpacker.unpackInt() for an integer value
+ * that is larger than Integer.MAX_VALUE will cause this exception.
+ */
+public class MessageIntegerOverflowException extends MessageTypeException {
     private final BigInteger bigInteger;
 
-    public IntegerOverflowException(BigInteger bigInteger) {
+    public MessageIntegerOverflowException(BigInteger bigInteger) {
         super();
         this.bigInteger = bigInteger;
     }
 
-    public IntegerOverflowException(String message, BigInteger bigInteger) {
+    public MessageIntegerOverflowException(String message, BigInteger bigInteger) {
         super(message);
         this.bigInteger = bigInteger;
     }

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

@@ -9,16 +9,17 @@
 import java.nio.file.Path;
 
 /**
- * Entry point for creating MessagePacker and MessageUnpacker
+ * Entry point for creating MessagePacker (newPacker) and MessageUnpacker (newUnpacker).
+ *
  */
 public class MessagePack {
 
     public static Charset UTF8 = Charset.forName("UTF-8");
 
     /**
-     * The code set of MessagePack. See also https://github.com/msgpack/msgpack/blob/master/spec.md for details.
+     * The prefix code set of MessagePack. See also https://github.com/msgpack/msgpack/blob/master/spec.md for details.
      */
-    public static class Code {
+    public static final class Code {
 
         public static final boolean isFixInt(byte b) {
             return isPosFixInt(b) || isNegFixInt(b);
@@ -92,6 +93,9 @@ public static final boolean isFixedRaw(byte b) {
     }
 
 
+    /**
+     * Header of extended type
+     */
     public static class ExtendedTypeHeader {
         private final int type;
         private final int length;
@@ -132,6 +136,11 @@ public static MessagePacker newPacker(WritableByteChannel out) {
         return new MessagePacker(new MessageBufferOutputChannel(out));
     }
 
+    /**
+     * Create a new MessageUnpacker that reads the data from a given array
+     * @param arr
+     * @return
+     */
     public static MessageUnpacker newUnpacker(byte[] arr) {
         return new MessageUnpacker(new ArrayMessageBufferInput(arr));
     }
@@ -149,6 +158,7 @@ public static MessageUnpacker newUnpacker(File inputFile) throws IOException {
 
     public static MessageUnpacker newUnpacker(InputStream in) {
         if(in instanceof FileInputStream) {
+            // When the input is FileInputStream, we can use file channel that can directly read the data from a file to an off-heap buffer
             return newUnpacker(((FileInputStream) in).getChannel());
         }
         else {

msgpack-core/src/main/java/org/msgpack/core/MessageException.java renamed to msgpack-core/src/main/java/org/msgpack/core/MessagePackException.java

@@ -17,22 +17,22 @@
 
 
 /**
- * A base class of the exceptions used in msgpack
+ * A base class of all of the message pack exceptions.
  */
-public class MessageException extends RuntimeException {
-    public MessageException() {
+public class MessagePackException extends RuntimeException {
+    public MessagePackException() {
         super();
     }
 
-    public MessageException(String message) {
+    public MessagePackException(String message) {
         super(message);
     }
 
-    public MessageException(String message, Throwable cause) {
+    public MessagePackException(String message, Throwable cause) {
         super(message, cause);
     }
 
-    public MessageException(Throwable cause) {
+    public MessagePackException(Throwable cause) {
         super(cause);
     }
 }

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

@@ -21,6 +21,21 @@
 import static org.msgpack.core.MessagePack.Code.*;
 
 /**
+ * Writer of message packed data.
+ *
+ * <p>
+ * MessagePacker provides packXXX methods for writing values in the message pack format.
+ * To write raw string or binary data, first use packRawStringHeader or packBinaryHeader to specify the data length,
+ * then call writePayload(...) method.
+ * </p>
+ *
+ * <p>
+ * MessagePacker class has no guarantee to produce the correct message-pack format data if it is not used correctly:
+ * packXXX methods of primitive values always produce the correct format, but
+ * packXXXHeader (e.g. array, map, ext) must be followed by correct number of array/map/ext type values.
+ * packRawStringHeader(length) and packBinaryHeader(length) must be followed by writePayload( ... length) to supply
+ * the binary data of the specified length in the header.
+ * </p>
  *
  */
 public class MessagePacker {

msgpack-core/src/main/java/org/msgpack/core/MessageSizeLimitException.java renamed to msgpack-core/src/main/java/org/msgpack/core/MessageSizeException.java

@@ -15,15 +15,18 @@
 //
 package org.msgpack.core;
 
-public class MessageSizeLimitException extends MessageException {
+/**
+ * Thrown to indicate too large message size (e.g, larger than 2^31-1).
+ */
+public class MessageSizeException extends MessagePackException {
     private final long size;
 
-    public MessageSizeLimitException(long size) {
+    public MessageSizeException(long size) {
         super();
         this.size = size;
     }
 
-    public MessageSizeLimitException(String message, long size) {
+    public MessageSizeException(String message, long size) {
         super(message);
         this.size = size;
     }

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

@@ -18,9 +18,9 @@
 import java.nio.charset.CharacterCodingException;
 
 /**
- *
+ * Thrown to indicate an error when encoding/decoding a String value
  */
-public class MessageStringCodingException extends MessageException {
+public class MessageStringCodingException extends MessagePackException {
     public MessageStringCodingException(String message, CharacterCodingException cause) {
         super(message, cause);
     }