如何构建Birt报表应用程序？

BIRT(一)安装Birt报表工具

 

商业智能(十八) 安装BIRT 发现自己还上了javaeye的头版了，也算是灌水灌出了自己的特色了吧, 希望自己还是加紧时间学习，好为大家提供更多更好的优质纯净水. 安装Birt 其实非常的简单.只需要下载Birt-Runtime-version 文件就可以了.下载解压后，其中有一个目录是ReportEngine 的目录，所有的Birt 能够运行都需要这个目录下的程序. 另外一个就是WebViewerExample 目录，这是一个eclipse 的sample ,直接把它放到tomcat webapps目录下就可以了. 运行成功后应该直接有 BIRT viewer has been installed 的提示,下面有个 View Example 的链接.它会调用一个Servlet 处理一个test.rptdesing 的模板并且接受一个默认的参数“my parameter" , 你可以之后改变这个参数. test.rptdesign 文件在WebViewerExample 下面，另外还有一个test1.rptdesing 文件把你的浏览器指向 http://localhost:8080/WebViewerExample/frameset?__report=test1.rptdesign 会弹出来一个parameter 对话框,随便输入两个1 ， 後然运行出来的报表是个非常简单的报表. 这两个报表都是只用visual design 做出来的.算是最基本的入门了. 再来看一下这个sample 的目录结构，在WebViewerExample下，有6个目录，一个index.jsp 文件和两个birt 模板文件. 其中documents 目录，logs 目录 ， scriptlib 目录是在web.xml 里面定义的，你可以定义到其他地方,里面还有其他的定义，都有注释。 在WEB-INF 目录下，有lib ， platform ,tlds 目录，web.xml文件 和 server-config.wsdd ，这是一个标准的BIRT 安装目录，platform 下放的是从birt-runtime-version 的reportengine 下copy 过来的. 另外还有一个viewer.properties 文件，里面定义了可以输出的文件格式，现在一共支持6种：html , pdf , postscript , doc , xls (也就是csv,或者说是excel） ,ppt 如果你需要Birt 支持excel 或者 word 格式在这里定义就好了. # [EXTENSION SETTING] viewer.extension.html=html viewer.extension.pdf=pdf viewer.extension.postscript=ps viewer.extension.doc=doc viewer.extension.xls_prototype=xls viewer.extension.ppt=ppt # [OUTPUT FORMAT LABEL NAME] viewer.label.html=HTML viewer.label.pdf=PDF viewer.label.postscript=Postscript viewer.label.doc=Word viewer.label.xls_prototype=Excel viewer.label.ppt=Powerpoint # [CSV SEPARATOR] viewer.sep.0=, viewer.sep.1=; viewer.sep.2=: viewer.sep.3=| viewer.sep.4=\t 后面的CSV SEPARATOR 是支持你导出数据用的. 注意你的lib 都已经正确放置了先. 下一篇是介绍用最简单的Design API 来设计一个模板.

 

如何构建一个Birt报表应用程序(一)

 

最近研究birt，资料太少，但是无意间找到了birt的官方教程，比较不错，闲来翻译整理了一些贴出来和大家分享。 构建一个报表的必须工作： 创建和配置报表引擎 单个报表引擎可以通过创建多个设计器来生成多个报表。通过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修改报表设计模版 报表应用程序在生成报表前可以修改报表设计模版。如：添加删除数据项，更深入的定制报表等。Design Engine API提供了修改设计模版（包括修改脚本）Design Engine的主要接口在org.eclipse.birt.model.api包中。

 

如何构建一个Birt报表应用程序(二)

 

下面详细介绍如何构建一个报表应用程序

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已经提供了足够的图像文件接口因此一般情况下不需要我们进行扩展。

 

如何构建一个Birt报表应用程序(三)

 

启动平台 设置完成平台上下文环境，你可以通过org.eclipse.birt.core.framework.Platform类启动一个平台。 Platform是一个Eclipse OSGI平台的包装类，提供一个同步的静态方法startup( )用来启动平台，该操作的开销比较大，因此你的应用程序最好只调用一次。平台使用结束后调用Platform.shutdown( )关闭。如果你是在Web应用程序里使用报表引擎，请在servlet的init方法中调用startup方法或者在第一次处理用到平台的请求时。最好启 动平台的代码封装为一个单例。如果你使用Birt提供的Web Viewer或使用基于Eclipse的富客户端程序（RCP），你就不需要启动平台，因为应用程序已经自己启动了OSGi。 创建报表引擎 BIRT提供一个工厂服务用于创建ReportEngine对象。Platform.createFactoryObject( )创建一个实现了org.eclipse.birt.report.engine.api.IReportEngineFactory接口的工厂对象。该 方法需要一个PlatformConfig对象。因为EngineConfig是继承自PlatformConfig，你可以使用 EngineConfig来创建一个工厂。最后通过IReportEngineFactory.createReportEngine( )方法和刚才使用的EngineConfig对象创建报表引擎。 实例 在独立运行的应用程序中创建一个报表引擎，如下： Java代码// Create an EngineConfig object.   EngineConfig config = new EngineConfig( );   // Set up the path to your BIRT home directory.   config.setBIRTHome( "C:/Program Files/birt-runtime-2_2_1/ReportEngine" );   // Explicitly set up the stand-alone application   IPlatformContext context = new PlatformFileContext( );   config.setEngineContext( context );   // Start the platform for a non-RCP application.   Platform.startup( config );   IReportEngineFactory factory = ( IReportEngineFactory ) Platform.createFactoryObject   ( IReportEngineFactory.EXTENSION_REPORT_ENGINE_FACTORY );   // Set up writing images or charts embedded in HTML output.   HTMLRenderOption ho = new HTMLRenderOption( );   ho.setImageHandler( new HTMLCompleteImageHandler( ));   config.setEmitterConfiguration( RenderOptionBase.OUTPUT_FORMAT_HTML, ho );   // Create the engine.   IReportEngine engine = factory.createReportEngine( config );   // Create an EngineConfig object. EngineConfig config = new EngineConfig( ); // Set up the path to your BIRT home directory. config.setBIRTHome( "C:/Program Files/birt-runtime-2_2_1/ReportEngine" ); // Explicitly set up the stand-alone application IPlatformContext context = new PlatformFileContext( ); config.setEngineContext( context ); // Start the platform for a non-RCP application. Platform.startup( config ); IReportEngineFactory factory = ( IReportEngineFactory ) Platform.createFactoryObject ( IReportEngineFactory.EXTENSION_REPORT_ENGINE_FACTORY ); // Set up writing images or charts embedded in HTML output. HTMLRenderOption ho = new HTMLRenderOption( ); ho.setImageHandler( new HTMLCompleteImageHandler( )); config.setEmitterConfiguration( RenderOptionBase.OUTPUT_FORMAT_HTML, ho ); // Create the engine. IReportEngine engine = factory.createReportEngine( config ); 说明：上面一个在windows系统上的独立运行的应用程序，它使用BIRT run-time提供的BIRT home，报表输出格式是HTML。 在Web应用程序上创建一个报表引擎，如下： Java代码 // Example class to create the report engine   public class BirtEngine {   private static IReportEngine birtEngine = null;   public static synchronized IReportEngine getBirtEngine( ServletContext sc ) {   if (birtEngine == null) {   EngineConfig config = new EngineConfig( );   config.setBIRTHome( "" );   IPlatformContext context = new PlatformServletContext( sc );   config.setPlatformContext( context );   try{   Platform.startup( config );   IReportEngineFactory factory = ( IReportEngineFactory )   Platform.createFactoryObject(    IReportEngineFactory.EXTENSION_REPORT_ENGINE_FACTORY );   birtEngine = factory.createReportEngine( config );   }catch ( Exception e ) { e.printStackTrace( ); }   }   return birtEngine;   }   }   // Example class to create the report engine public class BirtEngine { private static IReportEngine birtEngine = null; public static synchronized IReportEngine getBirtEngine( ServletContext sc ) { if (birtEngine == null) { EngineConfig config = new EngineConfig( ); config.setBIRTHome( "" ); IPlatformContext context = new PlatformServletContext( sc ); config.setPlatformContext( context ); try{ Platform.startup( config ); IReportEngineFactory factory = ( IReportEngineFactory ) Platform.createFactoryObject(  IReportEngineFactory.EXTENSION_REPORT_ENGINE_FACTORY ); birtEngine = factory.createReportEngine( config ); }catch ( Exception e ) { e.printStackTrace( ); } } return birtEngine; } } 说明：上面的代码是一个用单例模式实现的报表引擎的创建的类，EngineConfig配置了两个参数 BIRTHome和PlatformContext。 在上面例子的基础上进行更多的配置 Java代码 // In a different class, get the report engine   reportEngine = BirtEngine.getBirtEngine( request.getSession( ).getServletContext( ));   // Set up the engine   EngineConfig config = reportEngine.getConfig( );   HTMLRenderOption ho = new HTMLRenderOption( );   ho.setImageHandler( new HTMLServerImageHandler( ));   ho.setImageDirectory("output/image");   ho.setBaseImageURL("http://myhost/prependme?image=");   config.setEmitterConfiguration( RenderOptionBase.OUTPUT_FORMAT_HTML, ho );   // In a different class, get the report engine reportEngine = BirtEngine.getBirtEngine( request.getSession( ).getServletContext( )); // Set up the engine EngineConfig config = reportEngine.getConfig( ); HTMLRenderOption ho = new HTMLRenderOption( ); ho.setImageHandler( new HTMLServerImageHandler( )); ho.setImageDirectory("output/image"); ho.setBaseImageURL("http://myhost/prependme?image="); config.setEmitterConfiguration( RenderOptionBase.OUTPUT_FORMAT_HTML, ho ); 使用日志环境调试应用程序 BIRT报表引擎使用java.util.logging的Logger和Level类来处理引擎平台的日志信息。你在Eclipse中运行一个 应用程序运行信息默认的是显示在控制台上的。在非Eclipse环境中运行信息的输出就要有运行环境决定了。默认的日志级别是Level.INFO，你可 以通过改变日志级别来减少系统内部的日志信息。 使用EngineConfig.setLogConfig( )可以让日志输出到磁盘文件中。该方法需要两个参数，第一个参数是日志输出的目录，BIRT 引擎会在指定目录中创建一个名称格式为ReportEngine _YYYY_MM_DD_hh_mm_ss.log的日志文件。第二个参数是日志信息的最低级别，级别越高输出的日志信息越少。ReportEngine.changeLogLevel( )方法可以让你修改日志级别。 如何使用BIRT日志 如下： Java代码 // Set up the location and level of the logging output.   config.setLogConfig( "C:/Temp", Level.ERROR );   engine.changeLogLevel( Level.INFO );

 

 

如何构建一个Birt报表应用程序(四)

 

二、打开报表资源文件 BIRT引擎可以通过报表设计文件和报表文档两种方式生成报表，引擎还可以从报表设计文件生成报表文档。 你可以通过openReportDesign( )方法打开一个报表设计文件文件，他实例化一个IReportRunnable对象，支持文件路径或一个输入流。 你可以通过openReportDocument( )方法打开一个报表设计文件文件，他实例化一个IReportDocument对象，也支持文件路径或一个输入流。 使用这些方法要处理EngineException。 理解IReportRunnable对象 IReportRunnable对象提供到报表设计的基本属性的直接接口。报表设计属性的属性名是静态字符串变量，如：IReportRunnable.AUTHOR。可以通过getProperty( )方法去访问这些属性。下面的代码展示了如何连接到报表设计文件： Java代码 String designName = "./SimpleReport.rptdesign";   IReportRunnable runnable = null;   try {   runnable = engine.openReportDesign( designName );   }catch ( EngineException e ) {   System.err.println( "Design " + designName + " not found!" );   engine.destroy( );   System.exit( -1 );   }   // Get the value of a simple property.   String author = ( String ) runnable.getProperty( IReportRunnable.AUTHOR );   String designName = "./SimpleReport.rptdesign"; IReportRunnable runnable = null; try { runnable = engine.openReportDesign( designName ); }catch ( EngineException e ) { System.err.println( "Design " + designName + " not found!" ); engine.destroy( ); System.exit( -1 ); } // Get the value of a simple property. String author = ( String ) runnable.getProperty( IReportRunnable.AUTHOR ); 理解IReportDocument对象 IReportDocument对象提供了访问报表数据和报表结构的接口，它提供了方法来访问表格内容，书签，页面信息等。 使用findTOC( )访问表格内容，该方法使用TOCNode参数返回一个TOCNode对象。使用null参数就可以访问根表格。 调用getTOCTree( )返回一个ITOCTree对象获取更详细的Table信息。调用TOCNode.getChildren( )方法获取table的子节点，返回值是一个TOCNode对象列表。 通过TOCNode对象你可以得到表格中的内容和书签。你可以使用书签对象作为参数调用getPageNumber( )方法获取书签连接的页面的页数。通过这些信息你可以在以格式化的报表中显示特定的页面。 下面的代码展示了如何打开一个报表文档，并在页面上查找元素： Java代码 String dName = "./SimpleReport.rptdocument";   IReportDocument doc = null;   try {   doc = engine.openReportDocument( dName );    } catch ( EngineException e ) {   System.err.println( "Document " + dName + " not found!" );   engine.destroy( );   System.exit( -1 );   }   // Get the root of the table of contents.   TOCNode td = doc.findTOC( null );   java.util.List children = td.getChildren( );   long pNumber;   // Loop through the top level table of contents entries.   if ( children != null && children.size( ) > 0 ) {   for ( int i = 0; i < children.size( ); i++ ) {   // Find the required table of contents entry.   TOCNode child = ( TOCNode ) children.get( i );   if ( child.getDisplayString( ).equals( "103" ) ) {   // Get the number of the page that contains the data.   pNumber = doc.getPageNumber( child.getBookmark( ) );   System.out.println( "Page to print is " + pNumber );   }   }   }

 

 

如何构建一个Birt报表应用程序(五)

 

三、用程序处理报表参数 参数是报表生成之前想报表设计文件输入的报表元素。报表的应用程序可以访问报表的参数的属性，最常用的属性是name和value，你可以使用参数名或通用编码来获取参数。 为报表设计创建一个参数定义任务 一个IGetParameterDefinitionTask对象提供链接到报表设计所有参数的接口。通过调用 ReportEngine.createGetParameterDefinitionTask( )创建一个参数定义对象，使用结束后调用他的close方法关闭。 测试报表设计是否有参数 IGetParameterDefinitionTask.getParameterDefns( )可以测试报表设计是否有参数，它返回一个参数集合，调用集合的isEmpty( )方法可以测试集合中是否有元素。 获取报表设计的参数 通过IGetParameterDefinitionTask.getParameterDefn( )方法获取一个已知名字的参数，它返回一个IParameterDefnBase类型对象，也可以调用getParameterDefns( )方法返回一个参数集合。 getParameterDefns( )需要一个boolean参数，如果为false返回一个未分组的参数集合，如果为true返回报表设计中定义的参数组。 调用IParameterDefnBase.getParameterType( )可以检验参数是否是一个组。如果是一个组则返回IParameterDefnBase.PARAMETER_GROUP，如果是一个级联参数组则返回 IParameterDefnBase.CASCADING_PARAMETER_GROUP。为获取一组报表参数，使用方法 IParameterGroupDefn.getContents( )，它返回一个数据类型是IScalarParameterDefn的ArrayList对象。 获取报表参数的默认值 这个任务是可选的。调用IGetParameterDefinitionTask.getDefaultValue( )获取一个已知参数的默认值，它返回的是一个Object。可以通过调用IScalarParameterDefn.getDataType( )来获取Object的有效类型，它返回一个IScalarParameterDefn定义的int类型的静态变量。调用 IGetParameterDefinitionTask.getDefaultValues( )来获取报表设计的所有参数的默认值，它返回一个HashMap对象存储了从参数名到默认值的映射。 使用常量列表提供的效值 许多报表参数只接受常量列表的值，这些值可能是静态常量，也可能是数据库里查出来的数据list。使用 IGetParameterDefinitionTask.getSelectionList( )可以返回参数所能接受的参数（IParameterSelectionChoice）的集合，如果集合为null，则可以接受任何值。 IParameterSelectionChoice的getLabel( )方法返回现实的文本，getValue( )返回值。 获取每个报表参数的属性 这个任务是可选的。使用IScalarParameterDefn的方法可以获取表参数的属性。应用程序使用属性生成用户自定义接口。例如，获取参数的数据类型使用getDataType( )方法。 为参数设置值 调用IGetParameterDefinitionTask.setParameterValue( )为参数设置值。如果你是通过应用程为日期数值等参数返回一个字符串，要把他们转化成和本地无关的格式。调用方法 ReportParameterConverter.parse( )方法可以完成这项工作。getParameterValues( )方法返回一个HashMap包含了已经设置的所有参数。 实例 下面的代码展示了如何设置一个已知参数名的参数值： Java代码 // Create a parameter definition task.   IGetParameterDefinitionTask task = engine.createGetParameterDefinitionTask( runnable );   // Instantiate a scalar parameter.   IScalarParameterDefn param = (IScalarParameterDefn)    task.getParameterDefn( "customerID" );   // Get the default value of the parameter. In this case,    // the data type of the parameter, customerID, is Double.   int customerID = ((Double) task.getDefaultValue( param )).intValue( );   // Get a value for the parameter. This example assumes that    // this step creates a correctly typed object, inputValue.   // Set the value of the parameter.   task.setParameterValue( "customerID", inputValue );   // Get the values set by the application for all parameters.   HashMap parameterValues = task.getParameterValues( );   // Close the parameter definition task.   task.close( );   // Create a parameter definition task. IGetParameterDefinitionTask task = engine.createGetParameterDefinitionTask( runnable ); // Instantiate a scalar parameter. IScalarParameterDefn param = (IScalarParameterDefn)  task.getParameterDefn( "customerID" ); // Get the default value of the parameter. In this case,  // the data type of the parameter, customerID, is Double. int customerID = ((Double) task.getDefaultValue( param )).intValue( ); // Get a value for the parameter. This example assumes that  // this step creates a correctly typed object, inputValue. // Set the value of the parameter. task.setParameterValue( "customerID", inputValue ); // Get the values set by the application for all parameters. HashMap parameterValues = task.getParameterValues( ); // Close the parameter definition task. task.close( ); 下面的代码展示了如何使用报表参数集合，例子中使用ReportParameterConverter将字符串转化成用户接口接受的参数格式。 Java代码 // Create a parameter definition task.   IGetParameterDefinitionTask task = engine.createGetParameterDefinitionTask( runnable );   // Create a collection of the parameters in the report design.   Collection params = task.getParameterDefns( false );   // Get the default values of the parameters.   HashMap parameterValues = task.getDefaultValues( );   // Get values for the parameters. Later code in this example   // assumes that this step creates a HashMap object,   // inputValues. The keys in the HashMap are the parameter   // names and the values are those that the user provided.   // Iterate through the report parameters, setting the values    // in standard locale-independent format.   Iterator iterOuter = params.iterator( );   ReportParameterConverter cfgConverter =           new ReportParameterConverter( "", Locale.getDefault() );   while ( iterOuter.hasNext( ) ) {   IParameterDefnBase param = (IParameterDefnBase) iterOuter.next( );   String value = (String) inputValues.get( param.getName( ));   if ( value != null ) {   parameterValues.put( param.getName( ),    cfgConverter.parse( value, param.getDataType( ) ) );   }   }   // Close the parameter definition task.   task.close( );   // Create a parameter definition task. IGetParameterDefinitionTask task = engine.createGetParameterDefinitionTask( runnable ); // Create a collection of the parameters in the report design. Collection params = task.getParameterDefns( false ); // Get the default values of the parameters. HashMap parameterValues = task.getDefaultValues( ); // Get values for the parameters. Later code in this example // assumes that this step creates a HashMap object, // inputValues. The keys in the HashMap are the parameter // names and the values are those that the user provided. // Iterate through the report parameters, setting the values  // in standard locale-independent format. Iterator iterOuter = params.iterator( ); ReportParameterConverter cfgConverter =         new ReportParameterConverter( "", Locale.getDefault() ); while ( iterOuter.hasNext( ) ) { IParameterDefnBase param = (IParameterDefnBase) iterOuter.next( ); String value = (String) inputValues.get( param.getName( )); if ( value != null ) { parameterValues.put( param.getName( ),  cfgConverter.parse( value, param.getDataType( ) ) ); } } // Close the parameter definition task. task.close( ); 使用级联参数 级联参数参数是一组可供用户选择的参数值的集合。第一个参数的选择会影响到第二个参数中的值。参数使用一个或多个查询来从数据集把数据展示给用户。参数定义任务根据前面的选择以行为单位过滤参数组中的数据。 使用报表引擎实现级联参数，要进行如下工作： ■使用IGetParameterDefinitionTask.evaluateQuery( )方法为级联参数准备数据，它需要参数group的名字作为参数。 ■调用IGetParameterDefinitionTask.getSelectionListForCascadingGroup( )获取参数组的第一个参数的值，它需要两个参数，参数名和对象数组，对第一个参数来说这个数组是空的。该方法返回一个 IParameterSelectionChoice集合。 ■ 再次调用getSelectionListForCascadingGroup( )方法获取后面的参数，这次Object[ ]中放的是前面获取的参数值。 下面的代码展示了如何通过查询实现级联参数： Java代码 // Create a grouped collection of the design’s parameters.   Collection params = task.getParameterDefns( true );   // Iterate through the parameters to find the cascading group.   Iterator iter = params.iterator( );   while ( iter.hasNext( ) ) {   IParameterDefnBase param = (IParameterDefnBase) iter.next();   if ( param.getParameterType() ==    IParameterDefnBase.CASCADING_PARAMETER_GROUP ) {   ICascadingParameterGroup group = (ICascadingParameterGroup) param;   Iterator i2 = group.getContents( ).iterator( );   // Run the query for the cascading parameters.   task.evaluateQuery( group.getName() );   Object[ ] userValues = new Object[group.getContents( ).size( )];   // Get the report parameters in the cascading group.   int i = 0;   while ( i2.hasNext( ) ) {   IScalarParameterDefn member = (IScalarParameterDefn) i2.next( );   // Get the values for the parameter.   Object[ ] setValues = new Object[i];   if ( i > 0 )  System.arraycopy( userValues, 0, setValues, 0, i );   Collection c = task.getSelectionListForCascadingGroup(      group.getName(),setValues );   // Iterate through the values for the parameter.   Iterator i3 = c.iterator();   while ( i3.hasNext( ) ) {   IParameterSelectionChoice s =    ( IParameterSelectionChoice ) i3.next( );   String choiceValue = s.getValue( );   String choiceLabel = s.getLabel( );   }   // Get the value for the parameter from the list of   // choices. This example does not provide the code for   // this task.   userValues[i] = inputChoiceValue;   i++;   }   }   }

 

 

如何构建一个Birt报表应用程序(六)

 

四、报表生成的准备工作 BIRT支持HTML, Adobe PDF, Adobe PostScript (PS), Microsoft Excel (XLS), Microsoft PowerPoint (PPT)和 Microsoft Word (DOC) 格式的报表生成器。你也可以通过扩展支持自定义的格式。 有三个task类用来支持从源文件生成报表，就是： ■ IRunAndRenderTask. 通过运行报表设计文件直接生成目标格式的报表。调用方法ReportEngine.createRunAndRenderTask( )可以创建这个对象。 ■ IRunTask. 通过报表设计文件生成报表文档，ReportEngine.createRunTask( )方法可以创建这个对象。 ■ IRenderTask. 通过对报表文档中的内容进行格式化生成一个完整的报表或一个页面集。ReportEngine. createRenderTask( )方法返回该对象的一个实例。 每一个任务都可以使用多个报表文件，任务结束后都要调用close方法关闭。 为运行报表设计文件准备参数 IRunAndRenderTask 和 IRunTask对象允许设置报表参数。调用setParameterValues( )方法，通过传入一个参数的HashMap设置所有的参数，设置单个参数可以使用setParameterValue( )方法。 添加到报表引擎的类路径 一些报表设计需要扩展的java类，BIRT报表引擎通过使用环境变量信息定位类。通过动态设置应用程序上下文信息或引擎配置对象也可以配置java类的位置。使用EngineConstants中的常量来配置这些参数。 使用EngineTask对象和EngineConfig对象可以设置应用程序上下文，如下： Java代码 configOrTask.getAppContext( ).put(            EngineConstants.APPCONTEXT_CLASSLOADER_KEY,            MyClass.class.getClassLoader( ));   configOrTask.getAppContext( ).put(          EngineConstants.APPCONTEXT_CLASSLOADER_KEY,          MyClass.class.getClassLoader( )); 使用EngineConfig对象设置CLASSPATH，如下： Java代码 config.setProperty( EngineConstants.WEBAPP_CLASSPATH_KEY,       "c:/myjars/jar1.jar;c:/myclasses" );   config.setProperty( EngineConstants.WEBAPP_CLASSPATH_KEY,     "c:/myjars/jar1.jar;c:/myclasses" ); 使用Java System类设置CLASSPATH，如下： Java代码 System.setProperty(EngineConstants.WEBAPP_CLASSPATH_KEY,         "c:/myjars/jar1.jar;c:/myclasses" );   System.setProperty(EngineConstants.WEBAPP_CLASSPATH_KEY,         "c:/myjars/jar1.jar;c:/myclasses" ); BIRT按下面的顺序来查找扩展类： ■ 报表引擎plug-in的CLASSPATH ■ 上下文环境中定义的EngineConstants.APPCONTEXT_CLASSLOADER_KEY ■Java System 类或EngineConfig 中定义的EngineConstants.WEBAPP_CLASSPATH_KEY. ■Java System 类或EngineConfig 中定义的EngineConstants. PROJECT _CLASSPATH_KEY. ■Java System 类或EngineConfig 中定义的 EngineConstants. WORKSPACE _CLASSPATH_KEY. ■ 报表设计中引入的JAR文件 为报表设计提供外部对象 BIRT支持把以前实例化的对象拿过来重用。调用报表引擎前你要在应用程序中持有这个已经在内存中存在的对象。如果在脚本环境中使用，你传递对象给引擎后，脚本可以通过对象名在必要的是后获取对象。 可以通过EngineConfig或task得上下文环境为引擎提供对象。如下： Java代码 MyObject mo = new MyObject( );   config = new EngineConfig( );   // Get the application context from the config or the task   HashMap hm = config.getAppContext( );   //HashMap hm = task.getAppContext( );   hm.put( "MyCreatedObject", mo );   config.setAppContext( hm );   // To refer to this object in a BIRT script   // or expression, use MyCreatedObject.myMethod()

 

 

如何构建一个Birt报表应用程序(七)

 

设置rendering选项 按指定格式输出报表前要先设置报表输出选项。必须设置一个文件名或输出流用来输出报表，其他的设置都是可选的如是否创建一个可嵌入的HTML。 BIRT支持可嵌入和非可嵌入两种HTML，可嵌入HTML可以被嵌入其他的web页面，不包含头信息<body> 和<html>表签。 应用程序通过rendering options对象设置输出选项，指定格式的rendering options类实现了IRenderOption接口，并且继承了RenderOption类。HTMLRenderOption用来设置HTML输出 选项，PDFRenderOption用来设置PDF格式输出选项。其他的格式都使用RenderOption。 常用的设置有超连接的ＵＲＬ，事件处理器，图像处理器，输出格式，支持的图片输出格式，还可以设置输出到数据流还是文件。 设置HTML rendering选项 生成一个使用了图片的HTML报表，必须进行更多的配置。HTMLRenderOption提供了许多方式去自定义HTML的生产。下面是一些常用的选项： ■ 图像路径，生成HTML需要的图像（图片，动态生成的图表等）的路径通过调用方法HTMLRenderOption.setImageDirectory( )进行设置。 ■ 基本图像URL，在Web应用程序开发时，浏览器要引用到图像所要使用的URL路径前缀。通过HTMLRenderOption.setBaseImageURL( )进行设置。 ■ 图像处理器，使用HTMLRenderOption.setImageHandler( ) 进行设置 ■ 可嵌入的HTML，调用HTMLRenderOption.setEmbeddable( )。 ■ 从左到右的生成方式，调用HTMLRenderOption.setHtmlRtLFlag( )设置。 ■ 标题标签，调用HTMLRenderOption.setHtmlTitle( )设置，该标签将显示在浏览器的标签页上。 ■ 主页面内容，通过主页面可以设置页面大小、页眉、页脚等。如果不想让主页面的设置影响HTML的生成，可以调用HTMLRenderOption.setMasterPageContent( )设置。 ■ 浮动的页脚，主页面的页脚默认直接显示在内容的下方。传一个boolean值false给方法 HTMLRenderOption.setPageFooterFloatFlag( )，强制页脚在页面底部的固定位置显示。这个设置将在生成的HTML中添加一个固定高度的DIV。 ■主页的页边距，HTMLRenderOption.setOutputMasterPageMargins( )设置主页的页边距是否影响到HTML页面。 ■ HTML分页，生成HTML时也支持分页。设置HTMLRenderOption.setHtmlPagination( )可以让HTML页面支持分页。 下面的实例展示了在IRunAndRenderTask对象上使用rendering选项： Java代码 // Create a run and render task object.   IRunAndRenderTask task = engine.createRunAndRenderTask( runnable );   // Set values for all parameters in a HashMap, parameterValues   task.setParameterValues( parameterValues );   // Validate parameter values.   boolean parametersAreGood = task.validateParameters( );   // Set the name of an output file.   HTMLRenderOption options = new HTMLRenderOption( );   String output = name.replaceFirst( ".rptdesign", ".html" );   options.setOutputFileName( output );   options.setImageDirectory( "image" );   options.setHtmlRtLFlag( true );   options.setEmbeddable( false );   // Apply the rendering options to the task.   task.setRenderOption( options );   // Run and close the task   task.run();   task.close();   // Create a run and render task object. IRunAndRenderTask task = engine.createRunAndRenderTask( runnable ); // Set values for all parameters in a HashMap, parameterValues task.setParameterValues( parameterValues ); // Validate parameter values. boolean parametersAreGood = task.validateParameters( ); // Set the name of an output file. HTMLRenderOption options = new HTMLRenderOption( ); String output = name.replaceFirst( ".rptdesign", ".html" ); options.setOutputFileName( output ); options.setImageDirectory( "image" ); options.setHtmlRtLFlag( true ); options.setEmbeddable( false ); // Apply the rendering options to the task. task.setRenderOption( options ); // Run and close the task task.run(); task.close(); 设置PDF rendering选项 生成PDF格式的报表需要在报表中嵌入字体，或者使用非标准路径的字体，应用程序支持PDF rendering以下设置： ■ 字体路径，如果使用自定义路径下的字体，使用setFontDirectory( )进行设置。 ■ 嵌入的字体，调用PDFRenderOption.setEmbededFont( )可以使用嵌入字体。

 

 

如何构建一个Birt报表应用程序(八)

 

五、生成报表 IRunAndRenderTask和IRunTask对象的run方法可以生成报表，同时要处理run方法抛出的EngineException异常。 下面的代码展示了如何生成一个报表： Java代码 try {   task.run( );   System.out.println( "Created Report " + output + "." );   }catch ( EngineException e1 ) {   System.err.println( "Report " + name + " run failed." );   System.err.println( e1.toString( ) );   }   engine.destroy( );   try { task.run( ); System.out.println( "Created Report " + output + "." ); }catch ( EngineException e1 ) { System.err.println( "Report " + name + " run failed." ); System.err.println( e1.toString( ) ); } engine.destroy( ); 六、取消报表运行任务 BIRT报表引擎支持检查引擎任务的状态，并取消这个任务。通常使用不同的进程来执行这些操作。 使用EngineTask.getStatus( )方法可以检查报表的运行状态，返回值有下面这些： ■ IEngineTask.STATUS_NOT_STARTED. 任务没有启动 ■ IEngineTask.STATUS_RUNNING. 任务正在运行中 ■ IEngineTask.STATUS_SUCCEEDED. 任务正常结束 ■ IEngineTask.STATUS_FAILED. 任务没有正常执行 ■ IEngineTask.STATUS_CANCELLED. 任务被取消 调用IEngineTask.cancel( )方法可以取消任务。如果一个正在运行的任务被取消了，它将停止生成报表，如果任务正在查询数据库，则数据库要继续执行完查询任务。 下面就是一个取消任务的例子： Java代码 private class CancelReport extends Thread   {   private IEngineTask eTask;   public CancelReport( String myName, IEngineTask task ) {   super( myName );   eTask = task;   }   public void cancel( ) {   try {   Thread.currentThread( ).sleep( 100 );   eTask.cancel( );   System.out.println( "#### Report cancelled #####" );   }catch( Exception e )   {   e.printStackTrace();   }   }   }      CancelReport cancelThread = new CancelReport( "cancelReport", task);   cancelThread.cancel( );   private class CancelReport extends Thread { private IEngineTask eTask; public CancelReport( String myName, IEngineTask task ) { super( myName ); eTask = task; } public void cancel( ) { try { Thread.currentThread( ).sleep( 100 ); eTask.cancel( ); System.out.println( "#### Report cancelled #####" ); }catch( Exception e ) { e.printStackTrace(); } } }  CancelReport cancelThread = new CancelReport( "cancelReport", task); cancelThread.cancel( ); 结束了，只是简单的翻译一下，更深入的应用还靠大家去挖掘！

 

 

BIRT学习小结

 

自己写的birt学习笔记，由于是根据英文教材学习的，可能在理解上会出现一些偏差，见谅……，如需要示例，可以联系我 BIRT概述 BIRT (Business Intelligence and Reporting Tools), 是为 Web 应用程序开发的基于 Eclipse 的开源报表系统，特别之处在于它是以 Java 和 J2EE 为基础。BIRT 有两个主要组件：基于 Eclipse 的报表设计器，以及部署到应用服务器上的运行时组件。BIRT 也提供了图标引擎让你能为应用增加图表。 有了 BIRT，你可以为应用程序构建丰富的报表。 　　列表 － 列表是最简单的报表。当列表变长时，你可以把相关数据增加到同一分组（基于客户的订单分组，基于供应商的产品分组）。如果数据是数字类型的，你可以轻松的添加到“总数”、“平均”、或其他汇总中。 　　图表 － 当需要图表表现时，数字型数据比较好理解。BIRT 也提供饼状、线状以及柱状图标等。 交叉表 － 交叉表（也叫做十字表格或矩阵）用两种维度展示数据 信函和文档 － 通知、信件、以及其他文本文档都很容易通过 BIRT 方便建立。文档包括正文、格式、列表、图表等。 混合报表 － 很多报表需要联合以上所有的报表构成单一文档。例如，一份客户声明会列出客户所需要的信息，为当前促进(promotions)提供文本，以及提供并行的出帐和入帐列表。一份财政报表将包括声明、图表、表格，所有这些都将进行全方位的格式化，来匹配共有的配色方案。 BIRT开发流程概述 配置BIRT开发环境 我们可以基于eclipse进行birt的开发，在这里，我们在eclipse中集成了myeclipse7，由于myeclipse7已经集成了birt组件，所以我们只需要安装 myeclipse7插件即可。 配置数据源 数据源及报表所需要的数据的来源，报表展示的数据均来自数据源中。 BIRT目前支持多种数据源，具体包括数据库数据源 ，webservice数据源和xml数据源，和javascript数据源。目前最常见的数据源是数据库数据源。 配置报表用到的数据集 具体报表中用到的数据集合叫做数据集，数据集是按照一定的条件从数据源中获取到的数据集合。数据集中的数据可以被排序、过滤、以及分组。 设计报表 通过BIRT的开发平台，我们可以很方便快捷的设计出复杂、美观的报表。一个报表的信息存储在一个xml格式的报表文件中。 我们可以打开一个报表文件先看一下，在这里报表的文件看起来很复杂，所以，一般我们都是通过可视化开发工具进行报表文件的编辑。 部署报表到程序 当报表设计完成后，我们需要将其部署到相应的应用程序以供用户使用。BIRT提供了相应的运行时环境，可以将其整合到我们的web应用中，这样就可以运行报表了。 一个实例 实例说明 假设有这样一个报表设计开发要求:在mysql数据库中有一张与产品有关的数据表，其中包含产品分类名称、产品编号、产品名称、产品价格四个字段。 要求通过一张图表，按照产品的分类，罗列出各个分类下的产品详细信息。并统计每一分类下的产品数。 最后通过饼图将每个分类下的产品数量统计出来。 创建工程 首先我们创建一个工程，将其命名为reportShow;然后向其增加开发报表的报表功能。 选择file-new –reportProject，选择j2ee5.0,并将工程名称命名为：reportShow。我们先来看一下整个工程的结构：这个工程和普通的java web工程结构是一样的。不同的是多出了报表所用的运行时环境，主要是report web lib,以及在web.xml中添加了相应的servlet配置。 创建报表 下面我们将创建一个报表文件，将其命名为demoReport。 我们在reports文件夹下点击右键选择new -– report,输入报表名称：demoReport.rptdesign,选择空白报表一项；选择使用嵌入式标签进行展示；点击完成。这样就创建了一个报表文件。 现在我们来看一下,刚才的操作创建了两个文件，一个是/demoReport.jsp，用于演示报表jsp页面，另一个是：/reports/demoReport.rptdesign，使我们接下来需要编辑的报表文件。 数据库、数据源和数据集的配置 打开demoReport.rptdesign文件，我们现在首先要做的是配置数据源，以获取数据 我们使用数据库类型的数据源作为当前报表的数据源，我们使用mysql数据库，数据库名称为birtDemo,在其中有一名为product的表，包括4列：id 、name、price,categoryName分别代表主键，产品名称,价格,所属分类名称。 接下来，我们配置下birt数据源。在data explore面板中选择dataSource，右键选择new dataSource ，选择数据库数据源。选择：com.mysql.jdbc.driver.这个是已经配置好的数据源。由于时间有限，数据库数据源参数的具体配置请参见myeclipse 数据源的配置方式，在这里不再演示。 点击测试，检测是否能够连接到数据库中。若测试通过，则数据库数据源创建成功。 接下来我们创建数据集product，这里的product数据集，将包括birtDemo数据库的product表中的所有数据. 在dataSet上，右键选择new Data Set,输入数据集名称“product”，所属的数据源选择默认数据源即可。点击下一步，输入数据集查询语句：select * from birtdemo.product ，点击完成。接下来我们可以预览一下刚创建的数据集，如果有不满意的地方还可以对其进行修改。 预览一下，确实查询到了所有的数据。完成数据集的创建操作。 设计报表 我们首先将product数据集中的所有数据展示在一个表格中。 在 palette 面板中拖动一个table对象到右侧文件中，这样会在报表文件中添加一个列表对象。 选择列数。然后在data explore面板中，拖动product数据集的各个列到tabe中。切换到预览标签，我们可以看一下此时的展示效果：在table中列出了数据集的各个列的数据。 接下来，我们修改下列表的表头部分。分别改为：编号、名称、价格、分类。 下面，我们对报表进行按照分类进行分组操作。 首先我们调整一下各列的展示顺序，换成分类、编号、名称、价格。 然后在表格上按右键选择增加分组，选择分组列：categoryName。这样，就添加了一个分组到报表中。 接下来我们去掉多余的字段，并调整分组的样式【将分组改为对齐数据第一行并使其竖行剧中展示】。 下面我们对报表进行下美化。我们采取样式表的方式对列表进行美化。 先创建一个样式表文件：report.css,将其放置到css文件夹中。在其中添加上表格样式： .tables{ text-align:center; line-height:25px; font-size:14px; margin: 0; border: 1px solid #99CCCC; } .table-header{ color:red; } 我们在报表文件的out-line面板中导入这个文件：在Styles上按右键，选择Use Css File，选择我们刚才创建的文件，完成css文件的引入。 然后我们在报表的table上选择style—apply style 选择tables，这样就增加了样式到表格上了。我们可以预览一下效果。 我们接着给当前的报表增加一个图表，以饼图的形式，统计各个分类的产品数量。 我们先来定义一个数据集：叫做productStat,这里按照分类名称进行分组，取得分组名称以及分组中包含的数目。 select birtdemo.product.categoryName, count(birtdemo.product.price) from birtdemo.product group by birtdemo.product.categoryName 接下来，我们在报表文件中拖入一个Chart组件，我们选择chart的类型为pie，即饼图。在数据选择标签中，我们选择使用数据集的方式，选中刚创建的数据集productSta。 将分类名称部分拖动到分类部分；将总数部分拖动到左侧作为饼图的值。保存后点击报表的预览看一下效果。这样，一个简单的饼图就添加到报表中了。 发布 到目前为止，我们还只是在birt的开发环境中预览报表文件的效果，下面我们将在实际环境中运行报表看一下。 首先打开创建报表时自动生成的页面：demoReport.jsp 页面中使用了<birt:viewer>标签来访问我们刚才创建的报表，几个参数的意思很明显，分别指定了报表路径以及展示格式等。 最后，我们部署刚创建的应用，运行一下看一下实际效果。