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