XML Datasources in Jaspersoft Studio

Overview

An XML data source uses an XML file to provide the data printed to reports. The XML structure is not flat like a table. There are not rows and columns. It's more like a tree where we can have several levels of data. All data starts from a root node that can have any number of children or branches.

A child can be a value or it can be another node with children. For this reason it is necessary to use an XPath query to identify which nodes of the XML document must be considered as records.

The following XML is simple enough to easily explain how to do it:

<addressbook>
    <person>
        <name>ETHAN</name>
        <phone>+1 (415) 111-1111</phone>
    </person>
    <person>
        <name>CALEB</name>
        <phone>+1 (415) 222-2222</phone>
    </person>
    <person>
        <name>WILLIAM</name>
        <phone>+1 (415) 333-3333</phone>
    </person>
</addressbook>

Each record that we want to print can be identified with the XML node labeled "person". The selection of these specific XML tags is done with an XPath query like this:

/addressbook/person

XPath is a powerful query language to select data in an XML file. In this case, the expression selects all the nodes of type "person" that are children of "addressbook".

The result from the data source is a set of three records (since the occurrences of the tag person, child of addressbook, are three). The goal is to write a report in Jaspersoft Studio with a list of all the persons in the address book, showing each person's name and phone number.

Create the Example XML

To use the above XML from this tutorial, open your favorite text editor and create a new file. Then copy and paste it into this file:

Save the file with the name "ContactList.xml". You can also download this file from contactname.xml.

Creation of the Report

Now open Jaspersoft Studio AND begin creating a new report by selecting File > New > Jasper Report.

Select the "Silhouette" template. As file name use "ContactXMLReport".

When asked to choose the data adapter, click New, and, in the window that appears, select XML document and click Next.

In the next window, insert the name of the new data adapter, XMLAdapter, then click the Browse button.

Select the file ContactList.xml, then select the option: Use the report Xpath expression when filling the report to use an expression directlly inside the report.

The difference between these two options is that the first uses an expression defined in the report, so every report can use its own expression to retrive the data. The second one defines an expression in the data adapter, so every report that uses the data adapter will also use its expression.

When configuring an XML data source it is possible to specify in which mode the data source must operate or to use, and a Date and Number pattern that can be used to convert a text value in a more appropriate object (like a date or a number).

Since we don't need this option simply click Finish.

Back in the Report Creation wizard, the data adapter you just created should be selected.

Insert the XPath query, like we did with the SQL query in other tutorials. In this case, JasperReports executes the XPath query to select the nodes from the XML document provided using the XML data source.

Any data adapter can provide an editor to interact with the data source (the XML in this case). For example, for a JBDC data adapter we insert the SQL query, and from this adapter Jaspersoft Studio locates the necessary fields.

With the XML, you can provide an XPath query, like /addressbook/person, but you can also compose it using a visual editor that shows the tree structure of the the XML. By double clicking on a node the XPath query will be automatically generated.

The advantage of keeping the XPath query inside the report is that we can use parameters to make the query dynamic.

Note that the query "/addressbook/person" returns all the people under the tag "addressbook", and the fields that are the child nodes of those people, such as name and phone.

Click Next and notice where the fields "name" and "phone" are located. Add these to the report by clicking >> and then click Next.

We don't need groups, so on the next step click Next, then click Finish.

The report is created, and if you switch to Preview mode you should see this result:

The Background Band

The background band is a little different from other bands. It can have a maximum height equal to the page height and the elements appear behind the other bands.

For example, if you put an element at the top of the background band, it is placed at the start of the page (keeping the margins in consideration) and is under any other elements in the same position.

This band was introduced to provide an easy way to include watermarks or similar effects.

Differences with iReport

Jaspersoft Studio allows a friendlier way to define fields. In iReport, when you select the dataset you can't use an XPath query to locate fields; you first need to create the report, go in to the query designer, and only then you can write the XPath query and eventually add fields. At the end of the wizard, Jaspersoft Studio places the located fields inside the report. Because of this, Jaspersoft Studio is faster - at end of the wizard you can have a report already configured, with the fields placed and ready to be compiled, whereas with iReport you need to take additional steps before you can compile.

Using a Remote XML

Jaspersoft Studio provides a data adapter for the remote XML, like the RSS Feed. This means that it is possible to generate a report using not only a local XML but a remote XML provided from some external service. For this example, we will use the RSS Feed of the BBC News.

Begin creating a new report by selecting File> New > Jasper Report, and select the Tree template. Use the file name "BBCReport". When asked for a data adapter, click New.In the subsequent window, select the option XML document (remote) and click Next. Call the new data adapter "BBCAdapter" and use the following values:

• XML URL: http://feeds.bbci.co.uk/news/rss.xml?edition=int#
• Date pattern: EEE, dd MMM yyyy HH:mm:ss z

Then click Finish.

You have now created a data adapter for an XML on the web identified by an URL. Now you have the ability to insert an XPath query as seen with the local XML.

The RSS of the BBC contains all the the news into the tag item, inside the tag Channel. Expanding the Channel tag and double-clicking on Item generates the following XPath query: /rss/channel/item.

Next, click Finish to retrieve the fields.

Remember that double-clicking on an element Item dosen't select that precise element, but all the elements with the tag "Item" located on the same level as the selected element.

From the field list double-click to select the title, description and pubDate, then click Next. Again, we don't need groups so click Next and then Finish.

Now you have a report with the fields already placed, but because the description will contain more text, and is not in a good position.

Enlarge the band Detail and move the description under the title, then enlarge the field description to fill the band. You should end up with something like this:

Switch to the Preview tab to compile the report and you should see a result like this:

So we have filled the report with a remote XML, in this case an RSS Feed.

The Parameters

If you open the Dataset & Query dialog (select the report from the Outline view, then from the Properties tab and click the button Edit query, filter and sort options) you can see that, as query language, you are using XPath2.

The XPath2 query executer is able to download the XML file from a remote url that we set when we defined the data source, but the url can also be specified using the parameters.

Optionally, GET and POST parameters can be specified as parameters for the report from the Parameters tab inside the Dataset & Query dialog. When the report is executed inside an application, the URL can be set dynamically with a parameter XML_URL.

Other parameters that can be set include: XML_USERNAME and XML_PASSWORD for http authentication and XML_DATE_PATTERN and XML_NUMBER_PATTERN to set the pattern that converts dates and numbers from text.

POST and GET parameters can be specified creating parameters with the prefix XML_POST_ and XML_GET_. For example, to pass a GET parameter of name id, the parameter must be called XML_GET_id.

This approach is very flexible and can be used to get data from a web application like a PHP script that can create the XML data based on a set on input parameters passed from the report.

contactname.xml