Skip to content

Commit 76ab001

Browse files
mugamuga
committed
added java document to MessagePack.java
1 parent 910634b commit 76ab001

File tree

1 file changed

+127
-19
lines changed

1 file changed

+127
-19
lines changed

‎src/main/java/org/msgpack/MessagePack.java‎

Lines changed: 127 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@
4141
* deserializers for objects of classes.
4242
* </p>
4343
*
44-
* <h3>Overview</h3>
44+
* <h3>Overview of MessagePack</h3>
4545
*
4646
* <p>
4747
* MessagePack is a binary-based efficient object serialization library for
@@ -97,12 +97,12 @@
9797
* <p>
9898
* If you want to serialize multiple objects sequentially, MessagePack
9999
* recommends use of {@link org.msgpack.packer.Packer} and
100-
* {@link org.msgpack.unpacker.Unpacker} objects. Because {@link #write(Object)}
101-
* and {@link #read(byte[])} method invocations create
102-
* {@link org.msgpack.packer.Packer} and {@link org.msgpack.unpacker.Unpacker}
103-
* objects every times. To use <code>Packer</code> and <code>Unpacker</code>
104-
* objects, you call {@link #createPacker(OutputStream)} and
105-
* {@link #createUnpacker(byte[])}.
100+
* {@link org.msgpack.unpacker.Unpacker} objects. Because
101+
* {@link MessagePack#write(Object)} and {@link #read(byte[])} method
102+
* invocations create {@link org.msgpack.packer.Packer} and
103+
* {@link org.msgpack.unpacker.Unpacker} objects every times. To use
104+
* <code>Packer</code> and <code>Unpacker</code> objects, you call
105+
* {@link #createPacker(OutputStream)} and {@link #createUnpacker(byte[])}.
106106
* </p>
107107
*
108108
* <pre>
@@ -136,6 +136,97 @@
136136
* }
137137
* </pre>
138138
*
139+
* <h3>Various Types of Values Serialization/Deserialization</h3>
140+
*
141+
* <p>
142+
* <code>Packer</code>/<code>Unpacker</code> allows serializing/deserializing
143+
* values of various types as follows. They enable serializing/deserializing
144+
* values of various types like values of primitive types, values of primitive
145+
* wrapper classes, <code>String</code> objects, <code>byte[]</code> objects,
146+
* <code>ByteBuffer</code> objects, <code>List</code> objects, </code>Map</code>
147+
* objects and so on. As mentioned above, they also enable
148+
* serializing/deserizing objects of your own classes annotated by
149+
* <code>@Message</code>.
150+
* </p>
151+
*
152+
* <pre>
153+
* public class Main3 {
154+
* public static void main(String[] args) {
155+
* MessagePack msgpack = new MessagePack();
156+
*
157+
* //
158+
* // serialization
159+
* //
160+
*
161+
* ByteArrayOutputStream out = new ByteArrayOutputStream();
162+
* Packer packer = msgpack.createPacker(out);
163+
*
164+
* // serialize values of primitive types
165+
* packer.write(true); // boolean value
166+
* packer.write(10) // int value
167+
* packer.write(10.5); // double value
168+
*
169+
* // serialize objects of primitive wrapper types
170+
* packer.write(Boolean.TRUE);
171+
* packer.write(new Integer(10));
172+
* packer.write(new Double(10.5));
173+
* packer.write(&quot;MesagePack&quot;); // String object
174+
*
175+
* // serialize various types of arrays
176+
* packer.write(new int[] { 1, 2, 3, 4 });
177+
* packer.write(new Double[] { 10.5, 20.5 });
178+
* packer.write(new String[] { &quot;msg&quot;, &quot;pack&quot;, &quot;for&quot;, &quot;java&quot; });
179+
* packer.write(new byte[] { 0x30, 0x31, 0x32 }); // byte array
180+
*
181+
* // serialize various types of other reference values
182+
* packer.write(java.nio.ByteBufer.wrap(new byte[] { 0x30, 0x31, 0x32 })); // ByteBuffer object
183+
* packer.write(java.math.BigInteger.ONE); // BigInteger object
184+
* java.util.List&lt;String&gt; list = new java.util.ArrayList&lt;String&gt;();
185+
* list.add(&quot;msgpack&quot;);
186+
* list.add(&quot;for&quot;);
187+
* list.add(&quot;java&quot;);
188+
* packer.write(list); // List object
189+
* java.util.Map&lt;String, String&gt; map = new java.util.HashMap&lt;String, String&gt;();
190+
* map.put(&quot;sadayuki&quot;, &quot;furuhashi&quot;);
191+
* map.put(&quot;muga&quot;, &quot;nishizawa&quot;);
192+
* packer.write(map); // Map object
193+
*
194+
* //
195+
* // deserialization
196+
* //
197+
*
198+
* byte[] bytes = out.toByteArray();
199+
* ByteArrayInputStream in = new ByteArrayInputStream(bytes);
200+
* Unpacker unpacker = msgpack.createUnpacker(in);
201+
*
202+
* // to primitive values
203+
* boolean b = unpacker.readBoolean(); // boolean value
204+
* int i = unpacker.readInt(); // int value
205+
* double d = unpacker.readDouble(); // double value
206+
*
207+
* // to primitive wrapper value
208+
* Boolean wb = unpacker.readBoolean();
209+
* Integer wi = unpacker.readInt();
210+
* Double wd = unpacker.readDouble();
211+
* String ws = unpacker.readString();
212+
*
213+
* // to arrays
214+
* int[] ia = unpacker.read(int[].class);
215+
* Double[] da = unpacker.read(Double[].class);
216+
* String[] sa = unpacker.read(String[].class);
217+
* byte[] ba = unpacker.readByteArray();
218+
*
219+
* // to ByteBuffer object, BigInteger object, List object and Map object
220+
* java.nio.ByteBuffer buf = unpacker.readByteBuffer();
221+
* java.math.BigInteger bi = unpacker.readBigInteger();
222+
* java.util.List&lt;String&gt; dstList = new java.util.ArrayList&lt;String&gt;();
223+
* dstList = unpacker.read(dstList);
224+
* java.util.Map&lt;String, String&gt; dstMap = new java.util.HashMap&lt;String, String&gt;();
225+
* dstMap = unpacker.read(dstMap);
226+
* }
227+
* }
228+
* </pre>
229+
*
139230
* <h3>Without Annotations</h3>
140231
*
141232
* <p>
@@ -159,6 +250,29 @@
159250
* method.
160251
* </p>
161252
*
253+
* <h3>Optional Fields</h3>
254+
*
255+
* <p>
256+
* You can add new fields maintaining the compatibility. Use the @Optional in
257+
* the new fields.
258+
* </p>
259+
*
260+
* <pre>
261+
* <code>@Message</code>
262+
* public class MyMessage {
263+
* public String name;
264+
* public double version;
265+
* // new field
266+
* <code>@Optional</code>
267+
* public int flag = 0;
268+
* }
269+
* </pre>
270+
*
271+
* <p>
272+
* If you try to deserialize the old version data, optional fields will be
273+
* ignored.
274+
* </p>
275+
*
162276
*/
163277
public class MessagePack {
164278
private TemplateRegistry registry;
@@ -203,8 +317,7 @@ public Packer createPacker(OutputStream out) {
203317
}
204318

205319
/**
206-
* Returns serializer that enables serializing objects into
207-
* buffer.
320+
* Returns serializer that enables serializing objects into buffer.
208321
*
209322
* @since 0.6.0
210323
* @return buffer-based serializer
@@ -214,8 +327,7 @@ public BufferPacker createBufferPacker() {
214327
}
215328

216329
/**
217-
* Returns serializer that enables serializing objects into
218-
* buffer.
330+
* Returns serializer that enables serializing objects into buffer.
219331
*
220332
* @since 0.6.0
221333
* @param bufferSize
@@ -240,8 +352,7 @@ public Unpacker createUnpacker(InputStream in) {
240352
}
241353

242354
/**
243-
* Returns empty deserializer that enables deserializing
244-
* buffer.
355+
* Returns empty deserializer that enables deserializing buffer.
245356
*
246357
* @since 0.6.0
247358
* @return buffer-based deserializer
@@ -251,8 +362,7 @@ public BufferUnpacker createBufferUnpacker() {
251362
}
252363

253364
/**
254-
* Returns deserializer that enables deserializing
255-
* buffer.
365+
* Returns deserializer that enables deserializing buffer.
256366
*
257367
* @since 0.6.0
258368
* @param bytes
@@ -264,8 +374,7 @@ public BufferUnpacker createBufferUnpacker(byte[] bytes) {
264374
}
265375

266376
/**
267-
* Returns deserializer that enables deserializing
268-
* buffer.
377+
* Returns deserializer that enables deserializing buffer.
269378
*
270379
* @since 0.6.0
271380
* @param bytes
@@ -278,8 +387,7 @@ public BufferUnpacker createBufferUnpacker(byte[] bytes, int off, int len) {
278387
}
279388

280389
/**
281-
* Returns deserializer that enables deserializing
282-
* buffer.
390+
* Returns deserializer that enables deserializing buffer.
283391
*
284392
* @since 0.6.0
285393
* @param buffer

0 commit comments

Comments
 (0)