toBufferList()
{
try {
flush();
}
catch (IOException ex) {
- // IOException must not happen because underlaying ArrayBufferOutput never throws IOException
+ // IOException must not happen because underlying ArrayBufferOutput never throws IOException
throw new RuntimeException(ex);
}
return getArrayBufferOut().toBufferList();
diff --git a/msgpack-core/src/main/java/org/msgpack/core/MessageInsufficientBufferException.java b/msgpack-core/src/main/java/org/msgpack/core/MessageInsufficientBufferException.java
index 838dc77ab..099dcac6f 100644
--- a/msgpack-core/src/main/java/org/msgpack/core/MessageInsufficientBufferException.java
+++ b/msgpack-core/src/main/java/org/msgpack/core/MessageInsufficientBufferException.java
@@ -15,6 +15,9 @@
//
package org.msgpack.core;
+/**
+ * Exception that indicates end of input.
+ */
public class MessageInsufficientBufferException
extends MessagePackException
{
diff --git a/msgpack-core/src/main/java/org/msgpack/core/MessagePack.java b/msgpack-core/src/main/java/org/msgpack/core/MessagePack.java
index 7737aa664..ed8b1e405 100644
--- a/msgpack-core/src/main/java/org/msgpack/core/MessagePack.java
+++ b/msgpack-core/src/main/java/org/msgpack/core/MessagePack.java
@@ -33,20 +33,54 @@
import java.nio.charset.CodingErrorAction;
/**
- * This class has MessagePack prefix code definitions and packer/unpacker factory methods.
+ * Convenience class to build packer and unpacker classes.
+ *
+ * You can select an appropriate factory method as following.
+ *
+ *
+ * Deserializing objects from binary:
+ *
+ *
+ * | Input type | Factory method | Return type |
|---|
+ * | byte[] | {@link #newDefaultUnpacker(byte[], int, int)} | {@link MessageUnpacker} |
+ * | ByteBuffer | {@link #newDefaultUnpacker(ByteBuffer)} | {@link MessageUnpacker} |
+ * | InputStream | {@link #newDefaultUnpacker(InputStream)} | {@link MessageUnpacker} |
+ * | ReadableByteChannel | {@link #newDefaultUnpacker(ReadableByteChannel)} | {@link MessageUnpacker} |
+ * | {@link org.msgpack.core.buffer.MessageBufferInput} | {@link #newDefaultUnpacker(MessageBufferInput)} | {@link MessageUnpacker} |
+ *
+ *
+ *
+ * Serializing objects into binary:
+ *
+ *
+ * | Output type | Factory method | Return type |
|---|
+ * | byte[] | {@link #newDefaultBufferPacker()} | {@link MessageBufferPacker} |
+ *
| OutputStream | {@link #newDefaultPacker(OutputStream)} | {@link MessagePacker} |
+ * | WritableByteChannel | {@link #newDefaultPacker(WritableByteChannel)} | {@link MessagePacker} |
+ * | {@link org.msgpack.core.buffer.MessageBufferOutput} | {@link #newDefaultPacker(MessageBufferOutput)} | {@link MessagePacker} |
+ *
+ *
*/
public class MessagePack
{
+ /**
+ * @exclude
+ * Applications should use java.nio.charset.StandardCharsets.UTF_8 instead since Java 7.
+ */
public static final Charset UTF8 = Charset.forName("UTF-8");
/**
- * Default packer/unpacker configurations
+ * 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} used by {@link #newDefaultUnpacker(MessageBufferInput)} methods.
+ */
public static final UnpackerConfig DEFAULT_UNPACKER_CONFIG = new UnpackerConfig();
/**
- * The prefix code set of MessagePack. See also https://github.com/msgpack/msgpack/blob/master/spec.md for details.
+ * The prefix code set of MessagePack format. See also https://github.com/msgpack/msgpack/blob/master/spec.md for details.
*/
public static final class Code
{
@@ -139,10 +173,16 @@ private MessagePack()
}
/**
- * Create a packer that outputs the packed data to the specified output
+ * Creates a packer that serializes objects into the specified output.
+ *
+ * {@link org.msgpack.core.buffer.MessageBufferOutput} is an interface that lets applications customize memory
+ * allocation of internal buffer of {@link MessagePacker}. You may prefer {@link #newDefaultBufferPacker()},
+ * {@link #newDefaultPacker(OutputStream)}, or {@link #newDefaultPacker(WritableByteChannel)} methods instead.
+ *
+ * This method is equivalent to DEFAULT_PACKER_CONFIG.newPacker(out).
*
- * @param out
- * @return
+ * @param out A MessageBufferOutput that allocates buffer chunks and receives the buffer chunks with packed data filled in them
+ * @return A new MessagePacker instance
*/
public static MessagePacker newDefaultPacker(MessageBufferOutput out)
{
@@ -150,10 +190,15 @@ public static MessagePacker newDefaultPacker(MessageBufferOutput out)
}
/**
- * Create a packer that outputs the packed data to a target output stream
+ * Creates a packer that serializes objects into the specified output stream.
+ *
+ * Note that you don't have to wrap OutputStream in BufferedOutputStream because MessagePacker has buffering
+ * internally.
+ *
+ * This method is equivalent to DEFAULT_PACKER_CONFIG.newPacker(out).
*
- * @param out
- * @return
+ * @param out The output stream that receives sequence of bytes
+ * @return A new MessagePacker instance
*/
public static MessagePacker newDefaultPacker(OutputStream out)
{
@@ -161,10 +206,12 @@ public static MessagePacker newDefaultPacker(OutputStream out)
}
/**
- * Create a packer that outputs the packed data to a channel
+ * Creates a packer that serializes objects into the specified writable channel.
+ *
+ * This method is equivalent to DEFAULT_PACKER_CONFIG.newPacker(channel).
*
- * @param channel
- * @return
+ * @param channel The output channel that receives sequence of bytes
+ * @return A new MessagePacker instance
*/
public static MessagePacker newDefaultPacker(WritableByteChannel channel)
{
@@ -172,9 +219,13 @@ public static MessagePacker newDefaultPacker(WritableByteChannel channel)
}
/**
- * Create a packer for storing packed data into a byte array
+ * Creates a packer that serializes objects into byte arrays.
+ *
+ * This method provides an optimized implementation of newDefaultBufferPacker(new ByteArrayOutputStream()).
+ *
+ * This method is equivalent to DEFAULT_PACKER_CONFIG.newBufferPacker().
*
- * @return
+ * @return A new MessageBufferPacker instance
*/
public static MessageBufferPacker newDefaultBufferPacker()
{
@@ -182,10 +233,17 @@ public static MessageBufferPacker newDefaultBufferPacker()
}
/**
- * Create an unpacker that reads the data from a given input
+ * Creates an unpacker that deserializes objects from a specified input.
+ *
+ * {@link org.msgpack.core.buffer.MessageBufferInput} is an interface that lets applications customize memory
+ * allocation of internal buffer of {@link MessageUnpacker}. You may prefer
+ * {@link #newDefaultUnpacker(InputStream)}, {@link #newDefaultUnpacker(ReadableByteChannel)},
+ * {@link #newDefaultUnpacker(byte[], int, int)}, or {@link #newDefaultUnpacker(ByteBuffer)} methods instead.
+ *
+ * This method is equivalent to DEFAULT_UNPACKER_CONFIG.newDefaultUnpacker(in).
*
- * @param in
- * @return
+ * @param in The input stream that provides sequence of buffer chunks and optionally reuses them when MessageUnpacker consumed one completely
+ * @return A new MessageUnpacker instance
*/
public static MessageUnpacker newDefaultUnpacker(MessageBufferInput in)
{
@@ -193,10 +251,15 @@ public static MessageUnpacker newDefaultUnpacker(MessageBufferInput in)
}
/**
- * Create an unpacker that reads the data from a given input stream
+ * Creates an unpacker that deserializes objects from a specified input stream.
+ *
+ * Note that you don't have to wrap InputStream in BufferedInputStream because MessageUnpacker has buffering
+ * internally.
+ *
+ * This method is equivalent to DEFAULT_UNPACKER_CONFIG.newDefaultUnpacker(in).
*
- * @param in
- * @return
+ * @param in The input stream that provides sequence of bytes
+ * @return A new MessageUnpacker instance
*/
public static MessageUnpacker newDefaultUnpacker(InputStream in)
{
@@ -204,10 +267,12 @@ public static MessageUnpacker newDefaultUnpacker(InputStream in)
}
/**
- * Create an unpacker that reads the data from a given channel
+ * Creates an unpacker that deserializes objects from a specified readable channel.
+ *
+ * This method is equivalent to DEFAULT_UNPACKER_CONFIG.newDefaultUnpacker(in).
*
- * @param channel
- * @return
+ * @param channel The input channel that provides sequence of bytes
+ * @return A new MessageUnpacker instance
*/
public static MessageUnpacker newDefaultUnpacker(ReadableByteChannel channel)
{
@@ -215,10 +280,14 @@ public static MessageUnpacker newDefaultUnpacker(ReadableByteChannel channel)
}
/**
- * Create an unpacker that reads the data from a given byte array
+ * Creates an unpacker that deserializes objects from a specified byte array.
+ *
+ * This method provides an optimized implementation of newDefaultUnpacker(new ByteArrayInputStream(contents)).
+ *
+ * This method is equivalent to DEFAULT_UNPACKER_CONFIG.newDefaultUnpacker(contents).
*
- * @param contents
- * @return
+ * @param contents The byte array that contains packed objects in MessagePack format
+ * @return A new MessageUnpacker instance that will never throw IOException
*/
public static MessageUnpacker newDefaultUnpacker(byte[] contents)
{
@@ -226,12 +295,16 @@ public static MessageUnpacker newDefaultUnpacker(byte[] contents)
}
/**
- * Create an unpacker that reads the data from a given byte array [offset, offset+length)
+ * Creates an unpacker that deserializes objects from subarray of a specified byte array.
+ *
+ * This method provides an optimized implementation of newDefaultUnpacker(new ByteArrayInputStream(contents, offset, length)).
+ *
+ * This method is equivalent to DEFAULT_UNPACKER_CONFIG.newDefaultUnpacker(contents).
*
- * @param contents
- * @param offset
- * @param length
- * @return
+ * @param contents The byte array that contains packed objects
+ * @param offset The index of the first byte
+ * @param length The number of bytes
+ * @return A new MessageUnpacker instance that will never throw IOException
*/
public static MessageUnpacker newDefaultUnpacker(byte[] contents, int offset, int length)
{
@@ -239,10 +312,16 @@ public static MessageUnpacker newDefaultUnpacker(byte[] contents, int offset, in
}
/**
- * Create an unpacker that reads the data from a given ByteBuffer
+ * Creates an unpacker that deserializes objects from a specified ByteBuffer.
+ *
+ * Note that the returned unpacker reads data from the current position of the ByteBuffer until its limit.
+ * However, its position does not change when unpacker reads data. You may use
+ * {@link MessageUnpacker#getTotalReadBytes()} to get actual amount of bytes used in ByteBuffer.
+ *
+ * This method supports both non-direct buffer and direct buffer.
*
- * @param contents
- * @return
+ * @param contents The byte buffer that contains packed objects
+ * @return A new MessageUnpacker instance that will never throw IOException
*/
public static MessageUnpacker newDefaultUnpacker(ByteBuffer contents)
{
@@ -305,10 +384,13 @@ public boolean equals(Object obj)
}
/**
- * Create a packer that outputs the packed data to a given output
+ * Creates a packer that serializes objects into the specified output.
+ *
+ * {@link org.msgpack.core.buffer.MessageBufferOutput} is an interface that lets applications customize memory
+ * allocation of internal buffer of {@link MessagePacker}.
*
- * @param out
- * @return
+ * @param out A MessageBufferOutput that allocates buffer chunks and receives the buffer chunks with packed data filled in them
+ * @return A new MessagePacker instance
*/
public MessagePacker newPacker(MessageBufferOutput out)
{
@@ -316,10 +398,13 @@ public MessagePacker newPacker(MessageBufferOutput out)
}
/**
- * Create a packer that outputs the packed data to a given output stream
+ * Creates a packer that serializes objects into the specified output stream.
+ *
+ * Note that you don't have to wrap OutputStream in BufferedOutputStream because MessagePacker has buffering
+ * internally.
*
- * @param out
- * @return
+ * @param out The output stream that receives sequence of bytes
+ * @return A new MessagePacker instance
*/
public MessagePacker newPacker(OutputStream out)
{
@@ -327,10 +412,10 @@ public MessagePacker newPacker(OutputStream out)
}
/**
- * Create a packer that outputs the packed data to a given output channel
+ * Creates a packer that serializes objects into the specified writable channel.
*
- * @param channel
- * @return
+ * @param channel The output channel that receives sequence of bytes
+ * @return A new MessagePacker instance
*/
public MessagePacker newPacker(WritableByteChannel channel)
{
@@ -338,9 +423,11 @@ public MessagePacker newPacker(WritableByteChannel channel)
}
/**
- * Create a packer for storing packed data into a byte array
+ * Creates a packer that serializes objects into byte arrays.
+ *
+ * This method provides an optimized implementation of newDefaultBufferPacker(new ByteArrayOutputStream()).
*
- * @return
+ * @return A new MessageBufferPacker instance
*/
public MessageBufferPacker newBufferPacker()
{
@@ -348,13 +435,13 @@ public MessageBufferPacker newBufferPacker()
}
/**
- * Use String.getBytes() for converting Java Strings that are smaller than this threshold into UTF8.
+ * Use String.getBytes() for converting Java Strings that are shorter than this threshold.
* Note that this parameter is subject to change.
*/
- public PackerConfig withSmallStringOptimizationThreshold(int bytes)
+ public PackerConfig withSmallStringOptimizationThreshold(int length)
{
PackerConfig copy = clone();
- copy.smallStringOptimizationThreshold = bytes;
+ copy.smallStringOptimizationThreshold = length;
return copy;
}
@@ -364,8 +451,8 @@ public int getSmallStringOptimizationThreshold()
}
/**
- * When the next payload size exceeds this threshold, MessagePacker will call MessageBufferOutput.flush() before
- * packing the data (default: 8192).
+ * When the next payload size exceeds this threshold, MessagePacker will call
+ * {@link org.msgpack.core.buffer.MessageBufferOutput#flush()} before writing more data (default: 8192).
*/
public PackerConfig withBufferFlushThreshold(int bytes)
{
@@ -380,7 +467,7 @@ public int getBufferFlushThreshold()
}
/**
- * When a packer is created with newPacker(OutputStream) or newPacker(WritableByteChannel), the stream will be
+ * When a packer is created with {@link #newPacker(OutputStream)} or {@link #newPacker(WritableByteChannel)}, the stream will be
* buffered with this size of buffer (default: 8192).
*/
public PackerConfig withBufferSize(int bytes)
@@ -483,10 +570,13 @@ public boolean equals(Object obj)
}
/**
- * Create an unpacker that reads the data from a given input
+ * Creates an unpacker that deserializes objects from a specified input.
+ *
+ * {@link org.msgpack.core.buffer.MessageBufferInput} is an interface that lets applications customize memory
+ * allocation of internal buffer of {@link MessageUnpacker}.
*
- * @param in
- * @return
+ * @param in The input stream that provides sequence of buffer chunks and optionally reuses them when MessageUnpacker consumed one completely
+ * @return A new MessageUnpacker instance
*/
public MessageUnpacker newUnpacker(MessageBufferInput in)
{
@@ -494,10 +584,13 @@ public MessageUnpacker newUnpacker(MessageBufferInput in)
}
/**
- * Create an unpacker that reads the data from a given input stream
+ * Creates an unpacker that deserializes objects from a specified input stream.
+ *
+ * Note that you don't have to wrap InputStream in BufferedInputStream because MessageUnpacker has buffering
+ * internally.
*
- * @param in
- * @return
+ * @param in The input stream that provides sequence of bytes
+ * @return A new MessageUnpacker instance
*/
public MessageUnpacker newUnpacker(InputStream in)
{
@@ -505,10 +598,10 @@ public MessageUnpacker newUnpacker(InputStream in)
}
/**
- * Create an unpacker that reads the data from a given channel
+ * Creates an unpacker that deserializes objects from a specified readable channel.
*
- * @param channel
- * @return
+ * @param channel The input channel that provides sequence of bytes
+ * @return A new MessageUnpacker instance
*/
public MessageUnpacker newUnpacker(ReadableByteChannel channel)
{
@@ -516,10 +609,12 @@ public MessageUnpacker newUnpacker(ReadableByteChannel channel)
}
/**
- * Create an unpacker that reads the data from a given byte array
+ * Creates an unpacker that deserializes objects from a specified byte array.
+ *
+ * This method provides an optimized implementation of newDefaultUnpacker(new ByteArrayInputStream(contents)).
*
- * @param contents
- * @return
+ * @param contents The byte array that contains packed objects in MessagePack format
+ * @return A new MessageUnpacker instance that will never throw IOException
*/
public MessageUnpacker newUnpacker(byte[] contents)
{
@@ -527,10 +622,14 @@ public MessageUnpacker newUnpacker(byte[] contents)
}
/**
- * Create an unpacker that reads the data from a given byte array [offset, offset+size)
+ * Creates an unpacker that deserializes objects from subarray of a specified byte array.
+ *
+ * This method provides an optimized implementation of newDefaultUnpacker(new ByteArrayInputStream(contents, offset, length)).
*
- * @param contents
- * @return
+ * @param contents The byte array that contains packed objects
+ * @param offset The index of the first byte
+ * @param length The number of bytes
+ * @return A new MessageUnpacker instance that will never throw IOException
*/
public MessageUnpacker newUnpacker(byte[] contents, int offset, int length)
{
@@ -538,10 +637,14 @@ public MessageUnpacker newUnpacker(byte[] contents, int offset, int length)
}
/**
- * Create an unpacker that reads the data from a given ByteBuffer
+ * Creates an unpacker that deserializes objects from a specified ByteBuffer.
+ *
+ * Note that the returned unpacker reads data from the current position of the ByteBuffer until its limit.
+ * However, its position does not change when unpacker reads data. You may use
+ * {@link MessageUnpacker#getTotalReadBytes()} to get actual amount of bytes used in ByteBuffer.
*
- * @param contents
- * @return
+ * @param contents The byte buffer that contains packed objects
+ * @return A new MessageUnpacker instance that will never throw IOException
*/
public MessageUnpacker newUnpacker(ByteBuffer contents)
{
@@ -549,7 +652,7 @@ public MessageUnpacker newUnpacker(ByteBuffer contents)
}
/**
- * Allow unpackBinaryHeader to read str format family (default: true)
+ * Allows unpackBinaryHeader to read str format family (default: true)
*/
public UnpackerConfig withAllowReadingStringAsBinary(boolean enable)
{
@@ -564,7 +667,7 @@ public boolean getAllowReadingStringAsBinary()
}
/**
- * Allow unpackString and unpackRawStringHeader and unpackString to read bin format family (default: true)
+ * Allows unpackString and unpackRawStringHeader and unpackString to read bin format family (default: true)
*/
public UnpackerConfig withAllowReadingBinaryAsString(boolean enable)
{
@@ -579,7 +682,7 @@ public boolean getAllowReadingBinaryAsString()
}
/**
- * Action when encountered a malformed input (default: REPLACE)
+ * Sets action when encountered a malformed input (default: REPLACE)
*/
public UnpackerConfig withActionOnMalformedString(CodingErrorAction action)
{
@@ -594,7 +697,7 @@ public CodingErrorAction getActionOnMalformedString()
}
/**
- * Action when an unmappable character is found (default: REPLACE)
+ * Sets action when an unmappable character is found (default: REPLACE)
*/
public UnpackerConfig withActionOnUnmappableString(CodingErrorAction action)
{
diff --git a/msgpack-core/src/main/java/org/msgpack/core/MessagePacker.java b/msgpack-core/src/main/java/org/msgpack/core/MessagePacker.java
index 5559fd4ad..1cd9a9801 100644
--- a/msgpack-core/src/main/java/org/msgpack/core/MessagePacker.java
+++ b/msgpack-core/src/main/java/org/msgpack/core/MessagePacker.java
@@ -67,21 +67,65 @@
import static org.msgpack.core.Preconditions.checkNotNull;
/**
- * Writer of message packed data.
- *
+ * MessagePack serializer that converts objects into binary.
+ * You can use factory methods of {@link MessagePack} class or {@link MessagePack.PackerConfig} class to create
+ * an instance.
*
- * 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.
- *
- *
+ * 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 are also some utility methods for convenience.
*
- * 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.
- *
+ * Primitive methods:
+ *
+ *
+ * | Java type | Packer method | MessagePack type |
|---|
+ * | null | {@link #packNil()} | Nil |
+ * | boolean | {@link #packBoolean(boolean)} | Boolean |
+ * | byte | {@link #packByte(byte)} | Integer |
+ * | short | {@link #packShort(short)} | Integer |
+ * | int | {@link #packInt(int)} | Integer |
+ * | long | {@link #packLong(long)} | Integer |
+ * | BigInteger | {@link #packBigInteger(BigInteger)} | Integer |
+ * | float | {@link #packFloat(float)} | Float |
+ * | double | {@link #packDouble(double)} | Float |
+ * | byte[] | {@link #packBinaryHeader(int)} | Binary |
+ * | String | {@link #packRawStringHeader(int)} | String |
+ * | List | {@link #packArrayHeader(int)} | Array |
+ * | Map | {@link #packMapHeader(int)} | Map |
+ * | custom user type | {@link #packExtensionTypeHeader(byte, int)} | Extension |
+ *
+ *
+ *
+ * Utility methods:
+ *
+ *
+ * | Java type | Packer method | MessagePack type |
|---|
+ * | String | {@link #packString(String)} | String |
+ * | {@link Value} | {@link #packValue(Value)} | |
+ *
+ *
+ *
+ * To write a byte array, first you call {@link #packBinaryHeader} method with length of the byte array. Then,
+ * you call {@link #writePayload(byte[], int, int)} or {@link #addPayload(byte[], int, int)} method to write the
+ * contents.
+ *
+ *
+ * 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.
+ * iteration.
+ *
+ *
+ * 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.
+ *
+ *
+ * Note that packXxxHeader methods don't validate number of elements. You must call packer methods for correct
+ * number of times to produce valid MessagePack data.
+ *
+ *
+ * When IOException is thrown, primitive methods guarantee that all data is written to the internal buffer or no data
+ * is written. This is convenient behavior when you use a non-blocking output channel that may not be writable
+ * immediately.
*/
public class MessagePacker
implements Closeable, Flushable
@@ -92,6 +136,9 @@ public class MessagePacker
private final boolean str8FormatSupport;
+ /**
+ * Current internal buffer.
+ */
protected MessageBufferOutput out;
private MessageBuffer buffer;
@@ -126,10 +173,18 @@ protected MessagePacker(MessageBufferOutput out, MessagePack.PackerConfig config
}
/**
- * Reset output. This method doesn't close the old resource.
+ * Replaces underlying output.
+ *
+ * This method flushes current internal buffer to the output, swaps it with the new given output, then returns
+ * the old output.
+ *
+ *
+ * This method doesn't close the old output.
*
* @param out new output
- * @return the old resource
+ * @return the old output
+ * @throws IOException when underlying output throws IOException
+ * @throws NullPointerException the given output is null
*/
public MessageBufferOutput reset(MessageBufferOutput out)
throws IOException
@@ -148,11 +203,26 @@ public MessageBufferOutput reset(MessageBufferOutput out)
return old;
}
+ /**
+ * Returns total number of written bytes.
+ *
+ * This method returns total of amount of data flushed to the underlying output plus size of current
+ * internal buffer.
+ *
+ *
+ * Calling {@link #reset(MessageBufferOutput)} resets this number to 0.
+ */
public long getTotalWrittenBytes()
{
return totalFlushBytes + position;
}
+ /**
+ * Flushes internal buffer to the underlying output.
+ *
+ * This method also calls flush method of the underlying output after writing internal buffer.
+ */
+ @Override
public void flush()
throws IOException
{
@@ -162,6 +232,12 @@ public void flush()
out.flush();
}
+ /**
+ * Closes underlying output.
+ *
+ * This method flushes internal buffer before closing.
+ */
+ @Override
public void close()
throws IOException
{
@@ -278,6 +354,14 @@ private void writeLong(long v)
position += 8;
}
+ /**
+ * Writes a Nil value.
+ *
+ * This method writes a nil byte.
+ *
+ * @return this
+ * @throws IOException when underlying output throws IOException
+ */
public MessagePacker packNil()
throws IOException
{
@@ -285,6 +369,14 @@ public MessagePacker packNil()
return this;
}
+ /**
+ * Writes a Boolean value.
+ *
+ * This method writes a true byte or a false byte.
+ *
+ * @return this
+ * @throws IOException when underlying output throws IOException
+ */
public MessagePacker packBoolean(boolean b)
throws IOException
{
@@ -292,6 +384,16 @@ public MessagePacker packBoolean(boolean b)
return this;
}
+ /**
+ * Writes an Integer value.
+ *
+ *
+ * This method writes an integer using the smallest format from the int format family.
+ *
+ * @param b the integer to be written
+ * @return this
+ * @throws IOException when underlying output throws IOException
+ */
public MessagePacker packByte(byte b)
throws IOException
{
@@ -304,6 +406,16 @@ public MessagePacker packByte(byte b)
return this;
}
+ /**
+ * Writes an Integer value.
+ *
+ *
+ * This method writes an integer using the smallest format from the int format family.
+ *
+ * @param v the integer to be written
+ * @return this
+ * @throws IOException when underlying output throws IOException
+ */
public MessagePacker packShort(short v)
throws IOException
{
@@ -329,6 +441,16 @@ else if (v < (1 << 7)) {
return this;
}
+ /**
+ * Writes an Integer value.
+ *
+ *
+ * This method writes an integer using the smallest format from the int format family.
+ *
+ * @param r the integer to be written
+ * @return this
+ * @throws IOException when underlying output throws IOException
+ */
public MessagePacker packInt(int r)
throws IOException
{
@@ -361,6 +483,16 @@ else if (r < (1 << 16)) {
return this;
}
+ /**
+ * Writes an Integer value.
+ *
+ *
+ * This method writes an integer using the smallest format from the int format family.
+ *
+ * @param v the integer to be written
+ * @return this
+ * @throws IOException when underlying output throws IOException
+ */
public MessagePacker packLong(long v)
throws IOException
{
@@ -407,6 +539,16 @@ else if (v < (1 << 7)) {
return this;
}
+ /**
+ * Writes an Integer value.
+ *
+ *
+ * This method writes an integer using the smallest format from the int format family.
+ *
+ * @param bi the integer to be written
+ * @return this
+ * @throws IOException when underlying output throws IOException
+ */
public MessagePacker packBigInteger(BigInteger bi)
throws IOException
{
@@ -422,6 +564,16 @@ else if (bi.bitLength() == 64 && bi.signum() == 1) {
return this;
}
+ /**
+ * Writes a Float value.
+ *
+ *
+ * This method writes a float value using float format family.
+ *
+ * @param v the value to be written
+ * @return this
+ * @throws IOException when underlying output throws IOException
+ */
public MessagePacker packFloat(float v)
throws IOException
{
@@ -429,6 +581,16 @@ public MessagePacker packFloat(float v)
return this;
}
+ /**
+ * Writes a Float value.
+ *
+ *
+ * This method writes a float value using float format family.
+ *
+ * @param v the value to be written
+ * @return this
+ * @throws IOException when underlying output throws IOException
+ */
public MessagePacker packDouble(double v)
throws IOException
{
@@ -497,11 +659,14 @@ private int encodeStringToBufferAt(int pos, String s)
private static final int UTF_8_MAX_CHAR_SIZE = 6;
/**
- * Pack the input String in UTF-8 encoding
+ * Writes a String vlaue in UTF-8 encoding.
*
- * @param s
- * @return
- * @throws IOException
+ *
+ * This method writes a UTF-8 string using the smallest format from the str format family by default. If {@link MessagePack.PackerConfig#withStr8FormatSupport(boolean)} is set to false, smallest format from the str format family excepting str8 format.
+ *
+ * @param s the string to be written
+ * @return this
+ * @throws IOException when underlying output throws IOException
*/
public MessagePacker packString(String s)
throws IOException
@@ -581,6 +746,17 @@ else if (s.length() < (1 << 16)) {
return this;
}
+ /**
+ * Writes header of an Array value.
+ *
+ * You will call other packer methods for each element after this method call.
+ *
+ * You don't have to call anything at the end of iteration.
+ *
+ * @param arraySize number of elements to be written
+ * @return this
+ * @throws IOException when underlying output throws IOException
+ */
public MessagePacker packArrayHeader(int arraySize)
throws IOException
{
@@ -600,6 +776,18 @@ else if (arraySize < (1 << 16)) {
return this;
}
+ /**
+ * Writes header of a Map value.
+ *
+ * After this method call, for each key-value pair, you will 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.
+ *
+ * @param mapSize number of pairs to be written
+ * @return this
+ * @throws IOException when underlying output throws IOException
+ */
public MessagePacker packMapHeader(int mapSize)
throws IOException
{
@@ -619,6 +807,13 @@ else if (mapSize < (1 << 16)) {
return this;
}
+ /**
+ * Writes a dynamically typed value.
+ *
+ * @param v the value to be written
+ * @return this
+ * @throws IOException when underlying output throws IOException
+ */
public MessagePacker packValue(Value v)
throws IOException
{
@@ -626,6 +821,16 @@ public MessagePacker packValue(Value v)
return this;
}
+ /**
+ * Writes header of an Extension value.
+ *
+ * You MUST call {@link #writePayload(byte[])} or {@link #addPayload(byte[])} method to write body binary.
+ *
+ * @param extType the extension type tag to be written
+ * @param payloadLen number of bytes of a payload binary to be written
+ * @return this
+ * @throws IOException when underlying output throws IOException
+ */
public MessagePacker packExtensionTypeHeader(byte extType, int payloadLen)
throws IOException
{
@@ -669,6 +874,15 @@ else if (payloadLen < (1 << 16)) {
return this;
}
+ /**
+ * Writes header of a Binary value.
+ *
+ * You MUST call {@link #writePayload(byte[])} or {@link #addPayload(byte[])} method to write body binary.
+ *
+ * @param len number of bytes of a binary to be written
+ * @return this
+ * @throws IOException when underlying output throws IOException
+ */
public MessagePacker packBinaryHeader(int len)
throws IOException
{
@@ -684,6 +898,18 @@ else if (len < (1 << 16)) {
return this;
}
+ /**
+ * Writes header of a String value.
+ *
+ * Length must be number of bytes of a string in UTF-8 encoding.
+ *
+ * You MUST call {@link #writePayload(byte[])} or {@link #addPayload(byte[])} method to write body of the
+ * UTF-8 encoded string.
+ *
+ * @param len number of bytes of a UTF-8 string to be written
+ * @return this
+ * @throws IOException when underlying output throws IOException
+ */
public MessagePacker packRawStringHeader(int len)
throws IOException
{
@@ -703,12 +929,13 @@ else if (len < (1 << 16)) {
}
/**
- * Writes buffer to the output.
- * This method is used with packRawStringHeader or packBinaryHeader.
+ * Writes a byte array to the output.
+ *
+ * This method is used with {@link #packRawStringHeader(int)} or {@link #packBinaryHeader(int)} methods.
*
* @param src the data to add
* @return this
- * @throws IOException
+ * @throws IOException when underlying output throws IOException
*/
public MessagePacker writePayload(byte[] src)
throws IOException
@@ -717,14 +944,15 @@ public MessagePacker writePayload(byte[] src)
}
/**
- * Writes buffer to the output.
- * This method is used with packRawStringHeader or packBinaryHeader.
+ * Writes a byte array to the output.
+ *
+ * This method is used with {@link #packRawStringHeader(int)} or {@link #packBinaryHeader(int)} methods.
*
* @param src the data to add
* @param off the start offset in the data
* @param len the number of bytes to add
* @return this
- * @throws IOException
+ * @throws IOException when underlying output throws IOException
*/
public MessagePacker writePayload(byte[] src, int off, int len)
throws IOException
@@ -743,13 +971,15 @@ public MessagePacker writePayload(byte[] src, int off, int len)
}
/**
- * Writes buffer to the output.
- * Unlike writePayload method, addPayload method doesn't copy the source data. It means that the caller
- * must not modify the data after calling this method.
+ * Writes a byte array to the output.
+ *
+ * Unlike {@link #writePayload(byte[])} method, this method doesn't copy the byte array even when given byte
+ * array is shorter than {@link MessagePack.PackerConfig#withBufferFlushThreshold(int)}. This is faster than
+ * {@link #writePayload(byte[])} method but caller must not modify the byte array after calling this method.
*
* @param src the data to add
* @return this
- * @throws IOException
+ * @throws IOException when underlying output throws IOException
*/
public MessagePacker addPayload(byte[] src)
throws IOException
@@ -758,15 +988,18 @@ public MessagePacker addPayload(byte[] src)
}
/**
- * Writes buffer to the output.
- * Unlike writePayload method, addPayload method doesn't copy the source data. It means that the caller
- * must not modify the data after calling this method.
+ * Writes a byte array to the output.
+ *
+ * Unlike {@link #writePayload(byte[], int, int)} method, this method doesn't copy the byte array even when
+ * given byte array is shorter than {@link MessagePack.PackerConfig#withBufferFlushThreshold(int)}.
+ * This is faster than {@link #writePayload(byte[], int, int)} method but caller must not modify the byte array
+ * after calling this method.
*
* @param src the data to add
* @param off the start offset in the data
* @param len the number of bytes to add
* @return this
- * @throws IOException
+ * @throws IOException when underlying output throws IOException
*/
public MessagePacker addPayload(byte[] src, int off, int len)
throws IOException
diff --git a/msgpack-core/src/main/java/org/msgpack/core/MessageUnpacker.java b/msgpack-core/src/main/java/org/msgpack/core/MessageUnpacker.java
index 0696cd54c..82ed9d15f 100644
--- a/msgpack-core/src/main/java/org/msgpack/core/MessageUnpacker.java
+++ b/msgpack-core/src/main/java/org/msgpack/core/MessageUnpacker.java
@@ -40,31 +40,112 @@
import static org.msgpack.core.Preconditions.checkNotNull;
/**
- * MessageUnpacker lets an application read message-packed values from a data stream.
- * The application needs to call {@link #getNextFormat()} followed by an appropriate unpackXXX method according to the the returned format type.
- *
- *
- *
+ * MessagePack deserializer that converts binary into objects.
+ * You can use factory methods of {@link MessagePack} class or {@link MessagePack.UnpackerConfig} class to create
+ * an instance.
+ * To read values as statically-typed Java objects, there are two typical use cases.
+ *
+ * One use case is to read objects as {@link Value} using {@link #unpackValue} method. A {@link Value} object
+ * contains type of the deserialized value as well as the value itself so that you can inspect type of the
+ * deserialized values later. You can repeat {@link #unpackValue} until {@link #hasNext()} method returns false so
+ * that you can deserialize sequence of MessagePack values.
+ *
+ * The other use case is to use {@link #getNextFormat()} and {@link MessageFormat#getValueType()} methods followed
+ * by unpackXxx methods corresponding to returned type. Following code snipet is a typical application code:
+ *
* MessageUnpacker unpacker = MessagePack.newDefaultUnpacker(...);
* while(unpacker.hasNext()) {
- * MessageFormat f = unpacker.getNextFormat();
- * switch(f) {
- * case MessageFormat.POSFIXINT:
- * case MessageFormat.INT8:
- * case MessageFormat.UINT8: {
- * int v = unpacker.unpackInt();
- * break;
+ * MessageFormat format = unpacker.getNextFormat();
+ * ValueType type = format.getValueType();
+ * int length;
+ * ExtensionTypeHeader extension;
+ * switch(type) {
+ * case NIL:
+ * unpacker.unpackNil();
+ * break;
+ * case BOOLEAN:
+ * unpacker.unpackBoolean();
+ * break;
+ * case INTEGER:
+ * switch (format) {
+ * case UINT64:
+ * unpacker.unpackBigInteger();
+ * break;
+ * case INT64:
+ * case UINT32:
+ * unpacker.unpackLong();
+ * break;
+ * default:
+ * unpacker.unpackInt();
+ * break;
+ * }
+ * break;
+ * case FLOAT:
+ * unpacker.unpackDouble();
+ * break;
+ * case STRING:
+ * unpacker.unpackString();
+ * break;
+ * case BINARY:
+ * length = unpacker.unpackBinaryHeader();
+ * unpacker.readPayload(new byte[length]);
+ * break;
+ * case ARRAY:
+ * length = unpacker.unpackArrayHeader();
+ * for (int i = 0; i < length; i++) {
+ * readRecursively(unpacker);
+ * }
+ * break;
+ * case MAP:
+ * length = unpacker.unpackMapHeader();
+ * for (int i = 0; i < length; i++) {
+ * readRecursively(unpacker); // key
+ * readRecursively(unpacker); // value
+ * }
+ * break;
+ * case EXTENSION:
+ * extension = unpacker.unpackExtensionTypeHeader();
+ * unpacker.readPayload(new byte[extension.getLength()]);
+ * break;
* }
- * case MessageFormat.STRING: {
- * String v = unpacker.unpackString();
- * break;
- * }
- * // ...
- * }
+ * }
* }
*
- *
- *
+ *
+ * Following methods correspond to the MessagePack types:
+ *
+ *
+ * | MessagePack type | Unpacker method | Java type |
|---|
+ * | Nil | {@link #unpackNil()} | null |
+ * | Boolean | {@link #unpackBoolean()} | boolean |
+ * | Integer | {@link #unpackByte()} | byte |
+ * | Integer | {@link #unpackShort()} | short |
+ * | Integer | {@link #unpackInt()} | int |
+ * | Integer | {@link #unpackLong()} | long |
+ * | Integer | {@link #unpackBigInteger()} | BigInteger |
+ * | Float | {@link #unpackFloat()} | float |
+ * | Float | {@link #unpackDouble()} | double |
+ * | Binary | {@link #unpackBinaryHeader()} | byte array |
+ * | String | {@link #unpackRawStringHeader()} | String |
+ * | String | {@link #unpackString()} | String |
+ * | Array | {@link #unpackArrayHeader()} | Array |
+ * | Map | {@link #unpackMapHeader()} | Map |
+ * | Extension | {@link #unpackExtensionTypeHeader()} | {@link ExtensionTypeHeader} |
+ *
+ *
+ *
+ * To read a byte array, first call {@link #unpackBinaryHeader} method to get length of the byte array. Then,
+ * call {@link #readPayload(int)} or {@link #readPayloadAsReference(int)} method to read the the contents.
+ *
+ *
+ * To read an Array type, first call {@link #unpackArrayHeader()} method to get number of elements. Then,
+ * call unpacker methods for each element.
+ *
+ *
+ * To read a Map, first call {@link #unpackMapHeader()} method to get number of pairs of the map. Then,
+ * for each pair, call unpacker methods for key first, and then value. will call unpacker methods twice
+ * as many time as the returned count.
+ *
*/
public class MessageUnpacker
implements Closeable
@@ -139,10 +220,18 @@ protected MessageUnpacker(MessageBufferInput in, MessagePack.UnpackerConfig conf
}
/**
- * Reset input. This method doesn't close the old resource.
+ * Replaces underlying input.
+ *
+ * This method clears internal buffer, swaps the underlying input with the new given input, then returns
+ * the old input.
+ *
+ *
+ * This method doesn't close the old input.
*
* @param in new input
- * @return the old resource
+ * @return the old input
+ * @throws IOException never happens unless a subclass overrides this method
+ * @throws NullPointerException the given input is null
*/
public MessageBufferInput reset(MessageBufferInput in)
throws IOException
@@ -160,6 +249,15 @@ public MessageBufferInput reset(MessageBufferInput in)
return old;
}
+ /**
+ * Returns total number of read bytes.
+ *
+ * This method returns total of amount of data consumed from the underlying input minus size of data
+ * remained still unused in the current internal buffer.
+ *
+ *
+ * Calling {@link #reset(MessageBufferInput)} resets this number to 0.
+ */
public long getTotalReadBytes()
{
return totalReadBytes + position;
@@ -274,13 +372,18 @@ private boolean ensureBuffer()
}
/**
- * Returns the next MessageFormat type. This method should be called after {@link #hasNext()} returns true.
- * If {@link #hasNext()} returns false, calling this method throws {@link MessageInsufficientBufferException}.
- *
- * This method does not proceed the internal cursor.
+ * Returns format of the next value.
+ *
+ *
+ * Note that this method doesn't consume data from the internal buffer unlike the other unpack methods.
+ * Calling this method twice will return the same value.
+ *
+ *
+ * To not throw {@link MessageInsufficientBufferException}, this method should be called only when
+ * {@link #hasNext()} returns true.
*
* @return the next MessageFormat
- * @throws IOException when failed to read the input data.
+ * @throws IOException when underlying input throws IOException
* @throws MessageInsufficientBufferException when the end of file reached, i.e. {@link #hasNext()} == false.
*/
public MessageFormat getNextFormat()
@@ -612,6 +715,12 @@ public Variable unpackValue(Variable var)
}
}
+ /**
+ * Reads a Nil byte.
+ *
+ * @throws MessageTypeException when value is not MessagePack Nil type
+ * @throws IOException when underlying input throws IOException
+ */
public void unpackNil()
throws IOException
{
@@ -622,6 +731,13 @@ public void unpackNil()
throw unexpected("Nil", b);
}
+ /**
+ * Reads true or false.
+ *
+ * @return the read value
+ * @throws MessageTypeException when value is not MessagePack Boolean type
+ * @throws IOException when underlying input throws IOException
+ */
public boolean unpackBoolean()
throws IOException
{
@@ -635,6 +751,16 @@ else if (b == Code.TRUE) {
throw unexpected("boolean", b);
}
+ /**
+ * Reads a byte.
+ *
+ * This method throws {@link MessageIntegerOverflowException} if the value doesn't fit in the range of byte. This may happen when {@link #getNextFormat()} returns UINT8, INT16, or larger integer formats.
+ *
+ * @return the read value
+ * @throws MessageIntegerOverflowException when value doesn't fit in the range of byte
+ * @throws MessageTypeException when value is not MessagePack Integer type
+ * @throws IOException when underlying input throws IOException
+ */
public byte unpackByte()
throws IOException
{
@@ -692,6 +818,16 @@ public byte unpackByte()
throw unexpected("Integer", b);
}
+ /**
+ * Reads a short.
+ *
+ * This method throws {@link MessageIntegerOverflowException} if the value doesn't fit in the range of short. This may happen when {@link #getNextFormat()} returns UINT16, INT32, or larger integer formats.
+ *
+ * @return the read value
+ * @throws MessageIntegerOverflowException when value doesn't fit in the range of short
+ * @throws MessageTypeException when value is not MessagePack Integer type
+ * @throws IOException when underlying input throws IOException
+ */
public short unpackShort()
throws IOException
{
@@ -743,6 +879,16 @@ public short unpackShort()
throw unexpected("Integer", b);
}
+ /**
+ * Reads a int.
+ *
+ * This method throws {@link MessageIntegerOverflowException} if the value doesn't fit in the range of int. This may happen when {@link #getNextFormat()} returns UINT32, INT64, or larger integer formats.
+ *
+ * @return the read value
+ * @throws MessageIntegerOverflowException when value doesn't fit in the range of int
+ * @throws MessageTypeException when value is not MessagePack Integer type
+ * @throws IOException when underlying input throws IOException
+ */
public int unpackInt()
throws IOException
{
@@ -788,6 +934,16 @@ public int unpackInt()
throw unexpected("Integer", b);
}
+ /**
+ * Reads a long.
+ *
+ * This method throws {@link MessageIntegerOverflowException} if the value doesn't fit in the range of long. This may happen when {@link #getNextFormat()} returns UINT64.
+ *
+ * @return the read value
+ * @throws MessageIntegerOverflowException when value doesn't fit in the range of long
+ * @throws MessageTypeException when value is not MessagePack Integer type
+ * @throws IOException when underlying input throws IOException
+ */
public long unpackLong()
throws IOException
{
@@ -832,6 +988,13 @@ public long unpackLong()
throw unexpected("Integer", b);
}
+ /**
+ * Reads a BigInteger.
+ *
+ * @return the read value
+ * @throws MessageTypeException when value is not MessagePack Integer type
+ * @throws IOException when underlying input throws IOException
+ */
public BigInteger unpackBigInteger()
throws IOException
{
@@ -879,6 +1042,15 @@ public BigInteger unpackBigInteger()
throw unexpected("Integer", b);
}
+ /**
+ * Reads a float.
+ *
+ * This method rounds value to the range of float when precision of the read value is larger than the range of float. This may happen when {@link #getNextFormat()} returns FLOAT64.
+ *
+ * @return the read value
+ * @throws MessageTypeException when value is not MessagePack Float type
+ * @throws IOException when underlying input throws IOException
+ */
public float unpackFloat()
throws IOException
{
@@ -894,6 +1066,13 @@ public float unpackFloat()
throw unexpected("Float", b);
}
+ /**
+ * Reads a double.
+ *
+ * @return the read value
+ * @throws MessageTypeException when value is not MessagePack Float type
+ * @throws IOException when underlying input throws IOException
+ */
public double unpackDouble()
throws IOException
{
@@ -1053,6 +1232,18 @@ private String decodeStringFastPath(int length)
}
}
+ /**
+ * Reads header of an array.
+ *
+ *
+ * This method returns number of elements to be read. After this method call, you call unpacker methods for
+ * each element. You don't have to call anything at the end of iteration.
+ *
+ * @return the size of the array to be read
+ * @throws MessageTypeException when value is not MessagePack Array type
+ * @throws MessageSizeException when size of the array is larger than 2^31 - 1
+ * @throws IOException when underlying input throws IOException
+ */
public int unpackArrayHeader()
throws IOException
{
@@ -1073,6 +1264,19 @@ public int unpackArrayHeader()
throw unexpected("Array", b);
}
+ /**
+ * Reads header of a map.
+ *
+ *
+ * This method returns number of pairs to be read. After this method call, 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.
+ *
+ * @return the size of the map to be read
+ * @throws MessageTypeException when value is not MessagePack Map type
+ * @throws MessageSizeException when size of the map is larger than 2^31 - 1
+ * @throws IOException when underlying input throws IOException
+ */
public int unpackMapHeader()
throws IOException
{
@@ -1198,6 +1402,22 @@ public int unpackRawStringHeader()
throw unexpected("String", b);
}
+ /**
+ * Reads header of a binary.
+ *
+ *
+ * This method returns number of bytes to be read. After this method call, you call a readPayload method such as
+ * {@link #readPayload(int)} with the returned count.
+ *
+ *
+ * You can divide readPayload method into multiple calls. In this case, you must repeat readPayload methods
+ * until total amount of bytes becomes equal to the returned count.
+ *
+ * @return the size of the map to be read
+ * @throws MessageTypeException when value is not MessagePack Map type
+ * @throws MessageSizeException when size of the map is larger than 2^31 - 1
+ * @throws IOException when underlying input throws IOException
+ */
public int unpackBinaryHeader()
throws IOException
{
@@ -1243,6 +1463,16 @@ private void skipPayload(int numBytes)
}
}
+ /**
+ * Reads payload bytes of binary, extension, or raw string types.
+ *
+ *
+ * This consumes bytes, copies them to the specified buffer, and moves forward position of the byte buffer
+ * until ByteBuffer.remaining() returns 0.
+ *
+ * @param dst the byte buffer into which the data is read
+ * @throws IOException when underlying input throws IOException
+ */
public void readPayload(ByteBuffer dst)
throws IOException
{
@@ -1261,12 +1491,35 @@ public void readPayload(ByteBuffer dst)
}
}
+ /**
+ * Reads payload bytes of binary, extension, or raw string types.
+ *
+ * This consumes specified amount of bytes into the specified byte array.
+ *
+ *
+ * This method is equivalent to readPayload(dst, 0, dst.length).
+ *
+ * @param dst the byte array into which the data is read
+ * @throws IOException when underlying input throws IOException
+ */
public void readPayload(byte[] dst)
throws IOException
{
readPayload(dst, 0, dst.length);
}
+ /**
+ * Reads payload bytes of binary, extension, or raw string types.
+ *
+ * This method allocates a new byte array and consumes specified amount of bytes into the byte array.
+ *
+ *
+ * This method is equivalent to readPayload(new byte[length]).
+ *
+ * @param length number of bytes to be read
+ * @return the new byte array
+ * @throws IOException when underlying input throws IOException
+ */
public byte[] readPayload(int length)
throws IOException
{
@@ -1276,12 +1529,14 @@ public byte[] readPayload(int length)
}
/**
- * Read up to len bytes of data into the destination array
+ * Reads payload bytes of binary, extension, or raw string types.
*
- * @param dst the buffer into which the data is read
+ * This consumes specified amount of bytes into the specified byte array.
+ *
+ * @param dst the byte array into which the data is read
* @param off the offset in the dst array
* @param len the number of bytes to read
- * @throws IOException
+ * @throws IOException when underlying input throws IOException
*/
public void readPayload(byte[] dst, int off, int len)
throws IOException
@@ -1290,6 +1545,17 @@ public void readPayload(byte[] dst, int off, int len)
readPayload(ByteBuffer.wrap(dst, off, len));
}
+ /**
+ * Reads payload bytes of binary, extension, or raw string types as a reference to internal buffer.
+ *
+ *
+ * This consumes specified amount of bytes and returns its reference or copy. This method tries to
+ * return reference as much as possible because it is faster. However, it may copy data to a newly
+ * allocated buffer if reference is not applicable.
+ *
+ * @param length number of bytes to be read
+ * @throws IOException when underlying input throws IOException
+ */
public MessageBuffer readPayloadAsReference(int length)
throws IOException
{
@@ -1328,6 +1594,11 @@ private int readNextLength32()
return u32;
}
+ /**
+ * Closes underlying input.
+ *
+ * @throws IOException
+ */
@Override
public void close()
throws IOException
diff --git a/msgpack-core/src/main/java/org/msgpack/core/buffer/ArrayBufferOutput.java b/msgpack-core/src/main/java/org/msgpack/core/buffer/ArrayBufferOutput.java
index 186a579af..cd31e6453 100644
--- a/msgpack-core/src/main/java/org/msgpack/core/buffer/ArrayBufferOutput.java
+++ b/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.
+ *
+ * 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();
}
+ /**
+ * Gets the 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 a copy of the written data as a byte array.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * 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 toBufferList()
{
return new ArrayList(list);
}
/**
- * Clears the internal buffers
+ * Clears the written data.
*/
public void clear()
{
diff --git a/msgpack-core/src/main/java/org/msgpack/core/buffer/MessageBuffer.java b/msgpack-core/src/main/java/org/msgpack/core/buffer/MessageBuffer.java
index 50d472ae5..246e678a7 100644
--- a/msgpack-core/src/main/java/org/msgpack/core/buffer/MessageBuffer.java
+++ b/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.
- *
- * 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.
+ *
+ * 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.
+ *
+ * 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 import
+ * unnecessary classes such as MessagePackBE. On big-endian CPU archtectures, it automatically uses a subclass that
+ * includes TypeProfile overhead but still faster than stndard ByteBuffer class. On JVMs older than Java 7 and JVMs
+ * without Unsafe API (such as Android), implementation falls back to an universal implementation that uses ByteBuffer
+ * internally.
*/
public class MessageBuffer
{
@@ -205,7 +213,7 @@ public static MessageBuffer allocate(int size)
* The new buffer's size will be array.length. hasArray() will return true.
*
* @param array the byte array that will gack this MessageBuffer
- * @return
+ * @return a new MessageBuffer that wraps the given byte array
*
*/
public static MessageBuffer wrap(byte[] array)
@@ -223,7 +231,7 @@ public static MessageBuffer wrap(byte[] array)
* @param array the byte array that will gack this MessageBuffer
* @param offset The offset of the subarray to be used; must be non-negative and no larger than array.length
* @param length The length of the subarray to be used; must be non-negative and no larger than array.length - offset
- * @return
+ * @return a new MessageBuffer that wraps the given byte array
*
*/
public static MessageBuffer wrap(byte[] array, int offset, int length)
@@ -241,7 +249,7 @@ public static MessageBuffer wrap(byte[] array, int offset, int length)
* @param bb the byte buffer that will gack this MessageBuffer
* @throws IllegalArgumentException given byte buffer returns false both from hasArray() and isDirect()
* @throws UnsupportedOperationException given byte buffer is a direct buffer and this platform doesn't support Unsafe API
- * @return
+ * @return a new MessageBuffer that wraps the given byte array
*
*/
public static MessageBuffer wrap(ByteBuffer bb)
@@ -296,7 +304,7 @@ private static MessageBuffer newInstance(Constructor constructor, Object... a
}
catch (InvocationTargetException e) {
if (e.getCause() instanceof RuntimeException) {
- // underlaying constructor may throw RuntimeException
+ // underlying constructor may throw RuntimeException
throw (RuntimeException) e.getCause();
}
else if (e.getCause() instanceof Error) {
@@ -373,9 +381,12 @@ protected MessageBuffer(Object base, long address, int length)
}
/**
- * byte size of the buffer
+ * Gets the size of the buffer.
*
- * @return
+ * MessageBuffer doesn't have limit unlike ByteBuffer. Instead, you can use {@link #slice(int, int)} to get a
+ * part of the buffer.
+ *
+ * @return number of bytes
*/
public int size()
{
diff --git a/msgpack-core/src/main/java/org/msgpack/core/buffer/MessageBufferInput.java b/msgpack-core/src/main/java/org/msgpack/core/buffer/MessageBufferInput.java
index 46eea243e..77f7a06f6 100644
--- a/msgpack-core/src/main/java/org/msgpack/core/buffer/MessageBufferInput.java
+++ b/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.
*
- * 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.
+ *
+ * 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.
+ *
+ * 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;
}
diff --git a/msgpack-core/src/main/java/org/msgpack/core/buffer/MessageBufferOutput.java b/msgpack-core/src/main/java/org/msgpack/core/buffer/MessageBufferOutput.java
index 024414bae..a9a51fbcc 100644
--- a/msgpack-core/src/main/java/org/msgpack/core/buffer/MessageBufferOutput.java
+++ b/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.
+ *
+ * This method should return a MessageBuffer instance that has specified size of capacity at least.
+ *
+ * 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(int)} 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.
+ *
+ * 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.
+ *
+ * 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 when the next {@link #next(int)} is called.
*
- * @param length the size of buffer to flush
+ * @param length the number of bytes to write
* @throws IOException
*/
void writeBuffer(int length)
@@ -55,7 +66,6 @@ void writeBuffer(int length)
* @param buffer the data to write
* @param offset the start offset in the data
* @param length the number of bytes to write
- * @return
* @throws IOException
*/
void write(byte[] buffer, int offset, int length)
@@ -63,12 +73,14 @@ 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.
+ *
+ * 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
* @param length the number of bytes to add
- * @return
* @throws IOException
*/
void add(byte[] buffer, int offset, int length)
diff --git a/msgpack-core/src/main/java/org/msgpack/value/ArrayValue.java b/msgpack-core/src/main/java/org/msgpack/value/ArrayValue.java
index 4d7a6e8c2..05d64d3d7 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/ArrayValue.java
+++ b/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.
*/
diff --git a/msgpack-core/src/main/java/org/msgpack/value/BinaryValue.java b/msgpack-core/src/main/java/org/msgpack/value/BinaryValue.java
index c66f7a67c..74a413316 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/BinaryValue.java
+++ b/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 264-1 bytes.
*
diff --git a/msgpack-core/src/main/java/org/msgpack/value/BooleanValue.java b/msgpack-core/src/main/java/org/msgpack/value/BooleanValue.java
index 6ccf5c9ef..b0aa3b9d8 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/BooleanValue.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/BooleanValue.java
@@ -16,7 +16,7 @@
package org.msgpack.value;
/**
- * The interface {@code BooleanValue} represents MessagePack's Boolean type.
+ * Representation MessagePack's Boolean type.
*
* MessagePack's Boolean type can represent {@code true} or {@code false}.
*/
diff --git a/msgpack-core/src/main/java/org/msgpack/value/ExtensionValue.java b/msgpack-core/src/main/java/org/msgpack/value/ExtensionValue.java
index 5a076ecbc..51c50b9a8 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/ExtensionValue.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/ExtensionValue.java
@@ -16,7 +16,7 @@
package org.msgpack.value;
/**
- * The interface {@code ExtensionValue} represents MessagePack's Extension type.
+ * Representation of MessagePack's Extension type.
*
* MessagePack's Extension type can represent represents a tuple of type information and a byte array where type information is an
* integer whose meaning is defined by applications.
diff --git a/msgpack-core/src/main/java/org/msgpack/value/FloatValue.java b/msgpack-core/src/main/java/org/msgpack/value/FloatValue.java
index dbaf73a18..68fcf9fa5 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/FloatValue.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/FloatValue.java
@@ -16,7 +16,7 @@
package org.msgpack.value;
/**
- * The interface {@code FloatValue} represents MessagePack's Float type.
+ * Representation of MessagePack's Float type.
*
* MessagePack's Float type can represent IEEE 754 double precision floating point numbers including NaN and infinity. This is same with Java's {@code double} type.
*
diff --git a/msgpack-core/src/main/java/org/msgpack/value/ImmutableArrayValue.java b/msgpack-core/src/main/java/org/msgpack/value/ImmutableArrayValue.java
index 9301c2eb8..9aa0687fa 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/ImmutableArrayValue.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/ImmutableArrayValue.java
@@ -18,6 +18,11 @@
import java.util.Iterator;
import java.util.List;
+/**
+ * Immutable representation of MessagePack's Array type.
+ *
+ * MessagePack's Array type can represent sequence of values.
+ */
public interface ImmutableArrayValue
extends ArrayValue, ImmutableValue
{
diff --git a/msgpack-core/src/main/java/org/msgpack/value/ImmutableBinaryValue.java b/msgpack-core/src/main/java/org/msgpack/value/ImmutableBinaryValue.java
index 475241a57..9aefd7bc8 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/ImmutableBinaryValue.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/ImmutableBinaryValue.java
@@ -15,6 +15,13 @@
//
package org.msgpack.value;
+/**
+ * Immutable representation of MessagePack's Binary type.
+ *
+ * MessagePack's Binary type can represent a byte array at most 264-1 bytes.
+ *
+ * @see org.msgpack.value.ImmutableRawValue
+ */
public interface ImmutableBinaryValue
extends BinaryValue, ImmutableRawValue
{
diff --git a/msgpack-core/src/main/java/org/msgpack/value/ImmutableBooleanValue.java b/msgpack-core/src/main/java/org/msgpack/value/ImmutableBooleanValue.java
index dd2afad43..dcf221171 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/ImmutableBooleanValue.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/ImmutableBooleanValue.java
@@ -15,6 +15,11 @@
//
package org.msgpack.value;
+/**
+ * Immutable representation of MessagePack's Boolean type.
+ *
+ * MessagePack's Boolean type can represent {@code true} or {@code false}.
+ */
public interface ImmutableBooleanValue
extends BooleanValue, ImmutableValue
{
diff --git a/msgpack-core/src/main/java/org/msgpack/value/ImmutableExtensionValue.java b/msgpack-core/src/main/java/org/msgpack/value/ImmutableExtensionValue.java
index 5e984db05..8c9b73753 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/ImmutableExtensionValue.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/ImmutableExtensionValue.java
@@ -15,6 +15,11 @@
//
package org.msgpack.value;
+/**
+ * Immutable representation of MessagePack's Extension type.
+ *
+ * @see org.msgpack.value.ExtensionValue
+ */
public interface ImmutableExtensionValue
extends ExtensionValue, ImmutableValue
{
diff --git a/msgpack-core/src/main/java/org/msgpack/value/ImmutableFloatValue.java b/msgpack-core/src/main/java/org/msgpack/value/ImmutableFloatValue.java
index 7105483d1..9a30f9b9f 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/ImmutableFloatValue.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/ImmutableFloatValue.java
@@ -15,6 +15,13 @@
//
package org.msgpack.value;
+/**
+ * Immutable representation of MessagePack's Float type.
+ *
+ * MessagePack's Float type can represent IEEE 754 double precision floating point numbers including NaN and infinity. This is same with Java's {@code double} type.
+ *
+ * @see org.msgpack.value.ImmutableNumberValue
+ */
public interface ImmutableFloatValue
extends FloatValue, ImmutableNumberValue
{
diff --git a/msgpack-core/src/main/java/org/msgpack/value/ImmutableIntegerValue.java b/msgpack-core/src/main/java/org/msgpack/value/ImmutableIntegerValue.java
index 3482583ff..ec246748e 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/ImmutableIntegerValue.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/ImmutableIntegerValue.java
@@ -15,6 +15,11 @@
//
package org.msgpack.value;
+/**
+ * Immutable representation of MessagePack's Integer type.
+ *
+ * MessagePack's Integer type can represent from -263 to 264-1.
+ */
public interface ImmutableIntegerValue
extends IntegerValue, ImmutableNumberValue
{
diff --git a/msgpack-core/src/main/java/org/msgpack/value/ImmutableMapValue.java b/msgpack-core/src/main/java/org/msgpack/value/ImmutableMapValue.java
index cc3122f03..0c27d5540 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/ImmutableMapValue.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/ImmutableMapValue.java
@@ -15,6 +15,11 @@
//
package org.msgpack.value;
+/**
+ * Immutable representation of MessagePack's Map type.
+ *
+ * MessagePack's Map type can represent sequence of key-value pairs.
+ */
public interface ImmutableMapValue
extends MapValue, ImmutableValue
{
diff --git a/msgpack-core/src/main/java/org/msgpack/value/ImmutableNilValue.java b/msgpack-core/src/main/java/org/msgpack/value/ImmutableNilValue.java
index 8a7857287..36135fcef 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/ImmutableNilValue.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/ImmutableNilValue.java
@@ -15,6 +15,9 @@
//
package org.msgpack.value;
+/**
+ * Immutable representation of MessagePack's Nil type.
+ */
public interface ImmutableNilValue
extends NilValue, ImmutableValue
{
diff --git a/msgpack-core/src/main/java/org/msgpack/value/ImmutableNumberValue.java b/msgpack-core/src/main/java/org/msgpack/value/ImmutableNumberValue.java
index 42afcf304..a3b984af6 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/ImmutableNumberValue.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/ImmutableNumberValue.java
@@ -15,6 +15,12 @@
//
package org.msgpack.value;
+/**
+ * Immutable base interface of {@link ImmutableIntegerValue} and {@link ImmutableFloatValue} interfaces. To extract primitive type values, call toXXX methods, which may lose some information by rounding or truncation.
+ *
+ * @see org.msgpack.value.ImmutableIntegerValue
+ * @see org.msgpack.value.ImmutableFloatValue
+ */
public interface ImmutableNumberValue
extends NumberValue, ImmutableValue
{
diff --git a/msgpack-core/src/main/java/org/msgpack/value/ImmutableRawValue.java b/msgpack-core/src/main/java/org/msgpack/value/ImmutableRawValue.java
index 36698dbeb..d3f2eaab6 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/ImmutableRawValue.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/ImmutableRawValue.java
@@ -15,6 +15,14 @@
//
package org.msgpack.value;
+/**
+ * Immutable base interface of {@link ImmutableStringValue} and {@link ImmutableBinaryValue} interfaces.
+ *
+ * MessagePack's Raw type can represent a byte array at most 264-1 bytes.
+ *
+ * @see org.msgpack.value.ImmutableStringValue
+ * @see org.msgpack.value.ImmutableBinaryValue
+ */
public interface ImmutableRawValue
extends RawValue, ImmutableValue
{
diff --git a/msgpack-core/src/main/java/org/msgpack/value/ImmutableStringValue.java b/msgpack-core/src/main/java/org/msgpack/value/ImmutableStringValue.java
index 6e3f95360..2c198ae11 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/ImmutableStringValue.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/ImmutableStringValue.java
@@ -15,6 +15,12 @@
//
package org.msgpack.value;
+/**
+ * Immutable representation of MessagePack's String type.
+ *
+ * @see org.msgpack.value.StringValue
+ * @see org.msgpack.value.ImmutableRawValue
+ */
public interface ImmutableStringValue
extends StringValue, ImmutableRawValue
{
diff --git a/msgpack-core/src/main/java/org/msgpack/value/ImmutableValue.java b/msgpack-core/src/main/java/org/msgpack/value/ImmutableValue.java
index 6a5740029..88798a13d 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/ImmutableValue.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/ImmutableValue.java
@@ -15,6 +15,9 @@
//
package org.msgpack.value;
+/**
+ * Immutable declaration of {@link Value} interface.
+ */
public interface ImmutableValue
extends Value
{
diff --git a/msgpack-core/src/main/java/org/msgpack/value/IntegerValue.java b/msgpack-core/src/main/java/org/msgpack/value/IntegerValue.java
index 8480751c4..b23378261 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/IntegerValue.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/IntegerValue.java
@@ -20,7 +20,7 @@
import java.math.BigInteger;
/**
- * The interface {@code IntegerValue} represents MessagePack's Integer type.
+ * Representation of MessagePack's Integer type.
*
* MessagePack's Integer type can represent from -263 to 264-1.
*/
@@ -49,7 +49,8 @@ public interface IntegerValue
/**
* Returns the most succinct MessageFormat type to represent this integer value.
- * @return
+ *
+ * @return the smallest integer type of MessageFormat that is big enough to store the value.
*/
MessageFormat mostSuccinctMessageFormat();
diff --git a/msgpack-core/src/main/java/org/msgpack/value/MapValue.java b/msgpack-core/src/main/java/org/msgpack/value/MapValue.java
index fa7f55c8d..a68982a47 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/MapValue.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/MapValue.java
@@ -20,7 +20,7 @@
import java.util.Set;
/**
- * The interface {@code ArrayValue} represents MessagePack's Map type.
+ * Representation of MessagePack's Map type.
*
* MessagePack's Map type can represent sequence of key-value pairs.
*/
diff --git a/msgpack-core/src/main/java/org/msgpack/value/NilValue.java b/msgpack-core/src/main/java/org/msgpack/value/NilValue.java
index 8f5835001..9307ae6f0 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/NilValue.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/NilValue.java
@@ -16,7 +16,7 @@
package org.msgpack.value;
/**
- * The interface {@code NilValue} represents MessagePack's Nil type.
+ * Representation of MessagePack's Nil type.
*/
public interface NilValue
extends Value
diff --git a/msgpack-core/src/main/java/org/msgpack/value/NumberValue.java b/msgpack-core/src/main/java/org/msgpack/value/NumberValue.java
index 3e5bd75e0..828e6353c 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/NumberValue.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/NumberValue.java
@@ -18,7 +18,7 @@
import java.math.BigInteger;
/**
- * The base interface {@code NumberValue} of {@code IntegerValue} and {@code FloatValue}. To extract primitive type values, call toXXX methods, which may lose some information by rounding or truncation.
+ * Base interface of {@link IntegerValue} and {@link FloatValue} interfaces. To extract primitive type values, call toXXX methods, which may lose some information by rounding or truncation.
*
* @see org.msgpack.value.IntegerValue
* @see org.msgpack.value.FloatValue
diff --git a/msgpack-core/src/main/java/org/msgpack/value/RawValue.java b/msgpack-core/src/main/java/org/msgpack/value/RawValue.java
index 8857b5340..ba327a835 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/RawValue.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/RawValue.java
@@ -18,7 +18,7 @@
import java.nio.ByteBuffer;
/**
- * The interface {@code RawValue} represents MessagePack's Raw type, which means Binary or String type.
+ * Base interface of {@link StringValue} and {@link BinaryValue} interfaces.
*
* MessagePack's Raw type can represent a byte array at most 264-1 bytes.
*
@@ -38,7 +38,7 @@ public interface RawValue
/**
* Returns the value as {@code ByteBuffer}.
*
- * Returned ByteBuffer is read-only. See {@code#asReadOnlyBuffer()}.
+ * Returned ByteBuffer is read-only. See also {@link java.nio.ByteBuffer#asReadOnlyBuffer()}.
* This method doesn't copy the byte array as much as possible.
*/
ByteBuffer asByteBuffer();
diff --git a/msgpack-core/src/main/java/org/msgpack/value/StringValue.java b/msgpack-core/src/main/java/org/msgpack/value/StringValue.java
index 0c812d58d..de2ec1eae 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/StringValue.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/StringValue.java
@@ -16,7 +16,7 @@
package org.msgpack.value;
/**
- * The interface {@code StringValue} represents MessagePack's String type.
+ * Representation of MessagePack's String type.
*
* MessagePack's String type can represent a UTF-8 string at most 264-1 bytes.
*
diff --git a/msgpack-core/src/main/java/org/msgpack/value/Value.java b/msgpack-core/src/main/java/org/msgpack/value/Value.java
index 2fae838b4..546dfbbf4 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/Value.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/Value.java
@@ -20,11 +20,60 @@
import java.io.IOException;
/**
- * Value is an implementation of MessagePack type system. To retrieve values from a Value object,
- * You need to check its {@link ValueType} then call an appropriate asXXXValue method.
+ * Value stores a value and its type in MessagePack type system.
*
+ * Type conversion
+ *
+ * You can check type first using isXxx() methods or {@link #getValueType()} method, then convert the value to a
+ * subtype using asXxx() methods. You can also call asXxx() methods directly and catch
+ * {@link org.msgpack.core.MessageTypeCastException}.
*
+ *
+ * | MessagePack type | Check method | Convert method | Value type |
|---|
+ * | Nil | {@link #isNilValue()} | {@link #asNumberValue()} | {@link NilValue} |
+ * | Boolean | {@link #isBooleanValue()} | {@link #asBooleanValue()} | {@link BooleanValue} |
+ * | Integer or Float | {@link #isNumberValue()} | {@link #asNumberValue()} | {@link NumberValue} |
+ * | Integer | {@link #isIntegerValue()} | {@link #asIntegerValue()} | {@link IntegerValue} |
+ * | Float | {@link #isFloatValue()} | {@link #asFloatValue()} | {@link FloatValue} |
+ * | String or Binary | {@link #isRawValue()} | {@link #asRawValue()} | {@link RawValue} |
+ * | String | {@link #isStringValue()} | {@link #asStringValue()} | {@link StringValue} |
+ * | Binary | {@link #isBinaryValue()} | {@link #asBinaryValue()} | {@link BinaryValue} |
+ * | Array | {@link #isArrayValue()} | {@link #asArrayValue()} | {@link ArrayValue} |
+ * | Map | {@link #isMapValue()} | {@link #asMapValue()} | {@link MapValue} |
+ * | Extension | {@link #isExtensionValue()} | {@link #asExtensionValue()} | {@link ExtensionValue} |
+ *
*
+ * Immutable interface
+ *
+ * Value interface is the base interface of all Value interfaces. Immutable subtypes are useful so that you can
+ * declare that a (final) field or elements of a container object are immutable. Method arguments should be a
+ * regular Value interface generally.
+ *
+ * You can use {@link #immutableValue()} method to get immutable subtypes.
+ *
+ *
+ * | MessagePack type | Subtype method | Immutable value type |
|---|
+ * | any types | {@link Value}.{@link Value#immutableValue()} | {@link ImmutableValue} |
+ * | Nil | {@link NilValue}.{@link NilValue#immutableValue()} | {@link ImmutableNilValue} |
+ * | Boolean | {@link BooleanValue}.{@link BooleanValue#immutableValue()} | {@link ImmutableBooleanValue} |
+ * | Integer | {@link IntegerValue}.{@link IntegerValue#immutableValue()} | {@link ImmutableIntegerValue} |
+ * | Float | {@link FloatValue}.{@link FloatValue#immutableValue()} | {@link ImmutableFloatValue} |
+ * | Integer or Float | {@link NumberValue}.{@link NumberValue#immutableValue()} | {@link ImmutableNumberValue} |
+ * | String or Binary | {@link RawValue}.{@link RawValue#immutableValue()} | {@link ImmutableRawValue} |
+ * | String | {@link StringValue}.{@link StringValue#immutableValue()} | {@link ImmutableStringValue} |
+ * | Binary | {@link BinaryValue}.{@link BinaryValue#immutableValue()} | {@link ImmutableBinaryValue} |
+ * | Array | {@link ArrayValue}.{@link ArrayValue#immutableValue()} | {@link ImmutableArrayValue} |
+ * | Map | {@link MapValue}.{@link MapValue#immutableValue()} | {@link ImmutableMapValue} |
+ * | Extension | {@link ExtensionValue}.{@link ExtensionValue#immutableValue()} | {@link ImmutableExtensionValue} |
+ *
+ *
+ * Converting to JSON
+ *
+ * {@link #toJson()} method returns JSON representation of a Value. See its documents for details.
+ *
+ * toString() also returns a string representation of a Value that is similar to JSON. However, unlike toJson() method,
+ * toString() may return a special format that is not be compatible with JSON when JSON doesn't support the type such
+ * as ExtensionValue.
*/
public interface Value
{
@@ -249,14 +298,16 @@ void writeTo(MessagePacker pk)
/**
* Returns json representation of this Value.
- *
+ *
* Following behavior is not configurable at this release and they might be changed at future releases:
*
- * * if a key of MapValue is not string, the key is converted to a string using toString method.
- * * NaN and Infinity of DoubleValue are converted to null.
- * * ExtensionValue is converted to a 2-element array where first element is a number and second element is the data encoded in hex.
- * * BinaryValue is converted to a string using UTF-8 encoding. Invalid byte sequence is replaced with U+FFFD replacement character.
- * * Invalid UTF-8 byte sequences in StringValue is replaced with U+FFFD replacement character
+ *
+ * - if a key of MapValue is not string, the key is converted to a string using toString method.
+ * - NaN and Infinity of DoubleValue are converted to null.
+ * - ExtensionValue is converted to a 2-element array where first element is a number and second element is the data encoded in hex.
+ * - BinaryValue is converted to a string using UTF-8 encoding. Invalid byte sequence is replaced with
U+FFFD replacement character.
+ * - Invalid UTF-8 byte sequences in StringValue is replaced with
U+FFFD replacement character
+ *
*/
String toJson();
}
diff --git a/msgpack-core/src/main/java/org/msgpack/value/ValueType.java b/msgpack-core/src/main/java/org/msgpack/value/ValueType.java
index 91b2a585f..b06478402 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/ValueType.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/ValueType.java
@@ -16,7 +16,13 @@
package org.msgpack.value;
/**
- * MessageTypeFamily is a group of {@link org.msgpack.core.MessageFormat}s
+ * Representation of MessagePack types.
+ *
+ * MessagePack uses hierarchical type system. Integer and Float are subypte of Number, Thus {@link #isNumberType()}
+ * returns true if type is Integer or Float. String and Binary are subtype of Raw. Thus {@link #isRawType()} returns
+ * true if type is String or Binary.
+ *
+ * @see org.msgpack.core.MessageFormat
*/
public enum ValueType
{