Class Template

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 Details

    • 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 Details

    • 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(java.lang.String,java.lang.String) method.

    • fill

      public void fill(String name, int value)
      An alias for the set(java.lang.String,java.lang.String) method.

    • fill

      public void fill(String name, long value)
      An alias for the set(java.lang.String,java.lang.String) method.

    • fill

      public void fill(String name, boolean value)
      An alias for the set(java.lang.String,java.lang.String) method.

    • fill

      public void fill(String name, Object value)
      An alias for the set(java.lang.String,java.lang.String) 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