org.webmacro.engine
Class WMTemplate

java.lang.Object
  extended byorg.webmacro.engine.WMTemplate
All Implemented Interfaces:
Macro, Template, Visitable
Direct Known Subclasses:
FileTemplate, StreamTemplate, StringTemplate, URLTemplate

public abstract class WMTemplate
extends java.lang.Object
implements Template

Template objects represent the user defined layout into which the webmacro package will substitute values. It is a very simple kind of interpreted language containing text, blocks, and directives. Text is to be passed through verbatim. LList group text and directives into linear lists and sublists. Directives determine how subsequent blocks are to be processed and constitute the commands of the language.

The Template is lazily evaluated: it does not parse or open the supplied filename until it is used. Once it has parsed the file, it never alters its data. The intent is to allow a Template to be parsed once (somewhat expensive) and then used many times; and also not to incur any parsing costs at all if the Template is never actually used.

CONCURRENCY: You must parse() the template before making it available to other threads. After a template has been parsed it is immutable and can be shared between threads without synchronization. This class performs no synchronization itself but instead relies on the TemplateProvider/Broker to synchronize access.


Field Summary
protected  Broker _broker
          The resource broker used to resolve things in this template
protected  Block _content
          What this template contains is a top level block
protected  Log _log
          Where we log our errors
 
Constructor Summary
protected WMTemplate(Broker broker)
          Create a new Template.
protected WMTemplate(java.lang.String parserName, Broker broker)
          Create a new Template specifying both the broker and the parsing language.
 
Method Summary
 void accept(TemplateVisitor v)
           
 java.lang.Object evaluate(Context data)
          Parse the Template against the supplied context data and return it as a string.
protected  java.lang.String getDefaultEncoding()
          return the default encoding either from the WebMacro config or the JVM settings Note for Unix users: you may need to set the environmental variable LC_ALL=[locale] to get the default one set up.
 java.util.Map getMacros()
          Get the #macros' defined for this template.
 java.lang.String getName()
          Return a name for this template.
 java.lang.Object getParam(java.lang.String key)
          Template API
 java.util.Map getParameters()
           
protected  Parser getParser()
          Subclasses can override this if they wish to invoke a parser other than the WM parser, or choose the parser on some more complicated condition.
protected abstract  java.io.Reader getReader()
          Get the stream the template should be read from.
 void parse()
          Template API
 void setName(java.lang.String name)
          Set the name for this template.
 void setParam(java.lang.String key, java.lang.Object value)
          set a parameter.
abstract  java.lang.String toString()
          Return a name for this template.
 void write(FastWriter out, Context data)
          A macro has a write method which takes a context and applies it to the macro to create a resulting String value, which is then written to the supplied stream.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

_broker

protected final Broker _broker
The resource broker used to resolve things in this template


_log

protected final Log _log
Where we log our errors


_content

protected Block _content
What this template contains is a top level block

Constructor Detail

WMTemplate

protected WMTemplate(Broker broker)
Create a new Template. Constructors must supply a broker.


WMTemplate

protected WMTemplate(java.lang.String parserName,
                     Broker broker)
Create a new Template specifying both the broker and the parsing language.

Method Detail

getReader

protected abstract java.io.Reader getReader()
                                     throws java.io.IOException
Get the stream the template should be read from. Parse will call this method in order to locate a stream.

Throws:
java.io.IOException - if unable to read template

toString

public abstract java.lang.String toString()
Return a name for this template. For example, if the template reads from a file you might want to mention which it is--will be used to produce error messages describing which template had a problem.


getName

public java.lang.String getName()
Return a name for this template. If not overridden, uses toString()

Specified by:
getName in interface Template

setName

public void setName(java.lang.String name)
Set the name for this template. Default implementation does nothing.

Specified by:
setName in interface Template

getParser

protected Parser getParser()
                    throws TemplateException
Subclasses can override this if they wish to invoke a parser other than the WM parser, or choose the parser on some more complicated condition. This method will be called by parse();

Throws:
TemplateException

parse

public void parse()
           throws java.io.IOException,
                  TemplateException
Template API

Specified by:
parse in interface Template
Throws:
TemplateException - if the sytax was invalid and we could not recover
java.io.IOException - if we could not successfullly read the parseTool

getMacros

public java.util.Map getMacros()
Get the #macros' defined for this template.

Specified by:
getMacros in interface Template
Returns:
the #macro's defined for this template, or null if this template has not yet beed parse()'d.

evaluate

public final java.lang.Object evaluate(Context data)
                                throws PropertyException
Parse the Template against the supplied context data and return it as a string. If the operation fails for some reason, such as unable to read template or unable to introspect the context then this method will return a null string.

Specified by:
evaluate in interface Macro
Throws:
PropertyException - if required data was missing from context

write

public final void write(FastWriter out,
                        Context data)
                 throws java.io.IOException,
                        PropertyException
A macro has a write method which takes a context and applies it to the macro to create a resulting String value, which is then written to the supplied stream. Something will always be written to the stream, even if the operation is not really successful because of a parse error (an error message will be written to the stream in that case.)

Specified by:
write in interface Macro
Throws:
java.io.IOException - if there is a problem writing to the Writer
PropertyException - if required data was missing from context

accept

public void accept(TemplateVisitor v)
Specified by:
accept in interface Visitable

getDefaultEncoding

protected final java.lang.String getDefaultEncoding()
return the default encoding either from the WebMacro config or the JVM settings Note for Unix users: you may need to set the environmental variable LC_ALL=[locale] to get the default one set up.


getParam

public java.lang.Object getParam(java.lang.String key)
                          throws java.io.IOException,
                                 TemplateException
Template API

Specified by:
getParam in interface Template
Throws:
TemplateException - if an error occurred parsing the template
java.io.IOException - if an error occurred reading the template

getParameters

public java.util.Map getParameters()
Specified by:
getParameters in interface Template

setParam

public void setParam(java.lang.String key,
                     java.lang.Object value)
Description copied from interface: Template
set a parameter. Occasinally it's necessary to provide parameters externally. Although these might be considered of a different nature to those set by #param, they can be stored as such. One example might be the output character encoding which is needed when the template is played.

Specified by:
setParam in interface Template