皕杰报表开发指南--v3.5

皕杰商务智能平台
报表产品v3.5
(开发指南)
北京皕杰汇智科技有限公司
目录
一、皕杰报表参数说明 (2)
1.1S ERVLET方式 (2)
1.2T AG L IB标签应用 (4)
1.2.1 HTML发布报表 (4)
1.2.1.1 原理和用途 (4)
1.2.1.2 详细说明 (4)
1.2.2 参数表单 (5)
1.2.2.1 原理和用途 (5)
1.2.2.2 详细说明 (6)
1.2.3 多表Tab标签 (7)
二、JA V A自定义扩展 (7)
2.1自定义数据集 (7)
2.1.1用途 (7)
2.1.2类介绍 (8)
2.1.3构造方法 (8)
2.1.4 方法说明 (8)
2.1.5. 实用示例 (9)
2.2自定义事件处理类 (9)
2.2.1用途 (9)
2.2.2接口介绍 (9)
2.2.3方法说明 (9)
2.2.4实用示例 (10)
2.3自定义用户工厂 (10)
2.3.1用途 (10)
2.3.2接口介绍 (10)
2.3.3方法说明 (10)
三、API编程 (12)
3.1读入报表模板 (12)
3.2计算报表 (12)
3.3输出报表 (13)
3.4分页设置 (14)
3.5编辑报表模板 (14)
一、 皕杰报表参数说明
在web 报表的实际应用过程中，有一些数据及页面显示效果是要根据用户的实际需要皕进行调整的，为了满足用户的这一需求，杰报表设计了一些内置参数。

皕杰报表中，将参数传递给报表引擎的方式有两种：一是Servlet 方式，二是Taglib 标签方式。

1.1 Servlet 方式
采用Get 或Post 方式的url 请求ReportEmitter ，并在后面拼接请求的内置参数名称和值，参数之间用“&”符号连接。

例如：http://IP 地址：服务器端口/web 路径/ReportEmitter?rpt=Demo/参数报表/时间参数.brt&params=year=1997;area=华南区。

其中，“rpt ”和“params ”就是内置参数名称；“Demo/参数报表/时间参数.brt ”和“year=1997;area=华南”为内置参数的值。

注意：要把内置参数和用户参数区分开，内置参数是报表系统内部定义好的参数，指定了参参数说明见下表：
数名称和参数值的类型；用户参数是用户在设计报表时的自定义参数，例子中的“year ”和“area ”就是用户自定义参数。

本章所提到的“参数”一词，均皕指杰报表的内置参数。

是否
参数名
参数说明 参数值 缺省值
必填
rpt 是 指定报表模板
报表模板的路径
无
brf 否 报表模板是否为brf 文件 true 或false false rptobj
否
指定Object 类型的报表模板
Object 对象 无
emitter 否 报表的输出方式 为html 文件xls 另存为Excel 文件
topdf 另存为PDF 文件txt 另存为TXT 文件rint 输出到打印
tohtml
tohtml 另存
to
to
p params 否
报表模板中的用户自定义参数参数名1=参数值1；参数同报
表模，格式为“params=自定义参数名称1=参数值1；自定义参数名称2=参数值2；……” 名2=参数值2；…… 板中的参数名
和默认值
参数名
是否
必填
参数说明 参数值 缺省值
vars 否
报表模板中的用户自定义
变量，格式为“vars=变量名1=
变量值1；变量名2=变量值
2；……”
变量名1=变量值1；
变量名2=变量值2；……
同报表模
板中的参
数名和默
认值
page 否
指定显示页的序号，即要显
示第几页，当序号不存在时，默
认设为缺省值
正整数 1
rfscache 否是否刷新缓存 true或false false
pagecap 否
html页面上每页显示的行
数
正整数
同设计器
中报表模
板的设置
rptwidth 否报表在web上的输出宽度整数或百分比 750 rptheight 否报表在web上的输出高度整数或百分比 500 fitwidth 否报表宽度是否自适应拉伸 true或false false
toolbardisplay 否
工具条在页面上的显示位
置
top-在表格上方显示
bottom-在表格下方
显示
none-不显示工具条
bottom
xlsbtn 否
工具条中是否显示整页导
出Excel按钮
true或false true
xlsbtn1 否
工具条中是否显示分页导
出Excel按钮
true或false true
pdfbtn 否
工具条中是否显示导出
PDF按钮
true或false true
docbtn 否
工具条中是否显示导出
DOC按钮
true或false true
printbtn 否
工具条中是否显示打印按
钮
true或false True
ReportConfigR
eload 否配置文件热加载接口无无
注：1、当“brf=true”时，rpt参数的参数值所指向的报表模板应为brf文件。

2、“rpt”和“rptobj”两个参数必须设置一个，并且只能这只一个。

1.2 TagLib标签应用
1.2.1 HTML发布报表
1.2.1.1 原理和用途
通过定义Tag 皕
标签的属性及其值，在不需用户调用杰API 情况下，用tag标签完成报表的解析及运算，并按用户配置的属性要求将HTML 文件流输出到客户端。

1.2.1.2 详细说明
报表在JSP文件中用<prefix:report>标签来发布，prefix是用户在JSP文件头中引用tag 标签时指定的前缀名。

该定义语句如下所示：
<%@ taglib prefix="bios" uri="/BiosReportTags" %> 此定义语句必须写在JSP的开头，其中prefix的值可以自己指定，但tag标签中的前缀必须与其保持一致。

然后在要发布报表的地方用上面介绍的tag标签来发布，如：
<bios:report rpt="<%=rpt%>" params="<%=params%>" ……/>
此标签的属性说明见下表：
(属性名都是大小写相关，属性值必须放在双引号中)
参数名是否
必填
参数说明参数值缺省值
rpt 是指定报表模板报表模板的路径无
brf 否报表模板是否为brf文件 true或false rptobj 否指定Object类型的报表模板Object对象无
params 否
报表模板中的用户自定义参
数
参数名1=参数值1；参数
名2=参数值2；……
同报表模
板中的参
数名和默
认值
vars 否
报表模板中的用户自定义变
量
变量名1=变量值1；变量
名2=变量值2；……
同报表模
板中的参
数名和默
认值
rfscache 否是否刷新缓存 true或false false
pagecap 否 html页面上每页显示的行数正整数同设计器中报表模板的设置
rptwidth 否报表在web上的输出宽度
整数、百分比、脚本表达
式
750
是否参数名 参数说明 参数值
缺省值
必填 rptheight 否 报表在web 上的输出高度 整数、百分比、脚本表达
式 500
fitwidth
否
报表宽度是否自适应拉伸 true 或false false
toolbardisplay 否 是否显示工具条
top-在表格上方显示 bottom-在表格下方显示 none-不显示工具条
true
xlsbtn 否 工具条中是否显示整页导出Excel 按钮
true 或false true
xlsbtn1 否 工具条中是否显示分页导出Excel 按钮
true 或false true
pdfbtn 否 工具条中是否显示导出PDF 按钮
true 或false true
docbtn 否 工具条中是否显示导出DOC 按钮
true 或false true
printbtn 否 工具条中是否显示打印按钮true 或false true name
否
reportSet 标签中，report 元素需设置该属性，做为tab 标签页的标题
字符串
无
1.2.2 参数表单
1.2.2.1 原理和用途
在有些报表中，需要向报表传递一些参数或变量，传统的方式是要用户定义参数表单，如：
<form method="post" action="<%=request.getContextPath()%>/report.jsp"> <table><tr style =
"FONT-SIZE: 12px; FONT-FAMILY: 宋体"> <td>性别</td> <td>
<select name =
"sex"> <option value =0>男</option> <option value =1>女</option> </select> </td>
<td>&nbsp;<input type =
submit value =
"提交"></td> </tr> </table> </form>
这样做起来会很麻烦，因为所建参数要与报表中的参数或变量个数一致，名称及大小写一致，然后从requeset 中获取参数拼成字符串，通过url 或tag 标签传递到报表中。

为了节省用户的开发时间，可以使用Tag 标签生成参数表单，用户根据需要，在设计器中将参数及
变量设计成参数表单形式，为每个参数或变量设定显示名称、控件类型及所占列数等属性，在WEB 服务端通过<prefix:param>标签对本参数模板解析生成对应的参数表单。

设计参数报表 WEB 端显示效果
1.2.2.2 详细说明
报表在JSP 文件中用<prefix:param>标签来发布，prefix 是用户在JSP 文件头中引用tag 标签
时指定的前缀名。

该定义语句如下所示：
<%@ taglib prefix="bios" uri="/BiosReportTags" %>
此定义语句必须写在JSP 的开头，其中prefix 的值可以自己指定，但tag 标签中的前缀必须与其保持一致。

然后在要发布报表的地方用上面介绍的tag 标签来发布，如： <bios:param rpt ="<%=rpt%>" target="reportFrame"……/> 此标签的属性说明见下表：
(属性名都是大小写相关，属性值必须放在双引号中)
参数名 是否
必填 参数说明 参数值 缺省值
rpt 是 指定报表模板
报表模板的路径 无
target 否 连接页面在浏览器中的打开形式 _blank/_self/_parent/指定frame 的name 属性值 formId 否 为生成的表单指定id 属性值 字符串
action 否 指定表单提交路径 表单提交到的servlet 或jsp 路径字符串
width 否 参数表单页面显示宽度 整数、百分比、脚本表达式 height 否 参数表单页面显示高度 整数、百分比、脚本表达式 hiddenParams
否
隐藏的参数
参数名1=参数值1；参数名2=参数值2；……
hiddenVars 否 隐藏的变量 变量名1=变量值1；变量名2=变量值2；……
1.2.3 多表Tab 标签
报表在JSP 文件中用<prefix:reportSet>标签来发布，prefix 是用户在JSP 文件头中引用tag 标签时指定的前缀名。

该定义语句如下所示： <%@ taglib prefix="bios" uri="/BiosReportTags" %>
此定义语句必须写在JSP 的开头，其中prefix 的值可以自己指定，但tag 标签中的前缀必须与其保持一致。

reportSet 是用来以Tab 页面的形式显示多张报表或多个页面。

与前两个标签不同，此标签需要与report 、reportItem 标签同时使用。

在一对reportSet 标签中，有多个report 、reportItem 标签。

这里先介绍一下reportItem 标签。

reportItem 为reportSet 的子标签，用来显示普通html 或非报表显示的页面。

此标签的属性如下表：
参数名 是否必填 参数说明 参数值 缺省值
name 是 reportSet 标签中，做为tab 标签页的标题
字符串 url
是
需要显示的页面的url 路径
字符串
当Tab 页面显示的是报表时，使用report 标签；当Tab 页面显示的是普通网页时，使用reportItem 标签，如： <bios:reportSet>
<bios:report name =
"表1" rpt="<%=rpt1%>" rptwidth="100%" rptheight="100%" /> <bios:report name="表2" rpt="<%=rpt2%>" fitwidth="true" rptwidth="100%" rptheight="100%" toolbardisplay="top"/>
<bios:reportItem name ="表4" url="welcome.htm" /> </bios:reportSet>
二、 Java自定义扩展
2.1 自定义数据集
2.1.1用途
通常报表的数据都来自数据库，但也有特殊情况，例如通过中间件连接数据库，而非直接连接等，需要用户自定义数据集。

皕杰设计器中自定义数据集的应用：
首先添加用户自定义的数据集，选择【工具栏】->【窗口】->【首选项】->【报表运行时配置】，在【自定义数据集配置】中添加数据集，添加方式有两种，一是将编译好的.class 文件打成jar 包， 点击【添加JAR 】，将jar 包导入；二是点击【添加文件夹】，将包含.class 文件的文件夹添加到数据集。

添加好数据集，就可以在设计器的摘要视图中新建数据集，其中，【数据源】选项不填，【类型】选项选择“自定义类型”，在【编辑查询SQL 】对话框中添加自定义数据集的类名，单
击确定即可。

web中自定义数据集的应用：
web中添加自定义数据集也有两种方式：一是将编译好的.class文件打成jar包，放到
WEB-INF\lib文件夹里；二是将.class文件放到WEB-INF\classes目录下。

2.1.2类介绍
类。

杰报表自定义数据集返回的结果集类型为数用户自定义数据集需继承CustomDataSet皕
组。

2.1.3构造方法
CustomDataSet(ng.Object[] params)
说明：子类需要继承此构造方法
参数：params Object数组，数据集参数列表
CustomDataSet(UserContext userContext, ng.Object[] params)
说明：子类需要继承此构造方法（已过时）
参数：userContext UserContext类型，用来获得或设置请求中的参数。

params Object数组，参数数组
2.1.4 方法说明
getMetaData
语法：public abstract ng.String[] getMetaData()
用途：获取数据元信息(列名数组，长度要与数据列数一致)。

返回值：数据集列名数组
getParams
语法：protected final ng.Object[] getParams()
用途：获取数据集参数数组
返回值：Object数组
getRowCount
语法：public abstract int getRowCount()
用途：获取数据总行数
返回值：数据总行数
getRowData
语法：public abstract ng.Object[] getRowData(int rowIndex)
用途：获取指定行的数据
参数：rowIndex 指定数据行索引
返回值：指定数据行对象
getUserContext
语法：protected final UserContext getUserContext()
用途：获取用户上下文对象
返回值：上下文对象
init
语法：protected void init()
用途：执行自定义初始化操作，缺省不进行任何处理
参数：无
返回值：无
2.1.5. 实用示例
参考MyCustomDataSet.java
2.2自定义事件处理类
2.2.1用途
用户在打印或填报数据过程中，有时候需要在任务前后执行一系列操作，例如：某张报表只允许打印一次或者数据提交前要进行核对等。

用户将编译好的.class文件放到WEB-INF\classes目录下，然后在config.xml文件的<eventHandler>节点中添加用户自定义事件处理类的类名即可
2.2.2接口介绍
用户在自定义事件处理时，需要实现bios.report.engine.api.IEventHandler接口。

2.2.3方法说明
onPrintBegin
用途：打印前事件触发
语法：public String onPrintBegin(ng.String rpt,
String params, String vars, javax.servlet.http.HttpServletRequest request)
参数：rpt - 报表名称
params - 参数字符串（param1=value1；param2=value2；……），无参数时为null vars - 变量字符串（var1=value1；var2=value2；……），无变量时为null
request - HttpServlet请求
返回值：验证通过时返回null，执行打印；否则返回错误信息，不执行打印
onPrintEnd
用途：打印后事件触发
语法：public String onPrintEnd(ng.String rpt,
String params, String vars, javax.servlet.http.HttpServletRequest request)
参数：rpt - 报表名称
params - 参数字符串（param1=value1；param2=value2；……），无参数时为null
vars - 变量字符串（var1=value1；var2=value2；……），无变量时为null
request - HttpServlet请求
返回值：有错误信息,返回错误信息,否则返回null
onUpdateData
用途：填报操作进行数据更新前的事件触发
语法：public boolean onUpdateData(ng.String rpt, ng.String params,
ng.String vars,ng.String dataSource,ng.String tableName, java.util.List data)
参数：rpt - 报表名称
params - 参数字符串(格式：param1=xx;param2=yy;...)，无参数时为null
vars - 变量字符串(格式：var1=xx;var2=yy;...)，无变量时为null
dataSource - 数据源名称
tableName - 要更新的数据库表
data - 客户端提交的数据列表(java.util.List类型，列表条目为bios.report.engine.api.FillinDataRow
类型)
返回值：返回true，进行数据更新；否则不进行数据更新
2.2.4实用示例
参见DemoEventHandler.java
2.3自定义用户工厂
2.3.1用途
提供对用户自定义功能的调用。

皕杰API为用户提供了用户工厂接口，通过这个接口，用户可以实现自定义html工具条输出、读取完成扩展计算后的报表对象（即序列化brf皕
文件）和自定义报表来源（在杰报表中，服务器默认的是从report_home指定的路径来读取报表模板）。

2.3.2接口介绍
用户自定义用户工厂需要实现bios.report.engine.api.IUserFactory接口
2.3.3方法说明
supportsBuildToolbarHtml
用途：是否支持自定义html工具条输出
语法：public boolean supportsBuildToolbarHtml()
返回值：支持自定义html工具条输出，返回true；否则返回false。

buildToolbarHtml
用途：自定义html工具条输出，supportsBuildToolbarHtml()方法返回true时，该方法才生效。

语法：public ng.String buildToolbarHtml( javax.servlet.http.HttpServletRequest request
ng.String rptName,
ng.String params,
ng.String vars,
int pageIndex,
int pageCount,
java.util.Map otherParams)
参数：request - HttpServlet请求
rptName - 报表名称，导出&翻页时使用
pageCount - 总页数，翻页&分页导出时使用
pageIndex - 当前页序号，翻页&分页导出时使用
params - 参数字符串，导出&翻页时使用
vars - 变量字符串，导出&翻页时使用
otherParams - 其它请求参数，翻页时使用
返回值：HTML字符串
supportsLoadReportTemplate
用途：是否支持自定义读取报表模板
语法：public boolean supportsLoadReportTemplate()
返回值：支持自定义读取报表模板，返回true；否则返回false。

loadReportTemplate
用途：读取自定义来源报表模板，supportsLoadReportTemplate()方法返回true时，该方法才生效
语法：public java.io.InputStream loadReportTemplate(ng.String templateName)
参数：templateName - 模板名称，可以是文件名或用户自定义标识等
返回值：模板输入流
loadBrf
用途：读取报表序列化brf文件(完成扩展计算后的报表对象)
语法：public java.io.InputStream loadBrf(ng.String brfId)
参数：brfId - 需要读取的brf文件名称或用户自定义标识等
返回值：brt文件的输入流
supportsGetDataSource
用途：是否支持自定义获取报表所需的数据源，是getDbConnection(String dsName)和getXmlDataSource(String dsName, String xmlDefName)这两个方法的开关
语法：public boolean supportsGetDataSource()
返回值：支持自定义获取报表所需的数据源，返回true；否则返回false。

getDbConnection
用途：自定义获取报表所需的数据库连接
语法：public java.util.Map getDbConnection(ng.String dsName)
参数：dsName - 数据源名称，与设计器中的名称一致，默认数据源的名称为"default"
返回值：包含数据库连接及相关信息的Map，结构如下： {conn=数据库连接,charset=数据库编码,dbtype=数据库类型} 其中，conn: java.sql.Connection类型，不能为空；charset:
字符串类型，缺省使用GBK字符集；dbtype:字符串类型，可选值
为"ORACLE" "DB2" "SQLSERVER" "MYSQL" "SYBASE" "INFORMIX" "HSQL"
getXmlDataSource
用途：根据数据源名称，和xml定义名称，获取xml数据源信息
语法：public ng.String[] getXmlDataSource(ng.String
dsName,ng.String xmlDefName)
参数：dsName - 数据源名称，与设计器中一致
xmlDefName - 所选的xml定义名称，与设计器中一致
返回值：String[],xml数据源信息字符串数组。

其中，第一个字符串为xml文件路径或url，第二个字符串为xml编码。

supportsLoadBizModel
用途：是否支持自定义读取语义文件
语法：public boolean supportsLoadBizModel()
参数：无
返回值：自定义读取语义文件，返回true；否则返回false。

loadBizModel
用途：根据指定名称获取语义文件的输入流 supportsLoadBizModel()方法返回true时，该方法才生效
语法：public java.io.InputStream loadBizModel(ng.String bizModelName)
参数：bizModelName - 报表模板中引用的语义定义名称
返回值：语义文件输入流
三、API编程
皕杰报表API编程主要使用
3.1读入报表模板
采用文件和文件流两种方式读取报表模板，创建类BiosReportTemplate的实例。

方式一：文件方式
String fileName ="报表模板路径"; //报表模板文件的绝对路径BiosReportTemplate template = new BiosReportTemplate(fileName);
方式二：文件流方式
FileInputStream in = new FileInputStream("报表路径");//获取一个报表模板文件的输入流BiosReportTemplate template = new BiosReportTemplate(in);
3.2 计算报表
报表的计算过程：
/* 用文件方式或文件流方式读取报表模板 */
BiosReportTemplate template = new BiosReportTemplate(fileName);
/* 参数设置 */
Map params = new HashMap();
String[ ] paramNames = template.getParamNames();//获取报表模板中参数名称列表
for (int i = 0; i < paramNames.length; i++) {
params.put(paramNames[ i ], "1"); //设置参数值
}
/* 变量设置 */
Map vars = new HashMap();
String[ ] varNames = template.getVarNames();//获取报表模板中变量名称列表
for (int i = 0; i < varNames.length; i++) {
//设置变量值
"");
i
vars.put(varNames[
],
}
/* 创建报表运算对象 */
BiosReportManager manager = new BiosReportManager(template, params, vars);
/* 设置数据库连接 */ 注1
manager.setConnection(getConnection());
/* 执行运算 */
manager.calc();
注1用户根据具体需要，在计算之前自行设置数据库连接，不设置时使用应用服务器数据源3.3输出报表
使用杰API输出报表，通常是使用BiosReportManager类对象的相应方法皕
♦获取运算结果报表对象，该对象用于用于report标签中的rptobj参数
ng.Object obj = manager.getRptObject()
♦整页输出HTML
toHtml(javax.servlet.http.HttpServletRequest request)方法：
String html = manager.toHtml(null);
♦指定页输出HTML
toHtml(int pageIndex, javax.servlet.http.HttpServletRequest request)方法：
String html = manager.toHtml(1,null); //输出分页后第一页
整页输出Text
toTxt ()方法：
String txt = manager.toTxt();
指定页输出Text
toTxt (int pageIndex)方法：
String txt = manager.toTxt(2); //输出第二页
整页输出Excel
toExcel(java.io.OutputStream out, java.util.Map processData)方法：
FileOutputStream out = new FileOutputStream("文件名称"); //定义文件输出流
manager.toExcel(out,null);
分页输出Excel
toPagedExcel(java.io.OutputStream out, java.util.Map processData)方法：FileOutputStream out =new FileOutputStream("文件名称");
manager.toPagedExcel(out,null);
输出Pdf
toPdf(java.io.OutputStream out)方法：
FileOutputStream out =new FileOutputStream("文件名称");
manager.toPdf(out);
输出brf
toBrf(java.io.OutputStream out)方法：
FileOutputStream out =new FileOutputStream("文件名称");
manager.toBrf(out);
3.4分页设置
报表分页设置需要用到类PagingModel的对象。

pm.setPageSize(10); //每页显示数据行数（10行）
pm.setPagingType(PagingModel.PAGING_ROW); //设置分页类型(按行分页)
3.5编辑报表模板
读取一个已经存在的报表模板，构建一个BiosReportTemplate对象template，通过template设置模板的常规属性。

设置单元格属性值的方法：
setCellPropValue(int rowIndex,int colIndex,int propId,
ng.String value)
例如：
template.setCellPropValue(2,1,CellPropConst.PROP_FONT_COLOR,
"255,255,255"); //设置A2单元格字体颜色
接口中定义了一系列静态的单元格属性常量，详细内容参见杰皕杰API在CellPropConst皕API文档。

设置单元格数据值的方法：
setCellValue(int rowIndex, int colIndex, ng.String value)
例如：
template.setCellValue(2,1,”=ds1.Group(DEPT,false)”);
获取单元格属性值的方法：
getCellPropValue(int rowIndex,int colIndex,int propId)
例如：
template.getCellPropValue(3,3,CellPropConst.PROP_FONT_NAME));
//获取C3单元格字
体名称
获取单元格数据值的方法：
getCellValue(int rowIndex, int colIndex)
例如：
template. getCellValue(2, 1); //获取单元格的数据值
注:示例代码参见Sample.java。