Add msgpack-jackson/README.md

komamitsu · komamitsu · commit 8b75906cbef0 · 2014-11-10T21:43:25.000+09:00
diff --git a/README.md b/README.md
@@ -21,6 +21,7 @@ For sbt users:
 libraryDependencies += "org.msgpack" % "msgpack-core" % "0.7.0"
 ```
 
+If you want to use MessagePack through [jackson-databind](https://github.com/FasterXML/jackson-databind), you can use *jackson-dataformat-msgpack*. Please read [README](msgpack-jackson/README.md) to know how to use it.
 
 ## For Developers
 
diff --git a/msgpack-jackson/README.md b/msgpack-jackson/README.md
@@ -0,0 +1,70 @@
+# jackson-dataformat-msgpack
+
+This Jackson extension library handles reading and writing of data encoded in [MessagePack](http://msgpack.org/) data format.
+It extends standard Jackson streaming API (`JsonFactory`, `JsonParser`, `JsonGenerator`), and as such works seamlessly with all the higher level data abstractions (data binding, tree model, and pluggable extensions).
+
+## Maven dependency
+
+To use this module on Maven-based projects, use following dependency:
+
+```
+<dependency>
+  <groupId>org.msgpack</groupId>
+  <artifactId>jackson-dataformat-msgpack</artifactId>
+  <version>x.x.x</version>
+</dependency>
+```
+
+## Usage
+
+Only thing you need to do is to instantiate MessagePackFactory and pass it to the constructor of ObjectMapper.
+
+```
+  ObjectMapper objectMapper = new ObjectMapper(new MessagePackFactory());
+  ExamplePojo orig = new ExamplePojo("komamitsu");
+  byte[] bytes = objectMapper.writeValueAsBytes(orig);
+  ExamplePojo value = objectMapper.readValue(bytes, ExamplePojo.class);
+  System.out.println(value.getName()); // => komamitsu
+```
+
+Also, you can exchange data among multiple languages.
+
+Java
+
+```
+  // Serialize
+  Map<String, Object> obj = new HashMap<String, Object>();
+  obj.put("foo", "hello");
+  obj.put("bar", "world");
+  byte[] bs = objectMapper.writeValueAsBytes(obj);
+  // bs => [-126, -93, 102, 111, 111, -91, 104, 101, 108, 108, 111,
+  //        -93, 98, 97, 114, -91, 119, 111, 114, 108, 100]
+```
+
+Ruby
+
+```
+  require 'msgpack'
+
+  # Deserialize
+  xs = [-126, -93, 102, 111, 111, -91, 104, 101, 108, 108, 111,
+        -93, 98, 97, 114, -91, 119, 111, 114, 108, 100]
+  MessagePack.unpack(xs.pack("C*"))
+  # => {"foo"=>"hello", "bar"=>"world"}
+
+  # Serialize
+  ["zero", 1, 2.0, nil].to_msgpack.unpack('C*')
+  # => [148, 164, 122, 101, 114, 111, 1, 203, 64, 0, 0, 0, 0, 0, 0, 0, 192]
+```
+
+Java
+
+```
+  // Deserialize
+  bs = new byte[] {(byte) 148, (byte) 164, 122, 101, 114, 111, 1,
+                   (byte) 203, 64, 0, 0, 0, 0, 0, 0, 0, (byte) 192};
+  TypeReference<List<Object>> typeReference = new TypeReference<List<Object>>(){};
+  List<Object> xs = objectMapper.readValue(bs, typeReference);
+  // xs => [zero, 1, 2.0, null]
+```
+
