Package org.apache.juneau.commons.svl

Class VarResolver

java.lang.Object
org.apache.juneau.commons.svl.VarResolver
public class VarResolver extends Object
Utility class for resolving variables of the form "$X{key}" in strings.

Variables are of the form $X{key}, where X can consist of zero or more ASCII characters.
The variable key can contain anything, even nested variables that get recursively resolved.

Variables are defined through the VarResolver.Builder.vars(Class[]) method.

The Var interface defines how variables are converted to values.

Example:

public class SystemPropertiesVar extends SimpleVar { // Must have a no-arg constructor! public SystemPropertiesVar() { super("S"); } @Override public String resolve(VarResolverSession session, String value) { return System.getProperty(value); } } // Create a variable resolver that resolves system properties (e.g. "$S{java.home}") VarResolver varResolver = VarResolver.create().vars(SystemPropertiesVar.class).build(); // Use it! System.out.println(varResolver.resolve("java.home is set to $S{java.home}"));

See Also:

  • Field Details

    • DEFAULT

      public static final VarResolver DEFAULT
      Default string variable resolver with support for system properties, environment variables, and the built-in VarFunction catalog.
      Built-in Var bindings:
      Built-in VarFunction catalog:

      Ships ~68 built-in functions across 10 categories — string, type-conversion, arithmetic, boolean, conditional, regex, encoding, date/time, random/UUID, and JSON-navigation. Functions are invoked via the #{name(args...)} syntax. See VarResolver.Builder.defaultFunctions() for the registration mechanism.

      The 11 transformation/conditional Vars previously bundled here (SwitchVar, IfVar, CoalesceVar, PatternMatchVar, PatternReplaceVar, PatternExtractVar, UpperCaseVar, LowerCaseVar, NotEmptyVar, LenVar, SubstringVar) were deleted in 10.0.0; their behavior is now covered by the #{...} script syntax.

  • Constructor Details

  • Method Details

    • create

      public static VarResolver.Builder create()
      Instantiates a new clean-slate VarResolver.Builder object.
      Returns:
      A new VarResolver.Builder object.

    • addBean

      public <T> VarResolver addBean(Class<T> c, T value)
      Adds a bean to this session.
      Type Parameters:
      T - The bean type.
      Parameters:
      c - The bean type.
      value - The bean.
      Returns:
      This object .

    • copy

      public VarResolver.Builder copy()
      Returns a new builder object using the settings in this resolver as a base.
      Returns:
      A new var resolver builder.

    • createSession

      public VarResolverSession createSession()
      Creates a new resolver session with no session objects.
      Returns:
      A new resolver session.

    • createSession

      public VarResolverSession createSession(WritableBeanStore beanStore)
      Same as createSession() except allows you to specify a bean store for resolving beans.
      Parameters:
      beanStore - The bean store to associate with this session. May be null.
      Returns:
      A new resolver session.

    • resolve

      public String resolve(String s)
      Resolve variables in the specified string.

      This is a shortcut for calling createSession(null).resolve(s);.
      This method can only be used if the string doesn't contain variables that rely on the existence of session variables.

      Parameters:
      s - The input string. May be null.
      Returns:
      The string with variables resolved, or the same string if it doesn't contain any variables to resolve. Returns null if the input was null.

    • compile

      public VarTemplate compile(String input)
      Compiles a template string into a reusable VarTemplate.

      Compilation is the dual of resolve(String) — instead of tokenizing and resolving in one pass, the input is parsed once and the result returned as an immutable VarTemplate that callers can reuse across many resolutions:

      // Compile once... var tpl = vr.compile("hello, ${name:world}"); // ...resolve many times. for (var req : requests) { var session = vr.createSession().bean(req); writer.write(tpl.resolve(session)); }

      The returned VarTemplate is immutable and threadsafe; the VarResolverSession passed to VarTemplate.resolve(VarResolverSession) inherits its own threadsafety contract (sessions are not threadsafe). Use resolveSupplier(String) or VarTemplate.asSupplierWithFreshSessions(VarResolver) for a threadsafe re-evaluating Supplier.

      Compile-binding contract:

      The compiled template is bound to this resolver. Cached Var (and, in the future, function) references are resolved at compile time. Passing the compiled template to a session belonging to a different VarResolver is undefined behavior. Rebuilding the resolver invalidates compiled templates from the previous instance.

      Templates are not cached on the resolver. Callers that compile the same input repeatedly (e.g. framework consumers compiling per @Value field) should cache the returned VarTemplate on their own per-site metadata.

      Parameters:
      input - The template string to compile. May be null.
      Returns:
      A new VarTemplate bound to this resolver.

    • resolveSupplier

      public Supplier<String> resolveSupplier(String input)
      Returns a threadsafe Supplier that resolves the given template against this resolver each time Supplier.get() is called.

      Each call to Supplier.get() opens a fresh VarResolverSession, so the returned Supplier is safe to share across threads — making it the recommended default for user-facing code (e.g. @Value Supplier<String> field types, hot-reload config patterns).

      Equivalent to compile(input).asSupplierWithFreshSessions(this).

      For a session-bound (and therefore not threadsafe) variant, see VarResolverSession.resolveSupplier(String).

      Parameters:
      input - The template string. May be null.
      Returns:
      A threadsafe Supplier<String>.

    • resolveTo

      public void resolveTo(String s, Writer w) throws IOException
      Resolve variables in the specified string and sends the results to the specified writer.

      This is a shortcut for calling createSession(null).resolveTo(s, w);.
      This method can only be used if the string doesn't contain variables that rely on the existence of session variables.

      Parameters:
      s - The input string. May be null, in which case the writer is left unchanged.
      w - The writer to send the result to. Must not be null.
      Throws:
      IOException - Thrown by underlying stream.

    • getVarMap

      protected Map<String,Var> getVarMap()
      Returns an unmodifiable map of Vars associated with this context.
      Returns:
      A map whose keys are var names (e.g. "S") and values are Var instances.

    • getVars

      protected Var[] getVars()
      Returns an array of variables define in this variable resolver context.
      Returns:
      A new array containing the variables in this context.

    • getFunctionMap

      protected Map<String,VarFunction> getFunctionMap()
      Returns an unmodifiable map of VarFunctions associated with this context.
      Returns:
      A map whose keys are function names (e.g. "upper") and values are VarFunction instances.