Module net.shibboleth.utilities.java.support

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 Summary

Fields

Modifier and Type	Field	Description
private VelocityEngine	engine	The VelocityEngine used when evaluating the template.
private String	templateEncoding	The character encoding of the template.
private String	templateName	The name of the template to be evaluated.

Constructor Summary

Constructors

Modifier	Constructor	Description
private	Template(VelocityEngine velocityEngine, String velocityTemplateName, String velocityTemplateEncoding)	Constructor.

Method Summary

Modifier and Type	Method	Description
boolean	equals(Object obj)
static Template	fromTemplate(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(VelocityEngine engine, String template, Charset encoding)	Constructs a Template from a given template.
static Template	fromTemplateName(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(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(Context templateContext)	Evaluates the template using the given context and returns the result as a string.
void	merge(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 Detail

engine

@Nonnull
private final 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 Detail

Template

private Template(@Nonnull
                 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 Detail

fromTemplate

@Nonnull
public static Template fromTemplate(@Nonnull
                                    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
                                    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
                                        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
                                        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(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(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