net.shibboleth.utilities.java.support.velocity

Class Template

java.lang.Object

net.shibboleth.utilities.java.support.velocity.Template

public final class Template
extends java.lang.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 and Description
private org.apache.velocity.app.VelocityEngine	engine The VelocityEngine used when evaluating the template.
private java.lang.String	templateEncoding The character encoding of the template.
private java.lang.String	templateName The name of the template to be evaluated.

Constructor Summary

Constructors

Modifier	Constructor and Description
private	Template(org.apache.velocity.app.VelocityEngine velocityEngine, java.lang.String velocityTemplateName, java.lang.String velocityTemplateEncoding) Constructor.

Method Summary

Modifier and Type	Method and Description
boolean	equals(java.lang.Object obj)
static Template	fromTemplate(org.apache.velocity.app.VelocityEngine engine, java.lang.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, java.lang.String template, java.nio.charset.Charset encoding) Constructs a Template from a given template.
static Template	fromTemplateName(org.apache.velocity.app.VelocityEngine engine, java.lang.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, java.lang.String name, java.nio.charset.Charset encoding) Constructs a Template that evaluates a named velocity template with a using the given velocity engine.
java.lang.String	getTemplateName() Gets the name of the template.
int	hashCode()
java.lang.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, java.io.Writer output) Evaluates the template using the given context and sends the result to a Writer.
java.lang.String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

engine

private final org.apache.velocity.app.VelocityEngine engine

The VelocityEngine used when evaluating the template.

templateName

private final java.lang.String templateName

The name of the template to be evaluated.

templateEncoding

private final java.lang.String templateEncoding

The character encoding of the template.

Constructor Detail

Template

private Template(@Nonnull
                 org.apache.velocity.app.VelocityEngine velocityEngine,
                 @Nonnull @NotEmpty
                 java.lang.String velocityTemplateName,
                 @Nonnull
                 java.lang.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 Detail

fromTemplate

@Nonnull
public static Template fromTemplate(@Nonnull
                                             org.apache.velocity.app.VelocityEngine engine,
                                             @Nonnull @NotEmpty
                                             java.lang.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
                                             java.lang.String template,
                                             @Nonnull
                                             java.nio.charset.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
                                        java.lang.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
                                        java.lang.String name,
                                        @Nonnull
                                        java.nio.charset.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 java.lang.String getTemplateName()

Gets the name of the template.

Returns:

name of the template

merge

public java.lang.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,
                  java.io.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(java.lang.Object obj)

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object