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.juneau.*; 024import org.apache.juneau.json.*; 025import org.apache.juneau.parser.*; 026import org.apache.juneau.serializer.*; 027 028/** 029 * A pairing of a {@link JsonSerializer} 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 * Json <jv>json</jv> = <jk>new</jk> Json(); 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> = Json.<jsf>DEFAULT</jsf>.read(<jv>string</jv>, MyPojo.<jk>class</jk>); 044 * String <jv>string</jv> = Json.<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 Json extends CharMarshaller { 052 /** 053 * Default reusable instance. 054 */ 055 public static final Json DEFAULT = new Json(); 056 057 /** 058 * Serializes a Java object to a JSON string. 059 * 060 * <p> 061 * A shortcut for calling <c><jsf>DEFAULT</jsf>.write(<jv>object</jv>)</c>. 062 * 063 * @param object The object to serialize. 064 * @return 065 * The serialized object. 066 * @throws SerializeException If a problem occurred trying to convert the output. 067 */ 068 public static String of(Object object) throws SerializeException { 069 return DEFAULT.write(object); 070 } 071 072 /** 073 * Serializes a Java object to a JSON output. 074 * 075 * <p> 076 * A shortcut for calling <c><jsf>DEFAULT</jsf>.write(<jv>output</jv>)</c>. 077 * 078 * @param object The object to serialize. 079 * @param output 080 * The output object. 081 * <br>Can be any of the following types: 082 * <ul> 083 * <li>{@link Writer} 084 * <li>{@link OutputStream} - Output will be written as UTF-8 encoded stream. 085 * <li>{@link File} - Output will be written as system-default encoded stream. 086 * <li>{@link StringBuilder} - Output will be written to the specified string builder. 087 * </ul> 088 * @return The output object. 089 * @throws SerializeException If a problem occurred trying to convert the output. 090 * @throws IOException Thrown by underlying stream. 091 */ 092 public static Object of(Object object, Object output) throws SerializeException, IOException { 093 DEFAULT.write(object, output); 094 return output; 095 } 096 097 /** 098 * Parses a JSON input object to the specified Java type. 099 * 100 * <p> 101 * A shortcut for calling <c><jsf>DEFAULT</jsf>.read(<jv>input</jv>, <jv>type</jv>)</c>. 102 * 103 * @param <T> The class type of the object being created. 104 * @param input 105 * The input. 106 * <br>Can be any of the following types: 107 * <ul> 108 * <li><jk>null</jk> 109 * <li>{@link Reader} 110 * <li>{@link CharSequence} 111 * <li>{@link InputStream} containing UTF-8 encoded text (or charset defined by 112 * {@link org.apache.juneau.parser.ReaderParser.Builder#streamCharset(Charset)} property value). 113 * <li><code><jk>byte</jk>[]</code> containing UTF-8 encoded text (or charset defined by 114 * {@link org.apache.juneau.parser.ReaderParser.Builder#streamCharset(Charset)} property value). 115 * <li>{@link File} containing system encoded text (or charset defined by 116 * {@link org.apache.juneau.parser.ReaderParser.Builder#fileCharset(Charset)} property value). 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 object 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 135 * The input. 136 * <br>Can be any of the following types: 137 * <ul> 138 * <li><jk>null</jk> 139 * <li>{@link Reader} 140 * <li>{@link CharSequence} 141 * <li>{@link InputStream} containing UTF-8 encoded text (or charset defined by 142 * {@link org.apache.juneau.parser.ReaderParser.Builder#streamCharset(Charset)} property value). 143 * <li><code><jk>byte</jk>[]</code> containing UTF-8 encoded text (or charset defined by 144 * {@link org.apache.juneau.parser.ReaderParser.Builder#streamCharset(Charset)} property value). 145 * <li>{@link File} containing system encoded text (or charset defined by 146 * {@link org.apache.juneau.parser.ReaderParser.Builder#fileCharset(Charset)} property value). 147 * </ul> 148 * @param type 149 * The object type to create. 150 * <br>Can be any of the following: {@link ClassMeta}, {@link Class}, {@link ParameterizedType}, {@link GenericArrayType} 151 * @param args 152 * The type arguments of the class if it's a collection or map. 153 * <br>Can be any of the following: {@link ClassMeta}, {@link Class}, {@link ParameterizedType}, {@link GenericArrayType} 154 * <br>Ignored if the main type is not a map or collection. 155 * @return The parsed object. 156 * @throws ParseException Malformed input encountered. 157 * @throws IOException Thrown by underlying stream. 158 * @see BeanSession#getClassMeta(Type,Type...) for argument syntax for maps and collections. 159 */ 160 public static <T> T to(Object input, Type type, Type...args) throws ParseException, IOException { 161 return DEFAULT.read(input, type, args); 162 } 163 164 /** 165 * Parses a JSON input string to the specified type. 166 * 167 * <p> 168 * A shortcut for calling <c><jsf>DEFAULT</jsf>.read(<jv>input</jv>, <jv>type</jv>)</c>. 169 * 170 * @param <T> The class type of the object being created. 171 * @param input The input. 172 * @param type The object type to create. 173 * @return The parsed object. 174 * @throws ParseException Malformed input encountered. 175 */ 176 public static <T> T to(String input, Class<T> type) throws ParseException { 177 return DEFAULT.read(input, type); 178 } 179 180 /** 181 * Parses a JSON input string to the specified Java type. 182 * 183 * <p> 184 * A shortcut for calling <c><jsf>DEFAULT</jsf>.read(<jv>input</jv>, <jv>type</jv>, <jv>args</jv>)</c>. 185 * 186 * @param <T> The class type of the object to create. 187 * @param input The input. 188 * @param type 189 * The object type to create. 190 * <br>Can be any of the following: {@link ClassMeta}, {@link Class}, {@link ParameterizedType}, {@link GenericArrayType} 191 * @param args 192 * The type arguments of the class if it's a collection or map. 193 * <br>Can be any of the following: {@link ClassMeta}, {@link Class}, {@link ParameterizedType}, {@link GenericArrayType} 194 * <br>Ignored if the main type is not a map or collection. 195 * @return The parsed object. 196 * @throws ParseException Malformed input encountered. 197 * @see BeanSession#getClassMeta(Type,Type...) for argument syntax for maps and collections. 198 */ 199 public static <T> T to(String input, Type type, Type...args) throws ParseException { 200 return DEFAULT.read(input, type, args); 201 } 202 203 /** 204 * Constructor. 205 * 206 * <p> 207 * Uses {@link JsonSerializer#DEFAULT} and {@link JsonParser#DEFAULT}. 208 */ 209 public Json() { 210 this(JsonSerializer.DEFAULT, JsonParser.DEFAULT); 211 } 212 213 /** 214 * Constructor. 215 * 216 * @param s 217 * The serializer to use for serializing output. 218 * <br>Must not be <jk>null</jk>. 219 * @param p 220 * The parser to use for parsing input. 221 * <br>Must not be <jk>null</jk>. 222 */ 223 public Json(JsonSerializer s, JsonParser p) { 224 super(s, p); 225 } 226}