001// ***************************************************************************************************************************
002// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements.  See the NOTICE file *
003// * distributed with this work for additional information regarding copyright ownership.  The ASF licenses this file        *
004// * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance            *
005// * with the License.  You may obtain a copy of the License at                                                              *
006// *                                                                                                                         *
007// *  http://www.apache.org/licenses/LICENSE-2.0                                                                             *
008// *                                                                                                                         *
009// * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an  *
010// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the License for the        *
011// * specific language governing permissions and limitations under the License.                                              *
012// ***************************************************************************************************************************
013package org.apache.juneau.marshaller;
014
015import java.io.*;
016import java.lang.reflect.*;
017
018import org.apache.juneau.*;
019import org.apache.juneau.msgpack.*;
020import org.apache.juneau.parser.*;
021import org.apache.juneau.serializer.*;
022
023/**
024 * A pairing of a {@link MsgPackSerializer} and {@link MsgPackParser} into a single class with convenience read/write methods.
025 *
026 * <p>
027 *    The general idea is to combine a single serializer and parser inside a simplified API for reading and writing POJOs.
028 *
029 * <h5 class='figure'>Examples:</h5>
030 * <p class='bjava'>
031 *    <jc>// Using instance.</jc>
032 *    MsgPack <jv>msgPack</jv> = <jk>new</jk> MsgPack();
033 *    MyPojo <jv>myPojo</jv> = <jv>msgPack</jv>.read(<jv>bytes</jv>, MyPojo.<jk>class</jk>);
034 *    <jk>byte</jk>[] <jv>bytes</jv> = <jv>msgPack</jv>.write(<jv>myPojo</jv>);
035 * </p>
036 * <p class='bjava'>
037 * <jc>// Using DEFAULT instance.</jc>
038 *    MyPojo <jv>myPojo</jv> = MsgPack.<jsf>DEFAULT</jsf>.read(<jv>bytes</jv>, MyPojo.<jk>class</jk>);
039 *    <jk>byte</jk>[] <jv>bytes</jv> = MsgPack.<jsf>DEFAULT</jsf>.write(<jv>myPojo</jv>);
040 * </p>
041 *
042 * <h5 class='section'>See Also:</h5><ul>
043 *    <li class='link'><a class="doclink" href="../../../../index.html#jm.Marshallers">Marshallers</a>
044 * </ul>
045 */
046public class MsgPack extends StreamMarshaller {
047
048   //-----------------------------------------------------------------------------------------------------------------
049   // Static
050   //-----------------------------------------------------------------------------------------------------------------
051
052   /**
053    * Default reusable instance.
054    */
055   public static final MsgPack DEFAULT = new MsgPack();
056
057   //-----------------------------------------------------------------------------------------------------------------
058   // Instance
059   //-----------------------------------------------------------------------------------------------------------------
060
061   /**
062    * Constructor.
063    *
064    * @param s
065    *    The serializer to use for serializing output.
066    *    <br>Must not be <jk>null</jk>.
067    * @param p
068    *    The parser to use for parsing input.
069    *    <br>Must not be <jk>null</jk>.
070    */
071   public MsgPack(MsgPackSerializer s, MsgPackParser p) {
072      super(s, p);
073   }
074
075   /**
076    * Constructor.
077    *
078    * <p>
079    * Uses {@link MsgPackSerializer#DEFAULT} and {@link MsgPackParser#DEFAULT}.
080    */
081   public MsgPack() {
082      this(MsgPackSerializer.DEFAULT, MsgPackParser.DEFAULT);
083   }
084
085   /**
086    * Parses a JSON input string to the specified type.
087    *
088    * <p>
089    * A shortcut for calling <c><jsf>DEFAULT</jsf>.read(<jv>input</jv>, <jv>type</jv>)</c>.
090    *
091    * @param <T> The class type of the object being created.
092    * @param input The input.
093    * @param type The object type to create.
094    * @return The parsed object.
095    * @throws ParseException Malformed input encountered.
096    */
097   public static <T> T to(byte[] input, Class<T> type) throws ParseException {
098      return DEFAULT.read(input, type);
099   }
100
101   /**
102    * Parses a JSON input object to the specified Java type.
103    *
104    * <p>
105    * A shortcut for calling <c><jsf>DEFAULT</jsf>.read(<jv>input</jv>, <jv>type</jv>)</c>.
106    *
107    * @param <T> The class type of the object being created.
108    * @param input
109    *    The input.
110    *    <br>Can be any of the following types:
111    *    <ul>
112    *       <li><jk>null</jk>
113    *       <li>{@link InputStream}
114    *       <li><code><jk>byte</jk>[]</code>
115    *       <li>{@link File}
116    *       <li>{@link CharSequence} containing encoded bytes according to the {@link org.apache.juneau.parser.InputStreamParser.Builder#binaryFormat(BinaryFormat)} setting.
117    *    </ul>
118    * @param type The object type to create.
119    * @return The parsed object.
120    * @throws ParseException Malformed input encountered.
121    * @throws IOException Thrown by underlying stream.
122    */
123   public static <T> T to(Object input, Class<T> type) throws ParseException, IOException {
124      return DEFAULT.read(input, type);
125   }
126
127   /**
128    * Parses a JSON input string to the specified Java type.
129    *
130    * <p>
131    * A shortcut for calling <c><jsf>DEFAULT</jsf>.read(<jv>input</jv>, <jv>type</jv>, <jv>args</jv>)</c>.
132    *
133    * @param <T> The class type of the object to create.
134    * @param input The input.
135    * @param type
136    *    The object type to create.
137    *    <br>Can be any of the following: {@link ClassMeta}, {@link Class}, {@link ParameterizedType}, {@link GenericArrayType}
138    * @param args
139    *    The type arguments of the class if it's a collection or map.
140    *    <br>Can be any of the following: {@link ClassMeta}, {@link Class}, {@link ParameterizedType}, {@link GenericArrayType}
141    *    <br>Ignored if the main type is not a map or collection.
142    * @return The parsed object.
143    * @throws ParseException Malformed input encountered.
144    * @see BeanSession#getClassMeta(Type,Type...) for argument syntax for maps and collections.
145    */
146   public static <T> T to(byte[] input, Type type, Type...args) throws ParseException {
147      return DEFAULT.read(input, type, args);
148   }
149
150   /**
151    * Parses a JSON input object to the specified Java type.
152    *
153    * <p>
154    * A shortcut for calling <c><jsf>DEFAULT</jsf>.read(<jv>input</jv>, <jv>type</jv>, <jv>args</jv>)</c>.
155    *
156    * @param <T> The class type of the object to create.
157    * @param input
158    *    The input.
159    *    <br>Can be any of the following types:
160    *    <ul>
161    *       <li><jk>null</jk>
162    *       <li>{@link InputStream}
163    *       <li><code><jk>byte</jk>[]</code>
164    *       <li>{@link File}
165    *       <li>{@link CharSequence} containing encoded bytes according to the {@link org.apache.juneau.parser.InputStreamParser.Builder#binaryFormat(BinaryFormat)} setting.
166    *    </ul>
167    * @param type
168    *    The object type to create.
169    *    <br>Can be any of the following: {@link ClassMeta}, {@link Class}, {@link ParameterizedType}, {@link GenericArrayType}
170    * @param args
171    *    The type arguments of the class if it's a collection or map.
172    *    <br>Can be any of the following: {@link ClassMeta}, {@link Class}, {@link ParameterizedType}, {@link GenericArrayType}
173    *    <br>Ignored if the main type is not a map or collection.
174    * @return The parsed object.
175    * @throws ParseException Malformed input encountered.
176    * @throws IOException Thrown by underlying stream.
177    * @see BeanSession#getClassMeta(Type,Type...) for argument syntax for maps and collections.
178    */
179   public static <T> T to(Object input, Type type, Type...args) throws ParseException, IOException {
180      return DEFAULT.read(input, type, args);
181   }
182
183   /**
184    * Serializes a Java object to a JSON string.
185    *
186    * <p>
187    * A shortcut for calling <c><jsf>DEFAULT</jsf>.write(<jv>object</jv>)</c>.
188    *
189    * @param object The object to serialize.
190    * @return
191    *    The serialized object.
192    * @throws SerializeException If a problem occurred trying to convert the output.
193    */
194   public static byte[] of(Object object) throws SerializeException {
195      return DEFAULT.write(object);
196   }
197
198   /**
199    * Serializes a Java object to an output.
200    *
201    * <p>
202    * A shortcut for calling <c><jsf>DEFAULT</jsf>.write(<jv>output</jv>)</c>.
203    *
204    * @param object The object to serialize.
205    * @param output
206    *    The output object.
207    *    <br>Can be any of the following types:
208    *    <ul>
209    *       <li>{@link OutputStream}
210    *       <li>{@link File}
211    *    </ul>
212    * @return The output object.
213    * @throws SerializeException If a problem occurred trying to convert the output.
214    * @throws IOException Thrown by underlying stream.
215    */
216   public static Object of(Object object, Object output) throws SerializeException, IOException {
217      DEFAULT.write(object, output);
218      return output;
219   }
220}