Package net.shibboleth.shared.velocity

# Class Template

java.lang.Object
net.shibboleth.shared.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 Summary

Fields
Modifier and Type
Field
Description
`private final org.apache.velocity.app.VelocityEngine`
`engine`
The `VelocityEngine` used when evaluating the template.
`private final String`
`templateEncoding`
The character encoding of the template.
`private final String`
`templateName`
The name of the template to be evaluated.

## Constructor Summary

Constructors
Modifier
Constructor
Description
`private`
`Template(org.apache.velocity.app.VelocityEngine velocityEngine, String velocityTemplateName, String velocityTemplateEncoding)`
Constructor.

## Method Summary

Modifier and Type
Method
Description
`boolean`
`equals(Object obj)`
`static Template`
`fromTemplate(org.apache.velocity.app.VelocityEngine engine, String template)`
A convenience method that invoked `fromTemplate(VelocityEngine, String, Charset)` and assumes the given template is US ASCII encoded.
`static Template`
`fromTemplate(org.apache.velocity.app.VelocityEngine engine, String template, Charset encoding)`
Constructs a `Template` from a given template.
`static Template`
`fromTemplateName(org.apache.velocity.app.VelocityEngine engine, String templateName)`
A convenience method that invoked `fromTemplateName(VelocityEngine, String, Charset)` and assumes the named template is US ASCII encoded.
`static Template`
`fromTemplateName(org.apache.velocity.app.VelocityEngine engine, String name, Charset encoding)`
Constructs a `Template` that evaluates a named velocity template with a using the given velocity engine.
`String`
`getTemplateName()`
Gets the name of the template.
`int`
`hashCode()`
`String`
`merge(org.apache.velocity.context.Context templateContext)`
Evaluates the template using the given context and returns the result as a string.
`void`
`merge(org.apache.velocity.context.Context templateContext, Writer output)`
Evaluates the template using the given context and sends the result to a Writer.
`String`
`toString()`

### Methods inherited from class java.lang.Object

`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

## 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

@Nonnull 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

@Nonnull 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

@Nonnull 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`