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.json; 014 015import org.apache.juneau.*; 016import org.apache.juneau.annotation.*; 017import org.apache.juneau.parser.*; 018 019/** 020 * Parses any valid JSON text into a POJO model. 021 * 022 * <h5 class='topic'>Media types</h5> 023 * 024 * Handles <c>Content-Type</c> types: <bc>application/json, text/json</bc> 025 * 026 * <h5 class='topic'>Description</h5> 027 * 028 * This parser uses a state machine, which makes it very fast and efficient. It parses JSON in about 70% of the 029 * time that it takes the built-in Java DOM parsers to parse equivalent XML. 030 * 031 * <p> 032 * This parser handles all valid JSON syntax. 033 * In addition, when strict mode is disable, the parser also handles the following: 034 * <ul class='spaced-list'> 035 * <li> 036 * Javascript comments (both {@code /*} and {@code //}) are ignored. 037 * <li> 038 * Both single and double quoted strings. 039 * <li> 040 * Automatically joins concatenated strings (e.g. <code><js>"aaa"</js> + <js>'bbb'</js></code>). 041 * <li> 042 * Unquoted attributes. 043 * </ul> 044 * 045 * <p> 046 * Also handles negative, decimal, hexadecimal, octal, and double numbers, including exponential notation. 047 * 048 * <p> 049 * This parser handles the following input, and automatically returns the corresponding Java class. 050 * <ul class='spaced-list'> 051 * <li> 052 * JSON objects (<js>"{...}"</js>) are converted to {@link ObjectMap ObjectMaps}. 053 * <b>Note:</b> If a <code><xa>_type</xa>=<xs>'xxx'</xs></code> attribute is specified on the object, then an 054 * attempt is made to convert the object to an instance of the specified Java bean class. 055 * See the <c>beanTypeName</c> setting on the {@link PropertyStore} for more information about parsing 056 * beans from JSON. 057 * <li> 058 * JSON arrays (<js>"[...]"</js>) are converted to {@link ObjectList ObjectLists}. 059 * <li> 060 * JSON string literals (<js>"'xyz'"</js>) are converted to {@link String Strings}. 061 * <li> 062 * JSON numbers (<js>"123"</js>, including octal/hexadecimal/exponential notation) are converted to 063 * {@link Integer Integers}, {@link Long Longs}, {@link Float Floats}, or {@link Double Doubles} depending on 064 * whether the number is decimal, and the size of the number. 065 * <li> 066 * JSON booleans (<js>"false"</js>) are converted to {@link Boolean Booleans}. 067 * <li> 068 * JSON nulls (<js>"null"</js>) are converted to <jk>null</jk>. 069 * <li> 070 * Input consisting of only whitespace or JSON comments are converted to <jk>null</jk>. 071 * </ul> 072 * 073 * <p> 074 * Input can be any of the following: 075 * <ul class='spaced-list'> 076 * <li> 077 * <js>"{...}"</js> - Converted to a {@link ObjectMap} or an instance of a Java bean if a <xa>_type</xa> 078 * attribute is present. 079 * <li> 080 * <js>"[...]"</js> - Converted to a {@link ObjectList}. 081 * <li> 082 * <js>"123..."</js> - Converted to a {@link Number} (either {@link Integer}, {@link Long}, {@link Float}, 083 * or {@link Double}). 084 * <li> 085 * <js>"true"</js>/<js>"false"</js> - Converted to a {@link Boolean}. 086 * <li> 087 * <js>"null"</js> - Returns <jk>null</jk>. 088 * <li> 089 * <js>"'xxx'"</js> - Converted to a {@link String}. 090 * <li> 091 * <js>"\"xxx\""</js> - Converted to a {@link String}. 092 * <li> 093 * <js>"'xxx' + \"yyy\""</js> - Converted to a concatenated {@link String}. 094 * </ul> 095 * 096 * <p> 097 * TIP: If you know you're parsing a JSON object or array, it can be easier to parse it using the 098 * {@link ObjectMap#ObjectMap(CharSequence) ObjectMap(CharSequence)} or {@link ObjectList#ObjectList(CharSequence) 099 * ObjectList(CharSequence)} constructors instead of using this class. 100 * The end result should be the same. 101 */ 102@ConfigurableContext 103public class JsonParser extends ReaderParser { 104 105 //------------------------------------------------------------------------------------------------------------------- 106 // Configurable properties 107 //------------------------------------------------------------------------------------------------------------------- 108 109 static final String PREFIX = "JsonParser"; 110 111 /** 112 * Configuration property: Validate end. 113 * 114 * <h5 class='section'>Property:</h5> 115 * <ul> 116 * <li><b>Name:</b> <js>"JsonParser.validateEnd.b"</js> 117 * <li><b>Data type:</b> <c>Boolean</c> 118 * <li><b>Default:</b> <jk>false</jk> 119 * <li><b>Session property:</b> <jk>false</jk> 120 * <li><b>Methods:</b> 121 * <ul> 122 * <li class='jm'>{@link JsonParserBuilder#validateEnd(boolean)} 123 * <li class='jm'>{@link JsonParserBuilder#validateEnd()} 124 * </ul> 125 * </ul> 126 * 127 * <h5 class='section'>Description:</h5> 128 * <p> 129 * If <jk>true</jk>, after parsing a POJO from the input, verifies that the remaining input in 130 * the stream consists of only comments or whitespace. 131 * 132 * <h5 class='section'>Example:</h5> 133 * <p class='bcode w800'> 134 * <jc>// Create a parser that validates that there's no garbage at the end of the input.</jc> 135 * ReaderParser p = JsonParser. 136 * .<jsm>create</jsm>() 137 * .validateEnd() 138 * .build(); 139 * 140 * <jc>// Same, but use property.</jc> 141 * ReaderParser p = JsonParser. 142 * .<jsm>create</jsm>() 143 * .set(<jsf>JSON_validateEnd</jsf>, <jk>true</jk>) 144 * .build(); 145 * 146 * <jc>// Should fail because input has multiple POJOs.</jc> 147 * String in = <js>"{foo:'bar'}{baz:'qux'}"</js>; 148 * MyBean myBean = p.parse(in, MyBean.<jk>class</jk>); 149 * </p> 150 */ 151 public static final String JSON_validateEnd = PREFIX + ".validateEnd.b"; 152 153 //------------------------------------------------------------------------------------------------------------------- 154 // Predefined instances 155 //------------------------------------------------------------------------------------------------------------------- 156 157 /** Default parser, all default settings.*/ 158 public static final JsonParser DEFAULT = new JsonParser.Simple(PropertyStore.DEFAULT); 159 160 /** Default parser, all default settings.*/ 161 public static final JsonParser DEFAULT_STRICT = new JsonParser.Strict(PropertyStore.DEFAULT); 162 163 164 //------------------------------------------------------------------------------------------------------------------- 165 // Predefined subclasses 166 //------------------------------------------------------------------------------------------------------------------- 167 168 /** Default parser, strict mode. */ 169 public static class Strict extends JsonParser { 170 171 /** 172 * Constructor. 173 * 174 * @param ps The property store containing all the settings for this object. 175 */ 176 public Strict(PropertyStore ps) { 177 super(ps.builder().set(PARSER_strict, true).set(JSON_validateEnd, true).build()); 178 } 179 } 180 181 /** Default parser, simple mode. */ 182 public static class Simple extends JsonParser { 183 184 /** 185 * Constructor. 186 * 187 * @param ps The property store containing all the settings for this object. 188 */ 189 public Simple(PropertyStore ps) { 190 super(ps, "application/json+simple", "text/json+simple"); 191 } 192 } 193 194 //------------------------------------------------------------------------------------------------------------------- 195 // Instance 196 //------------------------------------------------------------------------------------------------------------------- 197 198 private final boolean validateEnd; 199 200 /** 201 * Constructor. 202 * 203 * @param ps The property store containing all the settings for this object. 204 */ 205 public JsonParser(PropertyStore ps) { 206 this(ps, "application/json", "text/json"); 207 } 208 209 /** 210 * Constructor. 211 * 212 * @param ps The property store containing all the settings for this object. 213 * @param consumes The list of media types that this parser consumes (e.g. <js>"application/json"</js>). 214 */ 215 public JsonParser(PropertyStore ps, String...consumes) { 216 super(ps, consumes); 217 validateEnd = getBooleanProperty(JSON_validateEnd, false); 218 } 219 220 @Override /* Context */ 221 public JsonParserBuilder builder() { 222 return new JsonParserBuilder(getPropertyStore()); 223 } 224 225 /** 226 * Instantiates a new clean-slate {@link JsonParserBuilder} object. 227 * 228 * <p> 229 * This is equivalent to simply calling <code><jk>new</jk> JsonParserBuilder()</code>. 230 * 231 * <p> 232 * Note that this method creates a builder initialized to all default settings, whereas {@link #builder()} copies 233 * the settings of the object called on. 234 * 235 * @return A new {@link JsonParserBuilder} object. 236 */ 237 public static JsonParserBuilder create() { 238 return new JsonParserBuilder(); 239 } 240 241 @Override /* Parser */ 242 public JsonParserSession createSession() { 243 return createSession(createDefaultSessionArgs()); 244 } 245 246 @Override /* Parser */ 247 public JsonParserSession createSession(ParserSessionArgs args) { 248 return new JsonParserSession(this, args); 249 } 250 251 //----------------------------------------------------------------------------------------------------------------- 252 // Properties 253 //----------------------------------------------------------------------------------------------------------------- 254 255 /** 256 * Configuration property: Validate end. 257 * 258 * @see #JSON_validateEnd 259 * @return 260 * <jk>true</jk> if after parsing a POJO from the input, verifies that the remaining input in 261 * the stream consists of only comments or whitespace. 262 */ 263 protected final boolean isValidateEnd() { 264 return validateEnd; 265 } 266 267 //----------------------------------------------------------------------------------------------------------------- 268 // Other methods 269 //----------------------------------------------------------------------------------------------------------------- 270 271 @Override /* Context */ 272 public ObjectMap toMap() { 273 return super.toMap() 274 .append("JsonParser", new DefaultFilteringObjectMap()); 275 } 276}