13.1报表引擎详解，API结构
BIRT包含几个引擎。一个引擎是一个提供一个特定领域的功能的一套Java API。例如，数据引擎包含管理数据的API，图表引擎包含生成一个图表的API。一般而言，BIRT包含四个引擎，报表设计引擎（design Engine），报表引擎(report engine)，图表引擎(chat engine)，数据引擎(data engine)。
a) 关于报表设计引擎
报表设计引擎包含验证一个报表设计文件的有效性和生成一个报表设计文件的API。报表设计引擎被BIRT Report Designer和任何定制的生成一个BIRT报表设计的Java应用程序所使用。生成引擎在创建一个报表文档时也使用报表设计引擎。报表设计引擎包含使用ROM技术规范来验证设计文件的元素和结构的有效性的API。
b) 关于报表引擎
报表引擎包含两部分：生成引擎和展示引擎。BIRT Report Viewer和定制的Java应用程序使用报表引擎来处理一个报表设计并按照设计中指定的格式生成报表。生成引擎包含读取和解释一个报表设计的API。生成引擎使用数据引擎来读取和转换来自由报表设计标识的数据源。生成引擎的输出是一个报表文档，这是一个报表产品中的一个中间文档。展示引擎处理由生成引擎创建的报表文档并按设计中指定的格式产生报表。和生成引擎一样，展示引擎也使用数据引擎。但是，在展示阶段，数据引擎从报表文件而不是数据源中获取数据。展示引擎它需要的任何一个报表发射器按照设计中指定的格式生成一个报表。BIRT有两个标准的发射器，HTML和PDF。BIRT也支持不是HTML和PDF格式的定制的发射器。图表报表项和定制的报表项扩展展示引擎来提供这些报表项的展示功能。
c) 关于图表引擎
图标引擎包含生成图表及将图表与来自数据源的数据关联起来的API。图表引擎的使用不仅限于BIRT应用程序。任何Java程序都可以使用图表引擎来创建和现实一个图表。BIRT Report Viewer 解释报表设计中的图标设计信息并使用图表引擎来生成图表。
d) 关于数据引擎
数据引擎包含获取和转换数据的API。当被生成引擎使用时，数据引擎直接从数据源中获取数据。当被展示引擎使用时，数据引擎从报表文档中获取数据。
1） 关于数据引擎组件
数据引擎包含两个主要组件：数据访问组件和数据转换组件。数据访问组件与ODA框架通信来获取数据。数据引擎的数据转换组件执行像排序、分组、累计和过滤来自数据访问组件的数据的操作。
2） 关于ODA框架
ODA框架管理ODA和本地驱动、装载驱动、打开连接并管理数据请求。ODA框架使用Eclipse Data Tools Platform项目来管理连接。ODA框架包含扩展点，籍此可以添加一个定制的ODA驱动。数据引擎扩展用于数据源的连接方法和驱动。如果有一个BIRT不支持的数据源就需要一个定制的ODA驱动。创建一个定制的ODA驱动时可能不仅需要扩展数据引擎而且还需要扩展BIRT Report Designer。如果数据源需要一个GUI组件来制定数据集，那么还需要一个BIRT Report Designer扩展。
应用开发者只需要了解公用的API，这些API包含在以下的几个包内：
a) org.eclipse.birt.report.model.api：这个包内包含了93个class，两个接口和一个exception，这个包是为那些想要定制report designer的开发者使用的,报表设计引擎包含这个包
b) org.eclipse.birt.report.engine.api：这个包包含了一个类，17个接口和四个exception，是给那些想要定制一个report generator的开发者使用的，报表引擎包含这个包
c) org.eclipse.birt.charthierarchy：这个包是给想定制一个chartgenerator的开发者使用的，图表引擎包含这个包
BIRT报表引擎（BIRT report engine）在几个环境提供了报表生成和翻译服务，包含在以下组件中：
a) Stand-alone engine：这个engine可以让开发者使用一个命令行程序来从一个report design文件(.rptdesign)中得到Html或PDF格式的report
b) BIRT report viewer：BIRT Report Designer使用它来预览report。这个程序是一个web程序，它运行在一个Eclipse内嵌的Tomcat中，这个Tomcat中有一个内嵌的report engine
c) Custom report designer with an embedded engine：一个定制的桌面报表应用集成BIRT report engine来预览报表
d) Web application that embeds the engine：一个类似于BIRT report viewer的Web程序，可以产生基于web的报表。
如下图所示：
另外，用户还能定制报表引擎，除了通常是集成到一个Web应用或者一个独立的Java应用程序外，定制的Java报表生成器质性和BIRT报表生成器相同的功能。和BIRT 报表浏览器Web应用一样，定制的Java报表生成器使用报表引擎的API来读取报表设计文件并生成一个报表。一个定制的业务逻辑来管理安全事宜、控制目录和确定输出的格式。
Report engine的核心engine运行并实施报表，而将其他的环境相关的任务留给运行该引擎的应用程序，比如：URLconstruction, image storage, and design file caching
BIRT report engine的API可以做以下几件事情：
a) 发现一组为报表定义的参数（包括动态参数和级联参数）
b) 获得参数的默认值
c) 产生任务（task）实施操作的应用
d）包含1到2个操作阶段（(RunTask 然后 Render Task 或者RunAndRenderTask)
d) 为报表产生图片或chart
e) 产生报表文档
f) 运行报表产生HTML或PDF格式的输出
EngineConfig –设置报表引擎可选的参数.
ReportEngine – 用于运行一到多个报表任务
IReportRunnable –用于打开报表设计文档，并把句柄传给报表任务
IReportDocument – 用于打开报表文档，并把句柄传给报表任务，同时包含很多方法用于获TOC,数据等等
HTMLRenderContext – 定义展示HTML的环境，例如设置HTML图片地址，事件处理
PDFRenderContext – 定义展示PDF的环境，例如设置字体的地址，事件处理
HTMLRenderOption – 用于设置html的可选选项，比如导出时的路径
报表设计引擎（Design Engine）需要完成的事情：
1、用于产生或者修改报表设计文档，报表模板文档，报表库文档
2、有时候报表引擎需要修改报表设计文档，这个时候就需要调用报表设计引擎
3、如果报表引擎在运行时，事件机制和脚本机制中本身就包含修改报表设计的代码，这个时候也要调用报表设计引擎
4、用于获取和设置报表参数
5、可以用于获取报表设计的种种属性和参数
用户还能定制报表设计器，一个定制的报表设计器是一个由Java开发人员创建的用来基于特定的需求生成一个格式良好的报表设计文件Java应用程序。定制的报表设计器不需要包含用户界面。定制的报表设计起的一个典型的例子是一个动态确定一个报表的目录、结构或者数据元的Java应用程序。定制的报表设计器使用和BIRTReport Designer相同的设计引擎API。
图表引擎用于产生图表，展示图表，修改图表，是一个比较独立的引擎。通常包含两个API包：
org.eclipse.birt.chart.model.*，org.eclipse.birt.chart.*
一般报表设计器在产生一份包含图表的设计文档的时候，都要调用图表的设计和展示引擎，但图表引擎不仅仅包含在报表设计器的类库中，报表在展示阶段如果包含图表，或者需要修改图表的时候，也会调用图表的引擎。
构建一个报表的必须工作：
创建和配置报表引擎
单个报表引擎可以通过创建多个设计器来生成多个报表。通过Platform.createFactoryObject()方法创建一个ReportEngine对象。设置BIRT目录，指向需要的plug-in和库。
打开报表文档（*.rptdesign 或 *.rptdocument）
通过ReportEngine对象的openReportDesign( )打开一个报表设计模版，参数是文件路径名或InputStream，返回一个IReportRunnable对象。
通过ReportEngine对象的openReportDocument( )打开一个报表文档，参数是文件路径名，返回一个IReportDocument对象。
连接数据源
通过创建数据连接或使用应用程序提供的连接为数据集提供数据源。
报表生成的准备工作
用一个IRenderOption对象设置输出格式，输出文件名，输出流或输出位置，和一些特定格式设置。HTMLRenderOption支持HTML格式的输出，输出PDF格式使用RenderOption
生成报表
使用IRunAndRenderTask对象生成IReportRunnable类型的报表，使用IRenderTask对象创建IReportDocument类型的报表。
也可以访问部署在应用程序服务器上的report viewer servlet来生成报表。
销毁引擎
当我们不再需要使用报表引擎时将它销毁。
可选的任务：
获取参数
如果报表中设置了参数，引擎要使用传入的参数生成报表，如果没有传入参数则使用默认值。
创建报表文档文件（*.rptdocument）
报表文档文件已二进制的形式存储的，如果应用程序使用报表设计文件，要通过IRunTask对象生成一个IReportDocument对象的报表文档。
从报表文档导出数据。
使用IDataExtractionTask对象在报表文档中导出一项或多项的值。
开发环境要求
把需要的类库都引入classpath或开发工具中。配置BIRT目录，目录中包含了从报表设计文件生成报表所需要的plug-in和类库。 BIRT的报表引擎包在他的ReportEngine子目录里提供了完整的BIRT home。如果你想动手修改BIRT源码的话，一定要保证源码的版本与BIRT home中的plug-in和类库的版本是一致的。
类库和plug-in
BIRT home的ReportEngine\lib子目录和ReportEngine\plugins中包含了报表应用程序需要的用到的类库和plug-in，你可以根据自己项目的情况删除掉不用的包。
jdbc驱动
BIRT home的plugins/org.eclipse.birt.report.data.oda.jdbc_...文件夹用于存放连接数据库所需要的驱动程序，你可以把需要的驱动程序包放到该目录下（引入classpath中好像是不起作用的…）
通过api修改报表设计模版
报表应用程序在生成报表前可以修改报表设计模版。如：添加删除数据项，更深入的定制报表等。DesignEngine API提供了修改设计模版（包括修改脚本）DesignEngine的主要接口在org.eclipse.birt.model.api包中。
下面给出一个简单的例子：
该报表的设计如下：
数据集上有事件处理绑定：
需要在报表的资源中导入事件处理包：
预览如下：
报表引擎的源码如下：
package REAPI;
import java.util.logging.Level;
import org.eclipse.birt.core.framework.Platform;
import org.eclipse.birt.report.engine.api.EXCELRenderOption;
import org.eclipse.birt.report.engine.api.EngineConfig;
import org.eclipse.birt.report.engine.api.EngineConstants;
import org.eclipse.birt.report.engine.api.EngineException;
import org.eclipse.birt.report.engine.api.HTMLRenderOption;
import org.eclipse.birt.report.engine.api.IReportEngine;
import org.eclipse.birt.report.engine.api.IReportEngineFactory;
import org.eclipse.birt.report.engine.api.IReportRunnable;
import org.eclipse.birt.report.engine.api.IRunAndRenderTask;
import org.eclipse.birt.report.engine.api.PDFRenderOption;
public class RunAndRenderTask {
public void runReport() throws EngineException
{
IRunAndRenderTask task=null;
IReportEngine engine=null;
EngineConfig config = null;
try{
//System.setProperty("java.io.tmpdir", "c:/temp/test/testsampledb");
config = new EngineConfig( );
config.setLogConfig("d:\\dwn.txt", Level.INFO);
config.getAppContext().put(EngineConstants.APPCONTEXT_CLASSLOADER_KEY, this.getClass().getClassLoader());
config.getAppContext().put(EngineConstants.WEBAPP_CLASSPATH_KEY, "d:\\eventjar.jar");
config.setBIRTHome("E:\\birt汉化包\\birt-runtime-3_7_2\\ReportEngine");
//config.setLogConfig(null, Level.FINEST);
Platform.startup( config );
IReportEngineFactory factory = (IReportEngineFactory) Platform
.createFactoryObject( IReportEngineFactory.EXTENSION_REPORT_ENGINE_FACTORY );
engine = factory.createReportEngine( config );
IReportRunnable design = null;
//Open the report design
design = engine.openReportDesign("d:\\dataseteventhandler.rptdesign");
task = engine.createRunAndRenderTask(design);
//task.setParameterValue("Top Count", (new Integer(5)));
task.validateParameters();
HTMLRenderOption options = new HTMLRenderOption();
options.setImageDirectory("d:\\");
options.setOutputFileName("d:\\eventhandlerjar.html");
options.setOutputFormat("html");
//PDFRenderOption options = new PDFRenderOption();
//options.setOutputFileName("d:\\topn.pdf");
//options.setSupportedImageFormats("PNG;GIF;JPG;BMP;SWF;SVG");
//options.setOutputFormat("pdf");
//EXCELRenderOption options = new EXCELRenderOption();
//options.setOutputFormat("xls");
//options.setOutputFileName("d:\\customers.xls");
//options.setWrappingText(true);
task.setRenderOption(options);
task.run();
task.close();
engine.destroy();
}catch( Exception ex){
ex.printStackTrace();
}
finally
{
if ( !task.getErrors( ).isEmpty( ) )
{
for ( Object e : task.getErrors( ) )
{
( (Exception) e ).printStackTrace( );
}
}
Platform.shutdown( );
System.out.println("Finished");
}
}
/**
* @param args
*/
public static void main(String[] args) {
try
{
RunAndRenderTask ex = new RunAndRenderTask( );
ex.runReport();
}
catch ( Exception e )
{
e.printStackTrace();
}
}
}运行，会看到D盘产生eventhandlerjar.html文档，查看如下：
下面详细介绍如何构建一个报表应用程序
org.eclipse.birt.report.engine.api包含了用来生成报表的类和接口，其中主要的类和接口有 ReportEngine, EngineConfig, IReportRunnable, IRenderOption以及它的子类，IEngineTask以及它的子类。
在Eclipse提供的Birt集成开发工具的帮助文档里有详细的api参考，不过有点简略。
一、创建报表引擎
报表引擎是ReportEngine类的一个实例，是任何报表应用程序的关键部分。首先用EngineConfig对象来为ReportEngine准备参数，然后用BIRT报表引擎工厂来创建引擎。创建一个配置对象：
EngineConfig config = new EngineConfig();
设置BIRT home
BIRT home就是BIRT plug-ins和类库的路径，它是报表引擎的关键参数。
你可以用下面的方式进行BIRT home设置：
■对于独立的应用程序可以吐过下面的方式设置：
config.setBIRTHome ( "C:/birt-runtime-<version>/ReportEngine" );
■也可以再你自己的环境变量中设置：
set BIRT_HOME="C:\birt-runtime-<version>\ReportEngine"
SET CLASSPATH=%BIRT_HOME%\<required library 1>;
■ 在Web应用程序里要首先取得绝对路径让后设置到config
config.setBIRTHome( servletContext.getRealPath( "/WEB-INF" ) );
■在WAR 文件的Web应用程序中可以使用PlatformServletContext.
config.setBIRTHome( "" );
■ 在Eclipse中,通过VM运行参数设置
-DBIRT_HOME="C:\birt-runtime-<version>\ReportEngine"
设置引擎的其他参数
通过配置对象进行配置的参数还有日志，OSGI(Open Services Gateway Initiative)，平台上下文，资源文件，临时资源文件，脚本等，这些都是可选的参数，详细信息可以参考EngineConfig的API。
不同运行环境的差异
应用程序是独立运行的还是以web形式运行的决定了平台上下文和HTML发射器（emitter，不知道是不是生成器更合适一点）的配置的不同。 平台上下文提供了报表引擎连接plug-in的机制，默认使用独立运行的方式。HTML发射器提供了处理图片和处理超链接和标签事件的功能。
设置上下文
BIRT是一个基于Eclipse的应用程序，因此它使用OSGI平台来启动插件来产生报表和设计引擎。BIRT需要的plug-in存储在 BIRT主目录下，通过platform context进行配置，它实现了接口org.eclipse.birt.core.framework.IPlatformContext。 context作为EngineConfig的一个参数通过setEngineContext( )进行设置。
BIRT中提供了两个IPlatformContext的实现：
PlatformFileContext通过文件系统目录配置context，用于独立运行的应用程序和web应用程序中部署的基于系统文件目录的BIRT应用程序。
IPlatformContext context = new PlatformFileContext( );
config.setEngineContext( context );
对于web应用上部署的BIRT应用程序，使用PlatformServletContext。它使用基于资源连接的J2EE ServletContext来定位BIRT plug-in。它默认使用“/WEB-INF/platform/”
IPlatformContext context =
new PlatformServletContext(request.getSession().getServletContext());
config.setPlatformContext(context);
如果默认的BIRT提供的实现不能满足你的要求，可以定义自己的实现。
设置HTML emitter
当使用HTML格式生成一个报表，引擎通过一个HTMLRenderOption对象来定义如何处理HTML emitter使用的资源（图像滤镜，图像元素，图表，书签等）。桌面应用程序和web应用程序用来处理图像的方法是不同的。使用HTML emitter首先要创建HTMLRenderOption，使用方法：
HTMLRenderOption ho = new HTMLRenderOption( );
ho.setImageHandler( new HTMLCompleteImageHandler( ));
config.setEmitterConfiguration( RenderOptionBase.OUTPUT_FORMAT_HTML, ho );
创建引擎时可以不必设置HTML emitter，你可以需要生成HTML报表时再去进行配置。
IHTMLImageHandler是用来处理图像的接口，BIRT提供了两个IHTMLImageHandler的实现：
HTMLCompleteImageHander可以将图像保存到文件目录。它首先使用HTMLRenderOption设置的图像目录，如果没 有则使用EngineConfig.setTempDir( )设置的临时文件目录，如果还没有则使用java.io.tmpdir定义的系统临时文件目录。生成的HTML中引用的图像也是引擎创建的。
HTMLServerImageHandler应用在web应用程序中，它将图像文件保存在HTMLRenderOption设置的图像文目录 中。HTML的图像的src指向生成的图像文件的路径也是在HTMLRenderOption中配置的。这样报表引擎就可以在本地文件中创建图像文件，并 且通过URL共享。
ho.setImageDirectory("output/image");
ho.setBaseImageURL("http://myhost/prependme?image=");
如果IHTMLImageHandler得实现不能满足你的要求，你可以开发自己的实现。或者继承并重写已有的image handler。HTMLCompleteImageHander已经提供了足够的图像文件接口因此一般情况下不需要我们进行扩展。
启动平台
设置完成平台上下文环境，你可以通过org.eclipse.birt.core.framework.Platform类启动一个平台。
最低0.47元/天 解锁文章
3万+
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
