Dom4jDataSource (Windward Reports 16.1 API)

java.lang.Object
- net.windward.datasource.DataSourceBase
- - net.windward.datasource.dom4j.Dom4jDataSource

All Implemented Interfaces:

DataSourceProvider
```
public class Dom4jDataSource
extends DataSourceBase
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

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

class Dom4jDataSource.VarResults

Nested Classes
Modifier and Type	Class and Description
`class`	`Dom4jDataSource.VarResults`

Field Summary
- Fields inherited from interface net.windward.datasource.DataSourceProvider
  NAME_DATASET, NAME_JSON, NAME_LITERAL, NAME_ODATA, NAME_SFDC, NAME_SQL, NAME_XML, NAME_XML_1_0

Constructor Summary

Constructors
Constructor and Description
`Dom4jDataSource(org.w3c.dom.Document document)` Create a DataSourceProvider that uses dom4j to traverse an xml stream.
`Dom4jDataSource(org.dom4j.Document document, boolean extractNamespaces)` 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.io.InputStream xmlData, java.io.InputStream schemaFile)` 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 string as the data and dom4j to traverse it.
`Dom4jDataSource(java.lang.String xmlConnectionString, java.lang.String schemaConnectionString)` Create a DataSourceProvider using the passed in connection strings.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`approveDenyModifySelect(BaseTag xmlTag)` Verifys that a tag select is approved by a user defined callback Or denies by throwing a DatasourceException or modifies the select
`void`	`close()` Called when processing is complete.
`static org.dom4j.io.SAXReader`	`createSAXReader()` Create a SAXReader set to disallow XXE aattacks.
`java.lang.String`	`getDatasourceName()` returns the name of this type in the form "sql", "xml", etc.
`java.lang.String`	`getDefaultNamespacePrefix()` The prefixes for namespaces are pulled from the XML datasource.
`java.util.Map<java.lang.String,java.lang.Object>`	`getParameters()` This call is for internal engine use only.
`int`	`getParamMode()` Get the parameter substitution mode.
`int`	`getQueryMode(java.lang.String query, BaseTag tag)` Returns the query mode for this select.
`DataSourceNode`	`getRootNode()` Returns the root node for this data set.
`TagAttributes[]`	`getTagAttributes()` Returns the allowed attributes for all tags.
`java.util.Date`	`parseAsDate(java.lang.String str)`
`void`	`populateDatasourceException(DataSourceException exception, BaseTag tag, DataSourceNode[] stack)` Populates that properties in a DataSourceException via DataSourceException.setProperties().
`void`	`setDefaultNamespacePrefix(java.lang.String prefix)` The prefixes for namespaces are pulled from the XML datasource.
`void`	`SetNamespaces(XPathNamespace[] namespaces)`
`void`	`setParameters(java.util.Map<java.lang.String,java.lang.Object> parameters)` This call is for internal engine use only.
`void`	`setParamMode(int paramMode)` Set the parameter substitution mode.
`boolean`	`supportsDataSets()` Does this datasource support data sets?
`void`	`validateTag(BaseTag xmlTag)` Verifys that a tag has all required attributes and no unknown attributes.

Methods inherited from class net.windward.datasource.DataSourceBase
convertToInputStream, lookupVariable

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - Dom4jDataSource
```
public Dom4jDataSource(java.lang.String xmlConnectionString,
                       java.lang.String schemaConnectionString)
                throws DataConnectionException
```
    Create a DataSourceProvider using the passed in connection strings. The schema connection string can be null.
    
    Parameters:
    
    xmlConnectionString - Connection string to read the XML file.
    
    schemaConnectionString - Connection string to read the schema. null if no schema.
    
    Throws:
    
    DataConnectionException
  - Dom4jDataSource
```
public Dom4jDataSource(java.io.InputStream xmlData,
                       java.io.InputStream schemaFile)
                throws DataConnectionException
```
    Create a DataSourceProvider that uses an xml stream as the data and dom4j to traverse it.
    
    Parameters:
    
    xmlData - A well formed xml data file.
    
    schemaFile - the schema file.
    
    Throws:
    
    DataConnectionException - thrown if anything goes wrong.
  - Dom4jDataSource
```
public Dom4jDataSource(java.io.InputStream xmlData)
                throws DataConnectionException
```
    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:
    
    DataConnectionException - thrown if anything goes wrong.
  - Dom4jDataSource
```
public Dom4jDataSource(java.lang.String xmlData)
                throws DataConnectionException
```
    Create a DataSourceProvider that uses an xml string as the data and dom4j to traverse it.
    
    Parameters:
    
    xmlData - Well formed xml (not a filename to an XML file - this is XML in a string).
    
    Throws:
    
    DataConnectionException - thrown if anything goes wrong.
  - Dom4jDataSource
```
public Dom4jDataSource(org.dom4j.Element node)
                throws DataConnectionException
```
    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.
    
    Throws:
    
    DataConnectionException
  - Dom4jDataSource
```
public Dom4jDataSource(org.dom4j.Document document,
                       boolean extractNamespaces)
                throws DataConnectionException
```
    Create a DataSourceProvider that uses dom4j to traverse an xml stream. The input is a dom4j Document.
    Be aware that this does a shallow copy so do not change the passed in object until the datasource is closed.
    
    Parameters:
    
    document - a dom4j document.
    
    extractNamespaces - true if namespaces need to be read from the document and set as namespaces. Set to false if this has already been done. You must do this yourself if the document has a schema.
    
    Throws:
    
    DataConnectionException
  - Dom4jDataSource
```
public Dom4jDataSource(org.w3c.dom.Document document)
                throws DataConnectionException
```
    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.
    
    Throws:
    
    DataConnectionException
- Method Detail
  - getDatasourceName
```
public java.lang.String getDatasourceName()
```
    returns the name of this type in the form "sql", "xml", etc.
    
    Specified by:
    
    getDatasourceName in interface DataSourceProvider
    
    Returns:
    
    "xml"
  - 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.
  - approveDenyModifySelect
```
public void approveDenyModifySelect(BaseTag xmlTag)
                             throws DataSourceException
```
    Verifys that a tag select is approved by a user defined callback Or denies by throwing a DatasourceException or modifies the select
    
    Specified by:
    
    approveDenyModifySelect in interface DataSourceProvider
    
    Parameters:
    
    xmlTag - The tag to check
    
    Throws:
    
    DataSourceException - thrown if illegal parameters passed in.
  - populateDatasourceException
```
public void populateDatasourceException(DataSourceException exception,
                                        BaseTag tag,
                                        DataSourceNode[] stack)
```
    Populates that properties in a DataSourceException via DataSourceException.setProperties().
    
    Specified by:
    
    populateDatasourceException in interface DataSourceProvider
    
    Parameters:
    
    exception - The exception to populate.
    
    tag - The tag we're processing. null if no tag.
    
    stack - The node stack at the time of the exception. null if not relevant.
  - SetNamespaces
```
public void SetNamespaces(XPathNamespace[] namespaces)
```
  - getParamMode
```
public int getParamMode()
```
    Get the parameter substitution mode. Uses one of the PARAM_MODE_* constants.
    
    Specified by:
    
    getParamMode in interface DataSourceProvider
    
    Returns:
    
    the parameter substitution mode.
  - setParamMode
```
public void setParamMode(int paramMode)
```
    Set the parameter substitution mode. Uses one of the PARAM_MODE_* constants.
    
    Specified by:
    
    setParamMode in interface DataSourceProvider
    
    Parameters:
    
    paramMode - the parameter substitution mode.
  - setParameters
```
public void setParameters(java.util.Map<java.lang.String,java.lang.Object> parameters)
```
    This call is for internal engine use only. Do not call this!
    
    Specified by:
    
    setParameters in interface DataSourceProvider
    
    Parameters:
    
    parameters - This object is directly assigned for use as it is shared. Therefore any changes to it after this call effect the datasource.
  - getParameters
```
public java.util.Map<java.lang.String,java.lang.Object> getParameters()
```
    This call is for internal engine use only. Do not call this!
    
    Specified by:
    
    getParameters in interface DataSourceProvider
  - setDefaultNamespacePrefix
```
public void setDefaultNamespacePrefix(java.lang.String prefix)
```
    The prefixes for namespaces are pulled from the XML datasource. The default namespace, if one exists, needs to be set. The default is def (ie /def:root/def:elem ).
    
    Parameters:
    
    prefix - The prefix used for the default namespace in xpath selects.
  - getDefaultNamespacePrefix
```
public java.lang.String getDefaultNamespacePrefix()
```
    The prefixes for namespaces are pulled from the XML datasource. The default namespace, if one exists, needs to be set. The default is def (ie /def:root/def:elem ).
    
    Returns:
    
    The prefix used for the default namespace in xpath selects.
  - 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
  - parseAsDate
```
public java.util.Date parseAsDate(java.lang.String str)
```
  - getQueryMode
```
public int getQueryMode(java.lang.String query,
                        BaseTag tag)
```
    Returns the query mode for this select. Looks at the first character for the force mode chars.
    
    Specified by:
    
    getQueryMode in interface DataSourceProvider
    
    Parameters:
    
    query - The select to evaluate.
    
    tag - The tag this select is for. This may be null.
    
    Returns:
    
    One of the BaseTage.MODE_* ints.
  - supportsDataSets
```
public boolean supportsDataSets()
```
    Does this datasource support data sets?
    
    Specified by:
    
    supportsDataSets in class DataSourceBase
    
    Returns:
    
    true if supported false if not
  - createSAXReader
```
public static org.dom4j.io.SAXReader createSAXReader()
                                              throws org.xml.sax.SAXException
```
    Create a SAXReader set to disallow XXE aattacks.
    
    Returns:
    
    a safe SAXReader.
    
    Throws:
    
    org.xml.sax.SAXException

Class Dom4jDataSource

Nested Class Summary

Field Summary

Fields inherited from interface net.windward.datasource.DataSourceProvider

Constructor Summary

Method Summary

Methods inherited from class net.windward.datasource.DataSourceBase

Methods inherited from class java.lang.Object

Constructor Detail

Dom4jDataSource

Dom4jDataSource

Dom4jDataSource

Dom4jDataSource

Dom4jDataSource

Dom4jDataSource

Dom4jDataSource

Method Detail

getDatasourceName

getTagAttributes

validateTag

approveDenyModifySelect

populateDatasourceException

SetNamespaces

getParamMode

setParamMode

setParameters

getParameters

setDefaultNamespacePrefix

getDefaultNamespacePrefix

getRootNode

close

parseAsDate

getQueryMode

supportsDataSets

createSAXReader