第二章 BIRT设计器概述及本地化支持

转载自：https://blog.csdn.net/z1012890225/article/details/37815863

2.1 BIRT设计器概述

2.1.1 基本概念

数据源：数据的来源，或提供者。如xml数据源、jdbc数据源等。

数据集：数据集合，它必须与数据源关联，可以理解为查询的结果。

报表以及报表项：报表可视为是针对一组数据集的表现形式，而报表项这是这个表现形式的某个具体的单元。它们之间的关系，与窗体和控件的关系非常类似。报表、数据集、数据源三者间的关系：数据源 — 数据集 — 报表。

报表参数：查询参数的表现形式，使用它可以构建更灵活的报表。

模板和库：主要用于复用报表设计，提高报表开发的效率。

在大纲视图中展开报表文件（后缀为.rptdesign）可以看到数据源，数据集，报表和数据项（主体，主页，样式，脚本等），报表参数（图2-1）。

图 2-1 报表的基本概念

模板和库类似于一个公共报表，我们在设计的时候可以使用公共数据源，公共数据集，公共样式，甚至公共数据项（图2-2）。模板的后缀为.rpttemplate，库的后缀名为.rptlibrary，模板和库的建立和使用在后文中再详细描述。

图 2-2 报表的模板和库

2.1.2 基本视图

在Eclipse BIRT设计器中，提供了多种视图，以方便进行模板文件的设计。各种设计视图如下：

1．报表编辑器（Report Editor）：

Report Editor提供了报表设计的画板，可以摆放设计元素并将其格式化。包括布局的表格、主页面、脚本、XML 文件源及预览。

布局：用于对整个报表界面进行整体布局，框架性的组件，支持拖放功能；

主页：用于设置模板文件的共用属性，如报表文件的头、尾、背景图片等；

脚本：支持对JavaScript脚本的编辑，BIRT支持事件模型，因此可以使用Java或JavaScript来编写事件处理器，事件处理器存在于报表的生成及渲染过程，可以用于修改报表的属性、字体颜色、数据值或调用外部代码；

XML 文件源：用于查看报表模板中所用于的XML代码，可以在这里进行XML内容的查看或编辑。

预览：把报表模板快速的渲染成为HTML格式文件进行预览。如下图所示：

图2-3 报表预览

2．数据资源管理器（Data Explorer）

在进行报表设计之前，设置好数据库连接通常是必须的。为了方便进行数据库的连接设置，BIRT提供了Data Explorer视图。

图2-4 BIRT Data Explorer

这种视图下可以允许为报表添加数据源及数据集。当然这里的数据源指是的数据库连接。BIRT提供了对JDBC、XML、脚本，Web Service数据源、CSV、TSV、SSV及PSV等数据源等等的支持。

而数据集可以理解为已经被执行的查询语句并返回的记录集。BIRT提供了一种特殊的数据集：Joint Data Set（简称联合数据集）。它可以对现在的数据集进行内连接或是外连接。当使用不同的数据源的，这种功能非常的实用。

Data Explorer还可以用于添加报表参数及数据立方体。报表参数是暴露给报表模板使用人员的参数，参数传递相关参数值，可以个性化报表。例如，可以使用数据集参数来修改查询语句，或使用BIRT JavaScript表达式来改变报表元素的样式及可见性。

报表参数可以是静态的，也可以是动态的。静态参数是指用户可以从预先定义好的参数值可选取值，进行相关的展示或运算，最简单就是文本框中的静态内容。动态参数一般指在绑定到BIRT数据集，而用户可以从中选取某些需要的数据或记录。

在BIRT3.7中，动态报表参数支持使用JavaScript表态式来动态显示文本或参数值。这样即可以动态的显示最终用户所传递的参数值。

此外，BIRT还支持联动报表参数。可以设置二级或是三级的联动下拉框或是List。最明显的例子如下图所示：

图2-5 BIRT联动报表参数

在Data Explorer视图中可以创建数据立方体，可以与BIRT中的交叉报表结合使用。BIRT数据立方体是多维的，可以基于多个数据集，如下图所示：

图2-6 BIRT数据立方体

除了上面的特性外，BIRT还新增了两种用于支持其它数据源的项目类型。这类数据源基于Eclipse的DTP（Data Tools Platform）项目所提供的ODA（Open Data Access）框架

图2-7 BIRT中ODA设计工具

3．画板（Palette）

BIRT Palette视图用于给报表画板添加报表元素。这里的元素可以代表从Data Explorer视图中所设计的数据。Palette中的元素支持自由的拖放功能，Palette上的元素属性可以通过属性编辑器进行设计，也可以通过ROM（BIRT Reports Object Model）进行描述。

图2-8 BIRT的Palette视图

Palette包括以下一些常用的元素：

标签（Label）：标签元素用于显示静态文本，标签元素的外观可以通过本地进行设置，如设置标签元素的超级连接、字体大小等属性；

文本（Text）：文本元素与标签元素相似，只是文本元素可以显示多行数据，更加易于格式输出。可以在文本元素中使用脚本表达式，然后在客户端使用标签进行解析；

动态文本（Dynamic Text）：动态文本元素通常用于显示CLOB数据值。CLOB数据可以通过使用BIRT Expression Builder得到数据；

数据（Data）：数据元素用于显示数据源的数据，通过使用Expression Builder来操作或改变数据值。例如，数据集有包含姓列以及名列，那么可以使用Expression Builder来将姓列与名列进行合并，从而形成包含姓名的一列；

图像（Image）：图片元素用于在报表模板中显示图片。BIRT支持通过URL获得图片，或是从数据库的取得图片（BLOB），或是从本地硬盘上获得图片；

网格（Grid）：网格元素用于布局报表中的报表元素，并进行统一的管理。例如，想在报表中显示产品销售数据表格，同时又想在右边显示一张图表，此时则需要使用Grid来进行网格划分，将报表分成一行两列；

列表（List）：列表元素也相当于一个容器，它不同于其它容器的地方在于列表元素可以绑定到数据集上。列表元素包含头、脚及数据部分。当渲染列表元素时，头与脚部分一次性渲染完成，而中间的数据部分需要显示数据集的每一行数据。数据格式可以是文本元素，也可以是表格、列表等元素；

表（Table）：表格元素与列表元素相似，都可以用于显示数据集中的数据。表格元素与HTML中的表格元素风格相似；

聚合（Aggregation）：汇总元素是BIRT 2.2新增的元素，使用Aggregation Builder向报表添加汇总功能。Aggregation Builder提供的汇总功能大概有25项，常见的如：SUM、MIN、MAX、AVERAGE等等；

图2-9 BIRT的Aggregation元素

图表（Chart）：图表元素用于在报表中添加图表。当在报表中添加了图表元素时，Chart Builder Wizard自动进行渲染并显示。Chart Builder Wizard用于设计图形，并提供了三大设置区域，分别是：设置图表类型、设置数据、设置图表格式。BIRT提供了大量的图表类型，同时，图表格式可以是PNG、JPG、BMP、SVG等输出格式。

交叉表（Cross Tab）：交叉报表元素用于显示BIRT数据立方体中的数据。在BIRT以前的版本中，表格中列数据需要在设计时就确定，而使用交叉报表元素，则列数据与行数可以动态生成，无需在报表设计时确定。

2-10 BIRT的交叉表元素

4．资源管理器（Library Explorer）

Library Explorer支持从已存在的报表库中拖放报表元素。因此，各种报表之间即可以共享一些公用的类库元素。同时，修改其中某一公用的类库元素，即可以修改所有的引用至此类库元素的所有报表。例如，可以在类库元素中保存公司的Logo，如果公司的Logo变化，则只需要修改类库的中Logo元素即可，其它引用此Logo的报表无需修改。

图2-11 BIRT的Library Explorer视图

5．属性编辑器（Property Editor）

属性编辑器视图用于设置报表中元素的属性。当然，每种元素的属性都不尽相同，因此，其界面都有所变化。当然也具有共用的一些属性，如style、width、font等等。此外，大部分元素都支持是否可见的属性。

2-12 BIRT的Property Editor视图

6．大纲（Outline）

Outline视图通过层次关系来展现报表设计的内容及其相关元素的层次关系。可以从Outline中直接选择元素进行查看或修改，当报表设计比较复杂时，Outline是相关方便有用的辅助工具。

图2-13 BIRT的Outline视图

比较重要的视图还有导航器（Navigator）和问题查看器(Problems)

图2-14 BIRT的导航器

图2-15 BIRT的问题查看栏

2.2 BIRT本地化之汉化

2.2.1 BIRT设计器的汉化

建议把整个eclipse环境都彻底汉化，需要的文件如下，这个在eclipse-birt官方网站上有语言包Language Packs。

BabelLanguagePack-birt-zh_3.7.0.v20111128043401.zip (91.78%)

BabelLanguagePack-eclipse-zh_3.7.0.v20111128043401.zip (87.36%)

BabelLanguagePack-modeling.emft.emf-facet-zh_3.7.0.v20111128043401.zip (21.16%)

BabelLanguagePack-modeling.gmp.graphiti-zh_3.7.0.v20111128043401.zip (20.45%)

BabelLanguagePack-modeling.mdt.modisco-zh_3.7.0.v20111128043401.zip (9.38%)

BabelLanguagePack-mylyn-zh_3.7.0.v20111128043401.zip (50.7%)

BabelLanguagePack-rt.equinox-zh_3.7.0.v20111128043401.zip (99.27%)

BabelLanguagePack-rt.equinox.p2-zh_3.7.0.v20111128043401.zip (22.2%)

BabelLanguagePack-rt.rap-zh_3.7.0.v20111128043401.zip (87.11%)

BabelLanguagePack-technology.actf-zh_3.7.0.v20111128043401.zip (4.46%)

BabelLanguagePack-technology.dltk-zh_3.7.0.v20111128043401.zip (69.33%)

BabelLanguagePack-technology.egit-zh_3.7.0.v20111128043401.zip (16.9%)

BabelLanguagePack-technology.jubula-zh_3.7.0.v20111128043401.zip (11.72%)

BabelLanguagePack-technology.stem-zh_3.7.0.v20111128043401.zip (79.99%)

BabelLanguagePack-technology.uomo-zh_3.7.0.v20111128043401.zip (3.6%)

BabelLanguagePack-tools.atf-zh_3.7.0.v20111128043401.zip (51.91%)

BabelLanguagePack-tools.cdt-zh_3.7.0.v20111128043401.zip (68.2%)

BabelLanguagePack-tools.gef-zh_3.7.0.v20111128043401.zip (66.21%)

BabelLanguagePack-tools.objectteams-zh_3.7.0.v20111128043401.zip (5.51%)

BabelLanguagePack-tools.tm-zh_3.7.0.v20111128043401.zip (21.24%)

BabelLanguagePack-webtools.common-zh_3.7.0.v20111128043401.zip (57.1%)

BabelLanguagePack-webtools.dali-zh_3.7.0.v20111128043401.zip (18.33%)

BabelLanguagePack-webtools.jsdt-zh_3.7.0.v20111128043401.zip (80.48%)

BabelLanguagePack-webtools.jsf-zh_3.7.0.v20111128043401.zip (39.76%)

BabelLanguagePack-webtools.libra-zh_3.7.0.v20111128043401.zip (26.04%)

BabelLanguagePack-webtools.servertools-zh_3.7.0.v20111128043401.zip (88.15%)

BabelLanguagePack-webtools.sourceediting-zh_3.7.0.v20111128043401.zip (74.66%)

BabelLanguagePack-webtools.webservices-zh_3.7.0.v20111128043401.zip (76.11%)

解压之后如下：

图2-16 BIRT Eclipse ALL-IN-ONE插件

把它们复制到Eclipse-ALL-IN-ONE的根目录下覆盖即可，重启eclipse即可看到完全汉化的界面。

2.2.2 BIRT Runtime的汉化

Birt的runtime 3.7包中提供了多个servelet（preview、frameset、run等），下面主要对frameset说一下（至于其他的servlet详细解释，可以参考本节后文BIRT servlet详细解释）
frameset：

采用Ajax框架，可以显示工具条，导航条和TOC面板，实现复杂的操作，

如分页处理，导出数据，导出报表，打印等。

该模式下会自动生成report document文件(预览report design文件)到特定的目录

(用户可以用参数指定，也可以定义在web.xml里)。采用Ajax，速度较慢。

frameset特点：

提供报表展示用工具条（导出、打印、分页等）

图2-17 BIRT工具栏之导出报表功能

图2-18 BIRT工具栏之打印报表功能

frameset展示页面开源，后期拓展、自定义修改容易
也许有人会说：其默认的frameset功能不错，但是其界面样式、风格等与公司产品风格不协调，希望对其自定义改造。对于这个问题，开源又一次展现了其魅力。我们完全可以直接去修改webcontent中的内容，按照自己的想法，去修改CSS等。

修改内容：WebViewerExample\webcontent\birt\pages\路径下的文件，比如control路径下的文件
NavigationbarFragment.jsp 用于定制导航栏内容

ProgressBarFragment.jsp 用于定制进度条内容

TocFragment.jsp 用于定制标签目录侧边栏内容

ToolbarFragment.jsp用于定制工具条内容

如下以工具栏按钮为例（ToolbarFragment.jsp），看里头的页面还是写得很清晰的。我们可以定制ToolbarFragment.jsp，让它只显示导出和打印

</>导出

<INPUT TYPE=”image” NAME=’exportReport’ SRC=”birt/images/ExportReport.gif”

TITLE=”导出“

ALT=”<%=BirtResources.getHtmlMessage(“birt.viewer.toolbar.exportreport”)%>” CLASS=”birtviewer_clickable”>

</TD>

打印

<INPUT TYPE=”image” NAME=’print’ SRC=”birt/images/Print.gif”

TITLE=”打印”

ALT=”<%=BirtResources.getHtmlMessage(“birt.viewer.toolbar.print”)%>” CLASS=”birtviewer_clickable”>

</TD>

Dialog路径下的文件用于修改对话框内容，parameter路径下文件用于修改参数对话框的内容，layout用于修改布局。

修改样式：WebViewerExample\webcontent\ birt\styles路径下的文件，用来修改导航栏，工具条，也报表栏，对话框的样式。
BIRT在设计的时候已经考虑了国际化的问题，eclipse官网上得汉化包能很快速地帮助我们解决BIRT汉化的问题。下文将详细说明frameset的汉化。汉化的过程也很方便，大体来说：先到官网下载相应的汉化包，替换viewServlet.jar 包中得messages.properties文件；重新打包viewServlet.jar包即可。
1、下载汉化包

汉化的过程很简单，先到官网下载相应的汉化包，http://download.eclipse.org/birt/downloads/lang.php?build=R-R1-2_2_2-200802271210

我实际操作过程中发现3.7下对应的语言包下载完后没有messages_zh.properties文件，在2.5版本的链接中是有的，所以推荐到2.5中去下。
2、替换viewservlets.jar 部署
2.1找到刚才安装的汉化插件包，进入plugins目录找到一个名为“org.eclipse.birt.report.viewer.nl_zh_*.jar（*代表版本号）的jar包，然后解压，在/org/eclipse/birt/report/resource目录下面会得到一个Messages_zh.properties文件，这个文件就是能够实现汉化的文件啦。

2.2找到birt运行库目录，即默认的birt-runtime-*目录，然后去/WebViewerExample/WEB-INF/lib下找到名为“viewservlets.jar”的jar包，使用压缩工具打开（不用解压），进入/org/eclipse/birt/report/resource目录，这里会发现一个Messages.properties文件，这个就是birt本身带的语言包配置文件啦。

2.3 将在第一步里得到的“Messages_zh.properties”重命名为“Messages.properties”，然后使用压缩工具的“添加”按钮将此文件添加到“viewservlets.jar”文件中（需要点击“覆盖”），这一步的目的就是将英文的配置文件替换为中文的配置。

2.4 将修改后的viewservlets.jar文件添加到工程，或者覆盖原来的viewservlets.jar文件，即可实现birt在客户端的汉化。

2.3 BIRT Runtime配置详解

一.web.xml

参数配置context-param

<!–
 Default locale setting.
 设置默认的Locale信息。
–>
<context-param>
 <param-name>BIRT_VIEWER_LOCALE</param-name>
 <param-value>en-US</param-value>
</context-param>

<!–
 Default timezone setting.
 Examples: “Europe/Paris”, “GMT+1”.
 Defaults to the container’s timezone.
 时区
 格式：”Europe/Paris”, “GMT+1”

默认为容器的时区
 –>
<context-param>
 <param-name>BIRT_VIEWER_TIMEZONE</param-name>
 <param-value></param-value>
</context-param>

<!–
 Report resources directory for preview. Defaults to {birt home}     设置BIRT Viewer的工作目录。     用户可以把report design或是report document文件存放在这个目录下，     这样就可以在URL上采用相对路径去预览这些报表文件了。默认是当前根目录。  -->  <context-param>   <param-name>BIRT_VIEWER_WORKING_FOLDER</param-name>   <param-value></param-value>  </context-param>      <context-param>   <param-name>BIRT_VIEWER_WORKING_FOLDER</param-name>   <param-value></param-value>  </context-param>    
<context-param>
 <param-name>BIRT_VIEWER_WORKING_FOLDER</param-name>
 <param-value></param-value>
</context-param>

<!--
 Temporary document files directory. Defaults to {birt home}/documents
 设置生成的document文件的存放路径。默认是documents目录。
–>
<context-param>
 <param-name>BIRT_VIEWER_DOCUMENT_FOLDER</param-name>
 <param-value></param-value>
</context-param>

<!–
 Flag whether the report resources can only be accessed under the working folder. Defaults to true
 简单的报表访问限制控制实现，如果设为true,哪就只能预览存放在工作目录下的报表文件。默认值是false。
–>
<context-param>
 <param-name>WORKING_FOLDER_ACCESS_ONLY</param-name>
 <param-value>true</param-value>
</context-param>

<!–
 Temporary image/chart directory. Defaults to {birt home}/report/images     设置生成的临时图片的存放路径。默认是report/images目录。  -->  <context-param>   <param-name>BIRT_VIEWER_IMAGE_DIR</param-name>   <param-value></param-value>  </context-param>    <context-param>   <param-name>BIRT_VIEWER_IMAGE_DIR</param-name>   <param-value></param-value>  </context-param>  
<context-param>
 <param-name>BIRT_VIEWER_IMAGE_DIR</param-name>
 <param-value></param-value>
</context-param>

<!--
 Engine log directory. Defaults to {birt home}/logs
 设置生成的日志文件存放路径。默认是logs目录。
–>
<context-param>
 <param-name>BIRT_VIEWER_LOG_DIR</param-name>
 <param-value></param-value>
</context-param>

<!–
 Directory where to store all the birt report script libraries (JARs).
 Defaults to {birt home}/scriptlib     设置用户script lib文件的存放目录( 在报表中用到的Java Event Handler Class )。     默认值是scriptlib。  -->  <context-param>   <param-name>BIRT_VIEWER_SCRIPTLIB_DIR</param-name>   <param-value></param-value>  </context-param>      <context-param>   <param-name>BIRT_VIEWER_SCRIPTLIB_DIR</param-name>   <param-value></param-value>  </context-param>    
<context-param>
 <param-name>BIRT_VIEWER_SCRIPTLIB_DIR</param-name>
 <param-value></param-value>
</context-param>

<!--
 Resource location directory. Defaults to {birt home}
 设置用户资源存放路径，这些资源包括library文件，image文件等。默认是当前根目录
–>
<context-param>
 <param-name>BIRT_RESOURCE_PATH</param-name>
 <param-value></param-value>
</context-param>

<!–
 Preview report rows limit. An empty value means no limit.
 设置获取dataset的最大记录数。
 主要应用于设计报表的时候，预览报表如果记录数太多，会花费很多的时间，也可能会引起out of memory问题。
 默认是不限制。
–>
<context-param>
 <param-name>BIRT_VIEWER_MAX_ROWS</param-name>
 <param-value></param-value>
</context-param>

<!–
 Max cube fetch levels limit for report preview (Only used when
 previewing a report design file using the preview pattern)
 设置CUBE查询的最大级数。和前面的参数作用类似。默认是不限制。
 (仅在preview模式下查看报表时有效)
–>
<context-param>
 <param-name>BIRT_VIEWER_MAX_CUBE_ROWLEVELS</param-name>
 <param-value></param-value>
</context-param>
<context-param>
 <param-name>BIRT_VIEWER_MAX_CUBE_COLUMNLEVELS</param-name>
 <param-value></param-value>
</context-param>

<!–
 Memory size in MB for creating a cube.
 设置在生成CUBE时，可以写在memory中的最大值，单位是MB
 可以提高效率，写在内存会比直接写在硬盘快很多。但同时也要注意内存占用的问题。
–>
<context-param>
 <param-name>BIRT_VIEWER_CUBE_MEMORY_SIZE</param-name>
 <param-value></param-value>
</context-param>

<!–
 Defines the BIRT viewer configuration file
 定义properties文件的路径，不可以修改。
–>
<context-param>
 <param-name>BIRT_VIEWER_CONFIG_FILE</param-name>
 <param-value>WEB-INF/viewer.properties</param-value>
</context-param>

<!–
 Flag whether to allow server-side printing. Possible values are “ON”
 and “OFF”. Defaults to “ON”.
 在frameset工具条上，提供有后台服务器打印的功能，该参数可以设置是打开还是关闭后台打印的功能。
 默认是打开。可选值为: ON 和 OFF。
–>
<context-param>
 <param-name>BIRT_VIEWER_PRINT_SERVERSIDE</param-name>
 <param-value>ON</param-value>
</context-param>

<!–
 Flag whether to force browser-optimized HTML output. Defaults to true
 这个参数是会传递给Engine的，主要用于一些CSS的兼容性方面的问题。默认值是true。
–>
<context-param>
 <param-name>HTML_ENABLE_AGENTSTYLE_ENGINE</param-name>
 <param-value>true</param-value>
</context-param>

<!–
 Filename generator class/factory to use for the exported reports.
–>
<context-param>
 <param-name>BIRT_FILENAME_GENERATOR_CLASS</param-name>
 <param-value>org.eclipse.birt.report.utility.filename.DefaultFilenameGenerator</param-value>
</context-param>

二. Servlet模式说明

<!– Viewer Servlet, Supports SOAP –>
<servlet>
<servlet-name>ViewerServlet</servlet-name>
<servlet-class>org.eclipse.birt.report.servlet.ViewerServlet</servlet-class>
</servlet>

<!– Engine Servlet –>
<servlet>
<servlet-name>EngineServlet</servlet-name>
<servlet-class>org.eclipse.birt.report.servlet.BirtEngineServlet</servlet-class>
</servlet>

<!–

frameset —- 采用Ajax框架，可以显示工具条，导航条和TOC面板，实现复杂的操作，

如分页处理，导出数据，导出报表，打印等。

该模式下会自动生成report document文件(预览report design文件)到特定的目录

(用户可以用参数指定，也可以定义在web.xml里)。采用Ajax，速度较慢。

–>

<servlet-mapping>
<servlet-name>ViewerServlet</servlet-name>
<url-pattern>/frameset</url-pattern>
</servlet-mapping>

<!–

run —- 也采用Ajax框架，但不实现frameset的复杂功能，

不会生成临时的report document文件(预览report design文件)，也不支持分页，

这个主要是应用在BIRT Designer里的preview tab里，

可以支持cancel操作，其它不怎么常用。采用Ajax，速度较慢。

–>
<servlet-mapping>
<servlet-name>ViewerServlet</servlet-name>
<url-pattern>/run</url-pattern>
</servlet-mapping>

<!–

preview — 没有用到Ajax框架，直接调用底层Engine API对报表进行render，

把生成的报表内容直接输出到浏览器。

这种模式和run模式调用的是相同的Engine API，

唯一区别在于run采用Ajax获取报表内容，而preview直接输出到浏览器。

如果要支持分页，用户需要在URL上定义__page和__pagerange参数。

需要特别说明的是，在这几种预览模式中，preview的速度是最快的。

–>
<servlet-mapping>
<servlet-name>EngineServlet</servlet-name>
<url-pattern>/preview</url-pattern>
</servlet-mapping>

<!–

download — 用于导出报表数据，

当你使用frameset工具条里的导出数据功能时，会用到这个模式。

–>

<servlet-mapping>
<servlet-name>EngineServlet</servlet-name>
<url-pattern>/download</url-pattern>
</servlet-mapping>

<!–

parameter — 该模式主要用于生成一个参数对话框，一般用户不常用，

用户可以直接通过提供的JSP Tag–parameterPage去实现参数对话框，不需要直接调用。

–>

<servlet-mapping>
<servlet-name>EngineServlet</servlet-name>
<url-pattern>/parameter</url-pattern>
</servlet-mapping>

<!–

document — 该模式主要是为了从report design文件生成report document文件。

用户可以在URL上提定document文件生成存放的路径(存放在server端)，如果未指定，

会直接生成rptdocument发送到客户端浏览器，用户可以下载到客户端。

–>

<servlet-mapping>
<servlet-name>EngineServlet</servlet-name>
<url-pattern>/document</url-pattern>
</servlet-mapping>

<!–

output — 该模式类似于frameset，会自动生成report document文件(预览report design文件)，

区别在于output不采用Ajax，而是将生成的报表内容直接输出到浏览器。

–>

<servlet-mapping>
<servlet-name>EngineServlet</servlet-name>
<url-pattern>/output</url-pattern>
</servlet-mapping>

<!–

extract—

–>
<servlet-mapping>
<servlet-name>EngineServlet</servlet-name>
<url-pattern>/extract</url-pattern>
</servlet-mapping>

三.viewer.properties参数设置

viewer.properties文件主要是定义一些扩展的参数。

# configurable variable for JSP base href. Please uncomment the below line.
#base_url=http://127.0.0.1:8080
该设置主要应用于代理服务器的情况下，在使用代理服务器后，从request里获取的URI并非真正的URI，需要在这里定义。

# [EXTENSION SETTING]
viewer.extension.html=html
viewer.extension.pdf=pdf
viewer.extension.postscript=ps
viewer.extension.doc=doc
viewer.extension.xls=xls
viewer.extension.ppt=ppt
定义输出的报表文件的后缀名，和format相关联。

# [OUTPUT FORMAT LABEL NAME]
viewer.label.html=HTML
viewer.label.pdf=PDF
viewer.label.postscript=PostScript
viewer.label.doc=Word
viewer.label.xls=Excel
viewer.label.ppt=PowerPoint
定义导出报表对话框里的报表格式列表，和format相关联，这样名字会更有意义。

# [CSV SEPARATOR]
viewer.sep.0=,
viewer.sep.1=;
viewer.sep.2=:
viewer.sep.3=|
viewer.sep.4=/t
支持多种CSV分隔符，用户也可以增加新的分隔符(只支持char，而不是string)。

但同时需要修改JSP文件和Messages.properties文件。

# [LOGGERS]
# “logger.”+class=level
# if no level is specified or the text “DEFAULT”,
# then the default level from the web.xml will be used
logger.org.eclipse.datatools.connectivity.oda=DEFAULT
logger.org.eclipse.datatools.enablement.oda=DEFAULT
当前的日志都是通过Engine输出的，如果需要其它组件的日志输出，可以在这里定义。

注意格式必须为logger.org……。而且该组件必须实现了java的logger。
可以单独为该组件设置日志级别，如果设为DEFAULT，就会使用web.xml里的设置。

四、URL参数

下面是一些主要用到的URL参数。

“__report”
定义要预览的rptdesign文件路径，支持相对路径和绝对路径，相对路径是相对于web.xml中定义的工作目录。

“__document”
定义要预览的rptdocument文件路径，同样支持相对和绝对路径。相对路径是相对于web.xml中定义的工作目录。

在同时定义了__report和__document参数时，以__document为优先，如未找到相应的document文件，

才会从design文件生成document文件(frameset/output)或是直接去render这个design文件(preview/run)。

“__title”
定义报表显示的标题。

“__showtitle”
是否显示frameset模式下上方的标题部分。true | false

“__toolbar”
是否显示frameset模式下的工具条。true | false

“__navigationbar”
是否显示frameset模式下的导航条。true | false

“__parameterpage”
是否强制弹出或不弹出报表参数对话框。true | false

“__format”
输出报表的格式，默认为html。现在支持：pdf | doc | xls | postscript | ppt

“__locale”
设置Locale信息，如 __locale=zh_CN，注意必须是国家加语言。

“__svg”
设置chart输出是否以SVG格式输出。true | false. frameset和run模式下，

会采用javascript判断客户端浏览器是否支持svg，但并非对所有浏览器有效。

“__bookmark”
设置页面要定位的书签名字。

“__istoc”
指定定位的书签是不是一个TOC名字。这个主要用于定位到一个TOC上。

如为true,就会根据__bookmark参数值去获取一个真正的书签名，从而实现正常的跳转。

“__rtl”
指定HTML页面输出是否需要right to left。支持不同国家的阅读习惯，如阿拉伯国家是从右到左的。

“__page”
指定要输出的报表页数，这个依赖于报表的分页设计(page break)。

“__pagerange”
指定要输出的报表页数范围。如1,3,5-9。

“__resourceFolder”
定义资源目录路径。同web.xml中的BIRT_RESOURCE_PATH设置。

“__asattachment”
是否以附件方式下载报表，如生成PDF或是其它格式里。默认是inline。

“__masterpage”
是否要显示master page。true | false

“__designer”
该参数主要是应用在BIRT Designer环境下，如会读取cache的报表参数等等，一般不用。true | false

“__overwrite”
该参数同web.xml定义的参数，不过web.xml里是全局设置，在URL上通过参数可以定义本次操作的设置。

“__imageID”
内部参数，用于image的引用，一般不用。

“__maxrows”
设置Dataset查询的最大记录数，要注意这个设置是全局的，会影响后面所有的请求。

主要用于BIRT Designer下，提高报表设计效率。同web.xml中的BIRT_VIEWER_MAX_ROWS设置。

“__maxlevels”
设置查询获取Cube的最大级数。同上面的__maxrows，也主要用于BIRT Designer设计环境。
同web.xml中的BIRT_VIEWER_MAX_CUBE_LEVELS设置。

“__cubememsize”
同web.xml中的BIRT_VIEWER_CUBE_MEMORY_SIZE参数设置。

“__instanceid”
如果查看BIRT输出的HTML代码，你就可以看到一些HTML Element会有一个iid的属性(如table)，

这个就是instanceid。这个是Engine动态生成的，不可提前预知。

所以你需要从HTML代码中得到这个值。该参数主要是为了获取reportlet(报表片断，

如只输出报表中的一个Table或是一个Chart)。需要配合__isreportlet参数。

“__isreportlet”
       指定当前输出是不是一个reportlet。true | false
       特别说明：为了输出一个reportlet，BIRT现在提供两种方式。
       1．为要输出的对象(表格或是Chart)定义一个bookmark，然后可以用下面的URL输出reportlet.
       http://localhost:8080/birt/frameset?__report=test.rptdesign&__bookmark=bk&__isreportlet=true

2．采用instanceid，但这个值事先是无法预知的，需要预览一次后从HTML代码中得到。

然后用下面的URL输出reportlet.
http://localhost:8080/birt/output?__report=test.rptdesign&__instanceid=iid&__isreportlet=true
还有就是要注意，reportlet只支持document文档。如果是预览design文档去输出reportlet，

就必须要使用frameset/output(自动生成document文档)。

“__clean”
BIRT里临时生成的一些文件都是和session相关的，比如临时document文件，还有image文件。

这些文件也可以通过session进行管理，这个参数就是指定是否需要在session

timeout的时候清除这些临时文件。默认值是true。
true | false

“__dpi”
可以设置输出Chart的dpi数值。

“__fittopage”
暂时这个参数只对PDF和postscript格式报表有效，指定是否调整至适合页面。

“__pagebreakonly”
暂时这个参数只对PDF和postscript格式报表有效，指定是否只采用BIRT报表内定的分页设置。

这个参数一般需要和__fittopage联合使用。

“__agentstyle”
同web.xml中的HTML_ENABLE_AGENTSTYLE_ENGINE参数设置。

========================== 后台Server端打印相关参数 ==========================
“__action” 定义执行的指令名称。当前只支持print指令，用于后台服务器打印。

“__printer” 后台打印机名称。

“__printer_copies” 对应打印机的打印份数参数。

“__printer_collate” 对应打印机的双面打印参数。

“__printer_duplex” 对应打印机的duplex参数。

“__printer_mode” 对应打印机的模式参数。是单色还是彩色。

“__printer_pagesize” 对应打印机的纸型参数。比如A4。

========================== JSP Tag相关参数 ===================================
“__id”
viewer的ID号，这个参数一般不常用，主要用于JSP Tag中，如在一个页面插入两个BIRT Viewer，

而且预览同一个报表文件，这时候因为在一个session下面，所以需要用不同的ID去生成单独的document文件。

不至于都生成同一个document文件上，从而引发冲突。

“__pattern”
在JSP Tag中用于指定要提交的Servlet Pattern名字，如frameset/output/run/preview等。

主要用于采用parameter模式生成parameter dialog对话框时。

“__target”
可以指定提交到的窗口名称。如_blank,_self等。

“__nocache”
指定是否会用到cache的报表参数值，这些cache的值一般保存在rptconfig文件里。

在设计报表并预览的时候，可以保存输入的报表参数值。这个在runtime的时候不常用。

========================== 报表参数相关 ===================================
“__isnull”
指定当前的报表参数为null值，后面是报表的参数名。

“__islocale”
指定当前的报表参数值是和Locale/Format相关的，

必须用特定的Locale/Format转化参数值(从String转化为Object)。格式为__islocale=paramName。

“__isdisplay__”
指定报表参数的displayText值,格式为__isdisplay__paramName=displayText。

可以在报表中引用displayText值，如params[“p1”].displayText。在URL上传displayText时如下(报表参数名为p1)：
&__isdisplay__p1=hello

“__islocale__”
指定该报表参数值是Locale/Format相关的，同时给定了参数值。格式为__islocale__paramName=paramValue。

========================== Export Data参数 ===================================
“__exportEncoding”
该参数应用于导出数据为CSV中，可以指定导出的文件编码，如GBK或是GB2312等。

“__sep”
该参数应用于导出数据为CSV中，可以指定数据分隔符，如逗号，冒号等。

“__exportdatatype”
该参数应用于导出数据为CSV中，可以指定是否输出数据类型。true | false

“ResultSetName”
要导出数据的记录集名字。

“SelectedColumnNumber”
要导出的栏位数。

“SelectedColumn”
要导出的数据栏位名称。

具体可以查看BirtSimpleExportDataDialog.js文件。

五、其它参数设置
在BIRT Viewer里还有一个比较特殊的参数应用，就是用户可以自定义自已的servlet，

然后传递对象到Application Context中，在报表中就可以从全局的Application Context去获取到这个对象。
这里相关的有两个内定的参数，AppContextKey和AppContextValue。下面是一个简单的示例。
public void service( HttpServletRequest request,

HttpServletResponse response ) throws ServletException,IOException, BirtException  {
           String myKeyName = “mykey”;
           List values = new ArrayList();
           values.add( “hello” );  values.add( new Date() );
           request.setAttribute( “AppContextKey”, myKeyName );
           request.setAttribute( “AppContextValue”, values );
           RequestDispatcher rd = request.getRequestDispatcher( ”/frameset” );
           rd.include( request, response );

}

2.4一个简单的BIRT的报表案例

创建报表工程

选择文件->新建->项目。如下图中的新建项目将显示可以创建的项目的类型。

图2-19 新建报表

展开商业智能和报表工具（Business Intelligence and Reporting Tools），选择报表项目（Report Project），然后选择下一步。

在新建报表项目的工程名称中输入下列文本My Report，如图所示：

图2-20 新建报表项目

要添加项目，请选择完成。现在可在导航器视图中看到该项目，如图所示。

图2-21 报表导航器

创建报表

选择文件->新建->报表。如下图：

图2-22 新建报表

选择My Report，输入报表文件名称，如：Customers.rptdesign

选择下一步。

可以通过一下方式创建报表：

从空白报表开始设计

使用预定义的报表模版

图2-23 选择模板

选择完成。新报表将出现在主窗口中，布局编辑器将显示空的报表页。如下图所示：

图2-24报表编辑器

数据源配置

在布局编辑器中开始设计报表之前，构建 BIRT 数据源以将报表连接至数据库或其他类型的数据源。构建数据源时，要指定驱动程序类、数据源名称和其他连接信息（例如，用户名和密码）。Birt自带一个已经配置为与 BIRT 报表设计器配合使用的样本数据库 Classic Models，对于本教程使用的是Derby数据库。

选择数据资源管理器(Data Explorer)。如果使用缺省报表设计透视图，则数据资源管理器位于布局编辑器的左边，在选用板（Palette）的旁边，如图所示。如果它尚未打开，则选择窗口->显示视图->数据资源管理器。

图2-25 数据资源管理器

右键单击Data Sources然后从上下文菜单中选择新建数据源。新建数据源显示可以创建的数据源的类型，如图所示。

图2-26 新建数据源

Classic Models Inc.Sample DataBase ———上面说过是BIRT样本数据库。

Flat File Data Source ———从CSV、SSV、TSV、PSV四种格式的文件获取数据源。

JDBC Data Source ——— 通过配置jdbc连接数据库。

Script Data Source ——— 通过编写脚本获取数据源。

Web Services Data Source ——— 通过web service方式获取数据源。

XML Data Source ——— 从xml文件获取数据源。

这里我们介绍通过示例数据库配置数据源。

图2-27 完成数据源的建立

完成以后编辑数据源，可以看到如下界面

图2-28 测试数据源

测试连接，会看到测试成功。

图2-29 测试数据源成功

后文我们会详细介绍怎么配置JDBC数据源，管理驱动程序。

创建数据集

数据集标识要从数据源检索的数据。我们是通过连接至 JDBC 数据源，则使用 SQL SELECT 语句来标识要检索的数据。

在数据资源管理器（Data Explorer）中，右键单击数据集（Data Set）并从上下文菜单中选择新建数据集。

在新建数据集的数据集名称中，输入下列文本，如图所示：

图2-30 新建数据集

对于其他字段选择缺省值。

Data Set Types 数据集类型一般使用jdabc数据源连接分为两种：一种是SQL Select Query为select查询，一种是SQL Stored Procedure Query存储过程查询（使用存储过程查询，必须数据库中已创建存储过程）。

Data Source显示先前创建的数据源的名称。

Data Set Types 指示该数据集使用 SQL Select Query查询。

选择下一步（Next）。

查询显示可帮助您创建 SQL 查询的信息。可用项列示数据库中的所有表。可以单击表旁边的加号（+）标志来显示该表的各个列。编辑数据集右边的文本区域显示 SQL SELECT 语句的必需关键字：

在文本区域中，输入下列 SQL SELECT 语句以指定要检索的数据：

如：select * from CLASSICMODELS.CUSTOMERS

虽然数据集编辑器以大写字母显示表和列名称，但可用您喜欢的方式输入这些名称，因为 SQL 不区分大小写。如果您不想输入查询，则可将列和表从可用项拖动到文本区域。

图2-31 编写查询sql

选择完成（Finish）以保存数据集。编辑数据集将显示在查询中指定的列，并提供编辑数据集的选项。

选择预览结果（Preview Results）以确保查询有效并且它返回正确的数据。如果正确输入了 SELECT 语句，您应该看到图中显示的结果。这些是查询返回的数据行。

图2-32 预览查询结果

选择确定，数据集创建成功。

对报表进行布局

1．在本过程中，您在报告页中插入元素以显示先前创建的数据集的数据。先插入一个表元素，然后在该表中插入数据元素。

2．选择选用板“画板（Palette）”。选用板显示所有可布置在报告中的元素。

3．为了以后的表布局美观，我们先从选用板中的“网格（Gird）”元素拖拽放入布局编辑器内（即文件的“布局（Layout）”视图）的报告中，插入时提示您要制定创建的行列数的详细信息：输入1列2行，

4．然后，将选用板中的表元素“表（Table）”拖放到布局编辑器内的报告中。插入表提示您指定要对此表创建的列数和详细信息行数。指定5列和1个详细信息行，然后选择“确定”。具有5列和1个详细信息行的表将出现在布局编辑器中。现在，您就可以在该表中插入数据了。

图2-33 插入网格

图2-34 插入表

5．选择数据资源管理器（Data Explorer）视图。在数据资源管理器视图中，展开“数据集（Data Sets）”，然后展开Customers，在查询中指定的列将出现在Customers下面。

将CUSTOMERNAME从Data Explorer中拖放到表的详细信息行“Detail Row”中的第一个单元格内（如下图）。详细信息行显示报告中的主要数据。在完成的报告中，详细信息行重复显示数据集中的所有数据行。

图2-35 插入数据项

6．然后采用同样的方法将CUSTOMERNUMBER，SALESREPEMPLOYEENUMBER，ADDRESSLINE1，PHONE这四个数据项从Data Explorer中拖放到表的详细信息行中，完成的报告中，详细信息行重复显示数据集中的所有数据行。如下图：

图2-36 表格布局

7．选中报表格左下角的“”（如上图），在下方的视图中会显示本Table的信息：

图2-37 属性编辑器

选择第二项“绑定”，将数据集的下拉框选为“Customer”，下方的Data Colum Binding中就会显示我们数据集中的数据项，通过此步我们将本报表与数据集绑定起来，否则将不能显示（一般将数据集中的数据项拖拽如Table中后，会自动将次数据集的数据项与本报表绑定，我们可以不用进行这步操作。但我们必须得清楚这个操作）。

完成后，表格的基本设置就算做完了。

格式化与预览

通过布局编辑器中选择“Preview”可对我们设计的报表进行预览。

我们通过一系列格式化操作，将报表进行美化。

完成以后则可，通过工具栏中提供的各种不同的视图模式来进行预览，如下：

图2-38 数据预览

使用默认的在Web查看器中查看报表预览结果如下：

图2-39 在web容器中预览报表

这个报表只是一个最基本的报表，后文会详细讲解怎么设置格式，样式，布局，美化报表。