net.windward.datasource
Interface DataSourceNode

public interface DataSourceNode

This represents a node in the dataset. Every time a forEach loop is entered one of these nodes must be created and is pushed on to the stack of forEach nodes. When a forEach is exited, the node is pop'ed off the stack. The base node is the DataSourceProvider.getRootNode().

Version:

2.0 2 January 2004

Method Summary

void	addQuery(QueryTag tag, DataSourceNode[] stack) Called for a query tag.
void	addSet(SetTag tag, DataSourceNode[] stack) Called for a set tag.
java.lang.String	adjustSelect(java.lang.String select, DataSourceNode[] stack) This method is only called by AutoTag.
void	close() We are done with this node.
boolean	evaluate(java.lang.String text, DataSourceNode[] stack) Evaluate an expression for the boolean result.
java.io.InputStream	getBitmap(OutTag tag, DataSourceNode[] stack) Called when tag is of type BITMAP.
net.windward.chart.ChartDataSet	getData(ChartTag tag, DataSourceNode[] stack, java.util.Locale locale) Returns a set of data used to create a chart.
java.lang.String	getEscape(EscapeTag tag, DataSourceNode[] stack) Called for an escape tag.
java.lang.Object	getForEach(ForEachTag tag, DataSourceNode[] stack) This method is only called by AutoTag.
java.lang.String[]	getFunction(FunctionTag tag, DataSourceNode[] stack) Called for a function tag.
java.lang.String	getHtml(HtmlTag tag, DataSourceNode[] stack) Called for an html tag.
java.lang.String	getImport(ImportTag tag, DataSourceNode[] stack) Called for an import tag.
DataSourceIterator	getIterator() Returns the iterator presently in use for this node.
java.lang.String	getLink(LinkTag tag, DataSourceNode[] stack) Called for a link tag.
MetaDataElement[]	getMetaData(BaseTag tag, int index, DataSourceNode[] stack) This method is only called by AutoTag.
java.lang.String	getOut(OutTag tag, DataSourceNode[] stack, java.util.Locale locale) Called for an out tag.
java.io.InputStream	getOutStream(OutTag tag, DataSourceNode[] stack) Called for an out tag.
java.lang.Object	getQuery(QueryTag tag, DataSourceNode[] stack) This method is only called by AutoTag.
java.lang.String	getSet(SetTag tag, DataSourceNode[] stack) This method is only called by AutoTag.
boolean	isExistingNode(BaseTag tag, DataSourceNode[] stack) Return true if the passed in node exists.
boolean	isIf(IfTag tag, DataSourceNode[] stack) Called for an if tag.
boolean	isSelect(java.lang.String select)
DataSourceIterator	iterator(ForEachTag tag, DataSourceNode[] stack) Called for a forEach tag.

Method Detail

getMetaData

public MetaDataElement[] getMetaData(BaseTag tag,
                                     int index,
                                     DataSourceNode[] stack)
                              throws DataSourceException

This method is only called by AutoTag. It is never called by the engine and can just throw an exception for a datasource written for the engine only. This calls the select for a tag and returns the nodes returned by the select.

Parameters:

tag - The tag to run.

index - For a chart tag this is which graph in the chart to run the select on.

stack - The stack of forEach loops in at this point. Node [0] is the root document node so this will always have length of at least 1.

Returns:

The metadata for the select.

Throws:

DataSourceException - If anything goes wrong.

getForEach

public java.lang.Object getForEach(ForEachTag tag,
                                   DataSourceNode[] stack)
                            throws DataSourceException

This method is only called by AutoTag. It is never called by the engine and can just throw an exception for a datasource written for the engine only. Returns the data from a forEach select. This always returns a .NET DataTable or XmlList

Parameters:

tag - The tag to run.

stack - The stack of forEach loops in at this point. Node [0] is the root document node so this will always have length of at least 1.

Returns:

The requested data.

Throws:

DataSourceException - If anything goes wrong.

adjustSelect

public java.lang.String adjustSelect(java.lang.String select,
                                     DataSourceNode[] stack)
                              throws DataSourceException

This method is only called by AutoTag. It is never called by the engine and can just throw an exception for a datasource written for the engine only. This will adjust a select statement to use the "column as alias" construct if there are multiple identical columns in the select.

Parameters:

select - The select to adjust

stack - The stack of forEach loops in at this point. Node [0] is the root document node so this will always have length of at least 1.

Returns:

The adjusted select.

Throws:

DataSourceException - If anything goes wrong.

getQuery

public java.lang.Object getQuery(QueryTag tag,
                                 DataSourceNode[] stack)
                          throws DataSourceException

This method is only called by AutoTag. It is never called by the engine and can just throw an exception for a datasource written for the engine only. Returns the data from a query select. This always returns a .NET DataTable or XmlList

Parameters:

tag - The tag to run.

stack - The stack of forEach loops in at this point. Node [0] is the root document node so this will always have length of at least 1.

Returns:

The requested data.

Throws:

DataSourceException - If anything goes wrong.

getSet

public java.lang.String getSet(SetTag tag,
                               DataSourceNode[] stack)
                        throws DataSourceException

This method is only called by AutoTag. It is never called by the engine and can just throw an exception for a datasource written for the engine only. Returns the data from a set. This always returns a .NET DataTable or XmlList

Parameters:

tag - The tag to run.

stack - The stack of forEach loops in at this point. Node [0] is the root document node so this will always have length of at least 1.

Returns:

The requested data.

Throws:

DataSourceException - If anything goes wrong.

isSelect

public boolean isSelect(java.lang.String select)

addQuery

public void addQuery(QueryTag tag,
                     DataSourceNode[] stack)
              throws DataSourceException

Called for a query tag. Adds this query to the list of queries the document holds. This query will continue to exist after this node is gone.

Parameters:

tag - The values that identify the datasource node to read.

stack - The stack of forEach loops in at this point. Node [0] is the root document node so this will always have length of at least 1.

Throws:

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

addSet

public void addSet(SetTag tag,
                   DataSourceNode[] stack)
            throws DataSourceException

Called for a set tag. Adds this set to the list of name:value pairs in the document map. This set will continue to exist after this node is gone.

Parameters:

tag - The name value pair.

stack - The stack of forEach loops in at this point. Node [0] is the root document node so this will always have length of at least 1.

Throws:

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

getBitmap

public java.io.InputStream getBitmap(OutTag tag,
                                     DataSourceNode[] stack)
                              throws DataSourceException

Called when tag is of type BITMAP. Returns the fileimage of the bitmap from the datasource. Return a 0 length array for an empty bitmap. Return null if the requested node does not exist.

Parameters:

tag - The values that identify the datasource node to read.

stack - The stack of forEach loops in at this point. Node [0] is the root document node so this will always have length of at least 1.

Returns:

A file image of the referenced bitmap.

Throws:

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

getEscape

public java.lang.String getEscape(EscapeTag tag,
                                  DataSourceNode[] stack)
                           throws DataSourceException

Called for an escape tag. Returns the text to insert into the report. This will only be called if the tag's type matches the report type being generated. Return a 0 length string for an empty node. Return null if the requested node does not exist.

Parameters:

tag - The values that identify the datasource node to read.

stack - The stack of forEach loops in at this point. Node [0] is the root document node so this will always have length of at least 1.

Returns:

The text to insert into the report.

Throws:

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

getFunction

public java.lang.String[] getFunction(FunctionTag tag,
                                      DataSourceNode[] stack)
                               throws DataSourceException

Called for a function tag. Returns an array of strings, one for each matching node with the string containing the node contents.

Parameters:

tag - The values that identify the datasource node to read.

stack - The stack of forEach loops in at this point. Node [0] is the root document node so this will always have length of at least 1.

Returns:

The node values. Returns a 0 length array (not null) if no nodes.

Throws:

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

getHtml

public java.lang.String getHtml(HtmlTag tag,
                                DataSourceNode[] stack)
                         throws DataSourceException

Called for an html tag. Returns the html text to be parsed and inserted into the report. Return a 0 length string for an empty node. Return null if the requested node does not exist.

Parameters:

tag - The values that identify the datasource node to read.

stack - The stack of forEach loops in at this point. Node [0] is the root document node so this will always have length of at least 1.

Returns:

The text to insert into the report.

Throws:

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

getImport

public java.lang.String getImport(ImportTag tag,
                                  DataSourceNode[] stack)
                           throws DataSourceException

Called for an import tag. Returns the name of the resource to be parsed and inserted into the report. Windward Reports will process the returned string based on the tag type attribute. Return a 0 length string for an empty node. Return null if the requested node does not exist. Windward Reports uses the type and source attributes on this returned value. This method cannot affect those attributes.

Parameters:

tag - The values that identify the datasource node to read.

stack - The stack of forEach loops in at this point. Node [0] is the root document node so this will always have length of at least 1.

Returns:

The text to insert into the report.

Throws:

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

getLink

public java.lang.String getLink(LinkTag tag,
                                DataSourceNode[] stack)
                         throws DataSourceException

Called for a link tag. Returns the link text that is the url for the link. Return a 0 length string for an empty node. Return null if the requested node does not exist.

Parameters:

tag - The values that identify the datasource node to read.

stack - The stack of forEach loops in at this point. Node [0] is the root document node so this will always have length of at least 1.

Returns:

The url for a link.

Throws:

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

getOut

public java.lang.String getOut(OutTag tag,
                               DataSourceNode[] stack,
                               java.util.Locale locale)
                        throws DataSourceException

Called for an out tag. Returns the text to be inserted into the report. Return a 0 length string for an empty node. Return null if the requested node does not exist and there is no default value.

Parameters:

tag - The values that identify the datasource node to read.

stack - The stack of forEach loops in at this point. Node [0] is the root document node so this will always have length of at least 1.

locale - The locale to produce the output in.

Returns:

The text to insert into the report.

Throws:

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

getOutStream

public java.io.InputStream getOutStream(OutTag tag,
                                        DataSourceNode[] stack)
                                 throws DataSourceException

Called for an out tag. Returns the raw bytes of a node. This is used to read a rtf or xml file from the database. Return a 0 length stream for an empty node. Return null if the requested node does not exist and there is no default value.

Parameters:

tag - The values that identify the datasource node to read.

stack - The stack of forEach loops in at this point. Node [0] is the root document node so this will always have length of at least 1.

Returns:

The text to insert into the report.

Throws:

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

isExistingNode

public boolean isExistingNode(BaseTag tag,
                              DataSourceNode[] stack)
                       throws DataSourceException

Return true if the passed in node exists. This should return true even if the passed in node is empty. This method needs to be fast.

Parameters:

tag - The values that identify the datasource node to read.

stack - The stack of forEach loops in at this point. Node [0] is the root document node so this will always have length of at least 1.

Returns:

True if the node exists, false otherwise.

Throws:

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

evaluate

public boolean evaluate(java.lang.String text,
                        DataSourceNode[] stack)
                 throws DataSourceException

Evaluate an expression for the boolean result.

Parameters:

text - The expression to evaluate.

stack - The stack of forEach loops in at this point. Node [0] is the root document node so this will always have length of at least 1.

Returns:

true or false.

Throws:

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

isIf

public boolean isIf(IfTag tag,
                    DataSourceNode[] stack)
             throws DataSourceException

Called for an if tag. Returns if the node exists. This normally is identical to isExistingNode() but can be different as this determines if an <wr:if ... > tag will return true while isExistingNode is used in numerous other cases.

Parameters:

tag - The values that identify the datasource node to read.

stack - The stack of forEach loops in at this point. Node [0] is the root document node so this will always have length of at least 1.

Returns:

True if the node exists, false otherwise.

Throws:

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

iterator

public DataSourceIterator iterator(ForEachTag tag,
                                   DataSourceNode[] stack)
                            throws DataSourceException

Called for a forEach tag. Returns an iterator used to walk through the nodes that match the forEach tag. It is the responsibility of this iterator to handle begin, step, and end in the tag. If there are no nodes, an iterator that will return false on the first call to hasNext() should be returned.

Parameters:

tag - The values that identify the datasource node to read.

stack - The stack of forEach loops in at this point. Node [0] is the root document node so this will always have length of at least 1.

Returns:

An iterator to walk the nodes that match.

Throws:

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

getIterator

public DataSourceIterator getIterator()
                               throws DataSourceException

Returns the iterator presently in use for this node. This is not the method called when processing a forEach tag. The method called to process a forEach tag is iterator(). This method is called to get the iterator in use for a node..
Windward Reports will never request multiple simultaneous iterators from a DataSourceNode. This restriction is critical for the functionality of this method.
This is not the iterator that returned this in it's iteration. It is the iterator created by this node and is returning nodes 1 level higher in the node stack. For example, stack[0] holds the iterator for the node at stack[1]. And by definition, the node at the top of the stack cannot have an iterator (because if it did, the first node returned by that iterator would then be on the top of the stack).

Returns:

The iterator in use for this node. Will return null if no iterator is in use for this node.

Throws:

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

close

public void close()
           throws DataSourceException

We are done with this node. Used to close any resources opened by this object.

Throws:

DataSourceException - Could not retrieve the data.

getData

public net.windward.chart.ChartDataSet getData(ChartTag tag,
                                               DataSourceNode[] stack,
                                               java.util.Locale locale)
                                        throws DataSourceException

Returns a set of data used to create a chart. The structure of this is tied tightly to the chart package.

Parameters:

tag - The wr:chart tag with the select setting to use.

stack - The stack of forEach loops in at this point. Node [0] is the root document node so this will always have length of at least 1.

locale - The locale to produce the output in.

Returns:

The data used by the charting functions to create the chart.

Throws:

DataSourceException - Could not retrieve the data.