net.windward.datasource.dom4j
Class Dom4jDataSource

java.lang.Object
  |
  +--net.windward.datasource.dom4j.Dom4jDataSource

All Implemented Interfaces:

DataSourceProvider

public class Dom4jDataSource

extends java.lang.Object

implements DataSourceProvider

This supplies a data source to Windward Reports using dom4j. Dom4j is an xml DOM wrapper. This class is the reference implementation for net.windward.datasource.
To reference a data element from a <wr:forEach ... var="item" > or <wr:query ... var="item" > tag inside another tag, use the following construct: '${item}/xpath' where xpath is an xpath reference from the node defined by item and the reference will return a single element.
When inside a forEach where step='N' where N > 1, you can also use ${item[1]}/xpath ... ${item[N-1]}/xpath to reference data for the N rows in each step. ${item[0]}/xpath is legal but redundent. You can also use <wr:if test='$item[1]}'> which will return true if the row[1] exists. Keep in mind that [1], [2], ... is not an absolute count but an offset from the base row presently on in the loop. And you cannot index past the set of rows that are the row presently on and the rows that will be skipped by step.

Version:

4.0 1 May 2005

Constructor Summary

Dom4jDataSource(org.w3c.dom.Document document)
Create a DataSourceProvider that uses dom4j to traverse an xml stream.

Dom4jDataSource(org.dom4j.Element node)
Create a DataSourceProvider that uses dom4j to traverse an xml stream.

Dom4jDataSource(java.io.InputStream xmlData)
Create a DataSourceProvider that uses an xml stream as the data and dom4j to traverse it.

Dom4jDataSource(java.lang.String xmlData)
Create a DataSourceProvider that uses an xml stream as the data and dom4j to traverse it.

Method Summary

void	close() Called when processing is complete.
java.lang.String	dump() Display the entire dataset.
DataSourceNode	getRootNode() Returns the root node for this data set.
TagAttributes[]	getTagAttributes() Returns the allowed attributes for all tags.
void	log() Log all info about this datasource to debug.
void	setMap(java.util.Map map) Adds a map that is used for ${variable} substitution.
void	validateTag(BaseTag xmlTag) Verifys that a tag has all required attributes and no unknown attributes.

Methods inherited from class java.lang.Object

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

Constructor Detail

Dom4jDataSource

public Dom4jDataSource(java.io.InputStream xmlData)
                throws DataSourceException

Create a DataSourceProvider that uses an xml stream as the data and dom4j to traverse it.

Parameters:

xmlData - A well formed xml data file.

Throws:

DataSourceException - thrown if anything goes wrong.

Dom4jDataSource

public Dom4jDataSource(java.lang.String xmlData)
                throws DataSourceException

Create a DataSourceProvider that uses an xml stream as the data and dom4j to traverse it.

Parameters:

xmlData - A well formed xml data file.

Throws:

DataSourceException - thrown if anything goes wrong.

Dom4jDataSource

public Dom4jDataSource(org.dom4j.Element node)

Create a DataSourceProvider that uses dom4j to traverse an xml stream. The input is a node in a dom4j xml tree and can be any location in the tree. The node will be treated as the root of the data and any nodes below the passed in node are invisible.
Be aware that this does a deep copy so it can be expensive.

Parameters:

node - a Node created in dom4j pointing to all or part of a xml tree.

Dom4jDataSource

public Dom4jDataSource(org.w3c.dom.Document document)

Create a DataSourceProvider that uses dom4j to traverse an xml stream. The input is a w3c.org Document (not a dom4j Document). There is no constructor for a w3c Element - just this one for a w3c Document.
Be aware that this does a deep copy so it can be expensive.

Parameters:

document - a w3c Document.

Method Detail

getTagAttributes

public TagAttributes[] getTagAttributes()

Returns the allowed attributes for all tags.

Specified by:

getTagAttributes in interface DataSourceProvider

Returns:

The tag attributes.

validateTag

public void validateTag(BaseTag xmlTag)
                 throws TagException

Verifys that a tag has all required attributes and no unknown attributes.

Specified by:

validateTag in interface DataSourceProvider

Parameters:

xmlTag - The tag to check

Throws:

TagException - thrown if illegal parameters passed in.

setMap

public void setMap(java.util.Map map)

Adds a map that is used for ${variable} substitution. The map should be string pairs and the key values cannot have any of the characters ${} in them. When ${key} is found in any tag, it is replaced with the matching value. The key and value strings are not evaluated in any way, it is just a text replace. This replace occurs before any other evaluation of a tag so the value string can have ${variable} values that will then be evaluated.
This call sets the map so calling it a second time replaces the map passed in the first time. The map is copied so on return changes to the passed in map will not affect the data source.

Specified by:

setMap in interface DataSourceProvider

Parameters:

map - The map of string pairs.

getRootNode

public DataSourceNode getRootNode()

Returns the root node for this data set. Outside of forEach loops this is the node all tag requests will be evaluated against.

Specified by:

getRootNode in interface DataSourceProvider

Returns:

The root node.

close

public void close()

Called when processing is complete. Used to close any resources opened by this object. Does nothing.

Specified by:

close in interface DataSourceProvider

Following copied from interface: net.windward.datasource.DataSourceProvider

Throws:

DataSourceException - Could not retrieve the data. Generally wraps a SqlException or XpathException.

log

public void log()

Log all info about this datasource to debug.

Specified by:

log in interface DataSourceProvider

dump

public java.lang.String dump()
                      throws DataSourceException

Display the entire dataset. This is used for debug level logging only.

Specified by:

dump in interface DataSourceProvider

Returns:

The entire dataset in a human readable format.

Throws:

DataSourceException - thrown if has any problems reading the dataset.