net.windward.datasource

Interface DataSourceNode

All Known Implementing Classes:

AbstractDataSourceNode, JdbcDataSource.JdbcNode, JsonDataSource.JsonDataNode

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

Modifier and Type	Method and Description
boolean	addQuery(QueryTag tag, DataSourceNode[] stack) Called for a query tag.
void	addSet(SetTag tag, DataSourceNode[] stack, java.util.Locale locale, IMacroState macroState) Called for a set tag.
boolean	addSwitch(SwitchTag tag, DataSourceNode[] stack) Called for a switch tag.
void	close() We are done with this node.
void	endSwitch(EndSwitchTag tag, DataSourceNode[] stack) Called when a switch ends.
boolean	evaluate(java.lang.String text, DataSourceNode[] stack, IMacroState macroState) Evaluate an expression for the boolean result.
java.io.InputStream	getBitmap(OutTag tag, DataSourceNode[] stack, IMacroState state) Called when tag is of type BITMAP.
java.lang.Object	getCursor() Returns the underlying cursor this node presently holds.
IChartDataSet	getData(ChartTag tag, DataSourceNode[] stack, java.util.Locale locale) Returns a set of data used to create a chart.
DataSourceProvider	getDataSourceProvider() Get the parent datasource.
DebugDatasourceState	getDatasourceState(DataSourceNode[] stack) Get the state of the datasource.
java.lang.Object[]	getEquationData(java.lang.String query, DataSourceNode[] stack, java.util.Locale locale) Returns an array of data from a given datasource query
java.lang.String	getImport(ImportTag tag, DataSourceNode[] stack) Deprecated.
java.lang.String	getImport(ImportTag tag, DataSourceNode[] stack, java.util.Locale locale, IMacroState macroState) An extended version of getImport() which supports the macro evaluation.
DataSourceIterator	getIterator() Returns the iterator presently in use for this node.
java.lang.String	getLink(BaseTag tag, DataSourceNode[] stack) Called for a link or DrillDown tag.
java.lang.Object	getNativeVariable(DataSourceNode[] stack, java.lang.String var) Gets the variable from a data provider on the stack.
java.lang.Object	getOut(OutTag tag, DataSourceNode[] stack, java.util.Locale locale, IMacroState state) Called for an out tag.
InputDataContainer	getOutStream(OutTag tag, DataSourceNode[] stack, IMacroState state) Called for an out tag.
int	getQueryMode(java.lang.String select, BaseTag tag) Returns the mode of a query.
java.lang.Object[]	getVariableValue(java.lang.String variable, DataSourceNode[] stack, java.util.Locale locale) Returns the variable value.
boolean	isCase(CaseTag tag, DataSourceNode[] stack, IMacroState macroState) Called for a case tag.
boolean	isExistingNode(BaseTag tag, DataSourceNode[] stack) Return true if the passed in node exists.
boolean	isIf(IfTag tag, DataSourceNode[] stack, IMacroState macroState) Called for an if tag.
boolean	isLiteralDataSourceNode() This is needed in parts of the code that do not know about the .NET version of the LiteralDataSourceNode, for example if we are in cross compiled java code and we need to know if a DataSourceNode is an instance of WindwardReportDrivers.net.windward.datasource.LiteralDatasource.LiteralDataSourceNode.
boolean	isSelect(java.lang.String select, boolean textIsNode) Returns true if the passed in string is believed to be a select.
DataSourceIterator	iterator(ForEachTag tag, DataSourceNode[] stack) Called for a forEach tag.
void	setIterator(DataSourceIterator it)

Method Detail

getNativeVariable

java.lang.Object getNativeVariable(DataSourceNode[] stack,
                                   java.lang.String var)

Gets the variable from a data provider on the stack. The stack is queried in order from top to bottom and if the provider in turn owns the variable its value is returnd. The base implementation simply returns null. Override it in the derived provider.

Parameters:

stack - The current stack of data providers.

var - A variable to look up. It's in the form of ${...}.

Returns:

The variable's value or null if the variable does not exist.

isSelect

boolean isSelect(java.lang.String select,
                 boolean textIsNode)

Returns true if the passed in string is believed to be a select. false otherwise.

Parameters:

select - Determine if this string is a select.

textIsNode - true if plain text is a nod. false if it's a value.

Returns:

true if believed to be a select. false otherwise.

addQuery

boolean 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.

Returns:

true if returned 1 or more rows of data. false if no data.

Throws:

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

addSet

void addSet(SetTag tag,
            DataSourceNode[] stack,
            java.util.Locale locale,
            IMacroState macroState)
     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

macroState - the macro state of the report have length of at least 1.

Throws:

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

getBitmap

java.io.InputStream getBitmap(OutTag tag,
                              DataSourceNode[] stack,
                              IMacroState state)
                       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.

state - macrostate of the report

Returns:

A file image of the referenced bitmap.

Throws:

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

getImport

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

Deprecated.

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.

getImport

java.lang.String getImport(ImportTag tag,
                           DataSourceNode[] stack,
                           java.util.Locale locale,
                           IMacroState macroState)
                    throws DataSourceException

An extended version of getImport() which supports the macro evaluation.

Throws:

DataSourceException

getLink

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

Called for a link or DrillDown 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

java.lang.Object getOut(OutTag tag,
                        DataSourceNode[] stack,
                        java.util.Locale locale,
                        IMacroState state)
                 throws DataSourceException

Called for an out tag. Returns the object 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. This can be a String, Number, or Date.

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.

state - The macro state of the report

Returns:

The object to insert into the report.

Throws:

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

getOutStream

InputDataContainer getOutStream(OutTag tag,
                                DataSourceNode[] stack,
                                IMacroState state)
                         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.

state - macrostate of the report

Returns:

The text to insert into the report.

Throws:

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

isExistingNode

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

boolean evaluate(java.lang.String text,
                 DataSourceNode[] stack,
                 IMacroState macroState)
          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.

macroState - macrostate of the report

Returns:

true or false.

Throws:

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

isIf

boolean isIf(IfTag tag,
             DataSourceNode[] stack,
             IMacroState macroState)
      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.

macroState - macrostate of the report

Returns:

True if the node exists, false otherwise.

Throws:

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

addSwitch

boolean addSwitch(SwitchTag tag,
                  DataSourceNode[] stack)
           throws DataSourceException

Called for a switch tag. Adds this switch to the list of switch the document holds. This switch will continue until the endSwitch is called.

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 no select. For a select, true if returned 1 or more rows of data. false if no data.

Throws:

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

isCase

boolean isCase(CaseTag tag,
               DataSourceNode[] stack,
               IMacroState macroState)
        throws DataSourceException

Called for a case tag. Returns if the case is true. This normally is identical to isExistingNode() but can be different as this determines if an <wr:case ... > 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.

macroState - macro state of the report

Returns:

True if the case is true, false otherwise.

Throws:

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

endSwitch

void endSwitch(EndSwitchTag tag,
               DataSourceNode[] stack)
        throws DataSourceException

Called when a switch ends. Will pop the innermost switch off the internal stack.

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.

iterator

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.

setIterator

void setIterator(DataSourceIterator it)

getIterator

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

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

IChartDataSet 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.

getCursor

java.lang.Object getCursor()
                    throws DataSourceException

Returns the underlying cursor this node presently holds. This is implementation specific.

Returns:

the underlying cursor this node presently holds.

Throws:

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

getVariableValue

java.lang.Object[] getVariableValue(java.lang.String variable,
                                    DataSourceNode[] stack,
                                    java.util.Locale locale)
                             throws DataSourceException

Returns the variable value.

Parameters:

variable - The string containing the variable name.

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 desired variable value.

Throws:

DataSourceException

getEquationData

java.lang.Object[] getEquationData(java.lang.String query,
                                   DataSourceNode[] stack,
                                   java.util.Locale locale)
                            throws DataSourceException

Returns an array of data from a given datasource query

Parameters:

query - The datasource query.

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 desired array of data

Throws:

DataSourceException

getQueryMode

int getQueryMode(java.lang.String select,
                 BaseTag tag)
          throws DataSourceException

Returns the mode of a query. It is one of the BaseTag.MODE_* values. This tells the underlying provider if the passed in select is a select=, evaluate=, or value=.

Parameters:

select - The query.

tag - The tag this select is for. This may be null.

Returns:

The mode.

Throws:

DataSourceException

getDatasourceState

DebugDatasourceState getDatasourceState(DataSourceNode[] stack)

Get the state of the datasource. Used by the debugger.

Parameters:

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 datasource state.

getDataSourceProvider

DataSourceProvider getDataSourceProvider()

Get the parent datasource.

Returns:

The datasource.

isLiteralDataSourceNode

boolean isLiteralDataSourceNode()

This is needed in parts of the code that do not know about the .NET version of the LiteralDataSourceNode, for example if we are in cross compiled java code and we need to know if a DataSourceNode is an instance of WindwardReportDrivers.net.windward.datasource.LiteralDatasource.LiteralDataSourceNode. This is necessary in the charting code as the series data select resulted in a LiteralDataSourceNode instead of a node of the original type. In this case we need to know it is a LiteralDataSourceNode, so that we can run row data selects against a query higher up the stack.

Returns:

true if this is an instane of a literal datasource node