com.qindesign.servlet
Class Template

java.lang.Object
  com.qindesign.servlet.Template

public class Template
extends Object

This class implements a simple template engine for use in servlets.

Variables are indicated by enclosing a name within hash marks. For example, the string "<p>Hello, #name#!</p>", contains a variable named "name".

Zero-length variable names ("##") are replaced by a single hash mark in the output, and unclosed hashes, or variable names with non- identifier chars in them are ignored and output as-is. Additionally, unset variables are also ignored and output as-is.

For variable names with non-identifier chars, parsing stops at the first such character, and what would be the variable's ending hash becomes the starting hash for another variable. For example, the string

"<span style=\"color: #C0C0C0\">My name is #name#</span>"

is considered to have only the variable, "name". Parsing stops for the potential variable whose name starts with "C0C0C0" because a double quote character is not a valid Java identifier.

Internally, the template string is stored in a byte array for fast output.

Version:

1.0.4

Author:

Shawn Silverman

Nested Class Summary

static interface

Template.UnsetVariableHandler This handler is called for each variable that is not set.

Method Summary

void	clear() Unsets all the template variables.
static void	flushCache() This clears the template cache.
String	get(String name) Gets the value associated with the specified variable.
boolean	has(String name) Checks if this template has the specified variable.
Enumeration	names() Returns an enumeration of the variable names in this template.
void	output(HttpServletRequest req, HttpServletResponse resp) Outputs the template.
static Template	parse(File file) Parses a file containing a template.
static Template	parse(String s) Parses a string containing a template.
void	set(String name, String value) Sets a value in the template.
void	setUnsetVariableHandler(Template.UnsetVariableHandler handler) Sets the handler for unset variables.

Methods inherited from class java.lang.Object

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

Method Detail

flushCache

public static void flushCache()

This clears the template cache.

parse

public static Template parse(File file)
                      throws IOException

Parses a file containing a template. This caches the template so that subsequent calls with the same file do not have to parse the file.

Parameters:

file - the file containing the template

Returns:

a new template, or null if the file does not exist.

Throws:

IOException - if there was an error reading from the file.

NullPointerException - if file is null.

parse

public static Template parse(String s)

Parses a string containing a template. The data is stored internally as bytes. The encoding is assumed to be in ISO-8859-1.

Parameters:

s - the template to parse

Returns:

a new template object

Throws:

NullPointerException - if the string is null.

clear

public void clear()

Unsets all the template variables.

set

public void set(String name,
                String value)

Sets a value in the template. A value of null unsets the variable.

Parameters:

name - the variable name to set

value - the value

get

public String get(String name)

Gets the value associated with the specified variable. This will return null if the variable is unset or does not exist.

Parameters:

name - the variable name to get

Returns:

the value associated with the specified variable, or null if the variable is unset or does not exist.

has

public boolean has(String name)

Checks if this template has the specified variable.

Parameters:

name - the variable name to search for

names

public Enumeration names()

Returns an enumeration of the variable names in this template. The list will not necessarily be in the same order as they occur in the template.

Returns:

an Enumeration of all the variable names in this template.

setUnsetVariableHandler

public void setUnsetVariableHandler(Template.UnsetVariableHandler handler)

Sets the handler for unset variables. The handler is called when a variable that has not been assigned a value is encountered.

Passing a value of null removes any previously set handler.

Parameters:

handler - the handler to listen for unset variables, or null to remove the handler

output

public void output(HttpServletRequest req,
                   HttpServletResponse resp)
            throws IOException,
                   ServletException

Outputs the template. Note that this does not set any response properties. It retrieves the servlet output stream straight away.

Parameters:

req - the HTTP request object

resp - the HTTP response object

Throws:

IOException - if there was an I/O error while outputting the template.

ServletException - if the callback generated this exception.