freemarker.template
Class Template

java.lang.Object
  |
  +--freemarker.template.Template

All Implemented Interfaces:

TemplateProcessor

public class Template

extends java.lang.Object

implements TemplateProcessor

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

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

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

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.

See Also:

TemplateCache

Field Summary

protected TemplateCache	cache
protected static java.lang.String	COMMENT_END
protected static java.lang.String	COMMENT_START
protected TemplateProcessor	compiledTemplate
protected java.util.Map	functions
protected static java.lang.String	LINE_SEPARATOR

Constructor Summary

Template()
Constructs an empty template.

Template(java.io.File file)
Constructs a template by compiling it from a file.

Template(java.io.InputStream stream)
Constructs a template by compiling it from an InputStream.

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

Template(java.lang.String filePath)
Constructs a template by compiling it from a file.

Method Summary

void	addFunction(freemarker.template.instruction.FunctionInstruction function) Adds a function to the template.
void	compileFromFile(java.io.File file) Reads and compiles a template from a file, by getting the file's FileInputStream and using it to call compileFromStream(), using the platform's default character encoding.
void	compileFromFile(java.lang.String filePath) Reads and compiles a template from a file, by getting the file's FileInputStream and using it to call compileFromStream(), using the platform's default character encoding.
void	compileFromStream(java.io.InputStream stream) Compiles the template from an InputStream, using the platform's default character encoding.
void	compileFromStream(java.io.Reader stream) Compiles the template from an Reader.
protected TemplateProcessor	compileText(java.lang.String text) Compiles the template text using the standard parser and builder classes.
static java.lang.String	formatErrorMessage(java.lang.String errorMessage) Used by FreeMarker classes to format an error message as an HTML comment.
freemarker.template.instruction.FunctionInstruction	getFunction(java.lang.String name) Retrieves a function from the template.
java.util.Set	getFunctionNames()
static java.lang.String	getStackTrace(java.lang.Exception e) Used by FreeMarker classes to format a stack trace as a string.
TemplateCache	getTemplateCache() Gets the TemplateCache that this template belongs to.
void	process(java.io.PrintWriter out) Processes the template, using an empty data model, and outputs the resulting HTML to a PrintWriter.
void	process(TemplateModelRoot modelRoot, java.io.PrintWriter out) Processes the template, using data from a template model, and outputs the resulting HTML to a PrintWriter.
void	setTemplateCache(TemplateCache cache) Sets the TemplateCache that this template belongs to.

Methods inherited from class java.lang.Object

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

Field Detail

COMMENT_START

protected static final java.lang.String COMMENT_START

LINE_SEPARATOR

protected static final java.lang.String LINE_SEPARATOR

COMMENT_END

protected static final java.lang.String COMMENT_END

compiledTemplate

protected TemplateProcessor compiledTemplate

cache

protected TemplateCache cache

functions

protected java.util.Map functions

Constructor Detail

Template

public Template()

Constructs an empty template.

Template

public Template(java.lang.String filePath)
         throws java.io.IOException

Constructs a template by compiling it from a file. Calls compileFromFile().

Parameters:

filePath - the absolute path of the template file to be compiled.

Template

public Template(java.io.File file)
         throws java.io.IOException

Constructs a template by compiling it from a file. Calls compileFromFile().

Parameters:

file - a File representing the template file to be compiled.

Template

public Template(java.io.InputStream stream)
         throws java.io.IOException

Constructs a template by compiling it from an InputStream. Calls compileFromStream().

Parameters:

stream - an InputStream from which the template can be read.

Template

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

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

Parameters:

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

Method Detail

compileFromFile

public void compileFromFile(java.lang.String filePath)
                     throws java.io.IOException

Reads and compiles a template from a file, by getting the file's FileInputStream and using it to call compileFromStream(), using the platform's default character encoding.

Parameters:

filePath - the absolute path of the template file to be compiled.

compileFromFile

public void compileFromFile(java.io.File file)
                     throws java.io.IOException

Reads and compiles a template from a file, by getting the file's FileInputStream and using it to call compileFromStream(), using the platform's default character encoding.

Parameters:

file - a File representing the template file to be compiled.

compileFromStream

public void compileFromStream(java.io.InputStream stream)
                       throws java.io.IOException

Compiles the template from an InputStream, using the platform's default character encoding. If the template has already been compiled, this method does nothing.

Parameters:

stream - an InputStream from which the template can be read.

compileFromStream

public void compileFromStream(java.io.Reader stream)
                       throws java.io.IOException

Compiles the template from an Reader. If the template has already been compiled, this method does nothing.

Parameters:

stream - an Reader from which the template can be read.

compileText

protected TemplateProcessor compileText(java.lang.String text)

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.

setTemplateCache

public void setTemplateCache(TemplateCache cache)

Sets the TemplateCache that this template belongs to. IncludeInstruction objects will be able to request this TemplateCache at run-time.

Parameters:

cache - the TemplateCache that this template belongs to.

getTemplateCache

public TemplateCache getTemplateCache()

Gets the TemplateCache that this template belongs to.

Returns:

the TemplateCache that this template belongs to.

addFunction

public void addFunction(freemarker.template.instruction.FunctionInstruction function)

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

getFunction

public freemarker.template.instruction.FunctionInstruction getFunction(java.lang.String name)

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

getFunctionNames

public java.util.Set getFunctionNames()

Returns:

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

process

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

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

Specified by:

process in interface TemplateProcessor

Parameters:

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

out - a PrintWriter to output the HTML to.

process

public void process(java.io.PrintWriter out)

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

Parameters:

out - a PrintWriter to output the HTML to.

formatErrorMessage

public static java.lang.String formatErrorMessage(java.lang.String errorMessage)

Used by FreeMarker classes to format an error message as an HTML comment.

getStackTrace

public static java.lang.String getStackTrace(java.lang.Exception e)

Used by FreeMarker classes to format a stack trace as a string.