net.sf.jasperreports.engine.data
Class AbstractXmlDataSource

java.lang.Object
  net.sf.jasperreports.engine.data.JRAbstractTextDataSource
      net.sf.jasperreports.engine.data.AbstractXmlDataSource

All Implemented Interfaces:

JRDataSource, JRRewindableDataSource

Direct Known Subclasses:

JaxenXmlDataSource, XalanXmlDataSource

public abstract class AbstractXmlDataSource
extends JRAbstractTextDataSource
implements JRRewindableDataSource

Abstract XML data source implementation that allows to access the data from a xml document using XPath expressions.

The data source is constructed around a node set (record set) selected by an XPath expression from the xml document.

Each field can provide an additional XPath expresion that will be used to select its value. This expression must be specified using the "fieldDescription" element of the field. The expression is evaluated in the context of the current node thus the expression should be relative to the current node.

To support subreports, sub data sources can be created. There are two different methods for creating sub data sources. The first one allows to create a sub data source rooted at the current node. The current node can be seen as a new document around which the sub data source is created. The second method allows to create a sub data source that is rooted at the same document that is used by the data source but uses a different XPath select expression.

Example:

 <A>
        <B id="0">
                <C>
                <C>
        </B>
        <B id="1">
                <C>
                <C>
        </B>
        <D id="3">
                <E>
                <E>
        </D>
 </A>
 

Data source creation

• new JRXmlDataSource(document, "/A/B") - creates a data source with two nodes of type /A/B
• new JRXmlDataSource(document, "/A/D") - creates a data source with two nodes of type /A/D

Field selection

• @id - will select the "id" attribute from the current node
• C - will select the value of the first node of type C under the current node.

Sub data source creation

• "((net.sf.jasperreports.engine.data.JRXmlDataSource)$P{REPORT_DATA_SOURCE}).subDataSource("/B/C") - in the context of the node B, creates a data source with elements of type /B/C
• "((net.sf.jasperreports.engine.data.JRXmlDataSource)$P{REPORT_DATA_SOURCE}).dataSource("/A/D") - creates a data source with elements of type /A/D

Generally the full power of XPath expression is available. As an example, "/A/B[@id > 0"] will select all the nodes of type /A/B having the id greater than 0. You'll find a short XPath tutorial here.

Note on performance. Due to the fact that all the XPath expression are interpreted the data source performance is not great. For the cases where more speed is required, consider implementing a custom data source that directly accesses the Document through the DOM API.

Version:

$Id: AbstractXmlDataSource.java 5180 2012-03-29 13:23:12Z teodord $

Author:

Narcis Marcu (narcism@users.sourceforge.net)

Constructor Summary

AbstractXmlDataSource()

Method Summary

AbstractXmlDataSource	dataSource() Creates a sub data source using as root document the document used by "this" data source.
abstract AbstractXmlDataSource	dataSource(java.lang.String selectExpr) Creates a sub data source using as root document the document used by "this" data source.
abstract org.w3c.dom.Node	getCurrentNode()
java.lang.Object	getFieldValue(JRField jrField) Gets the field value for the current position.
abstract java.lang.Object	getSelectObject(org.w3c.dom.Node currentNode, java.lang.String expression)
java.lang.String	getText(org.w3c.dom.Node node) Return the text that a node contains.
AbstractXmlDataSource	subDataSource() Creates a sub data source using the current node (record) as the root of the document.
abstract AbstractXmlDataSource	subDataSource(java.lang.String selectExpr) Creates a sub data source using the current node (record) as the root of the document.
abstract org.w3c.dom.Document	subDocument() Creates a document using the current node as root.

Methods inherited from class net.sf.jasperreports.engine.data.JRAbstractTextDataSource

convertNumber, convertStringValue, getConvertBean, getDatePattern, getFormattedDate, getFormattedNumber, getLocale, getNumberPattern, getTimeZone, setDatePattern, setLocale, setLocale, setNumberPattern, setTextAttributes, setTimeZone, setTimeZone

Methods inherited from class java.lang.Object

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

Methods inherited from interface net.sf.jasperreports.engine.JRRewindableDataSource

moveFirst

Methods inherited from interface net.sf.jasperreports.engine.JRDataSource

next

Constructor Detail

AbstractXmlDataSource

public AbstractXmlDataSource()

Method Detail

getCurrentNode

public abstract org.w3c.dom.Node getCurrentNode()

getSelectObject

public abstract java.lang.Object getSelectObject(org.w3c.dom.Node currentNode,
                                                 java.lang.String expression)
                                          throws JRException

Throws:

JRException

getFieldValue

public java.lang.Object getFieldValue(JRField jrField)
                               throws JRException

Description copied from interface: JRDataSource

Gets the field value for the current position.

Specified by:

getFieldValue in interface JRDataSource

Returns:

an object containing the field value. The object type must be the field object type.

Throws:

JRException

subDataSource

public abstract AbstractXmlDataSource subDataSource(java.lang.String selectExpr)
                                             throws JRException

Creates a sub data source using the current node (record) as the root of the document. An additional XPath expression specifies the select criteria applied to this new document and that produces the nodes (records) for the data source.

Parameters:

selectExpr - the XPath select expression

Returns:

the xml sub data source

Throws:

JRException - if the sub data source couldn't be created

See Also:

JRXmlDataSource.JRXmlDataSource(Document, String)

subDataSource

public AbstractXmlDataSource subDataSource()
                                    throws JRException

Creates a sub data source using the current node (record) as the root of the document. The data source will contain exactly one record consisting of the document node itself.

Returns:

the xml sub data source

Throws:

JRException - if the data source cannot be created

See Also:

JRXmlDataSource.subDataSource(String), JRXmlDataSource.JRXmlDataSource(Document)

subDocument

public abstract org.w3c.dom.Document subDocument()
                                          throws JRException

Creates a document using the current node as root.

Returns:

a document having the current node as root

Throws:

JRException

dataSource

public abstract AbstractXmlDataSource dataSource(java.lang.String selectExpr)
                                          throws JRException

Creates a sub data source using as root document the document used by "this" data source. An additional XPath expression specifies the select criteria applied to this document and that produces the nodes (records) for the data source.

Parameters:

selectExpr - the XPath select expression

Returns:

the xml sub data source

Throws:

JRException - if the sub data source couldn't be created

See Also:

JRXmlDataSource.JRXmlDataSource(Document, String)

dataSource

public AbstractXmlDataSource dataSource()
                                 throws JRException

Creates a sub data source using as root document the document used by "this" data source. The data source will contain exactly one record consisting of the document node itself.

Returns:

the xml sub data source

Throws:

JRException - if the data source cannot be created

See Also:

JRXmlDataSource.dataSource(String), JRXmlDataSource.JRXmlDataSource(Document)

getText

public java.lang.String getText(org.w3c.dom.Node node)

Return the text that a node contains. This routine:

• Ignores comments and processing instructions.
• Concatenates TEXT nodes, CDATA nodes, and the results of recursively processing EntityRef nodes.
• Ignores any element nodes in the sublist. (Other possible options are to recurse into element sublists or throw an exception.)

Parameters:

node - a DOM node

Returns:

a String representing node contents or null