[转]JasperReport用户手册之五

5 报表数据（ Report Date ）
       当我们谈到报表装填过程的时候，有三样东西需要作为输入提供给报表引擎：报表设计（ report design ），参数值（ parameter values ）和报表的数据源（ data source ）。
在先前的章节，我们已经看到了有关报表设计的某些方面，现在我们要更加详细的关注其他两方面的内容：参数（ parameter ）和报表数据源。他们描绘了报表引擎在装填报表过程中所用到的仅有的数据来源。像你用其他报表工具所希望的一样，这些数据将会根据报表设计中的定义的模版（ template ）被组织起来，并被用来生成准备打印的、面向页面的文档。

5.1 表达式（expressions）
       表达式是JasperReport的一个非常有用的特性。他们可以用来声明执行各种执行各种计算（calculations）的报表变量（report variables），进行报表的数据组织，定制报表文本字段（text field）的内容或者进一步定制报表对象的appearance。
所有报表表达式基本上都是Java表达式，他们可以以特殊的语法引用报表参数（parameter），报表字段（field）和报表变量（variable）。在XML报表设计中，有一些用于定义表达式的元素：，，，，，等等
因为所有的JasperReport表达式都是真正（real）的Java表达式，只要你用完整的类名（包括包名）来引用这些表达式，你就可以在任何class中使用他们。当你编译报表和装填数据的时候，你应该确定你在报表表达式中使用的类已经写入了classpath。
报表参数引用是通过$P{}序列引入的，例如：
$P{ReportTitle}
       这个例子假定我们在报表设计中有一个名为ReportTitle的报表参数，这个参数是一个java.lang.String类。当报表进行装填的时候，文本字段将会显示这个参数的值。
为了在一个表达式中使用报表字段，字段名必须放在$F{}的括号中。例如，如果我们想要在一个文本字段中显示两个数据源字段的连接值（concatenated values）,我们可以定义如下表达式：
$F{FirstName} + “ “ + $F{LastName}
表达式可以更加复杂：

$F{FirstName} + “ “ + $F{LastName}　+ “ was hired on “ +
(new SimpleDateFormat(“MM/DD/YYYY”)).format($F{HireDate)) + “.”
       正如你所看到的一样，参数、字段和变量引用都是通过用JasperReport的特殊语法从一个真正地Java对象中引入的。（实际上是一个JREvaluator对象，该对象是在运行其生成的动态对象，并不能在本地磁盘上见到它的身影，不过如果你使用iReport的话，你就可以在生成报表文件的同一目录下看到它的本来面目）

5.2 参数（Parameters）
       Parameters是传递给报表装填操作的对象引用。这些参数主要作用于把那些不能从报表数据源中获得的数据传给报表引擎。例如，我们可能要把执行报表装填过程的用户名字专递给报表引擎，如果我们想让它显示在报表上或者在我们想在报表的title上动态的改变它，我们就可以以参数的形式传给报表引擎。

我们可以用如下的方式定义参数：
       这里所提供的报表参数值可以被用到各种报表表达式中，在报表SQL查询中，甚至可以用到报表的scriptlet类里。下面是构成参数定义的全部组件（XML元素）：
参数名
       name属性是一个强制属性。JasperReport的命名习惯和Java语言的命名习惯是类似的，这意味着参数名应该是一个单词，其中不含特殊字符（如分号）。
参数类型
       报表参数的第二个强制属性是提供参数值的类型名。这个类型属性可以使任意的值，只要这个类型的名字在报表编译期和装填期能在classpath中找到即可。
Prompting for Parameter values
       在GUI引用程序中，建立一个报表参数集，让用户在执行装填过程之前输入某些应用程序需要用户输入的报表参数是很有用的。可选参数isForPropting参数用来声明是否显示提示信息让用户输入某些参数。下面的例子中，我声明了一个文本参数，当需要用户输入参数值的时候，这个文本参数用来在一个已定制的对话框中描述需要用户输入什么样的参数。
Please type here the report comments if any
]]>
       注意：相信大家都知道表示“内容”将不被XML解析器解析，也就是说，你可以在“内容”里加入XML的特殊字符，如>，<等等。
参数的默认值（parameter default value）
       通常参数值都是使用java.util.Map对象传给装填过程的，其中参数名作为Key。这样，你就不用每次都为每个参数提供一个value了—可以批量放到Map对象里一起传给装填管理器。如果你没有为参数提供一个value，引擎就认为它是null。但是如果你为它提供了一个默认值，则引擎将在你没提供这个参数值的情况下使用这个默认值。如果你在装填时没提供数据，下面的java.util.Date将在装填是被引擎使用来表示当天日期：
new java.util.Date()
在参数的默认表达式中，我们可以使用这个与定义的报表参数。
5.2.1内置的报表参数
       每一个报表设计中都含有一些与定义的报表参数，这些内置的参数的描述如下：
REPORT_PARAMETERS_MAP
       这是一个内置的参数，这个参数总是指向一个java.util.Map对象，该对象保存了用户调用报表装填过程时传递给报表引擎的用户定的参数。
REPORT_CONNECTION
       这个报表参数指向一个java.sql.Connection对象，这个对象被提供给报表引擎用来通过JDBC来执行SQL报表查询。将master报表使用的JDBC Connection对象传递给subreport是非常有用的，有关这方面信息请查看subreport例子
REPORT_DATASOURCE
       在报表装填的时候，我们可以或者直接由应用程序中提供，或由报表引擎从所提供的JDBC　Connection在后台create而获得一个数据源。这个内置的参数允许我们在报表表达式中或scriptlet中访问报表数据源，而不论我们为什么要这么做。
REPORT_SCRIPTLET
       即使报表不使用scriptlet，这个内置的参数仍将指向一个net.sf.jasper.engine.JRAbstracStriptlet实例，该实例实际是一个net.sf.jasper.engine.JRDefaultScriptlet对象。
但是当使用scriptlet时，报表装填过程所生成的这个指向scriptlet类实例的引用允许我们调用其中的某些特殊函数，使用或控制scriptlet对象在装填过程中已经准备好的数据。在scriptlet例子中你可以看到更详细的使用过程。

5.3 Data Source（数据源）
       在进行报表装填的时候，JasperReport引擎迭代的从用户提供的数据源中提取record，并根据报表设计所提供的模版生成报表的各个部分（section）。通常情况下，引擎需要接收一个net.sf.jasper.engine.JRDataSource对象作为报表数据源。但是像我们即将看到的那样，当报表数据存储于关系型数据库的时候，JasperReport有了让用户提供一个JDBC链接对象来替代通常的数据源对象的特性。JRDataSource接口非常简单，如果我们想要实现它只需要实现下面两个方法：
public Boolean next() throw JRException;
public Object getFieldValue(JRField jrField) throw JRException
       在报表装填的时候，next()方法将被报表引擎调用，迭代的从数据源中获取数据。第二个方法用来为每个在当前数据源记录（data source record）中的报表字段（report field）提供value。
       应当知道，从数据源取得数据的唯一方法是使用report field。一个数据源对象更像是一个二维表，表中含有数据。这个二维表的行是一条一条的record，而每一列都映射为一个report field。所以我们可以在report表达式中使用数据源。JasperReport提供了一些缺省的JRDataSource实现，我们来具体看一下：
Class net.sf.jasper.engine.JRResultSetDataSource
       这是一个非常有用的缺省实现，因为他外覆（wrap）了java.sql.ResultSet对象。由于多数报表的生成都采用关系数据库中存储的数据，所以这个类是被使用得最为广泛的数据源对象。然而在以下的两种情况下您可以不必在装填过程中自己生成这个对象：
       如果你选择在你的报表中用SQL查询来获得在关系数据库的某个table中的数据，报表引擎将会通过执行给定的SQL查询并且将返回的java.sql.ResultSet外覆为一个net.sf.jasper.engine.JRResultSetDataSource实例来执行这项操作。引擎唯一需要的是一个java.sql.Connection对象来执行查询操作。这时你可以提供connection对象来作为通用数据源对象（usual data source object）。例子有：jasper，scriptlet，subreport和query。
当然你可以在应用程序中即JasperReport之外执行SQL查询。这样的话，你可以手动的外覆java.sql.ResultSet，再调用报表装填过程之前实例化这个数据源对象。当使用这种类型的数据源的时候，你需要为在result set中的每一列生命一个report field。report field的名字和类型必须和列的名字和类型匹配。
Class net.sf.jasper.engine.JREcptyDataSource
       这个类主要用于当生成报表的数据不是来自数据源，而是来自参数或重要的仅是数据源中virtual records的数量的时候。例子fonts，images，shapes和unicode都使用了这个类来装填报表，来模拟数据源中没有一条记录，所有字段都为null的情况。
Class net.sf.jasper.engine.data.JRTableModelDataSource
       这个JRDataSource接口的缺省实现外覆了javax.swing.table.TableModel对象，它可以用在Java Swing应用程序中从已经显示到屏幕上的table中得数据来生成报表。--我喜欢。
通常有两种方法来使用这种数据源：
通常，为了要从中取得数据，你需要为javax.swing.table.TableModel对象的每一列生命一个report field。但是有些情况下会出现问题，比如report field的命名需要遵照Java命名规范来声明变量，而table的列名则不需要。幸运的是，你仍然可以通过列的索引而不是它的名字来将report field与列进行映射。例如，一个列名为“Produce Description”不可能被映射到名为“Produce Description”的report field上，因为report field名中含有空格，这将引起一个编译错误。但是如果你知道这个列示table model对象的第三列（index=2），那么你就可以命名相应的字段“COLUMN_ 2”并无误地使用这一列的数据。例子有：datasource
Class net.sf.jasper.engine.data.JRBeanArrayDataSource
       这个类外覆了一个JavaBeans数组，并且通过反射来获取report field的值。在这种数据源中，一个JavaBean对象描述了一条记录。如果我们有一个名为“ProductDescription”的report field，在获取这个字段的值的时候，程序将会试图通过反射机制调用一个当前JavaBeans对象中]名为getProductDescription()的方法。对于boolean字段，当调用get前缀的属性不能返回其属性值的时候，程序将会试图使用is前缀的方法来获得属性值。
Class net.sf.jasper.engine.data.JRBeanCollectionDataSource
       这个类和上一个类非常类似，它也是使用反射机制和JavaBean命名规范，但是它外覆了一个java.util.Collection对象而不是一个JavaBean对象数组。在datasource例子中你可以看到进一步的用法。