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.marshall.parser; 018 019import static org.apache.juneau.commons.utils.Shorts.*; 020import static org.apache.juneau.commons.utils.StringUtils.*; 021import static org.apache.juneau.commons.utils.ThrowableUtils.*; 022 023import java.io.*; 024import java.lang.reflect.*; 025import java.nio.charset.*; 026import java.time.*; 027import java.time.Duration; 028import java.time.temporal.*; 029import java.util.*; 030import java.util.function.*; 031 032import javax.xml.datatype.*; 033 034import org.apache.juneau.commons.bean.*; 035import org.apache.juneau.commons.collections.*; 036import org.apache.juneau.commons.function.*; 037import org.apache.juneau.commons.inject.*; 038import org.apache.juneau.commons.reflect.*; 039import org.apache.juneau.marshall.*; 040import org.apache.juneau.marshall.collections.*; 041import org.apache.juneau.marshall.httppart.*; 042import org.apache.juneau.marshall.objecttools.*; 043import org.apache.juneau.marshall.swap.spi.*; 044import org.apache.juneau.marshall.utils.*; 045 046/** 047 * Session object that lives for the duration of a single use of {@link Parser}. 048 * 049 * <h2 class='section'>Notes:</h2><ul> 050 * <li class='warn'>This class is not thread safe and is typically discarded after one use. 051 * </ul> 052 * 053 * <h2 class='section'>See Also:</h2><ul> 054 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/SerializersAndParsers">Serializers and Parsers</a> 055 056 * </ul> 057 */ 058@SuppressWarnings({ 059 "java:S112", // throws Exception intentional - callback/lifecycle method 060 "java:S1192", // Duplicated literals (argument/property names) read more clearly inline than as constants 061 "java:S1452", // create(), getClassMeta() and getListenerClass() expose wildcard Builder<?>/ClassMeta<?>/Class<? extends ParserListener> because the concrete type is not known statically 062 "rawtypes", // Raw types necessary for generic type handling throughout parser session 063 "resource", // pipe field holds the per-parse ParserPipe whose lifecycle is managed by the session, not owned as a standalone field. 064 "unchecked" // Type erasure requires unchecked casts throughout parser session 065}) 066public class ParserSession extends MarshallingSession { 067 068 /** 069 * Default value for {@link Builder#maxParseDepth(int)}. 070 */ 071 protected static final int DEFAULT_MAX_PARSE_DEPTH = 1000; 072 073 /** 074 * Builder class. 075 */ 076 @SuppressWarnings({ 077 "java:S119" // 'SELF' (CRTP self-type) is intentional and clearer than a single-letter name. 078 }) 079 public abstract static class Builder<SELF extends Builder<SELF>> extends MarshallingSession.Builder<SELF> { 080 081 private HttpPartSchema schema; 082 private Method javaMethod; 083 private Object outer; 084 private boolean trimStrings; 085 private Nulls nulls; 086 private int maxParseDepth = DEFAULT_MAX_PARSE_DEPTH; 087 private final Parser ctx; 088 089 /** 090 * Constructor 091 * 092 * @param ctx The context creating this session. 093 * <br>Cannot be <jk>null</jk>. 094 */ 095 protected Builder(Parser ctx) { 096 super(reqnn("ctx", ctx).getMarshallingContext()); 097 this.ctx = ctx; 098 mediaTypeDefault(ctx.getPrimaryMediaType()); 099 trimStrings = ctx.isTrimStrings(); 100 nulls = ctx.getNulls(); 101 } 102 103 @Override 104 public ParserSession build() { 105 return new ParserSession(this); 106 } 107 108 /** 109 * The java method that called this serializer, usually the method in a REST servlet. 110 * 111 * @param value 112 * The new property value. 113 * <br>Can be <jk>null</jk> to leave (or clear) the associated java method unset. 114 * @return This object. 115 */ 116 public SELF javaMethod(Method value) { 117 javaMethod = value; 118 return self(); 119 } 120 121 122 /** 123 * The outer object for instantiating top-level non-static inner classes. 124 * 125 * @param value 126 * The new property value. 127 * <br>Can be <jk>null</jk> (no outer object will be used, suitable for static or top-level classes). 128 * @return This object. 129 */ 130 public SELF outer(Object value) { 131 outer = value; 132 return self(); 133 } 134 135 /** 136 * The shared recursive-parse-depth budget honored by binary codec sessions (CBOR, Protobuf, MsgPack) 137 * at their recursive databind entry points. 138 * 139 * @param value 140 * The new property value. 141 * <br>Defaults to {@value ParserSession#DEFAULT_MAX_PARSE_DEPTH}. 142 * @return This object. 143 * @see ParserSession#enterParseDepth() 144 */ 145 public SELF maxParseDepth(int value) { 146 maxParseDepth = value; 147 return self(); 148 } 149 150 @Override /* Overridden from Builder */ 151 public SELF property(String key, Object value) { 152 if (key == null) { 153 super.property(key, value); 154 return self(); 155 } 156 switch (key) { 157 case "javaMethod", "ParserSession.javaMethod": 158 return javaMethod(cvt(value, Method.class)); 159 case "outer", "ParserSession.outer": 160 return outer(value); 161 case "schema", "ParserSession.schema": 162 return schema(cvt(value, HttpPartSchema.class)); 163 case "trimStrings", "ParserSession.trimStrings": 164 return trimStrings(cvt(value, Boolean.class)); 165 case "nulls", "ParserSession.nulls": 166 return nulls(cvt(value, Nulls.class)); 167 case "maxParseDepth", "ParserSession.maxParseDepth": 168 return maxParseDepth(cvt(value, Integer.class)); 169 default: 170 super.property(key, value); 171 return self(); 172 } 173 } 174 175 /** 176 * Trim parsed strings. 177 * 178 * @param value The new value for this setting. 179 * @return This object. 180 */ 181 public SELF trimStrings(boolean value) { 182 trimStrings = value; 183 return self(); 184 } 185 186 /** 187 * Per-session override for the parser's null-coercion policy. 188 * 189 * @param value The new value for this setting. {@code null} is treated as {@link Nulls#NOT_SET}. 190 * @return This object. 191 * @see Parser.Builder#nulls(Nulls) 192 * @since 10.0.0 193 */ 194 public SELF nulls(Nulls value) { 195 nulls = value == null ? Nulls.NOT_SET : value; 196 return self(); 197 } 198 199 /** 200 * HTTP-part schema. 201 * 202 * <p> 203 * Used for schema-based serializers and parsers to define additional formatting. 204 * 205 * @param value 206 * The new value for this property. 207 * <br>Can be <jk>null</jk> (will not set the value, keeps existing schema or remains <jk>null</jk>). 208 * @return This object. 209 */ 210 public SELF schema(HttpPartSchema value) { 211 if (nn(value)) 212 schema = value; 213 return self(); 214 } 215 216 /** 217 * Same as {@link #schema(HttpPartSchema)} but doesn't overwrite the value if it is already set. 218 * 219 * @param value 220 * The new value for this property. 221 * <br>If <jk>null</jk>, the value will not be set (keeps existing schema or remains <jk>null</jk>). 222 * @return This object. 223 */ 224 public SELF schemaDefault(HttpPartSchema value) { 225 if (nn(value) && schema == null) 226 schema = value; 227 return self(); 228 } 229 230 } 231 232 /** 233 * Concrete default builder leaf for the non-subclassed {@code create()} path (CRTP terminal). 234 */ 235 public static final class DefaultBuilder extends Builder<DefaultBuilder> { 236 237 DefaultBuilder(Parser ctx) { 238 super(ctx); 239 } 240 } 241 242 /** 243 * Creates a new builder for this object. 244 * 245 * @param ctx The context creating this session. 246 * <br>Cannot be <jk>null</jk>. 247 * @return A new builder. 248 */ 249 public static Builder<?> create(Parser ctx) { 250 return new DefaultBuilder(reqnn("ctx", ctx)); 251 } 252 253 /** 254 * Convenience method for calling the {@link NameProperty @NameProperty} method on the specified object if it exists. 255 * 256 * @param cm The class type of the object. 257 * <br>Can be <jk>null</jk> (no-op). 258 * @param o The object. 259 * @param name The name to set. 260 * @throws ExecutableException Exception occurred on invoked constructor/method/field. 261 */ 262 protected static final void setName(ClassMeta<?> cm, Object o, Object name) throws ExecutableException { 263 if (nn(cm)) { 264 Property m = cm.getNameProperty(); 265 if (nn(m) && m.canWrite()) 266 m.set(o, name); 267 } 268 } 269 270 /** 271 * Convenience method for calling the {@link ParentProperty @ParentProperty} method on the specified object if it 272 * exists. 273 * 274 * @param cm The class type of the object. 275 * <br>Can be <jk>null</jk> (no-op). 276 * @param o The object. 277 * @param parent The parent to set. 278 * @throws ExecutableException Exception occurred on invoked constructor/method/field. 279 */ 280 protected static final void setParent(ClassMeta<?> cm, Object o, Object parent) throws ExecutableException { 281 if (cm == null) 282 return; 283 Property m = cm.getParentProperty(); 284 if (nn(m) && m.canWrite()) 285 m.set(o, parent); 286 } 287 288 /** 289 * Returns the nearest enclosing bean used as the parent for {@link ParentProperty @ParentProperty} injection. 290 * 291 * <p> 292 * Unlike {@link #getOuter()} (which also serves as the instantiation context for non-static member/inner classes), 293 * this value tracks only the nearest enclosing <i>bean</i> as the object graph is parsed, deliberately skipping any 294 * intermediate collections/maps/arrays. It is {@code null} at the document root (no enclosing bean), which means a 295 * bean parsed at the root or directly inside a top-level collection has no parent injected. 296 * 297 * @return The nearest enclosing bean, or {@code null} if there is none. 298 */ 299 protected final Object parentBean() { 300 return parentBean; 301 } 302 303 /** 304 * Sets the nearest-enclosing-bean tracker used for {@link ParentProperty @ParentProperty} injection. 305 * 306 * <p> 307 * Callers should invoke this when they begin populating a bean's properties (passing that bean), then pass the 308 * returned previous value back to this method once done, restoring the tracker stack-style. 309 * 310 * @param value The new nearest enclosing bean (typically the bean currently being populated). 311 * @return The previous value, to be passed back to this method to restore the tracker. 312 */ 313 protected final Object swapParentBean(Object value) { 314 var old = parentBean; 315 parentBean = value; 316 return old; 317 } 318 319 private final HttpPartSchema schema; 320 private final Method javaMethod; 321 private final Object outer; 322 private final boolean trimStrings; 323 private final Nulls nulls; 324 private final int maxParseDepth; 325 private final Parser ctx; 326 private final ParserListener listener; 327 private final Deque<StringBuilder> sbStack; 328 private BeanPropertyMeta currentProperty; 329 private ClassMeta<?> currentClass; 330 private Object parentBean; 331 private final Position mark = new Position(-1); 332 private ParserPipe pipe; 333 private int parseDepth; 334 335 /** 336 * Constructor. 337 * 338 * @param builder The builder for this object. 339 * <br>Cannot be <jk>null</jk>. 340 */ 341 protected ParserSession(Builder<?> builder) { 342 super(builder); 343 ctx = builder.ctx; 344 javaMethod = builder.javaMethod; 345 outer = builder.outer; 346 parentBean = builder.outer; 347 schema = builder.schema; 348 trimStrings = builder.trimStrings; 349 nulls = builder.nulls == null ? Nulls.NOT_SET : builder.nulls; 350 maxParseDepth = builder.maxParseDepth; 351 listener = BeanInstantiator.createOrNull(ctx.getListener()); 352 sbStack = new ArrayDeque<>(); 353 } 354 355 /** 356 * Returns the input as a string. 357 * 358 * <p> 359 * This always returns a value for input of type {@link CharSequence}. 360 * <br>For other input types, use {@link org.apache.juneau.marshall.Context.Builder#debug() Context.Builder#debug()} setting to enable caching to a string 361 * before parsing so that this method returns the input. 362 * 363 * @return The input as a string, or <jk>null</jk> if no pipe has been created or we're reading from an uncached reader or input stream source. 364 */ 365 public String getInputAsString() { return pipe == null ? null : pipe.getInputAsString(); } 366 367 /** 368 * Returns information used to determine at what location in the parse a failure occurred. 369 * 370 * @return A map, typically containing something like <c>{line:123,column:456,currentProperty:"foobar"}</c> 371 */ 372 public final JsonMap getLastLocation() { 373 var m = new JsonMap(); 374 if (nn(currentClass)) 375 m.put("currentClass", currentClass.toString(true)); 376 if (nn(currentProperty)) 377 m.put("currentProperty", currentProperty); 378 return m; 379 } 380 381 /** 382 * Returns the listener associated with this session. 383 * 384 * @return The listener associated with this session, or <jk>null</jk> if there is no listener. 385 */ 386 public ParserListener getListener() { return listener; } 387 388 /** 389 * Returns the listener associated with this session. 390 * 391 * @param <T> The listener type. 392 * @param c The listener class to cast to. 393 * @return The listener associated with this session, or <jk>null</jk> if there is no listener. 394 */ 395 public <T extends ParserListener> T getListener(Class<T> c) { 396 return (T)listener; 397 } 398 399 /** 400 * Returns the current position into the reader or input stream. 401 * 402 * @return 403 * The current position into the reader or input stream. 404 * <br>Never <jk>null</jk>. 405 */ 406 public Position getPosition() { 407 if (mark.line != -1 || mark.column != -1 || mark.position != -1) 408 return mark; 409 if (pipe == null) 410 return Position.UNKNOWN; 411 return pipe.getPosition(); 412 } 413 414 /** 415 * HTTP part schema of object being parsed. 416 * 417 * @return HTTP part schema of object being parsed, or <jk>null</jk> if not specified. 418 */ 419 public final HttpPartSchema getSchema() { return schema; } 420 421 /** 422 * Returns <jk>true</jk> if this parser subclasses from {@link ReaderParser}. 423 * 424 * @return <jk>true</jk> if this parser subclasses from {@link ReaderParser}. 425 */ 426 public boolean isReaderParser() { return false; } 427 428 /** 429 * Same as {@link #read(Object, Type, Type...)} except optimized for a non-parameterized class. 430 * 431 * <p> 432 * This is the preferred parse method for simple types since you don't need to cast the results. 433 * 434 * <h4 class='section'>Examples:</h4> 435 * <p class='bjava'> 436 * ReaderParser <jv>parser</jv> = JsonParser.<jsf>DEFAULT</jsf>; 437 * 438 * <jc>// Parse into a string.</jc> 439 * String <jv>string</jv> = <jv>parser</jv>.read(<jv>json</jv>, String.<jk>class</jk>); 440 * 441 * <jc>// Parse into a bean.</jc> 442 * MyBean <jv>bean</jv> = <jv>parser</jv>.read(<jv>json</jv>, MyBean.<jk>class</jk>); 443 * 444 * <jc>// Parse into a bean array.</jc> 445 * MyBean[] <jv>beanArray</jv> = <jv>parser</jv>.read(<jv>json</jv>, MyBean[].<jk>class</jk>); 446 * 447 * <jc>// Parse into a linked-list of objects.</jc> 448 * List <jv>list</jv> = <jv>parser</jv>.read(<jv>json</jv>, LinkedList.<jk>class</jk>); 449 * 450 * <jc>// Parse into a map of object keys/values.</jc> 451 * Map <jv>map</jv> = <jv>parser</jv>.read(<jv>json</jv>, TreeMap.<jk>class</jk>); 452 * </p> 453 * 454 * @param <T> The class type of the object being created. 455 * @param input 456 * The input. 457 * See {@link #read(Object, Type, Type...)} for details. 458 * @param type The object type to create. 459 * @return The parsed object. 460 * @throws ParseException Malformed input encountered. 461 * @throws IOException Thrown by the underlying stream. 462 */ 463 public final <T> T read(Object input, Class<T> type) throws ParseException, IOException { 464 try (var p = createPipe(input)) { 465 return readInner(p, getClassMeta(type)); 466 } 467 } 468 469 /** 470 * Same as {@link #read(Object, Type, Type...)} except the type has already been converted into a {@link ClassMeta} 471 * object. 472 * 473 * <p> 474 * This is mostly an internal method used by the framework. 475 * 476 * @param <T> The class type of the object being created. 477 * @param input 478 * The input. 479 * See {@link #read(Object, Type, Type...)} for details. 480 * @param type The object type to create. 481 * @return The parsed object. 482 * @throws ParseException Malformed input encountered. 483 * @throws IOException Thrown by the underlying stream. 484 */ 485 public final <T> T read(Object input, ClassMeta<T> type) throws ParseException, IOException { 486 try (var p = createPipe(input)) { 487 return readInner(p, type); 488 } 489 } 490 491 /** 492 * Parses input into the specified object type. 493 * 494 * <p> 495 * The type can be a simple type (e.g. beans, strings, numbers) or parameterized type (collections/maps). 496 * 497 * <h4 class='section'>Examples:</h4> 498 * <p class='bjava'> 499 * ReaderParser <jv>parser</jv> = JsonParser.<jsf>DEFAULT</jsf>; 500 * 501 * <jc>// Parse into a linked-list of strings.</jc> 502 * List <jv>list1</jv> = <jv>parser</jv>.read(<jv>json</jv>, LinkedList.<jk>class</jk>, String.<jk>class</jk>); 503 * 504 * <jc>// Parse into a linked-list of beans.</jc> 505 * List <jv>list2</jv> = <jv>parser</jv>.read(<jv>json</jv>, LinkedList.<jk>class</jk>, MyBean.<jk>class</jk>); 506 * 507 * <jc>// Parse into a linked-list of linked-lists of strings.</jc> 508 * List <jv>list3</jv> = <jv>parser</jv>.read(<jv>json</jv>, LinkedList.<jk>class</jk>, LinkedList.<jk>class</jk>, String.<jk>class</jk>); 509 * 510 * <jc>// Parse into a map of string keys/values.</jc> 511 * Map <jv>map1</jv> = <jv>parser</jv>.read(<jv>json</jv>, TreeMap.<jk>class</jk>, String.<jk>class</jk>, String.<jk>class</jk>); 512 * 513 * <jc>// Parse into a map containing string keys and values of lists containing beans.</jc> 514 * Map <jv>map2</jv> = <jv>parser</jv>.read(<jv>json</jv>, TreeMap.<jk>class</jk>, String.<jk>class</jk>, List.<jk>class</jk>, MyBean.<jk>class</jk>); 515 * </p> 516 * 517 * <p> 518 * <c>Collection</c> classes are assumed to be followed by zero or one objects indicating the element type. 519 * 520 * <p> 521 * <c>Map</c> classes are assumed to be followed by zero or two meta objects indicating the key and value types. 522 * 523 * <p> 524 * The array can be arbitrarily long to indicate arbitrarily complex data structures. 525 * 526 * <h4 class='section'>Notes:</h4><ul> 527 * <li class='note'> 528 * Use the {@link #read(Object, Class)} method instead if you don't need a parameterized map/collection. 529 * </ul> 530 * 531 * @param <T> The class type of the object to create. 532 * @param input 533 * The input. 534 * <br>Character-based parsers can handle the following input class types: 535 * <ul> 536 * <li><jk>null</jk> 537 * <li>{@link Reader} 538 * <li>{@link CharSequence} 539 * <li>{@link InputStream} containing UTF-8 encoded text (or charset defined by 540 * {@link ReaderParser.Builder#streamCharset(Charset)} property value). 541 * <li><code><jk>byte</jk>[]</code> containing UTF-8 encoded text (or charset defined by 542 * {@link ReaderParser.Builder#streamCharset(Charset)} property value). 543 * </ul> 544 * <br>Stream-based parsers can handle the following input class types: 545 * <ul> 546 * <li><jk>null</jk> 547 * <li>{@link InputStream} 548 * <li><code><jk>byte</jk>[]</code> 549 * </ul> 550 * @param type 551 * The object type to create. 552 * <br>Can be any of the following: {@link ClassMeta}, {@link Class}, {@link ParameterizedType}, {@link GenericArrayType} 553 * @param args 554 * The type arguments of the class if it's a collection or map. 555 * <br>Can be any of the following: {@link ClassMeta}, {@link Class}, {@link ParameterizedType}, {@link GenericArrayType} 556 * <br>Ignored if the main type is not a map or collection. 557 * @return The parsed object. 558 * @throws ParseException Malformed input encountered. 559 * @see MarshallingSession#getClassMeta(Type,Type...) for argument syntax for maps and collections. 560 * @throws IOException Thrown by the underlying stream. 561 */ 562 public final <T> T read(Object input, Type type, Type...args) throws ParseException, IOException { 563 try (var p = createPipe(input)) { 564 return (T)readInner(p, getClassMeta(type, args)); 565 } 566 } 567 568 /** 569 * Same as {@link #read(Object, Class)} but parses from a string and doesn't throw an {@link IOException}. 570 * 571 * <p> 572 * This is the preferred parse method for simple types since you don't need to cast the results. 573 * 574 * <h4 class='section'>Examples:</h4> 575 * <p class='bjava'> 576 * ReaderParser <jv>parser</jv> = JsonParser.<jsf>DEFAULT</jsf>; 577 * 578 * <jc>// Parse into a string.</jc> 579 * String <jv>string</jv> = <jv>parser</jv>.read(<jv>json</jv>, String.<jk>class</jk>); 580 * 581 * <jc>// Parse into a bean.</jc> 582 * MyBean <jv>bean</jv> = <jv>parser</jv>.read(<jv>json</jv>, MyBean.<jk>class</jk>); 583 * 584 * <jc>// Parse into a bean array.</jc> 585 * MyBean[] <jv>beanArray</jv> = <jv>parser</jv>.read(<jv>json</jv>, MyBean[].<jk>class</jk>); 586 * 587 * <jc>// Parse into a linked-list of objects.</jc> 588 * List <jv>list</jv> = <jv>parser</jv>.read(<jv>json</jv>, LinkedList.<jk>class</jk>); 589 * 590 * <jc>// Parse into a map of object keys/values.</jc> 591 * Map <jv>map</jv> = <jv>parser</jv>.read(<jv>json</jv>, TreeMap.<jk>class</jk>); 592 * </p> 593 * 594 * @param <T> The class type of the object being created. 595 * @param input 596 * The input. 597 * See {@link #read(Object, Type, Type...)} for details. 598 * @param type The object type to create. 599 * @return The parsed object. 600 * @throws ParseException Malformed input encountered. 601 */ 602 public final <T> T read(String input, Class<T> type) throws ParseException { 603 try (var p = createPipe(input)) { 604 return readInner(p, getClassMeta(type)); 605 } catch (IOException e) { 606 throw new ParseException(e); // Shouldn't happen. 607 } 608 } 609 610 /** 611 * Same as {@link #read(Object, ClassMeta)} except parses from a string and doesn't throw an {@link IOException}. 612 * 613 * <p> 614 * This is mostly an internal method used by the framework. 615 * 616 * @param <T> The class type of the object being created. 617 * @param input 618 * The input. 619 * See {@link #read(Object, Type, Type...)} for details. 620 * @param type The object type to create. 621 * @return The parsed object. 622 * @throws ParseException Malformed input encountered. 623 */ 624 public final <T> T read(String input, ClassMeta<T> type) throws ParseException { 625 try (var p = createPipe(input)) { 626 return readInner(p, type); 627 } catch (IOException e) { 628 throw new ParseException(e); // Shouldn't happen. 629 } 630 } 631 632 /** 633 * Same as {@link #read(Object,Type,Type...)} but parses from a string and doesn't throw an {@link IOException}. 634 * 635 * @param <T> The class type of the object to create. 636 * @param input 637 * The input. 638 * <br>Character-based parsers can handle the following input class types: 639 * <ul> 640 * <li><jk>null</jk> 641 * <li>{@link Reader} 642 * <li>{@link CharSequence} 643 * <li>{@link InputStream} containing UTF-8 encoded text (or charset defined by 644 * {@link ReaderParser.Builder#streamCharset(Charset)} property value). 645 * <li><code><jk>byte</jk>[]</code> containing UTF-8 encoded text (or charset defined by 646 * {@link ReaderParser.Builder#streamCharset(Charset)} property value). 647 * </ul> 648 * <br>Stream-based parsers can handle the following input class types: 649 * <ul> 650 * <li><jk>null</jk> 651 * <li>{@link InputStream} 652 * <li><code><jk>byte</jk>[]</code> 653 * </ul> 654 * @param type 655 * The object type to create. 656 * <br>Can be any of the following: {@link ClassMeta}, {@link Class}, {@link ParameterizedType}, {@link GenericArrayType} 657 * @param args 658 * The type arguments of the class if it's a collection or map. 659 * <br>Can be any of the following: {@link ClassMeta}, {@link Class}, {@link ParameterizedType}, {@link GenericArrayType} 660 * <br>Ignored if the main type is not a map or collection. 661 * @return The parsed object. 662 * @throws ParseException Malformed input encountered. 663 * @see MarshallingSession#getClassMeta(Type,Type...) for argument syntax for maps and collections. 664 */ 665 public final <T> T read(String input, Type type, Type...args) throws ParseException { 666 try (var p = createPipe(input)) { 667 return (T)readInner(p, getClassMeta(type, args)); 668 } catch (IOException e) { 669 throw new ParseException(e); // Shouldn't happen. 670 } 671 } 672 673 /** 674 * Parses the specified array input with each entry in the object defined by the {@code argTypes} 675 * argument. 676 * 677 * <p> 678 * Used for converting arrays (e.g. <js>"[arg1,arg2,...]"</js>) into an {@code Object[]} that can be passed 679 * to the {@code Method.invoke(target, args)} method. 680 * 681 * <p> 682 * Used in the following locations: 683 * <ul class='spaced-list'> 684 * <li> 685 * Used to parse argument strings in the {@link ObjectIntrospector#invokeMethod(Method, Reader)} method. 686 * </ul> 687 * 688 * @param input The input. Subclasses can support different input types. 689 * @param argTypes Specifies the type of objects to create for each entry in the array. 690 * @return An array of parsed objects. 691 * @throws ParseException Malformed input encountered. 692 */ 693 public final Object[] readArgs(Object input, Type[] argTypes) throws ParseException { 694 try (var p = createPipe(input)) { 695 return doRead(p, getArgsClassMeta(argTypes)); 696 } catch (ParseException e) { 697 throw e; 698 } catch (@SuppressWarnings("unused") StackOverflowError e) { 699 throw new ParseException(this, "Depth too deep. Stack overflow occurred."); 700 } catch (IOException e) { 701 throw new ParseException(this, e, "I/O exception occurred. exception=%s, message=%s.", cns(e), localizedMessage(e)); 702 } catch (Exception e) { 703 throw new ParseException(this, e, "Exception occurred. exception=%s, message=%s.", cns(e), localizedMessage(e)); 704 } finally { 705 checkForWarnings(); 706 } 707 } 708 709 /** 710 * Parses the contents of the specified reader and loads the results into the specified collection. 711 * 712 * <p> 713 * Used in the following locations: 714 * <ul class='spaced-list'> 715 * <li> 716 * The various character-based constructors in {@link JsonList} (e.g. 717 * {@link JsonList#JsonList(CharSequence,Parser)}. 718 * </ul> 719 * 720 * @param <E> The element class type. 721 * @param input The input. See {@link #read(Object, ClassMeta)} for supported input types. 722 * @param c The collection being loaded. 723 * @param elementType The class type of the elements, or <jk>null</jk> to default to whatever is being parsed. 724 * @return The same collection that was passed in to allow this method to be chained. 725 * @throws ParseException Malformed input encountered. 726 * @throws UnsupportedOperationException If not implemented. 727 */ 728 public final <E> Collection<E> readIntoCollection(Object input, Collection<E> c, Type elementType) throws ParseException { 729 try (var p = createPipe(input)) { 730 return doReadIntoCollection(p, c, elementType); 731 } catch (ParseException e) { 732 throw e; 733 } catch (@SuppressWarnings("unused") StackOverflowError e) { 734 throw new ParseException(this, "Depth too deep. Stack overflow occurred."); 735 } catch (IOException e) { 736 throw new ParseException(this, e, "I/O exception occurred. exception=%s, message=%s.", cns(e), localizedMessage(e)); 737 } catch (Exception e) { 738 throw new ParseException(this, e, "Exception occurred. exception=%s, message=%s.", cns(e), localizedMessage(e)); 739 } finally { 740 checkForWarnings(); 741 } 742 } 743 744 /** 745 * Parses the contents of the specified reader and loads the results into the specified map. 746 * 747 * <p> 748 * Reader must contain something that serializes to a map (such as text containing a JSON object). 749 * 750 * <p> 751 * Used in the following locations: 752 * <ul class='spaced-list'> 753 * <li> 754 * The various character-based constructors in {@link JsonMap} (e.g. 755 * {@link JsonMap#JsonMap(CharSequence,Parser)}). 756 * </ul> 757 * 758 * @param <K> The key class type. 759 * @param <V> The value class type. 760 * @param input The input. See {@link #read(Object, ClassMeta)} for supported input types. 761 * @param m The map being loaded. 762 * @param keyType The class type of the keys, or <jk>null</jk> to default to <code>String.<jk>class</jk></code>. 763 * @param valueType The class type of the values, or <jk>null</jk> to default to whatever is being parsed. 764 * @return The same map that was passed in to allow this method to be chained. 765 * @throws ParseException Malformed input encountered. 766 * @throws UnsupportedOperationException If not implemented. 767 */ 768 public final <K,V> Map<K,V> readIntoMap(Object input, Map<K,V> m, Type keyType, Type valueType) throws ParseException { 769 try (var p = createPipe(input)) { 770 return doReadIntoMap(p, m, keyType, valueType); 771 } catch (ParseException e) { 772 throw e; 773 } catch (@SuppressWarnings("unused") StackOverflowError e) { 774 throw new ParseException(this, "Depth too deep. Stack overflow occurred."); 775 } catch (Exception e) { 776 throw new ParseException(this, e); 777 } finally { 778 checkForWarnings(); 779 } 780 } 781 782 /** 783 * Entry point for all parsing calls. 784 * 785 * <p> 786 * Calls the {@link #doRead(ParserPipe, ClassMeta)} implementation class and catches/re-wraps any exceptions 787 * thrown. 788 * 789 * @param pipe The parser input. 790 * @param type The class type of the object to create. 791 * @param <T> The class type of the object to create. 792 * @return The parsed object. 793 * @throws ParseException Malformed input encountered. 794 * @throws IOException Thrown by the underlying stream. 795 */ 796 private <T> T readInner(ParserPipe pipe, ClassMeta<T> type) throws ParseException, IOException { 797 if (type.isVoid()) 798 return null; 799 if (BeanSupplier.class.isAssignableFrom(type.inner()) && !BeanChannel.class.isAssignableFrom(type.inner())) 800 throw new ParseException(this, "BeanSupplier cannot be used as a parser target. Use BeanConsumer or BeanChannel for round-trip support."); 801 try { 802 var r = doRead(pipe, type); 803 // Primitive optionals (OptionalInt/Long/Double) are parsed as first-class optionals — the format 804 // parsers wrap the element in a generic Optional, so coerce the top-level result to the matching 805 // primitive-optional type (mirrors the Optional<T> contract; absent/null already resolved to empty). 806 if (type.isPrimitiveOptional() && ! type.inner().isInstance(r)) 807 return convertToType(r, type); 808 return r; 809 } catch (ParseException | IOException e) { 810 throw e; 811 } catch (@SuppressWarnings("unused") StackOverflowError e) { 812 throw new ParseException(this, "Depth too deep. Stack overflow occurred."); 813 } catch (Exception e) { 814 throw new ParseException(this, e, "Exception occurred. exception=%s, message=%s.", cns(e), localizedMessage(e)); 815 } finally { 816 checkForWarnings(); 817 } 818 } 819 820 /** 821 * Parses the input and streams each parsed element into the given {@link BeanConsumer}. 822 * 823 * <p> 824 * This is the primary API for large-dataset parsing where parsed beans should be consumed lazily 825 * (e.g. inserted directly into a database) rather than collected into an in-memory collection. 826 * 827 * <p> 828 * The parser drives the full consumer lifecycle: 829 * <ol> 830 * <li>Calls {@link BeanConsumer#begin()} before parsing starts 831 * <li>Calls {@link BeanConsumer#acceptThrows(Object)} for each parsed element 832 * <li>If {@link BeanConsumer#acceptThrows(Object)} throws, calls {@link BeanConsumer#onError(Exception)}; 833 * if {@code onError()} absorbs the exception, parsing continues to the next element 834 * <li>Always calls {@link BeanConsumer#complete()} at the end (like {@code finally}) 835 * </ol> 836 * 837 * <p> 838 * The default implementation parses the input into a {@link List} first and then feeds each element 839 * to the consumer. Format-specific subclasses may override {@link #doReadToBeanConsumer} for true 840 * streaming behavior without loading all elements into memory. 841 * 842 * @param <T> The element type. 843 * @param input The input to parse. 844 * @param consumer The consumer to receive parsed elements. 845 * @param elementType The type of each element. 846 * @throws ParseException If a parse error occurs that causes {@code onError()} to rethrow. 847 * @throws IOException If an I/O error occurs reading the input. 848 */ 849 public final <T> void readToBeanConsumer(Object input, BeanConsumer<T> consumer, Class<T> elementType) throws ParseException, IOException { 850 try (var p = createPipe(input)) { 851 doReadToBeanConsumer(p, consumer, elementType); 852 } 853 } 854 855 /** 856 * Format-specific implementation for {@link #readToBeanConsumer}. 857 * 858 * <p> 859 * The default implementation parses the input as a {@link List} and feeds each element to the consumer. 860 * Override this method in format-specific parsers to support true streaming without collecting all 861 * elements into memory. 862 * 863 * @param <T> The element type. 864 * @param pipe The parser input pipe. 865 * @param consumer The consumer to receive parsed elements. 866 * @param elementType The type of each element. 867 * @throws ParseException If a parse error occurs. 868 * @throws IOException If an I/O error occurs. 869 */ 870 protected <T> void doReadToBeanConsumer(ParserPipe pipe, BeanConsumer<T> consumer, Class<T> elementType) throws ParseException, IOException { 871 List<T> list = (List<T>) doRead(pipe, getClassMeta(List.class, elementType)); 872 if (list == null) 873 return; 874 var bodyThrown = drainToConsumer(consumer, list); 875 var completeThrown = completeQuietly(consumer); 876 if (bodyThrown != null) { 877 if (completeThrown != null) 878 bodyThrown.addSuppressed(completeThrown); 879 if (bodyThrown instanceof ParseException bodyThrown2) 880 throw bodyThrown2; 881 if (bodyThrown instanceof IOException bodyThrown2) 882 throw bodyThrown2; 883 throw new ParseException(this, bodyThrown, "Exception occurred. exception=%s, message=%s.", cns(bodyThrown), localizedMessage(bodyThrown)); 884 } 885 if (completeThrown != null) 886 throw new ParseException(this, completeThrown, "Exception occurred in BeanConsumer.complete(). exception=%s, message=%s.", cns(completeThrown), localizedMessage(completeThrown)); 887 } 888 889 private static <T> Exception drainToConsumer(BeanConsumer<T> consumer, List<T> list) { 890 try { 891 consumer.begin(); 892 for (var element : list) 893 acceptOrError(consumer, element); 894 } catch (Exception e) { 895 return e; 896 } 897 return null; 898 } 899 900 private static <T> void acceptOrError(BeanConsumer<T> consumer, T element) throws Exception { 901 try { 902 consumer.acceptThrows(element); 903 } catch (Exception e) { 904 consumer.onError(e); 905 } 906 } 907 908 private static Exception completeQuietly(BeanConsumer<?> consumer) { 909 try { 910 consumer.complete(); 911 return null; 912 } catch (Exception e) { 913 return e; 914 } 915 } 916 917 /** 918 * Throws {@link MissingRequiredPropertyException} if the bean map is missing {@code @BeanProp(required=true)} properties. 919 * 920 * <p> 921 * Call once per bean, after all input properties have been put into the map and before {@link BeanMap#getBean()} 922 * constructs it. Do not call it for intermediate bean maps that are filled in later. 923 * 924 * @param <T> The bean type. 925 * @param m The bean map. Can be <jk>null</jk>. 926 * @return The same bean map. 927 */ 928 protected final <T> BeanMap<T> checkRequired(BeanMap<T> m) { 929 return MissingRequiredPropertyException.check(this, m); 930 } 931 932 /** 933 * Converts the specified {@link MarshalledMap} into a bean identified by the <js>"_type"</js> property in the map. 934 * 935 * @param m The map to convert to a bean. 936 * <br>Must not be <jk>null</jk>. 937 * @param pMeta The current bean property being parsed. 938 * <br>Can be <jk>null</jk> (the <c>@MarshalledProp(dictionary={})</c> registry lookup is skipped). 939 * @param eType The current expected type being parsed. 940 * <br>Can be <jk>null</jk> (the <c>@Marshalled(dictionary={})</c> registry lookup on the expected type is skipped). 941 * @return 942 * The converted bean, or the same map if the <js>"_type"</js> entry wasn't found or didn't resolve to a bean. 943 */ 944 protected final Object cast(MarshalledMap m, BeanPropertyMeta pMeta, ClassMeta<?> eType) { 945 946 var btpn = getBeanTypePropertyName(eType); 947 948 var o = m.get(btpn); 949 if (o == null) 950 return m; 951 var typeName = o.toString(); 952 953 var cm = getClassMeta(typeName, pMeta, eType); 954 955 if (nn(cm)) { 956 var bm = m.getMarshallingSession().newBeanMap(cm.inner()); 957 958 // Iterate through all the entries in the map and set the individual field values. 959 m.forEach((k, v) -> { 960 if (! k.equals(btpn)) { 961 // Attempt to recursively cast child maps. 962 if (v instanceof MarshalledMap v2) 963 v = cast(v2, pMeta, eType); 964 bm.put(k, v); 965 } 966 }); 967 return checkRequired(bm).getBean(); 968 } 969 970 return m; 971 } 972 973 /** 974 * Converts the specified string to the specified type. 975 * 976 * @param outer 977 * The outer object if we're converting to an inner object that needs to be created within the context 978 * of an outer object. 979 * <br>Can be <jk>null</jk> if the target is not a non-static inner class requiring an enclosing instance. 980 * @param s The string to convert. 981 * <br>Can be <jk>null</jk> (returns <jk>null</jk>). 982 * @param type The class type to convert the string to. 983 * <br>Can be <jk>null</jk> (defaults to <c>Object</c>). 984 * @return The string converted as an object of the specified type, or <jk>null</jk> if the input string was <jk>null</jk>. 985 * @param <T> The class type to convert the string to. 986 * @throws ParseException Malformed input encountered. 987 * @throws ExecutableException Exception occurred on invoked constructor/method/field. 988 */ 989 @SuppressWarnings({ 990 "java:S3776" // Cognitive complexity acceptable for type-conversion dispatch across all supported target types 991 }) 992 protected final <T> T convertAttrToType(Object outer, String s, ClassMeta<T> type) throws ParseException { 993 if (s == null) 994 return null; 995 996 if (type == null) 997 type = (ClassMeta<T>)object(); 998 var swap = type.getSwap(this); 999 var sType = swap == null ? type : swap.getSwapClassMeta(this); 1000 1001 var o = (Object)s; 1002 if (sType.isChar()) 1003 o = parseCharacter(s); 1004 else if (sType.isNumber()) 1005 o = parseNumber(s, (Class<? extends Number>)sType.inner()); 1006 else if (sType.isBoolean()) 1007 o = Boolean.parseBoolean(s); 1008 else if (sType.isDate()) 1009 o = readDate(s, sType); 1010 else if (sType.isCalendar()) 1011 o = readCalendar(s, sType); 1012 else if (sType.isTemporal()) 1013 o = readTemporal(s, sType); 1014 else if (sType.isDuration()) 1015 o = readDuration(s); 1016 else if (sType.isPeriod()) 1017 o = readPeriod(s); 1018 else if (! (sType.isCharSequence() || sType.isObject())) { 1019 if (sType.canCreateNewInstanceFromString(outer)) 1020 o = sType.newInstanceFromString(outer, s); 1021 else 1022 throw new ParseException(this, "Invalid conversion from string to class '%s'", type); 1023 } 1024 1025 if (nn(swap)) 1026 o = unswap(swap, o, type); 1027 1028 return (T)o; 1029 } 1030 1031 /** 1032 * Wraps the specified input object into a {@link ParserPipe} object so that it can be easily converted into 1033 * a stream or reader. 1034 * 1035 * @param input 1036 * The input. 1037 * <br>For character-based parsers, this can be any of the following types: 1038 * <ul> 1039 * <li><jk>null</jk> 1040 * <li>{@link Reader} 1041 * <li>{@link CharSequence} 1042 * <li>{@link InputStream} containing UTF-8 encoded text (or whatever the encoding specified by 1043 * {@link ReaderParser.Builder#streamCharset(Charset)}). 1044 * <li><code><jk>byte</jk>[]</code> containing UTF-8 encoded text (or whatever the encoding specified by 1045 * {@link ReaderParser.Builder#streamCharset(Charset)}). 1046 * </ul> 1047 * <br>For byte-based parsers, this can be any of the following types: 1048 * <ul> 1049 * <li><jk>null</jk> 1050 * <li>{@link InputStream} 1051 * <li><code><jk>byte</jk>[]</code> 1052 * <li>{@link CharSequence} containing encoded bytes according to the {@link InputStreamParser.Builder#binaryFormat(BinaryFormat)} setting. 1053 * </ul> 1054 * @return 1055 * A new {@link ParserPipe} wrapper around the specified input object. 1056 */ 1057 protected ParserPipe createPipe(Object input) { 1058 return null; 1059 } 1060 1061 /** 1062 * Workhorse method. 1063 * 1064 * <p> 1065 * Subclasses are expected to implement this method or {@link Parser#doRead(ParserSession,ParserPipe,ClassMeta)}. 1066 * 1067 * <p> 1068 * The default implementation of this method simply calls {@link Parser#doRead(ParserSession,ParserPipe,ClassMeta)}. 1069 * 1070 * @param pipe Where to get the input from. 1071 * @param type 1072 * The class type of the object to create. 1073 * If <jk>null</jk> or <code>Object.<jk>class</jk></code>, object type is based on what's being parsed. 1074 * For example, when parsing JSON text, it may return a <c>String</c>, <c>Number</c>, 1075 * <c>JsonMap</c>, etc... 1076 * @param <T> The class type of the object to create. 1077 * @return The parsed object. 1078 * @throws IOException Thrown by underlying stream. 1079 * @throws ParseException Malformed input encountered. 1080 * @throws ExecutableException Exception occurred on invoked constructor/method/field. 1081 */ 1082 protected <T> T doRead(ParserPipe pipe, ClassMeta<T> type) throws IOException, ParseException, ExecutableException { 1083 return ctx.doRead(this, pipe, type); 1084 } 1085 1086 /** 1087 * Implementation method. 1088 * 1089 * <p> 1090 * Default implementation throws an {@link UnsupportedOperationException}. 1091 * 1092 * @param <E> The element type. 1093 * @param pipe The parser input. 1094 * @param c The collection being loaded. 1095 * @param elementType The class type of the elements, or <jk>null</jk> to default to whatever is being parsed. 1096 * @return The same collection that was passed in to allow this method to be chained. 1097 * @throws Exception If thrown from underlying stream, or if the input contains a syntax error or is malformed. 1098 */ 1099 protected <E> Collection<E> doReadIntoCollection(ParserPipe pipe, Collection<E> c, Type elementType) throws Exception { 1100 throw uoex("Parser '%s' does not support this method.", cn(getClass())); 1101 } 1102 1103 /** 1104 * Implementation method. 1105 * 1106 * <p> 1107 * Default implementation throws an {@link UnsupportedOperationException}. 1108 * 1109 * @param <K> The key type. 1110 * @param <V> The value type. 1111 * @param pipe The parser input. 1112 * @param m The map being loaded. 1113 * @param keyType The class type of the keys, or <jk>null</jk> to default to <code>String.<jk>class</jk></code>. 1114 * @param valueType The class type of the values, or <jk>null</jk> to default to whatever is being parsed. 1115 * @return The same map that was passed in to allow this method to be chained. 1116 * @throws Exception If thrown from underlying stream, or if the input contains a syntax error or is malformed. 1117 */ 1118 protected <K,V> Map<K,V> doReadIntoMap(ParserPipe pipe, Map<K,V> m, Type keyType, Type valueType) throws Exception { 1119 throw uoex("Parser '%s' does not support this method.", cn(getClass())); 1120 } 1121 1122 /** 1123 * Give the specified dictionary name, resolve it to a class. 1124 * 1125 * @param typeName The dictionary name to resolve. 1126 * @param pMeta The bean property we're currently parsing. 1127 * <br>Can be <jk>null</jk> (the <c>@MarshalledProp(dictionary={})</c> registry lookup is skipped). 1128 * @param eType The expected type we're currently parsing. 1129 * <br>Can be <jk>null</jk> (the <c>@Marshalled(dictionary={})</c> registry lookup on the expected type is skipped). 1130 * @return The resolved class, or <jk>null</jk> if the type name could not be resolved. 1131 */ 1132 protected final ClassMeta<?> getClassMeta(String typeName, BeanPropertyMeta pMeta, ClassMeta<?> eType) { 1133 BeanRegistry br = null; 1134 1135 // Resolve via @MarshalledProp(dictionary={}) 1136 if (nn(pMeta)) { 1137 br = (BeanRegistry) pMeta.getBeanRegistry(); 1138 if (nn(br) && br.hasName(typeName)) 1139 return br.getClassMeta(typeName); 1140 } 1141 1142 // Resolve via @Marshalled(dictionary={}) on the expected type where the 1143 // expected type is an interface with subclasses. 1144 if (nn(eType)) { 1145 br = eType.getBeanRegistry(); 1146 if (nn(br) && br.hasName(typeName)) 1147 return br.getClassMeta(typeName); 1148 } 1149 1150 // Last resort, resolve using the session registry. 1151 return getBeanRegistry().getClassMeta(typeName); 1152 } 1153 1154 /** 1155 * Debug output lines. 1156 * 1157 * @see Parser.Builder#debugOutputLines(int) 1158 * @return 1159 * The number of lines of input before and after the error location to be printed as part of the exception message. 1160 */ 1161 protected final int getDebugOutputLines() { return ctx.getDebugOutputLines(); } 1162 1163 /** 1164 * Returns the Java method that invoked this parser. 1165 * 1166 * <p> 1167 * When using the REST API, this is the Java method invoked by the REST call. 1168 * Can be used to access annotations defined on the method or class. 1169 * 1170 * @return The Java method that invoked this parser, or <jk>null</jk> if not set. 1171 */ 1172 protected final Method getJavaMethod() { return javaMethod; } 1173 1174 /** 1175 * Parser listener. 1176 * 1177 * @see Parser.Builder#listener(Class) 1178 * @return 1179 * Class used to listen for errors and warnings that occur during parsing, or <jk>null</jk> if none was configured. 1180 */ 1181 protected final Class<? extends ParserListener> getListenerClass() { return ctx.getListener(); } 1182 1183 /** 1184 * Returns the outer object used for instantiating top-level non-static member classes. 1185 * 1186 * <p> 1187 * When using the REST API, this is the servlet object. 1188 * 1189 * @return The outer object, or <jk>null</jk> if none was specified. 1190 */ 1191 protected final Object getOuter() { return outer; } 1192 1193 /** 1194 * Creates a reusable {@link StringBuilder} object from an internal pool. 1195 * 1196 * <p> 1197 * String builders are returned to the pool by calling {@link #returnStringBuilder(StringBuilder)}. 1198 * 1199 * @return A new or previously returned string builder. 1200 */ 1201 protected final StringBuilder getStringBuilder() { 1202 if (sbStack.isEmpty()) 1203 return new StringBuilder(); 1204 return sbStack.pop(); 1205 } 1206 1207 /** 1208 * Auto-close streams. 1209 * 1210 * @see Parser.Builder#autoCloseStreams() 1211 * @return 1212 * <jk>true</jk> if <l>InputStreams</l> and <l>Readers</l> passed into parsers will be closed 1213 * after parsing is complete. 1214 */ 1215 protected final boolean isAutoCloseStreams() { return ctx.isAutoCloseStreams(); } 1216 1217 /** 1218 * Trim parsed strings. 1219 * 1220 * @see Parser.Builder#trimStrings() 1221 * @return 1222 * <jk>true</jk> if string values will be trimmed of whitespace using {@link String#trim()} before being added to 1223 * the POJO. 1224 */ 1225 protected final boolean isTrimStrings() { return trimStrings; } 1226 1227 /** 1228 * Include input in errors. 1229 * 1230 * @see Parser.Builder#includeInputInErrors() 1231 * @return <jk>true</jk> if {@link ParseException} messages include a snippet of the input around the error location. 1232 */ 1233 protected final boolean isIncludeInputInErrors() { return ctx.isIncludeInputInErrors(); } 1234 1235 /** 1236 * Returns the effective {@link Nulls} default for this session — the per-session override (set via 1237 * {@link ParserSession.Builder#nulls(Nulls)}) when present, otherwise the parser context's 1238 * {@link Parser#getNulls()} value. 1239 * 1240 * @return The current session-level value (never <jk>null</jk>; {@link Nulls#NOT_SET} when unconfigured). 1241 * @since 10.0.0 1242 */ 1243 public final Nulls getNulls() { return nulls; } 1244 1245 /** 1246 * Unbuffered. 1247 * 1248 * @see Parser.Builder#unbuffered() 1249 * @return 1250 * <jk>true</jk> if parsers don't use internal buffering during parsing. 1251 */ 1252 protected final boolean isUnbuffered() { return ctx.isUnbuffered(); } 1253 1254 /** 1255 * Duration parse hint format. 1256 * 1257 * @return The configured duration parse hint format. 1258 */ 1259 protected final DurationFormat getDurationFormat() { return ctx.getMarshallingContext().getDurationFormat(); } 1260 1261 /** 1262 * Period parse hint format. 1263 * 1264 * @return The configured period parse hint format. 1265 */ 1266 protected final PeriodFormat getPeriodFormat() { return ctx.getMarshallingContext().getPeriodFormat(); } 1267 1268 /** 1269 * Calendar parse hint format. 1270 * 1271 * @return The configured calendar parse hint format. 1272 */ 1273 protected final CalendarFormat getCalendarFormat() { return ctx.getMarshallingContext().getCalendarFormat(); } 1274 1275 /** 1276 * Date parse hint format. 1277 * 1278 * @return The configured date parse hint format. 1279 */ 1280 protected final DateFormat getDateFormat() { return ctx.getMarshallingContext().getDateFormat(); } 1281 1282 /** 1283 * Temporal parse hint format. 1284 * 1285 * @return The configured temporal parse hint format. 1286 */ 1287 protected final TemporalFormat getTemporalFormat() { return ctx.getMarshallingContext().getTemporalFormat(); } 1288 1289 /** 1290 * Time-zone parse hint format. 1291 * 1292 * @return The configured time-zone parse hint format. 1293 */ 1294 protected final TimeZoneFormat getTimeZoneFormat() { return ctx.getMarshallingContext().getTimeZoneFormat(); } 1295 1296 /** 1297 * Locale parse hint format. 1298 * 1299 * @return The configured locale parse hint format. 1300 */ 1301 protected final LocaleFormat getLocaleFormat() { return ctx.getMarshallingContext().getLocaleFormat(); } 1302 1303 /** 1304 * Parses an ISO 8601 / numeric wire value into a {@link Duration} using this session's configured 1305 * {@linkplain #getDurationFormat() duration format} as the disambiguation hint. 1306 * 1307 * @param s The wire value to parse. <jk>null</jk> or empty returns <jk>null</jk>. 1308 * @return The parsed {@link Duration}, or <jk>null</jk> if {@code s} is <jk>null</jk> or empty. 1309 */ 1310 protected final Duration readDuration(String s) { 1311 return Iso8601Utils.parseDuration(s, getDurationFormat()); 1312 } 1313 1314 /** 1315 * Parses an ISO 8601 / numeric wire value into a {@link Period} using this session's configured 1316 * {@linkplain #getPeriodFormat() period format} as the disambiguation hint. 1317 * 1318 * @param s The wire value to parse. <jk>null</jk> or empty returns <jk>null</jk>. 1319 * @return The parsed {@link Period}, or <jk>null</jk> if {@code s} is <jk>null</jk> or empty. 1320 */ 1321 protected final Period readPeriod(String s) { 1322 return Iso8601Utils.parsePeriod(s, getPeriodFormat()); 1323 } 1324 1325 /** 1326 * Parses an ISO 8601 wire value into a {@link Date} target using this session's configured 1327 * {@linkplain #getDateFormat() date format} and {@linkplain #getTimeZone() time zone}. 1328 * 1329 * @param <T> The target type (unbounded to match {@link Iso8601Utils#parseDate}). 1330 * @param s The wire value to parse. <jk>null</jk> returns <jk>null</jk>. 1331 * @param cm The target class metadata. 1332 * @return The parsed value, or <jk>null</jk> if {@code s} is <jk>null</jk> or the target is not a 1333 * recognized {@link Date} type. 1334 */ 1335 protected final <T> T readDate(String s, ClassMeta<T> cm) { 1336 return Iso8601Utils.parseDate(s, cm, getDateFormat(), getTimeZone()); 1337 } 1338 1339 /** 1340 * Parses an ISO 8601 wire value into a {@link Calendar} or {@link XMLGregorianCalendar} 1341 * target using this session's configured {@linkplain #getCalendarFormat() calendar format} and 1342 * {@linkplain #getTimeZone() time zone}. 1343 * 1344 * @param <T> The target type (unbounded because {@link XMLGregorianCalendar} is not a 1345 * {@link Calendar} subclass). 1346 * @param s The wire value to parse. <jk>null</jk> returns <jk>null</jk>. 1347 * @param cm The target class metadata. 1348 * @return The parsed value, or <jk>null</jk> if {@code s} is <jk>null</jk> or the target is not a 1349 * recognized calendar type. 1350 */ 1351 protected final <T> T readCalendar(String s, ClassMeta<T> cm) { 1352 return Iso8601Utils.parseCalendar(s, cm, getCalendarFormat(), getTimeZone()); 1353 } 1354 1355 /** 1356 * Parses an ISO 8601 wire value into the specified {@link Temporal} subtype using 1357 * this session's configured {@linkplain #getTemporalFormat() temporal format} and 1358 * {@linkplain #getTimeZone() time zone}. 1359 * 1360 * @param <T> The target type (unbounded to match {@link Iso8601Utils#parseTemporal}). 1361 * @param s The wire value to parse. <jk>null</jk> returns <jk>null</jk>. 1362 * @param cm The target class metadata. 1363 * @return The parsed value, or <jk>null</jk> if {@code s} is <jk>null</jk> or the target is not a 1364 * {@link Temporal} subtype. 1365 */ 1366 protected final <T> T readTemporal(String s, ClassMeta<T> cm) { 1367 return Iso8601Utils.parseTemporal(s, cm, getTemporalFormat(), getTimeZone()); 1368 } 1369 1370 /** 1371 * Enters one level of recursive databind parsing, enforcing the shared {@link Builder#maxParseDepth(int)} 1372 * budget (default {@value #DEFAULT_MAX_PARSE_DEPTH}). 1373 * 1374 * <p> 1375 * Format parsers (JSON, UON, URL-encoding, XML, HTML, YAML, Markdown, CBOR, Protobuf, MsgPack) call this at their 1376 * recursive databind entry point before descending into a nested array/map/message element, and must call 1377 * {@link #exitParseDepth()} in a matching <jk>finally</jk> block regardless of outcome. Exceeding the budget 1378 * throws a {@link ParseException} so an adversarial deeply-nested document fails cleanly instead of exhausting 1379 * the call stack with a {@link StackOverflowError}. 1380 * 1381 * @throws ParseException If the configured maximum parse depth was exceeded. 1382 */ 1383 protected final void enterParseDepth() throws ParseException { 1384 if (++parseDepth > maxParseDepth) { 1385 parseDepth--; 1386 throw new ParseException(this, "Maximum parse depth exceeded (%s).", maxParseDepth); 1387 } 1388 } 1389 1390 /** 1391 * Exits one level of recursive databind parsing previously entered via {@link #enterParseDepth()}. 1392 * 1393 * <p> 1394 * Must be called exactly once per successful {@link #enterParseDepth()} call, in a matching <jk>finally</jk> 1395 * block so the depth counter is restored even when the nested parse throws. 1396 */ 1397 protected final void exitParseDepth() { 1398 parseDepth--; 1399 } 1400 1401 /** 1402 * Runs a local, parser-controlled allocation (e.g. pre-sizing an array/collection/buffer from a 1403 * wire-declared count) and converts an {@link OutOfMemoryError} thrown specifically from it into a bounded 1404 * {@link ParseException}. 1405 * 1406 * <p> 1407 * Only an {@link OutOfMemoryError} thrown from {@code alloc}'s own execution is converted here. Any other 1408 * {@link OutOfMemoryError} — one raised elsewhere in the call stack, signaling a JVM that is 1409 * genuinely running out of heap — is <b>not</b> this method's concern and is never observed by it; a 1410 * dying JVM is not a client input-validation failure and must not be reported as one. Format-specific 1411 * parser sessions should route untrusted-length-driven local allocations through this helper instead of 1412 * relying on a blanket catch at an outer parse boundary. 1413 * 1414 * @param <T> The allocated object's type. 1415 * @param what A short human-readable description of what's being allocated, used in the exception message 1416 * if the allocation fails. 1417 * <br>Must not be <jk>null</jk>. 1418 * @param alloc The allocation to attempt. 1419 * <br>Must not be <jk>null</jk>. 1420 * @return The allocated object. 1421 * @throws ParseException If {@code alloc} itself threw an {@link OutOfMemoryError}. 1422 */ 1423 protected final <T> T allocateLocal(String what, Supplier<T> alloc) throws ParseException { 1424 try { 1425 return alloc.get(); 1426 } catch (@SuppressWarnings("unused") OutOfMemoryError e) { 1427 throw new ParseException(this, "Out of memory occurred. Input too large to parse. Allocation: %s", what); 1428 } 1429 } 1430 1431 /** 1432 * Marks the current position. 1433 */ 1434 protected void mark() { 1435 if (nn(pipe)) { 1436 Position p = pipe.getPosition(); 1437 mark.line = p.line; 1438 mark.column = p.column; 1439 mark.position = p.position; 1440 } 1441 } 1442 1443 /** 1444 * Specialized warning when an exception is thrown while executing a bean setter. 1445 * 1446 * @param p The bean map entry representing the bean property. 1447 * <br>Must not be <jk>null</jk>. 1448 * @param t The throwable that the bean setter threw. 1449 */ 1450 protected final void onBeanSetterException(BeanPropertyMeta p, Throwable t) { 1451 if (nn(listener)) 1452 listener.onBeanSetterException(this, t, p); 1453 var prefix = ""; 1454 addWarning("%sCould not call setValue() on property '%s' of class '%s', exception = %s", prefix, p.getName(), p.getBeanMeta().getBeanInfo(), localizedMessage(t)); 1455 } 1456 1457 /** 1458 * Method that gets called when an unknown bean property name is encountered. 1459 * 1460 * @param propertyName The unknown bean property name. 1461 * <br>Must not be <jk>null</jk>. 1462 * @param beanMap The bean that doesn't have the expected property. 1463 * <br>Must not be <jk>null</jk>. 1464 * @param value The parsed value. 1465 * <br>Can be <jk>null</jk>, in which case whether the property is ignored is governed by 1466 * {@link MarshallingContext.Builder#disableIgnoreUnknownNullBeanProperties()} rather than 1467 * {@link MarshallingContext.Builder#ignoreUnknownBeanProperties()}. 1468 * @throws ParseException 1469 * Automatically thrown if {@link MarshallingContext.Builder#ignoreUnknownBeanProperties()} setting on this parser is 1470 * <jk>false</jk> 1471 * @param <T> The class type of the bean map that doesn't have the expected property. 1472 */ 1473 protected final <T> void onUnknownProperty(String propertyName, BeanMap<T> beanMap, Object value) throws ParseException { 1474 var bmcm = (ClassMeta<T>) beanMap.getBeanInfo(); 1475 if (propertyName.equals(getBeanTypePropertyName(bmcm))) 1476 return; 1477 if (! isIgnoreUnknownBeanProperties() && (nn(value) || ! isIgnoreUnknownNullBeanProperties())) 1478 throw new ParseException(this, "Unknown property '%s' encountered while trying to parse into class '%s'", propertyName, bmcm); 1479 if (nn(listener)) 1480 listener.onUnknownBeanProperty(this, propertyName, bmcm.inner(), beanMap.getBean()); 1481 } 1482 1483 @Override /* Overridden from MarshallingSession */ 1484 protected FluentMap<String,Object> properties() { 1485 return super.properties() 1486 .a("javaMethod", javaMethod) 1487 .a("listener", listener) 1488 .a("outer", outer) 1489 .a("trimStrings", trimStrings) 1490 .a("nulls", nulls) 1491 .a("maxParseDepth", maxParseDepth); 1492 } 1493 1494 /** 1495 * Returns a {@link StringBuilder} object back into the internal reuse pool. 1496 * 1497 * @param sb The string builder to return to the pool. No-op if <jk>null</jk>. 1498 */ 1499 protected final void returnStringBuilder(StringBuilder sb) { 1500 if (sb == null) 1501 return; 1502 sb.setLength(0); 1503 sbStack.push(sb); 1504 } 1505 1506 /** 1507 * Sets the current class being parsed for proper error messages. 1508 * 1509 * @param currentClass The current class being parsed. 1510 */ 1511 protected final void setCurrentClass(ClassMeta<?> currentClass) { this.currentClass = currentClass; } 1512 1513 /** 1514 * Sets the current bean property being parsed for proper error messages. 1515 * 1516 * @param currentProperty The current property being parsed. 1517 */ 1518 protected final void setCurrentProperty(BeanPropertyMeta currentProperty) { this.currentProperty = currentProperty; } 1519 1520 /** 1521 * The {@link #createPipe(Object)} method should call this method to set the pipe for debugging purposes. 1522 * 1523 * @param pipe The pipe created for this session. 1524 * @return The same pipe. 1525 */ 1526 protected ParserPipe setPipe(ParserPipe pipe) { 1527 this.pipe = pipe; 1528 return pipe; 1529 } 1530 1531 /** 1532 * Trims the specified object if it's a <c>String</c> and {@link #isTrimStrings()} returns <jk>true</jk>. 1533 * 1534 * @param <K> The object type. 1535 * @param o The object to trim. 1536 * @return The trimmed string if it's a string. 1537 */ 1538 protected final <K> K trim(K o) { 1539 if (isTrimStrings() && o instanceof String o2) 1540 return (K)o2.trim(); 1541 return o; 1542 1543 } 1544 1545 /** 1546 * Trims the specified string if {@link ParserSession#isTrimStrings()} returns <jk>true</jk>. 1547 * 1548 * @param s The input string to trim. 1549 * @return The trimmed string, or <jk>null</jk> if the input was <jk>null</jk>. 1550 */ 1551 protected final String trim(String s) { 1552 if (isTrimStrings() && nn(s)) 1553 return s.trim(); 1554 return s; 1555 } 1556 1557 /** 1558 * Unmarks the current position. 1559 */ 1560 protected void unmark() { 1561 mark.line = -1; 1562 mark.column = -1; 1563 mark.position = -1; 1564 } 1565 1566 /** 1567 * Invokes the specified swap on the specified object. 1568 * 1569 * @param swap The swap to invoke. 1570 * <br>Must not be <jk>null</jk>. 1571 * @param o The input object. 1572 * @param eType The expected type. 1573 * @return The swapped object. 1574 * @throws ParseException If swap method threw an exception. 1575 */ 1576 protected Object unswap(ObjectSwap swap, Object o, ClassMeta<?> eType) throws ParseException { 1577 try { 1578 return swap.unswap(this, o, eType); 1579 } catch (Exception e) { 1580 throw new ParseException(e); 1581 } 1582 } 1583}