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 and Description |
|---|
TemplateStreamer() |
| 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.
|
public static void streamRawFile(java.io.OutputStream out,
java.io.File resourceFile)
throws java.lang.Exception
java.lang.Exceptionpublic static void writeHtml(java.io.Writer w,
java.lang.String t)
throws java.lang.Exception
java.lang.Exceptionpublic static void streamTemplate(java.io.Writer out,
java.io.File file,
java.lang.String charset,
TemplateTokenRetriever ttr)
throws java.lang.Exception
out - the writer that the template will be streamed tofile - the abstract file path that locates the file to readcharset - the character encoding of the template file to be readttr - 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.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.Exceptionpublic static void streamTemplate(java.io.Writer out,
java.io.Reader template,
TemplateTokenRetriever ttr)
throws java.lang.Exception
java.lang.Exception