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.

Field Summary

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

private

Template(VelocityEngine velocityEngine, String velocityTemplateName, String velocityTemplateEncoding) Constructor.

Method Summary

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 returns the result as a string.
String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

engine

private final VelocityEngine engine

The VelocityEngine used when evaluating the template.

templateName

private final String templateName

The name of the template to be evaluated.

templateEncoding

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)
                             throws VelocityException

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

Throws:

VelocityException - thrown if engine is not configured to load the given template from the default StringResourceRepository

fromTemplate

@Nonnull
public static Template fromTemplate(@Nonnull
                                            VelocityEngine engine,
                                            @Nonnull@NotEmpty
                                            String template,
                                            @Nonnull
                                            Charset encoding)
                             throws VelocityException

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

Throws:

VelocityException - thrown if engine is not configured to load the given template from the default StringResourceRepository

fromTemplateName

public static Template fromTemplateName(@Nonnull
                                        VelocityEngine engine,
                                        @Nonnull@NotEmpty
                                        String templateName)
                                 throws VelocityException

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

Throws:

VelocityException - thrown if the template name is not known to the engine

fromTemplateName

public static Template fromTemplateName(@Nonnull
                                        VelocityEngine engine,
                                        @Nonnull@NotEmpty
                                        String name,
                                        @Nonnull
                                        Charset encoding)
                                 throws VelocityException

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

Throws:

VelocityException - thrown if the template name is not known to the engine

getTemplateName

@Nonnull
public String getTemplateName()

Gets the name of the template.

Returns:

name of the template

merge

public String merge(Context templateContext)
             throws VelocityException

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

Throws:

VelocityException - thrown if there is a problem evaluating the template

merge

public void merge(Context templateContext,
                  Writer output)
           throws VelocityException

Evaluates the template using the given context and returns the result as a string.

Parameters:

templateContext - current template context

output - writer that will receive the template output

Throws:

VelocityException - thrown if there is a problem evaluating the template

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