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}