Jasper Reports 简明教程

Report Data Sources

数据源是结构化的数据容器。在生成报表时，JasperReports 引擎从数据源获取数据。可以从数据库、XML 文件、对象数组以及对象集合获取数据。我们已经在 Filling Reports 章中看到，fillReportXXX() 方法期望接收报表的数据源，它必须以 net.sf.jasperreports.engine.JRDataSource 对象或 java.sql.Connection 的形式进行填充（如果报表数据位于关系数据库中）。

Datasources are structured data container. While generating the report, JasperReports engine obtains data from the datasources. Data can be obtained from the databases, XML files, arrays of objects, and collection of objects. We saw in the chapter Filling Reports, the fillReportXXX () method expects to receive a data source of the report, which has to fill, in the form of net.sf.jasperreports.engine.JRDataSource object or a java.sql.Connection (when the report data is found in a relational database).

JRDataSource 接口只有两个方法，应该实现以下内容 −

The JRDataSource interface has only two methods, which should be implemented −

public boolean next() throws JRException; At the report filling time, this method is called on the data source object by the reporting engine when iterating through the data.
public Object getFieldValue(JRField jrField) throws JRException; This method provides the value for each report field in the current data source record.

检索数据源中数据的唯一方法是使用报表字段。JRDataSource 接口有多个默认实现，具体取决于获取数据源中记录的方式。

The only way to retrieve data from the data source is by using the report fields. There are several default implementations of the JRDataSource interface, depending on the way, the records in the data source are acquired.

Datasource Implementations

下表总结了数据源及其实现类 −

The table given below summarizes the datasources and their implementation classes −

Datasource

Implementation Class

JDBC

net.sf.jasperreports.engine.JRResultSetDataSource

JavaBean

net.sf.jasperreports.engine.data.JRBeanCollectionDataSource, net.sf.jasperreports.engine.data.JRBeanArrayDataSource

Map-based

net.sf.jasperreports.engine.data.JRMapArrayDataSource, net.sf.jasperreports.engine.data.JRMapCollectionDataSource

TableModel

net.sf.jasperreports.engine.data.JRTableModelDataSource

XML

net.sf.jasperreports.engine.data.JRXmlDataSource

CSV

net.sf.jasperreports.engine.data.JRCsvDataSource

XLS

net.sf.jasperreports.engine.data.JRXlsDataSource

Empty

net.sf.jasperreports.engine.JREmptyDataSource

JDBC Data Sources

类 JRResultSetDataSource 会包装 java.sql.ResultSet 对象。当报表数据从关系数据库中提取时，这是最常用的数据源实现。如果 java.sql.Connection 传递到引擎，它将首先执行相关查询并将返回的 java.sql.ResultSet 对象存储在 JRResultSetDataSource 实例中。

Class JRResultSetDataSource craps a java.sql.ResultSet object. This is the most commonly used data source implementations when report data are extracted from a relational database. If a java.sql.Connection is passed to the engine instead, it executes first the related query and stores the returned java.sql.ResultSet object in a JRResultSetDataSource instance.

JavaBean Data Sources

类 JRBeanArrayDataSource 和 JRBeanCollectionDataSource 表示可以包装 JavaBean 对象数组和集合的实现。数组或集合中的每个对象都将被视为此类型数据源中的一条记录。特定 JavaBean 属性和相应报表字段之间的映射是通过命名约定进行的。报表字段的名称必须与 JavaBean 规范中指定的 JavaBean 属性的名称相同。

Classes JRBeanArrayDataSource and JRBeanCollectionDataSource represent implementations that can wrap arrays and collections of JavaBean objects. Each object inside the array or the collection will be seen as one record in this type of data source. The mapping between a particular JavaBean property and the corresponding report field is made by naming conventions. The name of the report field must be the same as the name of the JavaBean property as specified by the JavaBeans specifications.

在本教程的所有示例中，我们都使用了 JRBeanCollectionDataSource。

In all the examples of this tutorial, we have used JRBeanCollectionDataSource.

Map-based Data Sources

如果父应用程序已将报告数据存储在内存中，类 JRMapArrayDataSource 和 JRMapCollectionDataSource 的实现非常有用。包装的数组或集合中的每个 Map 对象都被视为数据源中的一个虚拟记录，报表字段的值是从使用报告字段（指定为键）的 map 中提取的。

The implementation classes JRMapArrayDataSource and JRMapCollectionDataSource are useful if the parent application already stores the reporting data available in-memory as java.util.Map objects. Each Map object in the wrapped array or collection is considered a virtual record in the data source, and the value of each report field is extracted from the map using the report field named as the key.

TableModel Data Sources

在许多客户端应用程序中，数据以表格格式显示。许多应用程序中一个常见的需求是允许用户将此表格格式打印为报表。实现类 JRTableModelDataSource 使得从表格格式为 Swing 应用程序生成报表变得轻而易举。此类包装一个 javax.swing.table.TableModel 对象。可以通过它们的名称或它们的以 0 为基准的索引来访问包装的 TableModel 对象中的列。

In many client-side applications, data is displayed in tabular format. A common requirement in many applications is to allow the user to print this tabular format as a report. Implementation class JRTableModelDataSource makes the task of generating reports from tabular format trivial for Swing applications. This class wraps a javax.swing.table.TableModel object. Columns in the wrapped TableModel object can be accessed either by their names or by their 0-based indexes.

XML Data Sources

类 JRXmlDataSource 是一种基于 DOM 的数据源实现，它使用 XPath 表达式从 XML 文档中选择数据。XML 数据源中的记录由通过 XPath 表达式选择的节点元素表示。使用字段说明（JRXML 中的 <fieldDescription> 元素）提供的 XPath 表达式从每个记录中检索字段值。

Class JRXmlDataSource is a data source implementation based on DOM, which uses XPath expressions to select data from the XML document. Records in the XML data source are represented by node elements selected through the XPath expression. Field values are retrieved from each record using the XPath expression provided by the field description (<fieldDescription> element in JRXML).

XPath 是一种用于导航 XML 文档的属性和元素的语言。在 http://www.w3.org/TR/xpath. 中可以找到有关 XPath 的更多信息

XPath is a language used to navigate through an XML document’s attributes and elements. More information about XPath can be found at http://www.w3.org/TR/xpath.

CSV Data Sources

JRCsvDataSource 表示一种用于数据源的实现，它从结构化文本文件（通常是 CSV）中检索其数据。使用它们的列索引检索字段值。

JRCsvDataSource represents an implementation for data sources, which retrieve their data from structured text files; usually CSVs. Field values are retrieved using their column index.

XLS Data Sources

JRXlsDataSource 表示一种用于数据源的实现，它从 Excel 文档中检索其数据。此数据源实现的报表字段映射也基于字段列索引。

JRXlsDataSource represents an implementation for data sources, which retrieve their data from Excel documents. Report-field mapping for this data source implementation is also based on the field column index.

Empty Data Sources

类 JREmptyDataSource 模拟了一个数据源，其内部具有给定数量的虚拟空记录。UI 工具使用它来提供基本的报表预览功能，或在特殊报表模板中，或用于测试和调试目的。

The class JREmptyDataSource, simulates a data source with a given number of virtual empty records inside. It is used by the UI tools to offer basic report preview functionality, or in special report templates, or for testing and debugging purposes.

Rewindable Data Sources

net.sf.jasperreports.engine.JRRewindableDataSource 扩展了基本的 JRDataSource 接口。它只会将一个方法 moveFirst() 添加到接口中。该方法旨在将光标移动到数据源中的第一个元素。

The net.sf.jasperreports.engine.JRRewindableDataSource extends the basic JRDataSource interface. It adds only one method, called moveFirst (), to the interface. This method is intended to move the cursor to the first element in the datasource.

当使用不允许拆分（因为 isSplitAllowed="false" 设置而产生）的频带中放置的子报表进行操作时，可回绕数据源非常有用，且当前页面上没有足够空间来渲染子报表。

Rewindable data sources are useful when working with sub-reports placed inside a band that is not allowed to split due to the isSplitAllowed="false" setting and there is not enough space on the current page for the sub report to be rendered.

以上所有数据源实现都是可回绕的，除了 JRResultSetDataSource ，因为它不支持将记录指针移回。仅当此数据源被手动用于包装一个 java.sql.ResultSet 并将其传递到子报表中时，才会出现问题。如果 SQL 查询位于子报表模板中，则不存在问题，因为引擎会在下个页面重新启动子报表时再次执行它。

All the above data source implementations are rewindable except for the JRResultSetDataSource, as it does not support moving the record pointer back. This poses a problem only if this data source is used manually to wrap a java.sql.ResultSet before passing it to the sub-report. There is no problem, if the SQL query resides in the sub-report template, as the engine will execute it again when restarting the sub-report on the next page.

Data Source Providers

JasperReports 库具有一个接口 net.sf.jasperreports.engine.JRDataSourceProvider 。它有助于创建和销毁数据源对象。在使用 GUI 工具创建报表模板时，需要一个用于定制报表数据源的特殊工具。JRDataSourceProvider 是将定制数据源插入设计工具中的标准方法。此接口的定制实现应实现以下方法，这些方法允许创建和销毁数据源对象，还允许（如果可能）列出数据源中可用的报表字段 −

The JasperReports library has an interface net.sf.jasperreports.engine.JRDataSourceProvider. This helps in creating and disposing of data source objects. When creating a report template using GUI tools, a special tool for customizing the report’s data source is needed. JRDataSourceProvider is the standard way to plug custom data sources into a design tool. A custom implementation of this interface should implement the following methods that allow creating and disposing of data source objects and also methods for listing the available report fields inside the data source if possible −

public boolean supportsGetFieldsOperation();

public JRField[] getFields(JasperReport report)
   throws JRException, UnsupportedOperationException;

public JRDataSource create(JasperReport report) throws JRException;

public void dispose(JRDataSource dataSource) throws JRException;