msgpack/msgpack-java — pull request #109 by xerial (2014-06-16 17:02:58+00:00)
Title: msgpack-value v07 API

I implemented msgpack-value API for v07. Here is an overview of the API:
![powerpoint___-__2014-06-17-msgpack-value_pptx_](https://cloud.githubusercontent.com/assets/57538/3289845/d58ad0ba-f570-11e3-8a09-3290e1a053ce.png)

msgpack-value has the following components:
- __Cursor__: traverses message-packed values. The user calls `hasNext()`, then `next() : Value` or `nextRef() : ValueRef` to retrieve values.
- __Value__: Immutable representation of a message-packed value.
- __NumberValue__ : An interface for Integer and Float values. It provides number conversion methods (w/ or w/o truncation/rounding) and value range checkers.
- __ValueRef__: A reference to a message-packed value. This reference is valid until `cursor.next()/nextRef()` is called. To make it immutable, call `ValueRef.toValue() : Value`, which creates a copy of the referenced value.
- __ValueHolder__: An implementation of `ValueRef`, a sort of union (in C language) that can hold any type of a value. This is useful to reduce the cost of Value instance creation. MessageUnpacker directly feeds a value into the holder via `unpackValue(ValueHolder)` method.

**Miscellaneous notes**:

- `org.msgpack.value` is now within the msgpack-core project because `Cursor` and `ValueHolder` need to interact with MessageUnpacker, and it makes difficult to separate msgpack-core and msgpack-value projects. For example, to switch the holder to use (e.g., long? or BigInteger?), adding `unpackValue(ValueHolder)` to the unpacker, then let it choose the target holder is the most straightforward way. And also ValueHolder can be used as an implementation of ValueRef. Moving `org.msgpack.value` package within msgpack-core project makes simple these interactions.
- Traversing 10,000 binary values using `Cursor.nextRef` is about 2.7 times faster than using `Cursor.next` (returns immutable values):
![1__leo_weaver_local___work_git_msgpack-java__java_](https://cloud.githubusercontent.com/assets/57538/3290018/69bc01f8-f573-11e3-9ed4-d20819d347a3.png)
- MessageUnpacker:
- Now supports counting total read bytes.
- Added `unpackValue(ValueHolder)`, `unpackInteger(IntegerHolder)`, `unpackFloat(FloatHolder)`
- Array/MapCursor
- Materialising large array/map values requires huge memory. `Array/MapCursor` interfaces that can be obtained from `Cursor` provide the methods for traversing arrays and maps without constructing the whole array/map values.
- In the draft code, these cursors extended `List` and `Map` interfaces, but this design makes complicate the implementation since Java does not allow mixin of the `List` and `Value` API implementations (e.g., AbstractValue). Because of this, we needed to copy many codes to implement Array/MapCursor. Instead, I chose to provide only `hasNext()` and `next()` methods to traverse map/array values.
- Upgraded to Scala 2.11 (Scala is used only for building and testing). TravisCI now runs `sbt test`
- Added settings to deploy and release to sonatype: To sync with Maven Central, do `sbt publishSigned`, then `sbt sonatypeRelease`.