Package org.apache.juneau.commons.svl

Class VarTemplate

java.lang.Object
org.apache.juneau.commons.svl.VarTemplate
public final class VarTemplate extends Object
A pre-compiled SVL template.

A VarTemplate is the result of compiling a template string against a VarResolver. It separates the "parse" step from the "evaluate" step so that repeated resolutions of the same input string skip tokenization, var-registry lookup, and (eventually) function-dispatch metadata.

Templates are obtained via VarResolver.compile(String) or VarResolverSession.compile(String) — there is no public constructor.

Compile-binding contract:

A compiled template is bound to the VarResolver instance it was compiled against. Cached Var (and, in the future, VarFunction) references are resolved at compile time. Passing a VarTemplate produced by one resolver to a session belonging to a different resolver is undefined behavior. Rebuilding the resolver invalidates any compiled templates from the previous instance — caller's responsibility to re-compile.

Threadsafety:

VarTemplate instances are immutable and threadsafe — the same template can be safely shared across threads. Note that VarResolverSession is not threadsafe; the session passed to resolve(VarResolverSession) or asSupplier(VarResolverSession) inherits the standard session-threadsafety contract. The asSupplierWithFreshSessions(VarResolver) variant opens a fresh session per call and is safe to share across threads.

Which Supplier do I want?
  • asSupplierWithFreshSessions(VarResolver) — opens a fresh session per .get() call. Safe to share across threads. Use this for user-facing code, hot-reload patterns, and any situation where the Supplier may be invoked on threads other than the caller's. Recommended default.
  • asSupplier(VarResolverSession) — captures the existing session and reuses it on every .get() call. Inherits the session's threadsafety contract (i.e. not threadsafe). Use only in perf-sensitive paths where the caller owns the session lifecycle.
See Also:

  • Method Details

    • resolve

      public String resolve(VarResolverSession session)
      Resolves this template against the given session.

      Walks the cached segment array in order, accumulating the result in a StringBuilder. Literal-only templates fast-path to a single allocation skip and return the source string directly.

      Parameters:
      session - The session to resolve against. Must not be null. The session is not required to belong to the same VarResolver this template was compiled against, but cached Var references will only honor that resolver's registry — see the "compile-binding contract" note in the class javadoc.
      Returns:
      The resolved string, or null if this template was compiled from a null source (mirroring VarResolverSession.resolve(String) returning null for null input). Otherwise never null.

    • resolveTo

      public Writer resolveTo(VarResolverSession session, Writer out) throws IOException
      Resolves this template against the given session and writes the result directly to out.

      Streamed-Var-bearing segments write through to out without materializing an intermediate String. Used by VarResolver.resolveTo(String, Writer) so downstream serializers can stream large content efficiently.

      Parameters:
      session - The session to resolve against. Must not be null.
      out - The writer to append to. Must not be null.
      Returns:
      out, for fluent-API chaining.
      Throws:
      IOException - Thrown by the underlying stream.

    • asSupplier

      public Supplier<String> asSupplier(VarResolverSession session)
      Returns a Supplier that resolves this template against the given session each time its Supplier.get() method is called.

      The captured session is reused across .get() calls; this Supplier is not threadsafe (it inherits the session's threadsafety contract). For a threadsafe variant use asSupplierWithFreshSessions(VarResolver).

      Parameters:
      session - The session to capture. Must not be null.
      Returns:
      A Supplier<String> bound to session.

    • asSupplierWithFreshSessions

      public Supplier<String> asSupplierWithFreshSessions(VarResolver vr)
      Returns a threadsafe Supplier that opens a fresh VarResolverSession on every Supplier.get() call.

      Use this variant when the returned Supplier may be invoked from threads other than the caller's — e.g. when stashed on a long-lived bean field or shared across worker threads. The fresh-session-per-.get() pattern is the recommended default for user-facing code.

      Parameters:
      vr - The resolver to open sessions against. Must not be null. Typically the same resolver this template was compiled against.
      Returns:
      A threadsafe Supplier<String>.

    • isLiteral

      public boolean isLiteral()
      Returns true if this template contains no variable references and resolves to a fixed string.

      Computed at compile time by inspecting the segment array: true iff the array is empty or contains only LiteralSegment entries. Stable-value folding may flip a template with stable Vars to literal by replacing the relevant VarRefSegment entries with LiteralSegment entries at compile time.

      Callers can use this hint to fast-path purely-literal templates — for example, by skipping the Supplier wrapping overhead for a @Value("plain string") field:

      var tpl = vr.compile(raw); if (tpl.isLiteral()) // No need to wrap in a Supplier; the value never changes. return tpl.resolve(session);

      Returns:
      true if the template resolves to a fixed string.

    • getSource

      public String getSource()
      Returns the raw input string this template was compiled from.

      Useful for diagnostics, error messages, and debugging. The string is preserved verbatim including any escape sequences.

      Returns:
      The raw input string.

    • resolveToUnchecked

      public Writer resolveToUnchecked(VarResolverSession session, Writer out)
      Convenience helper for callers that need to resolveTo(VarResolverSession, Writer) but don't want to handle IOException. Wraps any thrown IOException in a RuntimeException via the standard ThrowableUtils.toRex helper.
      Parameters:
      session - The session to resolve against. Must not be null.
      out - The writer to append to. Must not be null.
      Returns:
      out.

    • toString

      public String toString()
      Overrides:
      toString in class Object