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.urlencoding;
018
019import static org.apache.juneau.commons.lang.StateEnum.*;
020import static org.apache.juneau.commons.utils.Shorts.*;
021
022import java.io.*;
023import java.lang.reflect.*;
024import java.util.*;
025
026import org.apache.juneau.commons.bean.*;
027import org.apache.juneau.commons.reflect.*;
028import org.apache.juneau.commons.utils.*;
029import org.apache.juneau.marshall.*;
030import org.apache.juneau.marshall.collections.*;
031import org.apache.juneau.marshall.parser.*;
032import org.apache.juneau.marshall.swap.spi.*;
033import org.apache.juneau.marshall.uon.*;
034
035/**
036 * Session object that lives for the duration of a single use of {@link UrlEncodingParser}.
037 *
038 * <h2 class='section'>Notes:</h2><ul>
039 *    <li class='warn'>This class is not thread safe and is typically discarded after one use.
040 * </ul>
041 *
042 * <h2 class='section'>See Also:</h2><ul>
043 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/UrlEncodingSupport">URL-Encoding</a>
044 * </ul>
045 */
046@SuppressWarnings({
047   "java:S110", // Inheritance depth acceptable for session hierarchy
048   "java:S115", // Constants use UPPER_snakeCase convention (e.g., CONST_value)
049   "java:S1168", // readIntoBeanMap()/readIntoMap2() return null for blank or literal null input, which callers treat as 'no value'.
050   "java:S1192", // Duplicated literals (argument/property names) read more clearly inline than as constants
051   "java:S3776", // readAnything(), readIntoBeanMap() and readIntoMap2() are state machines over the URL-encoded grammar; splitting them would obscure the parse flow.
052   "rawtypes", // Raw types necessary for generic type handling
053   "resource", // UonReader is managed by caller
054   "unchecked", // Type erasure requires unchecked casts
055   "unused" // Intentionally unused; variable/parameter is required by the interface contract
056})
057public class UrlEncodingParserSession extends UonParserSession {
058
059   /**
060    * Builder class.
061    */
062   public static class Builder extends UonParserSession.Builder<Builder> {
063
064      private boolean expandedParams;
065      private final UrlEncodingParser ctx;
066
067      /**
068       * Constructor
069       *
070       * @param ctx The context creating this session.
071       *    <br>Cannot be <jk>null</jk>.
072       */
073      protected Builder(UrlEncodingParser ctx) {
074         super(ctx);
075         this.ctx = ctx;
076         expandedParams = ctx.isExpandedParams();
077      }
078
079      @Override
080      public UrlEncodingParserSession build() {
081         return new UrlEncodingParserSession(this);
082      }
083
084      /**
085       * Serialize bean property collections/arrays as separate key/value pairs.
086       *
087       * @param value The new value for this setting.
088       * @return This object.
089       */
090      public Builder expandedParams(boolean value) {
091         expandedParams = value;
092         return this;
093      }
094
095      @Override /* Overridden from Builder */
096      public Builder property(String key, Object value) {
097         if (key == null) { super.property(key, value); return this; }
098         switch (key) {
099            case "expandedParams", "UrlEncodingParserSession.expandedParams":
100               return expandedParams(cvt(value, Boolean.class));
101            default:
102               super.property(key, value);
103               return this;
104         }
105      }
106
107   }
108
109   /**
110    * Creates a new builder for this object.
111    *
112    * @param ctx The context creating this session.
113    *    <br>Cannot be <jk>null</jk>.
114    * @return A new builder.
115    */
116   public static Builder create(UrlEncodingParser ctx) {
117      return new Builder(ctx);
118   }
119
120   private final UrlEncodingParser ctx;
121   private final boolean expandedParams;
122
123   /**
124    * Constructor.
125    *
126    * @param builder The builder for this object.
127    */
128   public UrlEncodingParserSession(Builder builder) {
129      super(builder);
130      ctx = builder.ctx;
131      expandedParams = builder.expandedParams;
132   }
133
134   /**
135    * Returns <jk>true</jk> if the specified bean property should be expanded as multiple key-value pairs.
136    *
137    * @param pMeta The metadata on the bean property.
138    * @return <jk>true</jk> if the specified bean property should be expanded as multiple key-value pairs.
139    */
140   public final boolean shouldUseExpandedParams(BeanPropertyMeta pMeta) {
141      var cm = ((ClassMeta<?>) pMeta.getBeanInfo()).getSerializedClassMeta(this);
142      return cm.isCollectionOrArray() && (isExpandedParams() || getUrlEncodingClassMeta((ClassMeta<?>) pMeta.getBeanMeta().getBeanInfo()).isExpandedParams());
143   }
144
145   private <T> T readAnything(ClassMeta<T> eType, UonReader r, Object outer) throws IOException, ParseException, ExecutableException {
146      enterParseDepth();
147      try {
148         return readAnything0(eType, r, outer);
149      } finally {
150         exitParseDepth();
151      }
152   }
153
154   // Workhorse method, wrapped by readAnything() with the recursion-depth guard.
155   private <T> T readAnything0(ClassMeta<T> eType, UonReader r, Object outer) throws IOException, ParseException, ExecutableException {
156
157      if (eType == null)
158         eType = (ClassMeta<T>)object();
159      var swap = (ObjectSwap<T,Object>)eType.getSwap(this);
160      var builder = (BuilderSwap<T,Object>)eType.getBuilderSwap(this);
161      ClassMeta<?> sType = null;
162      if (nn(builder))
163         sType = builder.getBuilderClassMeta(this);
164      else if (nn(swap))
165         sType = swap.getSwapClassMeta(this);
166      else
167         sType = eType;
168
169      if (sType.isOptional())
170         return (T)o(readAnything(eType.getElementType(), r, outer));
171
172      int c = r.peekSkipWs();
173      if (c == '?') {
174         int ignored = r.read();
175      }
176
177      Object o;
178
179      if (sType.isObject()) {
180         var m = newGenericMap();
181         readIntoMap2(r, m, getClassMeta(Map.class, String.class, Object.class), outer);
182         if (m.containsKey("_value"))
183            o = m.get("_value");
184         else
185            o = cast(m, null, eType);
186      } else if (nn(builder)) {
187         var m = toBeanMap(builder.create(this, eType));
188         m = readIntoBeanMap(r, m);
189         o = m == null ? null : builder.build(this, checkRequired(m).getBean(), eType);
190      } else if (sType.canCreateNewBean(outer)) {
191         var m = newBeanMap(outer, sType.inner());
192         m = readIntoBeanMap(r, m);
193         o = m == null ? null : checkRequired(m).getBean();
194      } else if (sType.isMap()) {
195         var m = (sType.canCreateNewInstance() ? (Map)sType.newInstance() : newGenericMap(sType));
196         o = readIntoMap2(r, m, sType, m);
197      } else if (sType.isCollection() || sType.isArray() || sType.isArgs()) {
198         // ?1=foo&2=bar...
199         var c2 = ((sType.isArray() || sType.isArgs()) || ! sType.canCreateNewInstance(outer)) ? newGenericList() : (Collection)sType.newInstance();
200         var m = new TreeMap<Integer,Object>();
201         readIntoMap2(r, m, sType, c2);
202         c2.addAll(m.values());
203         if (sType.isArgs())
204            o = c2.toArray(new Object[c2.size()]);
205         else if (sType.isArray())
206            o = CollectionUtils.toArray(c2, sType.getElementType().inner());
207         else
208            o = c2;
209      } else {
210         // It could be a non-bean with _type attribute.
211         var m = newGenericMap();
212         readIntoMap2(r, m, getClassMeta(Map.class, String.class, Object.class), outer);
213         if (m.containsKey(getBeanTypePropertyName(eType)))
214            o = cast(m, null, eType);
215         else if (m.containsKey("_value"))
216            o = unwrapValueAs(m.get("_value"), sType);
217         else if (nn(sType.getProxyInvocationHandler())) {
218            o = checkRequired(newBeanMap(outer, sType.inner()).load(m)).getBean();
219         } else {
220            if (nn(sType.getNotABeanReason()))
221               throw new ParseException(this, "Class '%s' could not be instantiated as application/x-www-form-urlencoded.  Reason: '%s'", sType, sType.getNotABeanReason());
222            throw new ParseException(this, "Malformed application/x-www-form-urlencoded input for class '%s'.", sType);
223         }
224      }
225
226      if (nn(swap) && nn(o))
227         o = unswap(swap, o, eType);
228
229      if (nn(parentBean()))
230         setParent(eType, o, parentBean());
231
232      return (T)o;
233   }
234
235   @SuppressWarnings({
236      "java:S125", // State-machine comments (S1: ..., S2: ...)
237      "java:S2177", // Intentional: UrlEncodingParserSession provides its own private readIntoBeanMap() with expanded-params logic
238      "java:S2583", // State variables persist across loop iterations
239      "java:S2589", // Final if (state==S4) is always true given prior checks; exhaustive state error-reporting pattern
240      "java:S6541" // Single-threaded session contexts do not require synchronization
241   })
242   private <T> BeanMap<T> readIntoBeanMap(UonReader r, BeanMap<T> m) throws IOException, ParseException, ExecutableException {
243
244      int c = r.peekSkipWs();
245      if (c == -1)
246         return m;
247
248      // S1: Looking for attrName start.
249      // S2: Found attrName end, looking for =.
250      // S3: Found =, looking for valStart.
251      // S4: Looking for , or }
252
253      boolean isInEscape = false;
254
255      var state = S1;
256      var currAttr = "";
257      var pb = swapParentBean(m.getBean(false));
258      mark();
259      try {
260         while (c != -1) {
261            c = r.read();
262            if (! isInEscape) {
263               if (state == S1) {
264                  if (c == -1) {
265                     return m;
266                  }
267                  r.unread();
268                  mark();
269                  currAttr = readAttrName(r, true);
270                  if (currAttr == null)  // Value was '%00'
271                     return null;
272                  state = S2;
273               } else if (state == S2) {
274                  if (c == '\u0002')
275                     state = S3;
276                  else if (c == -1 || c == '\u0001') {
277                     m.put(currAttr, null);
278                     if (c == -1)
279                        return m;
280                     state = S1;
281                  }
282               } else if (state == S3) {  // NOSONAR - State check necessary for state machine
283                  if (c == -1 || c == '\u0001') {
284                     if (! currAttr.equals(getBeanTypePropertyName((ClassMeta<?>) m.getBeanInfo()))) {
285                        var pMeta = m.getPropertyMeta(currAttr);
286                        if (pMeta == null) {
287                           onUnknownProperty(currAttr, m, null);
288                           unmark();
289                        } else {
290                           unmark();
291                           setCurrentProperty(pMeta);
292                           // In cases of "&foo=", create an empty instance of the value if createable.
293                           // Otherwise, leave it null.  Arrays (especially primitive arrays
294                           // such as byte[]) report canCreateNewInstance()=false because their
295                           // element type has no no-arg constructor, but ClassMeta.newInstance()
296                           // already handles arrays via Array.newInstance(...,0); fall through
297                           // to that path so empty expanded-params arrays round-trip from the
298                           // "key=" sentinel emitted by the serializer.
299                           var cm = (ClassMeta<?>) pMeta.getBeanInfo();
300                           if (cm.canCreateNewInstance() || cm.isArray()) {
301                              try {
302                                 pMeta.set(m, currAttr, cm.newInstance());
303                              } catch (BeanRuntimeException e) {
304                                 onBeanSetterException(pMeta, e);
305                                 throw e;
306                              }
307                           }
308                           setCurrentProperty(null);
309                        }
310                     }
311                     if (c == -1)
312                        return m;
313                     state = S1;
314                  } else {
315                     if (! currAttr.equals(getBeanTypePropertyName((ClassMeta<?>) m.getBeanInfo()))) {
316                        var pMeta = m.getPropertyMeta(currAttr);
317                        if (pMeta == null) {
318                           onUnknownProperty(currAttr, m, readAnything(object(), r.unread(), m.getBean(false), true, null));
319                           unmark();
320                        } else {
321                           unmark();
322                           setCurrentProperty(pMeta);
323                           if (shouldUseExpandedParams(pMeta)) {
324                              var et = ((ClassMeta<?>) pMeta.getBeanInfo()).getElementType();
325                              var value = readAnything(et, r.unread(), m.getBean(false), true, pMeta);
326                              setName(et, value, currAttr);
327                              try {
328                                 pMeta.add(m, currAttr, value);
329                              } catch (BeanRuntimeException e) {
330                                 onBeanSetterException(pMeta, e);
331                                 throw e;
332                              }
333                           } else {
334                              var cm = (ClassMeta<?>) pMeta.getBeanInfo();
335                              var value = readAnything(cm, r.unread(), m.getBean(false), true, pMeta);
336                              setName(cm, value, currAttr);
337                              try {
338                                 pMeta.set(m, currAttr, value);
339                              } catch (BeanRuntimeException e) {
340                                 onBeanSetterException(pMeta, e);
341                                 throw e;
342                              }
343                           }
344                           setCurrentProperty(null);
345                        }
346                     }
347                     state = S4;
348                  }
349               } else if (state == S4) {
350                  if (c == '\u0001')
351                     state = S1;
352                  else if (c == -1) {
353                     return m;
354                  }
355               }
356            }
357            isInEscape = (c == '\\' && ! isInEscape);
358         }
359         if (state == S1)
360            throw new ParseException(this, "Could not find attribute name on object.");
361         if (state == S2)
362            throw new ParseException(this, "Could not find '=' following attribute name on object.");
363         if (state == S3)
364            throw new ParseException(this, "Could not find value following '=' on object.");
365         if (state == S4)
366            throw new ParseException(this, "Could not find end of object.");
367      } finally {
368         unmark();
369         swapParentBean(pb);
370      }
371
372      return null; // Unreachable.
373   }
374
375   private <K,V> Map<K,V> readIntoMap2(UonReader r, Map<K,V> m, ClassMeta<?> type, Object outer) throws IOException, ParseException, ExecutableException {
376
377      var keyType = (ClassMeta<K>)(type.isArgs() || type.isCollectionOrArray() ? getClassMeta(Integer.class) : type.getKeyType());
378
379      int c = r.peekSkipWs();
380      if (c == -1)
381         return m;
382
383      // S1: Looking for attrName start.
384      // S2: Found attrName end, looking for =.
385      // S3: Found =, looking for valStart.
386      // S4: Looking for & or end.
387
388      boolean isInEscape = false;
389
390      var state = S1;
391      int argIndex = 0;
392      K currAttr = null;
393      while (c != -1) {
394         c = r.read();
395         if (! isInEscape) {
396            if (state == S1) {
397               if (c == -1)
398                  return m;
399               r.unread();
400               var attr = readAttr(r, true);
401               currAttr = attr == null ? null : convertAttrToType(m, trim(attr.toString()), keyType);
402               state = S2;
403               c = 0; // Avoid isInEscape if c was '\'
404            } else if (state == S2) {
405               if (c == '\u0002')
406                  state = S3;
407               else if (c == -1 || c == '\u0001') {
408                  m.put(currAttr, null);
409                  if (c == -1)
410                     return m;
411                  state = S1;
412               }
413            } else if (state == S3) {
414               if (c == -1 || c == '\u0001') {
415                  ClassMeta<V> valueType;
416                  if (type.isArgs()) {
417                     valueType = (ClassMeta<V>)type.getArg(argIndex++);
418                  } else if (type.isCollectionOrArray()) {
419                     valueType = (ClassMeta<V>)type.getElementType();
420                  } else {
421                     valueType = (ClassMeta<V>)type.getValueType();
422                  }
423                  V value = convertAttrToType(m, "", valueType);
424                  m.put(currAttr, value);
425                  if (c == -1)
426                     return m;
427                  state = S1;
428               } else {
429                  // For performance, we bypass readAnything for string values.
430                  ClassMeta<V> valueType;
431                  if (type.isArgs()) {
432                     valueType = (ClassMeta<V>)type.getArg(argIndex++);
433                  } else if (type.isCollectionOrArray()) {
434                     valueType = (ClassMeta<V>)type.getElementType();
435                  } else {
436                     valueType = (ClassMeta<V>)type.getValueType();
437                  }
438                  V value = (V)(valueType.isString() ? super.readString(r.unread(), true) : super.readAnything(valueType, r.unread(), outer, true, null));
439
440                  // If we already encountered this parameter, turn it into a list.
441                  if (m.containsKey(currAttr) && valueType.isObject()) {
442                     Object v2 = m.get(currAttr);
443                     if (! (v2 instanceof MarshalledList)) {
444                        v2 = new JsonList(v2).setBeanSession(this);
445                        m.put(currAttr, (V)v2);
446                     }
447                     ((MarshalledList)v2).add(value);
448                  } else {
449                     m.put(currAttr, value);
450                  }
451                  state = S4;
452                  c = 0; // Avoid isInEscape if c was '\'
453               }
454            } else if (state == S4) {
455               if (c == '\u0001')
456                  state = S1;
457               else if (c == -1) {
458                  return m;
459               }
460            }
461         }
462         isInEscape = (c == '\\' && ! isInEscape);
463      }
464      if (state == S1)
465         throw new ParseException(this, "Could not find attribute name on object.");
466      if (state == S2)
467         throw new ParseException(this, "Could not find '=' following attribute name on object.");
468      if (state == S3)
469         throw new ParseException(this, "Dangling '=' found in object entry");
470      if (state == S4)
471         throw new ParseException(this, "Could not find end of object.");
472
473      return null; // Unreachable.
474   }
475
476   @Override /* Overridden from ParserSession */
477   protected <T> T doRead(ParserPipe pipe, ClassMeta<T> type) throws IOException, ParseException, ExecutableException {
478      try (var r = getUonReader(pipe, true)) {
479         return readAnything(type, r, getOuter());
480      }
481   }
482
483   @Override /* Overridden from ReaderParserSession */
484   protected <K,V> Map<K,V> doReadIntoMap(ParserPipe pipe, Map<K,V> m, Type keyType, Type valueType) throws Exception {
485      try (var r = getUonReader(pipe, true)) {
486         if (r.peekSkipWs() == '?') {
487            int ignored = r.read();
488         }
489         m = readIntoMap2(r, m, getClassMeta(Map.class, keyType, valueType), null);
490         return m;
491      }
492   }
493
494   /**
495    * Returns the language-specific metadata on the specified class.
496    *
497    * @param cm The class to return the metadata on.
498    * @return The metadata.
499    */
500   protected UrlEncodingClassMeta getUrlEncodingClassMeta(ClassMeta<?> cm) {
501      return ctx.getUrlEncodingClassMeta(cm);
502   }
503
504   /**
505    * Routes the {@code _value=...} top-level unwrap through the format-aware
506    * Duration/Period/Date/Calendar/Temporal parsers when the target type is one of those
507    * date/time/duration cluster types.  Otherwise falls through to the generic
508    * {@link #convertToType(Object, ClassMeta)} path.
509    *
510    * <p>
511    * Without this routing the inner value (typically a {@link Number} parsed from a bare wire
512    * literal) is converted via the generic {@code Number → T} coercion which does not consult
513    * {@link MarshallingContext#getDurationFormat()} / {@code getTemporalFormat()} etc., so the
514    * configured wire format hint (NANOS, ISO_YEAR, MILLIS, …) is silently dropped.
515    */
516   private <T> Object unwrapValueAs(Object rawValue, ClassMeta<T> sType) {
517      if (rawValue != null) {
518         if (sType.isDuration())
519            return readDuration(rawValue.toString());
520         if (sType.isPeriod())
521            return readPeriod(rawValue.toString());
522         if (sType.isDate())
523            return readDate(rawValue.toString(), sType);
524         if (sType.isCalendar())
525            return readCalendar(rawValue.toString(), sType);
526         if (sType.isTemporal())
527            return readTemporal(rawValue.toString(), sType);
528      }
529      return convertToType(rawValue, sType);
530   }
531
532   /**
533    * Parse bean property collections/arrays as separate key/value pairs.
534    *
535    * @see UrlEncodingParser.Builder#expandedParams()
536    * @return
537    * <jk>false</jk> if serializing the array <c>[1,2,3]</c> results in <c>?key=$a(1,2,3)</c>.
538    * <br><jk>true</jk> if serializing the same array results in <c>?key=1&amp;key=2&amp;key=3</c>.
539    */
540   protected final boolean isExpandedParams() { return expandedParams; }
541}