freemarker.template
Class Template

java.lang.Object
  |
  +--freemarker.template.AbstractTemplate
        |
        +--freemarker.template.Template
All Implemented Interfaces:
Cacheable, java.lang.Cloneable, Compileable, FunctionTemplateProcessor, java.io.Serializable, TemplateProcessor

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 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(TemplateModelRoot, Writer) 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.

Version:
$Id: Template.java,v 1.41 2003/11/27 07:07:09 run2000 Exp $
See Also:
TemplateCache, Serialized Form

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 functions
          A mapping of all function models in this compiled template.
 
Fields inherited from class freemarker.template.AbstractTemplate
cache
 
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(FunctionInstruction function)
          Adds a function to the template.
 java.lang.Object clone()
          Clones the current template.
 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.
protected static void copyFunctions(FunctionTemplateProcessor template, TemplateModelRoot modelRoot)
          Copies functions from a template into a data model.
 FunctionInstruction getFunction(java.lang.String name)
          Retrieves a function from the template.
 java.util.Set 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.
 void process(TemplateModelRoot modelRoot, java.io.PrintWriter out)
          Processes the template, using data from a template model, and outputs the resulting text to a PrintWriter.
 void process(TemplateModelRoot modelRoot, java.io.PrintWriter out, TemplateRuntimeHandler eventHandler)
          Processes the contents of this TemplateProcessor and outputs the resulting text to a PrintWriter.
 void process(TemplateModelRoot modelRoot, java.io.Writer out)
          Processes the template, using data from a template model, and outputs the resulting text to a Writer.
 void process(TemplateModelRoot 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
compileFromFile, compileFromFile, compileFromStream, compileFromStream, getCache, setCache
 
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 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()
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

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.
Overrides:
compileFromStream in class AbstractTemplate
Parameters:
stream - a 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.

addFunction

public void addFunction(FunctionInstruction function)
Adds a function to the template. Called by the TemplateBuilder at compile-time.
Specified by:
addFunction in interface FunctionTemplateProcessor
Parameters:
function - the function to be stored by the template

getFunction

public FunctionInstruction 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 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(TemplateModelRoot 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(TemplateModelRoot 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 void process(TemplateModelRoot 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.
Specified by:
process in interface TemplateProcessor
Overrides:
process in class AbstractTemplate
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.
Throws:
java.io.IOException - an IO error occurred with the Writer during processing

process

public void process(TemplateModelRoot 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.
Overrides:
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.

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.
Overrides:
process in class AbstractTemplate
Parameters:
out - a Writer to output the text to.

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.

Cloning is used in Caches, whenever we need to create a new template: rather than simply creating a new Template, we ask a TemplateRegistry to create one for us. TemplateRegistry uses the clone function to take an existing template, copy it, and return the copy to the cache, where it is then populated.

Overrides:
clone in class AbstractTemplate
Returns:
a shallow clone of the current template.

copyFunctions

protected static void copyFunctions(FunctionTemplateProcessor template,
                                    TemplateModelRoot modelRoot)
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

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.