TemplateStreamer

java.lang.Object
- com.purplehillsbooks.temps.TemplateStreamer

```
public class TemplateStreamer
extends java.lang.Object
```
Streams a template file to a Writer object while searching for tokens, and streaming token values in place of those token. The best way to explain this is by example. Consider the following template:
```
 <html>
 <body>
 Dear {{customer name}},
 Your account has a balance of {{account balance}}.
 Sincerely,
 The Bank
 </body>
 </html>
 
```
In this example, there are two tokens. The tokens start with "{{" and and with "}}" and everything between these is called the token name. The names of the tokens in this example are "customer name" and "account balance". The TemplateStreamer will stream out everything in the template, but inplace of the tokens, it will instead stream the appropriate associated values. A supplied TemplateTokenRetriever object locates and streams the associated values.

The TemplateStreamer class does not know what values need to be substituted for the tokens. When the TemplateStreamer instance is constructed, the host program must supply a TemplateTokenRetriever object that will provide values for each of the tokens. The TemplateStreamer will parse the template, and will stream all the non-token parts, but it will call the TemplateTokenRetriever for each of the tokens that it find, passing the name of the token to be output. The TemplateTokenRetriever then looks up and finds the value using whatever means necessary, and streams the value to the Writer, and returns.

We have called this "QuickForms" in the past. It is a lightweight mechanism that allows you to create user interface screens in HTML, and then substitute values into those screens as the screen is being served. Much lighter weight than JSP file, there is no compiler needed. Templates are parsed and streamed in a single action, which allows template files to be changed at any time, and there is no need to re-compile the templates. The parsing and streaming is very efficient and fast, incurring only an inperceptibly small overhead over simply streaming the file directly without parsing. The token values are streamed directly to the output, which eliminates any extra manipulation of string values normaly found in approaches that concatenate strings before producing output.
The file on disk is called a "template" It is a text file of any type, usually HTML. There are tokens that start with two curley braces "{{" and end with two curley braces "}}".
A single brace alone will be ignored. Everything that is not between the curley brace delimiter will be streamed out without change. When a token has been found, the content (that is the text between the braces) will be passed to the calling object in a "callback" method. The result of the callback is the value to place into the template (if any).
As a template design, you decide what token values are valuable for your situation, the TemplateStreamer does not care what the tokens are. The string value between the double curley braces (a.k.a. the token name) is passed unchanged to the TemplateTokenRetriever. The token name might have multiple parameters or even an expression of any syntax. The only restriction that exists on the token name is that it must not contain "}}" (the ending double curley brace.)
All the methods are static. There is no need to create an instance of this class.
How does this compare to JSP? Well, there are no looping constructs or branching constructs. It is really designed for flat files that simply need some run-time values placed into them. This is greate for simple web pages, and particularly for email templates -- basically anytime you have something that looks like HTML, but just has a few values substituted in.

Constructor Summary

Constructors
Constructor and Description

TemplateStreamer()

Constructors
Constructor and Description
`TemplateStreamer()`

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method and Description
`static void`	`streamRawFile(java.io.OutputStream out, java.io.File resourceFile)` streamRawFile simply reads the File passed in, and streams it to output byte for byte, WITHOUT any modification.
`static void`	`streamTemplate(java.io.Writer out, java.io.File file, java.lang.String charset, TemplateTokenRetriever ttr)` This is the main method used to stream a template file, reading from the file, writing to the supplied Writer, and substituting values for the tokens.
`static void`	`streamTemplate(java.io.Writer out, java.io.Reader template, TemplateTokenRetriever ttr)` This is the stream-in/stream-out version of the TemplateStreamer.
`static void`	`writeHtml(java.io.Writer w, java.lang.String t)` A convenience routine to properly encode values for use in HTML.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - TemplateStreamer
```
public TemplateStreamer()
```
- Method Detail
  - streamRawFile
```
public static void streamRawFile(java.io.OutputStream out,
                                 java.io.File resourceFile)
                          throws java.lang.Exception
```
    streamRawFile simply reads the File passed in, and streams it to output byte for byte, WITHOUT any modification. This is a convenience function. Exception if the file passed in does not exist. Exception if the file has zero bytes length on assumption this must be a mistake.
    
    Throws:
    
    java.lang.Exception
  - writeHtml
```
public static void writeHtml(java.io.Writer w,
                             java.lang.String t)
                      throws java.lang.Exception
```
    A convenience routine to properly encode values for use in HTML. Does the proper encoding for a value to be placed in an HTML file, and have it display exactly as the string is in Java. Always HTML encode all user-entered data, even if you think it should not need it, because this will prevent hackers from injecting scripts into the streamed output.
    
    Throws:
    
    java.lang.Exception
  - streamTemplate
```
public static void streamTemplate(java.io.Writer out,
                                  java.io.File file,
                                  java.lang.String charset,
                                  TemplateTokenRetriever ttr)
                           throws java.lang.Exception
```
    This is the main method used to stream a template file, reading from the file, writing to the supplied Writer, and substituting values for the tokens.
    
    Parameters:
    
    out - the writer that the template will be streamed to
    
    file - the abstract file path that locates the file to read
    
    charset - the character encoding of the template file to be read
    
    ttr - the TemplateTokenRetriever that understands how to find values for each of the possible token names in the file, and can stream that value to the Writer object.
    
    Throws:
    
    an - exception will be thrown if anything does not perform correctly: for example if the file is not found, or can not be opened, or can not be read, or the output Writer can not be written to, or the system runs out of memory, or if the template has a syntax error such as a missing end of token double brace. The exception will explain the problem that occurred. The host program should take care to properly log or otherwise communicate this problem to the appropriate channel, because the TemplateStreamer does not keep any log.
    
    java.lang.Exception
  - streamTemplate
```
public static void streamTemplate(java.io.Writer out,
                                  java.io.Reader template,
                                  TemplateTokenRetriever ttr)
                           throws java.lang.Exception
```
    This is the stream-in/stream-out version of the TemplateStreamer. Reads text from the Reader, and output it to the Writer while searching for and substituting tokens. Use this form when the template is not stored as a simple file on the disk.
    
    Throws:
    
    java.lang.Exception

Class TemplateStreamer

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

TemplateStreamer

Method Detail

streamRawFile

writeHtml

streamTemplate

streamTemplate