[转]JasperReport用户手册之一

1 简介

       JasperReport 是一个强大、灵活的报表生成工具，能够展示丰富的页面内容，并将之转换成 PDF ， HTML ，或者 XML 格式。最重要的是它是开源的，这给我们带来很大方便，但是文档却要钱，让人不爽。不过人总要生存，再说，做这么一个好东西，用户总不能一点代价也不付（虽然对于中国普通程序原来说太贵了点）。它还有一个相关的开源工程 —IReport ，这是一个图形化的辅助工具，因为 JasperReport 仅提供了可使用的类库而未提供更好的开发工具， IReport 的出现解决了这一难题。它们配合使用将会更大程度的提高效率。

       该库完全由 Java 写成，可以用于在各种 Java 应用程序，包括 J2EE ， Web 应用程序中生成动态内容。它的主要目的是辅助生成面向页面的（ page oriented ），准备付诸打印的文档。 JasperReport 借由定义于 XML 文档中的 report design 进行数据组织。这些数据可能来自不同的数据源，包括关系型数据库， collections ， java 对象数组。通过实现简单的接口，用户可以将 report library 插入到订制好的数据源中，在以后我们将提到有关内容。
其实这是一份 JasperReport Ultimate Guide 的简单翻译以及我的理解和例子。在最后，我将描述一个我正在做的工程，将其中用到的相关信息贡献出来。我这么做是因为当我在学这个类库的时候苦于很少有相关的中文文档，诱惑语焉不详，希望其他人不再受苦。这个文档将分几次贴出来，与原文档的章节相对应。这份文档的 Word 形式将在全部完成之后放在我的公开邮箱中与各位共享。我的 EMail 是 jxuedi@gmail.com 有什么意见或想法请与我联系。
闲言少叙，进入正题。

2 API 概览

       上图为一个生成报表并打印（导出）的全过程。我将会把涉及到的重要的类进行一一说明。
Class net.sf.jasper.engine.design.JasperDesign
       这是一个未经加工的报表实例，供 JasperReport Library 使用。这个类可以在 JasperReport 类库内置的 XML 解析器对 XML report design 进行解析处理之后得到。如果你的程序不想对直接 XML 文件进行操作，在例子 noxmldesign 中有不使用 XML 设计文件而动态生成这个类的方法。我们稍稍看看这个例子：
import 略
public class NoXmlDesignApp
{
private static JasperDesign getJasperDesign() throws JRException
{
//JasperDesign 定义 JasperDesign 的头信息
JasperDesign jasperDesign = new JasperDesign();
jasperDesign.setName("NoXmlDesignReport");
. 剩余略

//Fonts 定义使用到的字体
JRDesignStyle normalStyle = new JRDesignStyle();
normalStyle.setName("Arial_Normal");

//Parameters 定义 Parameters 的内容 — 这个内容以后会提到
JRDesignParameter parameter = new JRDesignParameter();
parameter.setName("ReportTitle");
parameter.setValueClass(java.lang.String.class);
jasperDesign.addParameter(parameter);

parameter = new JRDesignParameter();
parameter.setName("OrderByClause");
parameter.setValueClass(java.lang.String.class);
jasperDesign.addParameter(parameter);

//Query 定义查询
JRDesignQuery query = new JRDesignQuery();
query.setText("SELECT * FROM Address $P!{OrderByClause}");
jasperDesign.setQuery(query);

//Fields
JRDesignField field = new JRDesignField();
field.setName("Id");
field.setValueClass(java.lang.Integer.class);
jasperDesign.addField(field);

//Variables 定义变量
JRDesignVariable variable = new JRDesignVariable();
variable.setName("CityNumber");
variable.setValueClass(java.lang.Integer.class);
variable.setResetType(JRVariable.RESET_TYPE_GROUP);

//Groups 定义组
group.setMinHeightToStartNewPage(60);
expression = new JRDesignExpression();
// 余下定义一个文档的其他内容，这里省略

return jasperDesign;
}
从 getJasperDesign() 方法我们可以看出，这个应用程序并没有从 XML 文件里面将 report design 提取出来在生成 JasperDesign 类，而是直接利用 JasperDesign 提供的函数生成了一个报表设计。这样做的原因是基于灵活性的考虑，你可以在程序中随时动态生成报表，而不需要去从硬盘或网络中读取 XML 设计文件。但通常我不这么做，因为比较麻烦，而且要对 JasperReport 的每个元素都非常熟悉才行。
Class net.sf.jasper.engine.JasperReport
       这个类的实例包含了一个经过编译的 report design 对象。生成它的时机是对报表编译之后，但尚未对其填入数据的时候。编译过程中， JasperReport 需要生成一个临时的类文件，用以保存 report expression ，如变量表达式，文本，图像表达式，组表达式等等。这个临时的 Java Source File 是被动态编译的，编译器使用的是 JDK 中用来执行应用程序的编译器类（ compiler class ）。如果 tools.jar 不在 classpath 中，编译过程将采用 javac.exe 来进行后台编译。编译后所得的字节码保存在 JasperReport 类中，用来在执行期装填数据（ filling the report with data ）和给表达式赋值（ evaluate various report expression ）。
Class net.sf.jasper.engine.JasperCompileManager
       这是一个上面提到的与编译有关的类。利用它提供的一些方法，你将有能力编译从本地硬盘或一个 Input Stream 获得的 XML report ；还可以通过传给 JasperCompileManager 一个 JasperDesign 类，来对内存中的 report design 进行编译 — 功能很强大。
Class net.sf.jasper.engine.JasperPrint
       当一个报表已经装填好数据之后，这个文档就以 JasperPrint 类的实例出现。这个类可以直接用 JasperReport 内置的 viewer 进行查看，也可以序列化到硬盘以备后用，或者发送到网上去。这个类的实例是报表装填过程后的产物，它可以被 JasperReport 类库中的导出方法导出成各种流行的格式 —PDF ， HTML ， XML 等等。
Interface net.sf.jasper.engine.JRDataSource
       这个类与报表的数据源有关。只要能够恰当的实现他的一些接口，用户就可以在报表中使用各种数据源，在报表装填的时候由报表引擎负责对数据进行解释和获取。当报表装填的时候，报表引擎都会在后台生成或提供一个该接口的实例。
Class net.sf.jasper.engine.JRResultSetDataSource
       这是一个 JRDataSource 的缺省实现，因为很多报表数据都来源于关系数据库，所以 JasperReport 缺省包含了这个外覆（ wrap ）了 java.sql.ResultSet 对象的实现。
这个类可以用来包裹（ wrap ）用以对报表进行装填的、已经载入的结果集，也可以被报表引擎用来包裹通过 JDBC 执行完查询后所得的数据 ---- 非常有用。
Class net.sf.jasper.engine.data.JRTableModelDataSource
       顾名思义，这个类用于包裹 java.swing.table.TableModel 类中的数据，它也是实现了 JRDataSource 接口，用于在 Java Swing 程序中使用已经被载入到 table 中的数据来生成报表。
Class net.sf.jasper.engine.JREmptyDataSource
       这是 JRDataSouce 接口的最简单实现，这个类用在不需要显示数据源数据而从参数中获取数据的报表和仅需要知道数据源中的实际行数（ number of virtual rows ）的报表中。
JasperReport 自带的例子： fonts ， images ， shapes 和 unicode 中使用这个类对报表进行装填，来模拟没有任何 record 的数据源，这时所有的 field 都为 null 。例如：
JasperRunManager.runReportToPdfFile(fileName, null, new JREmptyDataSource());
Class net.sf.jasper.engine.JasperFillManager
       这个类用来实现报表的数据装填。这个类提供了很多方法来接受各种类型的 report design-- 可以是一个对象，一个文件，或一个输入流。它的输出结果也是多样的： file ， Object ， output Stream 。
report 的装填引擎需要接收一个可以从中获取数据和 value 的数据源作为报表参数。参数值（ Parameters value ）通常使用 Java.util.Map 来提供，里面包含的 KEY 是报表的参数名。
数据源可以通过两种方式提供，这取决于你的解决方案：
通常情况下，用户应该提供一个 JRDataSource 对象，例如我前面提到的那些。
但是大多数的报表都是采用关系数据库中的值来装填数据，所以 JasperReport 拥有一个内置的缺省行为 — 让用户在报表设计的时候提供一个 SQL 查询。在运行期，这个查询将被执行以用来从数据库中获取要装填的数据。在这种情况下， JasperReport 仅需要一个 java.sql.Connection 对象来取代通常的数据对象。 JasperReport 需要这个连接对象来连接数据库管理系统并执行查询操作。
在查询结束之后， JasperReport 将自动生成一个 JRResultSetDataSource ，并将它返回给报表装填过程。
Class net.sf.jasper.engine.JRAbstractScriptlet
       这个类同样用于报表装填期间，用户可以自己定义一些代码，并由报表引擎在装填过程中执行。这些用户代码可以处理报表数据操作，或在一些定义好的时刻执行，例如 page ，列，或组的分割处。
Class net.sf.jasper.engine.JRDefaultScriptlet
       这是一个非常方便的 JRAbstractScriptlet 的子类。通常情况下你应该选择继承这个类。
Class net.sf.jasper.engine.JasperPrintManager
       这个类用户提供打印方法，用户可以将整个文档或部分文档传递给它，也可以选择是否显示打印 Dialog ，这在他的 API 文档中可以找到，这里不再赘述。
Class net.sf.jasper.engine.JasperExportManager
       顾名思义，这个类负责文档的导出。这个类的具体信息详见 API 文档。非常明显和清除，没什么好解释的， Just use it 即可。
Class net.sf.jasper.engine.JasperRunManager
       有时，我们仅仅需要构造一个流行的文档格式，例如 PDF ，或 HTML ，而不需要将装填过程后生成的 JasperPrint 对象保存到硬盘或其他中间媒体上。这时，可以使用这个类来直接将装填过程生成的文档导出到所需的格式。
Class net.sf.jasper.view.JRViewer
       这是一个基于 Swing 的应用程序，你可以将它视为一个独立组件，用来进行打印预览。用户可以继承这个类，来构造满足自身要求的预览程序。
Class net.sf.jasper.view.JasperViewer
       这个类更像是使用 JRViewer 的教学组件，它演示了一个 Swing 应用程序如何装在并显示报表。
Class net.sf.jasper.view.JasperDesignViewer
       这个类用于报表的设计期间，用来预览报表模版。它仅作为一个开发工具存在于类库中。
Class net.sf.jasper.engine.util.JRLoader
       装载器用于报表生成的各个主要阶段 — 编译，装填等等。用户和引擎都可以利用这个类来装载所需的序列化对象如 file ， URLs ， intput stream 等等。这个类最令人感兴趣的函数当属 loadOnjectFromLocation(String location) 。当用户使用这个类从指定地点装载对象的时候，该函数将首先将 location 解释为一个合法的 URL ，如果解析失败，函数将认为所提供的 location 是硬盘上的一个文件名，并将试图读取它。如果在指定地点没找到文件，它将通过 classpath 定位一个相应于该 location 的资源，所有努力失败之后，将抛出异常。