+ *
*/
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} created by {@link #newDefaultPacker(MessageBufferOutput)} and {@link #newDefaultBufferPacker()} methods.
*/
public static final PackerConfig DEFAULT_PACKER_CONFIG = new PackerConfig();
+
+ /**
+ * Configuration of a {@link MessageUnpacker} created by {@link #newDefaultUnpacker(MessageBufferInput)} methods.
+ */
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..423886fd8 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 also some complex 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
+ *
+ *
+ *
+ * Complex 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. You don't have to call anything at the end of
+ * 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. You don't have to call anything at the end of iteration.
+ *
+ *
+ * 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 underlaying 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 underlaying 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 underlaying 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 underlaying output.
+ *
+ * This method also calls flush method of the underlaying output after writing internal buffer.
+ */
+ @Override
public void flush()
throws IOException
{
@@ -162,6 +232,12 @@ public void flush()
out.flush();
}
+ /**
+ * Closes underlaying 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 underlaying 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 underlaying 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 underlaying 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 underlaying 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 v the integer to be written
+ * @return this
+ * @throws IOException when underlaying 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 underlaying 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 underlaying 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 bi the integer to be written
+ * @return this
+ * @throws IOException when underlaying 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 bi the integer to be written
+ * @return this
+ * @throws IOException when underlaying 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 underlaying 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 underlaying 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 underlaying 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 underlaying output throws IOException
+ */
public MessagePacker packValue(Value v)
throws IOException
{
@@ -626,6 +821,15 @@ public MessagePacker packValue(Value v)
return this;
}
+ /**
+ * Writes header of an Extension value.
+ *
+ * You will call {@link #writePayload(byte[])} or {@link #addPayload(byte[])} method to write body binary.
+ *
+ * @param len number of bytes of a payload binary to be written
+ * @return this
+ * @throws IOException when underlaying output throws IOException
+ */
public MessagePacker packExtensionTypeHeader(byte extType, int payloadLen)
throws IOException
{
@@ -669,6 +873,15 @@ else if (payloadLen < (1 << 16)) {
return this;
}
+ /**
+ * Writes header of a Binary value.
+ *
+ * You will 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 underlaying output throws IOException
+ */
public MessagePacker packBinaryHeader(int len)
throws IOException
{
@@ -684,6 +897,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 will 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 underlaying output throws IOException
+ */
public MessagePacker packRawStringHeader(int len)
throws IOException
{
@@ -703,12 +928,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 underlaying output throws IOException
*/
public MessagePacker writePayload(byte[] src)
throws IOException
@@ -717,14 +943,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 underlaying output throws IOException
*/
public MessagePacker writePayload(byte[] src, int off, int len)
throws IOException
@@ -743,13 +970,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} 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} 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 underlaying output throws IOException
*/
public MessagePacker addPayload(byte[] src)
throws IOException
@@ -758,15 +987,17 @@ 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} 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} 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 underlaying 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..0b9c575bf 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(unpack);
+ * }
+ * break;
+ * case MAP:
+ * length = unpacker.unpackMapHeader();
+ * for (int i = 0; i < length; i++) {
+ * readRecursively(unpack); // key
+ * readRecursively(unpack); // 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 you call {@link #unpackBinaryHeader} method to get length of the byte array. Then,
+ * you call {@link #readPayload(int)} or {@link #readPayloadAsReference(int)} method to read the the contents.
+ *
+ *
+ * To read an Array type, first you call {@link #unpackArrayHeader()} method to get number of elements. Then,
+ * you call unpacker methods for each element. You don't have to call anything at the end of iteration.
+ *
+ *
+ * To read a Map, first you call {@link #unpackMapHeader(int)} method to get number of pairs of the map. Then,
+ * for each pair, you call unpacker methods for key first, and then value. You will call unpacker methods twice
+ * as many time as the returned count. You don't have to call anything at the end of iteration.
+ *
*/
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 underlaying input.
+ *
+ * This method clears internal buffer, swaps the underlaying input with the new given input, then returns
+ * the old input.
*
- * @param in new input
- * @return the old resource
+ *
+ * This method doesn't close the old input.
+ *
+ * @param out new input
+ * @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 underlaying 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 underlaying input throws IOException
* @throws MessageInsufficientBufferException when the end of file reached, i.e. {@link #hasNext()} == false.
*/
public MessageFormat getNextFormat()
@@ -612,6 +715,13 @@ public Variable unpackValue(Variable var)
}
}
+ /**
+ * Reads a Nil byte.
+ *
+ * @return the read value
+ * @throws MessageTypeException when value is not MessagePack Nil type
+ * @throws IOException when underlaying input throws IOException
+ */
public void unpackNil()
throws IOException
{
@@ -622,6 +732,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 underlaying input throws IOException
+ */
public boolean unpackBoolean()
throws IOException
{
@@ -635,6 +752,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 underlaying input throws IOException
+ */
public byte unpackByte()
throws IOException
{
@@ -692,6 +819,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 underlaying input throws IOException
+ */
public short unpackShort()
throws IOException
{
@@ -743,6 +880,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 underlaying input throws IOException
+ */
public int unpackInt()
throws IOException
{
@@ -788,6 +935,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 underlaying input throws IOException
+ */
public long unpackLong()
throws IOException
{
@@ -832,6 +989,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 underlaying input throws IOException
+ */
public BigInteger unpackBigInteger()
throws IOException
{
@@ -879,6 +1043,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 underlaying input throws IOException
+ */
public float unpackFloat()
throws IOException
{
@@ -894,6 +1067,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 underlaying input throws IOException
+ */
public double unpackDouble()
throws IOException
{
@@ -1053,6 +1233,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 underlaying input throws IOException
+ */
public int unpackArrayHeader()
throws IOException
{
@@ -1073,6 +1265,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 underlaying input throws IOException
+ */
public int unpackMapHeader()
throws IOException
{
@@ -1198,6 +1403,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 underlaying input throws IOException
+ */
public int unpackBinaryHeader()
throws IOException
{
@@ -1243,6 +1464,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 underlaying input throws IOException
+ */
public void readPayload(ByteBuffer dst)
throws IOException
{
@@ -1261,12 +1492,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 underlaying 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 underlaying input throws IOException
+ */
public byte[] readPayload(int length)
throws IOException
{
@@ -1276,12 +1530,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 underlaying input throws IOException
*/
public void readPayload(byte[] dst, int off, int len)
throws IOException
@@ -1290,6 +1546,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 underlaying input throws IOException
+ */
public MessageBuffer readPayloadAsReference(int length)
throws IOException
{
@@ -1328,6 +1595,11 @@ private int readNextLength32()
return u32;
}
+ /**
+ * Closes underlaying input.
+ *
+ * @throws IOException
+ */
@Override
public void close()
throws IOException
From e5999106bb2c86caedad1c5120a949208163ec96 Mon Sep 17 00:00:00 2001
From: Sadayuki Furuhashi
Date: Mon, 24 Oct 2016 13:37:04 -0700
Subject: [PATCH 028/417] Adding JavaDoc - part 2
---
.../org/msgpack/core/MessageBufferPacker.java | 33 ++++++++-
.../java/org/msgpack/core/MessagePack.java | 6 +-
.../java/org/msgpack/core/MessagePacker.java | 6 +-
.../org/msgpack/core/MessageUnpacker.java | 4 +-
.../core/buffer/ArrayBufferOutput.java | 37 +++++++++-
.../msgpack/core/buffer/MessageBuffer.java | 23 ++++---
.../core/buffer/MessageBufferInput.java | 27 ++++++--
.../core/buffer/MessageBufferOutput.java | 34 +++++++---
.../java/org/msgpack/value/ArrayValue.java | 2 +-
.../java/org/msgpack/value/BinaryValue.java | 2 +-
.../java/org/msgpack/value/BooleanValue.java | 2 +-
.../org/msgpack/value/ExtensionValue.java | 2 +-
.../java/org/msgpack/value/FloatValue.java | 2 +-
.../msgpack/value/ImmutableArrayValue.java | 5 ++
.../msgpack/value/ImmutableBinaryValue.java | 7 ++
.../msgpack/value/ImmutableBooleanValue.java | 5 ++
.../value/ImmutableExtensionValue.java | 5 ++
.../msgpack/value/ImmutableFloatValue.java | 7 ++
.../msgpack/value/ImmutableIntegerValue.java | 5 ++
.../org/msgpack/value/ImmutableMapValue.java | 5 ++
.../org/msgpack/value/ImmutableNilValue.java | 3 +
.../msgpack/value/ImmutableNumberValue.java | 6 ++
.../org/msgpack/value/ImmutableRawValue.java | 8 +++
.../msgpack/value/ImmutableStringValue.java | 6 ++
.../org/msgpack/value/ImmutableValue.java | 3 +
.../java/org/msgpack/value/IntegerValue.java | 2 +-
.../main/java/org/msgpack/value/MapValue.java | 2 +-
.../main/java/org/msgpack/value/NilValue.java | 2 +-
.../java/org/msgpack/value/NumberValue.java | 2 +-
.../main/java/org/msgpack/value/RawValue.java | 2 +-
.../java/org/msgpack/value/StringValue.java | 2 +-
.../main/java/org/msgpack/value/Value.java | 67 ++++++++++++++++---
.../java/org/msgpack/value/ValueType.java | 8 ++-
33 files changed, 279 insertions(+), 53 deletions(-)
diff --git a/msgpack-core/src/main/java/org/msgpack/core/MessageBufferPacker.java b/msgpack-core/src/main/java/org/msgpack/core/MessageBufferPacker.java
index 7483010b2..3f6b732a1 100644
--- a/msgpack-core/src/main/java/org/msgpack/core/MessageBufferPacker.java
+++ b/msgpack-core/src/main/java/org/msgpack/core/MessageBufferPacker.java
@@ -23,7 +23,11 @@
import java.util.List;
/**
- * MessagePacker that is useful to produce byte array output
+ * MessagePacker that is useful to produce byte array output.
+ *
+ * This class allocates a new buffer instead of resizing the buffer when data doesn't fit in the initial capacity.
+ * This is faster than ByteArrayOutputStream especially when size of written bytes is large because resizing a buffer
+ * usually needs to copy contents of the buffer.
*/
public class MessageBufferPacker
extends MessagePacker
@@ -52,11 +56,22 @@ private ArrayBufferOutput getArrayBufferOut()
return (ArrayBufferOutput) out;
}
+ /**
+ * Clears the written data.
+ */
public void clear()
{
getArrayBufferOut().clear();
}
+ /**
+ * Gets copy of the written data as a byte array.
+ *
+ * If your application needs better performance and smaller memory consumption, you may prefer
+ * {@link #toMessageBuffer()} or {@link #toBufferList()} to avoid copying.
+ *
+ * @return the byte array
+ */
public byte[] toByteArray()
{
try {
@@ -69,6 +84,14 @@ public byte[] toByteArray()
return getArrayBufferOut().toByteArray();
}
+ /**
+ * Gets the written data as a MessageBuffer.
+ *
+ * Unlike {@link #toByteArray()}, this method omits copy of the contents if size of the written data is smaller
+ * than a single buffer capacity.
+ *
+ * @return the MessageBuffer instance
+ */
public MessageBuffer toMessageBuffer()
{
try {
@@ -81,6 +104,14 @@ public MessageBuffer toMessageBuffer()
return getArrayBufferOut().toMessageBuffer();
}
+ /**
+ * Returns the written data as a list of MessageBuffer.
+ *
+ * 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()
{
try {
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 2c84d2328..ed8b1e405 100644
--- a/msgpack-core/src/main/java/org/msgpack/core/MessagePack.java
+++ b/msgpack-core/src/main/java/org/msgpack/core/MessagePack.java
@@ -35,7 +35,7 @@
/**
* Convenience class to build packer and unpacker classes.
*
- * You may choose factory method as following
+ * You can select an appropriate factory method as following.
*
*
* Deserializing objects from binary:
@@ -70,12 +70,12 @@ public class MessagePack
public static final Charset UTF8 = Charset.forName("UTF-8");
/**
- * Configuration of a {@link MessagePacker} created by {@link #newDefaultPacker(MessageBufferOutput)} and {@link #newDefaultBufferPacker()} methods.
+ * Configuration of a {@link MessagePacker} used by {@link #newDefaultPacker(MessageBufferOutput)} and {@link #newDefaultBufferPacker()} methods.
*/
public static final PackerConfig DEFAULT_PACKER_CONFIG = new PackerConfig();
/**
- * Configuration of a {@link MessageUnpacker} created by {@link #newDefaultUnpacker(MessageBufferInput)} methods.
+ * Configuration of a {@link MessageUnpacker} used by {@link #newDefaultUnpacker(MessageBufferInput)} methods.
*/
public static final UnpackerConfig DEFAULT_UNPACKER_CONFIG = new UnpackerConfig();
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 423886fd8..0c61b4bd1 100644
--- a/msgpack-core/src/main/java/org/msgpack/core/MessagePacker.java
+++ b/msgpack-core/src/main/java/org/msgpack/core/MessagePacker.java
@@ -72,7 +72,7 @@
* an instance.
*
* This class provides following primitive methods to write MessagePack values. These primitive methods write
- * short bytes (1 to 7 bytes) to the internal buffer at once. There also some complex methods for convenience.
+ * short bytes (1 to 7 bytes) to the internal buffer at once. There are also some complex methods for convenience.
*
* Primitive methods:
*
@@ -110,13 +110,13 @@
*
*
* To write a List, Collection or array, first you call {@link #packArrayHeader(int)} method with the number of
- * elements. Then, you call packer methods for each element. You don't have to call anything at the end of
+ * elements. Then, you call packer methods for each element.
* iteration.
*
*
* To write a Map, first you call {@link #packMapHeader(int)} method with size of the map. Then, for each pair,
* you call packer methods for key first, and then value. You will call packer methods twice as many time as the
- * size of the map. You don't have to call anything at the end of iteration.
+ * size of the map.
*
*
* Note that packXxxHeader methods don't validate number of elements. You must call packer methods for correct
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 0b9c575bf..64d26a29f 100644
--- a/msgpack-core/src/main/java/org/msgpack/core/MessageUnpacker.java
+++ b/msgpack-core/src/main/java/org/msgpack/core/MessageUnpacker.java
@@ -139,12 +139,12 @@
*
*
* To read an Array type, first you call {@link #unpackArrayHeader()} method to get number of elements. Then,
- * you call unpacker methods for each element. You don't have to call anything at the end of iteration.
+ * you call unpacker methods for each element.
*
*
* To read a Map, first you call {@link #unpackMapHeader(int)} method to get number of pairs of the map. Then,
* for each pair, you call unpacker methods for key first, and then value. You will call unpacker methods twice
- * as many time as the returned count. You don't have to call anything at the end of iteration.
+ * as many time as the returned count.
*
*/
public class MessageUnpacker
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..df952a61a 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 size of the written data.
+ *
+ * @return number of bytes
+ */
public int getSize()
{
int size = 0;
@@ -48,6 +57,14 @@ public int getSize()
return size;
}
+ /**
+ * Gets copy of the written data as a byte array.
+ *
+ * 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..65cb6eba3 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 load
+ * unnecessary classes such as MessagePackBE. On big-endian CPU archtectures, implementation uses subclass that
+ * includes TypeProfile overhead but still faster than ByteBuffer. On JVMs older than Java 7 and JVMs without Unsafe
+ * API (such as Android), implementation falls back to a universal implementation that uses standard ByteBuffer class
+ * internally.
*/
public class MessageBuffer
{
@@ -69,8 +77,7 @@ public class MessageBuffer
try {
int major = Integer.parseInt(javaVersion.substring(0, dotPos));
int minor = Integer.parseInt(javaVersion.substring(dotPos + 1));
- isJavaAtLeast7 = major > 1 || (major == 1 && minor >= 7);
- }
+ isJavaAtLeast7 = major > 1 || (major == 1 && minor >= 7); }
catch (NumberFormatException e) {
e.printStackTrace(System.err);
}
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..2b19b9d99 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..9ae1b13dd 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 at least specified size of capacity.
+ *
+ * When this method is called twice, the previously returned buffer is no longer used. This method may be called
+ * twice without call of {@link writeBuffer(MessageBuffer)} in between. In this case, the buffer should be
+ * discarded without flushing it to the output.
*
* @param minimumSize the mimium required buffer size to allocate
- * @return
+ * @return the MessageBuffer instance with at least minimumSize bytes of capacity
* @throws IOException
*/
MessageBuffer next(int minimumSize)
throws IOException;
/**
- * Flushes the previously allocated buffer.
- * This method is not always called because next method also flushes previously allocated buffer.
- * This method is called when write method is called or application wants to control the timing of flush.
+ * Writes the previously allocated buffer.
+ *
+ * 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.
*
- * @param length the size of buffer to flush
+ * @param length the number of bytes to write
* @throws IOException
*/
void writeBuffer(int length)
@@ -63,7 +74,10 @@ void write(byte[] buffer, int offset, int length)
/**
* Writes an external payload data.
- * This buffer is given - this MessageBufferOutput owns the buffer and may modify contents of the buffer. Contents of this buffer won't be modified by the caller.
+ *
+ * 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
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..0ecd5bb36 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..2776eb78c 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.
*/
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..9ce62463f 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.
*
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.
+ *
+ *
+ * {@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..b06936697 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
{
From 462c2a04b796e10f3784639d48fa67d92eaf3fea Mon Sep 17 00:00:00 2001
From: Sadayuki Furuhashi
Date: Wed, 26 Oct 2016 10:12:56 -0700
Subject: [PATCH 029/417] docs: minor fixes
---
.../main/java/org/msgpack/core/buffer/MessageBuffer.java | 9 +++++----
.../org/msgpack/core/buffer/MessageBufferOutput.java | 4 ++--
2 files changed, 7 insertions(+), 6 deletions(-)
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 65cb6eba3..05eccbfce 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
@@ -38,9 +38,9 @@
*
* MessageBuffer class itself is optimized for little-endian CPU archtectures so that JVM (HotSpot) can take advantage
* of the fastest JIT format which skips TypeProfile checking. To ensure this performance, applications must not load
- * unnecessary classes such as MessagePackBE. On big-endian CPU archtectures, implementation uses subclass that
- * includes TypeProfile overhead but still faster than ByteBuffer. On JVMs older than Java 7 and JVMs without Unsafe
- * API (such as Android), implementation falls back to a universal implementation that uses standard ByteBuffer class
+ * 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
@@ -77,7 +77,8 @@ public class MessageBuffer
try {
int major = Integer.parseInt(javaVersion.substring(0, dotPos));
int minor = Integer.parseInt(javaVersion.substring(dotPos + 1));
- isJavaAtLeast7 = major > 1 || (major == 1 && minor >= 7); }
+ isJavaAtLeast7 = major > 1 || (major == 1 && minor >= 7);
+ }
catch (NumberFormatException e) {
e.printStackTrace(System.err);
}
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 9ae1b13dd..66a5c43ea 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
@@ -31,7 +31,7 @@ public interface MessageBufferOutput
/**
* Allocates the next buffer to write.
*
- * This method should return a MessageBuffer instance that has at least specified size of capacity.
+ * 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(MessageBuffer)} in between. In this case, the buffer should be
@@ -51,7 +51,7 @@ MessageBuffer next(int minimumSize)
* 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.
+ * without flushing it to the output when the next {@link next(int)} is called.
*
* @param length the number of bytes to write
* @throws IOException
From 629f8052027dc00ac0d564240a4c96604694a6f1 Mon Sep 17 00:00:00 2001
From: Sadayuki Furuhashi
Date: Wed, 26 Oct 2016 10:25:17 -0700
Subject: [PATCH 030/417] docs: fixes warnings
---
.../java/org/msgpack/core/MessagePacker.java | 22 ++++++++++---------
.../org/msgpack/core/MessageUnpacker.java | 7 +++---
.../msgpack/core/buffer/MessageBuffer.java | 15 ++++++++-----
.../core/buffer/MessageBufferInput.java | 2 +-
.../core/buffer/MessageBufferOutput.java | 10 ++++-----
.../msgpack/value/ImmutableNumberValue.java | 4 ++--
.../java/org/msgpack/value/IntegerValue.java | 3 ++-
.../main/java/org/msgpack/value/RawValue.java | 2 +-
.../java/org/msgpack/value/ValueType.java | 4 ++--
9 files changed, 36 insertions(+), 33 deletions(-)
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 0c61b4bd1..3a6627f71 100644
--- a/msgpack-core/src/main/java/org/msgpack/core/MessagePacker.java
+++ b/msgpack-core/src/main/java/org/msgpack/core/MessagePacker.java
@@ -447,7 +447,7 @@ else if (v < (1 << 7)) {
*
* This method writes an integer using the smallest format from the int format family.
*
- * @param v the integer to be written
+ * @param r the integer to be written
* @return this
* @throws IOException when underlaying output throws IOException
*/
@@ -570,7 +570,7 @@ else if (bi.bitLength() == 64 && bi.signum() == 1) {
*
* This method writes a float value using float format family.
*
- * @param bi the integer to be written
+ * @param v the value to be written
* @return this
* @throws IOException when underlaying output throws IOException
*/
@@ -587,7 +587,7 @@ public MessagePacker packFloat(float v)
*
* This method writes a float value using float format family.
*
- * @param bi the integer to be written
+ * @param v the value to be written
* @return this
* @throws IOException when underlaying output throws IOException
*/
@@ -826,7 +826,8 @@ public MessagePacker packValue(Value v)
*
* You will call {@link #writePayload(byte[])} or {@link #addPayload(byte[])} method to write body binary.
*
- * @param len number of bytes of a payload binary to be written
+ * @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 underlaying output throws IOException
*/
@@ -972,9 +973,9 @@ public MessagePacker writePayload(byte[] src, int off, int len)
/**
* Writes a byte array to the output.
*
- * Unlike {@link #writePayload} 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} method but caller must not modify the byte array after calling this method.
+ * 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
@@ -989,9 +990,10 @@ public MessagePacker addPayload(byte[] src)
/**
* Writes a byte array to the output.
*
- * Unlike {@link #writePayload} 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} method but caller must not modify the byte array after calling this method.
+ * 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
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 64d26a29f..99a42a5fb 100644
--- a/msgpack-core/src/main/java/org/msgpack/core/MessageUnpacker.java
+++ b/msgpack-core/src/main/java/org/msgpack/core/MessageUnpacker.java
@@ -47,7 +47,7 @@
*
* 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
+ * 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
@@ -142,7 +142,7 @@
* you call unpacker methods for each element.
*
*
- * To read a Map, first you call {@link #unpackMapHeader(int)} method to get number of pairs of the map. Then,
+ * To read a Map, first you call {@link #unpackMapHeader()} method to get number of pairs of the map. Then,
* for each pair, you call unpacker methods for key first, and then value. You will call unpacker methods twice
* as many time as the returned count.
*
@@ -228,7 +228,7 @@ protected MessageUnpacker(MessageBufferInput in, MessagePack.UnpackerConfig conf
*
* This method doesn't close the old input.
*
- * @param out new input
+ * @param in new input
* @return the old input
* @throws IOException never happens unless a subclass overrides this method
* @throws NullPointerException the given input is null
@@ -718,7 +718,6 @@ public Variable unpackValue(Variable var)
/**
* Reads a Nil byte.
*
- * @return the read value
* @throws MessageTypeException when value is not MessagePack Nil type
* @throws IOException when underlaying input throws IOException
*/
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 05eccbfce..730cd245b 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
@@ -33,7 +33,7 @@
* 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
+ * 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
@@ -213,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 the new MessageBuffer
*
*/
public static MessageBuffer wrap(byte[] array)
@@ -231,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 the new MessageBuffer
*
*/
public static MessageBuffer wrap(byte[] array, int offset, int length)
@@ -249,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 the new MessageBuffer
*
*/
public static MessageBuffer wrap(ByteBuffer bb)
@@ -381,9 +381,12 @@ protected MessageBuffer(Object base, long address, int length)
}
/**
- * byte size of the buffer
+ * Gets 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 2b19b9d99..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
@@ -43,7 +43,7 @@ MessageBuffer next()
/**
* Closes the input.
*
- * When this method is called, the buffer previously returned from {@link next()} method is no longer used.
+ * 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.
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 66a5c43ea..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
@@ -34,7 +34,7 @@ public interface MessageBufferOutput
* 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(MessageBuffer)} in between. In this case, the buffer should be
+ * 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
@@ -47,11 +47,11 @@ MessageBuffer next(int minimumSize)
/**
* Writes the previously allocated buffer.
*
- * This method should write the buffer previously returned from {@link next(int)} method until specified number of
+ * 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.
+ * 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 number of bytes to write
* @throws IOException
@@ -66,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)
@@ -82,7 +81,6 @@ void write(byte[] buffer, int offset, int length)
* @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/ImmutableNumberValue.java b/msgpack-core/src/main/java/org/msgpack/value/ImmutableNumberValue.java
index 0ecd5bb36..a3b984af6 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/ImmutableNumberValue.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/ImmutableNumberValue.java
@@ -18,8 +18,8 @@
/**
* 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
+ * @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/IntegerValue.java b/msgpack-core/src/main/java/org/msgpack/value/IntegerValue.java
index 2776eb78c..b23378261 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/IntegerValue.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/IntegerValue.java
@@ -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/RawValue.java b/msgpack-core/src/main/java/org/msgpack/value/RawValue.java
index 9ce62463f..ba327a835 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/RawValue.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/RawValue.java
@@ -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/ValueType.java b/msgpack-core/src/main/java/org/msgpack/value/ValueType.java
index b06936697..b06478402 100644
--- a/msgpack-core/src/main/java/org/msgpack/value/ValueType.java
+++ b/msgpack-core/src/main/java/org/msgpack/value/ValueType.java
@@ -18,8 +18,8 @@
/**
* 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
+ * 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
From c0357ddb41ca8fc18bed91148b21c444c6782f04 Mon Sep 17 00:00:00 2001
From: "Taro L. Saito"
Date: Thu, 3 Nov 2016 23:29:01 -0700
Subject: [PATCH 031/417] Upgrade to sbt 0.13.13
---
project/build.properties | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/project/build.properties b/project/build.properties
index 02cb92b32..24be09b28 100755
--- a/project/build.properties
+++ b/project/build.properties
@@ -1,2 +1,2 @@
-sbt.version=0.13.9
+sbt.version=0.13.13
From 49ed7abfde095ec46ff93ef5440e9320cefa4967 Mon Sep 17 00:00:00 2001
From: Sadayuki Furuhashi
Date: Sat, 26 Nov 2016 16:30:10 -0800
Subject: [PATCH 032/417] applied review comments to javadoc
---
.../org/msgpack/core/MessageBufferPacker.java | 6 +-
.../java/org/msgpack/core/MessagePacker.java | 62 +++++++++----------
.../org/msgpack/core/MessageUnpacker.java | 62 +++++++++----------
.../core/buffer/ArrayBufferOutput.java | 4 +-
.../msgpack/core/buffer/MessageBuffer.java | 12 ++--
5 files changed, 73 insertions(+), 73 deletions(-)
diff --git a/msgpack-core/src/main/java/org/msgpack/core/MessageBufferPacker.java b/msgpack-core/src/main/java/org/msgpack/core/MessageBufferPacker.java
index 3f6b732a1..38962dbe2 100644
--- a/msgpack-core/src/main/java/org/msgpack/core/MessageBufferPacker.java
+++ b/msgpack-core/src/main/java/org/msgpack/core/MessageBufferPacker.java
@@ -78,7 +78,7 @@ public byte[] toByteArray()
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().toByteArray();
@@ -98,7 +98,7 @@ public MessageBuffer toMessageBuffer()
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().toMessageBuffer();
@@ -118,7 +118,7 @@ public List toBufferList()
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/MessagePacker.java b/msgpack-core/src/main/java/org/msgpack/core/MessagePacker.java
index 3a6627f71..1cd9a9801 100644
--- a/msgpack-core/src/main/java/org/msgpack/core/MessagePacker.java
+++ b/msgpack-core/src/main/java/org/msgpack/core/MessagePacker.java
@@ -72,7 +72,7 @@
* an instance.
*
* 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 complex methods for convenience.
+ * short bytes (1 to 7 bytes) to the internal buffer at once. There are also some utility methods for convenience.
*
* This method flushes current internal buffer to the output, swaps it with the new given output, then returns
* the old output.
@@ -183,7 +183,7 @@ protected MessagePacker(MessageBufferOutput out, MessagePack.PackerConfig config
*
* @param out new output
* @return the old output
- * @throws IOException when underlaying output throws IOException
+ * @throws IOException when underlying output throws IOException
* @throws NullPointerException the given output is null
*/
public MessageBufferOutput reset(MessageBufferOutput out)
@@ -206,7 +206,7 @@ public MessageBufferOutput reset(MessageBufferOutput out)
/**
* Returns total number of written bytes.
*
- * This method returns total of amount of data flushed to the underlaying output plus size of current
+ * This method returns total of amount of data flushed to the underlying output plus size of current
* internal buffer.
*
*
@@ -218,9 +218,9 @@ public long getTotalWrittenBytes()
}
/**
- * Flushes internal buffer to the underlaying output.
+ * Flushes internal buffer to the underlying output.
*
- * This method also calls flush method of the underlaying output after writing internal buffer.
+ * This method also calls flush method of the underlying output after writing internal buffer.
*/
@Override
public void flush()
@@ -233,7 +233,7 @@ public void flush()
}
/**
- * Closes underlaying output.
+ * Closes underlying output.
*
* This method flushes internal buffer before closing.
*/
@@ -360,7 +360,7 @@ private void writeLong(long v)
* This method writes a nil byte.
*
* @return this
- * @throws IOException when underlaying output throws IOException
+ * @throws IOException when underlying output throws IOException
*/
public MessagePacker packNil()
throws IOException
@@ -375,7 +375,7 @@ public MessagePacker packNil()
* This method writes a true byte or a false byte.
*
* @return this
- * @throws IOException when underlaying output throws IOException
+ * @throws IOException when underlying output throws IOException
*/
public MessagePacker packBoolean(boolean b)
throws IOException
@@ -392,7 +392,7 @@ public MessagePacker packBoolean(boolean b)
*
* @param b the integer to be written
* @return this
- * @throws IOException when underlaying output throws IOException
+ * @throws IOException when underlying output throws IOException
*/
public MessagePacker packByte(byte b)
throws IOException
@@ -414,7 +414,7 @@ public MessagePacker packByte(byte b)
*
* @param v the integer to be written
* @return this
- * @throws IOException when underlaying output throws IOException
+ * @throws IOException when underlying output throws IOException
*/
public MessagePacker packShort(short v)
throws IOException
@@ -449,7 +449,7 @@ else if (v < (1 << 7)) {
*
* @param r the integer to be written
* @return this
- * @throws IOException when underlaying output throws IOException
+ * @throws IOException when underlying output throws IOException
*/
public MessagePacker packInt(int r)
throws IOException
@@ -491,7 +491,7 @@ else if (r < (1 << 16)) {
*
* @param v the integer to be written
* @return this
- * @throws IOException when underlaying output throws IOException
+ * @throws IOException when underlying output throws IOException
*/
public MessagePacker packLong(long v)
throws IOException
@@ -547,7 +547,7 @@ else if (v < (1 << 7)) {
*
* @param bi the integer to be written
* @return this
- * @throws IOException when underlaying output throws IOException
+ * @throws IOException when underlying output throws IOException
*/
public MessagePacker packBigInteger(BigInteger bi)
throws IOException
@@ -572,7 +572,7 @@ else if (bi.bitLength() == 64 && bi.signum() == 1) {
*
* @param v the value to be written
* @return this
- * @throws IOException when underlaying output throws IOException
+ * @throws IOException when underlying output throws IOException
*/
public MessagePacker packFloat(float v)
throws IOException
@@ -589,7 +589,7 @@ public MessagePacker packFloat(float v)
*
* @param v the value to be written
* @return this
- * @throws IOException when underlaying output throws IOException
+ * @throws IOException when underlying output throws IOException
*/
public MessagePacker packDouble(double v)
throws IOException
@@ -666,7 +666,7 @@ private int encodeStringToBufferAt(int pos, String s)
*
* @param s the string to be written
* @return this
- * @throws IOException when underlaying output throws IOException
+ * @throws IOException when underlying output throws IOException
*/
public MessagePacker packString(String s)
throws IOException
@@ -755,7 +755,7 @@ else if (s.length() < (1 << 16)) {
*
* @param arraySize number of elements to be written
* @return this
- * @throws IOException when underlaying output throws IOException
+ * @throws IOException when underlying output throws IOException
*/
public MessagePacker packArrayHeader(int arraySize)
throws IOException
@@ -786,7 +786,7 @@ else if (arraySize < (1 << 16)) {
*
* @param mapSize number of pairs to be written
* @return this
- * @throws IOException when underlaying output throws IOException
+ * @throws IOException when underlying output throws IOException
*/
public MessagePacker packMapHeader(int mapSize)
throws IOException
@@ -812,7 +812,7 @@ else if (mapSize < (1 << 16)) {
*
* @param v the value to be written
* @return this
- * @throws IOException when underlaying output throws IOException
+ * @throws IOException when underlying output throws IOException
*/
public MessagePacker packValue(Value v)
throws IOException
@@ -824,12 +824,12 @@ public MessagePacker packValue(Value v)
/**
* Writes header of an Extension value.
*
- * You will call {@link #writePayload(byte[])} or {@link #addPayload(byte[])} method to write body binary.
+ * 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 underlaying output throws IOException
+ * @throws IOException when underlying output throws IOException
*/
public MessagePacker packExtensionTypeHeader(byte extType, int payloadLen)
throws IOException
@@ -877,11 +877,11 @@ else if (payloadLen < (1 << 16)) {
/**
* Writes header of a Binary value.
*
- * You will call {@link #writePayload(byte[])} or {@link #addPayload(byte[])} method to write body binary.
+ * 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 underlaying output throws IOException
+ * @throws IOException when underlying output throws IOException
*/
public MessagePacker packBinaryHeader(int len)
throws IOException
@@ -903,12 +903,12 @@ else if (len < (1 << 16)) {
*
* Length must be number of bytes of a string in UTF-8 encoding.
*
- * You will call {@link #writePayload(byte[])} or {@link #addPayload(byte[])} method to write body of the
+ * 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 underlaying output throws IOException
+ * @throws IOException when underlying output throws IOException
*/
public MessagePacker packRawStringHeader(int len)
throws IOException
@@ -935,7 +935,7 @@ else if (len < (1 << 16)) {
*
* @param src the data to add
* @return this
- * @throws IOException when underlaying output throws IOException
+ * @throws IOException when underlying output throws IOException
*/
public MessagePacker writePayload(byte[] src)
throws IOException
@@ -952,7 +952,7 @@ public MessagePacker writePayload(byte[] src)
* @param off the start offset in the data
* @param len the number of bytes to add
* @return this
- * @throws IOException when underlaying output throws IOException
+ * @throws IOException when underlying output throws IOException
*/
public MessagePacker writePayload(byte[] src, int off, int len)
throws IOException
@@ -979,7 +979,7 @@ public MessagePacker writePayload(byte[] src, int off, int len)
*
* @param src the data to add
* @return this
- * @throws IOException when underlaying output throws IOException
+ * @throws IOException when underlying output throws IOException
*/
public MessagePacker addPayload(byte[] src)
throws IOException
@@ -999,7 +999,7 @@ public MessagePacker addPayload(byte[] src)
* @param off the start offset in the data
* @param len the number of bytes to add
* @return this
- * @throws IOException when underlaying output 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 99a42a5fb..82ed9d15f 100644
--- a/msgpack-core/src/main/java/org/msgpack/core/MessageUnpacker.java
+++ b/msgpack-core/src/main/java/org/msgpack/core/MessageUnpacker.java
@@ -93,14 +93,14 @@
* case ARRAY:
* length = unpacker.unpackArrayHeader();
* for (int i = 0; i < length; i++) {
- * readRecursively(unpack);
+ * readRecursively(unpacker);
* }
* break;
* case MAP:
* length = unpacker.unpackMapHeader();
* for (int i = 0; i < length; i++) {
- * readRecursively(unpack); // key
- * readRecursively(unpack); // value
+ * readRecursively(unpacker); // key
+ * readRecursively(unpacker); // value
* }
* break;
* case EXTENSION:
@@ -134,16 +134,16 @@
*
*
*
- * To read a byte array, first you call {@link #unpackBinaryHeader} method to get length of the byte array. Then,
- * you call {@link #readPayload(int)} or {@link #readPayloadAsReference(int)} method to read the the contents.
+ * 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 you call {@link #unpackArrayHeader()} method to get number of elements. Then,
- * you call unpacker methods for each element.
+ * 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 you call {@link #unpackMapHeader()} method to get number of pairs of the map. Then,
- * for each pair, you call unpacker methods for key first, and then value. You will call unpacker methods twice
+ * 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.
*
*/
@@ -220,9 +220,9 @@ protected MessageUnpacker(MessageBufferInput in, MessagePack.UnpackerConfig conf
}
/**
- * Replaces underlaying input.
+ * Replaces underlying input.
*
- * This method clears internal buffer, swaps the underlaying input with the new given input, then returns
+ * This method clears internal buffer, swaps the underlying input with the new given input, then returns
* the old input.
*
*
@@ -252,7 +252,7 @@ public MessageBufferInput reset(MessageBufferInput in)
/**
* Returns total number of read bytes.
*
- * This method returns total of amount of data consumed from the underlaying input minus size of data
+ * 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.
*
*
@@ -383,7 +383,7 @@ private boolean ensureBuffer()
* {@link #hasNext()} returns true.
*
* @return the next MessageFormat
- * @throws IOException when underlaying input throws IOException
+ * @throws IOException when underlying input throws IOException
* @throws MessageInsufficientBufferException when the end of file reached, i.e. {@link #hasNext()} == false.
*/
public MessageFormat getNextFormat()
@@ -719,7 +719,7 @@ public Variable unpackValue(Variable var)
* Reads a Nil byte.
*
* @throws MessageTypeException when value is not MessagePack Nil type
- * @throws IOException when underlaying input throws IOException
+ * @throws IOException when underlying input throws IOException
*/
public void unpackNil()
throws IOException
@@ -736,7 +736,7 @@ public void unpackNil()
*
* @return the read value
* @throws MessageTypeException when value is not MessagePack Boolean type
- * @throws IOException when underlaying input throws IOException
+ * @throws IOException when underlying input throws IOException
*/
public boolean unpackBoolean()
throws IOException
@@ -759,7 +759,7 @@ else if (b == Code.TRUE) {
* @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 underlaying input throws IOException
+ * @throws IOException when underlying input throws IOException
*/
public byte unpackByte()
throws IOException
@@ -826,7 +826,7 @@ public byte unpackByte()
* @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 underlaying input throws IOException
+ * @throws IOException when underlying input throws IOException
*/
public short unpackShort()
throws IOException
@@ -887,7 +887,7 @@ public short unpackShort()
* @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 underlaying input throws IOException
+ * @throws IOException when underlying input throws IOException
*/
public int unpackInt()
throws IOException
@@ -942,7 +942,7 @@ public int unpackInt()
* @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 underlaying input throws IOException
+ * @throws IOException when underlying input throws IOException
*/
public long unpackLong()
throws IOException
@@ -993,7 +993,7 @@ public long unpackLong()
*
* @return the read value
* @throws MessageTypeException when value is not MessagePack Integer type
- * @throws IOException when underlaying input throws IOException
+ * @throws IOException when underlying input throws IOException
*/
public BigInteger unpackBigInteger()
throws IOException
@@ -1049,7 +1049,7 @@ public BigInteger unpackBigInteger()
*
* @return the read value
* @throws MessageTypeException when value is not MessagePack Float type
- * @throws IOException when underlaying input throws IOException
+ * @throws IOException when underlying input throws IOException
*/
public float unpackFloat()
throws IOException
@@ -1071,7 +1071,7 @@ public float unpackFloat()
*
* @return the read value
* @throws MessageTypeException when value is not MessagePack Float type
- * @throws IOException when underlaying input throws IOException
+ * @throws IOException when underlying input throws IOException
*/
public double unpackDouble()
throws IOException
@@ -1242,7 +1242,7 @@ private String decodeStringFastPath(int length)
* @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 underlaying input throws IOException
+ * @throws IOException when underlying input throws IOException
*/
public int unpackArrayHeader()
throws IOException
@@ -1275,7 +1275,7 @@ public int unpackArrayHeader()
* @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 underlaying input throws IOException
+ * @throws IOException when underlying input throws IOException
*/
public int unpackMapHeader()
throws IOException
@@ -1416,7 +1416,7 @@ public int unpackRawStringHeader()
* @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 underlaying input throws IOException
+ * @throws IOException when underlying input throws IOException
*/
public int unpackBinaryHeader()
throws IOException
@@ -1471,7 +1471,7 @@ private void skipPayload(int numBytes)
* until ByteBuffer.remaining() returns 0.
*
* @param dst the byte buffer into which the data is read
- * @throws IOException when underlaying input throws IOException
+ * @throws IOException when underlying input throws IOException
*/
public void readPayload(ByteBuffer dst)
throws IOException
@@ -1500,7 +1500,7 @@ public void readPayload(ByteBuffer dst)
* This method is equivalent to readPayload(dst, 0, dst.length).
*
* @param dst the byte array into which the data is read
- * @throws IOException when underlaying input throws IOException
+ * @throws IOException when underlying input throws IOException
*/
public void readPayload(byte[] dst)
throws IOException
@@ -1518,7 +1518,7 @@ public void readPayload(byte[] dst)
*
* @param length number of bytes to be read
* @return the new byte array
- * @throws IOException when underlaying input throws IOException
+ * @throws IOException when underlying input throws IOException
*/
public byte[] readPayload(int length)
throws IOException
@@ -1536,7 +1536,7 @@ public byte[] readPayload(int length)
* @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 when underlaying input throws IOException
+ * @throws IOException when underlying input throws IOException
*/
public void readPayload(byte[] dst, int off, int len)
throws IOException
@@ -1554,7 +1554,7 @@ public void readPayload(byte[] dst, int off, int len)
* allocated buffer if reference is not applicable.
*
* @param length number of bytes to be read
- * @throws IOException when underlaying input throws IOException
+ * @throws IOException when underlying input throws IOException
*/
public MessageBuffer readPayloadAsReference(int length)
throws IOException
@@ -1595,7 +1595,7 @@ private int readNextLength32()
}
/**
- * Closes underlaying input.
+ * Closes underlying input.
*
* @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 df952a61a..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
@@ -44,7 +44,7 @@ public ArrayBufferOutput(int bufferSize)
}
/**
- * Gets size of the written data.
+ * Gets the size of the written data.
*
* @return number of bytes
*/
@@ -58,7 +58,7 @@ public int getSize()
}
/**
- * Gets copy of the written data as a byte array.
+ * 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.
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 730cd245b..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
@@ -37,7 +37,7 @@
* 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 load
+ * 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
@@ -213,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 the new MessageBuffer
+ * @return a new MessageBuffer that wraps the given byte array
*
*/
public static MessageBuffer wrap(byte[] array)
@@ -231,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 the new MessageBuffer
+ * @return a new MessageBuffer that wraps the given byte array
*
*/
public static MessageBuffer wrap(byte[] array, int offset, int length)
@@ -249,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 the new MessageBuffer
+ * @return a new MessageBuffer that wraps the given byte array
*
*/
public static MessageBuffer wrap(ByteBuffer bb)
@@ -304,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) {
@@ -381,7 +381,7 @@ protected MessageBuffer(Object base, long address, int length)
}
/**
- * Gets size of the buffer.
+ * Gets the size of the buffer.
*
* MessageBuffer doesn't have limit unlike ByteBuffer. Instead, you can use {@link #slice(int, int)} to get a
* part of the buffer.
From 3a6ea2603dbf5a87129e658344194345808852bd Mon Sep 17 00:00:00 2001
From: xuwei-k <6b656e6a69@gmail.com>
Date: Sun, 27 Nov 2016 11:56:15 +0900
Subject: [PATCH 033/417] fix warning in build.sbt
```
/home/travis/build/msgpack/msgpack-java/build.sbt:59: warning: `<<=` operator is deprecated. Use `key := { x.value }` or `key ~= (old => { newValue })`.
See http://www.scala-sbt.org/0.13/docs/Migrating-from-sbt-012x.html
compile <<= (compile in Compile) dependsOn (jcheckStyle in Compile),
^
/home/travis/build/msgpack/msgpack-java/build.sbt:60: warning: `<<=` operator is deprecated. Use `key := { x.value }` or `key ~= (old => { newValue })`.
See http://www.scala-sbt.org/0.13/docs/Migrating-from-sbt-012x.html
compile <<= (compile in Test) dependsOn (jcheckStyle in Test)
^
```
https://travis-ci.org/msgpack/msgpack-java/jobs/179129836#L277
---
build.sbt | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/build.sbt b/build.sbt
index 257e6b28f..ccb366cae 100644
--- a/build.sbt
+++ b/build.sbt
@@ -56,8 +56,8 @@ val buildSettings = findbugsSettings ++ jacoco.settings ++ osgiSettings ++ Seq[S
jcheckStyleConfig := "facebook",
// Run jcheckstyle both for main and test codes
- compile <<= (compile in Compile) dependsOn (jcheckStyle in Compile),
- compile <<= (compile in Test) dependsOn (jcheckStyle in Test)
+ (compile in Compile) := ((compile in Compile) dependsOn (jcheckStyle in Compile)).value,
+ (compile in Test) := ((compile in Test) dependsOn (jcheckStyle in Test)).value
)
val junitInterface = "com.novocode" % "junit-interface" % "0.11" % "test"
From 8ec7368b9a6eabf310ad6e2e9f97788e7d04614c Mon Sep 17 00:00:00 2001
From: "Taro L. Saito"
Date: Mon, 12 Dec 2016 17:36:46 -0800
Subject: [PATCH 034/417] Fix #403: Add authors
---
AUTHORS | 5 +++++
1 file changed, 5 insertions(+)
create mode 100644 AUTHORS
diff --git a/AUTHORS b/AUTHORS
new file mode 100644
index 000000000..3401c83b9
--- /dev/null
+++ b/AUTHORS
@@ -0,0 +1,5 @@
+FURUHASHI Sadayuki
+Muga Nishizawa
+Taro L. Saito
+Mitsunori Komatsu
+OZAWA Tsuyoshi
From f669234af982314b39d1c9af9655a1d6dd0fa21d Mon Sep 17 00:00:00 2001
From: Sadayuki Furuhashi
Date: Mon, 12 Dec 2016 22:14:48 -0800
Subject: [PATCH 035/417] AUTHORS: updated
---
AUTHORS | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/AUTHORS b/AUTHORS
index 3401c83b9..cfcf3a089 100644
--- a/AUTHORS
+++ b/AUTHORS
@@ -1,4 +1,4 @@
-FURUHASHI Sadayuki
+Sadayuki Furuhashi
Muga Nishizawa
Taro L. Saito
Mitsunori Komatsu
From a4b0f3f922952169b30dfd6812c584c8100181ae Mon Sep 17 00:00:00 2001
From: Mitsunori Komatsu
Date: Thu, 12 Jan 2017 00:33:16 +0900
Subject: [PATCH 036/417] Override MessagePackExtensionType#equals and hashCode
Also, added an unit test of deserialization of
MessagePackExtensionType based on type.
---
.../dataformat/MessagePackExtensionType.java | 27 +++++++++
.../dataformat/MessagePackParserTest.java | 56 +++++++++++++++++++
2 files changed, 83 insertions(+)
diff --git a/msgpack-jackson/src/main/java/org/msgpack/jackson/dataformat/MessagePackExtensionType.java b/msgpack-jackson/src/main/java/org/msgpack/jackson/dataformat/MessagePackExtensionType.java
index 1906757f5..00b4f7de8 100644
--- a/msgpack-jackson/src/main/java/org/msgpack/jackson/dataformat/MessagePackExtensionType.java
+++ b/msgpack-jackson/src/main/java/org/msgpack/jackson/dataformat/MessagePackExtensionType.java
@@ -7,6 +7,7 @@
import com.fasterxml.jackson.databind.annotation.JsonSerialize;
import java.io.IOException;
+import java.util.Arrays;
@JsonSerialize(using = MessagePackExtensionType.Serializer.class)
public class MessagePackExtensionType
@@ -30,6 +31,32 @@ public byte[] getData()
return data;
}
+ @Override
+ public boolean equals(Object o)
+ {
+ if (this == o) {
+ return true;
+ }
+ if (!(o instanceof MessagePackExtensionType)) {
+ return false;
+ }
+
+ MessagePackExtensionType that = (MessagePackExtensionType) o;
+
+ if (type != that.type) {
+ return false;
+ }
+ return Arrays.equals(data, that.data);
+ }
+
+ @Override
+ public int hashCode()
+ {
+ int result = (int) type;
+ result = 31 * result + Arrays.hashCode(data);
+ return result;
+ }
+
public static class Serializer extends JsonSerializer
{
@Override
diff --git a/msgpack-jackson/src/test/java/org/msgpack/jackson/dataformat/MessagePackParserTest.java b/msgpack-jackson/src/test/java/org/msgpack/jackson/dataformat/MessagePackParserTest.java
index 112390598..8bab30926 100644
--- a/msgpack-jackson/src/test/java/org/msgpack/jackson/dataformat/MessagePackParserTest.java
+++ b/msgpack-jackson/src/test/java/org/msgpack/jackson/dataformat/MessagePackParserTest.java
@@ -23,11 +23,13 @@
import com.fasterxml.jackson.databind.DeserializationFeature;
import com.fasterxml.jackson.databind.KeyDeserializer;
import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.deser.std.UntypedObjectDeserializer;
import com.fasterxml.jackson.databind.module.SimpleModule;
import org.junit.Test;
import org.msgpack.core.MessagePack;
import org.msgpack.core.MessagePacker;
+import java.io.ByteArrayInputStream;
import java.io.ByteArrayOutputStream;
import java.io.File;
import java.io.FileInputStream;
@@ -41,6 +43,9 @@
import java.util.List;
import java.util.Map;
+import static org.hamcrest.MatcherAssert.assertThat;
+import static org.hamcrest.core.Is.is;
+import static org.hamcrest.core.IsInstanceOf.instanceOf;
import static org.junit.Assert.assertArrayEquals;
import static org.junit.Assert.assertEquals;
import static org.junit.Assert.assertNull;
@@ -671,4 +676,55 @@ public Object deserializeKey(String key, DeserializationContext ctxt)
assertEquals((Integer) 2, map.get(true));
assertEquals((Integer) 3, map.get(false));
}
+
+ public static class MyExtTypeDeserializer extends UntypedObjectDeserializer.Vanilla
+ {
+ @Override
+ public Object deserialize(JsonParser p, DeserializationContext ctxt)
+ throws IOException
+ {
+ Object obj = super.deserialize(p, ctxt);
+ if (obj instanceof MessagePackExtensionType) {
+ MessagePackExtensionType ext = (MessagePackExtensionType) obj;
+ if (ext.getType() == 31) {
+ if (Arrays.equals(ext.getData(), new byte[] {(byte) 0xCA, (byte) 0xFE, (byte) 0xBA, (byte) 0xBE})) {
+ return "Java";
+ }
+ return "Not Java";
+ }
+ }
+ return obj;
+ }
+ }
+
+ @Test
+ public void customDeserializationForExtType()
+ throws IOException
+ {
+ ByteArrayOutputStream out = new ByteArrayOutputStream();
+ MessagePacker packer = MessagePack.newDefaultPacker(out);
+ packer.packArrayHeader(4);
+ packer.packString("foo bar");
+ packer.packExtensionTypeHeader((byte) 31, 4);
+ packer.addPayload(new byte[] {(byte) 0xCA, (byte) 0xFE, (byte) 0xBA, (byte) 0xBE});
+ packer.packArrayHeader(1);
+ packer.packInt(42);
+ packer.packExtensionTypeHeader((byte) 32, 2);
+ packer.addPayload(new byte[] {(byte) 0xAB, (byte) 0xCD});
+ packer.close();
+
+ ObjectMapper objectMapper = new ObjectMapper(new MessagePackFactory());
+ SimpleModule module = new SimpleModule("MyModule").addDeserializer(Object.class, new MyExtTypeDeserializer());
+ objectMapper.registerModule(module);
+
+ List