au.com.forward.webstringtemplate
Class WebStringTemplateGroup

java.lang.Object
  org.antlr.stringtemplate.StringTemplateGroup
      au.com.forward.webstringtemplate.WebStringTemplateGroup

public class WebStringTemplateGroup

extends StringTemplateGroup

Manages a group of named mutually-referential WebStringTemplate objects.
See the documenation for details.
Currently the templates must all live under the same directory so that you can reference them as foo.st or gutter/header.st.
To refresh a group of templates, just create a new WebStringTemplateGroup and start pulling templates from there, or, set the refresh interval.

Use getInstanceOf(template-name) to get a string template to fill in. The name of a template is the file name minus ".st" ending.

Author:

matthew ford

Field Summary

static StringTemplateErrorListener	DEFAULT_SERVLET_ERROR_LISTENER The default error listener for all the WebStringTemplates
static java.util.logging.Logger	logger The Java logger for this class

Fields inherited from class org.antlr.stringtemplate.StringTemplateGroup

DEFAULT_ERROR_LISTENER

Constructor Summary

WebStringTemplateGroup(java.lang.String name, java.lang.String rootDir)
Create a group manager for some templates, all of which are loaded from the rootDir or classpath if rootDir is null.

WebStringTemplateGroup(java.lang.String name, java.lang.String rootDir, java.lang.String delimiterStart, java.lang.String delimiterStop)
Create a group manager for some templates, all of which are loaded from the rootDir or classpath if rootDir is null.

Method Summary

StringTemplate	createStringTemplate(java.util.Map initialValues) Create a StringTemplate of the correct class, used when sub-classing.
java.lang.Object[][]	getAllFilters() Returns a copy of the defined filters.
java.util.Map	getData(java.lang.String fileName) Gets the attributes from a HTML data file.
IWSTFilter	getDefaultFilter() Gets the defaultFilter for this WebStringTemplateGroup
IWSTFilter	getFilter(java.lang.String nameExtension) Gets the filter associated with this extension (case sensitive).
StringTemplate	getInstanceOf(java.lang.String name) Gets the instanceOf a WebStringTemplate with an empty data map.
WebStringTemplate	getInstanceOf(java.lang.String templateName, java.lang.String dataFileName) Gets the instanceOf a WebStringTemplate loaded with data from a HTML data file.
boolean	isMissingDataErrorPathReturn() Gets the missingDataErrorPathReturn setting.
static WebStringTemplate	setAttributes(WebStringTemplate wst, java.util.Map attributes) Add these attributes to the top level of the data map of the template.
IWSTFilter	setDefaultFilter(IWSTFilter filter) Set the default filter to use to filter strings passed to the template from the data map.
void	setErrorListener(StringTemplateErrorListener listener) Sets the default errorListener of the WebStringTemplates in this group
IWSTFilter	setFilter(java.lang.String nameExtension, IWSTFilter filter) Set the filter associated with this name extension.
void	setMissingDataErrorPathReturn(boolean flag) Sets the missingDataErrorPathReturn

Methods inherited from class org.antlr.stringtemplate.StringTemplateGroup

defineTemplate, error, error, getDelimiterStart, getDelimiterStop, getEmbeddedInstanceOf, getEmbeddedInstanceOf, getErrorListener, getFileNameFromTemplateName, getInstanceOf, getName, getRefreshInterval, getRootDir, getSuperGroup, getTemplate, getTemplateNameFromFileName, loadTemplate, loadTemplate, setName, setRefreshInterval, setRootDir, setSuperGroup, setSuperGroup, toString

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

logger

public static final java.util.logging.Logger logger

The Java logger for this class

DEFAULT_SERVLET_ERROR_LISTENER

public static StringTemplateErrorListener DEFAULT_SERVLET_ERROR_LISTENER

The default error listener for all the WebStringTemplates

Constructor Detail

WebStringTemplateGroup

public WebStringTemplateGroup(java.lang.String name,
                              java.lang.String rootDir)

Create a group manager for some templates, all of which are loaded from the rootDir or classpath if rootDir is null.
Uses "$[" and "]$" as delimiters.

The default filter is WSTXmlFilter and the name extension .plain is set to WSTPlainFiter and .xml is set to WSTXmlFilter

Parameters:

name - the name of group

rootDir - root dir to load templates from or null to use classpath. Any trailing / or file.separator is stripped.

WebStringTemplateGroup

public WebStringTemplateGroup(java.lang.String name,
                              java.lang.String rootDir,
                              java.lang.String delimiterStart,
                              java.lang.String delimiterStop)

Create a group manager for some templates, all of which are loaded from the rootDir or classpath if rootDir is null.
The default filter is WSTXmlFilter and the name extension .plain is set to WSTPlainFiter and .xml is set to WSTXmlFilter

Parameters:

name - name of group

rootDir - root dir to load templates from or null to use classpath. Any trailing / or file.separator is stripped

delimiterStart - start delimiter

delimiterStop - end delimiter

Method Detail

createStringTemplate

public StringTemplate createStringTemplate(java.util.Map initialValues)

Create a StringTemplate of the correct class, used when sub-classing.

Overrides:

createStringTemplate in class StringTemplateGroup

Parameters:

initialValues - map of attribute values

Returns:

a stringtemplate of the correct class

isMissingDataErrorPathReturn

public boolean isMissingDataErrorPathReturn()

Gets the missingDataErrorPathReturn setting.

Returns:

true if missing data returns an error path, else false

setMissingDataErrorPathReturn

public void setMissingDataErrorPathReturn(boolean flag)

Sets the missingDataErrorPathReturn

Parameters:

flag - true if missing data is to return an error path, else false

setDefaultFilter

public IWSTFilter setDefaultFilter(IWSTFilter filter)

Set the default filter to use to filter strings passed to the template from the data map.
This filter is only used if the attribute is not already wrapped in a filter.

Parameters:

filter - The defaultFilter

Returns:

the previous defaultFilter or null if none previously set.

Throws:

java.lang.NullPointerException - if filter null.

getDefaultFilter

public IWSTFilter getDefaultFilter()

Gets the defaultFilter for this WebStringTemplateGroup

Returns:

The defaultFilter

setFilter

public IWSTFilter setFilter(java.lang.String nameExtension,
                            IWSTFilter filter)

Set the filter associated with this name extension.
Don't set a filter for ".comment" as this extension is used for commenting the data definition file.

Parameters:

nameExtension - The attribute extension to associate this filter with. Any leading '.' is stripped.

filter - The filter to associate with this extension, null to remove association.

Returns:

the previous filter for this extension, or null if none previously set.

Throws:

java.lang.NullPointerException - if filter null and nameExtension is "". I.e. cannot remove the default filter.

java.lang.IllegalArgumentException - if extension name is "comment" (ignoring case).

getFilter

public IWSTFilter getFilter(java.lang.String nameExtension)

Gets the filter associated with this extension (case sensitive).
Strips any leading '.' from the extension before doing lookup

Parameters:

nameExtension - Description of the Parameter

Returns:

The filter assocaited with this extension or null if none set.

getAllFilters

public java.lang.Object[][] getAllFilters()

Returns a copy of the defined filters.

Returns:

Object[][2] of String key, IWSFilter pairs

setErrorListener

public void setErrorListener(StringTemplateErrorListener listener)

Sets the default errorListener of the WebStringTemplates in this group

Overrides:

setErrorListener in class StringTemplateGroup

Parameters:

listener - The errorListener value

Throws:

java.lang.NullPointerException - if listener is null.

getData

public java.util.Map getData(java.lang.String fileName)

Gets the attributes from a HTML data file.
Looks in the cache first and returns a clone of the previously loaded data if it is available.
Else if rootDir is null try and load as a resource from the classpath else load from rootDir+'/'+fileName.

If an error occures during loading, StringTemplateErrorListener.error(java.lang.String, java.lang.Throwable) is called and the map set to null. Note: the StringTemplateErrorListener.error(java.lang.String, java.lang.Throwable) may throw an exception and not return.

All attribute values are loaded as Strings. Each attribute is wrapped in a WSTPlainFilter to ensure it is delivered to the template exactly as loaded.

To generate HTML data, create a template and set its attribute data map and then set the attribute wst.outputDataDefinition to "true" in the template data map and call template.toString() and save the resulting string in a file.

Parameters:

fileName - the name of the HTML data file to load (including extension.)

Returns:

The template data map or null if error occured in loading.

Throws:

java.lang.NullPointerException - if fileName is null.

getInstanceOf

public StringTemplate getInstanceOf(java.lang.String name)

Gets the instanceOf a WebStringTemplate with an empty data map.
You need to cast the result i.e. (WebStringTemplate)getInstanceOf(name);
Use getInstanceOf(name,(String)null); instead as this returns a WebStringTemplate so a cast is not needed.

Overrides:

getInstanceOf in class StringTemplateGroup

Parameters:

name - the file name of the template (without the .st)

Returns:

the WebStringTemplate object

getInstanceOf

public WebStringTemplate getInstanceOf(java.lang.String templateName,
                                       java.lang.String dataFileName)

Gets the instanceOf a WebStringTemplate loaded with data from a HTML data file.

Parameters:

templateName - Name of template to load (without the trailing '.st')

dataFileName - the name of the data file to intialize this template with (including extension) or null if no dataFile to be loaded.

Returns:

The WebStringTemplate with attributes set to those in the datafile

setAttributes

public static WebStringTemplate setAttributes(WebStringTemplate wst,
                                              java.util.Map attributes)

Add these attributes to the top level of the data map of the template.
If any already exist they are overwritten by these.
Any non-String keys are quietly ignored and any invalid attribute names are not loaded.

Parameters:

wst - the WebStringTemplate

attributes - the map containing the attributes to add

Returns:

The updated string template