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}