.:Documentation and tutorials |
Home
Screenshots
Docs
Download
Project page
Credits
Donations
Vote for iReport on O'Reilly's OSDir.com
<< Previous | Next >> | Table of Contents 7 Using the XML datasource Starting from version 0.3.2, iReport provides an XML datasource that permit to fill a report reading data from an XML file. 7.1 Configuring an XML datasource The first step to use an XML file as a datasource is configure an XML Datasource. Select menu Datasource > Connections / Datasources, press New and select "XML file datasource" as connection type.
Fig.7.1: The XML datasource configuration panel.
Fill the name field with the name of this datasource (i.e. Adressbook), select the XML file and set the record path. 7.2 The Record Path An XML document is structured as a tree. JasperReports need data organized as a record set, so we must present a tree as set of record. The Record Path is a string that define the minimum path required to define a record. Example 1:
    <palette>
        <color>Red</color>
        <color>Green</color>
        <color>Blue</color>
    </palette>
It this very simple case, the Record Path is the path from the root (tag palette) to the leaf (tag color): /palette/color We use the same record path for this document (Example 2):
    <palette>
        <color>
        	<name>Red</name>
        	<red>255<red>
        	<green>0<green>
        	<blue>0<blue>
        </color>
        <color>
        	<name>Green</name>
        	<red>0<red>
        	<green>255<green>
        	<blue>0<blue>
        </color>
        <color>
        	<name>Blue</name>
        	<red>255<red>
        	<green>0<green>
        	<blue>0<blue>
        </color>
    </palette>
Please note that in this case the path don't ends with a leaf tag. In general, the end tag is the first tag that has children of different type or is a leaf. When the document become more complex, we can read prodoce a sub-datasource starting from a child. In example 3 we can see that any color can have 0 or more aliases...
    <palette>
        <color>
        	<name>Red</name>
    	<alias type="html">#FF0000</alias>
    	<alias type="rgb">255, 0, 0</alias>
    	<alias type="CMYK">0, 99, 100, 0</alias>
        </color>
        <color>
        	<name>Green</name>
    	<alias type="html">#0000FF</alias>
    	<alias type="rgb">0, 0, 255</alias>
    	<alias type="lab">88, -79, 81</alias>
    	<alias type="CMYK">63, 0, 100, 0</alias>
        </color>
        <color>
        	<name>Blue</name>
    	<alias type="html">#0000FF</alias>
    	<alias type="rgb">0, 0, 255</alias>
        </color>
    </palette>
In this case we can think to tags alias as a set of records childs of master record /palette/color, the childs record will have as record path the value /color/alias:
    <color>
        <alias type="html">#FF0000</alias>
        <alias type="rgb">255, 0, 0</alias>
        <alias type="CMYK">0, 99, 100, 0</alias>
    </color>
Note as this XML is very similar to example 1. 7.3 XML Datasource Syntax To bind fields inside the XML, a syntax similar to XPath is used. The field path is stored in the field description (this because the field name don't support a name like "/palette/color"). The path syntax is really simple. Is a recursive expression: <base_path>[<symbol> <base_path>[<symbol><...>] ]
<base_path> | is the path from the root to the tag. If this path is longer than the Record Path, it's cuted to the Record Path. It is required for a field definition. If it's alone, the value of the tag is returned. Example: /palette/color
<symbol> | is used to add an extra path to the base path and to define what should be returned. + add the following path to the base_path (this happen when the base_path = record path); @ return the attribute value: it's followed by the attribute name; * return all tags identified by the following path as a JRXMLDatasource Examples: /palette/color+name /color/alias@type /palette/color*alias /addressbook/catogory/person+other_info+extra_time/hobbies*hobby /addressbook@creation_date
7.4 Addressbook sample This sample shows how to use the JRXMLDatasource using subreports. The sample is composed by 4 files: addressbook.xml is the data file addressbook.jrxml is the master report file hobby.jrxml is the hobby subreport eamil.jrxml is the email subreport addressbook.xml
    <addressbook>
       <category name="home">
          <person id="1">
              <LASTNAME>Davolio</LASTNAME>
              <FIRSTNAME>Nancy</FIRSTNAME>
              <hobbies>
              	<hobby>Radio Control</hobby>
              	<hobby>R/C Cars</hobby>
              	<hobby>Micro R/C Cars</hobby>
              	<hobby>Die-Cast Models</hobby>
              </hobbies>
              <email>email1@my.domain.it</email>
              <email>email2@my.domain2.it</email>

          </person>
          <person id="2">
              <LASTNAME>Fuller</LASTNAME>
              <FIRSTNAME>Andrew</FIRSTNAME>
              <email>email3@my.domain3.it</email>
              <email>email4@my.domain4.it</email>
          </person>
          <person id="3">
              <LASTNAME>Leverling</LASTNAME>
              <FIRSTNAME>Janet</FIRSTNAME>
              <hobbies>
              	<hobby>Rockets</hobby>
              	<hobby>Puzzles</hobby>
              	<hobby>Science Hobby</hobby>
              	<hobby>Toy Horse</hobby>
              </hobbies>
              <email>email45@my.domain3.it</email>
              <email>email455@my.domain4.it</email>
          </person>
      </category>
      <category name="work">
          <person id="4">
              <LASTNAME>Peacock</LASTNAME>
              <FIRSTNAME>Margaret</FIRSTNAME>
              <hobbies>
              	<hobby>Toy Horse</hobby>
              </hobbies>
              <email>Peacock@margaret.com</email>
          </person>
          <person id="5">
              <LASTNAME>Buchanan</LASTNAME>
              <FIRSTNAME>Steven</FIRSTNAME>
              <hobbies>
              </hobbies>
              <email>Buchanan@steven.com</email>
          </person>
          <person id="6">
              <LASTNAME>Suyama</LASTNAME>
              <FIRSTNAME>Michael</FIRSTNAME>
          </person>
          <person id="7">
              <LASTNAME>King</LASTNAME>
              <FIRSTNAME>Robert</FIRSTNAME>
          </person>
      </category>
      <category name="Other">
          <person id="8">
              <LASTNAME>Callahan</LASTNAME>
              <FIRSTNAME>Laura</FIRSTNAME>
              <email>email25@my.domain3.it</email>
          </person>
          <person id="9">
              <LASTNAME>Dodsworth</LASTNAME>
              <email>Dodsworth@my.anne.it</email>
          </person>
      </category>
    </addressbook>
We have defined a datasource named Addressbook that use addressbook.xml as data file. The Record path is: /addressbook/category/person Fields in the report are defined as follow:
Field Name | Field Description | Type
CATEGORY | /addressbook/category@name | java.lang.String
PERSON_ID | /addressbook/category/person@id | java.lang.String
LASTNAME | /addressbook/category/person+LASTNAME | java.lang.String
FIRSTNAME | /addressbook/category/person+FIRSTNAME | java.lang.String
HOBBIES | /addressbook/category/person+hobbies*hobby | java.lang.Object (castable to JRDataSource)
EMAIL_ADDRESSES | /addressbook/category/person*email | java.lang.Object (castable to JRDataSource)
To the master report (figure 7.2) we have added a group named CATEGORY that has as expression the category name.
Fig.7.2: The master report.
We have two subreport too, one for hobbies of a person and one for email addresses. The first subreport element has $F{HOBBIES} as connection expression (of type datasource expression) and as subreport expression "/hobby.jasper" of type String. The second subreport element has $F{EMAIL_ADDRESSES} as connection expression (of type datasource expression) and as subreport expression "/email.jasper" of type String. In hobby.jasper we have defined only one field:
Field Name | Field Description | Type
HOBBY | /hobbies/hobby | java.lang.String
The same in email.jasper:
Field Name | Field Description | Type
EMAIL | /person/email | java.lang.String
Note as every field in subreport are defined specifing as root element in the path the parent element: HOBBY -> /hobbies/hobby EMAIL -> /person/email This is the result:
Fig.7.2: The final result.
Finally we show how to use the JRXMLDataDource in a program:
| XMLDataSourceExample.java |
    1   package it.businesslogic.ireport.examples;
    2
    3   import it.businesslogic.ireport.connection.JRXMLDataSource;
    4   import dori.jasper.engine.export.JRPdfExporter;
    5
    6   import dori.jasper.engine.*;
    7   import java.util.HashMap;
    8
    9
    10  public class XMLDataSourceExample {
    11
    12      public static void main(String[] args) throws Exception {
    13
    14                  String reportFileName = "/addressbook.jasper";
    15                  String outFileName = "/addressbook.pdf";
    16                  String xmlFileName = "/addressbook.xml";
    17                  String recordPath = "/addressbook/category/person";
    18
    19                  JRXMLDataSource jrxmlds = new JRXMLDataSource(xmlFileName,recordPath);
    20
    21          HashMap hm = new HashMap();
    22
    23          try
    24          {
    25              JasperPrint print = JasperFillManager.fillReport(
    26                          reportFileName,
    27                          hm,
    28                          jrxmlds);
    29
    30              JRExporter exporter = new dori.jasper.engine.export.JRPdfExporter();
    31
    32              exporter.setParameter(JRExporterParameter.OUTPUT_FILE_NAME,outFileName);
    33                      exporter.setParameter(JRExporterParameter.JASPER_PRINT,print);
    34
    35                      exporter.exportReport();
    36                      System.out.println("Created file: " + outFileName);
    37          }
    38          catch (JRException e)
    39          {
    40              e.printStackTrace();
    41              System.exit(1);
    42          }
    43          catch (Exception e)
    44          {
    45              e.printStackTrace();
    46              System.exit(1);
    47          }
    48
    49      }
    50
    51  }
7.5 XML Datasource license JRXMLDatasource is not released under GPL license (as iReport is) but under LGPL as jasperreports: in this way you can use the JRXMLDataSource in your program without problems. However, if you use it, please make a simbolic donation to the iReport project.
(c) 2002 by Giulio Toffoli <gt78 at businesslogic.it>