freemarker.template
Class Template

java.lang.Object
  freemarker.template.AbstractTemplate
      freemarker.template.Template

All Implemented Interfaces:

Cacheable, Compileable, FunctionTemplateProcessor, TemplateProcessor, java.io.Serializable, java.lang.Cloneable

public class Template
extends AbstractTemplate
implements FunctionTemplateProcessor, java.io.Serializable

An application or servlet can instantiate a Template to compile and process an HTML template.

You can pass the filename of the template to a TemplateFactory object, in which case it is compiled immediately. Once compiled, the resulting Template is stored in an an efficient data structure for later use.

To process the template and produce HTML, call the process(TemplateWriteableHashModel, Writer) method, which takes a tree of TemplateModel objects as its data model. The root node of the tree must be a TemplateWriteableHashModel.

Any error messages from exceptions thrown by the data model, or generated by the Template during compilation or processing, will be included as HTML comments in the output.

To facilitate multithreading, Template objects are immutable; if you need to recompile a template, you must make a new Template object. In most cases, it will be sufficient to let a TemplateCache do this for you.

Version:

$Id: Template.java 1166 2013-04-21 08:21:15Z run2000 $

See Also:

TemplateCache, TemplateFactory, Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from interface freemarker.template.TemplateProcessor

TemplateProcessor.ExitStatus

Field Summary

protected ParseException	buildError A cached copy of any parser exception thrown during compilation.
protected TemplateProcessor	compiledTemplate The root node of the compiled template.
protected java.util.Map<java.lang.String,TemplateFunctionModel>	functions A mapping of all function models in this compiled template.

Fields inherited from class freemarker.template.AbstractTemplate

cache

Constructor Summary

Template(java.io.Reader reader)
Constructs a template by compiling it from a Reader.

Template(java.io.Reader reader, Cache cache)
Constructs a template by compiling it from a Reader.

Method Summary

void	addFunction(java.lang.String name, TemplateFunctionModel function) Adds a function to the template.
java.lang.Object	clone() Clones the current template.
protected void	compile(java.io.Reader reader) Compiles the template from a Reader.
protected TemplateProcessor	compileText(java.lang.String text) Compiles the template text using the standard parser and builder classes.
protected static void	copyFunctions(FunctionTemplateProcessor template, TemplateWriteableHashModel modelRoot) Copies functions from a template into a data model.
TemplateFunctionModel	getFunction(java.lang.String name) Retrieves a function from the template.
java.util.Set<java.lang.String>	getFunctionNames() Retrieve a Set of function names for this template.
void	process(java.io.PrintWriter out) Processes the template, using an empty data model, and outputs the resulting text to a PrintWriter.
TemplateProcessor.ExitStatus	process(TemplateProcessorParameters p) Processes the contents of this TemplateProcessor and outputs the resulting text to a Writer.
void	process(TemplateWriteableHashModel modelRoot, java.io.PrintWriter out) Processes the template, using data from a template model, and outputs the resulting text to a PrintWriter.
void	process(TemplateWriteableHashModel modelRoot, java.io.PrintWriter out, TemplateRuntimeHandler eventHandler) Processes the contents of this TemplateProcessor and outputs the resulting text to a PrintWriter.
void	process(TemplateWriteableHashModel modelRoot, java.io.Writer out) Processes the template, using data from a template model, and outputs the resulting text to a Writer.
TemplateProcessor.ExitStatus	process(TemplateWriteableHashModel modelRoot, java.io.Writer out, TemplateRuntimeHandler eventHandler) Processes the contents of this TemplateProcessor and outputs the resulting text to a Writer.
void	process(java.io.Writer out) Processes the template, using an empty data model, and outputs the resulting text to a Writer.
java.lang.String	toString() Returns a string representation of the object.

Methods inherited from class freemarker.template.AbstractTemplate

getCache, getTemplateText

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

compiledTemplate

protected TemplateProcessor compiledTemplate

The root node of the compiled template.

functions

protected java.util.Map<java.lang.String,TemplateFunctionModel> functions

A mapping of all function models in this compiled template.

buildError

protected transient ParseException buildError

A cached copy of any parser exception thrown during compilation.

Constructor Detail

Template

public Template(java.io.Reader reader)
         throws java.io.IOException

Constructs a template by compiling it from a Reader. Calls compile().

Parameters:

reader - the source of the template file to be compiled.

Throws:

java.io.IOException

Template

public Template(java.io.Reader reader,
                Cache cache)
         throws java.io.IOException

Constructs a template by compiling it from a Reader. Calls compile().

Parameters:

reader - the source of the template file to be compiled.

Throws:

java.io.IOException

Method Detail

compile

protected void compile(java.io.Reader reader)
                throws java.io.IOException,
                       java.lang.IllegalArgumentException

Compiles the template from a Reader.

Specified by:

compile in class AbstractTemplate

Parameters:

reader - a Reader from which the template can be read.

Throws:

java.io.IOException

java.lang.IllegalArgumentException

compileText

protected TemplateProcessor compileText(java.lang.String text)
                                 throws java.io.IOException

Compiles the template text using the standard parser and builder classes. To provide different compilation behavior, subclasses need only override this method.

Parameters:

text - the text to compile.

Returns:

a TemplateProcessor representing the compiled template.

Throws:

java.io.IOException

addFunction

public void addFunction(java.lang.String name,
                        TemplateFunctionModel function)
                 throws java.lang.IllegalStateException

Adds a function to the template. Called by the TemplateBuilder at compile-time.

Specified by:

addFunction in interface FunctionTemplateProcessor

Parameters:

name - the name of the function to be stored

function - the function to be stored by the template

Throws:

java.lang.IllegalStateException - the method has been called after the template has been compiled

getFunction

public TemplateFunctionModel getFunction(java.lang.String name)

Retrieves a function from the template. Called by CallInstructions and IncludeInstructions at run-time.

Specified by:

getFunction in interface FunctionTemplateProcessor

Parameters:

name - the name of the function to be retrieved

getFunctionNames

public java.util.Set<java.lang.String> getFunctionNames()

Retrieve a Set of function names for this template.

Specified by:

getFunctionNames in interface FunctionTemplateProcessor

Returns:

a Set of function names (String objects) that have been defined for this template.

process

public void process(TemplateWriteableHashModel modelRoot,
                    java.io.PrintWriter out,
                    TemplateRuntimeHandler eventHandler)

Processes the contents of this TemplateProcessor and outputs the resulting text to a PrintWriter.

Parameters:

modelRoot - the root node of the data model.

out - a PrintWriter to send the output to.

eventHandler - a TemplateEventAdapter for handling any events that occur during processing.

process

public void process(TemplateWriteableHashModel modelRoot,
                    java.io.PrintWriter out)

Processes the template, using data from a template model, and outputs the resulting text to a PrintWriter.

Parameters:

modelRoot - the root node of the data model. If null, an empty data model is used.

out - a PrintWriter to send the output to.

process

public void process(java.io.PrintWriter out)

Processes the template, using an empty data model, and outputs the resulting text to a PrintWriter.

Parameters:

out - a PrintWriter to send the output to.

process

public TemplateProcessor.ExitStatus process(TemplateWriteableHashModel modelRoot,
                                            java.io.Writer out,
                                            TemplateRuntimeHandler eventHandler)
                                     throws java.io.IOException

Processes the contents of this TemplateProcessor and outputs the resulting text to a Writer.

Parameters:

modelRoot - the root node of the data model.

out - a Writer to send the output to.

eventHandler - a TemplateEventAdapter for handling any events that occur during processing.

Returns:

a zero or positive value if template processing was successful, otherwise a negative number to indicate that no template has been compiled

Throws:

java.io.IOException - an IO error occurred with the Writer during processing

process

public TemplateProcessor.ExitStatus process(TemplateProcessorParameters p)
                                     throws java.io.IOException

Processes the contents of this TemplateProcessor and outputs the resulting text to a Writer.

Specified by:

process in interface TemplateProcessor

Specified by:

process in class AbstractTemplate

Parameters:

p - template processing parameters

Returns:

a zero or positive value if template processing was successful, otherwise a negative number to indicate that no template has been compiled

Throws:

java.io.IOException - an IO error occurred with the Writer during processing

process

public void process(TemplateWriteableHashModel modelRoot,
                    java.io.Writer out)
             throws java.io.IOException

Processes the template, using data from a template model, and outputs the resulting text to a Writer.

Specified by:

process in class AbstractTemplate

Parameters:

modelRoot - the root node of the data model. If null, an empty data model is used.

out - a Writer to output the text to.

Throws:

java.io.IOException

process

public void process(java.io.Writer out)
             throws java.io.IOException

Processes the template, using an empty data model, and outputs the resulting text to a Writer.

Specified by:

process in class AbstractTemplate

Parameters:

out - a Writer to output the text to.

Throws:

java.io.IOException

clone

public java.lang.Object clone()

Clones the current template. A shallow clone is performed, meaning that changes to the underlying structure of one will affect the structure of the other. As Templates are immutable anyway, this shouldn't be an issue.

Overrides:

clone in class AbstractTemplate

Returns:

a shallow clone of the current template.

copyFunctions

protected static void copyFunctions(FunctionTemplateProcessor template,
                                    TemplateWriteableHashModel modelRoot)
                             throws TemplateModelException

Copies functions from a template into a data model. This lets functions from parent and child templates be available in both contexts.

Parameters:

template - the template from which function instructions will be copied

modelRoot - the template model where functions will be copied to

Throws:

TemplateModelException - the model could not accept the function

toString

public java.lang.String toString()

Returns a string representation of the object. The value returned represents the parse tree of the template.

Overrides:

toString in class java.lang.Object

Returns:

a string representation of the object.