au.com.forward.webstringtemplate
Class WebStringTemplate

java.lang.Object
  org.antlr.stringtemplate.StringTemplate
      au.com.forward.webstringtemplate.WebStringTemplate

All Implemented Interfaces:

java.util.Map

public class WebStringTemplate

extends StringTemplate

implements java.util.Map

A WebStringTemplate.
This class holds both the page template and the data map.

See the documentation for details of its use.

Author:

matthew ford

Nested Class Summary

Nested classes inherited from class java.util.Map

java.util.Map.Entry

Field Summary

static java.lang.String	DATA_CSS_FILE_PATH The name of the default HTML data map style file (dataStyle.css).
static java.lang.String	DATA_CSS_NAME The name of the default HTML data map style resource (dataStyle.css).
static int	DEFAULT_BUFFER_SIZE Default buffer size, 8192
static int	DEFAULT_MAX_DEPTH Default recursion level (3) used when writing out the HTML data map.
static java.util.logging.Logger	logger The Java Logger for this class
static java.lang.String	OUTPUT_BUFFER_SIZE The name of the attibute (wst.bufferSize) that sets the output buffer size for this template
static java.lang.String	OUTPUT_DATA_DEFINITION_FLAG The name of the attribute (wst.outputDataDefinition) that controls writing out the attribute map as a HTML data definition map.
static java.lang.String	OUTPUT_MAX_DEPTH The name of the attribute (wst.outputDataDefinition.maxDepth) that sets the recursion depth when writing out the HTML data map.
static java.lang.String	OUTPUT_SHOW_ALL_FLAG The name of the attribute (wst.outputDataDefinition.showAll) that controls if all attributes should be output.
static java.lang.String	OUTPUT_SHOW_FILTERS_FLAG The name of the attribute (wst.outputDataDefinition.showFilters) that controls if all the filter class name used for this string should be output before the string.
static java.lang.String	VERSION The version number - 1.5
static java.lang.String	VERSION_DATE The version date 22th Jan. 2004
static java.lang.String	WST_ATTRIBUTE_START Description of the Field
static java.lang.String	WST_COMMENT_ENDING The attribute name ending (.comment) that signifies an attribute comment (case insensitive).

Constructor Summary

WebStringTemplate(WebStringTemplateGroup group)
Create a blank template with no pattern and an empty attribute data map

WebStringTemplate(WebStringTemplateGroup group, java.util.Map initialValues)
Create a blank template with this data map of values

WebStringTemplate(WebStringTemplateGroup group, java.lang.String template)
Create an anonymous template with no name, but with a group

Method Summary

void	addAttribute(java.lang.String name, java.lang.Object value) Adds an attribute for this template data map.
java.lang.String	attributeHashtableToHTML(java.util.Map table, java.lang.String title, java.lang.String styleSheetPath) Outputs the template data map as a HTML data map.
void	attributeHashtableToHTML(java.util.Map table, java.lang.String title, java.lang.String styleSheetPath, int maxLevel, java.io.Writer out) Outputs the template data map as a HTML data map.
void	clear() Removes all mappings from this template data map.
boolean	containsKey(java.lang.Object key) Returns true if this template data map contains a mapping for the specified key.
boolean	containsValue(java.lang.Object value) Returns true if this template data map maps one or more keys to the specified value.
java.lang.Object	convertToArrayList(java.lang.Object value) Convert value to arrayList if needed.
java.lang.String	convertToString(java.lang.Object obj) Convert to string and trim leading and trailing spaces
static java.lang.String	dataEscape(java.lang.String input) Replaces non-ascii chars with unicode escapes and replaces in data output with , wrapps the whole in .
java.util.Set	entrySet() Returns a set view of the mappings contained in this template data map.
java.lang.Object	get(java.lang.Object key) Returns the value to which this template data map maps the specified key.
java.lang.Object	get(StringTemplate self, java.lang.String attribute) Resolve an attribute reference.
java.lang.Object	getAttribute(java.lang.String name) Gets the attribute value from this WebStringTemplate object.
java.lang.String	getNameForPath() Gets the nameForPath attribute of the WebStringTemplate object
int	getOutputBufferSize() The buffer size of the internal StringBuffer is controlled by the wst.buffersize attribute or set to 8192 bytes if this attribute is missing or not an integer.
WebStringTemplateGroup	getWebStringTemplateGroup() Gets the group of this WebStringTemplate.
boolean	isEmpty() Returns true if this template data map contains no key-value mappings.
java.util.Set	keySet() Returns a set view of the keys contained in this template data map.
static java.lang.String	loadConvert(java.lang.String theString) Converts encoded \uxxxx to unicode chars matches saveConvert in WebStringTemplate
java.lang.Object	put(java.lang.Object attributeName, java.lang.Object value) Associates the specified value with the specified attribute name in this template data map.
void	putAll(java.util.Map t) Copies all of the mappings from the specified map to this map.
java.lang.Object	remove(java.lang.Object key) Removes the mapping for this key from this template data map if it is present.
void	setAttribute(java.lang.String name, java.lang.Object value) Set an attribute.
void	setGroup(StringTemplateGroup group) Sets the group of this WebStringTemplate
void	setTemplate(java.lang.String template) un-encode Unicode characters before passing to StringTemplate
void	setWebStringTemplateGroup(WebStringTemplateGroup group) Sets the group of this WebStringTemplate
int	size() Returns the number of key-value mappings in this template data map.
boolean	skipThisAttibute(java.lang.String attributeName) Is this attribute name to be skipped when outputting the HTML data map.
boolean	skipThisClass(java.lang.String className) Should this class be skipped when output the values of the data map.
boolean	skipThisMethod(java.lang.String methodName) Should this method be skipped when doing object introspection.
boolean	testObjectTrue(java.lang.Object a) Tests if an object is not false.
java.lang.String	toString() Output this template, using the current attribute data map.
java.util.Collection	values() Returns a collection view of the values contained in this template data map.
java.lang.Object	wrapWithFilter(java.lang.Object value, IWSTFilter filter) Wrap an object with the given filter, but only if the object is not already wrapped.
void	write(java.io.Writer out) Output this template, using the current attribute data map.

Methods inherited from class org.antlr.stringtemplate.StringTemplate

checkForTrouble, debug, error, error, getArgumentContext, getArgumentsAST, getAttributes, getChunks, getErrorListener, getGroup, getInstanceOf, getInstanceOfWithAttributes, getName, getTemplate, getTemplateID, inLintMode, isDebugMode, removeAttribute, reset, setArgumentContext, setArgumentsAST, setAttributes, setDebugMode, setEnclosingInstance, setErrorListener, setLintMode, setName, toDebugString, warning

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.util.Map

equals, hashCode

Field Detail

logger

public static final java.util.logging.Logger logger

The Java Logger for this class

VERSION

public static final java.lang.String VERSION

The version number - 1.5

See Also:

Constant Field Values

VERSION_DATE

public static final java.lang.String VERSION_DATE

The version date 22th Jan. 2004

See Also:

Constant Field Values

WST_ATTRIBUTE_START

public static final java.lang.String WST_ATTRIBUTE_START

Description of the Field

See Also:

Constant Field Values

OUTPUT_BUFFER_SIZE

public static final java.lang.String OUTPUT_BUFFER_SIZE

The name of the attibute (wst.bufferSize) that sets the output buffer size for this template

See Also:

Constant Field Values

OUTPUT_DATA_DEFINITION_FLAG

public static final java.lang.String OUTPUT_DATA_DEFINITION_FLAG

The name of the attribute (wst.outputDataDefinition) that controls writing out the attribute map as a HTML data definition map.
If this attribute exists and is not false, the HTML data definition map will be written out instead of the processed template.

See Also:

Constant Field Values

OUTPUT_MAX_DEPTH

public static final java.lang.String OUTPUT_MAX_DEPTH

The name of the attribute (wst.outputDataDefinition.maxDepth) that sets the recursion depth when writing out the HTML data map.
Only used if wst.outputDataDefinition is not false.

See Also:

Constant Field Values

OUTPUT_SHOW_ALL_FLAG

public static final java.lang.String OUTPUT_SHOW_ALL_FLAG

The name of the attribute (wst.outputDataDefinition.showAll) that controls if all attributes should be output.
If this attribute exists and is not false, the HTML data map will contain all the attributes in the map even if they cannot be accessed by the template. Only used if wst.outputDataDefinition is not false.

See Also:

Constant Field Values

OUTPUT_SHOW_FILTERS_FLAG

public static final java.lang.String OUTPUT_SHOW_FILTERS_FLAG

The name of the attribute (wst.outputDataDefinition.showFilters) that controls if all the filter class name used for this string should be output before the string.
Only used if wst.outputDataDefinition is not false.

See Also:

Constant Field Values

WST_COMMENT_ENDING

public static final java.lang.String WST_COMMENT_ENDING

The attribute name ending (.comment) that signifies an attribute comment (case insensitive).
Use this ending to create an attribute name to hold a comment describing the attribute.

See Also:

Constant Field Values

DATA_CSS_NAME

public static final java.lang.String DATA_CSS_NAME

The name of the default HTML data map style resource (dataStyle.css).

See Also:

Constant Field Values

DATA_CSS_FILE_PATH

public static final java.lang.String DATA_CSS_FILE_PATH

The name of the default HTML data map style file (dataStyle.css).
Used if built-in style resource cannot be found.

See Also:

Constant Field Values

DEFAULT_MAX_DEPTH

public static final int DEFAULT_MAX_DEPTH

Default recursion level (3) used when writing out the HTML data map.

See Also:

Constant Field Values

DEFAULT_BUFFER_SIZE

public static final int DEFAULT_BUFFER_SIZE

Default buffer size, 8192

See Also:

Constant Field Values

Constructor Detail

WebStringTemplate

public WebStringTemplate(WebStringTemplateGroup group)

Create a blank template with no pattern and an empty attribute data map

Parameters:

group - the group to attach this template to. Must be a WebStringTemplateGroup*

WebStringTemplate

public WebStringTemplate(WebStringTemplateGroup group,
                         java.util.Map initialValues)

Create a blank template with this data map of values

Parameters:

group - the group to attach this template to. Must be a WebStringTemplateGroup*

initialValues - the data map of values. No check is made that this map has valid keys.

WebStringTemplate

public WebStringTemplate(WebStringTemplateGroup group,
                         java.lang.String template)

Create an anonymous template with no name, but with a group

Parameters:

group - the group to attach this template to. Must be a WebStringTemplateGroup

template - the template as a String

Throws:

java.lang.IllegalArgumentException - if group null or not a WebStringTemplateGroup

Method Detail

setGroup

public void setGroup(StringTemplateGroup group)

Sets the group of this WebStringTemplate

Overrides:

setGroup in class StringTemplate

Parameters:

group - The new group. Must be a WebStringTemplateGroup. Cannot be null.

Throws:

java.lang.IllegalArgumentException - if group null or not a WebStringTemplateGroup

getWebStringTemplateGroup

public WebStringTemplateGroup getWebStringTemplateGroup()

Gets the group of this WebStringTemplate.
Just calles super.getGroup() but casts result to WebStringTemplateGroup

Returns:

group a WebStringTemplateGroup

setWebStringTemplateGroup

public void setWebStringTemplateGroup(WebStringTemplateGroup group)

Sets the group of this WebStringTemplate

Parameters:

group - The new group. Cannot be null.

Throws:

java.lang.IllegalArgumentException - if group null

setAttribute

public void setAttribute(java.lang.String name,
                         java.lang.Object value)

Set an attribute.
null values are stored as "" (an empty string).
If the attribute name ends in .extension, look for assocaited filter. If a filter is found then strip the extension and wrap value in the filter, only if it not already wrapped.
names that start with wst. are control attributes and are not check for filter extensions.

Overrides:

setAttribute in class StringTemplate

Parameters:

name - The attribute name

value - The new attribute value

getAttribute

public java.lang.Object getAttribute(java.lang.String name)

Gets the attribute value from this WebStringTemplate object.
Just calls get(this,name)

Overrides:

getAttribute in class StringTemplate

Parameters:

name - the attribute key

Returns:

The attribute value, wrapped in a filter

get

public java.lang.Object get(StringTemplate self,
                            java.lang.String attribute)

Resolve an attribute reference.
It can be in three possible places:
1. the attribute list for the current template
2. if self is an embedded template, somebody invoked us possibly with arguments--check the argument context
3. if self is an embedded template, the attribute list for the enclosing instance

Overrides:

get in class StringTemplate

Parameters:

self - the StringTemplate to look in first

attribute - the attribute key

Returns:

The attribute value, wrapped in a filter

getNameForPath

public java.lang.String getNameForPath()

Gets the nameForPath attribute of the WebStringTemplate object

Returns:

The nameForPath value

setTemplate

public void setTemplate(java.lang.String template)

un-encode Unicode characters before passing to StringTemplate

Overrides:

setTemplate in class StringTemplate

Parameters:

template - The new template value

get

public java.lang.Object get(java.lang.Object key)

Returns the value to which this template data map maps the specified key. Returns null if the map contains no mapping for this key.

Specified by:

get in interface java.util.Map

Parameters:

key - the String key whose associated value is to be returned.

Returns:

the value to which this map maps the specified key, or null if the map contains no mapping for this key or if the key is null.

Throws:

java.lang.ClassCastException - if the key is not a String.

See Also:

containsKey(Object)

put

public java.lang.Object put(java.lang.Object attributeName,
                            java.lang.Object value)

Associates the specified value with the specified attribute name in this template data map.
If the map previously contained a mapping for this attribute name, the old value is replaced by the specified value.

If the attribute name ends in .extension, look for assocaited filter. If a filter is found then strip the extension and wrap value in the filter, only if it not already wrapped.
names that start with wst. are control attributes and are not check for filter extensions.

Specified by:

put in interface java.util.Map

Parameters:

attributeName - the name of this of this value.

value - value to be associated with this attribute name.

Returns:

previous value associated with this attribute name, or null if there was no mapping for key.

Throws:

java.lang.ClassCastException - if the attributeName is not a String.

java.lang.IllegalArgumentException - if the key is not a valid attributeName (i.e [. | _ | alpha][. | _ | alpha | digit]* )

size

public int size()

Returns the number of key-value mappings in this template data map. If the map contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE .

Specified by:

size in interface java.util.Map

Returns:

the number of key-value mappings in this map.

isEmpty

public boolean isEmpty()

Returns true if this template data map contains no key-value mappings.

Specified by:

isEmpty in interface java.util.Map

Returns:

true if this map contains no key-value mappings.

containsKey

public boolean containsKey(java.lang.Object key)

Returns true if this template data map contains a mapping for the specified key.

Specified by:

containsKey in interface java.util.Map

Parameters:

key - the String key whose presence in this map is to be tested.

Returns:

true if this map contains a mapping for the specified key.

Throws:

java.lang.ClassCastException - if the key is not a String.

containsValue

public boolean containsValue(java.lang.Object value)

Returns true if this template data map maps one or more keys to the specified value. This operation will probably require time linear in the map size for most implementations.

Specified by:

containsValue in interface java.util.Map

Parameters:

value - value whose presence in this map is to be tested.

Returns:

true if this map maps one or more keys to the specified value.

Throws:

java.lang.NullPointerException - if the value is null .

remove

public java.lang.Object remove(java.lang.Object key)

Removes the mapping for this key from this template data map if it is present.

Returns the value to which the map previously associated the key, or null if the map contained no mapping for this key. The map will not contain a mapping for the specified key once the call returns.

Specified by:

remove in interface java.util.Map

Parameters:

key - the String key whose mapping is to be removed from the map.

Returns:

previous value associated with specified key, or null if there was no mapping for key.

Throws:

java.lang.ClassCastException - if the key is not a String.

java.lang.NullPointerException - if the key is null .

putAll

public void putAll(java.util.Map t)

Copies all of the mappings from the specified map to this map. This operation is not supported on template data maps.

Specified by:

putAll in interface java.util.Map

Parameters:

t - map to put

Throws:

java.lang.UnsupportedOperationException - if the putAll method is called.

clear

public void clear()

Removes all mappings from this template data map.

Specified by:

clear in interface java.util.Map

keySet

public java.util.Set keySet()

Returns a set view of the keys contained in this template data map. The set is backed by the map, so changes to the map are reflected in the set, and vice-versa. If the map is modified while an iteration over the set is in progress, the results of the iteration are undefined. The set supports element removal, which removes the corresponding mapping from the map, via the Iterator.remove , Set.remove , removeAll retainAll , and clear operations. It does not support the add or addAll operations.

Specified by:

keySet in interface java.util.Map

Returns:

a set view of the keys contained in this map.

values

public java.util.Collection values()

Returns a collection view of the values contained in this template data map. The collection is backed by the map, so changes to the map are reflected in the collection, and vice-versa. If the map is modified while an iteration over the collection is in progress, the results of the iteration are undefined. The collection supports element removal, which removes the corresponding mapping from the map, via the Iterator.remove , Collection.remove , removeAll , retainAll and clear operations. It does not support the add or addAll operations.

Specified by:

values in interface java.util.Map

Returns:

a collection view of the values contained in this map.

entrySet

public java.util.Set entrySet()

Returns a set view of the mappings contained in this template data map. Each element in the returned set is a Map.Entry. The set is backed by the map, so changes to the map are reflected in the set, and vice-versa. If the map is modified while an iteration over the set is in progress, the results of the iteration are undefined. The set supports element removal, which removes the corresponding mapping from the map, via the Iterator.remove , Set.remove , removeAll , retainAll and clear operations. It does not support the add or addAll operations.

Specified by:

entrySet in interface java.util.Map

Returns:

a set view of the mappings contained in this map.

testObjectTrue

public boolean testObjectTrue(java.lang.Object a)

Tests if an object is not false.
Returns false for a null object, obj.toString()=="false" or obj.toString()=="" or obj.toString()=="0" (zero)
All other objects return true

Overrides:

testObjectTrue in class StringTemplate

Parameters:

a - the object to test

Returns:

true if the object is not false

wrapWithFilter

public java.lang.Object wrapWithFilter(java.lang.Object value,
                                       IWSTFilter filter)

Wrap an object with the given filter, but only if the object is not already wrapped.

Parameters:

value - the object to wrap

filter - the fiter to wrap it in, if it is not already wrapped. If null use the filter returned by WebStringTemplateGroup.getDefaultFilter().

Returns:

the wrapped object

convertToString

public java.lang.String convertToString(java.lang.Object obj)

Convert to string and trim leading and trailing spaces

Overrides:

convertToString in class StringTemplate

Parameters:

obj - the object to convert

Returns:

""+obj or a string containing the error that occured while trying to convert obj to a string.

convertToArrayList

public java.lang.Object convertToArrayList(java.lang.Object value)

Convert value to arrayList if needed.
In any case wrap in defaultFilter in not already wrapped in a filter

Overrides:

convertToArrayList in class StringTemplate

Parameters:

value - the object to convert

Returns:

the object converted to an ArrayList if it was an array or Enumeration or Iterator or Collection. The return object is always wrapped.
If the input value was wrapped, the return and all its list elements are also wrapped in the same filter, unless the element was already wrapped, else
if the input was not wrapped then the return and all its list elements are also wrapped in the the filter returned by WebStringTemplateGroup.getDefaultFilter(), , unless the element was already wrapped.

addAttribute

public void addAttribute(java.lang.String name,
                         java.lang.Object value)

Adds an attribute for this template data map.
If you add the same attribute more than once, you get a multi-valued attribute.
If the attribute name ends in .extension, look for assocaited filter. If a filter is found then strip the extension and wrap value in the filter, only if it not already wrapped.
names that start with wst. are control attributes and are not check for filter extensions. If you send in a StringTemplate object as a value, it's enclosing instance (where it will inherit values from) is set to 'this'. This would be the normal case, though you can set it back to null after this call if you want.
If you send in a List plus other values to the same attribute, they all get flattened into one List of values.
If you send in an array, it is converted to a List. Works with arrays of objects and arrays of {int,short,float,double,byte,char,boolean} and Enumeration, Iterator and Collection.

Parameters:

name - The name of this attribute

value - the value associated with this attribute name. Null values are saved as ""

Throws:

java.lang.NullPointerException - if name is null

IllegalArguementException - if the name does not match [. | _ | alpha][. | _ | alpha | digit]*

dataEscape

public static java.lang.String dataEscape(java.lang.String input)

Replaces non-ascii chars with unicode escapes and replaces in data output with , wrapps the whole in .
Handles null input.
This allows the data to be read back in exactly as it would appear in the template.

Parameters:

input - the string to escape

Returns:

the escaped string, or null if input was null

loadConvert

public static java.lang.String loadConvert(java.lang.String theString)

Converts encoded \uxxxx to unicode chars matches saveConvert in WebStringTemplate

Parameters:

theString - the string to convert

Returns:

the converted string

attributeHashtableToHTML

public java.lang.String attributeHashtableToHTML(java.util.Map table,
                                                 java.lang.String title,
                                                 java.lang.String styleSheetPath)

Outputs the template data map as a HTML data map.
Any < in the data are escaped with &shy; to ensure the data can be read back in exactly as output.

The output is controlled by the wst.outputDataDefinition.showAll and wst.outputDataDefinition.maxDepth settings.

Parameters:

table - the template data map to output. (Should work for any map.)

styleSheetPath - the style sheet path for an external stylesheet or null to embed the default one in the output file.

title - the title of the HTML output page

Returns:

the HTML output

attributeHashtableToHTML

public void attributeHashtableToHTML(java.util.Map table,
                                     java.lang.String title,
                                     java.lang.String styleSheetPath,
                                     int maxLevel,
                                     java.io.Writer out)
                              throws java.io.IOException

Outputs the template data map as a HTML data map.
Any < in the data are escaped with &shy; to ensure the data can be read back in exactly as output.

The output is controlled by the wst.outputDataDefinition.showAll setting.

Parameters:

table - the template data map to output. (Should work for any map.)

styleSheetPath - the style sheet path for an external stylesheet or null to embed the default one in the output file.

title - the title of the HTML output page

maxLevel - the maximum depth to recurse to when outputting.

out - Description of the Parameter

Throws:

java.io.IOException - Description of the Exception

skipThisMethod

public boolean skipThisMethod(java.lang.String methodName)

Should this method be skipped when doing object introspection.
Skip getOutputStream(), getInputStream(), getWriter(), getReader() and getClass().

Parameters:

methodName - the name of the method

Returns:

true if this method is to be skipped

skipThisClass

public boolean skipThisClass(java.lang.String className)

Should this class be skipped when output the values of the data map.
Skip javax.servlet.* and org.apache.* except org.apache.taglibs.standard.tag.common.sql.ResultImpl

Parameters:

className - the string class name of this object.

Returns:

true if this object should be skipped (not output)

skipThisAttibute

public boolean skipThisAttibute(java.lang.String attributeName)

Is this attribute name to be skipped when outputting the HTML data map.
If showAll, then don't skip any. Else skip attributes with invalid names and attribute names which contain '.' except .comment attributes

Parameters:

attributeName - the attribute name.

Returns:

true if the associated attribute value should be skipped (not output)

toString

public java.lang.String toString()

Output this template, using the current attribute data map.
If wst.outputDataDefinition is not false then instead of processing the template, output the attributes as a HTML page.

Overrides:

toString in class StringTemplate

Returns:

a String containing either the result of write(java.io.Writer) or attributeHashtableToHTML()

getOutputBufferSize

public int getOutputBufferSize()

The buffer size of the internal StringBuffer is controlled by the wst.buffersize attribute or set to 8192 bytes if this attribute is missing or not an integer.

Returns:

The outputBufferSize value

write

public void write(java.io.Writer out)
           throws java.io.IOException

Output this template, using the current attribute data map.
If wst.outputDataDefinition is not false then instead of processing the template, output the attributes as a HTML page.

Overrides:

write in class StringTemplate

Parameters:

out - Description of the Parameter

Throws:

java.io.IOException - Description of the Exception