Forward Computing and Control Pty. Ltd.
WebStringTemplate V1.5.0

2004/1/7

au.com.forward.webstringtemplate
Class WebStringTemplateGroup

java.lang.Object
  extended byorg.antlr.stringtemplate.StringTemplateGroup
      extended byau.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

Forward Computing and Control Pty. Ltd.
WebStringTemplate V1.5.0

2004/1/7

Copyright ©2003, Forward Computing and Control Pty. Ltd
ACN 003 669 994   NSW Australia,   All Rights Reserved.
WebStringTemplate and associated code is released under licence. See the source.
WebStringTemplate uses code from StringTemplates and Antlr, under licence.
See the WebStringTemplate licence file for details.