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