net.sf.jasperreports.engine.data

Class JRXmlDataSource

java.lang.Object

net.sf.jasperreports.engine.data.JRAbstractTextDataSource

net.sf.jasperreports.engine.data.AbstractXmlDataSource<JRXmlDataSource>

net.sf.jasperreports.engine.data.JRXmlDataSource

All Implemented Interfaces:

JRDataSource, JRRewindableDataSource

public class JRXmlDataSource
extends AbstractXmlDataSource<JRXmlDataSource>

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 expression that will be used to select its value. This expression must be specified using the AbstractXmlDataSource.PROPERTY_FIELD_EXPRESSION custom property at field level. The use of the field description to specify the XPath expression is still supported, but is now discouraged, the above mentioned custom property taking precedence over the field description. 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.

Author:

Peter Severin ([email protected], [email protected])

See Also:

JRXPathExecuterUtils

Field Summary

Fields inherited from class net.sf.jasperreports.engine.data.AbstractXmlDataSource

PROPERTY_FIELD_EXPRESSION

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

EXCEPTION_MESSAGE_KEY_CANNOT_CONVERT_FIELD_TYPE, EXCEPTION_MESSAGE_KEY_CANNOT_MODIFY_PROPERTIES_AFTER_START, EXCEPTION_MESSAGE_KEY_NODE_NOT_AVAILABLE, EXCEPTION_MESSAGE_KEY_NULL_DOCUMENT, EXCEPTION_MESSAGE_KEY_NULL_SELECT_EXPRESSION, EXCEPTION_MESSAGE_KEY_UNKNOWN_COLUMN_NAME, EXCEPTION_MESSAGE_KEY_UNKNOWN_NUMBER_TYPE

Constructor Summary

Constructors

Constructor and Description
JRXmlDataSource(Document document)
JRXmlDataSource(Document document, String selectExpression)
JRXmlDataSource(File file)
JRXmlDataSource(File file, boolean isNamespaceAware)
JRXmlDataSource(File file, String selectExpression)
JRXmlDataSource(File file, String selectExpression, boolean isNamespaceAware)
JRXmlDataSource(InputStream in)
JRXmlDataSource(InputStream in, boolean isNamespaceAware)
JRXmlDataSource(InputStream in, String selectExpression)
JRXmlDataSource(InputStream in, String selectExpression, boolean isNamespaceAware)
JRXmlDataSource(JasperReportsContext jasperReportsContext, Document document) Creates the data source by parsing the xml document from the given file.
JRXmlDataSource(JasperReportsContext jasperReportsContext, Document document, String selectExpression) Creates the data source by parsing the xml document from the given file.
JRXmlDataSource(JasperReportsContext jasperReportsContext, File file) Creates the data source by parsing the xml document from the given file.
JRXmlDataSource(JasperReportsContext jasperReportsContext, File file, boolean isNamespaceAware)
JRXmlDataSource(JasperReportsContext jasperReportsContext, File file, String selectExpression) Creates the data source by parsing the xml document from the given file.
JRXmlDataSource(JasperReportsContext jasperReportsContext, File file, String selectExpression, boolean isNamespaceAware)
JRXmlDataSource(JasperReportsContext jasperReportsContext, InputStream in) Creates the data source by parsing the xml document from the given input stream.
JRXmlDataSource(JasperReportsContext jasperReportsContext, InputStream in, boolean isNamespaceAware)
JRXmlDataSource(JasperReportsContext jasperReportsContext, InputStream in, String selectExpression) Creates the data source by parsing the xml document from the given input stream.
JRXmlDataSource(JasperReportsContext jasperReportsContext, InputStream in, String selectExpression, boolean isNamespaceAware)
JRXmlDataSource(JasperReportsContext jasperReportsContext, String uri) Creates the data source by parsing the xml document from the given system identifier (URI).
JRXmlDataSource(JasperReportsContext jasperReportsContext, String uri, boolean isNamespaceAware)
JRXmlDataSource(JasperReportsContext jasperReportsContext, String uri, String selectExpression) Creates the data source by parsing the xml document from the given system identifier (URI).
JRXmlDataSource(JasperReportsContext jasperReportsContext, String uri, String selectExpression, boolean isNamespaceAware)
JRXmlDataSource(RepositoryContext context, String uri, String selectExpression, boolean isNamespaceAware)
JRXmlDataSource(String uri)
JRXmlDataSource(String uri, boolean isNamespaceAware)
JRXmlDataSource(String uri, String selectExpression)
JRXmlDataSource(String uri, String selectExpression, boolean isNamespaceAware)

Method Summary

Modifier and Type	Method and Description
void	close() Closes the reader.
JRXmlDataSource	dataSource() Creates a sub data source using as root document the document used by "this" data source.
JRXmlDataSource	dataSource(String selectExpr) Creates a sub data source using as root document the document used by "this" data source.
Node	getCurrentNode()
Object	getSelectObject(Node currentNode, String expression)
void	moveFirst() Moves back to the first element in the data source.
boolean	next() Tries to position the cursor on the next element in the data source.
JRXmlDataSource	subDataSource() Creates a sub data source using the current node (record) as the root of the document.
JRXmlDataSource	subDataSource(String selectExpr) Creates a sub data source using the current node (record) as the root of the document.
Document	subDocument() Creates a document using the current node as root.

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

getFieldExpression, getFieldValue, getText

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

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

Methods inherited from class java.lang.Object

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

Constructor Detail

JRXmlDataSource

public JRXmlDataSource(JasperReportsContext jasperReportsContext,
                       Document document)
                throws JRException

Creates the data source by parsing the xml document from the given file. The data source will contain exactly one record consisting of the document node itself.

Parameters:

document - the document

Throws:

JRException - if the data source cannot be created

JRXmlDataSource

public JRXmlDataSource(Document document)
                throws JRException

Throws:

JRException

See Also:

JRXmlDataSource(JasperReportsContext, Document)

JRXmlDataSource

public JRXmlDataSource(JasperReportsContext jasperReportsContext,
                       Document document,
                       String selectExpression)
                throws JRException

Creates the data source by parsing the xml document from the given file. An additional XPath expression specifies the select criteria that produces the nodes (records) for the data source.

Parameters:

document - the document

selectExpression - the XPath select expression

Throws:

JRException - if the data source cannot be created

JRXmlDataSource

public JRXmlDataSource(Document document,
                       String selectExpression)
                throws JRException

Throws:

JRException

See Also:

JRXmlDataSource(JasperReportsContext, Document, String)

JRXmlDataSource

public JRXmlDataSource(JasperReportsContext jasperReportsContext,
                       InputStream in)
                throws JRException

Creates the data source by parsing the xml document from the given input stream.

Parameters:

in - the input stream

Throws:

JRException

See Also:

JRXmlDataSource(Document)

JRXmlDataSource

public JRXmlDataSource(JasperReportsContext jasperReportsContext,
                       InputStream in,
                       boolean isNamespaceAware)
                throws JRException

Throws:

JRException

JRXmlDataSource

public JRXmlDataSource(InputStream in)
                throws JRException

Throws:

JRException

See Also:

JRXmlDataSource(JasperReportsContext, InputStream)

JRXmlDataSource

public JRXmlDataSource(InputStream in,
                       boolean isNamespaceAware)
                throws JRException

Throws:

JRException

JRXmlDataSource

public JRXmlDataSource(JasperReportsContext jasperReportsContext,
                       InputStream in,
                       String selectExpression)
                throws JRException

Creates the data source by parsing the xml document from the given input stream.

Throws:

JRException

See Also:

JRXmlDataSource(InputStream), JRXmlDataSource(Document, String)

JRXmlDataSource

public JRXmlDataSource(JasperReportsContext jasperReportsContext,
                       InputStream in,
                       String selectExpression,
                       boolean isNamespaceAware)
                throws JRException

Throws:

JRException

JRXmlDataSource

public JRXmlDataSource(InputStream in,
                       String selectExpression)
                throws JRException

Throws:

JRException

See Also:

JRXmlDataSource(JasperReportsContext, InputStream, String)

JRXmlDataSource

public JRXmlDataSource(InputStream in,
                       String selectExpression,
                       boolean isNamespaceAware)
                throws JRException

Throws:

JRException

JRXmlDataSource

public JRXmlDataSource(JasperReportsContext jasperReportsContext,
                       String uri)
                throws JRException

Creates the data source by parsing the xml document from the given system identifier (URI).

If the system identifier is a URL, it must be full resolved.

Parameters:

uri - the system identifier

Throws:

JRException

See Also:

JRXmlDataSource(Document)

JRXmlDataSource

public JRXmlDataSource(JasperReportsContext jasperReportsContext,
                       String uri,
                       boolean isNamespaceAware)
                throws JRException

Throws:

JRException

JRXmlDataSource

public JRXmlDataSource(String uri)
                throws JRException

Throws:

JRException

See Also:

JRXmlDataSource(JasperReportsContext, String)

JRXmlDataSource

public JRXmlDataSource(String uri,
                       boolean isNamespaceAware)
                throws JRException

Throws:

JRException

JRXmlDataSource

public JRXmlDataSource(JasperReportsContext jasperReportsContext,
                       String uri,
                       String selectExpression)
                throws JRException

Creates the data source by parsing the xml document from the given system identifier (URI).

Throws:

JRException

See Also:

JRXmlDataSource(String), JRXmlDataSource(Document, String)

JRXmlDataSource

public JRXmlDataSource(JasperReportsContext jasperReportsContext,
                       String uri,
                       String selectExpression,
                       boolean isNamespaceAware)
                throws JRException

Throws:

JRException

JRXmlDataSource

public JRXmlDataSource(RepositoryContext context,
                       String uri,
                       String selectExpression,
                       boolean isNamespaceAware)
                throws JRException

Throws:

JRException

JRXmlDataSource

public JRXmlDataSource(String uri,
                       String selectExpression)
                throws JRException

Throws:

JRException

See Also:

JRXmlDataSource(JasperReportsContext, String, String)

JRXmlDataSource

public JRXmlDataSource(String uri,
                       String selectExpression,
                       boolean isNamespaceAware)
                throws JRException

Throws:

JRException

JRXmlDataSource

public JRXmlDataSource(JasperReportsContext jasperReportsContext,
                       File file)
                throws JRException

Creates the data source by parsing the xml document from the given file.

Parameters:

file - the file

Throws:

JRException

See Also:

JRXmlDataSource(Document)

JRXmlDataSource

public JRXmlDataSource(JasperReportsContext jasperReportsContext,
                       File file,
                       boolean isNamespaceAware)
                throws JRException

Throws:

JRException

JRXmlDataSource

public JRXmlDataSource(File file)
                throws JRException

Throws:

JRException

See Also:

JRXmlDataSource(JasperReportsContext, File)

JRXmlDataSource

public JRXmlDataSource(File file,
                       boolean isNamespaceAware)
                throws JRException

Throws:

JRException

JRXmlDataSource

public JRXmlDataSource(JasperReportsContext jasperReportsContext,
                       File file,
                       String selectExpression)
                throws JRException

Creates the data source by parsing the xml document from the given file.

Throws:

JRException

See Also:

JRXmlDataSource(File), JRXmlDataSource(Document, String)

JRXmlDataSource

public JRXmlDataSource(JasperReportsContext jasperReportsContext,
                       File file,
                       String selectExpression,
                       boolean isNamespaceAware)
                throws JRException

Throws:

JRException

JRXmlDataSource

public JRXmlDataSource(File file,
                       String selectExpression)
                throws JRException

Throws:

JRException

See Also:

JRXmlDataSource(JasperReportsContext, File, String)

JRXmlDataSource

public JRXmlDataSource(File file,
                       String selectExpression,
                       boolean isNamespaceAware)
                throws JRException

Throws:

JRException

Method Detail

moveFirst

public void moveFirst()
               throws JRException

Description copied from interface: JRRewindableDataSource

Moves back to the first element in the data source.

Throws:

JRException

next

public boolean next()

Description copied from interface: JRDataSource

Tries to position the cursor on the next element in the data source.

Returns:

true if there is a next record, false otherwise

getCurrentNode

public Node getCurrentNode()

Specified by:

getCurrentNode in class AbstractXmlDataSource<JRXmlDataSource>

getSelectObject

public Object getSelectObject(Node currentNode,
                              String expression)
                       throws JRException

Specified by:

getSelectObject in class AbstractXmlDataSource<JRXmlDataSource>

Throws:

JRException

subDataSource

public JRXmlDataSource subDataSource(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.

Specified by:

subDataSource in class AbstractXmlDataSource<JRXmlDataSource>

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(Document, String)

subDataSource

public JRXmlDataSource subDataSource()
                              throws JRException

Description copied from class: AbstractXmlDataSource

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.

Overrides:

subDataSource in class AbstractXmlDataSource<JRXmlDataSource>

Returns:

the xml sub data source

Throws:

JRException - if the data source cannot be created

See Also:

subDataSource(String), JRXmlDataSource(Document)

subDocument

public Document subDocument()
                     throws JRException

Creates a document using the current node as root.

Specified by:

subDocument in class AbstractXmlDataSource<JRXmlDataSource>

Returns:

a document having the current node as root

Throws:

JRException

dataSource

public JRXmlDataSource dataSource(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.

Specified by:

dataSource in class AbstractXmlDataSource<JRXmlDataSource>

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(Document, String)

dataSource

public JRXmlDataSource dataSource()
                           throws JRException

Description copied from class: AbstractXmlDataSource

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.

Overrides:

dataSource in class AbstractXmlDataSource<JRXmlDataSource>

Returns:

the xml sub data source

Throws:

JRException - if the data source cannot be created

See Also:

dataSource(String), JRXmlDataSource(Document)

close

public void close()

Closes the reader. Users of this data source should close it after usage.