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.*; 017import java.nio.charset.*; 018 019import org.apache.http.ParseException; 020import org.apache.juneau.*; 021import org.apache.juneau.json.*; 022import org.apache.juneau.serializer.*; 023 024/** 025 * A pairing of a {@link Json5Serializer} and {@link JsonParser} into a single class with convenience read/write methods. 026 * 027 * <p> 028 * The general idea is to combine a single serializer and parser inside a simplified API for reading and writing POJOs. 029 * 030 * <h5 class='figure'>Examples:</h5> 031 * <p class='bjava'> 032 * <jc>// Using instance.</jc> 033 * Json5 <jv>json</jv> = <jk>new</jk> Json5(); 034 * MyPojo <jv>myPojo</jv> = <jv>json</jv>.read(<jv>string</jv>, MyPojo.<jk>class</jk>); 035 * String <jv>string</jv> = <jv>json</jv>.write(<jv>myPojo</jv>); 036 * </p> 037 * <p class='bjava'> 038 * <jc>// Using DEFAULT instance.</jc> 039 * MyPojo <jv>myPojo</jv> = Json5.<jsf>DEFAULT</jsf>.read(<jv>string</jv>, MyPojo.<jk>class</jk>); 040 * String <jv>string</jv> = Json5.<jsf>DEFAULT</jsf>.write(<jv>myPojo</jv>); 041 * </p> 042 * 043 * <h5 class='section'>See Also:</h5><ul> 044 * <li class='link'><a class="doclink" href="../../../../index.html#jm.Marshallers">Marshallers</a> 045 * </ul> 046 */ 047public class Json5 extends CharMarshaller { 048 049 //----------------------------------------------------------------------------------------------------------------- 050 // Static 051 //----------------------------------------------------------------------------------------------------------------- 052 053 /** 054 * Default reusable instance. 055 */ 056 public static final Json5 DEFAULT = new Json5(); 057 058 /** 059 * Default reusable instance, readable format. 060 */ 061 public static final Json5 DEFAULT_READABLE = new Json5(Json5Serializer.DEFAULT_READABLE, Json5Parser.DEFAULT); 062 063 //----------------------------------------------------------------------------------------------------------------- 064 // Instance 065 //----------------------------------------------------------------------------------------------------------------- 066 067 /** 068 * Constructor. 069 * 070 * @param s 071 * The serializer to use for serializing output. 072 * <br>Must not be <jk>null</jk>. 073 * @param p 074 * The parser to use for parsing input. 075 * <br>Must not be <jk>null</jk>. 076 */ 077 public Json5(Json5Serializer s, Json5Parser p) { 078 super(s, p); 079 } 080 081 /** 082 * Constructor. 083 * 084 * <p> 085 * Uses {@link Json5Serializer#DEFAULT} and {@link Json5Parser#DEFAULT}. 086 */ 087 public Json5() { 088 this(Json5Serializer.DEFAULT, Json5Parser.DEFAULT); 089 } 090 091 /** 092 * Parses a JSON 5 input string to the specified type. 093 * 094 * <p> 095 * A shortcut for calling <c><jsf>DEFAULT</jsf>.read(<jv>input</jv>, <jv>type</jv>)</c>. 096 * 097 * @param <T> The class type of the object being created. 098 * @param input The input. 099 * @param type The object type to create. 100 * @return The parsed object. 101 * @throws ParseException Malformed input encountered. 102 */ 103 public static <T> T to(String input, Class<T> type) throws ParseException { 104 return DEFAULT.read(input, type); 105 } 106 107 /** 108 * Parses a JSON 5 input object to the specified Java type. 109 * 110 * <p> 111 * A shortcut for calling <c><jsf>DEFAULT</jsf>.read(<jv>input</jv>, <jv>type</jv>)</c>. 112 * 113 * @param <T> The class type of the object being created. 114 * @param input 115 * The input. 116 * <br>Can be any of the following types: 117 * <ul> 118 * <li><jk>null</jk> 119 * <li>{@link Reader} 120 * <li>{@link CharSequence} 121 * <li>{@link InputStream} containing UTF-8 encoded text (or charset defined by 122 * {@link org.apache.juneau.parser.ReaderParser.Builder#streamCharset(Charset)} property value). 123 * <li><code><jk>byte</jk>[]</code> containing UTF-8 encoded text (or charset defined by 124 * {@link org.apache.juneau.parser.ReaderParser.Builder#streamCharset(Charset)} property value). 125 * <li>{@link File} containing system encoded text (or charset defined by 126 * {@link org.apache.juneau.parser.ReaderParser.Builder#fileCharset(Charset)} property value). 127 * </ul> 128 * @param type The object type to create. 129 * @return The parsed object. 130 * @throws ParseException Malformed input encountered. 131 * @throws IOException Thrown by underlying stream. 132 */ 133 public static <T> T to(Object input, Class<T> type) throws ParseException, IOException { 134 return DEFAULT.read(input, type); 135 } 136 137 /** 138 * Parses a JSON 5 input string to the specified Java type. 139 * 140 * <p> 141 * A shortcut for calling <c><jsf>DEFAULT</jsf>.read(<jv>input</jv>, <jv>type</jv>, <jv>args</jv>)</c>. 142 * 143 * @param <T> The class type of the object to create. 144 * @param input The input. 145 * @param type 146 * The object type to create. 147 * <br>Can be any of the following: {@link ClassMeta}, {@link Class}, {@link ParameterizedType}, {@link GenericArrayType} 148 * @param args 149 * The type arguments of the class if it's a collection or map. 150 * <br>Can be any of the following: {@link ClassMeta}, {@link Class}, {@link ParameterizedType}, {@link GenericArrayType} 151 * <br>Ignored if the main type is not a map or collection. 152 * @return The parsed object. 153 * @throws ParseException Malformed input encountered. 154 * @see BeanSession#getClassMeta(Type,Type...) for argument syntax for maps and collections. 155 */ 156 public static <T> T to(String input, Type type, Type...args) throws ParseException { 157 return DEFAULT.read(input, type, args); 158 } 159 160 /** 161 * Parses a JSON 5 input object to the specified Java type. 162 * 163 * <p> 164 * A shortcut for calling <c><jsf>DEFAULT</jsf>.read(<jv>input</jv>, <jv>type</jv>, <jv>args</jv>)</c>. 165 * 166 * @param <T> The class type of the object to create. 167 * @param input 168 * The input. 169 * <br>Can be any of the following types: 170 * <ul> 171 * <li><jk>null</jk> 172 * <li>{@link Reader} 173 * <li>{@link CharSequence} 174 * <li>{@link InputStream} containing UTF-8 encoded text (or charset defined by 175 * {@link org.apache.juneau.parser.ReaderParser.Builder#streamCharset(Charset)} property value). 176 * <li><code><jk>byte</jk>[]</code> containing UTF-8 encoded text (or charset defined by 177 * {@link org.apache.juneau.parser.ReaderParser.Builder#streamCharset(Charset)} property value). 178 * <li>{@link File} containing system encoded text (or charset defined by 179 * {@link org.apache.juneau.parser.ReaderParser.Builder#fileCharset(Charset)} property value). 180 * </ul> 181 * @param type 182 * The object type to create. 183 * <br>Can be any of the following: {@link ClassMeta}, {@link Class}, {@link ParameterizedType}, {@link GenericArrayType} 184 * @param args 185 * The type arguments of the class if it's a collection or map. 186 * <br>Can be any of the following: {@link ClassMeta}, {@link Class}, {@link ParameterizedType}, {@link GenericArrayType} 187 * <br>Ignored if the main type is not a map or collection. 188 * @return The parsed object. 189 * @throws ParseException Malformed input encountered. 190 * @throws IOException Thrown by underlying stream. 191 * @see BeanSession#getClassMeta(Type,Type...) for argument syntax for maps and collections. 192 */ 193 public static <T> T to(Object input, Type type, Type...args) throws ParseException, IOException { 194 return DEFAULT.read(input, type, args); 195 } 196 197 /** 198 * Serializes a Java object to a JSON 5 string. 199 * 200 * <p> 201 * A shortcut for calling <c><jsf>DEFAULT</jsf>.write(<jv>object</jv>)</c>. 202 * 203 * @param object The object to serialize. 204 * @return 205 * The serialized object. 206 * @throws SerializeException If a problem occurred trying to convert the output. 207 */ 208 public static String of(Object object) throws SerializeException { 209 return DEFAULT.write(object); 210 } 211 212 /** 213 * Serializes a Java object to a JSON 5 output. 214 * 215 * <p> 216 * A shortcut for calling <c><jsf>DEFAULT</jsf>.write(<jv>output</jv>)</c>. 217 * 218 * @param object The object to serialize. 219 * @param output 220 * The output object. 221 * <br>Can be any of the following types: 222 * <ul> 223 * <li>{@link Writer} 224 * <li>{@link OutputStream} - Output will be written as UTF-8 encoded stream. 225 * <li>{@link File} - Output will be written as system-default encoded stream. 226 * <li>{@link StringBuilder} - Output will be written to the specified string builder. 227 * </ul> 228 * @return The output object. 229 * @throws SerializeException If a problem occurred trying to convert the output. 230 * @throws IOException Thrown by underlying stream. 231 */ 232 public static Object of(Object object, Object output) throws SerializeException, IOException { 233 DEFAULT.write(object, output); 234 return output; 235 } 236}