首页 > 代码库 > Birt参数配置详解
Birt参数配置详解
一.web.xml
1 <!-- 2 Default locale setting. 3 设置默认的Locale信息。 4 --> 5 <context-param> 6 <param-name>BIRT_VIEWER_LOCALE</param-name> 7 <param-value>en-US</param-value> 8 </context-param> 9 10 11 12 <!-- 13 Default timezone setting. 14 Examples: "Europe/Paris", "GMT+1". 15 Defaults to the container‘s timezone. 时区 16 --> 17 <context-param> 18 <param-name>BIRT_VIEWER_TIMEZONE</param-name> 19 <param-value></param-value> 20 </context-param> 21 22 <!-- 23 Report resources directory for preview. Defaults to ${birt home} 24 设置BIRT Viewer的工作目录。 25 用户可以把report design或是report document文件存放在这个目录下， 26 这样就可以在URL上采用相对路径去预览这些报表文件了。默认是当前根目录。 27 --> 28 <context-param> 29 <param-name>BIRT_VIEWER_WORKING_FOLDER</param-name> 30 <param-value></param-value> 31 </context-param> 32 33 <!-- 34 Temporary document files directory. Defaults to ${birt home}/documents 35 设置生成的document文件的存放路径。默认是documents目录。 36 --> 37 <context-param> 38 <param-name>BIRT_VIEWER_DOCUMENT_FOLDER</param-name> 39 <param-value></param-value> 40 </context-param> 41 42 43 44 <!-- 45 Flag whether the report resources can only be accessed under the 46 working folder. Defaults to true 47 简单的报表访问限制控制实现，如果设为true,哪就只能预览存放在工作目录下的报表文件。默认值是false。 48 --> 49 <context-param> 50 <param-name>WORKING_FOLDER_ACCESS_ONLY</param-name> 51 <param-value>true</param-value> 52 </context-param> 53 54 55 56 <!-- 57 Temporary image/chart directory. Defaults to ${birt home}/report/images 58 设置生成的临时图片的存放路径。默认是report/images目录。 59 --> 60 <context-param> 61 <param-name>BIRT_VIEWER_IMAGE_DIR</param-name> 62 <param-value></param-value> 63 </context-param> 64 65 66 67 <!-- 68 Engine log directory. Defaults to ${birt home}/logs 69 设置生成的日志文件存放路径。默认是logs目录。 70 --> 71 <context-param> 72 <param-name>BIRT_VIEWER_LOG_DIR</param-name> 73 <param-value></param-value> 74 </context-param> 75 76 77 78 <!-- 79 Report engine log level 80 设置日志的level，可选的值有：ALL|SEVERE|WARNING|INFO|CONFIG|FINE|FINER|FINEST|OFF。级别由高到低。 81 --> 82 <context-param> 83 <param-name>BIRT_VIEWER_LOG_LEVEL</param-name> 84 <param-value>WARNING</param-value> 85 </context-param> 86 87 88 89 <!-- 90 Directory where to store all the birt report script libraries (JARs). 91 Defaults to ${birt home}/scriptlib 92 设置用户script lib文件的存放目录( 在报表中用到的Java Event Handler Class )。 93 默认值是scriptlib。 94 --> 95 <context-param> 96 <param-name>BIRT_VIEWER_SCRIPTLIB_DIR</param-name> 97 <param-value></param-value> 98 </context-param> 99 100 <!--101 Resource location directory. Defaults to ${birt home}102 设置用户资源存放路径，这些资源包括library文件，image文件等。默认是当前根目录103 -->104 <context-param>105 <param-name>BIRT_RESOURCE_PATH</param-name>106 <param-value></param-value>107 </context-param>108 109 110 111 <!--112 Preview report rows limit. An empty value means no limit.113 设置获取dataset的最大记录数。114 主要应用于设计报表的时候，预览报表如果记录数太多，会花费很多的时间，也可能会引起out of memory问题。115 默认是不限制。116 -->117 <context-param>118 <param-name>BIRT_VIEWER_MAX_ROWS</param-name>119 <param-value></param-value>120 </context-param>121 122 123 124 <!--125 Max cube fetch levels limit for report preview (Only used when126 previewing a report design file using the preview pattern)127 设置CUBE查询的最大级数。和前面的参数作用类似。默认是不限制。128 (仅在preview模式下查看报表时有效)129 -->130 <context-param>131 <param-name>BIRT_VIEWER_MAX_CUBE_ROWLEVELS</param-name>132 <param-value></param-value>133 </context-param>134 <context-param>135 <param-name>BIRT_VIEWER_MAX_CUBE_COLUMNLEVELS</param-name>136 <param-value></param-value>137 </context-param>138 139 140 141 <!--142 Memory size in MB for creating a cube.143 设置在生成CUBE时，可以写在memory中的最大值，单位是MB144 可以提高效率，写在内存会比直接写在硬盘快很多。但同时也要注意内存占用的问题。145 -->146 <context-param>147 <param-name>BIRT_VIEWER_CUBE_MEMORY_SIZE</param-name>148 <param-value></param-value>149 </context-param>150 151 152 153 <!--154 Defines the BIRT viewer configuration file155 定义properties文件的路径，不可以修改。156 -->157 <context-param>158 <param-name>BIRT_VIEWER_CONFIG_FILE</param-name>159 <param-value>WEB-INF/viewer.properties</param-value>160 </context-param>161 162 163 164 <!--165 Flag whether to allow server-side printing. Possible values are "ON"166 and "OFF". Defaults to "ON".167 在frameset工具条上，提供有后台服务器打印的功能，该参数可以设置是打开还是关闭后台打印的功能。168 默认是打开。可选值为: ON 和 OFF。169 -->170 <context-param>171 <param-name>BIRT_VIEWER_PRINT_SERVERSIDE</param-name>172 <param-value>ON</param-value>173 </context-param>174 175 176 177 <!--178 Flag whether to force browser-optimized HTML output. Defaults to true179 这个参数是会传递给Engine的，主要用于一些CSS的兼容性方面的问题。默认值是true。180 -->181 <context-param>182 <param-name>HTML_ENABLE_AGENTSTYLE_ENGINE</param-name>183 <param-value>true</param-value>184 </context-param>185 186 187 188 <!--189 Filename generator class/factory to use for the exported reports.190 -->191 <context-param>192 <param-name>BIRT_FILENAME_GENERATOR_CLASS</param-name>193 <param-value>org.eclipse.birt.report.utility.filename.DefaultFilenameGenerator</param-value>194 </context-param>
2> Servlet模式说明
1 <!-- Viewer Servlet, Supports SOAP --> 2 <servlet> 3 <servlet-name>ViewerServlet</servlet-name> 4 <servlet-class>org.eclipse.birt.report.servlet.ViewerServlet</servlet-class> 5 </servlet> 6 7 <!-- Engine Servlet --> 8 <servlet> 9 <servlet-name>EngineServlet</servlet-name> 10 <servlet-class>org.eclipse.birt.report.servlet.BirtEngineServlet</servlet-class> 11 </servlet> 12 13 14 15 <!-- 16 17 frameset ---- 采用Ajax框架，可以显示工具条，导航条和TOC面板，实现复杂的操作， 18 19 如分页处理，导出数据，导出报表，打印等。 20 21 该模式下会自动生成report document文件(预览report design文件)到特定的目录 22 23 (用户可以用参数指定，也可以定义在web.xml里)。采用Ajax，速度较慢。 24 25 --> 26 27 <servlet-mapping> 28 <servlet-name>ViewerServlet</servlet-name> 29 <url-pattern>/frameset</url-pattern> 30 </servlet-mapping> 31 32 33 34 <!-- 35 36 run ---- 也采用Ajax框架，但不实现frameset的复杂功能， 37 38 不会生成临时的report document文件(预览report design文件)，也不支持分页， 39 40 这个主要是应用在BIRT Designer里的preview tab里， 41 42 可以支持cancel操作，其它不怎么常用。采用Ajax，速度较慢。 43 44 --> 45 <servlet-mapping> 46 <servlet-name>ViewerServlet</servlet-name> 47 <url-pattern>/run</url-pattern> 48 </servlet-mapping> 49 50 51 <!-- 52 53 preview --- 没有用到Ajax框架，直接调用底层Engine API对报表进行render， 54 55 把生成的报表内容直接输出到浏览器。 56 57 这种模式和run模式调用的是相同的Engine API， 58 59 唯一区别在于run采用Ajax获取报表内容，而preview直接输出到浏览器。 60 61 如果要支持分页，用户需要在URL上定义__page和__pagerange参数。 62 63 需要特别说明的是，在这几种预览模式中，preview的速度是最快的。 64 65 --> 66 <servlet-mapping> 67 <servlet-name>EngineServlet</servlet-name> 68 <url-pattern>/preview</url-pattern> 69 </servlet-mapping> 70 71 72 73 <!-- 74 75 download --- 用于导出报表数据， 76 77 当你使用frameset工具条里的导出数据功能时，会用到这个模式。 78 79 --> 80 81 <servlet-mapping> 82 <servlet-name>EngineServlet</servlet-name> 83 <url-pattern>/download</url-pattern> 84 </servlet-mapping> 85 86 87 88 <!-- 89 90 parameter --- 该模式主要用于生成一个参数对话框，一般用户不常用， 91 92 用户可以直接通过提供的JSP Tag--parameterPage去实现参数对话框，不需要直接调用。 93 94 --> 95 96 <servlet-mapping> 97 <servlet-name>EngineServlet</servlet-name> 98 <url-pattern>/parameter</url-pattern> 99 </servlet-mapping>100 101 102 103 <!--104 105 document --- 该模式主要是为了从report design文件生成report document文件。106 107 用户可以在URL上提定document文件生成存放的路径(存放在server端)，如果未指定，108 109 会直接生成rptdocument发送到客户端浏览器，用户可以下载到客户端。110 111 -->112 113 <servlet-mapping>114 <servlet-name>EngineServlet</servlet-name>115 <url-pattern>/document</url-pattern>116 </servlet-mapping>117 118 119 120 <!--121 122 output --- 该模式类似于frameset，会自动生成report document文件(预览report design文件)，123 124 区别在于output不采用Ajax，而是将生成的报表内容直接输出到浏览器。125 126 -->127 128 <servlet-mapping>129 <servlet-name>EngineServlet</servlet-name>130 <url-pattern>/output</url-pattern>131 </servlet-mapping>132 133 134 <!--135 136 extract--- 。137 138 -->139 <servlet-mapping>140 <servlet-name>EngineServlet</servlet-name>141 <url-pattern>/extract</url-pattern>142 </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文件。
===============================================================================
5. 其它参数设置
在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 );
}
Birt参数配置详解