fc.util
Class Template

java.lang.Object
  fc.util.Template

public class Template
extends Object

Provides an ultra-simple template/merge type capability. Can be used standalone or as part of a servlet/cgi environment.

Template description:

• The template for the merge file can contain any data with embedded template variables.

  A template variable is a alphanumeric name and starts with a $. The name can also contain the _ and - characters. Examples of variable names are: $foo, $bar9-abc and $ab_c. Names must begin with a alphabet letter and not with a number or any other character. (this makes is easy to have currency numbers like $123 in the template text, without it getting affected by the template engine treating it as a variable).

  The $ sign itself can be used via a special template variable ${dolsign} which gets replaced by a literal $ in the output. Note, the braces are necessary in this case. So to produce a literal $foo in the output, there are two choices:

  • set the value of $foo to the string "$foo", which will then be subsitituted in the resulting output.
  • specify ${dolsign}foo in the template text. The braces are necessary, because "$ foo", if found in the template text is simply ignored (not a valid variable) and hence dolsign is not needed at all. For the relevant case $foo, the braces serve to separate the word dolsign from foo.

  The template engine starts from the beginning of the template text and replaces each template variable by it's corresponding value. This value is specified via set(String, String) method. Template variables are resolved only once, so if $foo has the value "bar" and $bar has the value baz, then $$foo will be resolved to $bar but the resulting $bar will not be resolved further (to baz).

• In addition to template variables, Templates can also contain custom java code. This can be done by a special template variable, which is always called $code and is used with an argument that denotes the java object to call. For example: $code(mypackage.myclass) will call the code method in class mypackage.myclass. The specified custom class must implement the CustomCode interface. The specified custom class must contain a no-arg constructor and is instantiated (once and only once) by the template engine. Global state can be stored in a custom singleton object that can be created/used by the custom java code.
• The template engine executes in textual order, replacing/running code as it appears starting from the beginning of the template. If a corresponding value for a template variable is not found or a specified custom-code class cannot be loaded, that template variable is ignored (and removed) from the resulting output. So for example, if $foo does not have any value associated with it (i.e., is null by default), then it is simply removed in the resulting output. Similarly, if class mypkg.foo specified in the template text as $code(mypkg.foo) cannot be loaded/run, then it'll simply be ignored in the resulting output.
• Templates don't provide commands for looping (such as for, while etc). Templates are limited to simple variable substitution. However, the java code that creates/sets values for these variables can do any arbitrary looping, and using such loops, set the value of a template variable to any, arbitrarily large, string.

Thread safety: This class is not thread safe and higher level synchronization should be used if shared by multiple threads.

Constructor Summary

Template(File templatefile)
Constructs a new template object

Template(String template)
Constructs a new template object from the given String.

Method Summary

Map	getTemplateData() Returns the template data, which is a Map of template variables to values (which were all set, using the set(String, String) method.
static void	main(String[] args) Unit Test History
void	set(String name, String value) A template variable can be assigned data using this method.
void	write(File destfile) Merges and writes the template and data.
void	write(File destfile, boolean overwrite) Merges and writes the template and data.

Methods inherited from class java.lang.Object

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

Constructor Detail

Template

public Template(File templatefile)
         throws IOException

Constructs a new template object

Parameters:

templatefile - the absolute path to the template file

Throws:

IOException

Template

public Template(String template)
         throws IOException

Constructs a new template object from the given String. Note, this is the the String to use as the template, not the name of a file. Various input streams can be converted into a template using methods from the IOUtil class.

Throws:

IOException

Method Detail

getTemplateData

public Map getTemplateData()

Returns the template data, which is a Map of template variables to values (which were all set, using the set(String, String) method. This map can be modified, as deemed necessary.

set

public void set(String name,
                String value)

A template variable can be assigned data using this method. This method should be called at least once for every unique template variable in the template.

Parameters:

name - the name of the template variable including the preceding$ sign. For example: $foo

value - the value to assign to the template variable.

Throws:

IllegalArgumentException - if the specified name of the template variable is not syntactically valid.

write

public void write(File destfile)
           throws IOException

Merges and writes the template and data. Always overwrites the specified destination (even if the destionation file already exists);

Parameters:

destfile - the destination file (to write to).

Throws:

IOException

write

public void write(File destfile,
                  boolean overwrite)
           throws IOException

Merges and writes the template and data. Overwrites the specified destination, only if the overwrite flag is specified as true, otherwise no output is written if the specified file already exists.

The check to see whether an existing file is the same as the output file for this template is inherently system dependent. For example, on Windows, say an an existing file "foo.html" exist in the file system. Also suppose that the output file for this template is set to "FOO.html". This template then will then overwrite the data in the existing "foo.html" file but the output filename will not change to "FOO.html". This is because the windows filesystem treats both files as the same and a new File with a different case ("FOO.html") is not created.

Parameters:

destfile - the destination file (to write to).

overwrite - true to overwrite the destination

Throws:

IOException - if an I/O error occurs or if the destination file cannot be written to.

main

public static void main(String[] args)
                 throws Exception

Unit Test History

Class Version Tester  Status    Notes
1.0       hj    passed    

Throws:

Exception