JasperReports最终用户手册中文版——第二章API_概述.doc

2 API 概述大多数情况下，人们使用JasperReports的类库的时候都只会用到一小部分，并且不会对所有的API有个整体的概念。在这一章节里让我们近距离的来看一下那些在使用时有重要意义的类和接口。同时也可以了解在需要使用到JasperReports报表功能的应用程序里怎样使用这些类和接口。Class dori.jasper.engine.design.JasperDesign从这个类开始介绍是因为这个类的实例为JasperReports生成报表提供原材料。在JasperReprots使用内部的XML解析器解析了XML报表设计文件后便生成了dori.jasper.engine.design.JasperDesign实例。如果应用程序不使用XML文件，这个实例的生成也可以通过编程来实现。在提供源代码的例子里有一个叫做noxmldesign的例子，通过它你可以了解到如何不写XML报表设计文件而动态的生成一个dori.jasper.engine.design.JasperDesign实例。所有dori.jasper.engine.design.JasperDesign类的实例在被填充和生成报表使用之前已经被编译出来了。这就是我说它为类库提供原材料的原因。Class dori.jasper.engine.JasperReport这个类的实例是编译好的报表设计对象。它只会作为JasperReports报表编译的结果获得，并在填充表格和生成报表时被使用。为了以后更快速的使用，在通过不通程度的检查和报表元素整理后，这个类库创建了一个临时文件存放包括报表变量表达式、文本域和图形表达式组表达式等所有的报表表达式信息。这个临时Java源文件可以在两种情况下被编译。一是在使用中编译，还有一种是被JDK编译。如果在classpath里没有发现tools.jare文件，编译器就会通过运行javac.exe来编译这个文件。编译出来的二进制文件在填充报表数据和计算表达式时用到。Class dori.jasper.engine.JasperCompileManager这个类包括了报表编译的所有功能。使用它可以编译以文件形式和流形式提供的XML报表设计信息。它也可以直接在内存中将dori.jasper.engine.design.JasperDesign对象编译成dori.jasper.engine.JasperReport对象。其他的实用方法还包括了报表设计校验、在内存中生成XML报表设计和构造dori.jasper.engine.design.JasperDesign实例。通过GUI工具使用这些方法设计报表是一件非常简单的事情。Class dori.jasper.engine.JasperPrint在报表设计编译过并且填上了数据后，生成的文档以dori.jasper.engine.JasperPrint实例的形式存在。这时可以通过JasperReports内建的报表查看器直接使用，也可以序列化后存储到磁盘上以后使用，更甚于通过网络发送给他处使用。这个类的实例是JasperReports报表填充过程的输出，可以作为自定义格式的存储特征和页面导向的文档。它可以通过调用其他的方法被转换成诸如PDF、HTML、XML等常见的格式。Interface dori.jasper.engine.JRDataSourceJasperReports在报表数据来源方面是具有高柔韧性的。人们可以使用任意的数据源，前提条件就是能够提供一个这个接口的恰当的实现。这样报表引擎可以在填充报表时从数据源解析和检索数据。通常来说，如果一个报表填充了数据，肯定有一个这个接口的实例被报表引擎提供或创建。Class dori.jasper.engine.JRResultSetDataSource这个类是dori.jasper.engine.JRDataSource接口的一个默认实现。由于大多数的报表都由关系数据库的数据生成，JasperReports包含了一个封装了java.sql.ResultSet对象的默认实现。这个类有着明确的目的：在传给报表填充测试之前封装已经载入的数据集。在执行了通过JDBC的报表查询后它会被用来封装从数据库获得的数据。Class dori.jasper.engine.data.JRTableModelDataSource这个类是dori.jasper.engine.JRDataSource接口的另外一个默认实现。它封装了javax.swing.table.TableModel对象。它可以在Java Swing应用程序中通过已经载入的屏幕表格的数据生成报表。Class dori.jasper.engine.JREmptyDataSource作为最简单的dori.jasper.engine.JRDataSource接口的实现，这个类可以在不希望显示从数据源获得的数据，而只关心数据源的虚拟行数时在报表中使用。在提供的例子里有不少在填充报表时用到了这个类的实例，例如：fonts、images、shapes和unicode。这样做是为了模拟一个有一条空记录的数据源。Class dori.jasper.engine.JasperFillManager这个类实现了JasperReports的报表填充功能。它提供了接收以对象、文件或者输入流形式的报表设计和多样的输出形式如对象、文件和输出流的方法但是由于和报表设计放在一起，报表填充引擎为了生成文档不得不通过接收数据和值来接收数据源，以便生成报表参数。参数的值通常通过一个java.util.Map对象来提供，这个Map对象的键是报表参数的名字。数据源在不同的情况下可以通过两种方式提供：通常情况下，它必须作为一个dori.jasper.engine.JRDataSource对象被提供，就像上面说的那样。但是由于大多数的报表所填的值都是从关系数据库取出来的。JasperReports有一个内建的默认行为，可以让人们在报表设计的时候就指定一条SQL查询语句。当在运行时填充报表的时候，执行SQL查询语句来获得需要填充的值。在这种情况下，JasperReports需要的仅仅是一个java.sqlConnection对象，一个通常的数据源对象的实例。JasperReports需要使用这个连接对象通过JDBC连接到关系数据库管理系统，并且执行报表查询。在执行了报表查询后，JasperReports会自动创建一个dori.jasper.engine.JRResultSetDataSource对象来封装java.sql.ResultSet对象，并将它传给普通的填充过程使用。Class dori.jasper.engine.JRAbstractScriptlet脚本程序(Scriptlets)是JasperReports类库中一个非常强大的功能。它可以让用户自己编写在填充过程中可以被报表引擎执行的代码。用户代码可以在一个定义良好的片断（例如：页、列或者组）里操作报表数据；为生成的文档建立一个新的range。Class dori.jasper.engine.JRDefaultScriptlet这是dori.jasper.engine.JRAbstractScriptlet的一个便利的子类。大多数时间用户在使用脚本程序时会选择这个类，这样他们就不需要实现抽象类里定义的所有抽象方法了。Class dori.jasper.engine.JasperPrintManager我们在这里谈论Java报表工具而报表工具的意义就在于打印（显示）。在生成了文件形式的报表后，必须有办法来显示它，将它以不同的格式输出，而不光光是打印出来。在JapserReports中，我们可以通过这个类来打印报表，它包含了所有的打印功能。它提供了打印整个文档或者部分文档、显不显示打印对话框的方法。使用这个类可以将JasperReports文档的一页作为一个java.awt.Image对象来显示。Class dori.jasper.engine.JasperExportManager上面提到JasperReports可以将文档从它自己的格式转变成流行的文档格式，例如PDF、HTML或者XML。以后，JasperReports将会支持CSV、XSL和其他的格式。这个管理类对不同来源和不同去处（文件、输入输出流等）的数据提供不同的方法。Class dori.jasper.engine.JasperRunManager有时候在报表填充过程中我们不希望生成中间的dori.jasper.egine.JasperPrint对象，而直接生成我们所需要的文档格式，例如：PDF或HTML。这就可以通过这个类来实现。它可以在报表填充过程中直接将文档生成所需要的输出格式。这个管理类的使用方法在提供的webapp的例子里涉及到。Class dori.jasper.view.JRViewer这个类和上面说到的类不大一样，说它是一个实用类不如说是一个显示插件。它可以用在基于Swing的应用程序里来显示JasperReports生成的报表。这个可视化组件并不能满足每一个人。它被当作一个例子组件被包含在主类库中，用来显示核心打印功能可以在基于Swing的应用程序里通过dori.jasper.engine.JasperPrintManager类生成java.awt.Image对象来显示报表。如果想修改这个组件使其满足应用程序的需求，首选的方法是使用它的子类。Class dori.jasper.view.JasperViewer这也是一个以教学为目的的类。它使用了dori.jasper.view.JRViewer组件来显示报表。它是一个简单的Java Swing应用程序，可以装载和显示报表。它在提供的例子中被广泛的使用，用来显示生成的文档。Class dori.jasper.view.JasperDesignViewer通常，一个使用JasperReports来生成报表的应用程序如果使用了这个类将不能运行。这个类可以在设计阶段用来预览报表模版。它被当作一个用作可视化设计而使用的开发工具提供。它也在所有的例子里被用到。用来预览报表设计，不管是原始的XML表单还是编译后的表单。Class dori.jasper.engine.util.JRLoader所有JasperReports的主要过程，例如：报表编译，报表填充和输出，经常操作序列化的对象。有时候，在提交序列化的对象到希望的JasperReports过程之前，我们需要手动载入这些对象。这就是有dori.jasper.engine.util.JRLoader类的原因。它可以从不同的环境（文件、URL或者输入流）载入序列化的对象。这个类中最有趣的方法就是loadObjectFromLocation(String location)方法了。当调用这个方法来载入一个对象时，程序会先通过一个有效的URL来解析路径。如果失败了，程序就会认为这是一个文件路径并且尝试去读取。如果这个文件也没有被发现，程序就会尝试在classpath里寻找能够匹配的资源。如果这也失败了，没的说，只好抛出异常。