[计算机软件及应用]Eclipsebirt使用说明中文.doc

Birt使用说明Birt适合版本：2.1.3文档版本：V1.0作者：郑威武最后修改时间：2008-7-343目 录一、前言1二、相关软件11.1、BIRT21.2、GEF和EMF3三、Birt的安装和配置3四、使用说明54.1、创建项目54.2、创建第一个报表74.2.1、创建一个空白报表74.2.2、设置数据集参数94.2.3、设计报表144.3、报表中的参数264.3.1、静态标量参数274.3.2、动态标量参数29五、应用系统的结合31一、前言公司的一个Java语言的B/S架构项目中需要实现大量的文字报表和图像报表的功能，以前使用CSS、JS和JfreeChart等技术，只能实现简单的报表，很难达到现在需求，于是我研究了几个开源免费的报表工具，通过网上的评价，发现了Birt有以下几点优点：1、开发方便，Birt是Eclipse的一个插件可以很好的集成在Eclipse中，图形编辑框架下可以在几分钟之内做出一个报表。2、可以很方便地在一个报表中混合展现概要数据和详细数据。3、操作界面友好大方。4、提供了强大灵活的样式定义，对于属性CSS的设计人员来说，应该可以设计出相当出色的报表样式。5、集成在Eclipse中，不用再开启别报表开发工具窗口，对于习惯于Eclipse开发的程序员来说这点非常重要。6、Birt的本地化做的很好，安装以后操作界面就是中文的（这点我在使用过程中没有充分体现，我使用了Birt的中文语言包）。7、开源的报表产品，有源代码，可以进行深层的定制开发。8、生成的报表完全是XML格式，扩展性好。9、容易和应用系统结合。10、最重要一点是开源免费的（我穷啊）。根据这几个优点，我决定研究Birt，通过几天查找资料和自己的摸索，心中总算有些小的体会。由于习惯与Eclipse3.2版本，所以我使用了2.1.3版本的Birt，现在最新版本已经是2.3以上版本了，就是这个原因网上很多资料都不是很适合这个版本，所以我走了很多弯路，希望看到此文档的人能比我少走弯路，这也是我写这个文档的原因之一。二、相关软件相关的软件分别为：Java 1.4.2/1.5 JDK/JRE Eclipse-SDK-3.2.0 Graphics Editor Framework (GEF 3.2) runtime sdfsdEclipse Modeling Framework (EMF 2.2.3) runtime Birt 2.1.3Birt-runtime-2.1.3（发布时使用）NLpack1-birt-report-designer-all-in-one-2_1_3.zip（Birt的中文插件）下载地址为：http:/www.eclipse.org/birt/phoenix/由于在使用过程中对Birt、GEF和EMF不是很理解其用处，所以我也找了一些资料（汗颜，我想大家都知道），下面我就分别简单的介绍一下，如果大家都知道那就跳过去吧。1.1、BIRTBirt（Business Intelligence and Reporting Tools）是一个Eclipse-based开放源代码报表系统。，是为 Web 应用程序开发的基于 Eclipse 的开源报表系统，特别之处在于它是以 Java 和 J2EE 为基础。BIRT 有两个主要组件：基于 Eclipse 的报表设计器，以及部署到应用服务器上的运行时组件。12213123Birt可以实现的报表格式有一下几种，列表、图表、混合报表、交叉表和信件文档，在测试过程中，我只实现了列表、图表和混合报表。听说也可以实现交叉表和信件文档，我没有验证这里就不介绍了。列表：列表是最简单的报表。当列表变长时，你可以把相关数据增加到同一分组。如果数据是数字类型的，你可以轻松的添加到“总数”、“平均”、或其他汇总中。图表：当需要图表表现时，数字型数据比较好理解。BIRT 也提供饼状、线状以及柱状图标等。混合报表：很多报表需要联合以上所有的报表构成单一文档。例如，一份客户声明会列出客户所需要的信息，为当前促进(promotions)提供文本，以及提供并行的出帐和入帐列表。一份财政报表将包括声明、图表、表格，所有这些都将进行全方位的格式化，来匹配共有的配色方案。213123一份报表包括BIRT包含四个部分：数据、数据转换、业务逻辑和表现形式。数据：数据库、Web 服务、Java 对象，这些都可以作为 BIRT 报表源（Web 服务、Java 对象，我没有验证，不知道是否可行，大家都这样说，我也照搬了）。BIRT 的 ODA(Open Data Access) 框架允许任何人构建新的 UI 以及运行时支持任何类型的表格式数据，单一报表可包含从任意多个数据源获取数据。数据转换：报表通过对数据的分类、统计、过滤以及分组来适应用户需求。当然，数据库能实现这些功能，当遇到普通文件和 Java 对象时 BIRT 必须以 "simple" 数据源方式处理。BIRT 允许复杂的操作，比如总合分组、整体共计的百分比，等等。业务逻辑：真实世界的数据很少提供你理想的结构良好的报表。许多报表要求用具体逻辑把原始数据转换成用户的有用信息。如果该逻辑仅仅用于该报表，你可以用 BIRT 的 JavaScript 脚本支持。如果你的程序中已包含这些逻辑，你可以调用已有的 Java 代码。表现形式：一旦数据准备好了，你可以在很大的范围内选择表现形式。表格、图表、文字等等都可以。单一数据集可以有多种方式表现，而单一报表可以表现多个数据集。1.2、EMF和GEFEmf（Eclipse Modeling Framework）和Gef(Graphical Editor Framework)都是Eclipse的tools项目，在Eclipse中使用Emf对系统建模，如数据库模型、网络连接模型，甚至包括界面显示模型（JAVA的事件模型）。Gef它是一套图像编辑框架，用于开发图形应用，如果你在Eclipse中使用过基于图形设计的应用，例如UML建模，可视化软件界面设计(VE)等，它们基本上都是基于GEF而开发出来的。至于Emf和Gef的具体使用方法和实现效果，这里就不做重点介绍了，毕竟我们研究的主要对象是Birt。Birt是基于Emf和Gef来实现的。三、Birt的安装和配置Birt的安装和Eclipse的其他插件的安装一样，但是我建议使用Link的方式，这样结构上比较清晰，如果都放在Eclipse的plugins下，一是结构不清晰，二是如果以后不用拆分也很麻烦。虽然大家都知道怎么安装Eclipse插件，但是我这里还要啰嗦一下，保持文档的完整性。Eclipse的安装大家想必都会把，直接解压就可以了。在Eclipse根目录下新建一个文件夹，我创建的为myplugins，把下载的GEF-runtime-3.2.zip、emf-sdo-runtime-2.2.3.zip、Birt-2.1.3.zip和NLpack1-birt-report-designer-all-in-one-2_1_3.zip解压在此文件夹下并重命名，每个文件下的下层目录都为eclipse，如图：分别在Eclipse根目录下的links目录下创建对应的映射文件，文件格式为.link，我创建文件如图：内容如图：创建完成，重启Eclipse，重启前在Eclipse快捷方式的目标中加上-clean强制加载插件，如图：在下次使用Eclipse时记得去掉-clean，因为要检查插件，所有速度会很慢。至此Brit就安装完成了，简单吧？安装成功后在视图中多了一块报表设计的视图，如图万事俱备只欠东风，下一步我们就开始激动人心的使用之旅，期待了吧？四、使用说明这里用一个简单的例子来说明列表和图形报表的实现过程。4.1、创建项目创建一名为TestReports的Web项目，如图所示，文件=新建=项目选择【Web Porject】双击输入项目名称，点击【完成】4.2、创建第一个报表4.2.1、创建一个空白报表Eclipse切换到【表报设计】窗口，在WebRoot下创建一个文件夹reports，选中reports右键=新建=报表输入testReport.rptdesign的报表名称点击【下一步】选择空白报表模板，点击【完成】，一个空白的报表已经完成了。4.2.2、设置数据集参数1、创建数据源选中新创建的空白报表，进入【数据资源管理器】选中【数据源】右键=新建数据源，进入新建数据源窗口有很多类型的数据源，选择第二个JDBC数据源，输入数据源名称“OracleJDBC”点击【下一步】由于数据源为oralce数据源，首先要选择oracle的驱动，点击【管理驱动程序】点击【添加】，选择oralce数据库的驱动程序，添加后JAR文件一栏中现实了刚刚添加的驱动程序，添加后点击【确定】，返回【新建数据源】窗口，选择驱动程序类、数据数据库URL、用户名和密码（JNDI URL为数据源），点击【测试链接】，如果输入的项全部正确会提示，链接成功点击【完成】，数据源创建成功2、创建数据集合在【数据资源管理器】窗口，选中【数据集】，右键=新建数据集，进入新建数据集窗口输入数据集名称ryxx（人员信息），选择刚刚创建的数据源（oracleJDBC），选择数据集类型，我选择的为“SQL 选择查询”，点击【下一步】【可用数据项】一栏中显示出可选择的数据项（表），如果表空间和表过多，很难查找出创建数据集所需要的表，可以使用【应用筛选器】，在架构中选择所在的表空间，筛选器中输入表或表空间的关键子，类型包括，表、视图和存储过程，输入条件后点击【应用筛选器】，在【可用数据项】中现实出符合条件的表空间和表。在右面一栏中我们可以输入SQL语句，这个SQL语句可以手动自己输入，也可以手动从【可用数据项】中拖入SQL需要的字段或表，来拼装SQL语句，也可以选择莫个表和字段双击。创建了两个数据集分别为ryxx和ryxx_rb对应的SQL语句分别为：Ryxx：select gh,xb,xm,sfzhm from t_rygl_ryxx where gh>04700 and gh<05000Ryxx_xb：select xb,count(xb) as cxb from t_rygl_ryxx where gh>04700 and gh<05000 group by xb点击【预览结果】，可查看SQL语句对应的结果集，ryxx数据集对应的如图3、计算列在一些报表中可能要对一些列进行计算生成新的列。点击【计算列】 进入如下图：点击【新建】输入列名，选择数据类型，输入表达式添加计算列后，预览效果如图4.2.3、设计报表数据集已经创建成功，下一步就在报表中体现这些数据，设计出一个图形和文字结合的报表。1、Paletta窗口此窗口存在各种控件，使用方法是，直接拖到空白的报表上，下面分别介绍这几个控件的具体作用。Lable标签输入静态文本标签Text文本输入静态文本 DLable动态文本标签显示变量或表达式的值 Dtext动态文本显示变量或表达式的值Image图片可以在报表中插入图片。Grid可以用它在报表中设置你的布局。List用于在报表中显示list的信息Table用以显示你的数据集。可以把创建的数据集做为一个Table直接拖入到报表中，也可以先创建一个Table，然后拖入数据集中对应的字段。Table支持行列的合并，选中要合并的行列右键选择【合并单元格】即可 Char用于在报表中显示你的统计图2、设计图形选择Table拖入到空白报表中，设计成两行一列 选择Char拖入到Table的明细数据行，选中表，在【属性编译器】中【属性】中的【常规】中的【文本对齐】，选择居中，选择蓝色为背景色。图表类型选择，饼图；维选择，二维并具有深度；输出格式选择，SVG，点击【下一步】选择数据集一项，选中【使用数据集】，从下拉列表中选择ryxx_rb这个数据集，在数据预览中出现此数据集的字段以及值，右键cxb列（或者直接拖入到扇面大小定义）选择【绘制为值系列】；右键xb列（或者直接拖入到类定义）选择【用作类别系列】点击【下一步】，选择【图形区域】输入图表标题，选择背景色，选择【图形】选择客户区域背景，点击区域格式也可以改变图形布局，选择【图例】更改图例的背景色和布局，布局更改为，方向，水平；位置，下方；定位，北；伸展，水平。点击【系列】，更改着色依据，为系列增加标题点击【类别系类】以更改最小扇面的最小值，数据排序，分组和更改扇形颜色的分配点击【值系列】，点击【标签】更改标签现实的内容点击【完成】，此报表的一部分图形已经完成，在报表编译器中手动调整图表的大小，点击报表编辑器中的预览，效果如下：3、设计列表选择【大纲】面板选择ryxx的数据集，拖入到报表编辑器中选中列名右键【编辑】，更改为中文列名选中表，在【属性编译器】中【属性】中的【常规】中的【文本对齐】，选择居中选中第一行，右键=插入=行=在上面，选中新增加的行右键=合并单元格，右键=插入=标签=输入“职工详细信息”选中表，在【属性编译器】中【属性】中，更改字体和样式，根据自己的喜好定义。选中表，在【属性编译器】中的【排序】点击【添加】按钮，选择关键字（工号）和方向（升序），点击【确定】，此列表按照工号升序的排序现实，此功能也可以使用SQL语句的order by来实现。同样道理也可以实现分组。在表格下面增加一行，在第一个单元格插入【标签】，并输入“合计：”，其余三行合并单元格，插入【数据】，输入名称，选择数据类型点击表达式后面的按钮，双击可用列绑定=表=行数至此，一个简单的报表就生成了，预览如下：4.3、报表中的参数本节主要介绍标量参数，其他的参数形式请看原文（主要是还没有研究透彻，如果研究透彻了我会更新我的文档的），本节参照Birt 报表参数的使用。在生成上述简单例子的过程中，有些人肯定要问，为什么不介绍报表中出现的参数？据条件查询生成报表是最常见的一种格式，所以是非常重要的，这里我单独的拿出来来做介绍。按着上面的方法创建一个Testparameter的空白报表。参数是birt提供的一种很重要的机制，在bir 中，参数具有变量的作用，它为birt报表的生成提供了一种灵活强大的机制。本文示例使用 Birt 自带的 Sample 数据源，用到的数据基于图1所示的实体关系模型。从这个模型中可以看出，文中示例用到三张数据库表分别为customers，orders和orderdetails。其中customers表的customernumber字段作为外键出现在orders表中，而orders表的ordernumber字段做为外键出现在orderdetails表中。图 1. 实体关系模型在使用BIRT参数的时候，首先要了解BIRT分为报表参数和数据集参数。报表参数定义于整个报表内，而数据集参数定义于某个数据集（DataSet）中。数据集参数使用的时候通常需要链接到某个报表参数或者利用绑定表（binding tab）和一个嵌套表中的某个数据元素绑定。标量参数是Birt报表中最简单也是最基本的一类参数，标量参数可以分为静态和动态两种，其中静态参数从用户界面获得用户输入的数据值，而动态参数则可以关联至某一个数据集，因此可以获得一个数据的集合，供用户选择。下面分别介绍这两种参数。 4.3.1、静态标量参数右键点击【大纲】面板中的【报表参数】选项，在弹出的上下文菜单中点击【新建参数】，弹出图2所示编辑参数对话框，在【名字】域输入参数的名字，本例中使用的参数名字为“customernum”,此时【值列表】项默认为static。 点击【确定】后返回到开发主界面。图2：编辑参数创建名为SampleSet的数据集，见图3，SQL语句为：select CUSTOMERNAME from CUSTOMERS where CUSTOMERNUMBER = ?图3，创建数据集点击【完成】，进入编辑数据集窗口，点击【参数】=【新建】，输入参数名称，param；选择数据类型，字符串；选择方向，输入；选择链接到报表参数，customernum，点击【确定】完成了数据集中参数的定义。当报表运行时，Birt会使用由报表参数customernum传入的值填充where条件，生成结果数据集。 如图4所示。图4，新建参数4.3.2、动态标量参数动态参数可以提供一个数据值的列表供用户选择，这种功能能够极大增强报表设计用户界面的交互性。 在本例中，首先定义一个数据集，这个数据集不使用参数，它从订单表中查询出所有的订单号，为报表参数提供一个数据值的列表。 如图5所示。图5，数据集“ordernum”接下来，我们定义报表参数，这个参数链接至前面的ordernum，因此可以根据数据集中的参数ordernum动态的获得可选值。 如图6所示图6，报表参数“ordernumpara”如图中所示参数的【现实类型】选为“组合框”，【值列表】选择为“动态”，其链接至的【数据集】选择为前面定义的ordernum数据集，同时选定【选择值列】为数据集ordernum中的某个字段，这里ordernum数据集只有一个字段，故选择为ordernumber。 这样就将报表参数和数据集参数关联起来。但这不是我们的最终目的，我们的目的是以报表参数ordernumpara为中介，向另一个数据集提供参数。 因此，我们定义图7所示的数据集。图7，创建数据集“ordersdetail”点击【确定】，进入编辑数据集的窗口，点击【参数】=新建，进入新建参数窗口，输入名称，选择数据类型，选择方向和连接到报表参数，点击【确定】，如图8图8，创建本数据集的参数num链接至ordernumpara，就完成藉由一个报表参数为中介将一个数据集的字段值链接到另一个数据集的参数的功能。五、应用系统的结合与现有的系统结合有两种常见方式1、使用Birt自带的runtime把Birt-runtime-2.1.3.zip解压，把WebViewerExample 拷贝到% tomcat-Home%webapps目录下。把你做好的*.rptdesign 和*.rptconfig文件放于% tomcat-Home%webapps report目录下我们把刚刚创建的第一个报表“testreport.rptdesign”，拷贝到report下，重启Tomcat。输入以下的连接，Run 是html 的形式显示，看不出分页效果，但利用ie的打印功能可以实现打印的。Frameset 是pdf形式显示，可以看到分页效果的。8080是tomcat的端口testreport.rptdesign是报表名report 是相对路径的文件夹名http:/127.0.0.1:8080/WebViewerExample/run?_report=report/testreport.rptdesignhttp:/127.0.0.1:8080/WebViewerExample/frameset?_report=report/testreport.rptdesign效果分别如下：点击【打印】按钮2，使用birt提供的Report Engine Api来调用报表并展现报表我们一开始就创建了一个名字为TestReports的WEB工程，通过下面的步骤，做一个简单的例子来调用和展示我们做的第一个报表。第一，把Birt-runtime-2.1.3.zip解压，把根目录中的ReportEnginelib下的所有文件导入到，WebRoot模块下的WEB-INF目录中的lib目录下。第二，在WEB-INF目录中新建文件夹platform，把ReportEngine下的plugins和configuration导入platform目录下。第三，把数据库的驱动程序导入到工程的lib目录下第四，创建一个名字为BirtEngine的JAVA的类，具体代码如下：package cn.sh.sungate.report.bean;import java.io.InputStream;import java.io.IOException;import java.util.Properties;import java.util.logging.Level;import org.eclipse.birt.report.engine.api.EngineConfig;import org.eclipse.birt.report.engine.api.IReportEngine;import javax.servlet.*;import org.eclipse.birt.core.framework.PlatformServletContext;import org.eclipse.birt.core.framework.IPlatformContext;import org.eclipse.birt.core.framework.Platform;import org.eclipse.birt.core.exception.BirtException;import org.eclipse.birt.report.engine.api.IReportEngineFactory;public class BirtEngine private static IReportEngine birtEngine = null;private static Properties configProps = new Properties();private final static String configFile = "cn/sh/sungate/report/bean/BirtConfig.properties"public static synchronized void initBirtConfig() loadEngineProps();public static synchronized IReportEngine getBirtEngine(ServletContext sc) if (birtEngine = null) EngineConfig config = new EngineConfig();if (configProps != null) String logLevel = configProps.getProperty("logLevel");System.out.println("logLevel"+logLevel);Level level = Level.OFF;if ("SEVERE".equalsIgnoreCase(logLevel) level = Level.SEVERE; else if ("WARNING".equalsIgnoreCase(logLevel) level = Level.WARNING; else if ("INFO".equalsIgnoreCase(logLevel) level = Level.INFO; else if ("CONFIG".equalsIgnoreCase(logLevel) level = Level.CONFIG; else if ("FINE".equalsIgnoreCase(logLevel) level = Level.FINE; else if ("FINER".equalsIgnoreCase(logLevel) level = Level.FINER; else if ("FINEST".equalsIgnoreCase(logLevel) level = Level.FINEST; else if ("OFF".equalsIgnoreCase(logLevel) level = Level.OFF;config.setLogConfig(configProps.getProperty("logDirectory"),level);config.setEngineHome("");IPlatformContext context = new PlatformServletContext(sc);config.setPlatformContext(context);try Platform.startup(config); catch (BirtException e) e.printStackTrace();IReportEngineFactory factory = (IReportEngineFactory) Platform.createFactoryObject(IReportEngineFactory.EXTENSION_REPORT_ENGINE_FACTORY);birtEngine = factory.createReportEngine(config);return birtEngine;public static synchronized void destroyBirtEngine() if (birtEngine = null) return;birtEngine.shutdown();Platform.shutdown();birtEngine = null;public Object clone() throws CloneNotSupportedException throw new CloneNotSupportedException();private static void loadEngineProps() try / Config File must be in classpathClassLoader cl = Thread.currentThread().getContextClassLoader();InputStream in = null;in = cl.getResourceAsStream(configFile);configProps.load(in);in.close(); catch (IOException e) e.printStackTrace();第五，创建一个名字为WebReportServlet的Servlet的类，具体代码如下：package cn.sh.sungate.report.servlet;import java.io.IOException;import java.io.PrintWriter;import java.util.HashMap;import java.util.logging.Level;import java.util.logging.Logger;import javax.servlet.ServletContext;import javax.servlet.ServletException;import javax.servlet.http.HttpServlet;import javax.servlet.http.HttpServletRequest;import javax.servlet.http.HttpServletResponse;import org.eclipse.birt.report.engine.api.EngineConstants;import org.eclipse.birt.report.engine.api.HTMLRenderContext;import org.eclipse.birt.report.engine.api.HTMLRenderOption;import org.eclipse.birt.report.engine.api.IReportRunnable;import org.eclipse.birt.report.engine.api.IRunAndRenderTask;import org.eclipse.birt.report.engine.api.IReportEngine;import cn.sh.sungate.report.bean.BirtEngine;public class WebReportServlet extends HttpServlet /* * */private static final long serialVersionUID = 1L;/* * Constructor of the object. */private IReportEngine birtReportEngine = null;protected static Logger logger = Logger.getLogger("org.eclipse.birt");public WebReportServlet() super();/* * Destruction of the servlet. */public void destroy() super.destroy();BirtEngine.destroyBirtEngine();/* * The doGet method of the servlet. * */public void doGet(HttpServletRequest req, HttpServletResponse resp)throws ServletException, IOException / get report name and launch the engineresp.setContentType("text/html");/ resp.setContentType("application/pdf");resp.setHeader("Content-Disposition", "inline; filename=test.pdf");String reportName = req.getParameter("ReportName");ServletContext sc = req.getSession().getServletContext();this.birtReportEngine = BirtEngine.getBirtEngine(sc);/ setup image directoryHTMLRenderContext renderContext = new HTMLRenderContext();renderContext.setBaseImageURL(System.getProperty("java.io.tmpdir");renderContext.setImageDirectory(System.getProperty("java.io.tmpdir");logger.log(Level.FINE, "image directory "+ System.getProperty("java.io.tmpdir");HashMap contextMap = new HashMap();contextMap.put(EngineConstants.APPCONTEXT_HTML_RENDER_CONTEXT,renderContext);IReportRunnable design;IRunAndRenderTask task = null;try / Open report designdesign = birtReportEngine.openReportDesign(sc.getRealPath("/Reports")+ "/" + reportName);/ create task to run and render reporttask = birtReportEngine.createRunAndRenderTask(design);task.setAppContext(contextMap);HashMap paramMap = new HashMap();paramMap.put("param", "%");paramMap.put("sample", "lisa ok");task.setParameterValues(paramMap);/ set output optionsHTMLRenderOption options = new HTMLRenderOption();/ options.setOutputFormat(HTMLRenderOption.OUTPUT_FORMAT_PDF);options.setOutputFormat(HTMLRenderOption.OUTPUT_