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.json;
018
019import static org.apache.juneau.commons.lang.StateEnum.*;
020import static org.apache.juneau.commons.utils.CollectionUtils.*;
021import static org.apache.juneau.commons.utils.Shorts.*;
022import static org.apache.juneau.commons.utils.StringUtils.*;
023
024import java.io.*;
025import java.lang.reflect.*;
026import java.util.*;
027
028import org.apache.juneau.commons.bean.*;
029import org.apache.juneau.commons.lang.*;
030import org.apache.juneau.commons.reflect.*;
031import org.apache.juneau.commons.utils.*;
032import org.apache.juneau.marshall.*;
033import org.apache.juneau.marshall.collections.*;
034import org.apache.juneau.marshall.parser.*;
035import org.apache.juneau.marshall.stream.*;
036import org.apache.juneau.marshall.swap.spi.*;
037
038/**
039 * Session object that lives for the duration of a single use of {@link JsonParser}.
040 *
041 * <h2 class='section'>Notes:</h2><ul>
042 *    <li class='warn'>This class is not thread safe and is typically discarded after one use.
043 * </ul>
044 *
045 * <h2 class='section'>See Also:</h2><ul>
046 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JsonSupport">JSON</a>
047
048 * </ul>
049 */
050@SuppressWarnings({
051   "java:S110", // Deep inheritance inherent to the serializer/parser session hierarchy
052   "java:S115", // Constants use camelCase intentionally (e.g., decChars)
053   "java:S125", // State-machine and parse-path comments (S1: ..., Let o be null) are documentation, not commented-out code
054   "java:S135", // readIntoBeanMap2(), readIntoCollection2() and readIntoMap2() use several break/continue guards for invalid characters and separators; restructuring would reduce clarity
055   "java:S1168", // readFieldName() returns null for a missing name and doRead() for empty input; the unreachable fall-through returns in readIntoBeanMap2()/readIntoCollection2()/readIntoMap2() also return null
056   "java:S1192", // Duplicated literals (argument/property names) read more clearly inline than as constants
057   "java:S2583", // State variables persist across loop iterations
058   "java:S3776", // readAnything(), readIntoMap2(), readIntoCollection2() and readIntoBeanMap2() are branch-heavy JSON token state machines; splitting them would obscure the grammar
059   "java:S6541", // Brain method acceptable for JSON parser dispatch and state machines
060   "rawtypes", // Raw types necessary for generic type handling
061   "resource", // ParserReader is managed by caller
062   "unchecked" // Type erasure requires unchecked casts
063})
064public class JsonParserSession extends ReaderParserSession implements TokenReadable, ArrayRecordReadable {
065
066   /**
067    * Builder class.
068    */
069   @SuppressWarnings({
070      "java:S119" // 'SELF' (CRTP self-type) is intentional and clearer than a single-letter name.
071   })
072   public abstract static class Builder<SELF extends Builder<SELF>> extends ReaderParserSession.Builder<SELF> {
073
074      private boolean validateEnd;
075      private final JsonParser ctx;
076
077      /**
078       * Constructor
079       *
080       * @param ctx The context creating this session.
081       */
082      protected Builder(JsonParser ctx) {
083         super(ctx);
084         this.ctx = ctx;
085         validateEnd = ctx.isValidateEnd();
086      }
087
088      @Override
089      public JsonParserSession build() {
090         return new JsonParserSession(this);
091      }
092
093      /**
094       * Validate end.
095       *
096       * @param value The new value for this setting.
097       * @return This object.
098       */
099      public SELF validateEnd(boolean value) {
100         validateEnd = value;
101         return self();
102      }
103
104      @Override /* Overridden from Builder */
105      public SELF property(String key, Object value) {
106         if (key == null) { super.property(key, value); return self(); }
107         switch (key) {
108            case "validateEnd", "JsonParserSession.validateEnd":
109               return validateEnd(cvt(value, Boolean.class));
110            default:
111               super.property(key, value);
112               return self();
113         }
114      }
115
116   }
117
118   /**
119    * Concrete default builder leaf for the non-subclassed {@code create()} path (CRTP terminal).
120    */
121   public static final class DefaultBuilder extends Builder<DefaultBuilder> {
122
123      DefaultBuilder(JsonParser ctx) {
124         super(ctx);
125      }
126   }
127
128   private static final AsciiSet decChars = AsciiSet.create().ranges("0-9").build();
129
130   /**
131    * Creates a new builder for this object.
132    *
133    * @param ctx The context creating this session.
134    * @return A new builder.
135    */
136   @SuppressWarnings({
137      "java:S1452" // Builder<?> wildcard return intentional; callers use it to construct session instances polymorphically
138   })
139   public static Builder<?> create(JsonParser ctx) {
140      return new DefaultBuilder(ctx);
141   }
142
143   private final JsonParser ctx;
144   private final boolean validateEnd;
145
146   /**
147    * Constructor.
148    *
149    * @param builder The builder for this object.
150    */
151   protected JsonParserSession(Builder<?> builder) {
152      super(builder);
153      ctx = builder.ctx;
154      validateEnd = builder.validateEnd;
155   }
156
157   <T> T readAnything(ClassMeta<?> eType, ParserReader r, Object outer, BeanPropertyMeta pMeta) throws IOException, ParseException, ExecutableException {
158      enterParseDepth();
159      try {
160         return readAnything0(eType, r, outer, pMeta);
161      } finally {
162         exitParseDepth();
163      }
164   }
165
166   // Workhorse method, wrapped by readAnything() with the recursion-depth guard.
167   private <T> T readAnything0(ClassMeta<?> eType, ParserReader r, Object outer, BeanPropertyMeta pMeta) throws IOException, ParseException, ExecutableException {
168
169      if (eType == null)
170         eType = object();
171      var swap = (ObjectSwap<T,Object>)eType.getSwap(this);
172      var builder = (BuilderSwap<T,Object>)eType.getBuilderSwap(this);
173      ClassMeta<?> sType = null;
174      if (nn(builder))
175         sType = builder.getBuilderClassMeta(this);
176      else if (nn(swap))
177         sType = swap.getSwapClassMeta(this);
178      else
179         sType = eType;
180
181      if (sType.isOptional())
182         return (T)o(readAnything(eType.getElementType(), r, outer, pMeta));
183
184      setCurrentClass(sType);
185      var wrapperAttr = getJsonClassMeta(sType).getWrapperAttr();
186
187      Object o = null;
188
189      skipCommentsAndSpace(r);
190      if (nn(wrapperAttr))
191         skipWrapperAttrStart(r, wrapperAttr);
192      int c = r.peek();
193      if (c == -1) {
194         onEmptyInput();
195      } else if ((c == ',' || c == '}' || c == ']')) {
196         onMissingValue();
197      } else if (c == 'n') {
198         readKeyword("null", r);
199      } else if (sType.isObject()) {
200         if (c == '{') {
201            var m2 = newGenericMap();
202            readIntoMap2(r, m2, string(), object(), pMeta);
203            o = cast(m2, pMeta, eType);
204         } else if (c == '[') {
205            o = readIntoCollection2(r, newGenericList(), object(), pMeta);
206         } else if (c == '\'' || c == '"') {
207            o = readString(r);
208            if (sType.isChar())
209               o = parseCharacter(o);
210         } else if (isNumberStartChar(c)) {
211            o = readNumber(r, null);
212         } else if (c == 't') {
213            readKeyword("true", r);
214            o = Boolean.TRUE;
215         } else {
216            readKeyword("false", r);
217            o = Boolean.FALSE;
218         }
219      } else if (nn(builder)) {
220         var m = toBeanMap(builder.create(this, eType));
221         o = builder.build(this, checkRequired(readIntoBeanMap2(r, m)).getBean(), eType);
222      } else if (sType.canCreateNewBean(outer)) {
223         var m = newBeanMap(outer, sType.inner());
224         o = checkRequired(readIntoBeanMap2(r, m)).getBean();
225      } else if (sType.isMap()) {
226         Map m = (sType.canCreateNewInstance(outer) ? (Map)sType.newInstance(outer) : newGenericMap(sType));
227         o = readIntoMap2(r, m, sType.getKeyType(), sType.getValueType(), pMeta);
228      } else if (sType.isCollection()) {
229         if (c == '{') {
230            var m = newGenericMap();
231            readIntoMap2(r, m, string(), object(), pMeta);
232            o = cast(m, pMeta, eType);
233         } else {
234            Collection l = (sType.canCreateNewInstance(outer) ? (Collection)sType.newInstance() : newGenericList());
235            o = readIntoCollection2(r, l, sType, pMeta);
236         }
237      } else if (sType.isArray() || sType.isArgs()) {
238         if (c == '{') {
239            var m = newGenericMap();
240            readIntoMap2(r, m, string(), object(), pMeta);
241            o = cast(m, pMeta, eType);
242         } else {
243            var l = (ArrayList)readIntoCollection2(r, list(), sType, pMeta);
244            o = toArray(sType, l);
245         }
246      } else if (sType.isCharSequence()) {
247         o = readString(r);
248      } else if (sType.isChar()) {
249         o = parseCharacter(readString(r));
250      } else if (sType.isNumber()) {
251         o = readNumber(r, (Class<? extends Number>)sType.inner());
252      } else if (sType.isBoolean()) {
253         o = readBoolean(r);
254      } else if (sType.isDate()) {
255         o = readDate(readString(r), sType);
256      } else if (sType.isCalendar()) {
257         o = readCalendar(readString(r), sType);
258      } else if (sType.isTemporal()) {
259         o = readTemporal(readString(r), sType);
260      } else if (sType.isDuration()) {
261         o = readDuration(readString(r));
262      } else if (sType.isPeriod()) {
263         o = readPeriod(readString(r));
264      } else if (sType.canCreateNewInstanceFromString(outer) && (c == '\'' || c == '"')) {
265         o = sType.newInstanceFromString(outer, readString(r));
266      } else if (c == '{') {
267         Map m = newGenericMap();
268         readIntoMap2(r, m, sType.getKeyType(), sType.getValueType(), pMeta);
269         if (m.containsKey(getBeanTypePropertyName(eType)))
270            o = cast((MarshalledMap)m, pMeta, eType);
271         else if (nn(sType.getProxyInvocationHandler()))
272            o = checkRequired(newBeanMap(outer, sType.inner()).load(m)).getBean();
273         else
274            throw new ParseException(this, "Class '%s' could not be instantiated.  Reason: '%s'", cn(sType), sType.getNotABeanReason());
275      } else if (sType.canCreateNewInstanceFromString(outer) && canCoerceNonStringToString()) {
276         o = sType.newInstanceFromString(outer, readString(r));
277      } else {
278         throw new ParseException(this, "Unrecognized syntax for class type '%s', starting character '%s'", sType, (char)c);
279      }
280
281      if (nn(wrapperAttr))
282         skipWrapperAttrEnd(r);
283
284      if (nn(swap) && nn(o))
285         o = unswap(swap, o, eType);
286
287      if (nn(parentBean()))
288         setParent(eType, o, parentBean());
289
290      return (T)o;
291   }
292
293   private Boolean readBoolean(ParserReader r) throws IOException, ParseException {
294      int c = r.peek();
295      if (c == '\'' || c == '"')
296         return b(readString(r));
297      if (c == 't') {
298         readKeyword("true", r);
299         return Boolean.TRUE;
300      } else if (c == 'f') {
301         readKeyword("false", r);
302         return Boolean.FALSE;
303      } else {
304         throw new ParseException(this, "Unrecognized syntax.  Expected boolean value, actual='%s'", r.read(100));
305      }
306   }
307
308   /*
309    * Parse a JSON attribute from the character array at the specified position, then
310    * set the position marker to the last character in the field name.
311    */
312   protected String readFieldName(ParserReader r) throws IOException, ParseException {
313      int c = r.peek();
314      if (c == '\'' || c == '"')
315         return readString(r);
316      if (c == 'n') {
317         readKeyword("null", r);
318         return null;
319      }
320      throw new ParseException(this, "Unquoted attribute detected.");
321   }
322
323   private <T> BeanMap<T> readIntoBeanMap2(ParserReader r, BeanMap<T> m) throws IOException, ParseException, ExecutableException {
324
325      // S1: Looking for outer {
326      // S2: Looking for attrName start.
327      // S3: Found attrName end, looking for :.
328      // S4: Found :, looking for valStart: { [ " ' LITERAL.
329      // S5: Looking for , or }
330
331      var state = S1;
332      var currAttr = "";
333      int c = 0;
334      var pb = swapParentBean(m.getBean(false));
335      mark();
336      try {
337         while (c != -1) {
338            c = r.read();
339            if (state == S1) {
340               if (c == '{') {
341                  state = S2;
342               } else if (isCommentOrWhitespace(c)) {
343                  skipCommentsAndSpace(r.unread());
344               } else {
345                  break;
346               }
347            } else if (state == S2) {
348               if (c == '}') {
349                  return m;
350               } else if (isCommentOrWhitespace(c)) {
351                  skipCommentsAndSpace(r.unread());
352               } else {
353                  r.unread();
354                  mark();
355                  currAttr = readFieldName(r);
356                  state = S3;
357               }
358            } else if (state == S3) {  // NOSONAR - State check necessary for state machine
359               if (c == ':')
360                  state = S4;
361            } else if (state == S4) {
362               if (isCommentOrWhitespace(c)) {
363                  skipCommentsAndSpace(r.unread());
364               } else {
365               if (! currAttr.equals(getBeanTypePropertyName((ClassMeta<?>) m.getBeanInfo()))) {
366                  var pMeta = m.getPropertyMeta(currAttr);
367                  setCurrentProperty(pMeta);
368                  if (pMeta == null) {
369                     onUnknownProperty(currAttr, m, readAnything(object(), r.unread(), m.getBean(false), null));
370                     unmark();
371                  } else {
372                     unmark();
373                     var cm = (ClassMeta<?>) pMeta.getBeanInfo();
374                     Object value = readAnything(cm, r.unread(), m.getBean(false), pMeta);
375                     setName(cm, value, currAttr);
376                        try {
377                           pMeta.set(m, currAttr, value);
378                        } catch (BeanRuntimeException e) {
379                           onBeanSetterException(pMeta, e);
380                           throw e;
381                        }
382                     }
383                     setCurrentProperty(null);
384                  }
385                  state = S5;
386               }
387            } else if (state == S5) {
388               if (c == ',')
389                  state = S2;
390               else if (isCommentOrWhitespace(c))
391                  skipCommentsAndSpace(r.unread());
392               else if (c == '}') {
393                  return m;
394               }
395            }
396         }
397         if (state == S1)
398            throw new ParseException(this, "Expected '{' at beginning of JSON object.");
399         else if (state == S3)
400            throw new ParseException(this, "Could not find ':' following attribute name on JSON object.");
401         else if (state == S5)
402            throw new ParseException(this, "Could not find '}' marking end of JSON object.");
403      } finally {
404         unmark();
405         swapParentBean(pb);
406      }
407
408      return null; // Unreachable.
409   }
410
411   private <E> Collection<E> readIntoCollection2(ParserReader r, Collection<E> l, ClassMeta<?> type, BeanPropertyMeta pMeta) throws IOException, ParseException, ExecutableException {
412
413      // S1: Looking for outermost [
414      // S2: Looking for starting [ or { or " or ' or LITERAL or ]
415      // S3: Looking for , or ]
416      // S4: Looking for starting [ or { or " or ' or LITERAL
417
418      int argIndex = 0;
419
420      var state = S1;
421      int c = 0;
422      while (c != -1) {
423         c = r.read();
424         if (state == S1) {
425            if (c == '[')
426               state = S2;
427            else if (isCommentOrWhitespace(c))
428               skipCommentsAndSpace(r.unread());
429            else
430               break;  // Invalid character found.
431         } else if (state == S2) {
432            if (c == ']') {
433               return l;
434            } else if (isCommentOrWhitespace(c)) {
435               skipCommentsAndSpace(r.unread());
436            } else if (c != -1) {
437               l.add((E)readAnything(type.isArgs() ? type.getArg(argIndex++) : type.getElementType(), r.unread(), l, pMeta));
438               state = S3;
439            }
440         } else if (state == S3) {  // NOSONAR - State check necessary for state machine
441            if (c == ',') {
442               state = S4;
443            } else if (isCommentOrWhitespace(c)) {
444               skipCommentsAndSpace(r.unread());
445            } else if (c == ']') {
446               return l;
447            } else {
448               break;  // Invalid character found.
449            }
450         } else if (state == S4) {
451            if (isCommentOrWhitespace(c)) {
452               skipCommentsAndSpace(r.unread());
453            } else if (c == ']') {
454               if (allowsTrailingComma())
455                  return l;
456               break;
457            } else if (c != -1) {
458               l.add((E)readAnything(type.isArgs() ? type.getArg(argIndex++) : type.getElementType(), r.unread(), l, pMeta));
459               state = S3;
460            }
461         }
462      }
463      if (state == S1)
464         throw new ParseException(this, "Expected '[' at beginning of JSON array.");
465      else if (state == S2)
466         throw new ParseException(this, "Expected one of the following characters: {,[,',\",LITERAL.");
467      else if (state == S3)
468         throw new ParseException(this, "Expected ',' or ']'.");
469      else if (state == S4)
470         throw new ParseException(this, "Unexpected trailing comma in array.");
471
472      return null;  // Unreachable.
473   }
474
475   private <K,V> Map<K,V> readIntoMap2(ParserReader r, Map<K,V> m, ClassMeta<K> keyType, ClassMeta<V> valueType, BeanPropertyMeta pMeta) throws IOException, ParseException, ExecutableException {
476
477      if (keyType == null)
478         keyType = (ClassMeta<K>)string();
479
480      // S1: Looking for outer {
481      // S2: Looking for attrName start.
482      // S3: Found attrName end, looking for :.
483      // S4: Found :, looking for valStart: { [ " ' LITERAL.
484      // S5: Looking for , or }
485      // S6: Found , looking for attr start.
486
487      skipCommentsAndSpace(r);
488      var state = S1;
489      String currAttr = null;
490      int c = 0;
491      while (c != -1) {
492         c = r.read();
493         if (state == S1) {
494            if (c == '{')
495               state = S2;
496            else
497               break;
498         } else if (state == S2) {
499            if (c == '}') {
500               return m;
501            } else if (isCommentOrWhitespace(c)) {
502               skipCommentsAndSpace(r.unread());
503            } else {
504               currAttr = readFieldName(r.unread());
505               state = S3;
506            }
507         } else if (state == S3) {  // NOSONAR - State check necessary for state machine
508            if (c == ':')
509               state = S4;
510         } else if (state == S4) {
511            if (isCommentOrWhitespace(c)) {
512               skipCommentsAndSpace(r.unread());
513            } else {
514               K key = convertAttrToType(m, currAttr, keyType);
515               V value = readAnything(valueType, r.unread(), m, pMeta);
516               setName(valueType, value, key);
517               m.put(key, value);
518               state = S5;
519            }
520         } else if (state == S5) {
521            if (c == ',') {
522               state = S6;
523            } else if (isCommentOrWhitespace(c)) {
524               skipCommentsAndSpace(r.unread());
525            } else if (c == '}') {
526               return m;
527            } else {
528               break;
529            }
530         } else if (state == S6) {
531            if (c == '}') {
532               if (allowsTrailingComma())
533                  return m;
534               break;
535            } else if (isCommentOrWhitespace(c)) {
536               skipCommentsAndSpace(r.unread());
537            } else {
538               currAttr = readFieldName(r.unread());
539               state = S3;
540            }
541         }
542      }
543      if (state == S1)
544         throw new ParseException(this, "Expected '{' at beginning of JSON object.");
545      else if (state == S3)
546         throw new ParseException(this, "Could not find ':' following attribute name on JSON object.");
547      else if (state == S5)
548         throw new ParseException(this, "Could not find '}' marking end of JSON object.");
549      else if (state == S6)
550         throw new ParseException(this, "Unexpected '}' found in JSON object.");
551
552      return null; // Unreachable.
553   }
554
555   /*
556    * Looks for the keywords true, false, or null.
557    * Throws an exception if any of these keywords are not found at the specified position.
558    */
559   protected void readKeyword(String keyword, ParserReader r) throws IOException, ParseException {
560      String s = r.read(keyword.length());
561      if (s.equals(keyword))
562         return;
563      throw new ParseException(this, "Unrecognized syntax.  Expected='%s', Actual='%s'", keyword, s);
564   }
565
566   protected Number readNumber(ParserReader r, Class<? extends Number> type) throws IOException, ParseException {
567      int c = r.peek();
568      if (c == '\'' || c == '"')
569         return readNumber(r, readString(r), type);
570      return readNumber(r, r.readNumberString(), type);
571   }
572
573   @SuppressWarnings({
574      "java:S1172", // r accepted for API consistency; subclasses may use it for position tracking
575      "unused" // r accepted for API consistency; subclasses may use it for position tracking
576   })
577   protected Number readNumber(ParserReader r, String s, Class<? extends Number> type) throws ParseException {
578
579      if (s.isEmpty())
580         throw new ParseException(this, "Invalid JSON number: '%s'", s);
581
582      var isNegative = false;
583      var c = s.charAt(0);
584      if (c == '-') {
585         isNegative = true;
586         c = (s.length() == 1 ? 'x' : s.charAt(1));
587      }
588
589      if (c == '.')
590         throw new ParseException(this, "Invalid JSON number: '%s'", s);
591
592      if (c == '0' && s.length() > (isNegative ? 2 : 1)) {
593         var c2 = s.charAt((isNegative ? 2 : 1));
594         if (c2 != '.' && c2 != 'e' && c2 != 'E')
595            throw new ParseException(this, "Invalid JSON number: '%s'", s);
596      }
597
598      var i = s.indexOf('.');
599      if (i != -1 && (s.length() == (i + 1) || ! decChars.contains(s.charAt(i + 1))))
600         throw new ParseException(this, "Invalid JSON number: '%s'", s);
601
602      return StringUtils.parseNumber(s, type);
603   }
604
605   /*
606    * Starting from the specified position in the character array, returns the
607    * position of the character " or '.
608    * If the string consists of a concatenation of strings (e.g. 'AAA' + "BBB"), this method
609    * will automatically concatenate the strings and return the result.
610    */
611   protected String readString(ParserReader r) throws IOException, ParseException {
612      r.mark();
613      int qc = r.read();
614      if (qc != '"') {
615         var msg = (qc == '\'' ? "Invalid quote character \"%s\" being used." : "Did not find quote character marking beginning of string.  Character=\"%s\"");
616         throw new ParseException(this, msg, (char)qc);
617      }
618      String s = null;
619      boolean isInEscape = false;
620      int c = 0;
621      while (c != -1) {
622         c = r.read();
623         if (c <= 0x1F)
624            throw new ParseException(this, "Unescaped control character encountered: '0x%s'", f("%04X", c));
625         if (isInEscape) {
626            // @formatter:off
627            switch (c) {
628               case 'n': r.replace('\n'); break;
629               case 'r': r.replace('\r'); break;
630               case 't': r.replace('\t'); break;
631               case 'f': r.replace('\f'); break;
632               case 'b': r.replace('\b'); break;
633               case '\\': r.replace('\\'); break;
634               case '/': r.replace('/'); break;
635               case '\'': r.replace('\''); break;
636               case '"': r.replace('"'); break;
637               case 'u': {
638                  String n = r.read(4);
639                  try {
640                     r.replace(Integer.parseInt(n, 16), 6);
641                  } catch (@SuppressWarnings("unused") NumberFormatException e) {
642                     throw new ParseException(this, "Invalid Unicode escape sequence in string.");
643                  }
644                  break;
645               }
646               default:
647                  throw new ParseException(this, "Invalid escape sequence in string.");
648            }
649            // @formatter:on
650            isInEscape = false;
651         } else {
652            if (c == '\\') {
653               isInEscape = true;
654               r.delete();
655            } else if (c == qc) {
656               s = r.getMarked(1, -1);
657               break;
658            }
659         }
660      }
661      skipCommentsAndSpace(r);
662      if (r.peek() == '+')
663         throw new ParseException(this, "String concatenation detected.");
664      return trim(s);
665   }
666
667   /*
668    * Doesn't actually parse anything, but when positioned at the beginning of comment,
669    * it will move the pointer to the last character in the comment.
670    */
671   protected void skipComments(ParserReader r) throws ParseException, IOException {
672      int c = r.read();
673      if (c == '*') {
674         while (c != -1)
675            if ((c = r.read()) == '*' && (c = r.read()) == '/')
676               return;
677      } else if (c == '/') {
678         while (c != -1) {
679            c = r.read();
680            if (c == -1 || c == '\n')
681               return;
682         }
683      }
684      throw new ParseException(this, "Open ended comment.");
685   }
686
687   protected void skipCommentsAndSpace(ParserReader r) throws IOException, ParseException {
688      int c = 0;
689      while ((c = r.read()) != -1) {
690         if (! isWhitespace(c)) {
691            if (c == '/')
692               throw new ParseException(this, "Javascript comment detected.");
693            r.unread();
694            return;
695         }
696      }
697   }
698
699   /*
700    * Doesn't actually parse anything, but moves the position beyond the construct "}" when
701    * the @Json(wrapperAttr) annotation is used on a class.
702    */
703   private void skipWrapperAttrEnd(ParserReader r) throws ParseException, IOException {
704      int c = 0;
705      while ((c = r.read()) != -1) {
706         if (! isWhitespace(c)) {
707            if (c == '/') {
708               throw new ParseException(this, "Javascript comment detected.");
709            } else if (c == '}') {
710               return;
711            } else {
712               throw new ParseException(this, "Could not find '}' at the end of JSON wrapper object.");
713            }
714         }
715      }
716   }
717
718   /*
719    * Doesn't actually parse anything, but moves the position beyond the construct "{wrapperAttr:" when
720    * the @Json(wrapperAttr) annotation is used on a class.
721    */
722   private void skipWrapperAttrStart(ParserReader r, String wrapperAttr) throws IOException, ParseException {
723
724      // S1: Looking for outer '{'
725      // S2: Looking for attrName start.
726      // S3: Found attrName end, looking for :.
727      // S4: Found :, looking for valStart: { [ " ' LITERAL.
728
729      var state = S1;
730      String currAttr = null;
731      int c = 0;
732      while (c != -1) {
733         c = r.read();
734         if (state == S1) {
735            if (c == '{')
736               state = S2;
737         } else if (state == S2) {
738            if (isCommentOrWhitespace(c)) {
739               skipCommentsAndSpace(r.unread());
740            } else {
741               currAttr = readFieldName(r.unread());
742               if (! currAttr.equals(wrapperAttr))
743                  throw new ParseException(this, "Expected to find wrapper attribute '%s' but found attribute '%s'", wrapperAttr, currAttr);
744               state = S3;
745            }
746         } else if (state == S3) {  // NOSONAR - State check necessary for state machine
747            if (c == ':')
748               state = S4;
749         } else if (state == S4) {
750            if (isCommentOrWhitespace(c)) {
751               skipCommentsAndSpace(r.unread());
752            } else {
753               r.unread();
754               return;
755            }
756         }
757      }
758      if (state == S1)
759         throw new ParseException(this, "Expected '{' at beginning of JSON object.");
760      else if (state == S2)
761         throw new ParseException(this, "Could not find attribute name on JSON object.");
762      else
763         throw new ParseException(this, "Could not find ':' following attribute name on JSON object.");
764   }
765
766   /*
767    * Call this method after you've finished a parsing a string to make sure that if there's any
768    * remainder in the input, that it consists only of whitespace and comments.
769    */
770   private void validateEnd(ParserReader r) throws IOException, ParseException {
771      if (! isValidateEnd())
772         return;
773      skipCommentsAndSpace(r);
774      int c = r.read();
775      if (c != -1 && c != ';')  // var x = {...}; expressions can end with a semicolon.
776         throw new ParseException(this, "Remainder after parse: '%s'.", (char)c);
777   }
778
779   @Override /* Overridden from ParserSession */
780   protected <T> T doRead(ParserPipe pipe, ClassMeta<T> type) throws IOException, ParseException, ExecutableException {
781      try (var r = pipe.getParserReader()) {
782         if (r == null)
783            return null;
784         T o = readAnything(type, r, getOuter(), null);
785         validateEnd(r);
786         return o;
787      }
788   }
789
790   /**
791    * Opens a low-level pull-parser cursor over a JSON document, bound to this session's live
792    * {@link BeanSession}/{@link MarshallingContext}.
793    *
794    * <p>
795    * The cursor is purely structural &mdash; object swaps and {@code @Schema} annotations are not
796    * applied at this layer.  See {@link TokenReader} for the contract.
797    *
798    * <h4 class='section'>Builder properties honored:</h4>
799    * The structurally-applicable subset flows through to the cursor: <c>autoCloseStreams</c>,
800    * <c>unbuffered</c>, <c>trimStrings</c> (applied to {@link TokenType#VALUE_STRING} and
801    * {@link TokenType#FIELD_NAME} values), and the {@code ReaderParser} stream/file charsets.
802    *
803    * <h4 class='section'>Builder properties NOT honored:</h4>
804    * <c>validateEnd()</c> (the cursor leaves end-of-input checking to the caller),
805    * <c>listener(...)</c>/<c>debugOutputLines(...)</c>, <c>consumes(...)</c>, object swaps, and
806    * {@code @Schema} annotations (only applied on the POJO databind path).
807    *
808    * @param input The input.  Accepts {@link Reader}, {@link CharSequence}, {@link InputStream},
809    *    or <code><jk>byte</jk>[]</code>.
810    * @return A new {@link JsonTokenReader}.
811    * @throws IOException If a problem occurred opening the underlying input.
812    */
813   @SuppressWarnings({
814      "java:S2095" // ParserPipe lifecycle is transferred to the returned JsonTokenReader, which closes it via its own close(); the caller owns the cursor via try-with-resources.
815   })
816   @Override /* TokenReadable */
817   public TokenReader readTokens(Object input) throws IOException {
818      var pipe = new ParserPipe(
819         input,
820         isDebug(),
821         false /* strict */,
822         isAutoCloseStreams(),
823         isUnbuffered(),
824         getStreamCharset());
825      return new JsonTokenReader(pipe, new JsonTokenReader.Settings(isTrimStrings()), this);
826   }
827
828   /**
829    * Streaming array-element {@link RecordReader} backed by {@link JsonTokenReader}.
830    * Memory is O(1) in the array length &mdash; elements are bound on demand using this live session.
831    *
832    * @param input The input.
833    * @return A new element-streamed {@link RecordReader}.
834    * @throws IOException If a problem occurred opening the underlying input.
835    */
836   @Override /* ArrayRecordReadable */
837   public RecordReader readArrayRecords(Object input) throws IOException {
838      try {
839         return StreamingArrayRecord.reader(readTokens(input));
840      } catch (ParseException e) {
841         throw new IOException(e);
842      }
843   }
844
845   @Override /* Overridden from ReaderParserSession */
846   protected <E> Collection<E> doReadIntoCollection(ParserPipe pipe, Collection<E> c, Type elementType) throws IOException, ParseException, ExecutableException {
847      try (var r = pipe.getParserReader()) {
848         c = readIntoCollection2(r, c, getClassMeta(elementType == null ? Object.class : elementType), null);
849         validateEnd(r);
850         return c;
851      }
852   }
853
854   @Override /* Overridden from ReaderParserSession */
855   protected <K,V> Map<K,V> doReadIntoMap(ParserPipe pipe, Map<K,V> m, Type keyType, Type valueType) throws IOException, ParseException, ExecutableException {
856      try (var r = pipe.getParserReader()) {
857         m = readIntoMap2(r, m, (ClassMeta<K>)getClassMeta(keyType == null ? Object.class : keyType), (ClassMeta<V>)getClassMeta(valueType == null ? Object.class : valueType), null);
858         validateEnd(r);
859         return m;
860      }
861   }
862
863   /**
864    * Returns the language-specific metadata on the specified class.
865    *
866    * @param cm The class to return the metadata on.
867    * @return The metadata.
868    */
869   protected JsonClassMeta getJsonClassMeta(ClassMeta<?> cm) {
870      return ctx.getJsonClassMeta(cm);
871   }
872
873   /**
874    * Returns <jk>true</jk> if the specified character can start a number value.
875    *
876    * <p>
877    * JSON numbers start with a digit, <c>-</c>, or <c>.</c>.  JSON5 subclasses also accept
878    * <c>+</c>, <c>I</c> (<c>Infinity</c>), and <c>N</c> (<c>NaN</c>).
879    *
880    * @param c The next non-whitespace character.
881    * @return <jk>true</jk> if a number lexeme should be read from this character.
882    */
883   protected boolean isNumberStartChar(int c) {
884      return (c >= '0' && c <= '9') || c == '-' || c == '.';
885   }
886
887   /**
888    * Returns <jk>true</jk> if the specified character is whitespace or '/'.
889    *
890    * @param cp The codepoint.
891    * @return <jk>true</jk> if the specified character is whitespace or '/'.
892    */
893   protected boolean isCommentOrWhitespace(int cp) {
894      if (cp == '/')
895         return true;
896      return cp <= 0x20 && (cp == 0x09 || cp == 0x0A || cp == 0x0D || cp == 0x20);
897   }
898
899   /**
900    * Validate end.
901    *
902    * @see JsonParser.Builder#validateEnd()
903    * @return
904    *    <jk>true</jk> if after parsing a POJO from the input, verifies that the remaining input in
905    *    the stream consists of only comments or whitespace.
906    */
907   protected boolean isValidateEnd() { return validateEnd; }
908
909   /**
910    * Returns <jk>true</jk> if the specified character is whitespace.
911    *
912    * <p>
913    * Only 0x20 (space), 0x09 (tab), 0x0A (line feed) and 0x0D (carriage return) are considered whitespace.
914    *
915    * @param cp The codepoint.
916    * @return <jk>true</jk> if the specified character is whitespace.
917    */
918   protected boolean isWhitespace(int cp) {
919      return cp <= 0x20 && (cp == 0x09 || cp == 0x0A || cp == 0x0D || cp == 0x20);
920   }
921
922   /**
923    * Hook called when empty input is detected in {@code readAnything()}.
924    *
925    * @throws ParseException Always in strict mode.
926    */
927   protected void onEmptyInput() throws ParseException {
928      throw new ParseException(this, "Empty input.");
929   }
930
931   /**
932    * Hook called when a missing value is detected in {@code readAnything()}.
933    *
934    * @throws ParseException Always in strict mode.
935    */
936   protected void onMissingValue() throws ParseException {
937      throw new ParseException(this, "Missing value detected.");
938   }
939
940   /**
941    * Returns whether trailing commas are accepted before <c>]</c> / <c>}</c> in the databind path.
942    *
943    * <p>
944    * Default returns <jk>false</jk> (strict RFC-8259 JSON).  {@code Json5ParserSession} overrides
945    * this to <jk>true</jk> for the JSON5 dialect.
946    *
947    * @return <jk>true</jk> if a trailing comma should be silently accepted.
948    */
949   protected boolean allowsTrailingComma() {
950      return false;
951   }
952
953   /**
954    * Returns whether non-string types can be coerced to strings using {@code newInstanceFromString()}.
955    *
956    * @return Always {@code false} for standard JSON.
957    */
958   protected boolean canCoerceNonStringToString() {
959      return false;
960   }
961
962   @Override /* Overridden from MarshallingSession */
963   protected MarshalledMap newGenericMap() {
964      return new JsonMap(this);
965   }
966
967   @Override /* Overridden from MarshallingSession */
968   protected MarshalledList newGenericList() {
969      return new JsonList(this);
970   }
971}