<html>
<head>
<title>iReport</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<LINK REL=STYLESHEET TYPE="text/css" HREF="manual0.2.0/stylesheet.css" TITLE="Style">
<style>
FONT.fsmall { font: normal 9pt Arial; }
FONT.fmedio { font: normal 10pt Arial; }
FONT.ftitparagrafo { font: bold 13pt Arial; }
FONT.fparagrafo { font: bold 11pt Arial; }
FONT.smaaaaal { font: bold 8pt Arial; }
FONT.ftitle { font: normal 20pt Arial; }
A.fmedio { COLOR: #000000; TEXT-DECORATION: underline; font: normal 10pt Arial; }
A.fmedio:hover { COLOR: #AA0000; TEXT-DECORATION: underline; font: normal 10pt Arial; }

A.fmed2 { COLOR: #000000; TEXT-DECORATION: underline; font: normal 12pt Arial; }
A.fmed2:hover { COLOR: #AA0000; TEXT-DECORATION: underline; font: normal 12pt Arial; }

A.fmedim { COLOR: #000000; TEXT-DECORATION: none; font: normal 10pt Arial; }
A.fmedim:hover { COLOR: #AA0000; TEXT-DECORATION: underline; font: normal 10pt Arial; }
</style>
</head>

<body bgcolor="#FFFFFF" text="#000000" topmargin="0" leftmargin="0" marginwidth="0" marginheight="0">
<table width="100%" height="100%" border="0" cellspacing="0" cellpadding="0">
  <tr height="99"><td><table height="99" width="100%" border="0" cellspacing="0" cellpadding="0"><tr height="99">
    <td width="200" height="99" valign="top"><img src="images/logo_igor.gif" ></td>
    <td valign="top" width="99%" height="99"><table  width="100%" border="0" cellspacing="0" cellpadding="0">
	<tr> 
	  <td   height="49" bgcolor="#D4D0C8" valign="bottom" align="left"><font class="ftitle"><b>.:Documentation and tutorials</b></font></td>
	  <td   height="49" bgcolor="#D4D0C8" valign="middle" align="right"><A href="http://sourceforge.net"><img border=0 src="images/sflogo.gif" width="105" height="31"></a><img src="images/null.gif"49" width="10" border=0 height="1"></td>
	</tr>
	<tr> 
	  <td height="1" colspan="2" bgcolor="#000000"><img src="images/null.gif height="1" width="1"></td>
	</tr>
      </table></td>
		</tr></table></td>
  </tr> 
  <tr><td><table width="100%" height="100%" border="0" cellspacing="0" cellpadding="0"><tr><td width="120" valign="top" bgcolor="#C98890"><img src="images/null.gif" width="120" height="10">
  <table cellspacing=2 cellpadding=0 width="100%">
	<tr><td bgcolor="#EFA7B0"><font class="fmedio">&nbsp;<A HREF="index.php" class="fmedim">Home</a></font></td></tr>
	<tr><td bgcolor="#EFA7B0"><font class="fmedio">&nbsp;<A HREF="screenshots.html" class="fmedim">Screenshots</a></font></td></tr>
	<tr><td bgcolor="#EFA7B0"><font class="fmedio">&nbsp;<A HREF="docs.html" class="fmedim">Docs</a></font></td></tr>
	<tr><td bgcolor="#EFA7B0"><font class="fmedio">&nbsp;<A HREF="http://sourceforge.net/project/showfiles.php?group_id=64348" class="fmedim">Download</a></font></td></tr>
	<tr><td bgcolor="#EFA7B0"><font class="fmedio">&nbsp;<A HREF="http://sourceforge.net/projects/ireport" class="fmedim">Project page</a></font></td></tr>
	<tr><td bgcolor="#EFA7B0"><font class="fmedio">&nbsp;<A HREF="credits.html" class="fmedim">Credits</a></font></td></tr>
	<tr><td bgcolor="#EFA7B0"><font class="fmedio">&nbsp;<A HREF="http://ireport.sourceforge.net/donations.html" class="fmedim">Donations</a></font></td></tr>
  </table>
  <form method="post"
    action="http://www.osdir.com/
    modules.php?op=modload&amp;name=Downloads&amp;file=index">
<table border="0" cellspacing="0" cellpadding="0">
  <tr>
    <td align="center">
      <font class=fsmall>Vote for iReport on O'Reilly's OSDir.com</font>
    </td>
  </tr>
  <tr>
    <td><center>
      <table border="0" cellspacing="0" cellpadding="0">
        <tr>
          <td valign="top" align="center" nowrap>
            <select name="rating">
              <option selected>--</option><br>
              <option value="10">10</option><br>
              <option value="9">9</option><br>
              <option value="8">8</option><br>
              <option value="7">7</option><br>
              <option value="6">6</option><br>
              <option value="5">5</option><br>
              <option value="4">4</option><br>
              <option value="3">3</option><br>
              <option value="2">2</option><br>
              <option value="1">1</option><br>
            </select>
            <input type="submit" value="Vote!"><input type="hidden" name="ratinglid" value="396"><input type="hidden" name="req" value="addrating"><input type="hidden" name="ratinguser" value="outside">
          </td>
        </tr>
      </table>
    </td>
  </tr>
</table>
</form>
  </td>
    <td width="1" height="1" bgcolor="#6F6F6F"><img src="images/null.gif height="1" width="1"></td>
    <td valign="top"><table cellspacing=2 cellpadding=0 width="100%"><tr><td>
		<br>
		  <table align="center" width="95%" border="0" cellspacing="0" cellpadding="0">
		  <tr valign="top"><td>
			<a href="cap3.html"  class="fmedim">&lt;&lt; Previous</a> &nbsp;&nbsp;|&nbsp;&nbsp; <a href="cap5.html"  class="fmedim">Next &gt;&gt;</a> &nbsp;&nbsp;|&nbsp;&nbsp; <a href="manual0.2.0.html"  class="fmedim">Table of Contents</a>
			<hr height=1 width=100%>
		      
		      <font class="ftitparagrafo"><a name="4.0"></a><b>4 Connections and Datasources</b></font><br><br>
		      <font class="fsmall">Data to print can be retrived in several ways from different places like a database or a XML file. This data is presented to JasperReports always in form of records using a special interface called JRDataSource.
		      JasperReports comes with a good set of implementations of this interface to wrap JDBC ResultSets, TableModels, Collections, Vectors and Arrays of objects, etc...
		      But not always a JRDataSource is needed to supply data to the report in order to fill it. In fact JasperReports can execute yourself sql queries using a given opened Connection to a database,
		      and use the result to fill the report. How we'll see, this features will be very useful and easy to use.    
		      
		      </font><br><br>
		      </font>
		      <font class="fparagrafo"><a name="4.1"></a><b>4.1 Types of datasource</b></font><br><br>
		      <font class="fsmall">iReport supports JDBC connections and 4 types of datasource (that can be used to wrap any kind of custom datasource).<br>
		      <ul>
		      	<li><b>Empty data source (JREmptyDatasource)</b>: is a special datasource used to fill report that don't expose any records. This datasource is used when you press the button <img src="manual0.2.0/2_2.jpg" border=0 align="middle"> to "run" a report.</li> 
		      	<li><b>XML DataSource</b> (not yet implemented): is a datasource capable to wrap an XML file and normalize its content.
		      	<table align="left" border=0><tr><td><a href="manual0.2.0/4_1big.jpg"><img border=1 src="manual0.2.0/4_1.jpg"></a></td></tr><tr><td><font class="fsmall"><b>Fig.4.1: XML datasource definition.</b></font></td></tr></table>
		      	The only informations needed to create this type of datasource are a name (for the datasource) and the name of the XML file. 
		      	<br><br><br><br><br><br><br><br>
		      	</li>
		      	<li><b>JavaBeans Set Datasource</b> (not yet implemented): is a datasource capable to wrap a Collection or an Array of JavaBeans.  
		      	<table align="left" border=0><tr><td><a href="manual0.2.0/4_2big.jpg"><img border=1 src="manual0.2.0/4_2.jpg"></a></td></tr><tr><td><font class="fsmall"><b>Fig.4.2: JavaBeans Set datasource definition.</b></font></td></tr></table>
		      	How all the rest of datasources used by iReport and presented here, this datasource need a spacial factory class that provides a static method to generate a collection or an array of JavaBeans (alias a set of Objects).<br>
		      	To create this datasource you need a name for the datasource, the name of a class that will provide the static method to call to retrive the Array/Collection of Objects and the name of this method  that will
		      	have a definition like this:<br><br>
		      		<code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;public static Collection createMyCollection()</code><br>
		      		or <br><code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;public static Object[] createMyArray()</code><br>
		      		<br>
		      	Remember to set the type of result (Collection or Array). 	
		      	<br><br></li>
		      	<li><b>Custom Datasource</b>: this type of datasource is generic. iReport don't know how the JRDataSource is implemented by this particular connection but it's not important.
		      	<table align="left" border=0><tr><td><a href="manual0.2.0/4_3big.jpg"><img border=1 src="manual0.2.0/4_3.jpg"></a></td></tr><tr><td><font class="fsmall"><b>Fig.4.3: Custom JRDatasource definition.</b></font></td></tr></table>
		      	This datasource need a spacial factory class that provides a static method that return a JRDataSource.<br>
		      	To create this datasource you need a name for the datasource, the name of a class that will provide the static method to call to retrive the JRDataSource and the name of this method  that will
		      	have a definition like this:<br><br>
		      		<code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;public static JRDataSource createMyJRDataSource()</code><br>
		      	<br><br></li>
		      	</ul>
		      	An example of implementation of a custom datasource is provided at the end of this chapter.
		      	<br><br><br><br>
		      </font>
		      <font class="fparagrafo"><a name="4.2"></a><b>4.2 Setting up a JDBC connection</b></font><br><br>
		      <font class="fsmall">
		      To set up a JDBC connection we need a running JDBC capable DBMS (I like MySQL), an appropriate JDBC driver to access it, a database and a valid account. Are you ready? Let's go!<br>
		      Select the menu <font color="#AA0000"><b>Datasources &gt; Connection/Datasources</b></font>. Will appeare the frame with the list of datasources and JDBC connections that you have defined. Please note that you can define how many datasources and connecgtions you want but you can, for now, use only one at time. We'll see
		      how set the "Active connection". Press the "New" button.
		      <table align="left" border=0><tr><td><a href="manual0.2.0/4_4big.jpg"><img border=1 src="manual0.2.0/4_4.jpg"></a></td></tr><tr><td><font class="fsmall"><b>Fig.4.4: JDBC connection definition frame.</b></font></td></tr></table>In the new frame, write a connection name (i.e. "My First JDBC connection"), select the right JDBC driver, you can specify one writing it directly or use one already present in the list. Please note that this drivers are not shipped with iReport (except MySQL driver),
		      be sure that the driver that you want use is in the classpath. Putting a jar in the lib directory of iReport can be a good idea, but the jars present in this directory are added to the CLASSPATH only when iReport start (from version 0.3.1 iReport supports dynamic classpath, this means that you can put new jars in lib without restart iReport). For now it's not possible change the classpath of iReport 2 dinamically.<br>
		      
		      Before write the URL, write the database name, then press the button "Wizard". In this way, if iReport recognize the driver, it will suggest a URL to use with.<br>
		      Set the username and the password, then test the connection pressing the Test button.
		      <table align="left" border=0><tr><td><img border=1 src="manual0.2.0/4_5.jpg"></td></tr><tr><td><font class="fsmall"><b>Fig.4.5: The connection is OK.</b></font></td></tr></table>If all it's OK, a dialog box (Fig. 4.5) will inform you of the test success.<br>Many software use a very similar way to setting up a JDBC connection. You can refer to the specific JDBC driver documentation to know all
		      options offered by the driver and the exact syntax of the URL.<br>All most used DBMS have a JDBC driver. If you need to access a database via ODBC on a Win32 system, you can use the JDBC-ODBC brigde, a special JDBC driver developed by Sun Inc.. But I suggest to verify first the presence of a JDBC driver.<br><br>
		      iReport for default don't store connection passwords. If you want store it, you must first check the "Save password" checkbox.
		      Press the "Save" button to definitly store the connection in the iReport connections pool.		       
		      <br><br>
		       </font><br>
		      </font>
		      <font class="fparagrafo"><a name="4.3"></a><b>4.3 Setting up a custom datasource</b></font><br><br>
		      <font class="fsmall">
		      I will not bore to you with other basic slight notions on which button you must press in order to execute what is written on it...<br>If you have not, read the previous paragraph that explains where put hands to create a new datasource/connection. You only should to kwnow that you can choose the type of your datasource selecting it by the combobox in the connection frame.<br>When you have filled all fields, test it with the test button.
		     <br><br><br>
		      In this session we have created a simple report, saved as XML file, compiled as jasper file, filled with an "EmptyDataSource" end exported in PDF.
		      </font><br><br>
		      </font>
		      
		      <font class="fparagrafo"><a name="4.4"></a><b>4.4 Implementing a new custom datasource</b></font><br><br>
		      <font class="fsmall">
		      This topic is more a JasperReports releated argument, than an iReport feature explanation. But I think that can be useful know how you can develope your custom data driver (alias JRDataSource).<br>
		      We will write a very simple JRDataSource that retrive fields from a CSV file. A CSV file is a text file that contains a set row. Any row contains a cartain number of fields separated by a special character (i.e. teh semicolon ';').<br>
		      What must do our datasource is retrive this rows and return the right value to JasperReport when it ask for a fields (or column).
		      What we have to do is implement this very simple interface:<br><br>
		      <table border=0 cellpadding=2 bgcolor="#EEDDDD" width="100%"><tr><td><code>
		      package dori.jasper.engine;<br><br>
		      public interface JRDataSource<br>
		      {<br>
		      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;public boolean <b>next</b>() throws JRException;<br>
		      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;public Object &nbsp;<b>getFieldValue</b>(JRField jrField) throws JRException;<br>
		      }<br>
		      </code></tr></td></table><br>
		      A <code>JRField</code> is a vary simple class to. It contains the name of the field (a String), and the java Class that represents the type of this field. In our case all fields are of type String, but we can choose to use as field name (alias the column name) the values of the first row of our
		      cvs file or a generic name as COLUMN_1, COLUMN_2, ... This is the same way used by JasperReport in implementation of the TableModel wrapper datasource, that can indifferently use as column name the value of the column
		      header (if present) or the special name <code>COLUMN_&lt;n&gt;</code> with <code>n</code> in the set {0,1,2,3,...,k}. <br>
		      We'll use fixed names to refer columns in our datasource (COLUMN_1, COLUMN_2, ...).<br>
		      This is the code:<br><br>
		      <TABLE id="Header" border="0" cellpadding="0" cellspacing="0" width="100%" bgcolor="#EEDDDD">
<tr>
<td colspan="2" width="33%">&nbsp;</td>
<td align="center" colspan="2" width="33%">
<font size="4">JRCSVDataSource.java</font>
</td>
<td align="right" colspan="2" width="33%">&nbsp;</td>
</tr>
</TABLE>
<pre ID="Classes">
<FONT ID="LN">1   </FONT><A NAME="1"></A>
<FONT ID="LN">2   </FONT><A NAME="2"></A>
<FONT ID="LN">3   </FONT><A NAME="3"></A><FONT ID="Import">import</FONT> java.io.*;
<FONT ID="LN">4   </FONT><A NAME="4"></A><FONT ID="Import">import</FONT> java.util.*;
<FONT ID="LN">5   </FONT><A NAME="5"></A>
<FONT ID="LN">6   </FONT><A NAME="6"></A><FONT ID="Public">public</FONT> <FONT ID="Class">class</FONT> JRCSVDataSource <FONT ID="Implements">implements</FONT> dori.jasper.engine.JRDataSource {
<FONT ID="LN">7   </FONT><A NAME="7"></A>    
<FONT ID="LN">8   </FONT><A NAME="8"></A>    String row = <FONT ID="StringLiteral">""</FONT>;
<FONT ID="LN">9   </FONT><A NAME="9"></A>    LineNumberReader lineNumberReader;
<FONT ID="LN">10  </FONT><A NAME="10"></A>    
<FONT ID="LN">11  </FONT><A NAME="11"></A>    <FONT ID="FormalComment">/** Creates a new instance of JRCVSDataSource */</FONT>
<FONT ID="LN">12  </FONT><A NAME="12"></A>    <FONT ID="Public">public</FONT> JRCSVDataSource(String cvsFile) {
<FONT ID="LN">13  </FONT><A NAME="13"></A>        <FONT ID="Try">try</FONT> {
<FONT ID="LN">14  </FONT><A NAME="14"></A>            lineNumberReader = <FONT ID="New">new</FONT> LineNumberReader( <FONT ID="New">new</FONT> FileReader(cvsFile));
<FONT ID="LN">15  </FONT><A NAME="15"></A>        } <FONT ID="Catch">catch</FONT> (Exception ex) { }
<FONT ID="LN">16  </FONT><A NAME="16"></A>    }
<FONT ID="LN">17  </FONT><A NAME="17"></A>    
<FONT ID="LN">18  </FONT><A NAME="18"></A>    <FONT ID="Public">public</FONT> Object getFieldValue(dori.jasper.engine.JRField jRField) <FONT ID="Throws">throws</FONT> dori.jasper.engine.JRException {
<FONT ID="LN">19  </FONT><A NAME="19"></A>        String field = jRField.getName();
<FONT ID="LN">20  </FONT><A NAME="20"></A>        <FONT ID="Int">int</FONT> fieldPosition = Integer.parseInt(field.substring(<FONT ID="IntegerLiteral">7</FONT>)); <FONT ID="SingleLineComment">// Strip COLUMN_ 
<FONT ID="LN">21  </FONT><A NAME="21"></A></FONT>        StringTokenizer st = <FONT ID="New">new</FONT> StringTokenizer(row,<FONT ID="StringLiteral">";"</FONT>);
<FONT ID="LN">22  </FONT><A NAME="22"></A>        <FONT ID="While">while</FONT> (st.hasMoreTokens())
<FONT ID="LN">23  </FONT><A NAME="23"></A>        {
<FONT ID="LN">24  </FONT><A NAME="24"></A>            fieldPosition--; <FONT ID="SingleLineComment">// The column is not 0 indexed.
<FONT ID="LN">25  </FONT><A NAME="25"></A></FONT>            String token = st.nextToken();
<FONT ID="LN">26  </FONT><A NAME="26"></A>            <FONT ID="If">if</FONT> (fieldPosition == <FONT ID="IntegerLiteral">0</FONT>) <FONT ID="Return">return</FONT> token;
<FONT ID="LN">27  </FONT><A NAME="27"></A>        }
<FONT ID="LN">28  </FONT><A NAME="28"></A>        <FONT ID="Return">return</FONT> <FONT ID="Null">null</FONT>; <FONT ID="SingleLineComment">// Column not found...
<FONT ID="LN">29  </FONT><A NAME="29"></A></FONT>    }
<FONT ID="LN">30  </FONT><A NAME="30"></A>    
<FONT ID="LN">31  </FONT><A NAME="31"></A>    <FONT ID="Public">public</FONT> <FONT ID="Boolean">boolean</FONT> next() <FONT ID="Throws">throws</FONT> dori.jasper.engine.JRException {
<FONT ID="LN">32  </FONT><A NAME="32"></A>        <FONT ID="Try">try</FONT> {
<FONT ID="LN">33  </FONT><A NAME="33"></A>            row = lineNumberReader.readLine();
<FONT ID="LN">34  </FONT><A NAME="34"></A>            <FONT ID="If">if</FONT> (row.length()&gt;<FONT ID="IntegerLiteral">0</FONT>) <FONT ID="Return">return</FONT> <FONT ID="True">true</FONT>;
<FONT ID="LN">35  </FONT><A NAME="35"></A>        } <FONT ID="Catch">catch</FONT> (Exception ex) { }
<FONT ID="LN">36  </FONT><A NAME="36"></A>        <FONT ID="Return">return</FONT> <FONT ID="False">false</FONT>;
<FONT ID="LN">37  </FONT><A NAME="37"></A>    }   
<FONT ID="LN">38  </FONT><A NAME="38"></A>}</pre>
		      How you can see, only 38 lines of code... It's time to test it...<br>We'll write a little "JRDataSourcFactory" in order to use it with iReport.
		      This factory will instance a JRCSVDataSource and will return it with the static method: <code>getTheDatasource()</code><br>
		      <TABLE id="Header" border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td colspan="2" width="33%">&nbsp;</td>
<td align="center" colspan="2" width="33%">
<font size="4">CSVDatasourceTestFactory.java</font>
</td>
<td align="right" colspan="2" width="33%">&nbsp;</td>
</tr>
</TABLE>
<pre ID="Classes">
<FONT ID="LN">1   </FONT><A NAME="1"></A><FONT ID="Package">package</FONT> it.businesslogic.ireport.connection;
<FONT ID="LN">2   </FONT><A NAME="2"></A>
<FONT ID="LN">3   </FONT><A NAME="3"></A><FONT ID="Public">public</FONT> <FONT ID="Class">class</FONT> CSVDatasourceTestFactory {
<FONT ID="LN">4   </FONT><A NAME="4"></A>    
<FONT ID="LN">5   </FONT><A NAME="5"></A>    <FONT ID="Public">public</FONT> dori.jasper.engine.JRDataSource getTheDatasource( )
<FONT ID="LN">6   </FONT><A NAME="6"></A>    {
<FONT ID="LN">7   </FONT><A NAME="7"></A>        <FONT ID="Return">return</FONT> <FONT ID="New">new</FONT> JRCSVDataSource(<FONT ID="StringLiteral">"test.csv"</FONT>);
<FONT ID="LN">8   </FONT><A NAME="8"></A>    }
<FONT ID="LN">9   </FONT><A NAME="9"></A>}
<FONT ID="LN">10  </FONT><A NAME="10"></A></pre>
		      Open iReport, create a new custom JRDataSource connection and fill all fields as in Fig. 4.6, test and save the connection.
		      <table border=0><tr><td><a href="manual0.2.0/4_6big.jpg"><img border=1 src="manual0.2.0/4_6.jpg"></a></td></tr><tr><td><font class="fsmall"><b>Fig.4.6: The new CSV datasource connection.</b></font></td></tr></table>
		     <br>Now go to <font color="#AA0000"><b>Build &gt; Set active connection</b></font> and select our new connection ("CSV Datasource (test.csv)")<br>
		     <table border=0><tr><td><a href="manual0.2.0/4_7big.jpg"><img border=1 src="manual0.2.0/4_7.jpg"></a></td></tr><tr><td><font class="fsmall"><b>Fig.4.7: Set the active connection.</b></font></td></tr></table>
		     This is the result. We'll soon learn how to create the trial report used to test our datasource.
		     <table border=0><tr><td><a href="manual0.2.0/4_8big.jpg"><img border=1 src="manual0.2.0/4_8.jpg"></a></td></tr><tr><td><font class="fsmall"><b>Fig.4.8: The result print.</b></font></td></tr></table>
		     
		      </font><br><br>
		      </font>
		      
		       <hr height=1 width=100%>
		      <a href="manual0.2.0.html#1.0"  class="fmedim">&lt;&lt; Previous</a> &nbsp;&nbsp;|&nbsp;&nbsp; <a href="cap3.html#2.0"  class="fmedim">Next &gt;&gt;</a> &nbsp;&nbsp;|&nbsp;&nbsp; <a href="manual0.2.0.html"  class="fmedim">Table of Contents</a>
			<br><br>
		      </td>
		      
		     
		  </tr>
		   </table>
		   </td>
		    </tr> 
		   </table></td></tr></table></td>
  </tr>
  <tr height="15"><td><table  width="100%" border="0" cellspacing="0" cellpadding="0">
	<tr> 
	  <td height="1" colspan="2" bgcolor="#000000"><img src="images/null.gif height="1" width="1"></td>
	</tr>
	 <tr> 
	  <td   height="14" bgcolor="#D4D0C8" valign="bottom" align="center"><font class="fsmall">(c) 2002 by Giulio Toffoli &lt;gt78 at businesslogic.it&gt;</font></td>
	</tr>
      </table></td>
  </tr>
</table></body>
</html>
