Mercurial > hg > Members > sugi > MessagePack-java

comparison src/main/java/org/msgpack/MessagePack.java @ 0:cb825acd883a

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
first commit
author sugi
date Sat, 18 Oct 2014 15:06:15 +0900
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:cb825acd883a
1 //
2 // MessagePack for Java
3 //
4 // Copyright (C) 2009 - 2013 FURUHASHI Sadayuki
5 //
6 // Licensed under the Apache License, Version 2.0 (the "License");
7 // you may not use this file except in compliance with the License.
8 // You may obtain a copy of the License at
9 //
10 // http://www.apache.org/licenses/LICENSE-2.0
11 //
12 // Unless required by applicable law or agreed to in writing, software
13 // distributed under the License is distributed on an "AS IS" BASIS,
14 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 // See the License for the specific language governing permissions and
16 // limitations under the License.
17 //
18 package org.msgpack;
19
20 import java.io.InputStream;
21 import java.io.OutputStream;
22 import java.io.IOException;
23 import java.lang.reflect.Type;
24 import java.nio.ByteBuffer;
25 import org.msgpack.template.Template;
26 import org.msgpack.template.TemplateRegistry;
27 import org.msgpack.packer.Packer;
28 import org.msgpack.packer.BufferPacker;
29 import org.msgpack.packer.MessagePackPacker;
30 import org.msgpack.packer.MessagePackBufferPacker;
31 import org.msgpack.packer.Unconverter;
32 import org.msgpack.unpacker.Unpacker;
33 import org.msgpack.unpacker.BufferUnpacker;
34 import org.msgpack.unpacker.MessagePackUnpacker;
35 import org.msgpack.unpacker.MessagePackBufferUnpacker;
36 import org.msgpack.unpacker.Converter;
37 import org.msgpack.type.Value;
38
39 /**
40 * <p>
41 * This is basic class to use MessagePack for Java. It creates serializers and
42 * deserializers for objects of classes.
43 * </p>
44 *
45 * <p>
46 * See <a
47 * href="http://wiki.msgpack.org/display/MSGPACK/QuickStart+for+Java">Quick
48 * Start for Java</a> on MessagePack wiki.
49 * </p>
50 *
51 */
52 public class MessagePack {
53 private TemplateRegistry registry;
54
55 /**
56 *
57 * @since 0.6.0
58 */
59 public MessagePack() {
60 registry = new TemplateRegistry(null);
61 }
62
63 /**
64 *
65 * @since 0.6.0
66 * @param msgpack
67 */
68 public MessagePack(MessagePack msgpack) {
69 registry = new TemplateRegistry(msgpack.registry);
70 }
71
72 protected MessagePack(TemplateRegistry registry) {
73 this.registry = registry;
74 }
75
76 /**
77 *
78 * @since 0.6.0
79 * @param cl
80 */
81 public void setClassLoader(final ClassLoader cl) {
82 registry.setClassLoader(cl);
83 }
84
85 /**
86 * Returns serializer that enables serializing objects into
87 * {@link java.io.OutputStream} object.
88 *
89 * @since 0.6.0
90 * @param out
91 * output stream
92 * @return stream-based serializer
93 */
94 public Packer createPacker(OutputStream out) {
95 return new MessagePackPacker(this, out);
96 }
97
98 /**
99 * Returns serializer that enables serializing objects into buffer.
100 *
101 * @since 0.6.0
102 * @return buffer-based serializer
103 */
104 public BufferPacker createBufferPacker() {
105 return new MessagePackBufferPacker(this);
106 }
107
108 /**
109 * Returns serializer that enables serializing objects into buffer.
110 *
111 * @since 0.6.0
112 * @param bufferSize
113 * initial size of buffer
114 * @return buffer-based serializer
115 */
116 public BufferPacker createBufferPacker(int bufferSize) {
117 return new MessagePackBufferPacker(this, bufferSize);
118 }
119
120 /**
121 * Returns deserializer that enables deserializing
122 * {@link java.io.InputStream} object.
123 *
124 * @since 0.6.0
125 * @param in
126 * input stream
127 * @return stream-based deserializer
128 */
129 public Unpacker createUnpacker(InputStream in) {
130 return new MessagePackUnpacker(this, in);
131 }
132
133 /**
134 * Returns empty deserializer that enables deserializing buffer.
135 *
136 * @since 0.6.0
137 * @return buffer-based deserializer
138 */
139 public BufferUnpacker createBufferUnpacker() {
140 return new MessagePackBufferUnpacker(this);
141 }
142
143 /**
144 * Returns deserializer that enables deserializing buffer.
145 *
146 * @since 0.6.0
147 * @param bytes
148 * input byte array
149 * @return buffer-based deserializer
150 */
151 public BufferUnpacker createBufferUnpacker(byte[] bytes) {
152 return createBufferUnpacker().wrap(bytes);
153 }
154
155 /**
156 * Returns deserializer that enables deserializing buffer.
157 *
158 * @since 0.6.0
159 * @param bytes
160 * @param off
161 * @param len
162 * @return buffer-based deserializer
163 */
164 public BufferUnpacker createBufferUnpacker(byte[] bytes, int off, int len) {
165 return createBufferUnpacker().wrap(bytes, off, len);
166 }
167
168 /**
169 * Returns deserializer that enables deserializing buffer.
170 *
171 * @since 0.6.0
172 * @param buffer
173 * input {@link java.nio.ByteBuffer} object
174 * @return buffer-based deserializer
175 */
176 public BufferUnpacker createBufferUnpacker(ByteBuffer buffer) {
177 return createBufferUnpacker().wrap(buffer);
178 }
179
180 /**
181 * Serializes specified object.
182 *
183 * @since 0.6.0
184 * @param v
185 * serialized object
186 * @return output byte array
187 * @throws IOException
188 */
189 public <T> byte[] write(T v) throws IOException {
190 BufferPacker pk = createBufferPacker();
191 if (v == null) {
192 pk.writeNil();
193 } else {
194 @SuppressWarnings("unchecked")
195 Template<T> tmpl = registry.lookup(v.getClass());
196 tmpl.write(pk, v);
197 }
198 return pk.toByteArray();
199 }
200
201 /**
202 * Serializes specified object. It allows serializing object by specified
203 * template.
204 *
205 * @since 0.6.0
206 * @param v
207 * @param template
208 * @return
209 * @throws IOException
210 */
211 public <T> byte[] write(T v, Template<T> template) throws IOException {
212 BufferPacker pk = createBufferPacker();
213 template.write(pk, v);
214 return pk.toByteArray();
215 }
216
217 /**
218 * Serializes specified object to output stream.
219 *
220 * @since 0.6.0
221 * @param out
222 * output stream
223 * @param v
224 * serialized object
225 * @throws IOException
226 */
227 public <T> void write(OutputStream out, T v) throws IOException {
228 Packer pk = createPacker(out);
229 if (v == null) {
230 pk.writeNil();
231 } else {
232 @SuppressWarnings("unchecked")
233 Template<T> tmpl = registry.lookup(v.getClass());
234 tmpl.write(pk, v);
235 }
236 }
237
238 /**
239 * Serializes object to output stream by specified template.
240 *
241 * @since 0.6.0
242 * @param out
243 * output stream
244 * @param v
245 * serialized object
246 * @param template
247 * serializer/deserializer for the object
248 * @throws IOException
249 */
250 public <T> void write(OutputStream out, T v, Template<T> template)
251 throws IOException {
252 Packer pk = createPacker(out);
253 template.write(pk, v);
254 }
255
256 /**
257 * Serializes {@link org.msgpack.type.Value} object to byte array.
258 *
259 * @since 0.6.0
260 * @param v
261 * serialized {@link org.msgpack.type.Value} object
262 * @return output byte array
263 * @throws IOException
264 */
265 public byte[] write(Value v) throws IOException {
266 // FIXME ValueTemplate should do this
267 BufferPacker pk = createBufferPacker();
268 pk.write(v);
269 return pk.toByteArray();
270 }
271
272 /**
273 * Deserializes specified byte array to {@link org.msgpack.type.Value}
274 * object.
275 *
276 * @since 0.6.0
277 * @param bytes
278 * input byte array
279 * @return
280 * @throws IOException
281 */
282 public Value read(byte[] bytes) throws IOException {
283 return read(bytes, 0, bytes.length);
284 }
285
286 /**
287 * Deserializes byte array to {@link org.msgpack.type.Value} object.
288 *
289 * @since 0.6.0
290 * @param bytes
291 * @param off
292 * @param len
293 * @return
294 * @throws IOException
295 */
296 public Value read(byte[] bytes, int off, int len) throws IOException {
297 return createBufferUnpacker(bytes, off, len).readValue();
298 }
299
300 /**
301 * Deserializes {@link java.nio.ByteBuffer} object to
302 * {@link org.msgpack.type.Value} object.
303 *
304 * @since 0.6.0
305 * @param buffer
306 * input buffer
307 * @return
308 * @throws IOException
309 */
310 public Value read(ByteBuffer buffer) throws IOException {
311 return createBufferUnpacker(buffer).readValue();
312 }
313
314 /**
315 * Deserializes input stream to {@link org.msgpack.type.Value} object.
316 *
317 * @since 0.6.0
318 * @param in
319 * input stream
320 * @return deserialized {@link org.msgpack.type.Value} object
321 * @throws IOException
322 */
323 public Value read(InputStream in) throws IOException {
324 return createUnpacker(in).readValue();
325 }
326
327 /**
328 * Deserializes byte array to object.
329 *
330 * @since 0.6.0
331 * @param bytes
332 * input byte array
333 * @param v
334 * @return
335 * @throws IOException
336 */
337 public <T> T read(byte[] bytes, T v) throws IOException {
338 @SuppressWarnings("unchecked")
339 Template<T> tmpl = registry.lookup(v.getClass());
340 return read(bytes, v, tmpl);
341 }
342
343 /**
344 * Deserializes byte array to object according to template.
345 *
346 * @since 0.6.0
347 * @param bytes
348 * input byte array
349 * @param tmpl
350 * template
351 * @return
352 * @throws IOException
353 */
354 public <T> T read(byte[] bytes, Template<T> tmpl) throws IOException {
355 return read(bytes, null, tmpl);
356 }
357
358 /**
359 * Deserializes byte array to object of specified class.
360 *
361 * @since 0.6.0
362 * @param bytes
363 * input byte array
364 * @param c
365 * @return
366 * @throws IOException
367 */
368 public <T> T read(byte[] bytes, Class<T> c) throws IOException {
369 @SuppressWarnings("unchecked")
370 Template<T> tmpl = registry.lookup(c);
371 return read(bytes, null, tmpl);
372 }
373
374 /**
375 * Deserializes byte array to object according to specified template.
376 *
377 * @since 0.6.0
378 * @param bytes
379 * input byte array
380 * @param v
381 * @param tmpl
382 * template
383 * @return
384 * @throws IOException
385 */
386 public <T> T read(byte[] bytes, T v, Template<T> tmpl) throws IOException {
387 BufferUnpacker u = createBufferUnpacker(bytes);
388 return (T) tmpl.read(u, v);
389 }
390
391 /**
392 * Deserializes byte array to object.
393 *
394 * @since 0.6.8
395 * @param bytes
396 * input byte array
397 * @param v
398 * @return
399 * @throws IOException
400 */
401 public <T> T read(byte[] bytes, int off, int len, Class<T> c) throws IOException {
402 @SuppressWarnings("unchecked")
403 Template<T> tmpl = registry.lookup(c);
404 BufferUnpacker u = createBufferUnpacker(bytes, off, len);
405 return (T) tmpl.read(u, null);
406 }
407
408 /**
409 * Deserializes buffer to object.
410 *
411 * @since 0.6.0
412 * @param b
413 * input {@link java.nio.ByteBuffer} object
414 * @param v
415 * @return
416 * @throws IOException
417 */
418 public <T> T read(ByteBuffer b, T v) throws IOException {
419 @SuppressWarnings("unchecked")
420 Template<T> tmpl = registry.lookup(v.getClass());
421 return read(b, v, tmpl);
422 }
423
424 /**
425 * Deserializes buffer to object according to template.
426 *
427 * @since 0.6.0
428 * @param b
429 * input buffer object
430 * @param tmpl
431 * @return
432 * @throws IOException
433 */
434 public <T> T read(ByteBuffer b, Template<T> tmpl) throws IOException {
435 return read(b, null, tmpl);
436 }
437
438 /**
439 * Deserializes buffer to object of specified class.
440 *
441 * @since 0.6.0
442 * @param b
443 * @param c
444 * @return
445 * @throws IOException
446 */
447 public <T> T read(ByteBuffer b, Class<T> c) throws IOException {
448 @SuppressWarnings("unchecked")
449 Template<T> tmpl = registry.lookup(c);
450 return read(b, null, tmpl);
451 }
452
453 /**
454 * Deserializes buffer to object according to template.
455 *
456 * @since 0.6.0
457 * @param b
458 * input buffer object
459 * @param v
460 * @param tmpl
461 * @return
462 * @throws IOException
463 */
464 public <T> T read(ByteBuffer b, T v, Template<T> tmpl) throws IOException {
465 BufferUnpacker u = createBufferUnpacker(b);
466 return tmpl.read(u, v);
467 }
468
469 /**
470 * Deserializes input stream to object.
471 *
472 * @since 0.6.0
473 * @param in
474 * input stream
475 * @param v
476 * @return
477 * @throws IOException
478 */
479 public <T> T read(InputStream in, T v) throws IOException {
480 @SuppressWarnings("unchecked")
481 Template<T> tmpl = registry.lookup(v.getClass());
482 return read(in, v, tmpl);
483 }
484
485 /**
486 * Deserializes input stream to object according to template.
487 *
488 * @since 0.6.0
489 * @param in
490 * input stream
491 * @param tmpl
492 * @return
493 * @throws IOException
494 */
495 public <T> T read(InputStream in, Template<T> tmpl) throws IOException {
496 return read(in, null, tmpl);
497 }
498
499 /**
500 * Deserializes input stream to object of specified class.
501 *
502 * @since 0.6.0
503 * @param in
504 * @param c
505 * @return
506 * @throws IOException
507 */
508 public <T> T read(InputStream in, Class<T> c) throws IOException {
509 @SuppressWarnings("unchecked")
510 Template<T> tmpl = registry.lookup(c);
511 return read(in, null, tmpl);
512 }
513
514 /**
515 * Deserializes input stream to object according to template
516 *
517 * @since 0.6.0
518 * @param in
519 * input stream
520 * @param v
521 * @param tmpl
522 * @return
523 * @throws IOException
524 */
525 public <T> T read(InputStream in, T v, Template<T> tmpl) throws IOException {
526 Unpacker u = createUnpacker(in);
527 return tmpl.read(u, v);
528 }
529
530 /**
531 * Converts specified {@link org.msgpack.type.Value} object to object.
532 *
533 * @since 0.6.0
534 * @param v
535 * @param to
536 * @return
537 * @throws IOException
538 */
539 public <T> T convert(Value v, T to) throws IOException {
540 @SuppressWarnings("unchecked")
541 Template<T> tmpl = registry.lookup(to.getClass());
542 return tmpl.read(new Converter(this, v), to);
543 }
544
545 /**
546 * Converts {@link org.msgpack.type.Value} object to object specified class.
547 *
548 * @since 0.6.0
549 * @param v
550 * @param c
551 * @return
552 * @throws IOException
553 */
554 public <T> T convert(Value v, Class<T> c) throws IOException {
555 @SuppressWarnings("unchecked")
556 Template<T> tmpl = registry.lookup(c);
557 return tmpl.read(new Converter(this, v), null);
558 }
559
560 /**
561 * Converts {@link org.msgpack.type.Value} object to object according to template
562 *
563 * @since 0.6.8
564 * @param v
565 * @param tmpl
566 * @return
567 * @throws IOException
568 */
569 public <T> T convert(Value v, Template<T> tmpl) throws IOException {
570 return tmpl.read(new Converter(this, v), null);
571 }
572
573 /**
574 * Unconverts specified object to {@link org.msgpack.type.Value} object.
575 *
576 * @since 0.6.0
577 * @param v
578 * @return
579 * @throws IOException
580 */
581 public <T> Value unconvert(T v) throws IOException {
582 Unconverter pk = new Unconverter(this);
583 if (v == null) {
584 pk.writeNil();
585 } else {
586 @SuppressWarnings("unchecked")
587 Template<T> tmpl = registry.lookup(v.getClass());
588 tmpl.write(pk, v);
589 }
590 return pk.getResult();
591 }
592
593 /**
594 * Registers {@link org.msgpack.template.Template} object for objects of
595 * specified class. <tt>Template</tt> object is a pair of serializer and
596 * deserializer for object serialization. It is generated automatically.
597 *
598 * @since 0.6.0
599 * @param type
600 */
601 public void register(Class<?> type) {
602 registry.register(type);
603 }
604
605 /**
606 * Registers specified {@link org.msgpack.template.Template} object
607 * associated by class.
608 *
609 * @see #register(Class)
610 * @since 0.6.0
611 * @param type
612 * @param template
613 */
614 public <T> void register(Class<T> type, Template<T> template) {
615 registry.register(type, template);
616 }
617
618 /**
619 * Unregisters {@link org.msgpack.template.Template} object for objects of
620 * specified class.
621 *
622 * @since 0.6.0
623 * @param type
624 * @return
625 */
626 public boolean unregister(Class<?> type) {
627 return registry.unregister(type);
628 }
629
630 /**
631 * Unregisters all {@link org.msgpack.template.Template} objects that have
632 * been registered in advance.
633 *
634 * @since 0.6.0
635 */
636 public void unregister() {
637 registry.unregister();
638 }
639
640 /**
641 * Looks up a {@link org.msgpack.template.Template} object, which is
642 * serializer/deserializer associated by specified class.
643 *
644 * @since 0.6.0
645 * @param type
646 * @return
647 */
648 @SuppressWarnings("unchecked")
649 public <T> Template<T> lookup(Class<T> type) {
650 return registry.lookup(type);
651 }
652
653 public Template<?> lookup(Type type) {
654 return registry.lookup(type);
655 }
656
657 private static final MessagePack globalMessagePack = new MessagePack();
658
659 /**
660 * Serializes specified object and returns the byte array.
661 *
662 * @deprecated {@link MessagePack#write(Object)}
663 * @param v
664 * @return
665 * @throws IOException
666 */
667 @Deprecated
668 public static byte[] pack(Object v) throws IOException {
669 return globalMessagePack.write(v);
670 }
671
672 /**
673 * Serializes specified object to output stream.
674 *
675 * @deprecated {@link MessagePack#write(OutputStream, Object)}
676 * @param out
677 * @param v
678 * @throws IOException
679 */
680 @Deprecated
681 public static void pack(OutputStream out, Object v) throws IOException {
682 globalMessagePack.write(out, v);
683 }
684
685 /**
686 * Serializes object by specified template and return the byte array.
687 *
688 * @deprecated {@link MessagePack#write(Object, Template)}
689 * @param v
690 * @param template
691 * @return
692 * @throws IOException
693 */
694 @Deprecated
695 public static <T> byte[] pack(T v, Template<T> template) throws IOException {
696 return globalMessagePack.write(v, template);
697 }
698
699 /**
700 * Serializes object to output stream. The object is serialized by specified
701 * template.
702 *
703 * @deprecated {@link MessagePack#write(OutputStream, Object, Template)}
704 * @param out
705 * @param v
706 * @param template
707 * @throws IOException
708 */
709 @Deprecated
710 public static <T> void pack(OutputStream out, T v, Template<T> template)
711 throws IOException {
712 globalMessagePack.write(out, v, template);
713 }
714
715 /**
716 * Converts byte array to {@link org.msgpack.type.Value} object.
717 *
718 * @deprecated {@link MessagePack#read(byte[])}
719 * @param bytes
720 * @return
721 * @throws IOException
722 */
723 @Deprecated
724 public static Value unpack(byte[] bytes) throws IOException {
725 return globalMessagePack.read(bytes);
726 }
727
728 @Deprecated
729 public static <T> T unpack(byte[] bytes, Template<T> template) throws IOException {
730 BufferUnpacker u = new MessagePackBufferUnpacker(globalMessagePack).wrap(bytes);
731 return template.read(u, null);
732 }
733
734 @Deprecated
735 public static <T> T unpack(byte[] bytes, Template<T> template, T to) throws IOException {
736 BufferUnpacker u = new MessagePackBufferUnpacker(globalMessagePack).wrap(bytes);
737 return template.read(u, to);
738 }
739
740 /**
741 * Deserializes byte array to object of specified class.
742 *
743 * @deprecated {@link MessagePack#read(byte[], Class)}
744 * @param bytes
745 * @param klass
746 * @return
747 * @throws IOException
748 */
749 @Deprecated
750 public static <T> T unpack(byte[] bytes, Class<T> klass) throws IOException {
751 return globalMessagePack.read(bytes, klass);
752 }
753
754 /**
755 * Deserializes byte array to object.
756 *
757 * @param bytes
758 * @param to
759 * @return
760 * @throws IOException
761 */
762 @Deprecated
763 public static <T> T unpack(byte[] bytes, T to) throws IOException {
764 return globalMessagePack.read(bytes, to);
765 }
766
767 /**
768 * Converts input stream to {@link org.msgpack.type.Value} object.
769 *
770 * @deprecated {@link MessagePack#read(InputStream)}
771 * @param in
772 * @return
773 * @throws IOException
774 */
775 @Deprecated
776 public static Value unpack(InputStream in) throws IOException {
777 return globalMessagePack.read(in);
778 }
779
780 /**
781 * @deprecated
782 * @param in
783 * @param tmpl
784 * @return
785 * @throws IOException
786 * @throws MessageTypeException
787 */
788 @Deprecated
789 public static <T> T unpack(InputStream in, Template<T> tmpl)
790 throws IOException, MessageTypeException {
791 return tmpl.read(new MessagePackUnpacker(globalMessagePack, in), null);
792 }
793
794 /**
795 * @deprecated
796 * @param in
797 * @param tmpl
798 * @param to
799 * @return
800 * @throws IOException
801 * @throws MessageTypeException
802 */
803 @Deprecated
804 public static <T> T unpack(InputStream in, Template<T> tmpl, T to)
805 throws IOException, MessageTypeException {
806 return (T) tmpl.read(new MessagePackUnpacker(globalMessagePack, in), to);
807 }
808
809 /**
810 * Deserializes input stream to object of specified class.
811 *
812 * @deprecated {@link MessagePack#read(InputStream, Class)}
813 * @param in
814 * @param klass
815 * @return
816 * @throws IOException
817 */
818 @Deprecated
819 public static <T> T unpack(InputStream in, Class<T> klass)
820 throws IOException {
821 return globalMessagePack.read(in, klass);
822 }
823
824 /**
825 * Deserializes input stream to object.
826 *
827 * @deprecated {@link MessagePack#read(InputStream, Object)}
828 * @param in
829 * @param to
830 * @return
831 * @throws IOException
832 */
833 @Deprecated
834 public static <T> T unpack(InputStream in, T to) throws IOException {
835 return globalMessagePack.read(in, to);
836 }
837 }