[转]JasperReport用户手册之二

3 主要的任务和过程
       这一节我们将看到对你的 XML 报表设计进行分析，编译，装填数据，预览结果和导出到其他格式的过程。
3.1 XML 解析
       JasperReport 使用 SAX2.0 API 对 XML 文件进行解析。然而，这并不是必须的，用于可以在执行其自行决定使用哪一种 XML 解析器。
JasperReport 使用 org.xml.sax.helpers.XMLReaderFactory 类的 createXMLReader() 来获得解析器实例。在这种情况下，就像在 SAX2.0 文档中说的那样，在运行期，把 Java 系统属性 org.xml.sax.driver( 这是属性的 key) 的值 (value) 设定为 SAX driver 类的全限定名是必要的。用户可以通过两种方法做到这一点，我稍后将解释全部两种方法。如果你想使用不同的 SAX2.0XML 解析器，你需要指定相应的解析器类的名字。
设置系统属性的第一种方法是在你启动 Java 虚拟机的时候，在命令行使用 -D 开关： java –Dorg.xml.sax.driver=org.apache.serces.parsers.SAXParser mySAXApp sample.xml
在 JasperReport 提供的所有例子中，都采用 ANT 构建工具来执行不同的任务。我们通过使用内置的 task 中的元素来提供这一系统属性：

第二种设置系统属性的方法是使用 java.lang.System.setProperty(String key, String value)
System.setProperty(“org.xml.sax.driver”,” org.apache.xerces.parsers.SAXParser”);
Jsp/compile.jsp 和 web-inf/class/servlets/CompileServlet.java 文件提供了这方面的例子。
注：对于第二种方法，我要说些题外话。有关于 JVM 的系统属性（我们可以通过 System.out.println （ System.getProperty(“PropertyKey”) 来查看），可以在运行期像上面说所得那样用 System.setProperty(“propertyKey”,”propertyValue”); 来进行设置。但是一旦 JVM 已经启动之后，其内建的系统属性，如 user.dir ，就不能再被更改。奇怪的是我们仍可以用 System.setProperty() 方法对其进行设置，而在用 System.out.println(System.getProperty()) 方法进行查看的时候发现，其值已经更改为我们设置的值，但事实上我们设置的值不会起任何作用。所以对于内置的属性，我们只能通过 -D 开关在 JVM 执行之前进行设置。对于 org.xml.sax.driver ，由于它不是系统内建属性，所以仍然可以在 JVM 启动之后加以设置。更详细的信息可以参考王森的〈 Java 深度历险〉。

3.2 编译报表设计 (Report Designs)
       为了深成一个报表，用户需要首先生成报表的设计（ report’s design ），生成方法或采用直接编辑 XML 文件，或通过程序生成一个 net.sf.jasper.engine.design.JasperDesign 对象。本文中，我将主要采用编辑 XML 文件的方法，因为这种方法在目前是使用 JasperReport 类库的最好的方法，并且我们有机会更好的了解类库的行为。
       先前提到过， XML 报表设计是 JasperReport 用来生成报表的初级材料（ raw meterial ）。这是因为 XML 中的内容需要被编译并载入到 JasperDesign 对象中，这些对象将在报表引擎向其中填入数据之前经过编译过程。
       注意：大多数时候，报表的编译被划归为开发时期的工作。你需要编译你的应用程序报表设计，就像你编译你的 Java 源文件一样。在部署的时候，你必须将编译好的报表，连同应用程序一起安装到要部署的平台上去。这是因为在大多数情况下报表设计都是静态的，很少用应用程序需要提供给用户在执行期编译的，需要动态生成的报表。
       报表编译过程的主要目的是生成并装载含有所有报表表达式（ report expression ）的类的字节码。这个动态生成的类将会被用来在装填数据，并给所有报表表达式求值（ evaluate ）的时候使用。具体例子是，如果你用 IReport 生成一个报表名字叫 SimpleSheetTest ，它的 XML 设计文件名叫 SimpleSheetTest.jrxml ，同时和它在同一目录下 IReport 会自动生成一个文件名为 SimpleSheetTest.java ，里面主要是一些报表元素，如 Field ， Parameters ， Variables 的定义，以及一些求值表达式。当然，像上面提到的，这个文件在你直接使用 JasperReport API 的时候是看不到的，因为它是在执行期生成的一个 Class 。要想看到它的办法是：在 IDE （ JBuilder ， Eclipse ）中单步执行程序，在报表打印的阶段，你将能跟踪到这个类，它的名字就是 “ 你的报表名 .java” ，按上面的例子就是 SimpleSheetTest.java ，这和 IReport 是一致的。当然也可以像下面说的那样，到生成这个类的临时目录里找到它。
在这个类生成过程之前， JasperReport 引擎需要验证报表设计的一致性（ consistency ），哪怕存在一处验证检查失败都不会继续运行下面的工作。在下面的章节，我将会展示报表设计验证成功之后的状况。
对于这个包含了所有报表表达式（ report expressions ）的类的字节码，我们至少需要关心三个方面的内容：
临时工作目录（ temporary working l directory ）
Java 编译器的使用 l
Classpath l

       为了能够编译 Java 源文件，这个文件必须被创建并且被保存到磁盘上。 Java 编译过程的输出是一个 .class 文件，这个包含所有报表表达式的类在这个工作目录里被创建并编译，这也是为什么 JasperReport 需要访问这个临时目录的原因。当报表的编译过程结束之后，这些临时的类文件将被自动删除，而生成的字节码将保存在 net.sf.jasper.engine.JasperReport 对象中。如果需要的话，这个类可以将自己序列化（ serialized itself ）并保存到磁盘上。这就是 IReport 的做法。
       缺省情况下，这个临时工作目录就是启动 JVM 时的当前目录，这却取决于 JVM 的系统属性 user.dir 。通过更改系统属性 jasper.report.compile.temp ，用户可以很容易更改这个工作目录。在 Web 环境下，特别是当你不想让含有启动 Web Server 的批处理文件的目录和报表编译过程的临时工作目录混在一起的时候，修改这个属性就可以了。
       上面提到的第二个方面涉及用来编译报表表达式类的 Java 编译器。首先，报表引擎将试图使用 sun.tools.javac.Main 类来编译 Java 源文件。这个类包含在 tools.jar 中，当且仅当这个 jar 文件在 JDK 安装目录下的 bin/ 目录中，或在 classpath 中时， sun.tools.javac.Main 才能正常使用。
如果 JasperReport 不能成功装载 sun.tools.javac.Main 文件，程序将动态执行 java 编译过程，就像我们通常用命令行那样，使用 JDK 安装目录下的 bin/ 目录下的 javac.exe 。这就是为什么将 JDK 安装目录 /lib/ 下的 tools.jar 文件 copy 到 JasperReport 工程的 lib/ 目录下是一个可选的操作（ optional operation ）。如果 tools.jar 不在 classpath 中， JasperReport 将显示错误信息并继续上面提到的操作。
       当编译 Java 源文件的时候，最重要的事情莫过于 classpath 。如果 Java 编译器不能在指定的 classpath 中找到它试图编译的所有相关类的源文件，则整个过程将失败并停止，错误信息将在控制台显示出来。同样的事情也将发生在 JasperReport 试图编译报表表达式类的时候。所以，在 runtime 为编译过程提供正确的 classpath 是非常重要的。例如，我们我们需要确认在 classpath 中，我们提供了在报表表达式中可能用到的类（ custom class ）。
       在这个方面也有一个缺省的行为。如果没有为编译 report class 特殊指定 classpath ，引擎将会使用系统属性 java.class.path 的值来确定当前的 JVM classpath 。如果你指定了系统属性 jasper.reports.compile.class.path 的值，你可以用你定义的 classpath 来覆盖缺省行为。
       大多数情况下，编译一个 report 只需要简单的调用 JasperReport 类库中的 JasperCompileManager.compileReport(myXmlFileName); 即可。调用之后将生成编译好的 report design 并存储在 .jasper 文件中，这个文件将会保存在和提供 XML report design 文件相同的目录中。

3.3 Report Design 预览
       JasperReport 类库并没有提供高级的 GUI 工具来辅助进行设计工作。但是目前已经有至少 4 个 project 试图提供这样的工具。然而， JasperReport 本身提供了一个很有用的可视化组件来帮助报表设计者在编译的时候预览报表设计（其实不如直接用 IReport 方便）。
net.sf.jasper.view.JasperDesigner 是一个基于 Swing 的 Java 应用程序，它可以载入并显示 XML 形式或编译后的报表设计。尽管它不是一个复杂的 GUI 应用程序，缺乏像拖拽可视化报表元素这样的高级功能，但是它仍然是一个有用的工具（ instrument ）。所有 JasperReport 工程提供的例子都利用了这个报表查看器（ report viewer ）。
       如果你已经安装了 ANT （别告诉我你不知道什么是 ANT ），想要查看一个简单的报表设计（ JasperReport 工程所带例子），你只需要到相应的文件夹下输入如下命令：
〉 ant viewDesignXML 或者 〉 ant viewDesign
       如果你没安装 ANT ，要达到上面的效果就不是很容易，因为 JasperReport 本身需要一些其他辅助的 jar 包（在 JasperReport 安装目录 /lib 下），在运行的时候，你需要把这些 jar 包都包含到你的 classpath 里面，并且正确设计系统属性，如上面提到的 org.xml.sax.driver 。我可以展示一下在 windows 下的例子：
>java -classpath ./;../../../lib/commons-digester.jar;
../../../lib/commons-beanutils.jar;../../../lib/commons-collections.jar;
../../../lib/xerces.jar;../../../lib/jasperreports.jar
-Dorg.xml.sax.driver=org.apache.xerces.parsers.SAXParser
dori.jasper.view.JasperDesignViewer -XML -FFirstJasper.xml
很麻烦吧？还是赶快弄个 ANT 吧。下面是预览之后的结果（其实用 IReport 更好）