Package net.shibboleth.utilities.java.support.velocity

Class Template

java.lang.Object
net.shibboleth.utilities.java.support.velocity.Template
public final class Template extends Object
This is a helper class that wraps a velocity engine and template information into a single object. It provides methods, fromTemplate(VelocityEngine, String) and fromTemplate(VelocityEngine, String, Charset), for evaluating literal templates and fromTemplateName(VelocityEngine, String) and fromTemplateName(VelocityEngine, String, Charset) for evaluating templates referenced by name. It also ensures that the given VelocityEngine is configured in such a way as to be able to use the literal or named template. Note, this check occurs only at Template construction time so, if you're loading a named template from a file and that file disappears before calling merge(Context) or merge(Context, Writer) you'll still end up getting a ResourceNotFoundException. Many methods throw an VelocityException to report template or argument errors, which is an unchecked exception type.

  • Field Details

    • engine

      @Nonnull private final org.apache.velocity.app.VelocityEngine engine
      The VelocityEngine used when evaluating the template.

    • templateName

      @Nonnull @NotEmpty private final String templateName
      The name of the template to be evaluated.

    • templateEncoding

      @Nonnull @NotEmpty private final String templateEncoding
      The character encoding of the template.

  • Constructor Details

    • Template

      private Template(@Nonnull org.apache.velocity.app.VelocityEngine velocityEngine, @Nonnull @NotEmpty String velocityTemplateName, @Nonnull String velocityTemplateEncoding)
      Constructor.
      Parameters:
      velocityEngine - engine used to evaluate the template
      velocityTemplateName - name of the template to be evaluated
      velocityTemplateEncoding - encoding used by the template

  • Method Details

    • fromTemplate

      @Nonnull public static Template fromTemplate(@Nonnull org.apache.velocity.app.VelocityEngine engine, @Nonnull @NotEmpty String template)
      A convenience method that invoked fromTemplate(VelocityEngine, String, Charset) and assumes the given template is US ASCII encoded.

      See fromTemplate(VelocityEngine, String, Charset) for full details.

      Parameters:
      engine - engine that will be used to evaluate the template
      template - the literal Velocity template, NOT a template name see fromTemplateName(VelocityEngine, String) and fromTemplateName(VelocityEngine, String, Charset) for that
      Returns:
      an instance of this class that can be used to evaluate the given template using the given engine

    • fromTemplate

      @Nonnull public static Template fromTemplate(@Nonnull org.apache.velocity.app.VelocityEngine engine, @Nonnull @NotEmpty String template, @Nonnull Charset encoding)
      Constructs a Template from a given template. This template is loaded in to the singleton StringResourceRepository used by the StringResourceLoader under a randomly generated ID. Therefore, calling this method multiple times with the same template will result in multiple instances of the template string being loaded in to the StringResourceRepository (each under its own unique ID).

      NOTE, in oder for subsequent calls to merge(Context) or merge(Context, Writer) to be successful, the given VelocityEngine must be configured to look up templates from the StringResourceLoader.

      Parameters:
      engine - engine that will be used to evaluate the template
      template - the literal Velocity template, NOT a template name see fromTemplateName(VelocityEngine, String) or fromTemplateName(VelocityEngine, String, Charset) for that
      encoding - the encoding used by the template
      Returns:
      an instance of this class that can be used to evaluate the given template using the given engine

    • fromTemplateName

      public static Template fromTemplateName(@Nonnull org.apache.velocity.app.VelocityEngine engine, @Nonnull @NotEmpty String templateName)
      A convenience method that invoked fromTemplateName(VelocityEngine, String, Charset) and assumes the named template is US ASCII encoded.

      See fromTemplateName(VelocityEngine, String, Charset) for full details.

      Parameters:
      engine - engine that will be used to evaluate the template
      templateName - the name, as known to the given engine, of a velocity template
      Returns:
      an instance of this class that can be used to evaluate the named template using the given engine

    • fromTemplateName

      public static Template fromTemplateName(@Nonnull org.apache.velocity.app.VelocityEngine engine, @Nonnull @NotEmpty String name, @Nonnull Charset encoding)
      Constructs a Template that evaluates a named velocity template with a using the given velocity engine.
      Parameters:
      engine - the engine used to evaluate the template
      name - the name of the template
      encoding - the template encoding
      Returns:
      an instance of this class that can be used to evaluate the named template using the given engine

    • getTemplateName

      @Nonnull public String getTemplateName()
      Gets the name of the template.
      Returns:
      name of the template

    • merge

      public String merge(org.apache.velocity.context.Context templateContext)
      Evaluates the template using the given context and returns the result as a string.
      Parameters:
      templateContext - current template context
      Returns:
      the generated output of the template

    • merge

      public void merge(org.apache.velocity.context.Context templateContext, Writer output)
      Evaluates the template using the given context and sends the result to a Writer.
      Parameters:
      templateContext - current template context
      output - writer that will receive the template output

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object