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.commons.svl;
018
019import static org.apache.juneau.commons.reflect.ReflectionUtils.*;
020import static org.apache.juneau.commons.utils.ClassUtils.*;
021import static org.apache.juneau.commons.utils.CollectionUtils.*;
022import static org.apache.juneau.commons.utils.Shorts.*;
023import static org.apache.juneau.commons.utils.ThrowableUtils.*;
024
025import java.io.*;
026import java.lang.reflect.*;
027import java.util.*;
028import java.util.function.*;
029
030import org.apache.juneau.commons.collections.*;
031import org.apache.juneau.commons.inject.*;
032import org.apache.juneau.commons.lang.*;
033import org.apache.juneau.commons.utils.*;
034
035/**
036 * A var resolver session that combines a {@link VarResolver} with one or more session objects.
037 *
038 * <p>
039 * Instances of this class are considered light-weight and fast to construct, use, and discard.
040 *
041 * <p>
042 * This class contains the workhorse code for var resolution.
043 *
044 * <p>
045 * Instances of this class are created through the {@link VarResolver#createSession()} and
046 * {@link VarResolver#createSession(WritableBeanStore)} methods.
047 *
048 * <h2 class='section'>Notes:</h2><ul>
049 *    <li class='warn'>This class is not guaranteed to be thread safe.
050 * </ul>
051 *
052 * <h2 class='section'>See Also:</h2><ul>
053 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/MarshallSimpleVariableLanguage">Marshall Simple Variable Language</a>
054 * </ul>
055 */
056@SuppressWarnings({
057   "java:S1192", // Duplicated literals (argument/property names) read more clearly inline than as constants
058   "resource" // VarResolver resources managed by calling code
059})
060public class VarResolverSession {
061
062   private static boolean containsVars(Collection<?> c) {
063      var f = Flag.create();
064      c.forEach(x -> {
065         if (x instanceof CharSequence && x.toString().contains("$"))
066            f.set();
067      });
068      return f.isSet();
069   }
070
071   private static boolean containsVars(Map<?,?> m) {
072      var f = Flag.create();
073      m.forEach((k, v) -> {
074         if (v instanceof CharSequence && v.toString().contains("$"))
075            f.set();
076      });
077      return f.isSet();
078   }
079
080   private static boolean containsVars(Object array) {
081      for (var i = 0; i < Array.getLength(array); i++) {
082         var o = Array.get(array, i);
083         if (o instanceof CharSequence && o.toString().contains("$"))
084            return true;
085      }
086      return false;
087   }
088
089   private static final Set<String> HTML_DOC_PASSTHROUGH_VARS = Set.of("W", "C", "RS");
090
091   private static final Set<String> SCRIPT_STYLE_REFUSED_VARS = Set.of("RQ", "RH", "RF", "RP", "RA", "SA", "R");
092
093   private final VarResolver context;
094
095   private final WritableBeanStore beanStore;
096
097   private int recursionDepth;
098   private int resolveDepth;
099   private int budgetSegments;
100   private long budgetChars;
101
102   // Per top-level resolve() work caps: bound the total variable substitutions and the text they produce.
103   static final int MAX_SEGMENTS = 10_000;
104   static final long MAX_OUTPUT_CHARS = 1L << 20;
105
106   /** Number of {@code ${...}} references inside {@code #{...}} currently being resolved on this session. */
107   private int exprVarDepth;
108
109   private boolean htmlDocEncode;
110
111   private boolean scriptStyleRefuse;
112
113   private Function<Object,String> valueFormatter;
114   private Function<String,Object> scope;
115
116   /**
117    * Constructor.
118    *
119    * @param context
120    *    The {@link VarResolver} context object that contains the {@link Var Vars} and context objects associated with
121    *    that resolver.
122    * @param beanStore The bean store to use for resolving beans needed by vars.  Can be <jk>null</jk> (this session will then have no parent bean store, and only beans explicitly added via {@link #bean(Class, Object)} will be resolvable).
123    *
124    */
125   public VarResolverSession(VarResolver context, WritableBeanStore beanStore) {
126      this.context = context;
127      this.beanStore = new BasicBeanStore(beanStore);
128   }
129
130   /**
131    * Looks up a registered function by exact name.
132    *
133    * <p>
134    * Functions excluded by {@link VarResolver.Builder#allowFunctions(String...)} are not returned, so a
135    * <jk>null</jk> result means absent <i>or denied</i>; use {@link #isFunctionDenied(String)} to tell them apart.
136    *
137    * @param name The function name.
138    * @return The function, or <jk>null</jk> if none is registered under that name (or it is not allowed).
139    */
140   public VarFunction findFunction(String name) { return context.findFunction(name); }
141
142   /**
143    * Returns <jk>true</jk> if the named function (or operator) is excluded by the resolver's allowlist.
144    *
145    * @param name The function name (e.g. <js>"upper"</js> or <js>"$op.add"</js>).
146    * @return <jk>true</jk> if the name was registered and filtered out by the allowlist, or is an <c>$op.*</c> name the allowlist does not permit.
147    */
148   public boolean isFunctionDenied(String name) { return context.isDenied(name) || (name.startsWith("$op.") && ! context.isAllowed(name)); }
149
150   /**
151    * Resolves a <c>${Type:body}</c> reference to a typed value for the expression evaluator.
152    *
153    * <p>
154    * Finds the var by prefix and returns <c>var.doResolveValue(session, body)</c>, so defaults ({@link DefaultingVar})
155    * and multipart keys are honoured.  The body is resolved with the existing nested-marker machinery first when the
156    * var allows nesting and the body contains a <c>$</c>.  The {@link #resolveScriptStyle(String)} refusal and the
157    * {@link #resolveHtmlDoc(String)} encoding apply exactly as they do to template <c>${...}</c> references: under
158    * HTML-doc encoding a value from a non-passthrough var is escaped, and a non-<c>String</c> value other than a
159    * <c>Number</c> or <c>Boolean</c> is first converted with <c>String.valueOf</c> (as the template path does), so
160    * markup inside a collection or bean cannot bypass the escaping.
161    *
162    * @param prefix The var name (e.g. <js>"S"</js>).
163    * @param body The var body (already in the var's own syntax, e.g. <js>"key,default"</js>).
164    * @return The value, or <jk>null</jk> if absent or (lenient mode) the var is unknown.
165    * @throws VarResolverException If the var is unknown and the resolver is strict, or the var fails.
166    */
167   Object resolveValue(String prefix, String body) {
168      var v = isScriptStyleRefused(prefix) ? null : getVar(prefix);
169      if (v == null) {
170         if (context.strict)
171            throw new VarResolverException("Unknown or unavailable variable '%s'", prefix);
172         return null;
173      }
174      try {
175         var b = (v.allowNested() && body.indexOf('$') != -1) ? resolve(body) : body;
176         var r = v.doResolveValue(this, b);
177         // HTML-doc chrome: values are escaped unless the var is an HTML passthrough, as in templates.
178         if (! htmlDocEncode || r == null || r instanceof Number || r instanceof Boolean)
179            return r;
180         return applyHtmlDocChromeEncoding(prefix, r instanceof String s2 ? s2 : String.valueOf(r));
181      } catch (VarResolverException e) {
182         throw e;
183      } catch (Exception e) {
184         throw new VarResolverException(e, "Problem occurred resolving variable '%s': %s", prefix, e.getMessage());
185      }
186   }
187
188   /**
189    * Overrides the value formatter for this session.
190    *
191    * <p>
192    * The override <em>replaces</em> the resolver's formatter and also formats {@link Structure} values.
193    *
194    * @param value The formatter.  <jk>null</jk> reverts to the resolver's formatter.
195    * @return This object.
196    */
197   public VarResolverSession valueFormatter(Function<Object,String> value) {
198      this.valueFormatter = value;
199      return this;
200   }
201
202   /**
203    * Sets the render scope for this session.
204    *
205    * <p>
206    * Bare identifiers inside <c>#{...}</c> expressions (outside any <c>.?[...]</c> / <c>.![...]</c> element) are looked
207    * up through this function.  A <jk>null</jk> result means the name is absent.  Inside a projection the element is the
208    * innermost scope and this function is the fallback for names the element lacks.
209    *
210    * <p>
211    * Expressions that contain identifiers are never folded at compile time, so a scope can differ per session.
212    * core <c>${...}</c> references do not read this scope; a resolver can register a var (such as the template layer's <c>P</c> var) that does.
213    *
214    * @param value The scope lookup.  <jk>null</jk> clears the scope (every identifier is absent).
215    * @return This object.
216    */
217   public VarResolverSession scope(Function<String,Object> value) {
218      this.scope = value;
219      return this;
220   }
221
222   /**
223    * Returns the render scope.
224    *
225    * @return The render scope, or an always-absent scope if none was set.  Never <jk>null</jk>.
226    */
227   public Function<String,Object> scope() { return scope == null ? ExprSegment.EMPTY_SCOPE : scope; }
228
229   /**
230    * Formats the typed result of an expression as text.
231    *
232    * @param value The value.  May be <jk>null</jk>.
233    * @return The text; never <jk>null</jk>.
234    */
235   public String formatValue(Object value) {
236      String r;
237      if (valueFormatter != null)
238         r = valueFormatter.apply(value);
239      else if (value instanceof Structure)
240         r = value.toString();
241      else
242         r = context.valueFormatter.apply(value);
243      return r == null ? "" : r;
244   }
245
246   /** @return The maximum collection size for expressions, and for the functions that build lists, tables and joins. */
247   public int maxCollectionSize() { return context.maxCollectionSize; }
248
249   /** @return The maximum expression nesting depth. */
250   int maxExprDepth() { return context.maxExprDepth; }
251
252   /**
253    * Enters a {@code ${...}} reference inside {@code #{...}}.
254    *
255    * <p>
256    * Such references compile their body lazily, so a deep {@code #{${...#{${...}}...}}} chain would recurse at
257    * evaluation time.  The chain is capped at {@code maxExprDepth}; every successful call must be paired with
258    * {@link #exitExprVar()}.
259    *
260    * @return <jk>false</jk> (and no depth change) if the cap is reached.
261    */
262   boolean enterExprVar() {
263      if (exprVarDepth >= context.maxExprDepth)
264         return false;
265      exprVarDepth++;
266      return true;
267   }
268
269   /** Leaves a reference entered with {@link #enterExprVar()}. */
270   void exitExprVar() {
271      exprVarDepth--;
272   }
273
274   /**
275    * Returns whether the owning resolver is in strict mode.
276    *
277    * @return <jk>true</jk> if strict.
278    */
279   public boolean isStrict() { return context.strict; }
280
281   /**
282    * Adds a bean to this session.
283    *
284    * @param <T> The bean type.
285    * @param c The bean type.
286    * @param value The bean.
287    * @return This object.
288    */
289   public <T> VarResolverSession bean(Class<T> c, T value) {
290      beanStore.addBean(c, value);
291      return this;
292   }
293
294   /**
295    * Returns the bean from the registered bean store.
296    *
297    * @param <T> The value type.
298    * @param c The bean type.
299    * @return
300    *    The bean.
301    *    <br>Never <jk>null</jk>.
302    */
303   public <T> Optional<T> getBean(Class<T> c) {
304      Optional<T> t = beanStore.getBean(c);
305      if (! t.isPresent())
306         t = context.beanStore.getBean(c);
307      return t;
308   }
309
310   /**
311    * Resolve all variables in the specified string.
312    *
313    * @param s
314    *    The string to resolve variables in.  Can be <jk>null</jk> (returns <jk>null</jk>).
315    * @return
316    *    The new string with all variables resolved, or the same string if no variables were found.
317    *    <br>Returns <jk>null</jk> if the input was <jk>null</jk>.
318    */
319   public String resolve(String s) {
320      if (s == null)
321         return null;
322      if (s.isEmpty())
323         return s;
324      if (resolveDepth++ == 0) {
325         budgetSegments = 0;
326         budgetChars = 0;
327      }
328      try {
329         return context.compile(s).resolve(this);
330      } finally {
331         resolveDepth--;
332      }
333   }
334
335   /**
336    * Charges one variable substitution of the given size against this resolve's work budget.
337    *
338    * @param chars The number of characters produced by the substitution.
339    * @throws VarResolverException If the budget is exhausted.
340    */
341   void charge(int chars) {
342      budgetChars += chars;
343      if (++budgetSegments > MAX_SEGMENTS || budgetChars > MAX_OUTPUT_CHARS)
344         throw new VarResolverException("Variable resolution work limit exceeded (%s substitutions, %s characters).", MAX_SEGMENTS, MAX_OUTPUT_CHARS);
345   }
346
347   /**
348    * Re-resolves a var's output, enforcing the resolver's maximum recursion depth.
349    *
350    * @param s The string to resolve.
351    * @return The resolved string.
352    * @throws VarResolverException If the maximum recursion depth is exceeded.
353    */
354   String resolveRecursive(String s) {
355      if (++recursionDepth > context.maxRecursionDepth) {
356         recursionDepth--;
357         throw new VarResolverException("Maximum variable recursion depth (%s) exceeded while resolving '%s'", context.maxRecursionDepth, s.length() > 80 ? s.substring(0, 80) + "..." : s);
358      }
359      try {
360         return resolve(s);
361      } finally {
362         recursionDepth--;
363      }
364   }
365
366   /**
367    * Resolves SVL variables for HTML-doc chrome fields that write raw HTML.
368    *
369    * <p>
370    * Literal characters from the template (including tags) pass through unchanged. Each SVL
371    * substitution is XML-escaped via {@link StringUtils#escapeXml(String)} before insert, except
372    * the HTML-passthrough vars {@code $W}, {@code $C}, and {@code $RS}.
373    *
374    * <p>
375    * Plain {@link #resolve(String)} is unchanged. Use this only for HTML-doc chrome (aside, header,
376    * footer, nav HTML fragments, head, no-results).
377    *
378    * @param s The chrome template. Can be <jk>null</jk>.
379    * @return The resolved chrome string, or <jk>null</jk> if the input was <jk>null</jk>.
380    */
381   public String resolveHtmlDoc(String s) {
382      htmlDocEncode = true;
383      try {
384         return resolve(s);
385      } finally {
386         htmlDocEncode = false;
387      }
388   }
389
390   /**
391    * Resolves SVL variables for {@code <script>} and {@code <style>} chrome.
392    *
393    * <p>
394    * Request-derived vars ({@code $RQ}, {@code $RH}, {@code $RF}, {@code $RP}, {@code $RA},
395    * {@code $SA}, {@code $R}) are left unresolved (same as an unknown var). Other vars including
396    * {@code $W}, {@code $C}, and {@code $RS} still resolve.
397    *
398    * @param s The script or style template. Can be <jk>null</jk>.
399    * @return The resolved string, or <jk>null</jk> if the input was <jk>null</jk>.
400    */
401   public String resolveScriptStyle(String s) {
402      scriptStyleRefuse = true;
403      try {
404         return resolve(s);
405      } finally {
406         scriptStyleRefuse = false;
407      }
408   }
409
410   /**
411    * Compiles the given template string into a reusable {@link VarTemplate}.
412    *
413    * <p>
414    * Equivalent to {@link VarResolver#compile(String) this.context.compile(input)}; provided on
415    * the session for symmetry with {@link #resolve(String)}. The returned template is bound to
416    * the underlying {@link VarResolver}, not to this session — see the {@link VarTemplate}
417    * class javadoc for the compile-binding contract.
418    *
419    * @param input The template string. May be {@code null}.
420    * @return A new {@link VarTemplate} bound to the underlying resolver.
421    */
422   public VarTemplate compile(String input) {
423      return context.compile(input);
424   }
425
426   /**
427    * Returns a session-bound {@link Supplier} that re-resolves the given template against
428    * <i>this</i> session each time {@link Supplier#get()} is called.
429    *
430    * <p>
431    * Unlike {@link VarResolver#resolveSupplier(String)} — which opens a fresh session per
432    * {@code .get()} and is threadsafe to share — this Supplier captures the existing session
433    * and reuses it. <b>It is therefore not threadsafe</b>; it inherits the standard
434    * "{@link VarResolverSession} is not guaranteed to be thread safe" contract.
435    *
436    * <p>
437    * Use this variant only when the caller owns the session lifecycle and the perf saving of
438    * skipping per-call session construction matters. For shared / cross-thread use cases,
439    * prefer {@link VarResolver#resolveSupplier(String)}.
440    *
441    * @param input The template string. May be {@code null}.
442    * @return A {@code Supplier<String>} bound to this session.
443    */
444   public Supplier<String> resolveSupplier(String input) {
445      return compile(input).asSupplier(this);
446   }
447
448   /**
449    * Resolves the specified strings in the string array.
450    *
451    * @param in The string array containing variables to resolve.  Must not be <jk>null</jk> or a {@link NullPointerException} is thrown, though individual elements can be <jk>null</jk>.
452    * @return An array with resolved strings.  Elements are <jk>null</jk> where the corresponding input element was <jk>null</jk>.
453    */
454   public String[] resolve(String[] in) {
455      var out = new String[in.length];
456      for (var i = 0; i < in.length; i++)
457         out[i] = resolve(in[i]);
458      return out;
459   }
460
461   /**
462    * Convenience method for resolving variables in arbitrary objects.
463    *
464    * <p>
465    * Supports resolving variables in the following object types:
466    * <ul>
467    *    <li>{@link CharSequence}
468    *    <li>Arrays containing values of type {@link CharSequence}.
469    *    <li>Collections containing values of type {@link CharSequence}.
470    *       <br>Collection class must have a no-arg constructor.
471    *    <li>Maps containing values of type {@link CharSequence}.
472    *       <br>Map class must have a no-arg constructor.
473    * </ul>
474    *
475    * @param <T> The value type.
476    * @param o The object.  Can be <jk>null</jk> (returns <jk>null</jk>).
477    * @return The same object if no resolution was needed, otherwise a new object or data structure if resolution was
478    * needed.  Returns <jk>null</jk> if the input was <jk>null</jk>.
479    */
480   @SuppressWarnings({
481      "java:S3776", // Cognitive complexity acceptable for recursive resolution logic
482      "rawtypes", // Raw types necessary for generic resolution
483      "unchecked" // Type erasure requires unchecked operations
484   })
485   public <T> T resolve(T o) {
486      if (o == null)
487         return null;
488      if (o instanceof CharSequence o2)
489         return (T)resolve(o2.toString());
490      if (isArray(o)) {
491         if (! containsVars(o))
492            return o;
493         var o2 = Array.newInstance(o.getClass().getComponentType(), Array.getLength(o));
494         for (var i = 0; i < Array.getLength(o); i++)
495            Array.set(o2, i, resolve(Array.get(o, i)));
496         return (T)o2;
497      }
498      if (o instanceof Set o2) {
499         try {
500            if (! containsVars(o2))
501               return o;
502            Set o3 = info(o).getDeclaredConstructor(x -> x.isPublic() && x.getParameterCount() == 0).map(ci -> safe(() -> (Set)ci.inner().newInstance())).orElseGet(LinkedHashSet::new);
503            Set o4 = o3;
504            o2.forEach(x -> o4.add(resolve(x)));
505            return (T)o3;
506         } catch (VarResolverException e) {
507            throw e;
508         } catch (Exception e) {
509            throw new VarResolverException(e, "Problem occurred resolving set.");
510         }
511      }
512      if (o instanceof List o2) {
513         try {
514            if (! containsVars(o2))
515               return o;
516            List o3 = info(o).getDeclaredConstructor(x -> x.isPublic() && x.getParameterCount() == 0).map(ci -> safe(() -> (List)ci.inner().newInstance())).orElseGet(() -> list());
517            List o4 = o3;
518            o2.forEach(x -> o4.add(resolve(x)));
519            return (T)o3;
520         } catch (VarResolverException e) {
521            throw e;
522         } catch (Exception e) {
523            throw new VarResolverException(e, "Problem occurred resolving collection.");
524         }
525      }
526      if (o instanceof Map o2) {
527         try {
528            if (! containsVars(o2))
529               return o;
530            Map o3 = info(o).getDeclaredConstructor(x -> x.isPublic() && x.getParameterCount() == 0).map(ci -> safe(() -> (Map)ci.inner().newInstance())).orElseGet(LinkedHashMap::new);
531            Map o4 = o3;
532            o2.forEach((k, v) -> o4.put(k, resolve(v)));
533            return (T)o3;
534         } catch (VarResolverException e) {
535            throw e;
536         } catch (Exception e) {
537            throw new VarResolverException(e, "Problem occurred resolving map.");
538         }
539      }
540      return o;
541   }
542
543   /**
544    * Resolves variables in the specified string and sends the output to the specified writer.
545    *
546    * <p>
547    * More efficient than first parsing to a string and then serializing to the writer since this method doesn't need
548    * to construct a large string.
549    *
550    * @param s The string to resolve variables in.  Can be <jk>null</jk>, in which case the writer is left unchanged.
551    * @param out The writer to write to.  Must not be <jk>null</jk>.
552    * @return The same writer.
553    * @throws IOException Thrown by underlying stream.
554    */
555   public Writer resolveTo(String s, Writer out) throws IOException {
556      if (s == null)
557         return out;
558      if (s.isEmpty()) {
559         return out;
560      }
561      return context.compile(s).resolveTo(this, out);
562   }
563
564   protected FluentMap<String,Object> properties() {
565      // @formatter:off
566      return filteredBeanPropertyMap()
567         .a("context.beanStore", this.context.beanStore)
568         .a("var", this.context.getVarMap().keySet())
569         .a("session.beanStore", beanStore);
570      // @formatter:on
571   }
572
573   @Override /* Overridden from Object */
574   public String toString() {
575      return r(properties());
576   }
577
578   /**
579    * Returns the {@link Var} with the specified name.
580    *
581    * @param name The var name (e.g. <js>"S"</js>).  Must not be <jk>null</jk>.
582    * @return The {@link Var} instance, or <jk>null</jk> if no <c>Var</c> is associated with the specified name.
583    */
584   protected Var getVar(String name) {
585      Var v = this.context.getVarMap().get(name);
586      return nn(v) && v.canResolve(this) ? v : null;
587   }
588
589   /**
590    * Returns <jk>true</jk> if this session is resolving HTML-doc chrome and substitutions should be XML-escaped.
591    *
592    * @return <jk>true</jk> if HTML-doc chrome encoding is enabled.
593    */
594   boolean isHtmlDocEncode() {
595      return htmlDocEncode;
596   }
597
598   /**
599    * Returns <jk>true</jk> if {@code varName} must be left unresolved in script/style chrome.
600    *
601    * @param varName The SVL var prefix (e.g. <js>"RQ"</js>).
602    * @return <jk>true</jk> if the var should fall through like an unknown var.
603    */
604   boolean isScriptStyleRefused(String varName) {
605      return scriptStyleRefuse && SCRIPT_STYLE_REFUSED_VARS.contains(varName);
606   }
607
608   /**
609    * XML-escapes an SVL substitution when HTML-doc chrome encoding is enabled and the var is not passthrough.
610    *
611    * @param varName The SVL var prefix.
612    * @param replacement The resolved substitution text.
613    * @return The possibly escaped replacement.
614    */
615   String applyHtmlDocChromeEncoding(String varName, String replacement) {
616      if (! htmlDocEncode || replacement == null || HTML_DOC_PASSTHROUGH_VARS.contains(varName))
617         return replacement;
618      return StringUtils.escapeXml(replacement);
619   }
620}