Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## net.sf.jasperreports.engine.data
Class JRXmlDataSource

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

All Implemented Interfaces:
  JRDataSource, JRRewindableDataSource

    public class JRXmlDataSource

extends JRAbstractTextDataSource
implements JRRewindableDataSource

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: JRXmlDataSource.java 3690 2010-04-06 12:23:17Z shertage $
Author:
  Peter Severin (peter_p_s@sourceforge.net, contact@jasperassistant.com)
See Also:
  `JRXPathExecuterUtils`

Constructor Summary
`JRXmlDataSource(org.w3c.dom.Document document)` Creates the data source by parsing the xml document from the given file.
`JRXmlDataSource(org.w3c.dom.Document document, java.lang.String selectExpression)` Creates the data source by parsing the xml document from the given file.
`JRXmlDataSource(java.io.File file)` Creates the data source by parsing the xml document from the given file.
`JRXmlDataSource(java.io.File file, java.lang.String selectExpression)` Creates the data source by parsing the xml document from the given file.
`JRXmlDataSource(java.io.InputStream in)` Creates the data source by parsing the xml document from the given input stream.
`JRXmlDataSource(java.io.InputStream in, java.lang.String selectExpression)` Creates the data source by parsing the xml document from the given input stream.
`JRXmlDataSource(java.lang.String uri)` Creates the data source by parsing the xml document from the given system identifier (URI).
`JRXmlDataSource(java.lang.String uri, java.lang.String selectExpression)` Creates the data source by parsing the xml document from the given system identifier (URI).

Method Summary
`JRXmlDataSource` | `dataSource()` Creates a sub data source using as root document the document used by "this" data source.
`JRXmlDataSource` | `dataSource(java.lang.String selectExpr)` Creates a sub data source using as root document the document used by "this" data source.
`java.lang.Object` | `getFieldValue(JRField jrField)` Gets the field value for the current position.
`java.lang.String` | `getText(org.w3c.dom.Node node)` Return the text that a node contains.
`static void` | `main(java.lang.String[] args)`
`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(java.lang.String selectExpr)` Creates a sub data source using the current node (record) as the root of the document.
`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, getLocale, getNumberPattern, getTimeZone, setDatePattern, setLocale, setNumberPattern, setTextAttributes, setTimeZone`

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

Constructor Detail

### JRXmlDataSource

    public JRXmlDataSource(org.w3c.dom.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(org.w3c.dom.Document document,
                           java.lang.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(java.io.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(java.io.InputStream in,
                           java.lang.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(java.lang.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(java.lang.String uri,
                           java.lang.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(java.io.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(java.io.File file,
                           java.lang.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)`

Method Detail

### moveFirst

    public void moveFirst()
                   throws JRException

  Description copied from interface: `JRRewindableDataSource`
  Moves back to the first element in the data source.

  Specified by:
    `moveFirst` in interface `JRRewindableDataSource`
  Throws:
    `JRException`

### next

    public boolean next()

  Description copied from interface: `JRDataSource`
  Tries to position the cursor on the next element in the data source.

  Specified by:
    `next` in interface `JRDataSource`
  Returns:
    true if there is a next record, false otherwise

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

### subDataSource

    public JRXmlDataSource 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:
    `subDataSource(String)`, `JRXmlDataSource(Document)`

### subDocument

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

### dataSource

    public JRXmlDataSource 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:
    `dataSource(String)`, `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

### main

    public static void main(java.lang.String[] args)
                     throws java.lang.Exception

  Throws:
    `java.lang.Exception`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

© 2001-2010 Jaspersoft Corporation www.jaspersoft.com