Package org.apache.juneau.commons.template

Class TemplateResolver

java.lang.Object
org.apache.juneau.commons.template.TemplateResolver
public final class TemplateResolver extends Object
Renders SVL templates written by authors who are less trusted than the application.

A template resolver is a locked-down VarResolver: it registers no system vars, permits only the functions in SafeFunctions, and reads data only from the map passed to each render. The built-in functions give lists, tables and per-row projections; see the package documentation for the grammar and the encoding rule.

Inside a projection over a list of maps, size and empty resolve to the row map's own size and emptiness even when the row has no such key, so they do not fall back to a scope entry of the same name.

Example:

var resolver = TemplateResolver.create().destination(Destinations.HTML).build(); var template = resolver.parse("Failed: ${n}\n#{ul(failed.![id + ' - ' + msg])}"); var html = resolver.render(template, Map.of("n", 2, "failed", rows));

Notes:

  • Field Details

    • DEFAULT

      public static final TemplateResolver DEFAULT
      A resolver with the default configuration: lenient, no destination.

      It does no encoding and renders structures with Structure.toString(). Resolved values reach the output unescaped, so it is not for HTML, Markdown, JSON or URLs; build a resolver with a Destinations preset (or an explicit encoder) for those.

  • Method Details

    • create

      public static TemplateResolver.Builder create()
      Creates a builder.
      Returns:
      A new builder.

    • parse

      public ParsedTemplate parse(String template)
      Parses a template.
      Parameters:
      template - The template text. May be null.
      Returns:
      The parsed template. Never null.
      Throws:
      ExprException - In strict mode, if the template is malformed or uses an unknown or denied function. In lenient mode nothing is thrown.

    • render

      public String render(ParsedTemplate template, Map<String,?> scope)
      Renders a template using the default value encoder of the configured destination (none if there is no destination).
      Parameters:
      template - The template. Must not be null, and must have been parsed by this resolver.
      scope - The names the template can read. May be null (no names).
      Returns:
      The rendered text.
      Throws:
      IllegalArgumentException - If the template was parsed by a different resolver.

    • render

      public String render(ParsedTemplate template, Map<String,?> scope, UnaryOperator<String> valueEncoder)
      Renders a template.
      Parameters:
      template - The template. Must not be null, and must have been parsed by this resolver.
      scope - The names the template can read. May be null (no names).
      valueEncoder - The value encoder. Overrides the destination's encoder; null uses the destination's.
      Returns:
      The rendered text.

    • check

      public List<TemplateProblem> check(String template, TemplateCatalog catalog)
      Checks a template against a catalog without rendering it. Never throws.

      Reports, in source order: an identifier not in the catalog, a row field not in its list's catalog, a row field read through a name that is not a declared list, an unknown or denied function (unless the catalog allows them), an unknown var, and a marker that does not compile. The key of a ${name} or ${name:default} reference is checked like an identifier, so ${secret} is a problem when secret is not declared; a key that is itself computed (${${x}}) is read as written and is reported as unknown. The default text after : is not checked.

      Parameters:
      template - The template text. May be null.
      catalog - The catalog. Must not be null.
      Returns:
      The problems. Empty if the template is clean.

    • validate

      public ParsedTemplate validate(String template, TemplateCatalog catalog)
      Like check(String, TemplateCatalog) but throws.
      Parameters:
      template - The template text. May be null.
      catalog - The catalog. Must not be null.
      Returns:
      The parsed template, if it is clean.
      Throws:
      TemplateValidationException - If there are problems.