Template (MollyPages.org Foundation API)

java.lang.Object
- fc.util.Template

```
public final 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 $ char itself can be output 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 substituted 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 not recursively resolved, 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

Constructors
Constructor and Description

Template(File templatefile)
Constructs a new template object

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

Constructors
Constructor and Description
`Template(File templatefile)` Constructs a new template object
`Template(String template)` Constructs a new template object from the given String.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`fill(String name, boolean value)` An alias for the `set` method.
`void`	`fill(String name, int value)` An alias for the `set` method.
`void`	`fill(String name, long value)` An alias for the `set` method.
`void`	`fill(String name, Object value)` An alias for the `set` method.
`void`	`fill(String name, String value)` An alias for the `set` method.
`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`	`reset()` Resets the template data.
`void`	`set(String name, String value)` A template variable can be assigned data using this method.
`String`	`toString()`
`String`	`value()` Merges and writes the template and data and returns it as a String
`void`	`write(File destfile)` Merges and writes the template and data.
`void`	`write(File destfile, boolean overwrite)` Merges and writes the template and data.
`void`	`write(PrintStream out)` Merges and writes the template and data to the specified Writer
`void`	`write(Writer out)` Merges and writes the template and data to the specified Writer

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, 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.
  - reset
```
public void reset()
```
    Resets the template data. If reusing the template over and over again, this is faster, invoke this between each reuse. (rather than recreate it from scratch every time).
  - 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.
  - fill
```
public void fill(String name,
                 String value)
```
    An alias for the set method.
  - fill
```
public void fill(String name,
                 int value)
```
    An alias for the set method.
  - fill
```
public void fill(String name,
                 long value)
```
    An alias for the set method.
  - fill
```
public void fill(String name,
                 boolean value)
```
    An alias for the set method.
  - fill
```
public void fill(String name,
                 Object value)
```
    An alias for the set method.
  - 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.
  - write
```
public void write(Writer out)
           throws IOException
```
    Merges and writes the template and data to the specified Writer
    
    Throws:
    
    IOException
  - write
```
public void write(PrintStream out)
           throws IOException
```
    Merges and writes the template and data to the specified Writer
    
    Throws:
    
    IOException
  - value
```
public String value()
             throws IOException
```
    Merges and writes the template and data and returns it as a String
    
    Throws:
    
    IOException
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - main
```
public static void main(String[] args)
                 throws Exception
```
    Unit Test History
```
Class Version Tester  Status    Notes
1.0       hj    passed    
```
    Throws:
    
    Exception

Class Template

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Template

Template

Method Detail

getTemplateData

reset

set

fill

fill

fill

fill

fill

write

write

write

write

value

toString

main