第三章 BIRT数据源的配置（续)

 

Web Services 技术是一套标准，它定义了应用程序如何在 Web 上实现互操作。用户可以使用任何语言，在不同的平台下编写 Web Services，然后通过 Web Services 的标准来对这些服务进行注册、查询和访问。BIRT 可以方便的帮助用户访问基于 SOAP 的 Web Services，并且使用 SOAP 响应作为生成报表的数据。

支 持 使 用 WSDL 文 件 定 义 数 据 源 和 数 据 集 。 WSDL 文 件 是 一 种 常 用 的 WebServices 服务描述语言。BIRT 可以解析 WSDL 文件，帮助用户定义 SOAP 查询和使用 SOAP 响应包含的信息生成报表。用户可以为一个 Web Services 数据集定义参数并在 SOAP 请求中使用有一些案例，BIRT 使用 WSDL 自动生成的 SOAP 请求模板是无效的，这时用户可以对模板进行手工修改用户可以提供一些实现了 BIRT 定义的连接和查询接口的 Java 类作为数据源。SOAP 响应使用 XML 格式，用户可以可视化的把 XML 格式的 SOAP 响应映射为一个表结构。具体的操作与定义 XML 数据集的操作相同。

选择数据源类型

指定 Web Services 的连接属性

WSDL URL 或位置用户指定要连接的 Web Services 的 WSDL。本文例子用的是 Google 提供的 WebServices。SOAP 终结点（End Point） 和自定义驱动类SOAP 终结点是一个接收 servlet，具体的作用可以参考参考文献[4]。

如果用户指定了自定义驱动类，BIRT 就会使用它来连接访问 Web Services。在这种情况下，SOAP End Point 可以为空；如果 SOAP 终结点不为空，它将作为一个连接属性被传递给用户指定的驱动的 connect 方法。如果自定义驱动类为空并且 SOAP 终结点不为空，BIRT 将使用 SOAP 终结点建立SOAP/HTTP 连接。自定义驱动类是一个 Java 类的全名，这个 Java 类必须在应用的 class path 上或者驱动程序类路径指定的 class path 上，另一种办法是把所需要的 Java 文件放在 BIRTplugins "org.eclipse.datatools.enablement.oda.ws"的 lib 目录中。这个类必须实现下面的方法来建立 Web Services 连接。

测试连接按钮可以用来测试用户输入的连接当前是否是可以连通的。

建立一个 Web Services 数据集

选择在 WSDL 中定义的操作

这个对话框显示一个树结构，包含所有在 WSDL 中定义的操作。用户可以选择一个操作，并在以后的步骤中创建基于该操作的 SOAP 请求模板，如果用户没有指定 WSDL本步骤将被跳过。本文选择的操作是 doGoogleSearch，选择需要的参数

这些参数是 BIRT 根据上一步选择的操作解析 WSDL 文件得到的。选中的参数会出现在下一步的 SOAP 请求模板中，没选中的参数则不会出现在 SOAP 请求模板中。编辑 SOAP 请求模板

用户可以对 BIRT 自动生成的 SOAP 请求 模板进行修改SOAP 信息必须通过 XML 进行编码，具体的语法可以参考 SOAP 语法方面的文档。参数名的格式为“&?参数名?&”。用户可以使用插入参数按钮给 SOAP 请求 参数设置缺省值。清除按钮可以用来清除整个模板文本。定义 SOAP 响应

用户可以使用这个对话框定义 SOAP 响应架构(schema)和选择一个 SOAP 响应消息的例子。指定 SOAP 响应 架构是把 SOAP 响应消息映射为表格式的数据集的先决条件。用户可以选择在 WSDL 文件中定义的响应 架构，这是缺省选项。用户也可以选择一个外部的 XML 架构(XSD)文件作为响应 架构。在 SOAP 终结点查询 Web Services 指定一个 Web Services 查询来获得一个 SOAP 响应消息作为示例数据来源。使用外部示例文件是允许用户选择一个外部文件来提供一个例子 SOAP 响应消息。示

例文件必须是用 XML 格式编码，只需要包含 SOAP 响应消息的数据部分就可以了。把 SOAP 响应消息映射为表格式的数据集

从这个步骤开始与定义 XML 数据集的相关步骤是相同的。

3.6 文本数据源

一. 新建文本数据

1. 新建文本数据文档,文档后缀名可以是txt,或者是csv.在这里我们来建立一个后缀名为txt的文本文件,名称为TextSource.txt.

2. 文本数据格式:

第一行是字段名称,每个字段之间必须用逗号隔开.

第二行是字段类型,每个类型名称之间必须用逗号隔开.

第三行是字段内容,每个内容之间必须用逗号隔开,如果是字符串类型的,就用双引号括起来.

每行之间不能有空行,必须一行结束后,紧接着另一行.例如:

3. 文本数据格式举例:

Name,Sex,Age,Address,Date

STRING,STRING,INT,STRING,TIME

"xiaozheng"," female",520,"Monthly",01/31/2003/ 09:59:59 AM

"xiaodan"," female",520,"Monthly",01/31/2003/ 09:59:59 AM

"lianglaing","male",66666,"Monthly",01/31/2003/ 09:59:59 AM

二. 新建数据源

1. 在birt左上方的资源管理器中选择新建数据源,选择平面文件数据源.

2. 数据源名称为TextDataSource,点击Next,选择你的文本文件所在文件夹,字符集默认.

3. 点击测试连接.

三. 新建数据集

1. 在birt左上方的资源管理器中选择新建数据集,选择TextDataSource数据源.

2. 数据集名称为TestDataSet,点击Next.选择文件筛选中的*.txt.因为我们建立的数据文本是txt的.

3. 选择TextSource.txt文本文件.

4. 选择后,在右边会出现文本数据的字段名称,全部选中到左边,点击完成.

5. 如图:

四. 预览文本数据效果

1. 将新建的TextDataSet数据集拖动到报表编辑页面中,然后预览,就可看到效果.

2. 如图:

3. 最终效果如图:

3.7 平面文件数据源

1 平面文件数据源的类型

在这里，对于我们正在介绍的BIRT而言，可以接受作为数据源的平面文件类型共有4种： *.CSV， *.SSV，*.PSV，*.TSV。

2 四种平面文件类型的区别

2.1 CSV文件

CSV文件——comma separated value，也叫逗号（,）分隔值文件，即文件内容用逗号来分割数值。

文件定义格式示例如下：

2.2 SSV文件

SSV文件——semicolon separated value，也叫分号（;）分隔值文件，即文件内容用分号来分割数值。

文件定义格式示例如下：

2.3 PSV文件

 PSV文件——pipe separated value，也叫pipe符号（|）分隔值文件，即文件内容用pipe符号来分割数值。

文件定义格式示例如下：

2.4 TSV文件

TSV文件——tab separated value，也叫tab符号分隔值文件，即文件内容用tab符号来分割数值。

文件定义格式示例如下：

从以上的定义就可以发现，这四种文件的主要不同之处在于定义时所用来分割数值的分隔符不同。

3 BIRT 定义的平面文件格式和规则

下面我们介绍一下BIRT对于合法平面文件的的格式和规则要求。

首先，除了分隔符可以不同之外，其余的必须遵循CSV文件的规范。

关于CSV文件的一些详细介绍，请参考技术文档：

http://en.wikipedia.org/wiki/Comma-separated_values

其次，必须遵循BIRT的特殊规定：

每一行的数据，列的数量必须一致，但列的内容可以为空。

对定义的数据类型有一定的限制，对各数据类型的数据定义格式也有一定的要求和限制。

4 BIRT 平面文件驱动支持的数据类型

对于BIRT 平面文件驱动而言，其支持的数据类型有：整数, 浮点, 字符串, 日期, 日期时间，时间，小数, 布尔。

5 平面文件中可定义的数据类型

在作为数据源的平面文件中，BIRT支持的数据类型有更加广泛的定义方式。

下表向用户直观地描述了平面文件中定义的数据类型和BIRT驱动支持的数据类型之间的转换关系。

平面文件中定义的数据类型

转换成BIRT支持的数据类型

CHAR, VARCHAR, STRING, LONGVARCHAR, CLOB, BLOB,ANY, BINARY, VARBINARY, LONGVARBINARY

字符串

BIT, INT, INTEGER, SMALLINT, TINYINT

整数

BIGINT, DECIMAL, BIGDECIMAL, NUMERIC

小数

FLOAT, DOUBLE, REAL

浮点

TIMESTAMP, DATETIME

日期时间

DATE

日期

TIME

时间

BOOLEAN

布尔

6 一些特殊数据类型的数据定义格式

BIRT的数据类型

平面文件数据的解析规则

源数据示例

日期

先根据ISO8601标准进行解析，如果无法解析则根据本机JRE的locale设置来解析，如果仍无法解析再根据美国的locale解析。合法的源数据最后将被解析构造成一个java.util.Date对象。

2006-6-12;

2006-8-12

时间

先按照上述日期类型的解析规则将源数据解析成一个java.util.Date对象；如果解析成功则获取此对象的时分秒信息得到一个java.sql.Time对象；如果无法解析，则按照【时:分:秒】或者【时:分:秒 AM/PM】的格式来解析并获取源数据的时、分、秒数值，构造成一个java.sql.Time对象。

2006-6-12 2:04:00;

11:25:39 

日期时间

1.如果源数据的格式符合

【yyyy-mm-dd hh:mm:ss.fffffffff】格式，则直接用java.sql.TimeStamp.valueOf(stringValue) 来得到一个java.sql.TimeStamp对象；

2.如果源数据为长整型，则直接用new java.sql.TimeStamp( longValue ) 得到一个java.sql.TimeStamp对象；

3.按照上述日期类型的解析规则解析源数据并得到一个java.util.Date对象，然后通过

new java.sql.TimeStamp

(java.util.Date.getTime())

方法得到一个java.sql.TimeStamp对象。

328000000;

2006-6-12 11:25:39

7. 使用BIRT创建平面文件数据源

7.1 新建平面文件数据源

用户在“数据资源管理器”视图上选择新建一个平面文件数据源的时候，需要指定所选定的平面文件的文件类型以及此文件所在的目录。BIRT可以接受本地磁盘目录或者是其它符合文件协议的目录。另外，用户还需要选择一个和此平面文件相应的编码方式。

操作界面如图4-1所示。

图 4-1 新建平面文件，指定文件夹及其它属性

7.2 设定平面文件的映射规则

从图 4-1，用户也应注意到新建平面文件数据源的界面上有两个选项可供选择：

将第一行用作列名称指示器。

将第二行用作数据类型指示器。

7.2.1将第一行用作列名称指示器

勾选此项BIRT将会把平面文件的第一行作为结果集的字段名来处理。

否则，第一行的数据将会被视作结果集第一条记录的值进行映射。

需要注意的是，如果此项未被勾选，则第二个选项将不开放操作，即平面文件里的第二行数据将被视作结果集第二条记录的值进行映射，而非各字段的数据类型。

7.2.2将第二行用作数据类型指示器

勾选此项BIRT将会把平面文件的第二行作为结果集的各字段数据类型来处理。

否则，第二行的数据将被视作结果集第一条记录的值进行映射，而非各字段的数据类型。

7.3 测试平面文件的连接

在设定完所有的选项之后，可以通过“测试连接”按钮测试所指定的文件目录是否存在。

8.  编辑平面文件数据源

假设我们已经建立了一个名为“数据源1”的平面文件数据源，可以在“数据资源管理器”视图区域选择它进行编辑。

打开编辑对话框之后，用户将会看到左边的导航栏提示有三个类别的操作：

平面文件数据源连接属性

连接配置文件

属性绑定

8.1平面文件数据源连接属性

这个操作页面类似于新建平面文件数据源的界面和操作，用户可以修改各选项，重新定义属性。此时当先前指定的平面文件路径不存在的时候，在对话框的上部将会显示错误信息。如图 5-1 所示。

图 5-1 编辑平面文件的连接属性时，因指定的路径非法而显示错误信息 1

此时，如果通过“测试连接”按钮进行连接测试，将会得到“Ping失败”的结果提示。

8.2属性绑定

这个页面提供给用户修改连接属性的途径，部分类似于在“平面文件数据源连接属性”页面的同类功能。操作界面如图4所示。

下面介绍一下此页面各个属性的含义和输入规范。

注意：所有的输入必须符合JavaScript的表达式规范，如果值是个字符串，必须加上双引号。

主文件夹：找到平面文件的路径。

CSV类型：平面文件的类型；可选填4种平面文件的类型之一。

字符集：通过java.nio.charset.Charset.availableCharsets( )获取所有Java虚拟机支持的字符集，具体的字符集列表可参考技术文档：

http://www.iana.org/assignments/character-sets

值得注意的是，Unicode规范中有一个较为特殊BOM的概念。BOM——Byte Order Mark，就是字节序标记。UTF-8、UTF-16编码往往会包含BOM这种特殊的字符，其中UTF-16 BOM又分为两种形式：

UTF-16:le(Little- Endian) 和UTF-16:be(Big- Endian)。

现在许多软件不予以支持BOM，而BIRT在这一点上却提供了良好的支持。BIRT在读取源文件时会主动识别其是否为UTF-16LE（不使用BOM）或者UTF-16BE（不使用BOM）编码。如果是其中之一则直接将字符集名作为参数传给java.io.FileInputStream对象，如果不是，则将编码方式设为默认的UTF-8。在使用UTF-8编码方式时，BIRT会主动识别源文件是否为UTF-8 BOM编码，如果包含BOM，将会对于读入的字节流做特殊处理，以保证读取数据的正确性。

使用第一行用作列名称指示器：输入true，表示使用第一行用作列名称指示器，反之输入false。

使用第二行用作数据类型指示器：输入true，表示使用第二行用作数据类型指示器，反之输入false。

图 5-2 编辑平面文件数据源的属性绑定

如图 5-2 所示，在属性绑定页面里在各个属性的对应文本编写区域内手动输入了一些JavaScript表达式。在真正运行报表时，这些属性值将起作用。

换句话说，在平面文件数据集的编辑页面预览结果时，这些属性的设置并不起作用，仍然采用“平面文件数据源连接属性”的设置。但在BIRT的“布局”区域真正设计报表、绑定此数据集，并且进行预览时，这些值才会工作。

9. 平面文件数据集

9.1 新建平面文件数据集

现在有一个已经建好的平面文件“chart.csv”,放在“D:\BIRT DEV\CSV”目录下，其内容如下：

ONumber,StartDate,EndDate,Status,Pnumber,Value1,Value2,High,Close,Low,Open

INT,DATE,DATE,STRING,INT,Double,Double,Double,Double,Double,Double

,2006-6-12,2006-8-12,,363,15.29,,27.7,27.3,26.9,27.1

101,2006-4-22,2006-5-22,b,128,14.53,156.55,28,26.4,26,27.1

102,2006-5-18,,c,,32.55,95.25,25.41,25.28,25.13,25.19

新建平面文件数据源“数据源”，把“D:\BIRT DEV\CSV”设为主目录。

新建平面文件数据集，进入“选择表”的页面之后，可以自由选择指定查找的文件夹路径下的所有符合指定文件类型的合法平面文件。

我们选择“chart.csv”,之后在左边区域的表中会列出此文件内的所有合法字段，用户可以单选或多选所需字段，映射到右边的表格中，作为新建的平面文件数据集的字段。

如图 6-1-1如果用户选择不使用平面文件的第一行作为数据集的字段名，那么BIRT将会依次给作为数据源的平面文件和数据集的字段按照column_[index]的规则命名。

图 6-1-1 不使用第一行作为列名指示器

在图 6-1-2所示的界面中，我们可以看到右边的表里面有3个字段，分别是名称, 原始名称以及类型。

名称：当前的平面文件数据集的各个字段名，允许用户在不重名的条件下修改。

原始名称：在作为数据源的平面文件中，被选择映射的字段名，这是不可修改的。

类型：经过BIRT转换之后的各字段数据类型，允许用户通过下拉菜单重新选择数据类型。

图 6-1-2 为数据集选择列 1

图 6-1-3 数据集的名称可编辑修改

如图 6-1-3所示，用户可以在不重名的条件下修改数据集的列名称。

如图 6-1-4所示，用户可以在不重名的条件下修改数据集各列的数据类型。

图 6-1-4 数据集的类型可通过下拉框重新选择 1

如果所指定的文件夹路径下并不包含任何合法的平面文件，在页面的上部也会做相应的信息提示。如图 6-1-5所示。

图 6-1-5 指定文件夹不包含合法的平面文件

完成之后，一个基本的平面文件数据集就建成了。

9.2 编辑平面文件数据集

现在，已经建好了一个名为“数据集1”的平面文件数据集，用户之后可以打开进行一些编辑操作，例如添加筛选器，或者是计算列，之后可预览结果。如图 6-2-1所示。

图 6-2-1 预览数据集的结果

9.3平面文件数据源不同映射规则的预览结果比较

在这里，我们给用户展示一下之前对平面文件数据源不同映射规则设定下，预览结果的不同，以期给用户一个更加直观的理解。

假设有这样一个平面文件table-semicolon.ssv，其内容格式定义如下：

INT0_COL;DOUBLE0_COL;STRING_COL;DATE_COL;TIME_COL;TIMESTAMP_COL;

INT;DOUBLE; STRING; DATE; TIME; TIMESTAMP;

0;0.22077730306828824;S0.43336868;2000-1-1;00:04:00;250000000

1;0.03296764101523675;S0.70705503;2001-2-2;01:04:00;250000000

2;0.6608755794157164;S0.6333958;2002-3-3;02:04:00;250000000

3;0.38373945059170766;S0.8294698;2003-4-4;03:04:00;250000000

4;0.16351305975663322;S0.73003954;2004-5-5;04:04:00;265000000

9.3.1 “将第一行用作列名称指示器”选项

新建名为“数据源1”平面文件数据源，将此平面文件（table-semicolon.ssv）所在目录设为查找目录。在平面文件数据源的属性设置页面中，勾选“将第一行用作列名称指示器”，如图 6-3-1所示。

图 6-3-1勾选“将第一行用作列名称指示器”

我们再建立一个名为“数据集1”的平面文件数据集，以“数据源1”作为其数据源。并选择“able-semicolon.ssv”做列映射。我们可以看到此时将会把able-semicolon.ssv文件中的第一行作为列名来处理。

图 6-3-2 将第一行作为列名来映射

如图 6-3-2所示，此时第一行数据将会被作为列名来映射。其预览结果如图 6-3-3所示。

图 6-3-3 将第一行作为列名来映射的数据集预览结果

我们重新回到“数据源1”的属性编辑页面，勾除“将第一行用作列名称指示器”，如图 6-3-4所示。

图 6-3-4 勾除“将第一行用作列名称指示器”

打开相应的数据集“数据集1”， 我们将会看到此时的列名遵循【COLUMN_INDEX】的形式来定义。初始的数据类型均为字符串类型。如图 6-3-5 所示。

图 6-3-5 勾除“将第一行用作列名称指示器时”的列名

预览结果，我们将会看到平面文件中定义的第一行数据作为了“数据集1”的第一条记录值进行映射。如图 6-3-6 所示。

图 6-3-6 勾除将第一行用作列名称指示器时的预览结果

9.3.2 “将第二行用作数据类型指示器”选项

如图 6-3-7所示，将“数据源1”的平面文件数据源属性中勾除“将第二行用作数据类型指示器”选项。

图 6-3-7 勾除 将第二行用作数据类型指示器选项

新建一个以“数据源1”为数据源的平面文件数据集“数据集2”，此时可以在如图 6-3-8中看到平面文件的第一行作为了数据集的列名来映射，而数据类型均设为默认的“字符串”类型。

图 6-3-8 平面文件数据集的列选择

此时预览结果，可以看到平面文件中的第二行数据并没有作为数据类型指示器，而是映射成为了结果集的第一条记录值，如图 6-3-9 所示。

图 6-3-9 预览结果，第二行数据作为字段的值显示

图 6-3-10 勾选将第二行用作数据类型指示器

回到“数据源1”的属性编辑页面，勾选“将第二行用作数据类型指示器”，如图 6-3-10所示，之后新建一个平面文件数据集“数据集3”，仍然以“数据源1”作为数据源。我们可以看到平面文件的第二行数据作为数据类型映射至数据集，如图 6-3-11所示。

图 6-3-11 勾选“将第二行用作数据类型指示器”的数据类型映射

预览结果如图 6-3-12所示，不难发现，平面文件的第二行数据没有出现在数据集的记录中。

值得注意的是，比较图 6-3-9 和图 6-3-12，我们可以看到 “TIMESTAMP_COL”一栏的数据显示的不同。如果用户没有勾选“将第二行用作数据类型指示器”，BIRT给予默认数据类型“字符串”，如果用户也没有手动进行修改，则最后显示的就是平面文件中的数据；而当用户勾选这一项之后，第二行数据类型发生作用，此时“TIMESTAMP_COL”的数据类型“日期时间”从平面文件的第二行数据映射而得，在经过BIRT的重新解析和转换之后最终在结果集中以“日期时间”的格式显示。

图 6-3-12 第二行数据没有成为结果集的记录值